@voyantjs/flights 0.19.0

package/dist/orchestration/fan-out.js

@@ -0,0 +1,132 @@
+/**
+ * Multi-connection fan-out search.
+ *
+ * Parallel `searchFlights` across all of an operator's flight connections
+ * with per-connection timeouts, partial-success handling, and merge by
+ * itinerary fingerprint. Returns a merged result set with the cheapest
+ * offer per itinerary as the primary rank, alternates from other
+ * connections beneath it, and a per-connection status map.
+ *
+ * Implements voyant-cloud's `MergedFlightOffer` shape so consumers see the
+ * same result format regardless of where the orchestration runs.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §4.
+ */
+import { itineraryFingerprint } from "./fingerprint.js";
+/**
+ * Fan out a flight search across an operator's connections, parallelized
+ * with per-connection timeout, then merge by itinerary fingerprint.
+ *
+ * Partial-success semantics: connections that time out / error / report
+ * capability-missing are flagged in `perConnection`; the orchestration
+ * still returns whatever responding connections produced.
+ */
+export async function fanOutFlightSearch(options) {
+    const timeoutMs = options.perConnectionTimeoutMs ?? 5000;
+    const settled = await Promise.all(options.adapters.map(async ({ connectionId, adapter, context }) => {
+        const start = Date.now();
+        try {
+            // Capability check up front. If the adapter declares a max-slices
+            // limit and the request exceeds it, fail fast as `capability_missing`.
+            const max = adapter.capabilities.maxSlicesPerSearch;
+            if (max != null && options.request.slices.length > max) {
+                return {
+                    connectionId,
+                    status: "capability_missing",
+                    offers: [],
+                    latencyMs: Date.now() - start,
+                    errorMessage: `Connection supports max ${max} slices; request had ${options.request.slices.length}`,
+                };
+            }
+            const ctx = { connectionId, ...context };
+            const response = await withTimeout(adapter.searchFlights(ctx, options.request), timeoutMs, `connection ${connectionId} timed out after ${timeoutMs}ms`);
+            return {
+                connectionId,
+                status: "ok",
+                offers: response.offers,
+                latencyMs: Date.now() - start,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const isTimeout = message.includes("timed out");
+            return {
+                connectionId,
+                status: isTimeout ? "timeout" : "error",
+                offers: [],
+                latencyMs: Date.now() - start,
+                errorMessage: message,
+            };
+        }
+    }));
+    // Build per-connection status report.
+    const perConnection = settled.map((r) => ({
+        connectionId: r.connectionId,
+        status: r.status,
+        count: r.offers.length,
+        latencyMs: r.latencyMs,
+        errorMessage: r.errorMessage,
+    }));
+    // Group offers by itinerary fingerprint, building MergedFlightOffer per group.
+    const merged = mergeByFingerprint(settled);
+    // Sort merged offers by cheapest price ascending.
+    merged.sort((a, b) => compareMoney(a.cheapest.totalPrice, b.cheapest.totalPrice));
+    const limited = options.limit != null ? merged.slice(0, options.limit) : merged;
+    return { offers: limited, perConnection };
+}
+function mergeByFingerprint(results) {
+    const buckets = new Map();
+    for (const { connectionId, offers } of results) {
+        for (const offer of offers) {
+            const key = itineraryFingerprint(offer);
+            const bucket = buckets.get(key);
+            if (bucket) {
+                bucket.offers.push({ connectionId, offer });
+                bucket.sourceConnectionIds.add(connectionId);
+            }
+            else {
+                buckets.set(key, {
+                    offers: [{ connectionId, offer }],
+                    sourceConnectionIds: new Set([connectionId]),
+                });
+            }
+        }
+    }
+    const merged = [];
+    for (const [fingerprint, bucket] of buckets) {
+        // Sort offers within the bucket by total price ascending.
+        bucket.offers.sort((a, b) => compareMoney(a.offer.totalPrice, b.offer.totalPrice));
+        const cheapestEntry = bucket.offers[0];
+        if (!cheapestEntry)
+            continue;
+        merged.push({
+            itineraryFingerprint: fingerprint,
+            cheapest: cheapestEntry.offer,
+            alternates: bucket.offers.slice(1).map((entry) => entry.offer),
+            sourceConnectionIds: Array.from(bucket.sourceConnectionIds),
+        });
+    }
+    return merged;
+}
+/**
+ * Compare two `Money` values. Currencies must match — cross-currency
+ * comparison would require live FX which the orchestration doesn't have.
+ * Returns negative if `a < b`, positive if `a > b`, 0 if equal.
+ */
+function compareMoney(a, b) {
+    if (a.currency !== b.currency) {
+        // Fall back to string compare on amount when currencies differ —
+        // produces a stable but not-meaningful order. Real deployments
+        // normalize currency upstream of the orchestration.
+        return a.amount.localeCompare(b.amount);
+    }
+    const aNum = Number.parseFloat(a.amount);
+    const bNum = Number.parseFloat(b.amount);
+    return aNum - bNum;
+}
+async function withTimeout(promise, ms, message) {
+    return await Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms)),
+    ]);
+}

package/dist/orchestration/fan-out.test.d.ts

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

package/dist/orchestration/fan-out.test.d.ts.map

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

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

