@voyantjs/flights-contracts 0.96.0

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)));
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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 type { Aircraft, Airline, Airport, ReferenceDataCapabilities, ReferenceDataProvider } from "./contract.js";
+export interface StaticBundleReferenceData {
+    airlines?: Airline[];
+    airports?: Airport[];
+    aircraft?: Aircraft[];
+}
+export interface StaticBundleProviderOptions {
+    data: StaticBundleReferenceData;
+    /** Override capabilities; defaults are inferred from which arrays are populated. */
+    capabilities?: Partial<ReferenceDataCapabilities>;
+}
+/**
+ * Build a `ReferenceDataProvider` from in-memory bundles. Maps are built
+ * once at construction; lookups are O(1).
+ */
+export declare function createStaticBundleReferenceProvider(options: StaticBundleProviderOptions): ReferenceDataProvider;
+//# sourceMappingURL=static-bundle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static-bundle.d.ts","sourceRoot":"","sources":["../../src/reference/static-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,eAAe,CAAA;AAGtB,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,yBAAyB,CAAA;IAC/B,oFAAoF;IACpF,YAAY,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAA;CAClD;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,2BAA2B,GACnC,qBAAqB,CAuEvB"}

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/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@voyantjs/flights-contracts",
+  "version": "0.96.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contract/types": "./src/contract/types.ts",
+    "./contract/adapter": "./src/contract/adapter.ts",
+    "./contract/schemas": "./src/contract/schemas.ts",
+    "./contract/post-book-types": "./src/contract/post-book-types.ts",
+    "./reference/contract": "./src/reference/contract.ts",
+    "./reference/static-bundle": "./src/reference/static-bundle.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "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"
+      },
+      "./contract/schemas": {
+        "types": "./dist/contract/schemas.d.ts",
+        "import": "./dist/contract/schemas.js",
+        "default": "./dist/contract/schemas.js"
+      },
+      "./contract/post-book-types": {
+        "types": "./dist/contract/post-book-types.d.ts",
+        "import": "./dist/contract/post-book-types.js",
+        "default": "./dist/contract/post-book-types.js"
+      },
+      "./reference/contract": {
+        "types": "./dist/reference/contract.d.ts",
+        "import": "./dist/reference/contract.js",
+        "default": "./dist/reference/contract.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": {
+    "zod": "^4.3.6"
+  },
+  "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-contracts"
+  }
+}