@voyant-travel/catalog 0.117.2

package/dist/booking-engine/checkout-finalize.js

@@ -0,0 +1,132 @@
+/**
+ * `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 { createWorkflow, step } from "@voyant-travel/core/workflows";
+async function runStep(name, recorder, fn) {
+    await recorder?.startStep(name);
+    try {
+        const result = await fn();
+        await recorder?.completeStep(name, asRecord(result));
+        return result;
+    }
+    catch (err) {
+        await recorder?.failStep(name, err);
+        throw err;
+    }
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export const checkoutFinalizeWorkflow = createWorkflow("checkout-finalize", [
+    step("transition_to_confirmed").run(async (input, ctx) => {
+        const deps = ctx.results.__deps;
+        if (!deps)
+            throw new Error("checkout-finalize: deps not seeded into context");
+        await runStep("transition_to_confirmed", deps.recorder, () => deps.confirmBooking(input.bookingId));
+    }),
+    step("issue_invoice").run(async (input, ctx) => {
+        const deps = ctx.results.__deps;
+        if (!deps)
+            throw new Error("checkout-finalize: deps not seeded into context");
+        return runStep("issue_invoice", deps.recorder, async () => {
+            const proforma = deps.findProformaForBooking
+                ? await deps.findProformaForBooking(input.bookingId)
+                : null;
+            return deps.issueInvoice({
+                bookingId: input.bookingId,
+                convertedFromInvoiceId: proforma?.invoiceId ?? null,
+            });
+        });
+    }),
+    step("link_payment_to_invoice").run(async (input, ctx) => {
+        const deps = ctx.results.__deps;
+        if (!deps)
+            throw new Error("checkout-finalize: deps not seeded into context");
+        if (!deps.linkPaymentToInvoice)
+            return null;
+        const issueOutput = ctx.results.issue_invoice;
+        if (!issueOutput?.invoiceId) {
+            // Invoice generation was skipped (returned null) — there's
+            // nothing to link a payment to. Skip silently rather than
+            // throwing so the workflow continues for "hold"-only checkouts.
+            return null;
+        }
+        return runStep("link_payment_to_invoice", deps.recorder, () => deps.linkPaymentToInvoice({
+            bookingId: input.bookingId,
+            invoiceId: issueOutput.invoiceId,
+            paymentSessionId: input.paymentSessionId,
+        }));
+    }),
+    step("generate_contract_pdf").run(async (input, ctx) => {
+        const deps = ctx.results.__deps;
+        if (!deps)
+            throw new Error("checkout-finalize: deps not seeded into context");
+        // Optional step — when no generator is wired, the workflow
+        // proceeds without a contract document (some operators don't
+        // attach a customer-facing contract). Returning null also keeps
+        // the dashboard's step row, which is the point of having this
+        // as an explicit step rather than a fire-and-forget subscriber.
+        if (!deps.generateContractPdf)
+            return null;
+        return runStep("generate_contract_pdf", deps.recorder, () => deps.generateContractPdf({ bookingId: input.bookingId }));
+    }),
+]);
+/**
+ * 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 async function runCheckoutFinalize(input, deps, options = {}) {
+    // Seed deps into ctx.results before the first step runs by passing
+    // them as a synthetic step output. The step name MUST match the
+    // key the downstream steps read (`__deps`) — a previous spelling
+    // (`__seed_deps`) silently broke this because step outputs are
+    // keyed by name.
+    const seeded = createWorkflow("checkout-finalize", [
+        step("__deps").run(() => deps),
+        ...checkoutFinalizeWorkflow.steps,
+    ]);
+    // For resume: the synthetic "__deps" step would otherwise be
+    // skipped (and produce no value), starving downstream steps of
+    // their dependencies. Inject deps into seedResults so the skipped
+    // path still hydrates them.
+    const seedResults = options.skipUntil !== undefined
+        ? { ...(options.seedResults ?? {}), __deps: deps }
+        : options.seedResults;
+    await seeded.run({
+        input,
+        skipUntil: options.skipUntil,
+        seedResults,
+    });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * `BookingDraft` + V1 engine contract schemas now live in
+ * `@voyant-travel/catalog-contracts` so external consumers (Voyant Connect, adapter
+ * authors, the Admin SDK) can validate booking-engine payloads without the
+ * catalog runtime. Re-exported here to keep existing `@voyant-travel/catalog`
+ * import paths stable. See `docs/adr/0002-contract-packages.md`.
+ */
+export * from "@voyant-travel/catalog-contracts/booking-engine/contracts";
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/booking-engine/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,2DAA2D,CAAA"}