@@ -0,0 +1,237 @@
+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() {
+            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");
+    });
+});

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,90 @@
+/**
+ * `ReferenceDataProvider` contract — swappable provider for global
+ * reference data (airlines, airports, aircraft, currencies, countries).
+ *
+ * Per architecture §5.11.6 / §6, implementable at any layer:
+ *   - **In-deployment local Postgres** (the simplest case)
+ *   - Static JSON / CSV bundle
+ *   - Internal data lake / warehouse
+ *   - Third-party services (OAG, Cirium, RouteHappy)
+ *   - GDS-bundled reference subscriptions
+ *   - Voyant Data (the hosted default)
+ *
+ * No implementer is privileged. Operators can run a fully self-contained
+ * Voyant deployment with all reference data in their own database, no
+ * external dependency.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §6.
+ */
+export interface Airline {
+    iataCode: string;
+    icaoCode?: string;
+    name: string;
+    /** ISO 3166-1 alpha-2 country code. */
+    country?: string;
+    /** Optional logo URL. */
+    logoUrl?: string;
+    /** Optional alliance affiliation: `"oneworld"`, `"star-alliance"`, `"skyteam"`. */
+    alliance?: string;
+}
+export interface Airport {
+    iataCode: string;
+    icaoCode?: string;
+    name: string;
+    city: string;
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    timezone?: string;
+    latitude?: number;
+    longitude?: number;
+}
+export interface Aircraft {
+    iataCode: string;
+    icaoCode?: string;
+    name: string;
+    manufacturer?: string;
+    /** Optional capacity hint (typical seat count). */
+    typicalSeats?: number;
+}
+/**
+ * Capabilities declared by the provider. Lets the catalog plane fail
+ * fast when a deployment requests reference data the provider can't
+ * serve (e.g. asking for currencies from a provider that only covers
+ * airlines/airports).
+ */
+export interface ReferenceDataCapabilities {
+    coversAirlines: boolean;
+    coversAirports: boolean;
+    coversAircraft: boolean;
+    coversCurrencies: boolean;
+    coversCountries: boolean;
+    /** True for hosted/read-only providers; false for ones that allow upserts. */
+    isReadOnly: boolean;
+    /** How often the provider's data refreshes from upstream. */
+    refreshCadence: "static" | "weekly" | "daily" | "on-demand";
+}
+/**
+ * The reference data contract. Used by flight integrations to hydrate
+ * IATA codes into human-readable names + metadata; usable by any other
+ * vertical that needs the same lookup surface.
+ */
+export interface ReferenceDataProvider {
+    readonly capabilities: ReferenceDataCapabilities;
+    /** Look up one airline by IATA code. Returns null if not found. */
+    getAirline(iataCode: string): Promise<Airline | null>;
+    /** Look up one airport by IATA code. */
+    getAirport(iataCode: string): Promise<Airport | null>;
+    /** Look up one aircraft type by IATA code. */
+    getAircraft(iataCode: string): Promise<Aircraft | null>;
+    /** Batch lookup — preferred for hydrating offers / orders with many codes. */
+    getAirlines(iataCodes: string[]): Promise<Map<string, Airline>>;
+    getAirports(iataCodes: string[]): Promise<Map<string, Airport>>;
+    getAircraftBatch(iataCodes: string[]): Promise<Map<string, Aircraft>>;
+}
+/**
+ * Helper that hydrates a batch of distinct IATA codes once and returns a
+ * Map. Used internally by providers that fetch from a slow upstream and
+ * want to serve repeated lookups from an in-memory cache.
+ */
+export declare function dedupeCodes(codes: string[]): string[];
+//# 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;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,OAAO,CAAA;IACvB,cAAc,EAAE,OAAO,CAAA;IACvB,cAAc,EAAE,OAAO,CAAA;IACvB,gBAAgB,EAAE,OAAO,CAAA;IACzB,eAAe,EAAE,OAAO,CAAA;IACxB,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAA;IACnB,6DAA6D;IAC7D,cAAc,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAA;CAC5D;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAA;IAEhD,mEAAmE;IACnE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAErD,wCAAwC;IACxC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAErD,8CAA8C;IAC9C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IAEvD,8EAA8E;IAC9E,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/D,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/D,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;CACtE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAErD"}

package/dist/reference/contract.js

@@ -0,0 +1,26 @@
+/**
+ * `ReferenceDataProvider` contract — swappable provider for global
+ * reference data (airlines, airports, aircraft, currencies, countries).
+ *
+ * Per architecture §5.11.6 / §6, implementable at any layer:
+ *   - **In-deployment local Postgres** (the simplest case)
+ *   - Static JSON / CSV bundle
+ *   - Internal data lake / warehouse
+ *   - Third-party services (OAG, Cirium, RouteHappy)
+ *   - GDS-bundled reference subscriptions
+ *   - Voyant Data (the hosted default)
+ *
+ * No implementer is privileged. Operators can run a fully self-contained
+ * Voyant deployment with all reference data in their own database, no
+ * external dependency.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §6.
+ */
+/**
+ * Helper that hydrates a batch of distinct IATA codes once and returns a
+ * Map. Used internally by providers that fetch from a slow upstream and
+ * want to serve repeated lookups from an in-memory cache.
+ */
+export function dedupeCodes(codes) {
+    return Array.from(new Set(codes.filter((c) => c.length > 0)));
+}