@voyant-travel/inventory 0.1.0

package/dist/booking-engine/handler.js

@@ -0,0 +1,398 @@
+/**
+ * Owned-arm booking handler for the `products` vertical.
+ * agent-quality: file-size exception -- Product booking handler keeps quote, commit, cancel, and status behavior together until booking-engine handlers are split by operation.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6 +
+ * §10 Phase A. Composes:
+ *
+ *   - The products vertical's existing pricing primitives
+ *     (`products.sellAmountCents` / `sellCurrency`) for pricing
+ *     basis. Per-pax / per-band pricing layered in Phase C+ via
+ *     `product_pax_pricing_tiers`.
+ *   - `getProductContent` + `buildProductDraftShape` for the journey
+ *     wizard's step descriptor.
+ *   - An injected `createBooking` function for the commit path
+ *     — keeps the Inventory-owned Product handler from depending on
+ *     `@voyant-travel/finance` (no workspace cycle).
+ *
+ * Phase A scope (deliberately narrow):
+ *   - Price = product.sellAmountCents × pax_count, no taxes / addons /
+ *     accommodation / vouchers.
+ *   - Commit goes through the bridge into `bookingsCreate`'s input
+ *     shape — products-only, no extras / accommodations / cruises / encrypted
+ *     travel details / snapshot graph.
+ *
+ * Phase C+ extensions land on this same handler without re-architecting
+ * the dispatch.
+ */
+import { DEFAULT_PAX_BANDS, defaultBookingFields, defaultDraftShapeFlags, defaultTravelerFields, paxBandsAllowedTotalFrom, } from "@voyant-travel/catalog/booking-engine";
+import { applyAddonSelections, bookingExtraLinesFromAddonSelections, bookingItemLinesFromOptionSelections, defaultBookingNumber, extractBillingParty, extractInternalNotes, extractPartyTravelers, extractTaxLines, loadProduct, normalizeOptionSelections, priceOptionSelections, priceQuote, readInitialStatus, resolveSellAmountCentsOverride, sumPax, } from "./handler-support.js";
+export function buildOwnedProductDraftShape(options = {}) {
+    // Use the product's configured traveler types when supplied; otherwise
+    // the generic adult/child/infant defaults.
+    const paxBands = options.paxBands && options.paxBands.length > 0 ? options.paxBands : DEFAULT_PAX_BANDS;
+    const fields = options.travelerFields ?? defaultTravelerFields();
+    const addons = options.addonCatalog ?? [];
+    const variants = options.productOptions ?? [];
+    const flags = defaultDraftShapeFlags();
+    // Room/vehicle-style products sell inventory units (rooms) the operator
+    // must pick a quantity of; person-only products price by pax band alone.
+    const hasInventoryUnits = variants.some((variant) => variant.units?.some((unit) => unit.unitType === "room" || unit.unitType === "vehicle"));
+    return {
+        ...flags,
+        showsAddons: addons.length > 0,
+        paxBands,
+        paxBandsAllowedTotal: paxBandsAllowedTotalFrom(paxBands),
+        ...(options.paxBandDependencies && options.paxBandDependencies.length > 0
+            ? { paxBandDependencies: options.paxBandDependencies }
+            : {}),
+        travelerFields: fields,
+        bookingFields: defaultBookingFields(),
+        paymentIntents: ["hold", "card"],
+        configureSubSteps: [
+            ...(variants.length > 0 ? [{ kind: "product-option", options: variants }] : []),
+            // Owned products are scheduled — the operator picks a real departure.
+            // The journey renders an injected slot picker for this kind, falling
+            // back to a free date when the product has no scheduled departures.
+            { kind: "departure", required: true },
+            // Inventory products: the operator picks room/unit quantities for the
+            // chosen option + departure. The journey renders an injected units
+            // picker that writes `configure.optionSelections`.
+            ...(hasInventoryUnits ? [{ kind: "option-units" }] : []),
+            { kind: "occupancy", bands: paxBands },
+        ],
+        addons: addons.length > 0 ? { catalog: addons } : undefined,
+    };
+}
+/**
+ * Run an optional enrichment loader so a single failure (a missing
+ * migration, a flaky query) never rejects the quote. The journey
+ * descriptor — steps, pax bands, options, extras, units — must always
+ * render; a broken enrichment source degrades to `undefined`, not a
+ * collapsed booking shape. Logs the cause for diagnosis.
+ */
+async function safeLoad(label, promise) {
+    if (!promise)
+        return undefined;
+    try {
+        return await promise;
+    }
+    catch (error) {
+        console.warn(`[products/booking-engine] ${label} failed; continuing without it`, error);
+        return undefined;
+    }
+}
+export function createProductsBookingHandler(options) {
+    const generateNumber = options.generateBookingNumber ?? defaultBookingNumber;
+    return {
+        entityModule: "products",
+        async computeQuote(ctx, request) {
+            const product = await loadProduct(ctx.db, request.entityId);
+            if (!product) {
+                return { available: false, invalidReason: "product_not_found" };
+            }
+            if (product.status !== "active" && product.status !== "draft") {
+                return {
+                    available: false,
+                    invalidReason: `product_status_${product.status}`,
+                };
+            }
+            const draft = (request.draft ?? {});
+            const optionId = draft.configure?.variantId;
+            const optionSelections = normalizeOptionSelections(draft.configure?.optionSelections);
+            const slotId = draft.configure?.departureSlotId;
+            // Concurrent enrichment + slot-date lookup. The slot date is
+            // needed before we can call loadResolvedOptionPrice, so it
+            // joins this batch.
+            const [travelerFields, addonCatalog, productOptionCatalog, paxBands, paxBandDependencies, taxRate, slotDate,] = await Promise.all([
+                safeLoad("loadTravelerFields", options.loadTravelerFields?.(ctx, request.entityId)),
+                safeLoad("loadAddonCatalog", options.loadAddonCatalog?.(ctx, request.entityId)),
+                safeLoad("loadProductOptions", options.loadProductOptions?.(ctx, request.entityId)),
+                safeLoad("loadPaxBands", options.loadPaxBands?.(ctx, request.entityId)),
+                safeLoad("loadPaxBandDependencies", options.loadPaxBandDependencies?.(ctx, request.entityId)),
+                safeLoad("loadTaxRate", options.loadTaxRate?.(ctx, {
+                    productId: request.entityId,
+                    buyerCountry: draft.billing?.address?.country,
+                    buyerType: draft.billing?.buyerType,
+                })),
+                slotId && options.loadSlotDate
+                    ? safeLoad("loadSlotDate", options.loadSlotDate(ctx, slotId)).then((date) => date ?? draft.configure?.departureDate ?? null)
+                    : Promise.resolve(draft.configure?.departureDate ?? null),
+            ]);
+            // The journey descriptor never depends on pricing — build it
+            // unconditionally so the wizard always renders the right steps,
+            // bands, options, extras and units. Pricing is best-effort: a
+            // failure here returns the shape with no price rather than 500ing
+            // the quote (which would collapse the shape to the bare default).
+            const shape = buildOwnedProductDraftShape({
+                travelerFields,
+                addonCatalog,
+                productOptions: productOptionCatalog,
+                paxBands,
+                paxBandDependencies,
+            });
+            let available = false;
+            let pricing;
+            try {
+                const resolvedPrice = optionSelections.length === 0 && optionId && slotDate && options.loadResolvedOptionPrice
+                    ? await options.loadResolvedOptionPrice(ctx, {
+                        productId: request.entityId,
+                        optionId,
+                        date: slotDate,
+                    })
+                    : null;
+                const paxCount = sumPax(draft.configure?.pax);
+                // Per-pax pricing fallback: when no pax is supplied yet, quote a
+                // single-occupant baseline so the wizard can render a starter
+                // total before the user picks counts.
+                const effectivePax = paxCount > 0 ? paxCount : 1;
+                const priced = optionSelections.length > 0
+                    ? await priceOptionSelections({
+                        ctx,
+                        options,
+                        product,
+                        productOptions: productOptionCatalog ?? [],
+                        selections: optionSelections,
+                        slotDate,
+                    })
+                    : priceQuote({
+                        product,
+                        resolvedPrice,
+                        pax: draft.configure?.pax,
+                        effectivePax,
+                    });
+                const pricedWithAddons = applyAddonSelections({
+                    priced,
+                    addons: draft.addons,
+                    addonCatalog: addonCatalog ?? [],
+                    effectivePax,
+                });
+                // Tax computation. The base is taxable; addons/accommodation
+                // get the same rate in this MVP cut. Per-line override (the
+                // `applies_to` axis on tax_classes.lines) lands in a follow-up
+                // when the catalog actually carries mixed treatments.
+                const taxIsInclusive = taxRate?.priceMode === "inclusive";
+                const grossCents = pricedWithAddons.totalCents;
+                const taxCents = taxRate && taxRate.rate > 0
+                    ? taxIsInclusive
+                        ? Math.round(grossCents - grossCents / (1 + taxRate.rate))
+                        : Math.round(grossCents * taxRate.rate)
+                    : 0;
+                const netCents = taxIsInclusive ? grossCents - taxCents : grossCents;
+                const payableCents = taxIsInclusive ? grossCents : netCents + taxCents;
+                available = grossCents > 0;
+                pricing = available
+                    ? {
+                        base_amount: netCents,
+                        taxes: taxCents,
+                        fees: 0,
+                        surcharges: 0,
+                        currency: product.sellCurrency,
+                        breakdown: {
+                            // `currency` is required for the API serializer to use this
+                            // itemized breakdown instead of synthesizing a single "Base"
+                            // line from base_amount.
+                            currency: product.sellCurrency,
+                            lines: pricedWithAddons.lines.map((line) => ({
+                                ...line,
+                                taxIncluded: taxIsInclusive,
+                            })),
+                            taxes: taxRate && taxCents > 0
+                                ? [
+                                    {
+                                        code: taxRate.code,
+                                        label: taxRate.label,
+                                        rate: taxRate.rate,
+                                        amount: taxCents,
+                                        base: netCents,
+                                        includedInPrice: taxIsInclusive,
+                                        scope: taxIsInclusive ? "included" : "excluded",
+                                    },
+                                ]
+                                : [],
+                            subtotal: netCents,
+                            taxTotal: taxCents,
+                            total: payableCents,
+                            paxCount: effectivePax,
+                        },
+                    }
+                    : undefined;
+            }
+            catch (error) {
+                console.warn("[products/booking-engine] pricing failed; returning shape without a price", error);
+                available = false;
+                pricing = undefined;
+            }
+            return {
+                available,
+                invalidReason: available ? undefined : "no_sell_amount_configured",
+                pricing,
+                shape,
+            };
+        },
+        /**
+         * Place a soft hold on the row's chosen slot. When the
+         * `holds` bridge is wired, decrements
+         * `availability_slots.remainingPax` against the slot for the
+         * pax count; concurrent placeHold attempts are serialized via
+         * a row-level lock inside the bridge. When omitted, returns a
+         * stamping token without touching inventory.
+         *
+         * The slot id and pax count are pulled off
+         * `request.parameters.slotId` / `request.parameters.paxCount`
+         * — the journey wizard threads these from the draft's
+         * Configure step (`departureSlotId` + summed `pax`).
+         */
+        async placeHold(_ctx, request) {
+            const token = request.draftId ?? defaultBookingNumber();
+            const expiresAt = new Date(Date.now() + request.ttlMs);
+            if (!options.holds) {
+                return { holdToken: token, expiresAt };
+            }
+            const params = (request.parameters ?? {});
+            const slotId = params.slotId;
+            const paxCount = params.paxCount ?? 1;
+            if (!slotId || !request.draftId) {
+                // No slot chosen yet → no inventory to lock. Return a
+                // stamping token so the journey can still call extend /
+                // release.
+                return { holdToken: token, expiresAt };
+            }
+            const result = await options.holds.place({
+                draftId: request.draftId,
+                productId: params.productId ?? request.entityId,
+                slotId,
+                paxCount,
+                ttlMs: request.ttlMs,
+                holdToken: token,
+            });
+            if (result.status === "ok") {
+                return { holdToken: result.holdToken, expiresAt: result.expiresAt };
+            }
+            // Capacity / lookup failures fall back to a stamping token
+            // — the journey commit will revalidate via the engine's
+            // re-quote and reject if capacity has dried up.
+            return { holdToken: token, expiresAt };
+        },
+        async extendHold(_ctx, holdToken, request) {
+            const ttlMs = request?.ttlMs ?? 30 * 60 * 1000;
+            if (options.holds) {
+                const result = await options.holds.extend({ holdToken, ttlMs });
+                if (result.status === "ok") {
+                    return { holdToken, expiresAt: result.expiresAt };
+                }
+            }
+            return { holdToken, expiresAt: new Date(Date.now() + ttlMs) };
+        },
+        async releaseHold(_ctx, holdToken) {
+            if (options.holds) {
+                await options.holds.release(holdToken);
+            }
+        },
+        async commit(ctx, request) {
+            const draft = (request.draft ?? {});
+            // Defensive product load — the bridge will fail with
+            // `product_not_found` anyway, but a clean early-return keeps the
+            // commit path's error envelope predictable.
+            const product = await loadProduct(ctx.db, request.entityId);
+            if (!product) {
+                return {
+                    status: "failed",
+                    orderRef: "",
+                    upstreamPayload: { reason: "product_not_found" },
+                };
+            }
+            const partyBilling = extractBillingParty(request.party);
+            const partyTravelers = extractPartyTravelers(request.party);
+            const travelers = (draft.travelers ?? []).map((t, index) => ({
+                firstName: t.firstName,
+                lastName: t.lastName,
+                email: t.email,
+                phone: t.phone,
+                personId: partyTravelers[index]?.personId ?? null,
+                participantType: "traveler",
+                travelerCategory: t.band === "child" || t.band === "infant"
+                    ? t.band
+                    : "adult",
+            }));
+            // Promotion-discounted quotes: thread the discounted customer-
+            // facing amount into the booking's seed sellAmountCents so
+            // checkout / payment see the quoted amount, not the product list
+            // price. Inclusive-tax quotes rewrite `base_amount` to net
+            // subtotal during tax recompute, so derive the override from the
+            // gross breakdown total when an included tax line is present.
+            const sellAmountCentsOverride = resolveSellAmountCentsOverride(request.pricing);
+            const optionSelections = normalizeOptionSelections(draft.configure?.optionSelections);
+            const selectedOptionIds = [
+                ...new Set(optionSelections.map((selection) => selection.optionId)),
+            ];
+            const primaryOptionId = selectedOptionIds.length === 1
+                ? selectedOptionIds[0]
+                : optionSelections.length === 0
+                    ? (draft.configure?.variantId ?? null)
+                    : null;
+            const bridge = await options.createBooking({
+                productId: product.id,
+                optionId: primaryOptionId,
+                // Link the departure so the booking item carries availability_slot_id
+                // (powers the duplicate-departure check + slot-level reporting).
+                slotId: draft.configure?.departureSlotId ?? null,
+                bookingNumber: generateNumber(),
+                personId: partyBilling.personId,
+                organizationId: partyBilling.organizationId,
+                contactFirstName: partyBilling.contactFirstName,
+                contactLastName: partyBilling.contactLastName,
+                contactEmail: partyBilling.contactEmail,
+                contactPhone: partyBilling.contactPhone,
+                internalNotes: extractInternalNotes(request.party),
+                travelers: travelers.length > 0 ? travelers : undefined,
+                paymentSchedules: draft.paymentSchedules,
+                documentGeneration: draft.documentGeneration
+                    ? {
+                        contractDocument: draft.documentGeneration.contractDocument === true,
+                        invoiceDocument: draft.documentGeneration.invoiceDocument === true,
+                        invoiceType: draft.documentGeneration.invoiceType === "proforma" ? "proforma" : "invoice",
+                    }
+                    : undefined,
+                suppressNotifications: draft.suppressNotifications,
+                sellAmountCentsOverride,
+                // Manual operator override: `confirmedSellAmountCents` wins over the
+                // quote/promotion price; the quote total is the `catalog` baseline so
+                // booking-create's override audit + required-reason check fire correctly.
+                ...(draft.priceOverride
+                    ? {
+                        catalogSellAmountCents: sellAmountCentsOverride ?? null,
+                        confirmedSellAmountCents: draft.priceOverride.amountCents,
+                        priceOverrideReason: draft.priceOverride.reason.trim() || null,
+                    }
+                    : {}),
+                // Operator-applied gift / refund-credit voucher. booking-create
+                // redeems it atomically and re-checks status / expiry / balance.
+                voucherRedemption: draft.voucherRedemption,
+                taxLines: extractTaxLines(request.pricing),
+                itemLines: bookingItemLinesFromOptionSelections(optionSelections),
+                extraLines: bookingExtraLinesFromAddonSelections({
+                    addons: draft.addons,
+                    addonCatalog: await options.loadAddonCatalog?.(ctx, product.id),
+                    currency: product.sellCurrency,
+                    quantityMultiplier: Math.max(1, travelers.length || 1),
+                }),
+                initialStatus: readInitialStatus(request.parameters),
+            });
+            if (bridge.status !== "ok" || !bridge.bookingId) {
+                return {
+                    status: "failed",
+                    orderRef: "",
+                    upstreamPayload: { bridge },
+                };
+            }
+            return {
+                status: "held",
+                bookingId: bridge.bookingId,
+                orderRef: bridge.bookingNumber ?? bridge.bookingId,
+                pricing: request.pricing,
+                upstreamPayload: { bridgeBookingId: bridge.bookingId },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * `@voyant-travel/inventory/booking-engine` — owned-arm booking handler
+ * for the Product vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6.
+ */
+export { type AvailabilityHoldBridge, type BookingCreateBridge, type BookingCreateBridgeInput, type BookingCreateBridgeResult, buildOwnedProductDraftShape, type CreateProductsBookingHandlerOptions, createProductsBookingHandler, } from "./handler.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/booking-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,2BAA2B,EAC3B,KAAK,mCAAmC,EACxC,4BAA4B,GAC7B,MAAM,cAAc,CAAA"}

package/dist/booking-engine/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@voyant-travel/inventory/booking-engine` — owned-arm booking handler
+ * for the Product vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6.
+ */
+export { buildOwnedProductDraftShape, createProductsBookingHandler, } from "./handler.js";

package/dist/booking-engine.d.ts

@@ -0,0 +1,2 @@
+export * from "./booking-engine/index.js";
+//# sourceMappingURL=booking-engine.d.ts.map

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

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

package/dist/booking-engine.js

@@ -0,0 +1 @@
+export * from "./booking-engine/index.js";