package/dist/booking-engine/contracts.js

@@ -0,0 +1,8 @@
+/**
+ * `BookingDraft` + V1 engine contract schemas now live in
+ * `@voyant-travel/catalog-contracts` so external consumers (Voyant Connect, adapter
+ * authors, the Admin SDK) can validate booking-engine payloads without the
+ * catalog runtime. Re-exported here to keep existing `@voyant-travel/catalog`
+ * import paths stable. See `docs/adr/0002-contract-packages.md`.
+ */
+export * from "@voyant-travel/catalog-contracts/booking-engine/contracts";

package/dist/booking-engine/contracts.test.d.ts

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

package/dist/booking-engine/contracts.test.d.ts.map

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

package/dist/booking-engine/contracts.test.js

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { bookingDraftV1, bookRequestV1, pricingBreakdownV1, quoteRequestV1, quoteResponseV1, } from "./contracts.js";
+describe("V1 contracts", () => {
+    describe("bookingDraftV1", () => {
+        it("accepts a minimal draft and applies defaults", () => {
+            const result = bookingDraftV1.parse({
+                entity: { module: "products", id: "prod_1", sourceKind: "owned" },
+            });
+            expect(result.configure.pax).toEqual({});
+            expect(result.billing.buyerType).toBe("B2C");
+            expect(result.payment.intent).toBe("hold");
+            expect(result.travelers).toEqual([]);
+            expect(result.addons).toEqual([]);
+        });
+        it("preserves explicit field values", () => {
+            const result = bookingDraftV1.parse({
+                entity: { module: "products", id: "prod_1", sourceKind: "owned" },
+                configure: {
+                    pax: { adult: 2 },
+                    roomTypeId: "HOTEL:DZL1",
+                    ratePlanId: "HOTEL:DZL1:BB",
+                    board: "BB",
+                },
+                billing: {
+                    buyerType: "B2B",
+                    contact: { firstName: "Mihai", lastName: "U", email: "a@b.com" },
+                    address: { country: "RO" },
+                    company: { name: "Voyant" },
+                },
+            });
+            expect(result.configure.pax.adult).toBe(2);
+            expect(result.configure.roomTypeId).toBe("HOTEL:DZL1");
+            expect(result.configure.ratePlanId).toBe("HOTEL:DZL1:BB");
+            expect(result.configure.board).toBe("BB");
+            expect(result.billing.buyerType).toBe("B2B");
+            expect(result.billing.address.country).toBe("RO");
+            expect(result.billing.company?.name).toBe("Voyant");
+        });
+        it("rejects malformed entity reference", () => {
+            const result = bookingDraftV1.safeParse({});
+            expect(result.success).toBe(false);
+        });
+    });
+    describe("quoteRequestV1", () => {
+        it("validates a request without a draft", () => {
+            const result = quoteRequestV1.safeParse({
+                entityModule: "products",
+                entityId: "prod_1",
+                sourceKind: "owned",
+                scope: { locale: "en-GB", audience: "staff", market: "default" },
+            });
+            expect(result.success).toBe(true);
+        });
+        it("requires audience to be one of the recognized actors", () => {
+            const result = quoteRequestV1.safeParse({
+                entityModule: "products",
+                entityId: "prod_1",
+                sourceKind: "owned",
+                scope: { locale: "en-GB", audience: "robot", market: "default" },
+            });
+            expect(result.success).toBe(false);
+        });
+    });
+    describe("bookRequestV1", () => {
+        it("requires either quoteId or draftId", () => {
+            expect(bookRequestV1.safeParse({}).success).toBe(false);
+            expect(bookRequestV1.safeParse({ quoteId: "q1" }).success).toBe(true);
+            expect(bookRequestV1.safeParse({ draftId: "d1" }).success).toBe(true);
+        });
+        it("rejects too-short idempotency keys", () => {
+            const result = bookRequestV1.safeParse({ quoteId: "q1", idempotencyKey: "abc" });
+            expect(result.success).toBe(false);
+        });
+        it("accepts idempotency keys in the 8–128 range", () => {
+            expect(bookRequestV1.safeParse({ quoteId: "q1", idempotencyKey: "12345678" }).success).toBe(true);
+            expect(bookRequestV1.safeParse({ quoteId: "q1", idempotencyKey: "x".repeat(128) }).success).toBe(true);
+            expect(bookRequestV1.safeParse({ quoteId: "q1", idempotencyKey: "x".repeat(129) }).success).toBe(false);
+        });
+    });
+    describe("pricingBreakdownV1", () => {
+        it("validates a populated breakdown", () => {
+            const result = pricingBreakdownV1.safeParse({
+                currency: "EUR",
+                lines: [{ kind: "base", label: "Base", quantity: 2, unitAmount: 5000, totalAmount: 10000 }],
+                taxes: [{ code: "vat", label: "VAT", rate: 0.19, amount: 1900, base: 10000 }],
+                subtotal: 10000,
+                taxTotal: 1900,
+                total: 11900,
+            });
+            expect(result.success).toBe(true);
+        });
+        it("rejects bad currency length", () => {
+            const result = pricingBreakdownV1.safeParse({
+                currency: "EURO",
+                lines: [],
+                taxes: [],
+                subtotal: 0,
+                taxTotal: 0,
+                total: 0,
+            });
+            expect(result.success).toBe(false);
+        });
+    });
+    describe("quoteResponseV1", () => {
+        it("validates a minimal availability=false response", () => {
+            const result = quoteResponseV1.safeParse({
+                quoteId: "q1",
+                quotedAt: new Date().toISOString(),
+                expiresAt: new Date(Date.now() + 60_000).toISOString(),
+                available: false,
+                invalidReason: "out_of_stock",
+            });
+            expect(result.success).toBe(true);
+        });
+    });
+});

