@voyant-travel/commerce 0.2.2 → 0.3.0

package/dist/checkout/options.js

@@ -0,0 +1,21 @@
+/**
+ * Deployment-supplied options for the catalog-checkout cluster.
+ *
+ * The checkout business logic (materialization, tax, start-service,
+ * acceptance signature) lives in `@voyant-travel/commerce`. The two
+ * genuinely deployment-specific dependencies are injected here as
+ * structural functions so the package never statically imports the
+ * deployment, and — crucially — never imports `@voyant-travel/inventory`
+ * (which already depends on `@voyant-travel/commerce`; a static import
+ * would cycle).
+ *
+ *   - `resolveBookingTaxSettings` — reads the operator's tax-mode /
+ *     tax-policy-profile row. The deployment owns the settings table.
+ *   - `getOwnedProductName` — resolves an owned product's title for the
+ *     line-item fallback. The package can't import inventory's
+ *     `productsService.getProductById` without cycling, so the
+ *     deployment hands it in.
+ *   - `resolveBankTransferInstructions` — reads the operator profile +
+ *     payment-instruction rows for the bank-transfer checkout path.
+ */
+export {};

package/dist/checkout/routes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Storefront checkout route module, owned by `@voyant-travel/commerce`.
+ *
+ * POST /checkout/start parses the BookingJourney checkout request and
+ * delegates to the checkout-start service. A deployment composes this and
+ * supplies the `CheckoutStartOptions` (injected tax-settings + owned-product
+ * name + bank-transfer instruction readers) the service needs.
+ *
+ * Mount the returned Hono at `/v1/public/catalog` (relative paths).
+ */
+import type { Context } from "hono";
+import { Hono } from "hono";
+import type { CheckoutStartOptions } from "./options.js";
+/**
+ * Build the storefront checkout routes. `options` may be a value or a
+ * per-request factory — the deployment passes a factory when an injected
+ * option needs to capture the request `Context` (e.g. resolving a payment
+ * provider runtime from the per-request container).
+ */
+export declare function createCatalogCheckoutRoutes(options: CheckoutStartOptions | ((c: Context) => CheckoutStartOptions)): Hono;
+//# sourceMappingURL=routes.d.ts.map

package/dist/checkout/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/checkout/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AASxD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,oBAAoB,CAAC,GACrE,IAAI,CAMN"}

package/dist/checkout/routes.js

@@ -0,0 +1,59 @@
+/**
+ * Storefront checkout route module, owned by `@voyant-travel/commerce`.
+ *
+ * POST /checkout/start parses the BookingJourney checkout request and
+ * delegates to the checkout-start service. A deployment composes this and
+ * supplies the `CheckoutStartOptions` (injected tax-settings + owned-product
+ * name + bank-transfer instruction readers) the service needs.
+ *
+ * Mount the returned Hono at `/v1/public/catalog` (relative paths).
+ */
+import { parseJsonBody } from "@voyant-travel/hono";
+import { Hono } from "hono";
+import { CatalogCheckoutStartError, checkoutStartSchema, startCatalogCheckout, } from "./start-service.js";
+/**
+ * Build the storefront checkout routes. `options` may be a value or a
+ * per-request factory — the deployment passes a factory when an injected
+ * option needs to capture the request `Context` (e.g. resolving a payment
+ * provider runtime from the per-request container).
+ */
+export function createCatalogCheckoutRoutes(options) {
+    const routes = new Hono();
+    routes.post("/checkout/start", (c) => handleCheckoutStart(c, typeof options === "function" ? options(c) : options));
+    return routes;
+}
+async function handleCheckoutStart(c, options) {
+    let body;
+    try {
+        body = await parseJsonBody(c, checkoutStartSchema);
+    }
+    catch (err) {
+        return c.json({ error: err instanceof Error ? err.message : "invalid body" }, 400);
+    }
+    try {
+        const result = await startCatalogCheckout({
+            db: c.get("db"),
+            env: c.env,
+            eventBus: c.var.eventBus,
+            resolveRuntime: (key) => c.var.container?.resolve(key),
+            requestMeta: checkoutRequestMeta(c),
+            options,
+        }, body);
+        return c.json(result);
+    }
+    catch (err) {
+        if (err instanceof CatalogCheckoutStartError) {
+            return c.json({ error: err.code }, err.status);
+        }
+        throw err;
+    }
+}
+function checkoutRequestMeta(c) {
+    return {
+        clientIp: c.req.header("cf-connecting-ip") ??
+            c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+            c.req.header("x-real-ip") ??
+            "",
+        userAgent: c.req.header("user-agent") ?? "",
+    };
+}

