@voyant-travel/catalog 0.117.2

package/dist/adapter/schemas.test.js

@@ -0,0 +1,344 @@
+import { describe, expect, it } from "vitest";
+import { adapterCapabilitiesSchema, cancelRequestSchema, cancelResultSchema, catalogProjectionSchema, connectionStateSchema, discoveryCursorSchema, discoveryPageSchema, getContentRequestSchema, getContentResultSchema, getReservationRequestSchema, getReservationResultSchema, listReservationsPageSchema, listReservationsQuerySchema, liveResolveRequestSchema, liveResolveResultSchema, provenanceSchema, pushAvailabilityRequestSchema, pushAvailabilityResultSchema, pushBookingRequestSchema, pushBookingResultSchema, pushContentRequestSchema, pushContentResultSchema, reservationStatusSchema, reserveRequestSchema, reserveResultSchema, sourceAdapterContextSchema, sourceAdapterRequestScopeSchema, sourceAdapterSchema, } from "./schemas.js";
+const typeChecks = [
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+    true,
+];
+void typeChecks;
+const capabilities = {
+    verticals: ["products"],
+    supportsLiveResolution: true,
+    supportsDriftDetection: true,
+    supportsBookingForwarding: true,
+    supportsReservationRetrieval: true,
+    supportsSyncCancellation: false,
+    postBookOperations: ["cancel", "status"],
+    cacheTtlSeconds: 300,
+    supportsContentFetch: true,
+    supportedContentLocales: ["en-GB", "ro-RO"],
+    ownsContentCache: true,
+    ownsAvailabilityCache: false,
+    holdReleaseGraceMs: 1000,
+    supportsBookingPush: true,
+    supportsAvailabilityPush: true,
+    supportsContentPush: true,
+    providerCapabilities: [
+        {
+            capability: "category_availability_counts",
+            support: "supported",
+            applies_to: ["cruises"],
+            evidence: "category inventory feed",
+        },
+        {
+            capability: "physical_inventory_units",
+            support: "unsupported",
+            applies_to: ["cruises"],
+            reason: "provider feed exposes category counts but not cabin numbers",
+        },
+    ],
+};
+const context = {
+    connection_id: "conn_123",
+    credentials: { apiKey: "secret" },
+    tenant_id: "tenant_1",
+    correlation_id: "corr_1",
+};
+const provenance = {
+    source_kind: "direct:tui",
+    source_provider: "tui",
+    source_connection_id: "conn_123",
+    source_ref: "TUI-123",
+    source_freshness: "sync",
+    last_sourced_at: new Date("2026-01-01T00:00:00Z"),
+};
+const projection = {
+    entity_module: "products",
+    entity_id: "prod_123",
+    provenance,
+    fields: { title: "Sample tour", country: "RO" },
+};
+const discoveryPage = {
+    projections: [projection],
+    next_cursor: "cursor_2",
+};
+const liveResolveRequest = {
+    ids: ["prod_123"],
+    scope: {
+        locale: "en-GB",
+        audience: "customer",
+        market: "GB",
+        currency: "GBP",
+    },
+    parameters: { departureId: "dep_1" },
+};
+const sourceAdapterRequestScope = liveResolveRequest.scope;
+const liveResolveResult = {
+    values: {
+        prod_123: {
+            price: { amount: "100.00", currency: "GBP" },
+            remainingPax: 4,
+        },
+    },
+    failed: { prod_missing: "not_found" },
+};
+const getContentRequest = {
+    entity_module: "products",
+    entity_id: "prod_123",
+    locale: "ro-RO",
+    market: "RO",
+    currency: "RON",
+};
+const getContentResult = {
+    entity_module: "products",
+    entity_id: "prod_123",
+    source_ref: "TUI-123",
+    returned_locale: "en-GB",
+    machine_translated: false,
+    content: { product: { title: "Sample tour" } },
+    content_schema_version: "products/v1",
+    source_updated_at: new Date("2026-01-02T00:00:00Z"),
+    fresh_until: new Date("2026-01-03T00:00:00Z"),
+    etag: "etag-1",
+};
+const reserveRequest = {
+    entity_module: "products",
+    entity_id: "prod_123",
+    parameters: { departureId: "dep_1" },
+    party: { travelers: 2 },
+    payment_intent: { type: "hold" },
+    scope: sourceAdapterRequestScope,
+    idempotency_key: "reserve_123",
+};
+const reserveResult = {
+    upstream_ref: "booking_123",
+    status: "held",
+    upstream_payload: { holdToken: "hold_1" },
+};
+const cancelRequest = {
+    upstream_ref: "booking_123",
+    reason: "customer_request",
+    scope: sourceAdapterRequestScope,
+    idempotency_key: "cancel_123",
+};
+const cancelResult = {
+    status: "pending",
+    pending_channel: "partner portal",
+};
+const getReservationRequest = {
+    upstream_ref: "booking_123",
+    scope: sourceAdapterRequestScope,
+};
+const getReservationResult = {
+    upstream_ref: "booking_123",
+    status: "confirmed",
+    source_updated_at: new Date("2026-01-04T00:00:00Z"),
+    upstream_payload: { travelers: 2, supplierStatus: "OK" },
+};
+const listReservationsQuery = {
+    cursor: "cursor_1",
+    limit: 50,
+    status: ["held", "confirmed", "cancelling"],
+    updated_after: new Date("2026-01-01T00:00:00Z"),
+    scope: sourceAdapterRequestScope,
+};
+const listReservationsPage = {
+    reservations: [getReservationResult],
+    next_cursor: "cursor_2",
+};
+const pushBookingRequest = {
+    idempotencyKey: "idem_1",
+    bookingId: "book_1",
+    bookingItemId: "item_1",
+    externalProductId: "EXT-1",
+    externalRateId: "RATE-1",
+    externalCategoryId: "CAT-1",
+    channelId: "channel_1",
+    contractPolicy: { commission: 0.1 },
+    payload: { travelers: 2 },
+};
+const pushBookingResult = {
+    upstreamRef: "upstream_1",
+    externalReference: "CONF-1",
+    externalStatus: "confirmed",
+    upstreamPayload: { ok: true },
+};
+const pushAvailabilityRequest = {
+    channelId: "channel_1",
+    externalProductId: "EXT-1",
+    externalRateId: "RATE-1",
+    externalCategoryId: "CAT-1",
+    slotId: "slot_1",
+    productId: "prod_123",
+    optionId: "opt_1",
+    startsAt: new Date("2026-02-01T10:00:00Z"),
+    remainingPax: 8,
+    source: "booking",
+};
+const pushAvailabilityResult = {
+    externalStatus: "updated",
+    upstreamPayload: { ok: true },
+};
+const pushContentRequest = {
+    channelId: "channel_1",
+    externalProductId: "EXT-1",
+    productId: "prod_123",
+    contentHash: "hash_123",
+    content: { product: { title: "Sample tour" } },
+    contentSchemaVersion: "products/v1",
+    locale: "en-GB",
+};
+const pushContentResult = {
+    externalStatus: "updated",
+    upstreamPayload: { ok: true },
+    acknowledgedHash: "hash_123",
+};
+const sourceAdapter = {
+    kind: "direct:tui",
+    capabilities,
+    async connect() { },
+    async getState() {
+        return "active";
+    },
+    async discover() {
+        return discoveryPage;
+    },
+    async getContent(_ctx, request) {
+        return { ...getContentResult, entity_id: request.entity_id };
+    },
+    async getReservation(_ctx, request) {
+        return request.upstream_ref === getReservationResult.upstream_ref ? getReservationResult : null;
+    },
+    async listReservations() {
+        return listReservationsPage;
+    },
+};
+const roundTripCases = [
+    ["adapterCapabilitiesSchema", adapterCapabilitiesSchema, capabilities],
+    ["connectionStateSchema", connectionStateSchema, "active"],
+    ["sourceAdapterContextSchema", sourceAdapterContextSchema, context],
+    ["provenanceSchema", provenanceSchema, provenance],
+    ["catalogProjectionSchema", catalogProjectionSchema, projection],
+    ["discoveryCursorSchema", discoveryCursorSchema, "cursor_2"],
+    ["discoveryPageSchema", discoveryPageSchema, discoveryPage],
+    ["sourceAdapterRequestScopeSchema", sourceAdapterRequestScopeSchema, sourceAdapterRequestScope],
+    ["liveResolveRequestSchema", liveResolveRequestSchema, liveResolveRequest],
+    ["liveResolveResultSchema", liveResolveResultSchema, liveResolveResult],
+    ["getContentRequestSchema", getContentRequestSchema, getContentRequest],
+    ["getContentResultSchema", getContentResultSchema, getContentResult],
+    ["reserveRequestSchema", reserveRequestSchema, reserveRequest],
+    ["reserveResultSchema", reserveResultSchema, reserveResult],
+    ["cancelRequestSchema", cancelRequestSchema, cancelRequest],
+    ["cancelResultSchema", cancelResultSchema, cancelResult],
+    ["reservationStatusSchema", reservationStatusSchema, "cancelling"],
+    ["getReservationRequestSchema", getReservationRequestSchema, getReservationRequest],
+    ["getReservationResultSchema", getReservationResultSchema, getReservationResult],
+    ["listReservationsQuerySchema", listReservationsQuerySchema, listReservationsQuery],
+    ["listReservationsPageSchema", listReservationsPageSchema, listReservationsPage],
+    ["pushBookingRequestSchema", pushBookingRequestSchema, pushBookingRequest],
+    ["pushBookingResultSchema", pushBookingResultSchema, pushBookingResult],
+    ["pushAvailabilityRequestSchema", pushAvailabilityRequestSchema, pushAvailabilityRequest],
+    ["pushAvailabilityResultSchema", pushAvailabilityResultSchema, pushAvailabilityResult],
+    ["pushContentRequestSchema", pushContentRequestSchema, pushContentRequest],
+    ["pushContentResultSchema", pushContentResultSchema, pushContentResult],
+    ["sourceAdapterSchema", sourceAdapterSchema, sourceAdapter],
+];
+const invalidCases = [
+    ["adapterCapabilitiesSchema", adapterCapabilitiesSchema, { ...capabilities, verticals: [123] }],
+    ["connectionStateSchema", connectionStateSchema, "reconnecting"],
+    ["sourceAdapterContextSchema", sourceAdapterContextSchema, { credentials: { apiKey: "secret" } }],
+    ["provenanceSchema", provenanceSchema, { ...provenance, source_freshness: "live" }],
+    ["catalogProjectionSchema", catalogProjectionSchema, { ...projection, entity_module: 123 }],
+    ["discoveryCursorSchema", discoveryCursorSchema, 123],
+    ["discoveryPageSchema", discoveryPageSchema, { projections: [{ fields: {} }] }],
+    [
+        "sourceAdapterRequestScopeSchema",
+        sourceAdapterRequestScopeSchema,
+        { ...sourceAdapterRequestScope, currency: "GB" },
+    ],
+    [
+        "liveResolveRequestSchema",
+        liveResolveRequestSchema,
+        { ...liveResolveRequest, scope: { ...liveResolveRequest.scope, locale: "not_locale" } },
+    ],
+    ["liveResolveResultSchema", liveResolveResultSchema, { values: {}, failed: { prod_1: "gone" } }],
+    ["getContentRequestSchema", getContentRequestSchema, { ...getContentRequest, currency: "EU" }],
+    [
+        "getContentResultSchema",
+        getContentResultSchema,
+        { ...getContentResult, content_schema_version: undefined },
+    ],
+    ["reserveRequestSchema", reserveRequestSchema, { ...reserveRequest, parameters: undefined }],
+    ["reserveResultSchema", reserveResultSchema, { ...reserveResult, status: "pending" }],
+    ["cancelRequestSchema", cancelRequestSchema, { reason: "customer_request" }],
+    ["cancelResultSchema", cancelResultSchema, { ...cancelResult, refund_currency: "GB" }],
+    ["reservationStatusSchema", reservationStatusSchema, "expired"],
+    [
+        "getReservationRequestSchema",
+        getReservationRequestSchema,
+        { ...getReservationRequest, upstream_ref: undefined },
+    ],
+    [
+        "getReservationResultSchema",
+        getReservationResultSchema,
+        { ...getReservationResult, status: "expired" },
+    ],
+    ["listReservationsQuerySchema", listReservationsQuerySchema, { limit: 0 }],
+    [
+        "listReservationsPageSchema",
+        listReservationsPageSchema,
+        { reservations: [{ ...getReservationResult, upstream_payload: "raw" }] },
+    ],
+    [
+        "pushBookingRequestSchema",
+        pushBookingRequestSchema,
+        { ...pushBookingRequest, payload: undefined },
+    ],
+    ["pushBookingResultSchema", pushBookingResultSchema, { externalStatus: "confirmed" }],
+    [
+        "pushAvailabilityRequestSchema",
+        pushAvailabilityRequestSchema,
+        { ...pushAvailabilityRequest, remainingPax: -1 },
+    ],
+    ["pushAvailabilityResultSchema", pushAvailabilityResultSchema, { upstreamPayload: "ok" }],
+    [
+        "pushContentRequestSchema",
+        pushContentRequestSchema,
+        { ...pushContentRequest, locale: "not_locale" },
+    ],
+    ["pushContentResultSchema", pushContentResultSchema, { acknowledgedHash: 123 }],
+    ["sourceAdapterSchema", sourceAdapterSchema, { ...sourceAdapter, discover: "yes" }],
+];
+describe("catalog source-adapter schemas", () => {
+    it.each(roundTripCases)("parses %s fixtures without changing shape", (_name, schema, value) => {
+        expect(schema.parse(value)).toEqual(value);
+    });
+    it.each(invalidCases)("rejects invalid %s fixtures", (_name, schema, value) => {
+        expect(schema.safeParse(value).success).toBe(false);
+    });
+});

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