package/dist/booking-engine/draft-shape.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `BookingDraftShape` + the shared draft-shape defaults now live in
+ * `@voyant-travel/catalog-contracts` so client packages (bookings-react,
+ * catalog-react) and adapter authors can consume the journey descriptor
+ * without the catalog runtime. Re-exported here to keep existing
+ * `@voyant-travel/catalog` import paths stable. See
+ * `docs/adr/0002-contract-packages.md`.
+ */
+export * from "@voyant-travel/catalog-contracts/booking-engine/draft-shape";
+//# sourceMappingURL=draft-shape.d.ts.map

package/dist/booking-engine/draft-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-shape.d.ts","sourceRoot":"","sources":["../../src/booking-engine/draft-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,6DAA6D,CAAA"}

package/dist/booking-engine/draft-shape.js

@@ -0,0 +1,9 @@
+/**
+ * `BookingDraftShape` + the shared draft-shape defaults now live in
+ * `@voyant-travel/catalog-contracts` so client packages (bookings-react,
+ * catalog-react) and adapter authors can consume the journey descriptor
+ * without the catalog runtime. Re-exported here to keep existing
+ * `@voyant-travel/catalog` import paths stable. See
+ * `docs/adr/0002-contract-packages.md`.
+ */
+export * from "@voyant-travel/catalog-contracts/booking-engine/draft-shape";

package/dist/booking-engine/draft-shape.test.d.ts

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

