@voyantjs/flights 0.19.0

package/dist/reference/local-postgres.d.ts

@@ -0,0 +1,390 @@
+/**
+ * In-deployment local-Postgres `ReferenceDataProvider`.
+ *
+ * The simplest possible implementation: reference data lives as ordinary
+ * tables in the operator's own Voyant Postgres database. Population is
+ * a one-time seed migration / weekly batch refresh / CSV import — whatever
+ * suits the deployment. **No external service, no network call.**
+ *
+ * This is a fully valid first-party implementation, not a fallback. For
+ * many tour operators / DMCs, this is the right choice — they don't want
+ * a hosted dependency just for IATA lookups.
+ *
+ * The schema below is exposed as drizzle table definitions; operators can
+ * pull them into their `drizzle.config.ts` schema list to generate
+ * migrations, or apply the SQL directly.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §6.2.
+ */
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import type { ReferenceDataCapabilities, ReferenceDataProvider } from "./contract.js";
+/**
+ * `reference_airlines` — IATA-code-keyed airline catalog. Populate from a
+ * public IATA dataset, a CSV import, or curated by the operator.
+ */
+export declare const referenceAirlines: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "reference_airlines";
+    schema: undefined;
+    columns: {
+        iataCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "iata_code";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        icaoCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "icao_code";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        country: import("drizzle-orm/pg-core").PgColumn<{
+            name: "country";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        logoUrl: import("drizzle-orm/pg-core").PgColumn<{
+            name: "logo_url";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        alliance: import("drizzle-orm/pg-core").PgColumn<{
+            name: "alliance";
+            tableName: "reference_airlines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * `reference_airports` — IATA-code-keyed airport catalog with geo + tz.
+ */
+export declare const referenceAirports: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "reference_airports";
+    schema: undefined;
+    columns: {
+        iataCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "iata_code";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        icaoCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "icao_code";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        city: import("drizzle-orm/pg-core").PgColumn<{
+            name: "city";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        country: import("drizzle-orm/pg-core").PgColumn<{
+            name: "country";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timezone: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timezone";
+            tableName: "reference_airports";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        latitude: import("drizzle-orm/pg-core").PgColumn<{
+            name: "latitude";
+            tableName: "reference_airports";
+            dataType: "number";
+            columnType: "PgReal";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        longitude: import("drizzle-orm/pg-core").PgColumn<{
+            name: "longitude";
+            tableName: "reference_airports";
+            dataType: "number";
+            columnType: "PgReal";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * `reference_aircraft` — IATA-code-keyed aircraft type catalog.
+ */
+export declare const referenceAircraft: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "reference_aircraft";
+    schema: undefined;
+    columns: {
+        iataCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "iata_code";
+            tableName: "reference_aircraft";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        icaoCode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "icao_code";
+            tableName: "reference_aircraft";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "reference_aircraft";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        manufacturer: import("drizzle-orm/pg-core").PgColumn<{
+            name: "manufacturer";
+            tableName: "reference_aircraft";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        typicalSeats: import("drizzle-orm/pg-core").PgColumn<{
+            name: "typical_seats";
+            tableName: "reference_aircraft";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export interface LocalPostgresReferenceProviderOptions {
+    db: AnyDrizzleDb;
+    /**
+     * Override capabilities — operators that don't populate aircraft data
+     * can declare `coversAircraft: false` to fail fast on aircraft lookups.
+     * Default: covers airlines + airports + aircraft, read-only at the
+     * provider layer (operators write directly to the tables out-of-band).
+     */
+    capabilities?: Partial<ReferenceDataCapabilities>;
+}
+/**
+ * Build a `ReferenceDataProvider` backed by ordinary Postgres tables in
+ * the operator's own Voyant database. No external service.
+ */
+export declare function createLocalPostgresReferenceProvider(options: LocalPostgresReferenceProviderOptions): ReferenceDataProvider;
+//# sourceMappingURL=local-postgres.d.ts.map

package/dist/reference/local-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-postgres.d.ts","sourceRoot":"","sources":["../../src/reference/local-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIhD,OAAO,KAAK,EAIV,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,eAAe,CAAA;AAOtB;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS5B,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM5B,CAAA;AAMF,MAAM,WAAW,qCAAqC;IACpD,EAAE,EAAE,YAAY,CAAA;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAA;CAClD;AAYD;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,qCAAqC,GAC7C,qBAAqB,CAwFvB"}

package/dist/reference/local-postgres.js

@@ -0,0 +1,194 @@
+/**
+ * In-deployment local-Postgres `ReferenceDataProvider`.
+ *
+ * The simplest possible implementation: reference data lives as ordinary
+ * tables in the operator's own Voyant Postgres database. Population is
+ * a one-time seed migration / weekly batch refresh / CSV import — whatever
+ * suits the deployment. **No external service, no network call.**
+ *
+ * This is a fully valid first-party implementation, not a fallback. For
+ * many tour operators / DMCs, this is the right choice — they don't want
+ * a hosted dependency just for IATA lookups.
+ *
+ * The schema below is exposed as drizzle table definitions; operators can
+ * pull them into their `drizzle.config.ts` schema list to generate
+ * migrations, or apply the SQL directly.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §6.2.
+ */
+import { eq, inArray } from "drizzle-orm";
+import { integer, pgTable, real, text } from "drizzle-orm/pg-core";
+import { dedupeCodes } from "./contract.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Drizzle table schemas
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * `reference_airlines` — IATA-code-keyed airline catalog. Populate from a
+ * public IATA dataset, a CSV import, or curated by the operator.
+ */
+export const referenceAirlines = pgTable("reference_airlines", {
+    iataCode: text("iata_code").primaryKey(),
+    icaoCode: text("icao_code"),
+    name: text("name").notNull(),
+    country: text("country"),
+    logoUrl: text("logo_url"),
+    alliance: text("alliance"),
+});
+/**
+ * `reference_airports` — IATA-code-keyed airport catalog with geo + tz.
+ */
+export const referenceAirports = pgTable("reference_airports", {
+    iataCode: text("iata_code").primaryKey(),
+    icaoCode: text("icao_code"),
+    name: text("name").notNull(),
+    city: text("city").notNull(),
+    country: text("country").notNull(),
+    timezone: text("timezone"),
+    latitude: real("latitude"),
+    longitude: real("longitude"),
+});
+/**
+ * `reference_aircraft` — IATA-code-keyed aircraft type catalog.
+ */
+export const referenceAircraft = pgTable("reference_aircraft", {
+    iataCode: text("iata_code").primaryKey(),
+    icaoCode: text("icao_code"),
+    name: text("name").notNull(),
+    manufacturer: text("manufacturer"),
+    typicalSeats: integer("typical_seats"),
+});
+const DEFAULT_CAPABILITIES = {
+    coversAirlines: true,
+    coversAirports: true,
+    coversAircraft: true,
+    coversCurrencies: false,
+    coversCountries: false,
+    isReadOnly: true, // provider doesn't expose writes; operator manages tables out-of-band
+    refreshCadence: "weekly", // operator-driven cadence; static if seeded once
+};
+/**
+ * Build a `ReferenceDataProvider` backed by ordinary Postgres tables in
+ * the operator's own Voyant database. No external service.
+ */
+export function createLocalPostgresReferenceProvider(options) {
+    const { db } = options;
+    const capabilities = {
+        ...DEFAULT_CAPABILITIES,
+        ...options.capabilities,
+    };
+    return {
+        capabilities,
+        async getAirline(iataCode) {
+            if (!capabilities.coversAirlines)
+                return null;
+            const rows = await db
+                .select()
+                .from(referenceAirlines)
+                .where(eq(referenceAirlines.iataCode, iataCode))
+                .limit(1);
+            const row = rows[0];
+            return row ? rowToAirline(row) : null;
+        },
+        async getAirport(iataCode) {
+            if (!capabilities.coversAirports)
+                return null;
+            const rows = await db
+                .select()
+                .from(referenceAirports)
+                .where(eq(referenceAirports.iataCode, iataCode))
+                .limit(1);
+            const row = rows[0];
+            return row ? rowToAirport(row) : null;
+        },
+        async getAircraft(iataCode) {
+            if (!capabilities.coversAircraft)
+                return null;
+            const rows = await db
+                .select()
+                .from(referenceAircraft)
+                .where(eq(referenceAircraft.iataCode, iataCode))
+                .limit(1);
+            const row = rows[0];
+            return row ? rowToAircraft(row) : null;
+        },
+        async getAirlines(iataCodes) {
+            if (!capabilities.coversAirlines)
+                return new Map();
+            const codes = dedupeCodes(iataCodes);
+            if (codes.length === 0)
+                return new Map();
+            const rows = await db
+                .select()
+                .from(referenceAirlines)
+                .where(inArray(referenceAirlines.iataCode, codes));
+            const result = new Map();
+            for (const row of rows) {
+                result.set(row.iataCode, rowToAirline(row));
+            }
+            return result;
+        },
+        async getAirports(iataCodes) {
+            if (!capabilities.coversAirports)
+                return new Map();
+            const codes = dedupeCodes(iataCodes);
+            if (codes.length === 0)
+                return new Map();
+            const rows = await db
+                .select()
+                .from(referenceAirports)
+                .where(inArray(referenceAirports.iataCode, codes));
+            const result = new Map();
+            for (const row of rows) {
+                result.set(row.iataCode, rowToAirport(row));
+            }
+            return result;
+        },
+        async getAircraftBatch(iataCodes) {
+            if (!capabilities.coversAircraft)
+                return new Map();
+            const codes = dedupeCodes(iataCodes);
+            if (codes.length === 0)
+                return new Map();
+            const rows = await db
+                .select()
+                .from(referenceAircraft)
+                .where(inArray(referenceAircraft.iataCode, codes));
+            const result = new Map();
+            for (const row of rows) {
+                result.set(row.iataCode, rowToAircraft(row));
+            }
+            return result;
+        },
+    };
+}
+function rowToAirline(row) {
+    return {
+        iataCode: row.iataCode,
+        icaoCode: row.icaoCode ?? undefined,
+        name: row.name,
+        country: row.country ?? undefined,
+        logoUrl: row.logoUrl ?? undefined,
+        alliance: row.alliance ?? undefined,
+    };
+}
+function rowToAirport(row) {
+    return {
+        iataCode: row.iataCode,
+        icaoCode: row.icaoCode ?? undefined,
+        name: row.name,
+        city: row.city,
+        country: row.country,
+        timezone: row.timezone ?? undefined,
+        latitude: row.latitude ?? undefined,
+        longitude: row.longitude ?? undefined,
+    };
+}
+function rowToAircraft(row) {
+    return {
+        iataCode: row.iataCode,
+        icaoCode: row.icaoCode ?? undefined,
+        name: row.name,
+        manufacturer: row.manufacturer ?? undefined,
+        typicalSeats: row.typicalSeats ?? undefined,
+    };
+}

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"}