@@ -0,0 +1,124 @@
+/**
+ * `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 type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { SourceAdapterContext, SourceAdapterRequestScope } from "../adapter/contract.js";
+import { type PricingBasis, type SelectBookingCatalogSnapshot } from "../snapshot/schema.js";
+/**
+ * `BookingPaymentIntent` now lives in `@voyant-travel/catalog-contracts`
+ * (the shared server/client seam, alongside `bookRequestV1` whose
+ * `paymentIntent` field mirrors it). Re-exported here to keep existing
+ * `@voyant-travel/catalog/booking-engine` import paths stable.
+ */
+import type { BookingPaymentIntent } from "./contracts.js";
+import type { OwnedBookingHandlerRegistry } from "./owned-handler.js";
+import type { SourceAdapterRegistry } from "./registry.js";
+import type { SnapshotContentCapturer } from "./snapshot-content.js";
+export type { BookingPaymentIntent };
+export interface BookEntityRequest {
+    /** Quote previously returned from `quoteEntity`. */
+    quoteId: string;
+    /**
+     * Existing or newly-created booking shell id. Generated when omitted,
+     * using the `bookings` typeid prefix so the value is shape-compatible
+     * with `packages/bookings`.
+     */
+    bookingId?: string;
+    /** Customer / passenger payload echoed to the adapter's reserve call. */
+    party?: Record<string, unknown>;
+    /** Defaults to `{ type: "hold" }` — see `BookingPaymentIntent`. */
+    paymentIntent?: BookingPaymentIntent;
+    /** Vertical-specific parameters passed to the adapter. */
+    parameters?: Record<string, unknown>;
+    /**
+     * Caller-supplied idempotency key. When set, a duplicate
+     * `bookEntity` call within the snapshot table's lifetime returns
+     * the prior booking instead of creating a new one. Length 8–128.
+     * Per booking-journey-architecture §12.6.
+     */
+    idempotencyKey?: string;
+    adapterContext: SourceAdapterContext;
+    /**
+     * Locale / market / currency scope for snapshot content capture per
+     * sourced-content §5.1. Required when `deps.captureSnapshotContent`
+     * is wired — the engine refreshes content from the adapter at commit
+     * time using this scope and embeds the result as `content_capture`
+     * in `frozen_payload`. When the deps callback isn't set, this field
+     * is ignored and snapshot behavior is unchanged.
+     */
+    contentScope?: {
+        locale: string;
+        market?: string;
+        currency?: string;
+    };
+    /**
+     * Per-request supplier scope forwarded to `SourceAdapter.reserve`.
+     * Kept separate from `contentScope`: this controls upstream write
+     * semantics, while `contentScope` controls snapshot-content capture.
+     */
+    adapterScope?: SourceAdapterRequestScope;
+}
+export interface BookEntityResult {
+    bookingId: string;
+    orderRef: string;
+    status: "held" | "confirmed" | "ticketed" | "failed";
+    snapshotId: string;
+    pricing?: PricingBasis;
+    upstreamPayload?: Record<string, unknown>;
+}
+export interface BookEntityDeps {
+    registry: SourceAdapterRegistry;
+    /**
+     * Owned-arm dispatch — when set and the quote's source kind is
+     * `"owned"`, the engine commits via a handler keyed by
+     * `entity_module` instead of the SourceAdapterRegistry. Per
+     * booking-journey-architecture §6.
+     */
+    ownedHandlers?: OwnedBookingHandlerRegistry;
+    /**
+     * Optional snapshot content capture orchestrator (sourced-content
+     * §5.1). When set, called after `adapter.reserve` succeeds. Returns a
+     * `SnapshotContentCapture` envelope embedded in `frozen_payload` so
+     * audit can later distinguish a fresh capture from a cache fallback.
+     *
+     * Throws `SnapshotContentUnavailableError` when neither a fresh
+     * adapter fetch nor a cache fallback can produce content; the engine
+     * propagates that error and aborts the commit. When the entity is
+     * owned (no sourced-entry row), the orchestrator should return null
+     * and the engine skips the capture.
+     *
+     * Implementations live in templates: each template composes per-
+     * vertical content services into one capturer and threads it through
+     * deps.
+     */
+    captureSnapshotContent?: SnapshotContentCapturer;
+}
+/**
+ * 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 declare function bookEntity(db: AnyDrizzleDb, deps: BookEntityDeps, request: BookEntityRequest): Promise<BookEntityResult>;
+export type { SelectBookingCatalogSnapshot };
+//# sourceMappingURL=book.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"book.d.ts","sourceRoot":"","sources":["../../src/booking-engine/book.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,OAAO,KAAK,EAEV,oBAAoB,EACpB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,4BAA4B,EAClC,MAAM,uBAAuB,CAAA;AAC9B;;;;;GAKG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAQ1D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAA;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAE1D,OAAO,KAAK,EAA0B,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE5F,YAAY,EAAE,oBAAoB,EAAE,CAAA;AAMpC,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE/B,mEAAmE;IACnE,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAEpC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,cAAc,EAAE,oBAAoB,CAAA;IAEpC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE;QACb,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,CAAA;IAED;;;;OAIG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAA;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAA;IACpD,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,qBAAqB,CAAA;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,2BAA2B,CAAA;IAC3C;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,EAAE,uBAAuB,CAAA;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAqL3B;AAoID,YAAY,EAAE,4BAA4B,EAAE,CAAA"}