Build an insurance onboarding flow

git clone https://github.com/cardog-ai/example-insurance-onboarding.git

# Copy to .env.local. With these values the app runs on recorded fixtures
# and a development auth secret.

# Your Cardog API key (https://cardog.app/account/api). Server-side only; it
# never reaches the browser. Leave empty for fixture mode.
CARDOG_API_KEY=

# Signs sessions. This value is a DEVELOPMENT PLACEHOLDER so a fresh clone
# builds and runs; the app warns on every production start while it is set.
# Replace it before deploying: openssl rand -base64 32
BETTER_AUTH_SECRET=ottervale-dev-only-secret-replace-before-deploying

# Where the app is served. Needed when it is not http://localhost:3020.
BETTER_AUTH_URL=http://localhost:3020

# SQLite file. Created on first run.
DATABASE_PATH=data/ottervale.db

# Seeded review logins (created by `pnpm db:setup` on an empty database):
#   applicant    applicant@ottervale.example   / ottervale-applicant
#   underwriter  underwriter@ottervale.example / ottervale-underwriter

pnpm create next-app@latest ottervale --ts --app --tailwind --src-dir
cd ottervale
pnpm add @cardog/api better-auth better-sqlite3 drizzle-orm server-only
pnpm add -D drizzle-kit tsx @types/better-sqlite3

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // better-sqlite3 is a native module: load it from node_modules at runtime.
  serverExternalPackages: ["better-sqlite3"],
  // This app is its own root, even when it sits inside another repository.
  outputFileTracingRoot: process.cwd(),
};

export default nextConfig;

function authSecret(): string {
  const set = process.env.BETTER_AUTH_SECRET?.trim();
  const production = process.env.NODE_ENV === "production" && process.env.NEXT_PHASE !== "phase-production-build";
  if (set) {
    if (production && set === DEV_SECRET) {
      console.warn("[ottervale] BETTER_AUTH_SECRET is the development placeholder. Replace it before deploying.");
    }
    return set;
  }
  if (!production) return DEV_SECRET;
  throw new Error("[ottervale] BETTER_AUTH_SECRET is not set. Generate one with `openssl rand -base64 32`.");
}

export const auth = betterAuth({
  appName: "Ottervale",
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3020",
  secret: authSecret(),
  database: drizzleAdapter(db, {
    provider: "sqlite",
    schema: { user: schema.user, session: schema.session, account: schema.account, verification: schema.verification },
  }),
  emailAndPassword: { enabled: true, minPasswordLength: 8, autoSignIn: true },
  user: {
    additionalFields: {
      role: { type: "string", required: false, defaultValue: "applicant", input: false },
    },
  },
  plugins: [nextCookies()],
});

import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "@/lib/auth";

export const { GET, POST } = toNextJsHandler(auth);

const apiKey = process.env.CARDOG_API_KEY?.trim();

/** The one Cardog client. Server-side only. */
export const cardog: CardogClient | null = apiKey
  ? new CardogClient({ apiKey, appId: "ottervale-onboarding", baseUrl: process.env.CARDOG_BASE_URL || undefined })
  : null;

export const dataMode: "live" | "fixture" = cardog ? "live" : "fixture";
export { FIXTURE_VINS };

// The v2 response types, read off the client's own method signatures.
type V2 = CardogClient["v2"];
export type VinIdentity = Awaited<ReturnType<V2["vin"]["getByVin"]>>;
export type BuildSpecSheet = Awaited<ReturnType<V2["specs"]["sheetByBuild"]>>;
export type SafetyRatings = Awaited<ReturnType<V2["safety"]["ratings"]>>;
export type MarketQuote = Awaited<ReturnType<V2["quotes"]["getByRef"]>>;
export type ModelYearRecalls = Awaited<ReturnType<V2["recalls"]["entity"]>>;
export type VinImageRead = Awaited<ReturnType<CardogClient["vin"]["image"]>>;

export interface Result<T> {
  data: T | null;
  call: CallRecord;
  error: string | null;
}

export function checkVin(vin: string): VinCheck {
  if (!vin) return { state: "empty" };
  const bad = vin.match(/[IOQ]/);
  if (bad) {
    const hint = bad[0] === "I" ? "1" : "0";
    return { state: "invalid", message: `VINs never use the letter ${bad[0]}. It's probably the number ${hint}.` };
  }
  if (/[^A-HJ-NPR-Z0-9]/.test(vin)) return { state: "invalid", message: "Only letters and numbers." };
  if (vin.length < 17) return { state: "typing", remaining: 17 - vin.length };
  const expected = expectedCheckDigit(vin);
  if (expected && expected !== vin[8]) {
    return {
      state: "check-mismatch",
      message: `The 9th character should be ${expected} for this VIN. Check for a mistyped character.`,
    };
  }
  return { state: "ok", message: "17 characters, check digit matches." };
}

