@voyantjs/flights 0.19.0

package/dist/reference/static-bundle.js

@@ -0,0 +1,83 @@
+/**
+ * Static-bundle `ReferenceDataProvider`.
+ *
+ * Even simpler than a local-Postgres provider — ship a JSON / CSV bundle
+ * with the deployment, load it into memory at startup, serve from a `Map`.
+ * Appropriate for small operators with stable, narrow geographic scope and
+ * no need for refresh.
+ *
+ * No DB, no external service, no network call.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §6.2.
+ */
+import { dedupeCodes } from "./contract.js";
+/**
+ * Build a `ReferenceDataProvider` from in-memory bundles. Maps are built
+ * once at construction; lookups are O(1).
+ */
+export function createStaticBundleReferenceProvider(options) {
+    const airlines = new Map();
+    const airports = new Map();
+    const aircraft = new Map();
+    for (const airline of options.data.airlines ?? []) {
+        airlines.set(airline.iataCode, airline);
+    }
+    for (const airport of options.data.airports ?? []) {
+        airports.set(airport.iataCode, airport);
+    }
+    for (const ac of options.data.aircraft ?? []) {
+        aircraft.set(ac.iataCode, ac);
+    }
+    const inferredCapabilities = {
+        coversAirlines: airlines.size > 0,
+        coversAirports: airports.size > 0,
+        coversAircraft: aircraft.size > 0,
+        coversCurrencies: false,
+        coversCountries: false,
+        isReadOnly: true,
+        refreshCadence: "static",
+        ...options.capabilities,
+    };
+    return {
+        capabilities: inferredCapabilities,
+        async getAirline(iataCode) {
+            return airlines.get(iataCode) ?? null;
+        },
+        async getAirport(iataCode) {
+            return airports.get(iataCode) ?? null;
+        },
+        async getAircraft(iataCode) {
+            return aircraft.get(iataCode) ?? null;
+        },
+        async getAirlines(iataCodes) {
+            const codes = dedupeCodes(iataCodes);
+            const result = new Map();
+            for (const code of codes) {
+                const value = airlines.get(code);
+                if (value)
+                    result.set(code, value);
+            }
+            return result;
+        },
+        async getAirports(iataCodes) {
+            const codes = dedupeCodes(iataCodes);
+            const result = new Map();
+            for (const code of codes) {
+                const value = airports.get(code);
+                if (value)
+                    result.set(code, value);
+            }
+            return result;
+        },
+        async getAircraftBatch(iataCodes) {
+            const codes = dedupeCodes(iataCodes);
+            const result = new Map();
+            for (const code of codes) {
+                const value = aircraft.get(code);
+                if (value)
+                    result.set(code, value);
+            }
+            return result;
+        },
+    };
+}

package/dist/reference/static-bundle.test.d.ts

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

package/dist/reference/static-bundle.test.d.ts.map

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