package/dist/checkout/start-service.d.ts

@@ -0,0 +1,75 @@
+import type { EventBus } from "@voyant-travel/core";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { z } from "zod";
+import type { CheckoutStartOptions } from "./options.js";
+export declare const checkoutStartSchema: z.ZodObject<{
+    bookingId: z.ZodString;
+    paymentIntent: z.ZodEnum<{
+        hold: "hold";
+        card: "card";
+        bank_transfer: "bank_transfer";
+        inquiry: "inquiry";
+    }>;
+    contractAcceptance: z.ZodOptional<z.ZodObject<{
+        templateId: z.ZodString;
+        templateSlug: z.ZodString;
+        acceptedTerms: z.ZodLiteral<true>;
+        acceptedMarketing: z.ZodBoolean;
+        acceptedAt: z.ZodString;
+        renderedHtml: z.ZodString;
+    }, z.core.$strip>>;
+    payerEmail: z.ZodOptional<z.ZodString>;
+    payerName: z.ZodOptional<z.ZodString>;
+    returnOrigin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutStartInput = z.infer<typeof checkoutStartSchema>;
+export interface CheckoutStartRequestMeta {
+    clientIp?: string;
+    userAgent?: string;
+}
+export interface CatalogCheckoutStartContext {
+    db: PostgresJsDatabase;
+    env: Record<string, string | undefined>;
+    eventBus?: EventBus;
+    resolveRuntime?: (key: string) => unknown;
+    requestMeta?: CheckoutStartRequestMeta;
+    /** Deployment-supplied injected readers (tax settings, owned product name, bank transfer). */
+    options: CheckoutStartOptions;
+}
+export type CatalogCheckoutStartResult = {
+    kind: "card_redirect";
+    bookingId: string;
+    paymentSessionId: string;
+    redirectUrl: string | null;
+    note?: string;
+} | {
+    kind: "bank_transfer_instructions";
+    bookingId: string;
+    proformaId: string | null;
+    proformaNumber: string | null;
+    paymentSessionId: string | null;
+    instructions: {
+        beneficiary: string;
+        iban: string;
+        bankName: string;
+        reference: string;
+        amountCents: number;
+        currency: string;
+        dueAt: string;
+    };
+} | {
+    kind: "inquiry_received";
+    bookingId: string;
+    inquiryId: string;
+    note?: string;
+} | {
+    kind: "hold_placed";
+    bookingId: string;
+};
+export declare class CatalogCheckoutStartError extends Error {
+    readonly code: string;
+    readonly status: 404 | 409 | 500 | 502;
+    constructor(code: string, status: 404 | 409 | 500 | 502);
+}
+export declare function startCatalogCheckout(context: CatalogCheckoutStartContext, body: CheckoutStartInput): Promise<CatalogCheckoutStartResult>;
+//# sourceMappingURL=start-service.d.ts.map

package/dist/checkout/start-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-service.d.ts","sourceRoot":"","sources":["../../src/checkout/start-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAOnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAExD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;iBAgB9B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAEpE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,kBAAkB,CAAA;IACtB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACvC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACzC,WAAW,CAAC,EAAE,wBAAwB,CAAA;IACtC,8FAA8F;IAC9F,OAAO,EAAE,oBAAoB,CAAA;CAC9B;AAED,MAAM,MAAM,0BAA0B,GAClC;IACE,IAAI,EAAE,eAAe,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GACD;IACE,IAAI,EAAE,4BAA4B,CAAA;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,YAAY,EAAE;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;CACF,GACD;IACE,IAAI,EAAE,kBAAkB,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GACD;IACE,IAAI,EAAE,aAAa,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAEL,qBAAa,yBAA0B,SAAQ,KAAK;aAEhC,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG;gBAD7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG;CAKhD;AAYD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,EACpC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,0BAA0B,CAAC,CAmErC"}

package/dist/checkout/start-service.js

@@ -0,0 +1,415 @@
+// agent-quality: file-size exception -- owner: commerce; the checkout-start
+// service (card / bank-transfer / inquiry / hold intents) is one cohesive
+// entry point; splitting it would scatter a single request lifecycle.
+import { bookingsService, canTransitionBooking, transitionBooking } from "@voyant-travel/bookings";
+import { bookings } from "@voyant-travel/bookings/schema";
+import { financeService, issueProformaFromBooking, } from "@voyant-travel/finance";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { materializeBookingFromSnapshot } from "./materialization.js";
+export const checkoutStartSchema = z.object({
+    bookingId: z.string().min(1),
+    paymentIntent: z.enum(["card", "bank_transfer", "hold", "inquiry"]),
+    contractAcceptance: z
+        .object({
+        templateId: z.string().min(1),
+        templateSlug: z.string().min(1),
+        acceptedTerms: z.literal(true),
+        acceptedMarketing: z.boolean(),
+        acceptedAt: z.string().datetime(),
+        renderedHtml: z.string().min(1),
+    })
+        .optional(),
+    payerEmail: z.string().email().optional(),
+    payerName: z.string().optional(),
+    returnOrigin: z.string().url().optional(),
+});
+export class CatalogCheckoutStartError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = "CatalogCheckoutStartError";
+    }
+}
+export async function startCatalogCheckout(context, body) {
+    const db = context.db;
+    let booking = (await db.select().from(bookings).where(eq(bookings.id, body.bookingId)).limit(1))[0] ?? null;
+    // Sourced products go through the catalog-snapshot path on
+    // /book — they never write to the `bookings` table directly.
+    // Materialize a minimal row from the snapshot so the rest of the
+    // checkout-start flow (state transitions, payment session, etc)
+    // can operate on a normal booking. Owned products already have
+    // the row written by their OwnedBookingHandler.commit.
+    if (!booking) {
+        booking = await materializeBookingFromSnapshot(db, body.bookingId, context.env, context.options);
+    }
+    if (!booking)
+        throw new CatalogCheckoutStartError("booking_not_found", 404);
+    if ((body.paymentIntent === "card" || body.paymentIntent === "bank_transfer") &&
+        booking.holdExpiresAt &&
+        booking.holdExpiresAt <= new Date()) {
+        throw new CatalogCheckoutStartError("hold_expired", 409);
+    }
+    // Pre-create a draft contract carrying the acceptance fingerprint
+    // in `metadata.acceptance`. The auto-generate-contract subscriber
+    // (fired by `booking.confirmed` after payment) detects this draft
+    // by booking_id, populates the rendered body + variables from the
+    // confirmed booking state, and issues + generates the PDF —
+    // allocating the contract number at issue time. The signature
+    // promotion path then reads `metadata.acceptance` straight off
+    // the contract row instead of relaying through internal_notes.
+    //
+    // Idempotency: re-entering /checkout/start (e.g. customer hits
+    // Back then resubmits) finds the existing draft and updates its
+    // metadata in place — no duplicate contract rows, no duplicate
+    // acceptance fingerprints.
+    if (body.contractAcceptance) {
+        try {
+            await persistAcceptanceDraftContract(db, context.requestMeta ?? {}, booking, body.contractAcceptance);
+        }
+        catch (err) {
+            // Acceptance recording is best-effort during checkout-start —
+            // the customer still needs to reach payment even if our
+            // legal-side pre-create stumbles. Surfacing as a 5xx here
+            // would block real bookings on a contract-template mis-config;
+            // we log and proceed so payment can land.
+            console.error("[catalog-checkout] persistAcceptanceDraftContract failed", err);
+        }
+    }
+    switch (body.paymentIntent) {
+        case "card":
+            return startCardCheckout(context, booking, body);
+        case "bank_transfer":
+            return startBankTransferCheckout(context, booking);
+        case "inquiry":
+            return startInquiryCheckout(context, booking);
+        case "hold":
+            return {
+                kind: "hold_placed",
+                bookingId: booking.id,
+            };
+    }
+}
+/**
+ * Inquiry intent — write a quote for the operator to follow
+ * up on, then cancel the booking so inventory isn't blocked.
+ *
+ * The pipeline + stage used can be pinned via env vars
+ * (`INQUIRY_PIPELINE_ID` / `INQUIRY_STAGE_ID`); otherwise we pick the
+ * first sales pipeline + its first stage. Without any configured
+ * pipeline the endpoint falls back to a stub response so the journey
+ * keeps working through demos.
+ */
+async function startInquiryCheckout(context, booking) {
+    const db = context.db;
+    const env = context.env;
+    const eventBus = context.eventBus;
+    let pipelineId = env.INQUIRY_PIPELINE_ID ?? null;
+    let stageId = env.INQUIRY_STAGE_ID ?? null;
+    if (!pipelineId || !stageId) {
+        const { quotesService } = await import("@voyant-travel/quotes");
+        const pipelines = await quotesService
+            .listPipelines(db, { entityType: "quote", limit: 1, offset: 0 })
+            .catch(() => null);
+        const firstPipeline = pipelines?.data?.[0] ?? null;
+        if (firstPipeline) {
+            pipelineId = pipelineId ?? firstPipeline.id;
+            const stages = await quotesService
+                .listStages(db, { pipelineId: firstPipeline.id, limit: 1, offset: 0 })
+                .catch(() => null);
+            stageId = stageId ?? stages?.data?.[0]?.id ?? null;
+        }
+    }
+    if (!pipelineId || !stageId) {
+        // No quote pipeline configured. Still cancel the booking so the
+        // hold doesn't linger, and return a stub inquiry reference.
+        await releaseInquiryBooking(db, booking, eventBus);
+        return {
+            kind: "inquiry_received",
+            bookingId: booking.id,
+            inquiryId: `inq-${booking.id}`,
+            note: "No quote pipeline configured — set INQUIRY_PIPELINE_ID + INQUIRY_STAGE_ID to record a real quote.",
+        };
+    }
+    const { quotesService } = await import("@voyant-travel/quotes");
+    const quote = await quotesService.createQuote(db, {
+        title: `Inquiry — booking ${booking.bookingNumber}`,
+        pipelineId,
+        stageId,
+        personId: booking.personId,
+        organizationId: booking.organizationId,
+        status: "open",
+        valueAmountCents: booking.sellAmountCents ?? null,
+        valueCurrency: booking.sellCurrency ?? null,
+        source: "storefront-inquiry",
+        sourceRef: booking.id,
+        tags: [],
+    });
+    await releaseInquiryBooking(db, booking, eventBus);
+    await eventBus?.emit("inquiry.created", {
+        quoteId: quote?.id ?? null,
+        bookingId: booking.id,
+        bookingNumber: booking.bookingNumber,
+        pipelineId,
+        stageId,
+    });
+    return {
+        kind: "inquiry_received",
+        bookingId: booking.id,
+        inquiryId: quote?.id ?? `inq-${booking.id}`,
+    };
+}
+async function releaseInquiryBooking(db, booking, eventBus) {
+    // Inquiry mode: don't keep capacity locked. Cancel the booking so
+    // the hold drops; the row stays for the audit trail.
+    if (!canTransitionBooking(booking.status, "cancelled"))
+        return;
+    try {
+        await bookingsService.cancelBooking(db, booking.id, { reason: "Released — converted to inquiry" }, undefined, { eventBus });
+    }
+    catch (err) {
+        console.warn("[catalog-checkout] could not release booking on inquiry path", err);
+    }
+}
+/**
+ * Move the booking from `on_hold` (or `draft`) into `awaiting_payment`
+ * so ops can see in the bookings list which rows are pending money
+ * vs. just brokered. The state machine accepts the transition;
+ * already-`awaiting_payment` / already-`confirmed` rows are
+ * silently no-op'd so re-entries (e.g. user reloads the dialog
+ * twice) stay idempotent.
+ */
+async function markAwaitingPayment(db, booking) {
+    if (!canTransitionBooking(booking.status, "awaiting_payment"))
+        return;
+    const patch = transitionBooking(booking.status, "awaiting_payment");
+    await db
+        .update(bookings)
+        .set({ ...patch, updatedAt: new Date() })
+        .where(eq(bookings.id, booking.id));
+}
+async function startCardCheckout(context, booking, body) {
+    const db = context.db;
+    // Without a card provider configured, fall back to a placeholder
+    // redirect — the storefront's confirmation page polls booking status
+    // and surfaces "we're still processing" until ops marks payment
+    // received manually. Useful for demos without sandbox creds.
+    const amountCents = booking.sellAmountCents ?? 0;
+    const currency = booking.sellCurrency ?? "EUR";
+    await markAwaitingPayment(db, booking);
+    const session = await financeService.createPaymentSession(db, {
+        bookingId: booking.id,
+        amountCents,
+        currency,
+        status: "pending",
+        expiresAt: booking.holdExpiresAt?.toISOString() ?? null,
+        payerName: body.payerName ?? null,
+        payerEmail: body.payerEmail ?? null,
+        notes: `Storefront card payment for booking ${booking.bookingNumber}`,
+        targetType: "booking",
+    });
+    if (!session) {
+        throw new CatalogCheckoutStartError("could_not_create_payment_session", 500);
+    }
+    // Derive billing name from the payer name; the deployment-supplied
+    // `startCardPayment` fills in any provider-specific placeholder billing
+    // (city, country code, postal code, etc).
+    const [firstName, ...rest] = (body.payerName ?? "").trim().split(/\s+/);
+    const lastName = rest.length > 0 ? rest.join(" ") : "Customer";
+    let started = null;
+    try {
+        started =
+            (await context.options.startCardPayment?.({
+                db,
+                sessionId: session.id,
+                billing: {
+                    email: body.payerEmail ?? "tbd@example.com",
+                    firstName: firstName || "Customer",
+                    lastName,
+                },
+                description: `Booking ${booking.bookingNumber}`,
+                // The provider redirects the customer back to this URL after 3DS.
+                // Land them on the confirmation page in card_pending mode — the
+                // provider webhook does the actual booking confirmation in the
+                // background; this page just polls until the booking flips to
+                // `confirmed`.
+                returnUrl: body.returnOrigin
+                    ? `${body.returnOrigin}/shop/confirmation/${encodeURIComponent(booking.id)}?kind=card_pending`
+                    : undefined,
+            })) ?? null;
+    }
+    catch (err) {
+        console.error("[catalog-checkout] startCardPayment failed", err);
+        throw new CatalogCheckoutStartError("payment_provider_failed", 502);
+    }
+    if (!started) {
+        // No card provider configured — surface the booking on the standard
+        // confirmation page in `card_pending` mode. The page polls booking
+        // status and unlocks contract/invoice download links once the
+        // operator marks payment received via the booking detail's
+        // pending-payment-sessions panel.
+        return {
+            kind: "card_redirect",
+            bookingId: booking.id,
+            paymentSessionId: session.id,
+            redirectUrl: `/shop/confirmation/${encodeURIComponent(booking.id)}?kind=card_pending&session=${encodeURIComponent(session.id)}`,
+            note: "Netopia not configured — falling back to a confirmation-page poll.",
+        };
+    }
+    return {
+        kind: "card_redirect",
+        bookingId: booking.id,
+        paymentSessionId: session.id,
+        redirectUrl: started.redirectUrl,
+    };
+}
+async function startBankTransferCheckout(context, booking) {
+    const db = context.db;
+    await markAwaitingPayment(db, booking);
+    // Issue a proforma synchronously so the customer leaves with a
+    // document reference. SmartBill (subscribing to
+    // invoice.proforma.issued) will sync to its proforma endpoint.
+    const issueDate = new Date().toISOString().slice(0, 10);
+    const dueDate = new Date(Date.now() + 5 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    const eventBus = context.eventBus;
+    const proformaInput = {
+        bookingId: booking.id,
+        issueDate,
+        dueDate,
+        invoiceType: "proforma",
+        notes: null,
+    };
+    // Pull the booking's items via the shared schema; financeService
+    // wants the InvoiceFromBookingData shape (booking + items).
+    const { bookingItems } = await import("@voyant-travel/bookings/schema");
+    const bookingItemRows = await db
+        .select()
+        .from(bookingItems)
+        .where(eq(bookingItems.bookingId, booking.id));
+    const proforma = await issueProformaFromBooking(db, proformaInput, {
+        booking: {
+            id: booking.id,
+            bookingNumber: booking.bookingNumber,
+            personId: booking.personId,
+            organizationId: booking.organizationId,
+            sellCurrency: booking.sellCurrency,
+            baseCurrency: booking.baseCurrency,
+            fxRateSetId: null,
+            sellAmountCents: booking.sellAmountCents,
+            baseSellAmountCents: booking.baseSellAmountCents,
+        },
+        items: bookingItemRows.map((item) => ({
+            id: item.id,
+            title: item.title,
+            quantity: item.quantity,
+            unitSellAmountCents: item.unitSellAmountCents,
+            totalSellAmountCents: item.totalSellAmountCents,
+        })),
+    }, { eventBus });
+    // Create a payment session targeting the booking + proforma so the
+    // operator can mark it received via the existing
+    // POST /v1/admin/finance/payment-sessions/:id/complete endpoint.
+    // That endpoint emits payment.completed which fires the
+    // checkout-finalize workflow (final invoice, contract auto-gen).
+    const paymentSession = await financeService.createPaymentSession(db, {
+        bookingId: booking.id,
+        invoiceId: proforma?.id ?? null,
+        amountCents: booking.sellAmountCents ?? 0,
+        currency: booking.sellCurrency ?? "EUR",
+        status: "pending",
+        paymentMethod: "bank_transfer",
+        expiresAt: booking.holdExpiresAt?.toISOString() ?? null,
+        notes: `Bank transfer for booking ${booking.bookingNumber} (proforma ${proforma?.invoiceNumber ?? "—"})`,
+        targetType: "booking",
+    });
+    const bankTransfer = await context.options.resolveBankTransferInstructions(db, context.env);
+    return {
+        kind: "bank_transfer_instructions",
+        bookingId: booking.id,
+        proformaId: proforma?.id ?? null,
+        proformaNumber: proforma?.invoiceNumber ?? null,
+        paymentSessionId: paymentSession?.id ?? null,
+        instructions: {
+            beneficiary: bankTransfer.beneficiary,
+            iban: bankTransfer.iban,
+            bankName: bankTransfer.bankName,
+            reference: `BOOK-${booking.bookingNumber}`,
+            amountCents: booking.sellAmountCents ?? 0,
+            currency: booking.sellCurrency ?? "EUR",
+            dueAt: dueDate,
+        },
+    };
+}
+/**
+ * Pre-create (or update) a draft contract carrying the acceptance
+ * fingerprint in `metadata.acceptance`. Called from /checkout/start
+ * when the customer accepts the contract preview, BEFORE payment
+ * lands.
+ *
+ * The draft has:
+ *   - status="draft" (no number yet — issued post-payment)
+ *   - templateVersionId pointing at the slug's current version
+ *   - bookingId / personId / organizationId from the booking
+ *   - metadata.acceptance with templateId/Slug, acceptedAt,
+ *     acceptedMarketing, ipAddress, userAgent, renderedHtmlLength
+ *
+ * The body is left empty; `autoGenerateContractForBooking` (fired by
+ * `booking.confirmed`) detects the existing draft, fills in the
+ * fully-resolved variables, then issues + generates the PDF.
+ *
+ * Idempotency: a re-entry of /checkout/start finds the existing draft
+ * and updates its `metadata.acceptance` in place (last acceptance
+ * wins — typical when customer hits Back, edits acceptance, resubmits).
+ */
+async function persistAcceptanceDraftContract(db, requestMeta, booking, acceptance) {
+    const { contractsService } = await import("@voyant-travel/legal/contracts");
+    const template = await contractsService.findTemplateBySlug(db, acceptance.templateSlug);
+    if (!template?.currentVersionId) {
+        console.warn(`[catalog-checkout] persistAcceptanceDraftContract: template "${acceptance.templateSlug}" not found or has no current version; skipping.`);
+        return;
+    }
+    const acceptanceMetadata = {
+        templateId: acceptance.templateId,
+        templateSlug: acceptance.templateSlug,
+        acceptedAt: acceptance.acceptedAt,
+        acceptedMarketing: acceptance.acceptedMarketing,
+        clientIp: requestMeta.clientIp ?? "",
+        userAgent: requestMeta.userAgent ?? "",
+        renderedHtmlLength: acceptance.renderedHtml.length,
+    };
+    // Look for an existing draft contract on this booking. Storefront
+    // re-submissions hit this branch.
+    const existingList = await contractsService.listContracts(db, {
+        bookingId: booking.id,
+        limit: 1,
+        offset: 0,
+    });
+    const existing = existingList.data[0];
+    if (existing) {
+        const prior = existing.metadata ?? {};
+        await contractsService.updateContract(db, existing.id, {
+            metadata: { ...prior, acceptance: acceptanceMetadata },
+        });
+        return;
+    }
+    await contractsService.createContract(db, {
+        scope: "customer",
+        status: "draft",
+        title: `${template.name} — ${booking.bookingNumber}`,
+        templateVersionId: template.currentVersionId,
+        seriesId: null,
+        bookingId: booking.id,
+        personId: booking.personId ?? null,
+        organizationId: booking.organizationId ?? null,
+        language: template.language,
+        variables: {},
+        metadata: {
+            autoGenerated: true,
+            trigger: "storefront.checkout-acceptance",
+            acceptance: acceptanceMetadata,
+        },
+    });
+}

package/dist/checkout/start-service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=start-service.test.d.ts.map

package/dist/checkout/start-service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-service.test.d.ts","sourceRoot":"","sources":["../../src/checkout/start-service.test.ts"],"names":[],"mappings":""}

package/dist/checkout/start-service.test.js

@@ -0,0 +1,57 @@
+import { Hono } from "hono";
+import { describe, expect, it, vi } from "vitest";
+import { createCatalogCheckoutRoutes } from "./routes.js";
+import { CatalogCheckoutStartError, startCatalogCheckout } from "./start-service.js";
+function stubOptions(overrides = {}) {
+    return {
+        resolveBookingTaxSettings: vi.fn(),
+        getOwnedProductName: vi.fn().mockResolvedValue(null),
+        resolveBankTransferInstructions: vi
+            .fn()
+            .mockResolvedValue({ beneficiary: "Acme", iban: "RO00", bankName: "Bank" }),
+        ...overrides,
+    };
+}
+/** Stub db whose first `select().from().where().limit()` returns `bookingRows`. */
+function stubDb(bookingRows) {
+    return {
+        select: () => ({
+            from: () => ({
+                where: () => ({ limit: async () => bookingRows }),
+            }),
+        }),
+    };
+}
+describe("startCatalogCheckout", () => {
+    it("places a hold for an existing booking", async () => {
+        const booking = { id: "bk_1", status: "on_hold", holdExpiresAt: null };
+        const result = await startCatalogCheckout({
+            db: stubDb([booking]),
+            env: {},
+            options: stubOptions(),
+        }, { bookingId: "bk_1", paymentIntent: "hold" });
+        expect(result).toEqual({ kind: "hold_placed", bookingId: "bk_1" });
+    });
+    it("throws booking_not_found when no booking + no snapshot materializes", async () => {
+        // No booking row, and the snapshot lookup (dynamic import of catalog)
+        // returns nothing → materializeBookingFromSnapshot yields null.
+        const db = stubDb([]);
+        const err = await startCatalogCheckout({ db, env: {}, options: stubOptions() }, { bookingId: "missing", paymentIntent: "hold" }).catch((e) => e);
+        expect(err).toBeInstanceOf(CatalogCheckoutStartError);
+        expect(err).toMatchObject({ code: "booking_not_found", status: 404 });
+    });
+});
+describe("createCatalogCheckoutRoutes", () => {
+    it("returns 400 on an invalid checkout body", async () => {
+        // Invalid body fails schema validation before the handler reads `db`,
+        // so no db wiring is needed for the 400 path.
+        const app = new Hono();
+        app.route("/v1/public/catalog", createCatalogCheckoutRoutes(stubOptions()));
+        const res = await app.request("/v1/public/catalog/checkout/start", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ bookingId: "", paymentIntent: "nope" }),
+        });
+        expect(res.status).toBe(400);
+    });
+});