@voyant-travel/flights 0.119.2

package/dist/orchestration/fan-out.test.js

@@ -0,0 +1,271 @@
+import { describe, expect, it } from "vitest";
+import { fanOutFlightSearch } from "./fan-out.js";
+function makeOffer(overrides) {
+    return {
+        offerId: overrides.offerId ?? "ofr_default",
+        source: overrides.source ?? "test",
+        itineraries: [
+            {
+                segments: [
+                    {
+                        segmentId: "s1",
+                        carrierCode: "BA",
+                        flightNumber: "177",
+                        departure: { iataCode: "LHR", at: "2026-10-15T11:00:00+00:00" },
+                        arrival: { iataCode: "JFK", at: "2026-10-15T14:00:00-04:00" },
+                        cabin: "economy",
+                    },
+                ],
+            },
+        ],
+        fareBreakdowns: [
+            {
+                passengerType: "adult",
+                passengerCount: 1,
+                baseFare: { amount: "500", currency: "USD" },
+                taxes: { amount: "100", currency: "USD" },
+                total: { amount: "600", currency: "USD" },
+            },
+        ],
+        totalPrice: overrides.totalPrice ?? { amount: "600", currency: "USD" },
+        ...overrides,
+    };
+}
+function makeAdapter(provider, behaviour = {}) {
+    return {
+        capabilities: {
+            provider,
+            declared: [],
+            maxSlicesPerSearch: behaviour.maxSlices,
+        },
+        async searchFlights(ctx) {
+            behaviour.captureContext?.(ctx);
+            if (behaviour.delayMs) {
+                await new Promise((r) => setTimeout(r, behaviour.delayMs));
+            }
+            if (behaviour.throws)
+                throw behaviour.throws;
+            return { offers: behaviour.offers ?? [] };
+        },
+        async priceOffer() {
+            throw new Error("not implemented in test");
+        },
+        async bookFlight() {
+            throw new Error("not implemented in test");
+        },
+        async getOrder() {
+            throw new Error("not implemented in test");
+        },
+        async cancelOrder() {
+            throw new Error("not implemented in test");
+        },
+    };
+}
+const oneSliceRequest = {
+    slices: [{ origin: "LHR", destination: "JFK", departureDate: "2026-10-15" }],
+    passengers: { adults: 1 },
+    cabin: "economy",
+};
+describe("fanOutFlightSearch", () => {
+    it("merges identical itineraries from multiple providers, keeping cheapest as primary", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_amadeus",
+                    adapter: makeAdapter("amadeus", {
+                        offers: [
+                            makeOffer({ source: "amadeus", totalPrice: { amount: "650", currency: "USD" } }),
+                        ],
+                    }),
+                },
+                {
+                    connectionId: "conn_hisky",
+                    adapter: makeAdapter("hisky", {
+                        offers: [
+                            makeOffer({ source: "hisky", totalPrice: { amount: "600", currency: "USD" } }),
+                        ],
+                    }),
+                },
+            ],
+            request: oneSliceRequest,
+        });
+        expect(result.offers).toHaveLength(1);
+        expect(result.offers[0]?.cheapest.totalPrice.amount).toBe("600");
+        expect(result.offers[0]?.cheapest.source).toBe("hisky");
+        expect(result.offers[0]?.alternates).toHaveLength(1);
+        expect(result.offers[0]?.alternates[0]?.source).toBe("amadeus");
+        expect(result.offers[0]?.sourceConnectionIds.sort()).toEqual(["conn_amadeus", "conn_hisky"]);
+    });
+    it("sorts merged offers by cheapest price ascending", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_a",
+                    adapter: makeAdapter("a", {
+                        offers: [
+                            makeOffer({
+                                offerId: "ofr_expensive",
+                                source: "a",
+                                itineraries: [
+                                    {
+                                        segments: [
+                                            {
+                                                segmentId: "s",
+                                                carrierCode: "VS",
+                                                flightNumber: "3",
+                                                departure: { iataCode: "LHR", at: "2026-10-15T15:00:00+00:00" },
+                                                arrival: { iataCode: "JFK", at: "2026-10-15T18:00:00-04:00" },
+                                                cabin: "economy",
+                                            },
+                                        ],
+                                    },
+                                ],
+                                totalPrice: { amount: "1000", currency: "USD" },
+                            }),
+                            makeOffer({
+                                offerId: "ofr_cheap",
+                                source: "a",
+                                totalPrice: { amount: "300", currency: "USD" },
+                            }),
+                        ],
+                    }),
+                },
+            ],
+            request: oneSliceRequest,
+        });
+        expect(result.offers).toHaveLength(2);
+        expect(result.offers[0]?.cheapest.totalPrice.amount).toBe("300");
+        expect(result.offers[1]?.cheapest.totalPrice.amount).toBe("1000");
+    });
+    it("flags timed-out connections and returns results from responding ones", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_fast",
+                    adapter: makeAdapter("fast", { offers: [makeOffer({ source: "fast" })] }),
+                },
+                {
+                    connectionId: "conn_slow",
+                    adapter: makeAdapter("slow", { delayMs: 200 }),
+                },
+            ],
+            request: oneSliceRequest,
+            perConnectionTimeoutMs: 50,
+        });
+        expect(result.offers).toHaveLength(1);
+        const fast = result.perConnection.find((c) => c.connectionId === "conn_fast");
+        const slow = result.perConnection.find((c) => c.connectionId === "conn_slow");
+        expect(fast?.status).toBe("ok");
+        expect(slow?.status).toBe("timeout");
+    });
+    it("flags connections that throw as 'error' without losing other results", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_ok",
+                    adapter: makeAdapter("ok", { offers: [makeOffer({})] }),
+                },
+                {
+                    connectionId: "conn_fail",
+                    adapter: makeAdapter("fail", { throws: new Error("provider down") }),
+                },
+            ],
+            request: oneSliceRequest,
+        });
+        expect(result.offers).toHaveLength(1);
+        const fail = result.perConnection.find((c) => c.connectionId === "conn_fail");
+        expect(fail?.status).toBe("error");
+        expect(fail?.errorMessage).toBe("provider down");
+    });
+    it("flags connections that don't support the request's slice count as capability_missing", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_pp",
+                    adapter: makeAdapter("point-to-point", {
+                        maxSlices: 1,
+                        offers: [makeOffer({})],
+                    }),
+                },
+            ],
+            request: {
+                ...oneSliceRequest,
+                slices: [
+                    ...oneSliceRequest.slices,
+                    { origin: "JFK", destination: "LAX", departureDate: "2026-10-20" },
+                ],
+            },
+        });
+        expect(result.offers).toHaveLength(0);
+        expect(result.perConnection[0]?.status).toBe("capability_missing");
+    });
+    it("respects the limit parameter on the merged result", async () => {
+        const result = await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_a",
+                    adapter: makeAdapter("a", {
+                        offers: [
+                            makeOffer({ offerId: "1", totalPrice: { amount: "100", currency: "USD" } }),
+                            makeOffer({
+                                offerId: "2",
+                                itineraries: [
+                                    {
+                                        segments: [
+                                            {
+                                                segmentId: "s",
+                                                carrierCode: "AA",
+                                                flightNumber: "1",
+                                                departure: { iataCode: "LHR", at: "2026-10-15T20:00:00+00:00" },
+                                                arrival: { iataCode: "JFK", at: "2026-10-15T23:00:00-04:00" },
+                                                cabin: "economy",
+                                            },
+                                        ],
+                                    },
+                                ],
+                                totalPrice: { amount: "200", currency: "USD" },
+                            }),
+                        ],
+                    }),
+                },
+            ],
+            request: oneSliceRequest,
+            limit: 1,
+        });
+        expect(result.offers).toHaveLength(1);
+        expect(result.offers[0]?.cheapest.totalPrice.amount).toBe("100");
+    });
+    it("propagates adapter context fields to each connection", async () => {
+        const controller = new AbortController();
+        const captured = [];
+        await fanOutFlightSearch({
+            adapters: [
+                {
+                    connectionId: "conn_a",
+                    adapter: makeAdapter("a", {
+                        offers: [makeOffer({})],
+                        captureContext: (ctx) => {
+                            captured.push(ctx);
+                        },
+                    }),
+                    context: {
+                        requestId: "req_1",
+                        correlationId: "corr_1",
+                        idempotencyKey: "idem_1",
+                        environment: "sandbox",
+                        signal: controller.signal,
+                    },
+                },
+            ],
+            request: oneSliceRequest,
+        });
+        expect(captured[0]).toMatchObject({
+            connectionId: "conn_a",
+            requestId: "req_1",
+            correlationId: "corr_1",
+            idempotencyKey: "idem_1",
+            environment: "sandbox",
+        });
+        expect(captured[0]?.signal).toBe(controller.signal);
+    });
+});