package/dist/reference/static-bundle.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { createStaticBundleReferenceProvider } from "./static-bundle.js";
+const ba = { iataCode: "BA", icaoCode: "BAW", name: "British Airways", country: "GB" };
+const aa = { iataCode: "AA", icaoCode: "AAL", name: "American Airlines", country: "US" };
+const lhr = {
+    iataCode: "LHR",
+    name: "Heathrow",
+    city: "London",
+    country: "GB",
+    timezone: "Europe/London",
+};
+const jfk = {
+    iataCode: "JFK",
+    name: "John F. Kennedy",
+    city: "New York",
+    country: "US",
+    timezone: "America/New_York",
+};
+const b738 = {
+    iataCode: "738",
+    icaoCode: "B738",
+    name: "Boeing 737-800",
+    manufacturer: "Boeing",
+};
+describe("createStaticBundleReferenceProvider", () => {
+    it("infers capabilities from which arrays are populated", () => {
+        const provider = createStaticBundleReferenceProvider({
+            data: { airlines: [ba], airports: [lhr] },
+        });
+        expect(provider.capabilities.coversAirlines).toBe(true);
+        expect(provider.capabilities.coversAirports).toBe(true);
+        expect(provider.capabilities.coversAircraft).toBe(false);
+        expect(provider.capabilities.refreshCadence).toBe("static");
+        expect(provider.capabilities.isReadOnly).toBe(true);
+    });
+    it("getAirline returns the airline for a known code, null otherwise", async () => {
+        const provider = createStaticBundleReferenceProvider({ data: { airlines: [ba, aa] } });
+        expect(await provider.getAirline("BA")).toEqual(ba);
+        expect(await provider.getAirline("XX")).toBeNull();
+    });
+    it("getAirport / getAircraft work the same way", async () => {
+        const provider = createStaticBundleReferenceProvider({
+            data: { airports: [lhr, jfk], aircraft: [b738] },
+        });
+        expect(await provider.getAirport("LHR")).toEqual(lhr);
+        expect(await provider.getAircraft("738")).toEqual(b738);
+        expect(await provider.getAircraft("999")).toBeNull();
+    });
+    it("getAirlines (batch) returns a Map of found codes only", async () => {
+        const provider = createStaticBundleReferenceProvider({ data: { airlines: [ba, aa] } });
+        const result = await provider.getAirlines(["BA", "AA", "XX"]);
+        expect(result.size).toBe(2);
+        expect(result.get("BA")).toEqual(ba);
+        expect(result.get("AA")).toEqual(aa);
+        expect(result.has("XX")).toBe(false);
+    });
+    it("batch lookups deduplicate input codes", async () => {
+        const provider = createStaticBundleReferenceProvider({ data: { airlines: [ba] } });
+        const result = await provider.getAirlines(["BA", "BA", "BA"]);
+        expect(result.size).toBe(1);
+    });
+    it("empty input returns an empty Map", async () => {
+        const provider = createStaticBundleReferenceProvider({ data: {} });
+        expect((await provider.getAirlines([])).size).toBe(0);
+        expect((await provider.getAirports([])).size).toBe(0);
+        expect((await provider.getAircraftBatch([])).size).toBe(0);
+    });
+    it("capabilities can be overridden", () => {
+        const provider = createStaticBundleReferenceProvider({
+            data: { airlines: [ba] },
+            capabilities: { refreshCadence: "weekly" },
+        });
+        expect(provider.capabilities.refreshCadence).toBe("weekly");
+    });
+});

package/dist/snapshot.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Booking-time snapshot capture for flight orders.
+ *
+ * Flights are a partial-adoption vertical: they participate in the catalog
+ * plane's snapshot graph but skip overlay / index / drift / RAG. This
+ * helper turns a `FlightOffer` + `FlightOrder` pair into a
+ * `CaptureSnapshotInput` ready for `captureSnapshot` /
+ * `captureSnapshotGraph`.
+ *
+ * Mirrors the per-vertical pattern (`buildProductSnapshotInput`,
+ * `buildCruiseSnapshotInput`, etc.) but skips the resolved-view step
+ * because flights have no overlay store.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §5.1 for the
+ * full snapshot scope (frozen offer + order + segments + fare breakdown +
+ * pricing basis).
+ */
+import type { CaptureSnapshotInput } from "@voyantjs/catalog";
+import type { FlightOffer, FlightOrder } from "./contract/types.js";
+export interface BuildFlightSnapshotInputOptions {
+    /** The booked flight offer at booking time (frozen view). */
+    offer: FlightOffer;
+    /** The flight order returned by the adapter (PNR, ticket numbers, status). */
+    order: FlightOrder;
+    /** The source kind — typically `"voyant-connect"` or a direct adapter slug. */
+    sourceKind: string;
+    /** Source provider sub-identifier — e.g. `"hisky"`, `"amadeus"`. */
+    sourceProvider?: string;
+    /** The connection identifier the booking was placed against. */
+    sourceConnectionId?: string;
+    /** Optional override for the entity id; defaults to the adapter's `orderId`. */
+    entityId?: string;
+}
+/**
+ * Build a `CaptureSnapshotInput` from a flight offer + order. Use the
+ * result with `captureSnapshot` (single-flight bookings) or
+ * `captureSnapshotGraph` (composite bookings — flight inside a tour
+ * package, etc.).
+ *
+ * The `frozen_payload` carries the full FlightOffer and FlightOrder,
+ * structured as `{ offer, order }`, so refunds and post-book operations
+ * eight months later can read exactly what the customer paid for.
+ *
+ * The `pricing_basis` structured columns are populated from the offer's
+ * `totalPrice`. Taxes / fees / surcharges decomposition is left to the
+ * adapter — `FlightOffer` exposes `fareBreakdowns[]` per passenger which
+ * the caller can aggregate as needed and pass via `pricingBasis`.
+ */
+export declare function buildFlightSnapshotInput(options: BuildFlightSnapshotInputOptions): Omit<CaptureSnapshotInput, "bookingId">;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAgB,MAAM,mBAAmB,CAAA;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEnE,MAAM,WAAW,+BAA+B;IAC9C,6DAA6D;IAC7D,KAAK,EAAE,WAAW,CAAA;IAClB,8EAA8E;IAC9E,KAAK,EAAE,WAAW,CAAA;IAClB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAiCzC"}