export async function readVinFromImage(base64: string, step: string): Promise<Result<VinImageRead>> {
  return run<VinImageRead>({
    step,
    vin: FIXTURE_VINS[0].vin,
    key: "image",
    method: "cardog.vin.image",
    args: [`<${Math.round((base64.length * 3) / 4 / 1024)} KB image, base64>`],
    http: "POST /vin/image",
    returns: "The VIN read from the photo",
    live: (c) => c.vin.image(base64),
  });
}

import { NextResponse } from "next/server";
import { getViewer } from "@/lib/session";
import { readVinFromImage } from "@/lib/cardog";
import { normalizeVin } from "@/lib/vin";

const MAX_BYTES = 8 * 1024 * 1024;

/** POST multipart { photo } → the VIN read from it. */
export async function POST(req: Request) {
  const me = await getViewer();
  if (!me) return NextResponse.json({ ok: false, error: "Sign in first." }, { status: 401 });
  const form = await req.formData().catch(() => null);
  const file = form?.get("photo");
  if (!(file instanceof File)) return NextResponse.json({ ok: false, error: "No photo received." }, { status: 400 });
  if (file.size > MAX_BYTES)
    return NextResponse.json({ ok: false, error: "That photo is over 8 MB." }, { status: 413 });

  const base64 = Buffer.from(await file.arrayBuffer()).toString("base64");
  const r = await readVinFromImage(base64, "Add your vehicle");
  const vin = r.data?.success ? normalizeVin(r.data.result) : null;
  return NextResponse.json({
    ok: Boolean(vin && vin.length === 17),
    vin,
    error:
      vin && vin.length === 17
        ? null
        : r.error ?? "We couldn't find a VIN in that photo. Try again closer, or type it.",
    calls: [r.call],
  });
}

export function decodeVin(vin: string, step: string) {
  return run<VinIdentity>({
    step,
    vin,
    key: "decode",
    method: "cardog.v2.vin.getByVin",
    args: [vin],
    http: `GET /v2/vin/${vin}`,
    returns: "Identity card: year, make, model, trim, refs, nano, decoded attributes",
    live: (c) => c.v2.vin.getByVin(vin),
  });
}

import { NextResponse } from "next/server";
import { getViewer } from "@/lib/session";
import { identify } from "@/lib/vehicle-read";
import { normalizeVin } from "@/lib/vin";

/** POST { vin } → decode + build spec sheet. Signed-in applicants only. */
export async function POST(req: Request) {
  const me = await getViewer();
  if (!me) return NextResponse.json({ ok: false, error: "Sign in first." }, { status: 401 });
  const { vin } = (await req.json().catch(() => ({}))) as { vin?: string };
  const v = normalizeVin(vin ?? "");
  if (v.length !== 17) return NextResponse.json({ ok: false, error: "A VIN has 17 characters." }, { status: 400 });
  return NextResponse.json(await identify(me.id, v));
}

export async function identify(userId: string, vin: string, step = "Add your vehicle"): Promise<ReadResult> {
  const d = draftFor(userId, vin);
  d.raw = { decode: null, specs: null, safety: null, quote: null };
  d.calls = [];

  const decoded = await decodeVin(vin, step);
  d.calls.push(decoded.call);
  if (!decoded.data) return { ok: false, error: decoded.error, facts: null, calls: [decoded.call] };
  d.raw.decode = decoded.data;

  const calls = [decoded.call];
  if (decoded.data.nano) {
    const specs = await readBuildSpecs(decoded.data.nano, vin, step);
    d.calls.push(specs.call);
    calls.push(specs.call);
    d.raw.specs = specs.data;
  }
  d.at = Date.now();
  return { ok: true, error: null, facts: facts(vin, d.raw), calls };
}

export async function details(userId: string, vin: string, step = "Prefilled details"): Promise<ReadResult> {
  const d = draftFor(userId, vin);
  if (!d.raw.decode) {
    const r = await identify(userId, vin, step);
    if (!r.ok) return r;
  }
  const modelYear = (d.raw.decode as { refs?: { modelYear?: string | null } }).refs?.modelYear;
  if (!modelYear) return { ok: true, error: null, facts: facts(vin, d.raw), calls: [] };

  const [safety, quote] = await Promise.all([
    readSafetyRatings(modelYear, vin, step),
    readMarketQuote(modelYear, vin, step),
  ]);
  d.raw.safety = safety.data;
  d.raw.quote = quote.data;
  d.calls.push(safety.call, quote.call);
  d.at = Date.now();
  return { ok: true, error: null, facts: facts(vin, d.raw), calls: [safety.call, quote.call] };
}