package/dist/orchestration/fingerprint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Itinerary fingerprint — deterministic key derived from a `FlightOffer`'s
+ * segments. Two providers selling the same flight produce identical
+ * fingerprints; the multi-connection fan-out uses this to merge offers
+ * across connections.
+ *
+ * Mirrors voyant-cloud's `itineraryFingerprint` so fingerprints are
+ * portable: an offer fingerprinted in voyant-cloud and another fingerprinted
+ * here for the same physical flight match by string equality.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §4.
+ */
+import type { FlightOffer } from "../contract/types.js";
+/**
+ * Deterministic key derived from segments: carrier code + flight number +
+ * departure/arrival airports + times + cabin. Two providers selling the
+ * same flight produce identical fingerprints.
+ */
+export declare function itineraryFingerprint(offer: FlightOffer): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/orchestration/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/orchestration/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAS/D"}

package/dist/orchestration/fingerprint.js

@@ -0,0 +1,22 @@
+/**
+ * Itinerary fingerprint — deterministic key derived from a `FlightOffer`'s
+ * segments. Two providers selling the same flight produce identical
+ * fingerprints; the multi-connection fan-out uses this to merge offers
+ * across connections.
+ *
+ * Mirrors voyant-cloud's `itineraryFingerprint` so fingerprints are
+ * portable: an offer fingerprinted in voyant-cloud and another fingerprinted
+ * here for the same physical flight match by string equality.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §4.
+ */
+/**
+ * Deterministic key derived from segments: carrier code + flight number +
+ * departure/arrival airports + times + cabin. Two providers selling the
+ * same flight produce identical fingerprints.
+ */
+export function itineraryFingerprint(offer) {
+    return offer.itineraries
+        .flatMap((itinerary) => itinerary.segments.map((s) => `${s.carrierCode}${s.flightNumber}|${s.departure.iataCode}|${s.departure.at}|${s.arrival.iataCode}|${s.arrival.at}|${s.cabin}`))
+        .join("→");
+}