package/dist/booking-engine/draft-shape.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-shape.test.d.ts","sourceRoot":"","sources":["../../src/booking-engine/draft-shape.test.ts"],"names":[],"mappings":""}

package/dist/booking-engine/draft-shape.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_PAX_BANDS, DEFAULT_PAX_TOTAL, defaultBookingFields, defaultDraftShapeFlags, defaultTravelerFields, paxBandsAllowedTotalFrom, } from "./draft-shape.js";
+describe("defaultDraftShapeFlags", () => {
+    it("returns the canonical flag set: configure + billing + travelers + payment + review on, accommodation + addons off", () => {
+        const flags = defaultDraftShapeFlags();
+        expect(flags.showsConfigure).toBe(true);
+        expect(flags.showsBilling).toBe(true);
+        expect(flags.showsTravelers).toBe(true);
+        expect(flags.showsAccommodation).toBe(false);
+        expect(flags.showsAddons).toBe(false);
+        expect(flags.showsPayment).toBe(true);
+        expect(flags.showsReview).toBe(true);
+    });
+    it("returns a fresh object on each call (no shared mutation)", () => {
+        const a = defaultDraftShapeFlags();
+        const b = defaultDraftShapeFlags();
+        expect(a).not.toBe(b);
+    });
+});
+describe("paxBandsAllowedTotalFrom", () => {
+    it("sums minCount and maxCount across bands", () => {
+        expect(paxBandsAllowedTotalFrom([
+            { code: "adult", label: "Adult", minCount: 1, maxCount: 8 },
+            { code: "child", label: "Child", minCount: 0, maxCount: 4 },
+        ])).toEqual({ min: 1, max: 12 });
+    });
+    it("returns 0/0 for an empty list", () => {
+        expect(paxBandsAllowedTotalFrom([])).toEqual({ min: 0, max: 0 });
+    });
+    it("handles the default multi-band list", () => {
+        expect(paxBandsAllowedTotalFrom(DEFAULT_PAX_BANDS)).toEqual({ min: 1, max: 18 });
+    });
+});
+describe("DEFAULT_PAX_BANDS / DEFAULT_PAX_TOTAL constants", () => {
+    it("DEFAULT_PAX_BANDS covers adults, children, and infants", () => {
+        expect(DEFAULT_PAX_BANDS).toEqual([
+            { code: "adult", label: "Adult", minAge: 12, minCount: 1, maxCount: 8 },
+            { code: "child", label: "Child", minAge: 2, maxAge: 11, minCount: 0, maxCount: 6 },
+            { code: "infant", label: "Infant", maxAge: 1, minCount: 0, maxCount: 4 },
+        ]);
+    });
+    it("DEFAULT_PAX_TOTAL is 1-8", () => {
+        expect(DEFAULT_PAX_TOTAL).toEqual({ min: 1, max: 8 });
+    });
+});
+describe("default field requirement sets", () => {
+    it("defaultTravelerFields includes identity, contact, and document fields", () => {
+        const fields = defaultTravelerFields();
+        expect(fields.map((f) => f.key)).toEqual([
+            "firstName",
+            "lastName",
+            "email",
+            "phone",
+            "dateOfBirth",
+            "documentType",
+            "documentNumber",
+            "documentExpiry",
+        ]);
+        expect(fields.find((f) => f.key === "firstName")?.required).toBe(true);
+        expect(fields.find((f) => f.key === "email")?.required).toBe(false);
+    });
+    it("defaultBookingFields covers buyerType + address basics", () => {
+        const fields = defaultBookingFields();
+        const keys = fields.map((f) => f.key);
+        expect(keys).toContain("buyerType");
+        expect(keys).toContain("address.line1");
+        expect(keys).toContain("address.city");
+        expect(keys).toContain("address.country");
+    });
+    it("defaultBookingFields buckets fields into the billing group", () => {
+        const fields = defaultBookingFields();
+        expect(fields.every((f) => f.group === "billing")).toBe(true);
+    });
+});