package/dist/snapshot.js

@@ -0,0 +1,65 @@
+/**
+ * Booking-time snapshot capture for flight orders.
+ *
+ * Flights are a partial-adoption vertical: they participate in the catalog
+ * plane's snapshot graph but skip overlay / index / drift / RAG. This
+ * helper turns a `FlightOffer` + `FlightOrder` pair into a
+ * `CaptureSnapshotInput` ready for `captureSnapshot` /
+ * `captureSnapshotGraph`.
+ *
+ * Mirrors the per-vertical pattern (`buildProductSnapshotInput`,
+ * `buildCruiseSnapshotInput`, etc.) but skips the resolved-view step
+ * because flights have no overlay store.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §5.1 for the
+ * full snapshot scope (frozen offer + order + segments + fare breakdown +
+ * pricing basis).
+ */
+/**
+ * Build a `CaptureSnapshotInput` from a flight offer + order. Use the
+ * result with `captureSnapshot` (single-flight bookings) or
+ * `captureSnapshotGraph` (composite bookings — flight inside a tour
+ * package, etc.).
+ *
+ * The `frozen_payload` carries the full FlightOffer and FlightOrder,
+ * structured as `{ offer, order }`, so refunds and post-book operations
+ * eight months later can read exactly what the customer paid for.
+ *
+ * The `pricing_basis` structured columns are populated from the offer's
+ * `totalPrice`. Taxes / fees / surcharges decomposition is left to the
+ * adapter — `FlightOffer` exposes `fareBreakdowns[]` per passenger which
+ * the caller can aggregate as needed and pass via `pricingBasis`.
+ */
+export function buildFlightSnapshotInput(options) {
+    const { offer, order, sourceKind, sourceProvider, sourceConnectionId, entityId } = options;
+    const frozenPayload = {
+        offer,
+        order,
+    };
+    const pricingBasis = (() => {
+        const total = offer.totalPrice ?? order.totalPrice;
+        if (!total)
+            return undefined;
+        const baseAmount = Number.parseFloat(total.amount);
+        if (!Number.isFinite(baseAmount))
+            return undefined;
+        return {
+            base_amount: baseAmount,
+            taxes: 0, // adapter decomposes if it tracks taxes separately
+            fees: 0,
+            surcharges: 0,
+            currency: total.currency,
+            breakdown: { fareBreakdowns: offer.fareBreakdowns },
+        };
+    })();
+    return {
+        entityModule: "flights",
+        entityId: entityId ?? order.orderId,
+        sourceKind,
+        sourceProvider,
+        sourceConnectionId,
+        sourceRef: order.pnr ?? order.orderId,
+        frozenPayload,
+        pricingBasis,
+    };
+}

package/dist/snapshot.test.d.ts

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

package/dist/snapshot.test.d.ts.map

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