package/dist/orchestration/fingerprint.test.d.ts

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

package/dist/orchestration/fingerprint.test.d.ts.map

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

package/dist/orchestration/fingerprint.test.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { itineraryFingerprint } from "./fingerprint.js";
+const offerLondonToNYC = {
+    offerId: "ofr_a",
+    source: "amadeus",
+    itineraries: [
+        {
+            segments: [
+                {
+                    segmentId: "s1",
+                    carrierCode: "BA",
+                    flightNumber: "177",
+                    departure: { iataCode: "LHR", at: "2026-10-15T11:00:00+00:00" },
+                    arrival: { iataCode: "JFK", at: "2026-10-15T14:00:00-04:00" },
+                    cabin: "economy",
+                },
+            ],
+        },
+    ],
+    fareBreakdowns: [
+        {
+            passengerType: "adult",
+            passengerCount: 1,
+            baseFare: { amount: "500", currency: "USD" },
+            taxes: { amount: "100", currency: "USD" },
+            total: { amount: "600", currency: "USD" },
+        },
+    ],
+    totalPrice: { amount: "600", currency: "USD" },
+};
+describe("itineraryFingerprint", () => {
+    it("produces a deterministic key from segments", () => {
+        const fp = itineraryFingerprint(offerLondonToNYC);
+        expect(fp).toBe("BA177|LHR|2026-10-15T11:00:00+00:00|JFK|2026-10-15T14:00:00-04:00|economy");
+    });
+    it("two providers selling the same flight produce identical fingerprints", () => {
+        const fromAmadeus = { ...offerLondonToNYC, offerId: "ofr_amadeus", source: "amadeus" };
+        const fromHisky = { ...offerLondonToNYC, offerId: "ofr_hisky", source: "hisky" };
+        expect(itineraryFingerprint(fromAmadeus)).toBe(itineraryFingerprint(fromHisky));
+    });
+    it("differs when carrier changes", () => {
+        const altered = {
+            ...offerLondonToNYC,
+            itineraries: [
+                {
+                    segments: [
+                        {
+                            ...offerLondonToNYC.itineraries[0].segments[0],
+                            carrierCode: "VS",
+                            flightNumber: "3",
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(itineraryFingerprint(altered)).not.toBe(itineraryFingerprint(offerLondonToNYC));
+    });
+    it("differs when cabin class changes (price tier matters for grouping)", () => {
+        const business = {
+            ...offerLondonToNYC,
+            itineraries: [
+                {
+                    segments: [{ ...offerLondonToNYC.itineraries[0].segments[0], cabin: "business" }],
+                },
+            ],
+        };
+        expect(itineraryFingerprint(business)).not.toBe(itineraryFingerprint(offerLondonToNYC));
+    });
+    it("multi-leg itineraries fingerprint with arrow separator between segments", () => {
+        const multiLeg = {
+            ...offerLondonToNYC,
+            itineraries: [
+                {
+                    segments: [
+                        offerLondonToNYC.itineraries[0].segments[0],
+                        {
+                            segmentId: "s2",
+                            carrierCode: "AA",
+                            flightNumber: "100",
+                            departure: { iataCode: "JFK", at: "2026-10-22T10:00:00-04:00" },
+                            arrival: { iataCode: "LHR", at: "2026-10-22T22:00:00+00:00" },
+                            cabin: "economy",
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(itineraryFingerprint(multiLeg)).toContain("→");
+        expect(itineraryFingerprint(multiLeg).split("→")).toHaveLength(2);
+    });
+});

package/dist/reference/contract.d.ts

@@ -0,0 +1,2 @@
+export * from "@voyant-travel/flights-contracts/reference/contract";
+//# sourceMappingURL=contract.d.ts.map

package/dist/reference/contract.d.ts.map

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

package/dist/reference/contract.js

@@ -0,0 +1 @@
+export * from "@voyant-travel/flights-contracts/reference/contract";