@voyant-travel/catalog 0.117.2

package/dist/booking-engine/book.js

@@ -0,0 +1,311 @@
+/**
+ * `bookEntity` — the second step in the booking engine lifecycle.
+ *
+ * Validates the supplied quote, calls `adapter.reserve`, and writes a
+ * `booking_catalog_snapshot` row with the frozen view, source pointer,
+ * and pricing breakdown. The snapshot is the audit record; the source
+ * pointer is what subsequent `cancelEntity` / status calls dispatch
+ * against.
+ *
+ * `bookingId` is plain text (no FK), so the engine accepts an existing
+ * id from the caller (when a `bookings` row already exists) or generates
+ * one on demand. This keeps the engine decoupled from `packages/bookings`
+ * — the engine and the bookings module evolve independently and are
+ * joined at read time via the shared `booking_id` text column.
+ */
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { eq } from "drizzle-orm";
+import { captureSnapshot } from "../services/snapshot-service.js";
+import { bookingCatalogSnapshotTable, } from "../snapshot/schema.js";
+import { BookingEngineError, QUOTE_NOT_FOUND, QuoteExpiredError, QuoteMismatchError, ReserveFailedError, } from "./errors.js";
+import { OWNED_SOURCE_KIND } from "./owned-handler.js";
+import { catalogQuotesTable } from "./schema.js";
+function paymentIntentToAdapterRecord(intent) {
+    return { ...intent };
+}
+/**
+ * Book the row referenced by `quoteId`. End-to-end: validate quote,
+ * dispatch `adapter.reserve`, capture snapshot, mark quote consumed.
+ *
+ * Throws:
+ *   - `BookingEngineError(QUOTE_NOT_FOUND)` if the quote doesn't exist.
+ *   - `QuoteExpiredError` if the quote's `expires_at` has passed.
+ *   - `QuoteMismatchError` if a future caller tries to book a different
+ *     entity than the quote was issued for (defensive — the engine
+ *     re-reads quote.entity_*).
+ *   - `NoAdapterRegisteredError` if the registry has no adapter for
+ *     the quote's `source_kind`.
+ *   - `ReserveFailedError` when the adapter returns `status: "failed"`.
+ */
+export async function bookEntity(db, deps, request) {
+    // Idempotency check — when the caller supplies a key, look for a
+    // prior snapshot with the same key and short-circuit. Snapshot rows
+    // outlive quotes (audit), so the lookup works even if the quote
+    // has been consumed or expired.
+    if (request.idempotencyKey) {
+        const prior = await loadSnapshotByIdempotencyKey(db, request.idempotencyKey);
+        if (prior) {
+            return {
+                bookingId: prior.booking_id,
+                orderRef: prior.source_ref ?? prior.id,
+                // Status comes from the prior commit's payload; default to
+                // "held" since we don't persist the original status column.
+                // Callers that need the precise status should re-read the
+                // booking row.
+                status: "held",
+                snapshotId: prior.id,
+                pricing: snapshotToPricing(prior),
+                upstreamPayload: undefined,
+            };
+        }
+    }
+    const quote = await loadQuote(db, request.quoteId);
+    assertQuoteUsable(quote);
+    const paymentIntent = request.paymentIntent ?? { type: "hold" };
+    const bookingId = request.bookingId ?? newId("bookings");
+    const isOwned = quote.source_kind === OWNED_SOURCE_KIND && deps.ownedHandlers != null;
+    // Owned arm: dispatch to handler.commit; skip snapshot-content
+    // capture (owned content lives in the operator's own DB, not in a
+    // remote upstream).
+    if (isOwned) {
+        if (!deps.ownedHandlers)
+            throw new Error("unreachable: ownedHandlers checked above");
+        const handler = deps.ownedHandlers.resolveOrThrow(quote.entity_module);
+        const quotePricing = readPricingFromQuote(quote);
+        const commitResult = await handler.commit({ db, adapterContext: request.adapterContext }, {
+            entityModule: quote.entity_module,
+            entityId: quote.entity_id,
+            bookingId,
+            party: request.party,
+            parameters: request.parameters,
+            pricing: quotePricing,
+            draft: request.parameters?.draft,
+        });
+        if (commitResult.status === "failed") {
+            throw new ReserveFailedError(commitResult.upstreamPayload, quote.source_kind, quote.entity_id);
+        }
+        // The handler may mint its own booking row id rather than use the provided
+        // one — adopt it so the response + snapshot + quote marker reference the
+        // real booking (otherwise the detail page 404s on a non-existent id).
+        const ownedBookingId = commitResult.bookingId ?? bookingId;
+        const finalPricing = commitResult.pricing ?? quotePricing;
+        const ownedFrozenPayload = {
+            quote: serializeQuote(quote),
+            commit: commitResult.upstreamPayload ?? null,
+            paymentIntent,
+        };
+        const ownedSnapshot = await captureSnapshot(db, {
+            bookingId: ownedBookingId,
+            entityModule: quote.entity_module,
+            entityId: quote.entity_id,
+            sourceKind: quote.source_kind,
+            sourceProvider: quote.source_provider ?? undefined,
+            sourceConnectionId: quote.source_connection_id ?? undefined,
+            sourceRef: commitResult.orderRef || quote.source_ref || undefined,
+            frozenPayload: ownedFrozenPayload,
+            pricingBasis: finalPricing,
+            idempotencyKey: request.idempotencyKey,
+        });
+        await markQuoteConsumed(db, quote.id, ownedBookingId);
+        return {
+            bookingId: ownedBookingId,
+            orderRef: commitResult.orderRef || ownedSnapshot.id,
+            status: commitResult.status,
+            snapshotId: ownedSnapshot.id,
+            pricing: finalPricing,
+            upstreamPayload: commitResult.upstreamPayload,
+        };
+    }
+    // Sourced arm — preserves the existing dispatch path verbatim.
+    const adapter = quote.source_connection_id
+        ? (deps.registry.resolveByConnection(quote.source_connection_id) ??
+            deps.registry.resolveOrThrow(quote.source_kind))
+        : deps.registry.resolveOrThrow(quote.source_kind);
+    if (!adapter.reserve) {
+        throw new BookingEngineError("RESERVE_FAILED", `adapter "${adapter.kind}" does not implement reserve()`, { sourceKind: quote.source_kind });
+    }
+    const reserveRequest = {
+        entity_module: quote.entity_module,
+        entity_id: quote.entity_id,
+        parameters: request.parameters ?? {},
+        party: request.party,
+        payment_intent: paymentIntentToAdapterRecord(paymentIntent),
+        scope: request.adapterScope,
+        idempotency_key: request.idempotencyKey,
+    };
+    const reserveResult = await adapter.reserve(request.adapterContext, reserveRequest);
+    if (reserveResult.status === "failed") {
+        throw new ReserveFailedError(reserveResult.upstream_payload, quote.source_kind, quote.entity_id);
+    }
+    const pricing = readPricingFromQuote(quote);
+    // Snapshot content capture per sourced-content §5.1 — refresh from
+    // the adapter, fall back to cache, throw if neither produces content.
+    // Skipped entirely when the deps callback isn't wired (legacy
+    // behavior).
+    let contentCapture = null;
+    if (deps.captureSnapshotContent && request.contentScope) {
+        contentCapture = await deps.captureSnapshotContent({
+            db,
+            entity_module: quote.entity_module,
+            entity_id: quote.entity_id,
+            source_kind: quote.source_kind,
+            source_connection_id: quote.source_connection_id ?? undefined,
+            source_ref: reserveResult.upstream_ref || quote.source_ref || undefined,
+            locale: request.contentScope.locale,
+            market: request.contentScope.market,
+            currency: request.contentScope.currency,
+            adapterContext: request.adapterContext,
+        });
+    }
+    const frozenPayload = {
+        quote: serializeQuote(quote),
+        reserve: reserveResult.upstream_payload ?? null,
+        paymentIntent,
+    };
+    if (contentCapture) {
+        // The content_capture envelope is alongside `content` so audit can
+        // later distinguish a fresh capture from a cache fallback (per
+        // §5.1). Both fields are nested under frozen_payload as opaque
+        // JSONB — no schema migration required.
+        frozenPayload.content = contentCapture.content;
+        frozenPayload.content_capture = {
+            source: contentCapture.source,
+            fetched_at: contentCapture.fetched_at,
+            fallback_reason: contentCapture.fallback_reason,
+            content_etag: contentCapture.content_etag,
+            content_schema_version: contentCapture.content_schema_version,
+        };
+    }
+    const snapshotInput = {
+        bookingId,
+        entityModule: quote.entity_module,
+        entityId: quote.entity_id,
+        sourceKind: quote.source_kind,
+        sourceProvider: quote.source_provider ?? undefined,
+        sourceConnectionId: quote.source_connection_id ?? undefined,
+        sourceRef: reserveResult.upstream_ref || quote.source_ref || undefined,
+        frozenPayload,
+        pricingBasis: pricing,
+        idempotencyKey: request.idempotencyKey,
+    };
+    const snapshot = await captureSnapshot(db, snapshotInput);
+    await markQuoteConsumed(db, quote.id, bookingId);
+    return {
+        bookingId,
+        orderRef: reserveResult.upstream_ref || snapshot.id,
+        status: reserveResult.status,
+        snapshotId: snapshot.id,
+        pricing,
+        upstreamPayload: reserveResult.upstream_payload,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+async function loadSnapshotByIdempotencyKey(db, idempotencyKey) {
+    const rows = (await db
+        .select()
+        .from(bookingCatalogSnapshotTable)
+        .where(eq(bookingCatalogSnapshotTable.idempotency_key, idempotencyKey))
+        .limit(1));
+    return rows[0];
+}
+function snapshotToPricing(snapshot) {
+    if (snapshot.pricing_base_amount == null || !snapshot.pricing_currency)
+        return undefined;
+    const base = typeof snapshot.pricing_base_amount === "string"
+        ? Number.parseFloat(snapshot.pricing_base_amount)
+        : Number(snapshot.pricing_base_amount);
+    if (!Number.isFinite(base))
+        return undefined;
+    return {
+        base_amount: base,
+        taxes: numericOrZero(snapshot.pricing_taxes),
+        fees: numericOrZero(snapshot.pricing_fees),
+        surcharges: numericOrZero(snapshot.pricing_surcharges),
+        currency: snapshot.pricing_currency,
+        breakdown: snapshot.pricing_breakdown ?? undefined,
+        appliedOffers: snapshot.pricing_applied_offers ?? undefined,
+    };
+}
+async function loadQuote(db, quoteId) {
+    const rows = (await db
+        .select()
+        .from(catalogQuotesTable)
+        .where(eq(catalogQuotesTable.id, quoteId))
+        .limit(1));
+    const quote = rows[0];
+    if (!quote) {
+        throw new BookingEngineError(QUOTE_NOT_FOUND, `quote ${quoteId} not found`, { quoteId });
+    }
+    return quote;
+}
+function assertQuoteUsable(quote) {
+    if (quote.consumed_at) {
+        throw new QuoteMismatchError(quote.id, { entityModule: quote.entity_module, entityId: quote.entity_id }, { entityModule: quote.entity_module, entityId: quote.entity_id });
+    }
+    const expiresAt = new Date(quote.expires_at);
+    if (Number.isNaN(expiresAt.getTime())) {
+        throw new BookingEngineError(QUOTE_NOT_FOUND, `quote ${quote.id} has invalid expires_at`, {
+            quoteId: quote.id,
+        });
+    }
+    if (expiresAt.getTime() <= Date.now()) {
+        throw new QuoteExpiredError(quote.id, expiresAt);
+    }
+    if (!quote.available) {
+        throw new ReserveFailedError({ invalidReason: quote.invalid_reason }, quote.source_kind, quote.entity_id);
+    }
+}
+async function markQuoteConsumed(db, quoteId, bookingId) {
+    await db
+        .update(catalogQuotesTable)
+        .set({
+        consumed_at: new Date(),
+        consumed_booking_id: bookingId,
+    })
+        .where(eq(catalogQuotesTable.id, quoteId));
+}
+function readPricingFromQuote(quote) {
+    const baseRaw = quote.pricing_base_amount;
+    if (baseRaw == null)
+        return undefined;
+    const base = typeof baseRaw === "string" ? Number.parseFloat(baseRaw) : Number(baseRaw);
+    if (!Number.isFinite(base))
+        return undefined;
+    const currency = quote.pricing_currency;
+    if (!currency)
+        return undefined;
+    return {
+        base_amount: base,
+        taxes: numericOrZero(quote.pricing_taxes),
+        fees: numericOrZero(quote.pricing_fees),
+        surcharges: numericOrZero(quote.pricing_surcharges),
+        currency,
+        breakdown: quote.pricing_breakdown ?? undefined,
+        appliedOffers: quote.pricing_applied_offers ?? undefined,
+    };
+}
+function numericOrZero(v) {
+    if (v == null)
+        return 0;
+    const n = typeof v === "string" ? Number.parseFloat(v) : Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+function serializeQuote(quote) {
+    return {
+        id: quote.id,
+        entity_module: quote.entity_module,
+        entity_id: quote.entity_id,
+        source_kind: quote.source_kind,
+        source_provider: quote.source_provider,
+        source_ref: quote.source_ref,
+        locale: quote.locale,
+        audience: quote.audience,
+        market: quote.market,
+        currency: quote.currency,
+        pricing_base_amount: quote.pricing_base_amount,
+        pricing_currency: quote.pricing_currency,
+        upstream_payload: quote.upstream_payload,
+        created_at: quote.created_at,
+        expires_at: quote.expires_at,
+    };
+}

package/dist/booking-engine/cancel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `cancelEntity` — third step in the booking engine lifecycle.
+ *
+ * Looks up the snapshot row, dispatches `adapter.cancel`, returns the
+ * adapter's refund result. The snapshot stays — it's the audit record —
+ * and the booking row's lifecycle (set status to cancelled, etc.) is the
+ * caller's responsibility, kept outside the engine to preserve the
+ * decoupling from `packages/bookings`.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { CancelResult, SourceAdapterContext, SourceAdapterRequestScope } from "../adapter/contract.js";
+import type { SourceAdapterRegistry } from "./registry.js";
+export interface CancelEntityRequest {
+    bookingId: string;
+    entityModule: string;
+    entityId: string;
+    reason?: string;
+    scope?: SourceAdapterRequestScope;
+    idempotencyKey?: string;
+    adapterContext: SourceAdapterContext;
+}
+export interface CancelEntityResult {
+    status: CancelResult["status"];
+    refundAmount?: number;
+    refundCurrency?: string;
+    pendingChannel?: string;
+    /** The snapshot row's id — exposed for callers that want to log the cancel against it. */
+    snapshotId: string;
+}
+export interface CancelEntityDeps {
+    registry: SourceAdapterRegistry;
+}
+/**
+ * Cancel the given (booking, entity) pair. Throws `ORDER_NOT_FOUND` when
+ * no snapshot row matches. Otherwise dispatches to the registered
+ * adapter; if the adapter doesn't implement `cancel`, returns the
+ * adapter's refusal verbatim so the caller can surface it.
+ */
+export declare function cancelEntity(db: AnyDrizzleDb, deps: CancelEntityDeps, request: CancelEntityRequest): Promise<CancelEntityResult>;
+//# sourceMappingURL=cancel.d.ts.map

package/dist/booking-engine/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/booking-engine/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrD,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAA;AAO/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAE1D,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,yBAAyB,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,EAAE,oBAAoB,CAAA;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,qBAAqB,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B"}

package/dist/booking-engine/cancel.js

@@ -0,0 +1,56 @@
+/**
+ * `cancelEntity` — third step in the booking engine lifecycle.
+ *
+ * Looks up the snapshot row, dispatches `adapter.cancel`, returns the
+ * adapter's refund result. The snapshot stays — it's the audit record —
+ * and the booking row's lifecycle (set status to cancelled, etc.) is the
+ * caller's responsibility, kept outside the engine to preserve the
+ * decoupling from `packages/bookings`.
+ */
+import { and, eq } from "drizzle-orm";
+import { bookingCatalogSnapshotTable, } from "../snapshot/schema.js";
+import { BookingEngineError, ORDER_NOT_FOUND } from "./errors.js";
+/**
+ * Cancel the given (booking, entity) pair. Throws `ORDER_NOT_FOUND` when
+ * no snapshot row matches. Otherwise dispatches to the registered
+ * adapter; if the adapter doesn't implement `cancel`, returns the
+ * adapter's refusal verbatim so the caller can surface it.
+ */
+export async function cancelEntity(db, deps, request) {
+    const snapshot = await loadSnapshot(db, request.bookingId, request.entityModule, request.entityId);
+    const adapter = snapshot.source_connection_id
+        ? (deps.registry.resolveByConnection(snapshot.source_connection_id) ??
+            deps.registry.resolveOrThrow(snapshot.source_kind))
+        : deps.registry.resolveOrThrow(snapshot.source_kind);
+    if (!adapter.cancel) {
+        return {
+            status: "refused",
+            snapshotId: snapshot.id,
+        };
+    }
+    const result = await adapter.cancel(request.adapterContext, {
+        upstream_ref: snapshot.source_ref ?? snapshot.id,
+        reason: request.reason,
+        scope: request.scope,
+        idempotency_key: request.idempotencyKey,
+    });
+    return {
+        status: result.status,
+        refundAmount: result.refund_amount,
+        refundCurrency: result.refund_currency,
+        pendingChannel: result.pending_channel,
+        snapshotId: snapshot.id,
+    };
+}
+async function loadSnapshot(db, bookingId, entityModule, entityId) {
+    const rows = (await db
+        .select()
+        .from(bookingCatalogSnapshotTable)
+        .where(and(eq(bookingCatalogSnapshotTable.booking_id, bookingId), eq(bookingCatalogSnapshotTable.entity_module, entityModule), eq(bookingCatalogSnapshotTable.entity_id, entityId)))
+        .limit(1));
+    const snapshot = rows[0];
+    if (!snapshot) {
+        throw new BookingEngineError(ORDER_NOT_FOUND, `no snapshot row for booking=${bookingId} entity=${entityModule}:${entityId}`, { bookingId, entityModule, entityId });
+    }
+    return snapshot;
+}

package/dist/booking-engine/checkout-finalize.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `checkoutFinalize` workflow — runs on `payment.completed` for
+ * bookings created through the storefront's checkout-start path.
+ *
+ * Steps:
+ *   1. transition_to_confirmed — flip the booking from
+ *      `awaiting_payment` to `confirmed`, stamping `paidAt`. This
+ *      emits `booking.confirmed` which fans out to:
+ *        - legal's auto-generate-contract subscriber (if wired)
+ *        - finance's auto-generate-invoice subscriber (Phase 5)
+ *   2. issue_invoice — explicit fallback when finance auto-generation
+ *      isn't wired. Idempotent — checks if an invoice already exists.
+ *
+ * Compensation: if `issue_invoice` fails after the booking is
+ * already confirmed, we don't roll back to `awaiting_payment` — the
+ * payment was real and the booking is real. Instead the workflow
+ * leaves the booking in `confirmed` and rethrows so the workflow
+ * runs view surfaces the failed step for ops.
+ *
+ * This is a thin adapter on top of `createWorkflow` from
+ * `@voyant-travel/core/workflows` — no durability, no event-await; the
+ * caller subscribes to `payment.completed` and runs the workflow
+ * inline. Phase 6 of the storefront-checkout-flow plan elaborates
+ * with workflow-runs surfacing.
+ */
+import type { EventBus } from "@voyant-travel/core";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export interface CheckoutFinalizeInput {
+    bookingId: string;
+    /** Optional payment metadata for audit logging. */
+    paymentSessionId?: string;
+    paymentIntent?: "card" | "bank_transfer" | "hold" | "ticket_on_credit";
+}
+/**
+ * Optional step-lifecycle hooks the caller can wire to the
+ * `@voyant-travel/workflow-runs` recorder (or any other observability
+ * sink). Catalog stays neutral — it just emits the events.
+ */
+export interface CheckoutFinalizeStepRecorder {
+    startStep(name: string): Promise<void> | void;
+    completeStep(name: string, output?: Record<string, unknown> | null): Promise<void> | void;
+    failStep(name: string, error: unknown): Promise<void> | void;
+}
+export interface CheckoutFinalizeDeps {
+    db: PostgresJsDatabase;
+    eventBus?: EventBus;
+    /** Optional observability sink — see CheckoutFinalizeStepRecorder. */
+    recorder?: CheckoutFinalizeStepRecorder;
+    /**
+     * Confirms the booking — flips it from `awaiting_payment`/`on_hold`
+     * to `confirmed`. Implementations should emit `booking.confirmed`
+     * once the transaction commits so downstream subscribers fan out.
+     */
+    confirmBooking: (bookingId: string) => Promise<void>;
+    /**
+     * Issues the final invoice for the booking. When `convertedFromInvoiceId`
+     * is supplied (proforma → invoice path), implementations should
+     * preserve the linkage. Returning `null` is treated as "skipped"
+     * (e.g. invoice already issued) and not an error.
+     */
+    issueInvoice: (input: {
+        bookingId: string;
+        convertedFromInvoiceId?: string | null;
+    }) => Promise<{
+        invoiceId: string;
+    } | null>;
+    /**
+     * Look up an existing proforma for this booking so we can pass
+     * its id into `issueInvoice` (for the conversion linkage). Return
+     * `null` if there isn't one — the booking went through card or
+     * inquiry rather than bank-transfer.
+     */
+    findProformaForBooking?: (bookingId: string) => Promise<{
+        invoiceId: string;
+    } | null>;
+    /**
+     * Generate (or fetch existing) the contract PDF for the booking.
+     * The implementation is expected to be **idempotent** — if a
+     * contract document already exists for this booking, return its
+     * id without re-rendering. This keeps the explicit workflow step
+     * compatible with the legal package's `booking.confirmed`
+     * subscriber, which races with the step in storefront flows.
+     *
+     * Returning `null` is treated as "no contract template wired" and
+     * skipped silently — the operator may not have configured one,
+     * which is a deployment choice rather than a workflow failure.
+     *
+     * Optional: when omitted, the workflow skips this step entirely
+     * (operators that don't want explicit-step recording leave it
+     * unset and rely on the subscriber).
+     */
+    generateContractPdf?: (input: {
+        bookingId: string;
+    }) => Promise<{
+        contractId: string;
+        attachmentId: string;
+    } | null>;
+    /**
+     * Reconcile paid `payment_sessions` for the booking against the
+     * just-issued invoice: update each paid session's `invoice_id`
+     * pointer and write a `payments` row so the invoice flips to paid.
+     *
+     * The session was created at storefront-checkout time with
+     * `target_type: "booking"` and `invoice_id: NULL` because the
+     * invoice didn't exist yet. Without this back-link, the invoice
+     * permanently reads as unpaid even though the customer's money is
+     * sitting in the paid session.
+     *
+     * Idempotency: implementations should skip sessions that already
+     * have an `invoice_id` set or already have a `payment_id`. Returns
+     * the count of newly-linked sessions for observability.
+     */
+    linkPaymentToInvoice?: (input: {
+        bookingId: string;
+        invoiceId: string;
+        /** Hint from the workflow input — when set, prefer linking this session. */
+        paymentSessionId?: string;
+    }) => Promise<{
+        paymentId: string | null;
+        sessionsLinked: number;
+    }>;
+}
+export declare const checkoutFinalizeWorkflow: import("@voyant-travel/core").WorkflowDefinition;
+export interface RunCheckoutFinalizeOptions {
+    /**
+     * For resume runs — name of the step to resume from. Steps before
+     * this one are skipped and their outputs hydrated from
+     * {@link RunCheckoutFinalizeOptions.seedResults}.
+     */
+    skipUntil?: string;
+    /** Step outputs from the parent run, keyed by step name. */
+    seedResults?: Record<string, unknown>;
+}
+/**
+ * Run the workflow with deps seeded. Wraps `checkoutFinalizeWorkflow.run`
+ * with the dependency-injection plumbing — the workflow primitive
+ * doesn't carry a "deps" concept on its own, so we pass them through
+ * `ctx.results` keyed under `__deps`.
+ *
+ * Resume support: when `skipUntil` is set, the seeded `__deps` step
+ * is added to `seedResults` automatically so the resumed step still
+ * sees `ctx.results.__deps`. The caller doesn't need to know about
+ * the deps-injection mechanism.
+ */
+export declare function runCheckoutFinalize(input: CheckoutFinalizeInput, deps: CheckoutFinalizeDeps, options?: RunCheckoutFinalizeOptions): Promise<void>;
+//# sourceMappingURL=checkout-finalize.d.ts.map

package/dist/booking-engine/checkout-finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-finalize.d.ts","sourceRoot":"","sources":["../../src/booking-engine/checkout-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,GAAG,kBAAkB,CAAA;CACvE;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,kBAAkB,CAAA;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,4BAA4B,CAAA;IACvC;;;;OAIG;IACH,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD;;;;;OAKG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE;QACpB,SAAS,EAAE,MAAM,CAAA;QACjB,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACvC,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IAC3C;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IACrF;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC5B,SAAS,EAAE,MAAM,CAAA;KAClB,KAAK,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IAClE;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC7B,SAAS,EAAE,MAAM,CAAA;QACjB,SAAS,EAAE,MAAM,CAAA;QACjB,4EAA4E;QAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACpE;AAyBD,eAAO,MAAM,wBAAwB,kDAgEnC,CAAA;AAEF,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAuBf"}