@voyant-travel/catalog 0.117.2

package/dist/adapter/contract.test.js

@@ -0,0 +1,390 @@
+import { describe, expect, it } from "vitest";
+import { availabilityProjectionSchema, cancelRequestSchema, getReservationRequestSchema, getReservationResultSchema, listReservationsPageSchema, providerPromotionSchema, reservationStatusSchema, reserveRequestSchema, } from "./schemas.js";
+describe("AdapterCapabilities — content fetch declaration", () => {
+    it("accepts adapters that omit supportsContentFetch (backward compatible)", () => {
+        const cap = {
+            verticals: ["products"],
+            supportsLiveResolution: true,
+            supportsDriftDetection: false,
+            supportsBookingForwarding: false,
+            postBookOperations: [],
+        };
+        expect(cap.supportsContentFetch).toBeUndefined();
+        expect(cap.supportedContentLocales).toBeUndefined();
+        expect(cap.ownsContentCache).toBeUndefined();
+        expect(cap.ownsAvailabilityCache).toBeUndefined();
+    });
+    it("records content and availability cache ownership when declared", () => {
+        const cap = {
+            verticals: ["products"],
+            supportsLiveResolution: true,
+            supportsDriftDetection: false,
+            supportsBookingForwarding: true,
+            supportsReservationRetrieval: true,
+            postBookOperations: ["cancel"],
+            supportsContentFetch: true,
+            supportedContentLocales: ["en-GB", "ro-RO", "de-DE"],
+            ownsContentCache: true,
+            ownsAvailabilityCache: true,
+        };
+        expect(cap.supportsContentFetch).toBe(true);
+        expect(cap.supportedContentLocales).toEqual(["en-GB", "ro-RO", "de-DE"]);
+        expect(cap.ownsContentCache).toBe(true);
+        expect(cap.ownsAvailabilityCache).toBe(true);
+        expect(cap.supportsReservationRetrieval).toBe(true);
+    });
+});
+describe("AdapterCapabilities — provider capability declarations", () => {
+    it("can state supported and explicitly unsupported provider features", () => {
+        const cap = {
+            verticals: ["cruises"],
+            supportsLiveResolution: true,
+            supportsDriftDetection: true,
+            supportsBookingForwarding: true,
+            postBookOperations: ["cancel", "status"],
+            providerCapabilities: [
+                {
+                    capability: "category_availability_counts",
+                    support: "supported",
+                    applies_to: ["sailings", "cabin_categories"],
+                },
+                {
+                    capability: "physical_inventory_units",
+                    support: "unsupported",
+                    applies_to: ["cabins"],
+                    reason: "current feed exposes category inventory counts but not cabin numbers",
+                },
+                {
+                    capability: "offer_applicability_evaluation",
+                    support: "unknown",
+                    reason: "customer/session eligibility is provider-side",
+                },
+            ],
+        };
+        expect(cap.providerCapabilities?.map((item) => [item.capability, item.support])).toEqual([
+            ["category_availability_counts", "supported"],
+            ["physical_inventory_units", "unsupported"],
+            ["offer_applicability_evaluation", "unknown"],
+        ]);
+    });
+});
+describe("ProviderPromotion / AvailabilityProjection contract shape", () => {
+    it("represents non-evaluable loyalty offers with normalized display media", () => {
+        const promotion = {
+            source_offer_id: "UNI-PAST-GUEST",
+            provider: "uniworld",
+            display: {
+                display_name: "Past Guest Savings",
+                subtitle: "Exclusive loyalty pricing",
+                media: [
+                    {
+                        kind: "primary",
+                        url: "https://example.com/offers/past-guest.jpg",
+                        alt_text: "River ship suite",
+                    },
+                ],
+                featured: true,
+            },
+            applicability: {
+                evaluation: "not_evaluable_locally",
+                price_effect: "price_affecting",
+                constraints: [
+                    {
+                        kind: "loyalty",
+                        resolution: "customer_context_required",
+                        values: ["past_guest"],
+                        requires_customer_context: true,
+                    },
+                    {
+                        kind: "fare_code",
+                        resolution: "not_evaluable_locally",
+                        values: ["PG"],
+                    },
+                ],
+            },
+            stacking: "unknown",
+            raw_payload: { offerCode: "UNI-PAST-GUEST" },
+        };
+        expect(providerPromotionSchema.parse(promotion)).toEqual(promotion);
+        expect(promotion.applicability.evaluation).toBe("not_evaluable_locally");
+        expect(promotion.display?.media?.[0]?.kind).toBe("primary");
+    });
+    it("distinguishes category-count availability from exact physical units", () => {
+        const projection = {
+            row_kind: "category",
+            row_id: "suite-deluxe",
+            available_units: 3,
+            precision: "category_count",
+            status: "low",
+            low_availability_threshold: 4,
+            badge: { kind: "low_availability", label: "Only 3 left" },
+            sort_priority: 20,
+        };
+        expect(availabilityProjectionSchema.parse(projection)).toEqual(projection);
+        expect(projection.precision).toBe("category_count");
+        expect(projection.status).toBe("low");
+    });
+});
+describe("GetContentRequest / GetContentResult shape", () => {
+    it("requires entity_module, entity_id, and locale", () => {
+        const req = {
+            entity_module: "products",
+            entity_id: "prod_abc",
+            locale: "ro-RO",
+        };
+        expect(req.locale).toBe("ro-RO");
+        expect(req.market).toBeUndefined();
+        expect(req.currency).toBeUndefined();
+    });
+    it("carries optional market + currency scope axes", () => {
+        const req = {
+            entity_module: "cruises",
+            entity_id: "crus_xyz",
+            locale: "de-DE",
+            market: "DE",
+            currency: "EUR",
+        };
+        expect(req.market).toBe("DE");
+        expect(req.currency).toBe("EUR");
+    });
+    it("returned_locale may differ from request.locale (upstream fallback)", () => {
+        const result = {
+            entity_module: "products",
+            entity_id: "prod_abc",
+            source_ref: "TUI-123",
+            // Asked for ro-RO, upstream had no Romanian → served en-GB.
+            returned_locale: "en-GB",
+            content: { product: { name: "Sample" } },
+            content_schema_version: "products/v1",
+        };
+        expect(result.returned_locale).toBe("en-GB");
+        expect(result.machine_translated).toBeUndefined();
+    });
+    it("flags machine_translated when upstream marks the payload", () => {
+        const result = {
+            entity_module: "products",
+            entity_id: "prod_abc",
+            source_ref: "TUI-123",
+            returned_locale: "ro-RO",
+            machine_translated: true,
+            content: { product: { name: "Mostră" } },
+            content_schema_version: "products/v1",
+        };
+        expect(result.machine_translated).toBe(true);
+    });
+});
+describe("SourceAdapter — getContent capability gating", () => {
+    it("typechecks without getContent (capability not declared)", () => {
+        const adapter = {
+            kind: "thin",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: false,
+                supportsBookingForwarding: false,
+                postBookOperations: [],
+                supportsContentFetch: false,
+            },
+            async connect() { },
+            async pause() { },
+            async disconnect() { },
+            async getState() {
+                return "active";
+            },
+            async discover() {
+                return { projections: [], next_cursor: undefined };
+            },
+        };
+        expect(adapter.getContent).toBeUndefined();
+        expect(adapter.capabilities.supportsContentFetch).toBe(false);
+    });
+    it("typechecks with getContent implemented", async () => {
+        const adapter = {
+            kind: "rich",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: false,
+                supportsBookingForwarding: false,
+                postBookOperations: [],
+                supportsContentFetch: true,
+                supportedContentLocales: ["en-GB"],
+            },
+            async connect() { },
+            async pause() { },
+            async disconnect() { },
+            async getState() {
+                return "active";
+            },
+            async discover() {
+                return { projections: [], next_cursor: undefined };
+            },
+            async getContent(_ctx, request) {
+                return {
+                    entity_module: request.entity_module,
+                    entity_id: request.entity_id,
+                    source_ref: "ref-1",
+                    returned_locale: "en-GB",
+                    content: { product: { name: "Test" } },
+                    content_schema_version: "products/v1",
+                };
+            },
+        };
+        expect(adapter.getContent).toBeDefined();
+        const result = await adapter.getContent({ connection_id: "conn_1" }, { entity_module: "products", entity_id: "prod_abc", locale: "ro-RO" });
+        expect(result.returned_locale).toBe("en-GB");
+        expect(result.content_schema_version).toBe("products/v1");
+    });
+});
+describe("SourceAdapter — reservation retrieval capability gating", () => {
+    it("typechecks without reservation read methods when capability is false", () => {
+        const adapter = {
+            kind: "booking-write-only",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: false,
+                supportsBookingForwarding: true,
+                supportsReservationRetrieval: false,
+                postBookOperations: ["cancel"],
+            },
+            async reserve() {
+                return { upstream_ref: "booking_abc", status: "held" };
+            },
+            async cancel() {
+                return { status: "cancelled" };
+            },
+        };
+        expect(adapter.getReservation).toBeUndefined();
+        expect(adapter.listReservations).toBeUndefined();
+        expect(adapter.capabilities.supportsReservationRetrieval).toBe(false);
+    });
+    it("typechecks with getReservation and listReservations implemented", async () => {
+        const reservation = {
+            upstream_ref: "booking_abc",
+            status: "confirmed",
+            source_updated_at: new Date("2026-01-01T00:00:00Z"),
+            upstream_payload: { travelers: 2 },
+        };
+        const page = {
+            reservations: [reservation],
+            next_cursor: "cursor_2",
+        };
+        const adapter = {
+            kind: "booking-readable",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: true,
+                supportsBookingForwarding: true,
+                supportsReservationRetrieval: true,
+                postBookOperations: ["cancel", "status"],
+            },
+            async getReservation(_ctx, request) {
+                return request.upstream_ref === reservation.upstream_ref ? reservation : null;
+            },
+            async listReservations() {
+                return page;
+            },
+        };
+        const request = {
+            upstream_ref: "missing",
+            scope: { locale: "en-GB", audience: "operator", market: "GB", currency: "GBP" },
+        };
+        expect(getReservationRequestSchema.parse(request)).toEqual(request);
+        await expect(adapter.getReservation({ connection_id: "conn_1" }, request)).resolves.toBeNull();
+        await expect(adapter.getReservation({ connection_id: "conn_1" }, { upstream_ref: "booking_abc" })).resolves.toEqual(reservation);
+        await expect(adapter.listReservations({ connection_id: "conn_1" }, { status: ["confirmed"] })).resolves.toEqual(page);
+        expect(getReservationResultSchema.parse(reservation)).toEqual(reservation);
+        expect(listReservationsPageSchema.parse(page)).toEqual(page);
+    });
+    it("accepts every reservation status and rejects unknown statuses", () => {
+        const statuses = [
+            "held",
+            "confirmed",
+            "ticketed",
+            "failed",
+            "cancelled",
+            "pending",
+            "refused",
+            "cancelling",
+        ];
+        expect(statuses.map((status) => reservationStatusSchema.parse(status))).toEqual(statuses);
+        expect(reservationStatusSchema.safeParse("expired").success).toBe(false);
+    });
+});
+describe("ReserveRequest / CancelRequest scoped write shape", () => {
+    it("round-trips reserve requests with request scope and idempotency key", () => {
+        const request = {
+            entity_module: "products",
+            entity_id: "prod_abc",
+            parameters: { departureId: "dep_1" },
+            party: { travelers: 2 },
+            scope: {
+                locale: "en-GB",
+                audience: "customer",
+                market: "GB",
+                currency: "GBP",
+            },
+            idempotency_key: "reserve_abc",
+        };
+        expect(reserveRequestSchema.parse(request)).toEqual(request);
+    });
+    it("round-trips cancel requests with request scope and idempotency key", () => {
+        const request = {
+            upstream_ref: "booking_abc",
+            reason: "customer_request",
+            scope: {
+                locale: "en-GB",
+                audience: "customer",
+                market: "GB",
+                currency: "GBP",
+            },
+            idempotency_key: "cancel_abc",
+        };
+        expect(cancelRequestSchema.parse(request)).toEqual(request);
+    });
+});
+describe("SourceAdapter — cancellation capability declaration", () => {
+    it("typechecks sync cancellation adapters that return terminal statuses", async () => {
+        const adapter = {
+            kind: "sync-cancel",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: false,
+                supportsBookingForwarding: true,
+                supportsSyncCancellation: true,
+                postBookOperations: ["cancel"],
+            },
+            async cancel() {
+                return { status: "cancelled", refund_amount: 100, refund_currency: "GBP" };
+            },
+        };
+        await expect(adapter.cancel({ connection_id: "conn_1" }, { upstream_ref: "up_1" })).resolves.toEqual({
+            status: "cancelled",
+            refund_amount: 100,
+            refund_currency: "GBP",
+        });
+    });
+    it("typechecks async cancellation adapters that return pending", async () => {
+        const adapter = {
+            kind: "async-cancel",
+            capabilities: {
+                verticals: ["products"],
+                supportsLiveResolution: false,
+                supportsDriftDetection: true,
+                supportsBookingForwarding: true,
+                supportsSyncCancellation: false,
+                postBookOperations: ["cancel"],
+            },
+            async cancel() {
+                return { status: "pending", pending_channel: "partner portal" };
+            },
+        };
+        await expect(adapter.cancel({ connection_id: "conn_1" }, { upstream_ref: "up_1" })).resolves.toEqual({
+            status: "pending",
+            pending_channel: "partner portal",
+        });
+    });
+});