package/dist/snapshot.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { buildFlightSnapshotInput } from "./snapshot.js";
+const sampleOffer = {
+    offerId: "ofr_abc",
+    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" },
+};
+const sampleOrder = {
+    orderId: "ord_xyz",
+    pnr: "ABCDEF",
+    status: "ticketed",
+    offer: sampleOffer,
+    passengers: [],
+    totalPrice: { amount: "600", currency: "USD" },
+    createdAt: "2026-09-01T12:00:00Z",
+};
+describe("buildFlightSnapshotInput", () => {
+    it("composes a CaptureSnapshotInput with frozen offer + order", () => {
+        const input = buildFlightSnapshotInput({
+            offer: sampleOffer,
+            order: sampleOrder,
+            sourceKind: "voyant-connect",
+            sourceProvider: "amadeus",
+            sourceConnectionId: "conn_xyz",
+        });
+        expect(input.entityModule).toBe("flights");
+        expect(input.entityId).toBe("ord_xyz");
+        expect(input.sourceKind).toBe("voyant-connect");
+        expect(input.sourceProvider).toBe("amadeus");
+        expect(input.sourceConnectionId).toBe("conn_xyz");
+        // sourceRef defaults to PNR when present
+        expect(input.sourceRef).toBe("ABCDEF");
+    });
+    it("falls back to orderId for sourceRef when PNR is missing", () => {
+        const orderNoPnr = { ...sampleOrder, pnr: undefined };
+        const input = buildFlightSnapshotInput({
+            offer: sampleOffer,
+            order: orderNoPnr,
+            sourceKind: "direct:hisky",
+        });
+        expect(input.sourceRef).toBe("ord_xyz");
+    });
+    it("populates structured pricing columns from offer.totalPrice", () => {
+        const input = buildFlightSnapshotInput({
+            offer: sampleOffer,
+            order: sampleOrder,
+            sourceKind: "owned",
+        });
+        expect(input.pricingBasis).toBeDefined();
+        expect(input.pricingBasis?.base_amount).toBe(600);
+        expect(input.pricingBasis?.currency).toBe("USD");
+        expect(input.pricingBasis?.breakdown).toEqual({
+            fareBreakdowns: sampleOffer.fareBreakdowns,
+        });
+    });
+    it("frozen_payload contains the full offer + order pair", () => {
+        const input = buildFlightSnapshotInput({
+            offer: sampleOffer,
+            order: sampleOrder,
+            sourceKind: "owned",
+        });
+        expect(input.frozenPayload).toEqual({ offer: sampleOffer, order: sampleOrder });
+    });
+    it("entityId can be overridden (e.g. for tour-package composite bookings)", () => {
+        const input = buildFlightSnapshotInput({
+            offer: sampleOffer,
+            order: sampleOrder,
+            sourceKind: "voyant-connect",
+            entityId: "custom_entity_xyz",
+        });
+        expect(input.entityId).toBe("custom_entity_xyz");
+    });
+});

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@voyantjs/flights",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contract/types": "./src/contract/types.ts",
+    "./contract/adapter": "./src/contract/adapter.ts",
+    "./orchestration/fingerprint": "./src/orchestration/fingerprint.ts",
+    "./orchestration/fan-out": "./src/orchestration/fan-out.ts",
+    "./snapshot": "./src/snapshot.ts",
+    "./reference/contract": "./src/reference/contract.ts",
+    "./reference/local-postgres": "./src/reference/local-postgres.ts",
+    "./reference/static-bundle": "./src/reference/static-bundle.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./contract/types": {
+        "types": "./dist/contract/types.d.ts",
+        "import": "./dist/contract/types.js",
+        "default": "./dist/contract/types.js"
+      },
+      "./contract/adapter": {
+        "types": "./dist/contract/adapter.d.ts",
+        "import": "./dist/contract/adapter.js",
+        "default": "./dist/contract/adapter.js"
+      },
+      "./orchestration/fingerprint": {
+        "types": "./dist/orchestration/fingerprint.d.ts",
+        "import": "./dist/orchestration/fingerprint.js",
+        "default": "./dist/orchestration/fingerprint.js"
+      },
+      "./orchestration/fan-out": {
+        "types": "./dist/orchestration/fan-out.d.ts",
+        "import": "./dist/orchestration/fan-out.js",
+        "default": "./dist/orchestration/fan-out.js"
+      },
+      "./snapshot": {
+        "types": "./dist/snapshot.d.ts",
+        "import": "./dist/snapshot.js",
+        "default": "./dist/snapshot.js"
+      },
+      "./reference/contract": {
+        "types": "./dist/reference/contract.d.ts",
+        "import": "./dist/reference/contract.js",
+        "default": "./dist/reference/contract.js"
+      },
+      "./reference/local-postgres": {
+        "types": "./dist/reference/local-postgres.d.ts",
+        "import": "./dist/reference/local-postgres.js",
+        "default": "./dist/reference/local-postgres.js"
+      },
+      "./reference/static-bundle": {
+        "types": "./dist/reference/static-bundle.d.ts",
+        "import": "./dist/reference/static-bundle.js",
+        "default": "./dist/reference/static-bundle.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "dependencies": {
+    "@voyantjs/db": "workspace:*",
+    "@voyantjs/catalog": "workspace:*",
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@voyantjs/voyant-typescript-config": "workspace:*",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/flights"
+  }
+}