export function readMarketQuote(modelYearRef: string, vin: string, step: string) {
  return run<MarketQuote>({
    step,
    vin,
    key: "quote",
    method: "cardog.v2.quotes.getByRef",
    args: [modelYearRef],
    http: `GET /v2/quotes/${modelYearRef}`,
    returns: "Asking-price quartiles and listing counts for the model year",
    live: (c) => c.v2.quotes.getByRef(modelYearRef),
  });
}

export async function addVehicle(input: {
  vin: string;
  answers: Answers;
  manual?: { year: number | null; make: string; model: string; trim: string };
}): Promise<ActionResult> {
  const me = await requireViewer();
  const p = await policyFor(me.id);
  if (!editable(p.status))
    return { ok: false, error: "This policy is with underwriting. Vehicles can be added once it comes back." };

  const vin = normalizeVin(input.vin);
  if (vin.length !== 17) return { ok: false, error: "A VIN has 17 characters." };
  if (vehiclesOn(p.id).some((v) => v.vin === vin))
    return { ok: false, error: "This vehicle is already on your policy." };

  let facts;
  let calls: CallRecord[] = [];
  if (input.manual) {
    facts = manualVehicleFile(vin, input.manual);
  } else {
    // Reuse what the applicant saw; read again only if it has expired.
    const held = heldDraft(me.id, vin);
    if (held) {
      facts = held.facts;
      calls = held.calls;
    } else {
      const r = await readAll(me.id, vin, "Add to policy");
      if (!r.ok || !r.facts) return { ok: false, error: r.error ?? "The vehicle could not be read." };
      facts = r.facts;
      calls = r.allCalls;
    }
  }

  const now = new Date();
  db.insert(vehicle)
    .values({
      id: crypto.randomUUID(),
      policyId: p.id,
      vin,
      source: input.manual ? "manual" : "cardog",
      year: facts.year,
      make: facts.make,
      model: facts.model,
      trim: input.answers.trim ?? facts.trim,
      facts,
      answers: input.answers,
      calls,
      refreshedAt: now,
    })
    .run();
  db.update(policy).set({ updatedAt: now }).where(eq(policy.id, p.id)).run();
  dropDraft(me.id, vin);
  revalidatePath("/policy");
  return { ok: true };
}

export function readModelYearRecalls(modelYearRef: string, vin: string, step: string) {
  return run<ModelYearRecalls>({
    step,
    vin,
    key: "recalls",
    method: "cardog.v2.recalls.entity",
    args: [modelYearRef, { limit: 20 }],
    http: `GET /v2/recalls/entity/${modelYearRef}?limit=20`,
    returns: "Recall campaigns issued for the model year (Transport Canada and NHTSA)",
    live: (c) => c.v2.recalls.entity(modelYearRef, { limit: 20 }),
  });
}

export function queue() {
  const rows = db
    .select({ policy, applicant: { id: user.id, name: user.name, email: user.email } })
    .from(policy)
    .innerJoin(user, eq(user.id, policy.userId))
    .where(ne(policy.status, "draft"))
    .orderBy(desc(policy.submittedAt))
    .all();
  const ids = rows.map((r) => r.policy.id);
  const vs = ids.length ? db.select().from(vehicle).where(inArray(vehicle.policyId, ids)).all() : [];
  return rows.map((r) => ({ ...r, vehicles: vs.filter((v) => v.policyId === r.policy.id) }));
}

export async function decidePolicy(
  policyId: string,
  decision: "approved" | "referred",
  note: string
): Promise<ActionResult> {
  const uw = await requireUnderwriter();
  const p = db.select().from(policy).where(eq(policy.id, policyId)).get();
  if (!p || p.status !== "submitted") return { ok: false, error: "This application is not waiting for a decision." };
  db.update(policy)
    .set({ status: decision, decidedAt: new Date(), decidedBy: uw.name, decisionNote: note.trim() || null })
    .where(eq(policy.id, policyId))
    .run();
  revalidatePath("/underwriting");
  revalidatePath(`/underwriting/${policyId}`);
  return { ok: true };
}

# Ottervale onboarding: one container, SQLite on a mounted volume.
#   docker build -t ottervale .
#   docker run -p 3020:3020 -v ottervale-data:/app/data \
#     -e CARDOG_API_KEY=... -e BETTER_AUTH_SECRET=... -e BETTER_AUTH_URL=https://your.host ottervale
FROM node:22-bookworm-slim AS build
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:22-bookworm-slim
WORKDIR /app
ENV NODE_ENV=production
RUN corepack enable
COPY --from=build /app ./
VOLUME /app/data
EXPOSE 3020
CMD ["pnpm", "start"]

docker build -t ottervale .
docker run -p 3020:3020 -v ottervale-data:/app/data \
  -e CARDOG_API_KEY=your_cardog_api_key \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e BETTER_AUTH_URL=https://onboarding.example.com \
  ottervale