package/dist/adapter/provider-contracts.d.ts

@@ -0,0 +1,2 @@
+export * from "@voyant-travel/catalog-contracts/adapter/provider-contracts";
+//# sourceMappingURL=provider-contracts.d.ts.map

package/dist/adapter/provider-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-contracts.d.ts","sourceRoot":"","sources":["../../src/adapter/provider-contracts.ts"],"names":[],"mappings":"AAAA,cAAc,6DAA6D,CAAA"}

package/dist/adapter/provider-contracts.js

@@ -0,0 +1 @@
+export * from "@voyant-travel/catalog-contracts/adapter/provider-contracts";

package/dist/adapter/provider-contracts.test.d.ts

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

package/dist/adapter/provider-contracts.test.d.ts.map

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

package/dist/adapter/provider-contracts.test.js

@@ -0,0 +1,206 @@
+import { describe, expect, it } from "vitest";
+import { availabilityBadgeKindSchema, availabilityBadgeSchema, availabilityProjectionSchema, availabilityRowKindSchema, availabilityStatusSchema, availabilityUnitPrecisionSchema, capabilitySupportSchema, promotionApplicabilityConstraintKindSchema, promotionApplicabilityConstraintSchema, promotionApplicabilityEvaluationSchema, promotionApplicabilityResolutionSchema, promotionApplicabilitySchema, promotionDisplayFieldsSchema, promotionMediaAssetSchema, promotionMediaKindSchema, promotionPriceEffectSchema, promotionStackingSemanticsSchema, providerCapabilityDeclarationSchema, providerCapabilityKeySchema, providerPromotionSchema, } 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,
+];
+void typeChecks;
+const providerCapabilityDeclaration = {
+    capability: "offer_applicability_evaluation",
+    support: "unknown",
+    reason: "loyalty eligibility depends on shopper session context",
+};
+const promotionApplicabilityConstraint = {
+    kind: "fare_code",
+    resolution: "not_evaluable_locally",
+    values: ["PAST-GUEST"],
+    requires_customer_context: true,
+    reason: "provider does not link every sale row to a specific offer row",
+};
+const promotionApplicability = {
+    evaluation: "not_evaluable_locally",
+    price_effect: "informational_only",
+    constraints: [promotionApplicabilityConstraint],
+};
+const promotionMediaAsset = {
+    kind: "hero",
+    url: "https://example.com/offers/hero.jpg",
+    alt_text: "River cruise promotion",
+    width: 1600,
+    height: 900,
+};
+const promotionDisplayFields = {
+    display_name: "Past Guest Savings",
+    subtitle: "Exclusive loyalty pricing",
+    rich_description: "<p>Save on selected departures.</p>",
+    terms_and_conditions: "Eligibility required.",
+    media: [promotionMediaAsset],
+    featured: true,
+    display_priority: 10,
+};
+const providerPromotion = {
+    source_offer_id: "offer_123",
+    source_offer_ref: "PG-2026",
+    provider: "uniworld",
+    display: promotionDisplayFields,
+    applicability: promotionApplicability,
+    stacking: "unknown",
+    raw_payload: { offerCode: "PG-2026" },
+};
+const availabilityBadge = {
+    kind: "low_availability",
+    label: "Only 3 left",
+};
+const availabilityProjection = {
+    row_kind: "category",
+    row_id: "suite-deluxe",
+    available_units: 3,
+    precision: "category_count",
+    status: "low",
+    low_availability_threshold: 4,
+    badge: availabilityBadge,
+    sort_priority: 20,
+    source_updated_at: "2026-05-30T00:00:00Z",
+};
+const roundTripCases = [
+    ["capabilitySupportSchema", capabilitySupportSchema, "unsupported"],
+    [
+        "providerCapabilityKeySchema",
+        providerCapabilityKeySchema,
+        "physical_inventory_units",
+    ],
+    [
+        "providerCapabilityDeclarationSchema",
+        providerCapabilityDeclarationSchema,
+        providerCapabilityDeclaration,
+    ],
+    [
+        "promotionApplicabilityEvaluationSchema",
+        promotionApplicabilityEvaluationSchema,
+        "not_evaluable_locally",
+    ],
+    [
+        "promotionPriceEffectSchema",
+        promotionPriceEffectSchema,
+        "informational_only",
+    ],
+    [
+        "promotionApplicabilityConstraintKindSchema",
+        promotionApplicabilityConstraintKindSchema,
+        "customer_session",
+    ],
+    [
+        "promotionApplicabilityResolutionSchema",
+        promotionApplicabilityResolutionSchema,
+        "customer_context_required",
+    ],
+    [
+        "promotionApplicabilityConstraintSchema",
+        promotionApplicabilityConstraintSchema,
+        promotionApplicabilityConstraint,
+    ],
+    ["promotionApplicabilitySchema", promotionApplicabilitySchema, promotionApplicability],
+    ["promotionMediaKindSchema", promotionMediaKindSchema, "primary"],
+    ["promotionMediaAssetSchema", promotionMediaAssetSchema, promotionMediaAsset],
+    ["promotionDisplayFieldsSchema", promotionDisplayFieldsSchema, promotionDisplayFields],
+    [
+        "promotionStackingSemanticsSchema",
+        promotionStackingSemanticsSchema,
+        "provider_defined",
+    ],
+    ["providerPromotionSchema", providerPromotionSchema, providerPromotion],
+    ["availabilityRowKindSchema", availabilityRowKindSchema, "sailing"],
+    [
+        "availabilityUnitPrecisionSchema",
+        availabilityUnitPrecisionSchema,
+        "category_count",
+    ],
+    ["availabilityStatusSchema", availabilityStatusSchema, "sold_out"],
+    [
+        "availabilityBadgeKindSchema",
+        availabilityBadgeKindSchema,
+        "low_availability",
+    ],
+    ["availabilityBadgeSchema", availabilityBadgeSchema, availabilityBadge],
+    ["availabilityProjectionSchema", availabilityProjectionSchema, availabilityProjection],
+];
+const invalidCases = [
+    ["capabilitySupportSchema", capabilitySupportSchema, "partial"],
+    ["providerCapabilityKeySchema", providerCapabilityKeySchema, "deck_plans"],
+    [
+        "providerCapabilityDeclarationSchema",
+        providerCapabilityDeclarationSchema,
+        { ...providerCapabilityDeclaration, support: "partial" },
+    ],
+    ["promotionApplicabilityEvaluationSchema", promotionApplicabilityEvaluationSchema, "local"],
+    ["promotionPriceEffectSchema", promotionPriceEffectSchema, "discount"],
+    [
+        "promotionApplicabilityConstraintKindSchema",
+        promotionApplicabilityConstraintKindSchema,
+        "tier",
+    ],
+    ["promotionApplicabilityResolutionSchema", promotionApplicabilityResolutionSchema, "maybe"],
+    [
+        "promotionApplicabilityConstraintSchema",
+        promotionApplicabilityConstraintSchema,
+        { ...promotionApplicabilityConstraint, values: [123] },
+    ],
+    [
+        "promotionApplicabilitySchema",
+        promotionApplicabilitySchema,
+        { ...promotionApplicability, constraints: undefined },
+    ],
+    ["promotionMediaKindSchema", promotionMediaKindSchema, "banner"],
+    [
+        "promotionMediaAssetSchema",
+        promotionMediaAssetSchema,
+        { ...promotionMediaAsset, url: "image" },
+    ],
+    [
+        "promotionDisplayFieldsSchema",
+        promotionDisplayFieldsSchema,
+        { ...promotionDisplayFields, media: [{ ...promotionMediaAsset, width: 0 }] },
+    ],
+    ["promotionStackingSemanticsSchema", promotionStackingSemanticsSchema, "combinable"],
+    [
+        "providerPromotionSchema",
+        providerPromotionSchema,
+        { ...providerPromotion, source_offer_id: 123 },
+    ],
+    ["availabilityRowKindSchema", availabilityRowKindSchema, "cabin"],
+    ["availabilityUnitPrecisionSchema", availabilityUnitPrecisionSchema, "estimated"],
+    ["availabilityStatusSchema", availabilityStatusSchema, "limited"],
+    ["availabilityBadgeKindSchema", availabilityBadgeKindSchema, "few_left"],
+    ["availabilityBadgeSchema", availabilityBadgeSchema, { kind: "few_left" }],
+    [
+        "availabilityProjectionSchema",
+        availabilityProjectionSchema,
+        { ...availabilityProjection, available_units: -1 },
+    ],
+];
+describe("provider catalog contract 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/adapter/schemas.d.ts

@@ -0,0 +1,2 @@
+export * from "@voyant-travel/catalog-contracts/adapter/schemas";
+//# sourceMappingURL=schemas.d.ts.map

package/dist/adapter/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/adapter/schemas.ts"],"names":[],"mappings":"AAAA,cAAc,kDAAkD,CAAA"}

package/dist/adapter/schemas.js

@@ -0,0 +1 @@
+export * from "@voyant-travel/catalog-contracts/adapter/schemas";

package/dist/adapter/schemas.test.d.ts

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

package/dist/adapter/schemas.test.d.ts.map

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