@voyantjs/flights 0.19.0

package/README.md

@@ -0,0 +1,98 @@
+# @voyantjs/flights
+
+Phase 3 of the catalog plane. The flights vertical — a partial-adoption module
+for live-API flight search and booking.
+
+See [`docs/architecture/catalog-flights-architecture.md`](../../docs/architecture/catalog-flights-architecture.md)
+for the full design.
+
+## Install
+
+```bash
+pnpm add @voyantjs/flights
+```
+
+## What's in the box
+
+- **`./contract/types`** — `FlightOffer`, `FlightOrder`, `FlightSegment`,
+  `FlightSearchRequest`, `FlightBookRequest`, capability ids, `paymentIntent`
+  discriminated union. Shapes mirror voyant-cloud's `connect-flight-contract`
+  so adapters are portable across `voyant-cloud` and Voyant Catalog.
+- **`./contract/adapter`** — `FlightConnectorAdapter` interface (5 core methods
+  + capability declarations). Provider-agnostic; implementations come from
+  Voyant Connect, third-party providers, or operator-built adapters.
+- **`./orchestration/fingerprint`** — Itinerary fingerprint helper. Two
+  providers selling the same flight produce identical fingerprints.
+- **`./orchestration/fan-out`** — Multi-connection fan-out search:
+  parallel `searchFlights` across all of an operator's flight connections,
+  per-provider timeout + circuit breaker, dedupe by itinerary fingerprint,
+  merged result with `cheapest` + `alternates[]`.
+- **`./snapshot`** — Booking-time snapshot capture. Builds a
+  `CaptureSnapshotInput` for the catalog plane's `captureSnapshot` /
+  `captureSnapshotGraph` from a flight `FlightOffer` + `FlightOrder` pair.
+- **`./reference/contract`** — `ReferenceDataProvider` contract (airlines,
+  airports, aircraft). Implementable at any layer.
+- **`./reference/local-postgres`** — Reference data from plain Postgres
+  tables in the operator's own database. **No external service, no network
+  call.** The simplest deployment option.
+- **`./reference/static-bundle`** — Reference data from a bundled JSON / CSV.
+
+## Phase relationship
+
+Phase 3 is independent of Phase 2 (RAG). Either can ship first; both build on
+Phase 1 (`@voyantjs/catalog`).
+
+Flights opt **in** to:
+- Booking snapshot graph (the most important participation)
+- Provenance shape
+- Webhook events
+- Source disconnection lifecycle
+
+Flights opt **out** of:
+- Search index projection (live fan-out replaces it)
+- Editorial overlays (no marketing copy on a flight)
+- Embeddings / RAG (Phase 2 explicitly excludes flights)
+- Pricing tiers (built into the multi-connection fan-out itself)
+- Drift detection (live by definition)
+
+## Usage
+
+### Multi-connection search
+
+```typescript
+import { fanOutFlightSearch } from "@voyantjs/flights/orchestration/fan-out"
+
+const result = await fanOutFlightSearch({
+  adapters: [hiskyAdapter, amadeusAdapter, charterConsolidatorAdapter],
+  request: {
+    slices: [
+      { origin: "LHR", destination: "JFK", departureDate: "2026-10-15" },
+      { origin: "JFK", destination: "LHR", departureDate: "2026-10-22" },
+    ],
+    passengers: { adults: 2 },
+    cabin: "economy",
+  },
+  perConnectionTimeoutMs: 5000,
+})
+
+// result.offers — merged offers across all connections, deduped by
+// itinerary fingerprint, sorted by cheapest price ascending.
+// result.perConnection — status + latency per connection.
+```
+
+### Reference data — operator's own Postgres tables
+
+```typescript
+import {
+  createLocalPostgresReferenceProvider,
+  createReferenceDataTables,
+} from "@voyantjs/flights/reference/local-postgres"
+
+// Schema lives in the operator's own DB. No external service required.
+const reference = createLocalPostgresReferenceProvider({ db })
+
+const ba = await reference.getAirline("BA")
+// → { iataCode: "BA", icaoCode: "BAW", name: "British Airways", country: "GB" }
+```
+
+See `docs/architecture/catalog-flights-architecture.md` for the full design.

package/dist/contract/adapter.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `FlightConnectorAdapter` contract — the seam through which any flight
+ * provider integrates with Voyant.
+ *
+ * Five core methods every adapter must implement; capability-gated
+ * methods exist as optional members on the interface and stub with
+ * `CAPABILITY_NOT_SUPPORTED` if the adapter doesn't declare them.
+ *
+ * Implementations come from anywhere — Voyant Connect, a wholesaler's own
+ * engineering team, a cruise line direct API, an operator-built GDS
+ * connector, a third-party integrator. No implementer is privileged.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §3.
+ */
+import type { FlightBookRequest, FlightCapability, FlightOffer, FlightOrder, FlightSearchRequest } from "./types.js";
+/**
+ * Context passed to every adapter call. Identifies the connection and
+ * carries credentials, optional point-of-sale, tracing identifiers.
+ */
+export interface FlightAdapterContext {
+    connectionId: string;
+    credentials?: Record<string, string>;
+    /** Operator's IATA office id / pseudo-city / point-of-sale, when applicable. */
+    pointOfSale?: string;
+    correlationId?: string;
+}
+export interface FlightSearchResponse {
+    offers: FlightOffer[];
+    /** Provider-specific data, opaque to the consumer. */
+    providerData?: Record<string, unknown>;
+}
+export interface FlightPriceRequest {
+    offerId: string;
+    /** Some providers require the offer payload echoed back to re-price. */
+    offer?: FlightOffer;
+}
+export interface FlightPriceResponse {
+    offer: FlightOffer;
+    /** Whether the offer's price/availability is still valid for booking. */
+    valid: boolean;
+    /** When `valid: false`, why the offer was invalidated. */
+    invalidReason?: string;
+}
+export interface FlightBookResponse {
+    order: FlightOrder;
+}
+export interface FlightGetOrderResponse {
+    order: FlightOrder;
+}
+export interface FlightCancelResponse {
+    order: FlightOrder;
+    refundedAmount?: {
+        amount: string;
+        currency: string;
+    };
+}
+export type FlightCancelReason = "customer_request" | "schedule_change" | "operational" | "fraud";
+/**
+ * Capability declaration returned by the adapter at registration time.
+ * The orchestration layer reads `capabilities` to route requests and to
+ * fail fast on unsupported operations.
+ */
+export interface FlightAdapterCapabilities {
+    /** Provider identifier — e.g. `"hisky"`, `"amadeus"`, `"duffel"`, `"sabre"`, `"travelport-ndc"`. */
+    provider: string;
+    /** Capabilities declared by this connection. */
+    declared: FlightCapability[];
+    /**
+     * Maximum slices per search request supported. Many providers cap at
+     * 1 (single-carrier point-to-point), 2 (round-trip), or 4-6 (multi-city).
+     */
+    maxSlicesPerSearch?: number;
+    /**
+     * Default per-source timeout hint for the orchestration layer.
+     */
+    defaultTimeoutMs?: number;
+}
+/**
+ * The flight connector contract. Five core methods + optional capability-
+ * gated methods. Adapters that don't support a capability either omit the
+ * method or have it throw `CAPABILITY_NOT_SUPPORTED`.
+ */
+export interface FlightConnectorAdapter {
+    readonly capabilities: FlightAdapterCapabilities;
+    /** Search flights matching the request's slices + passengers + cabin. */
+    searchFlights(ctx: FlightAdapterContext, request: FlightSearchRequest): Promise<FlightSearchResponse>;
+    /** Re-price an offer immediately before booking. */
+    priceOffer(ctx: FlightAdapterContext, request: FlightPriceRequest): Promise<FlightPriceResponse>;
+    /**
+     * Book the flight. Behavior depends on `paymentIntent`:
+     *   - `hold` → returns order with status `confirmed`; caller must call
+     *     `ticketOrder` later (capability-gated).
+     *   - `card` / `ticket_on_credit` → returns order with status `ticketed`.
+     */
+    bookFlight(ctx: FlightAdapterContext, request: FlightBookRequest): Promise<FlightBookResponse>;
+    /** Get an order by id (for status checks, post-book operations). */
+    getOrder(ctx: FlightAdapterContext, orderId: string): Promise<FlightGetOrderResponse>;
+    /** Cancel an order. */
+    cancelOrder(ctx: FlightAdapterContext, orderId: string, reason?: FlightCancelReason): Promise<FlightCancelResponse>;
+    /** `flight/holds` — promote a held order to ticketed. */
+    ticketOrder?(ctx: FlightAdapterContext, orderId: string): Promise<FlightGetOrderResponse>;
+}
+/**
+ * Standard error code for capability-gated methods that aren't supported
+ * by the adapter. Mirrors voyant-cloud's convention so behavior is
+ * portable across runtimes.
+ */
+export declare const CAPABILITY_NOT_SUPPORTED: "CAPABILITY_NOT_SUPPORTED";
+export declare class FlightCapabilityNotSupportedError extends Error {
+    readonly provider: string;
+    readonly capability: FlightCapability;
+    readonly operation: string;
+    readonly code: "CAPABILITY_NOT_SUPPORTED";
+    constructor(provider: string, capability: FlightCapability, operation: string);
+}
+/**
+ * Helper for adapters that want to short-circuit at the start of a method
+ * when a required capability isn't declared.
+ */
+export declare function requireCapability(capabilities: FlightAdapterCapabilities, capability: FlightCapability, operation: string): void;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/contract/adapter.ts"],"names":[],"mappings":"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"}

package/dist/contract/adapter.js

@@ -0,0 +1,43 @@
+/**
+ * `FlightConnectorAdapter` contract — the seam through which any flight
+ * provider integrates with Voyant.
+ *
+ * Five core methods every adapter must implement; capability-gated
+ * methods exist as optional members on the interface and stub with
+ * `CAPABILITY_NOT_SUPPORTED` if the adapter doesn't declare them.
+ *
+ * Implementations come from anywhere — Voyant Connect, a wholesaler's own
+ * engineering team, a cruise line direct API, an operator-built GDS
+ * connector, a third-party integrator. No implementer is privileged.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §3.
+ */
+/**
+ * Standard error code for capability-gated methods that aren't supported
+ * by the adapter. Mirrors voyant-cloud's convention so behavior is
+ * portable across runtimes.
+ */
+export const CAPABILITY_NOT_SUPPORTED = "CAPABILITY_NOT_SUPPORTED";
+export class FlightCapabilityNotSupportedError extends Error {
+    provider;
+    capability;
+    operation;
+    code = CAPABILITY_NOT_SUPPORTED;
+    constructor(provider, capability, operation) {
+        super(`Flight provider "${provider}" does not declare capability "${capability}" (operation: ${operation}). ` +
+            `Either configure the request to skip this operation or register a connector that supports it.`);
+        this.provider = provider;
+        this.capability = capability;
+        this.operation = operation;
+        this.name = "FlightCapabilityNotSupportedError";
+    }
+}
+/**
+ * Helper for adapters that want to short-circuit at the start of a method
+ * when a required capability isn't declared.
+ */
+export function requireCapability(capabilities, capability, operation) {
+    if (!capabilities.declared.includes(capability)) {
+        throw new FlightCapabilityNotSupportedError(capabilities.provider, capability, operation);
+    }
+}

package/dist/contract/types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Flight contract types — shapes mirror voyant-cloud's `connect-flight-contract`
+ * so adapters are portable across Voyant Cloud and Voyant Catalog deployments.
+ *
+ * These are the load-bearing data structures: `FlightSegment`, `Itinerary`,
+ * `FlightOffer`, `FlightOrder`, `FlightSearchRequest`, `FlightBookRequest`,
+ * the `paymentIntent` discriminated union, and the capability id namespace.
+ *
+ * **Drift policy:** when voyant-cloud's `connect-flight-contract` evolves,
+ * mirror the additive changes here. Breaking changes flow through a
+ * coordinated release across both packages.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §3.
+ */
+/** Cabin class. Standard IATA-aligned vocabulary. */
+export type CabinClass = "economy" | "premium_economy" | "business" | "first";
+/** Passenger type. Affects fare lookup and ticketing rules. */
+export type PassengerType = "adult" | "child" | "infant" | "senior" | "youth";
+/** Currency + amount. */
+export interface Money {
+    amount: string;
+    currency: string;
+}
+/**
+ * One segment of an itinerary — from departure airport to arrival airport
+ * on a specific carrier + flight number.
+ */
+export interface FlightSegment {
+    segmentId: string;
+    carrierCode: string;
+    flightNumber: string;
+    /** Operating carrier when different from the marketing carrier. */
+    operatingCarrierCode?: string;
+    operatingFlightNumber?: string;
+    departure: {
+        iataCode: string;
+        terminal?: string;
+        at: string;
+    };
+    arrival: {
+        iataCode: string;
+        terminal?: string;
+        at: string;
+    };
+    duration?: string;
+    aircraft?: string;
+    cabin: CabinClass;
+    fareClass?: string;
+    fareBasis?: string;
+    status?: string;
+    /** Provider-specific data — opaque round-trip. */
+    providerData?: Record<string, unknown>;
+}
+/**
+ * One itinerary (journey leg) — a sequence of segments. Round-trip and
+ * multi-city offers have multiple itineraries.
+ */
+export interface Itinerary {
+    segments: FlightSegment[];
+    duration?: string;
+}
+/** Per-passenger fare breakdown line. */
+export interface FareBreakdown {
+    passengerType: PassengerType;
+    passengerCount: number;
+    baseFare: Money;
+    taxes: Money;
+    fees?: Money;
+    total: Money;
+    fareFamily?: string;
+}
+/**
+ * A priced flight proposition. Returned by `searchFlights`; passed back to
+ * `priceOffer` and `bookFlight`. Always vertical-specific — never collapse
+ * into a generic `Offer` (per architecture §1.1 and `UBIQUITOUS_LANGUAGE.md`).
+ */
+export interface FlightOffer {
+    offerId: string;
+    /** Source identifier — typically the connection id or adapter slug. */
+    source: string;
+    itineraries: Itinerary[];
+    fareBreakdowns: FareBreakdown[];
+    totalPrice: Money;
+    validatingCarrier?: string;
+    /** ISO 8601 — when the offer expires (provider may refuse to book after). */
+    expiresAt?: string;
+    /** ISO 8601 — last ticketing date. */
+    lastTicketingDate?: string;
+    instantTicketing?: boolean;
+    /** Provider-specific data — opaque round-trip. */
+    providerData?: Record<string, unknown>;
+}
+/**
+ * One slice of a search request. Slice count determines trip type:
+ *   - 1 slice  → one-way
+ *   - 2 slices → round-trip
+ *   - 3+       → multi-city / open-jaw
+ */
+export interface FlightSlice {
+    origin: string;
+    destination: string;
+    departureDate: string;
+    departureTimeWindow?: {
+        earliest?: string;
+        latest?: string;
+    };
+}
+export interface PassengerCounts {
+    adults: number;
+    children?: number;
+    infants?: number;
+}
+export interface FlightSearchRequest {
+    slices: FlightSlice[];
+    passengers: PassengerCounts;
+    cabin?: CabinClass;
+    searchOptions?: {
+        directOnly?: boolean;
+        maxStops?: number;
+        minConnectionMinutes?: number;
+        includeCarriers?: string[];
+        excludeCarriers?: string[];
+    };
+}
+/**
+ * Intent-driven booking — caller declares what they want, system honors
+ * or rejects per the adapter's declared capabilities. Default if omitted:
+ * `{ type: "hold" }`.
+ */
+export type PaymentIntent = {
+    type: "hold";
+} | {
+    type: "card";
+    token: string;
+    cardholderName?: string;
+    billingAddress?: BillingAddress;
+} | {
+    type: "ticket_on_credit";
+    iataCode?: string;
+};
+export interface BillingAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode?: string;
+    countryCode: string;
+}
+export interface FlightPassenger {
+    passengerId: string;
+    type: PassengerType;
+    givenNames: string;
+    surname: string;
+    birthDate: string;
+    gender?: "M" | "F" | "X";
+    email?: string;
+    phone?: string;
+    documents?: TravelDocument[];
+}
+export interface TravelDocument {
+    type: "passport" | "national_id" | "visa";
+    number: string;
+    countryOfIssue: string;
+    countryOfNationality?: string;
+    expiryDate?: string;
+}
+export interface FlightBookRequest {
+    offerId: string;
+    /** Provider-specific re-priced offer payload, when the adapter requires it. */
+    offer?: FlightOffer;
+    passengers: FlightPassenger[];
+    contact?: {
+        email?: string;
+        phone?: string;
+    };
+    paymentIntent?: PaymentIntent;
+}
+export type FlightOrderStatus = "pending" | "confirmed" | "ticketed" | "cancelled" | "failed";
+export interface FlightTicket {
+    ticketNumber: string;
+    passengerId: string;
+    segmentIds: string[];
+    status?: string;
+}
+export interface FlightOrder {
+    orderId: string;
+    /** PNR / record locator. */
+    pnr?: string;
+    status: FlightOrderStatus;
+    offer: FlightOffer;
+    passengers: FlightPassenger[];
+    contact?: {
+        email?: string;
+        phone?: string;
+    };
+    tickets?: FlightTicket[];
+    totalPrice: Money;
+    /** ISO 8601 — deadline before the hold expires (held orders only). */
+    paymentDeadline?: string;
+    createdAt: string;
+    updatedAt?: string;
+    /** Provider-specific data — opaque round-trip. */
+    providerData?: Record<string, unknown>;
+}
+/**
+ * Capability ids declared per connection. Adapters that don't declare a
+ * capability stub the corresponding method with `CAPABILITY_NOT_SUPPORTED`.
+ */
+export declare const FLIGHT_CAPABILITIES: {
+    readonly HOLDS: "flight/holds";
+    readonly SEATMAP: "flight/seatmap";
+    readonly SEAT_SELECTION: "flight/seat-selection";
+    readonly ANCILLARIES: "flight/ancillaries";
+    readonly CHECKIN: "flight/checkin";
+    readonly EXCHANGE: "flight/exchange";
+    readonly REFUND: "flight/refund";
+    readonly VOID: "flight/void";
+    readonly SSR: "flight/ssr";
+    readonly BRANDED_FARES: "flight/branded-fares";
+};
+export type FlightCapability = (typeof FLIGHT_CAPABILITIES)[keyof typeof FLIGHT_CAPABILITIES];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contract/types.ts"],"names":[],"mappings":"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"}

package/dist/contract/types.js

@@ -0,0 +1,33 @@
+/**
+ * Flight contract types — shapes mirror voyant-cloud's `connect-flight-contract`
+ * so adapters are portable across Voyant Cloud and Voyant Catalog deployments.
+ *
+ * These are the load-bearing data structures: `FlightSegment`, `Itinerary`,
+ * `FlightOffer`, `FlightOrder`, `FlightSearchRequest`, `FlightBookRequest`,
+ * the `paymentIntent` discriminated union, and the capability id namespace.
+ *
+ * **Drift policy:** when voyant-cloud's `connect-flight-contract` evolves,
+ * mirror the additive changes here. Breaking changes flow through a
+ * coordinated release across both packages.
+ *
+ * See `docs/architecture/catalog-flights-architecture.md` §3.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Capability ids
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Capability ids declared per connection. Adapters that don't declare a
+ * capability stub the corresponding method with `CAPABILITY_NOT_SUPPORTED`.
+ */
+export const FLIGHT_CAPABILITIES = {
+    HOLDS: "flight/holds",
+    SEATMAP: "flight/seatmap",
+    SEAT_SELECTION: "flight/seat-selection",
+    ANCILLARIES: "flight/ancillaries",
+    CHECKIN: "flight/checkin",
+    EXCHANGE: "flight/exchange",
+    REFUND: "flight/refund",
+    VOID: "flight/void",
+    SSR: "flight/ssr",
+    BRANDED_FARES: "flight/branded-fares",
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CAPABILITY_NOT_SUPPORTED, type FlightAdapterCapabilities, type FlightAdapterContext, type FlightBookResponse, type FlightCancelReason, type FlightCancelResponse, FlightCapabilityNotSupportedError, type FlightConnectorAdapter, type FlightGetOrderResponse, type FlightPriceRequest, type FlightPriceResponse, type FlightSearchResponse, requireCapability, } from "./contract/adapter.js";
+export * from "./contract/types.js";
+export { type ConnectionResult, type ConnectionSearchStatus, type FanOutFlightSearchOptions, type FanOutFlightSearchResult, fanOutFlightSearch, type MergedFlightOffer, } from "./orchestration/fan-out.js";
+export { itineraryFingerprint } from "./orchestration/fingerprint.js";
+export { type Aircraft, type Airline, type Airport, dedupeCodes, type ReferenceDataCapabilities, type ReferenceDataProvider, } from "./reference/contract.js";
+export { createLocalPostgresReferenceProvider, type LocalPostgresReferenceProviderOptions, referenceAircraft, referenceAirlines, referenceAirports, } from "./reference/local-postgres.js";
+export { createStaticBundleReferenceProvider, type StaticBundleProviderOptions, type StaticBundleReferenceData, } from "./reference/static-bundle.js";
+export { type BuildFlightSnapshotInputOptions, buildFlightSnapshotInput, } from "./snapshot.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,iCAAiC,EACjC,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AACnC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AAErE,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,WAAW,EACX,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,GAC3B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,oCAAoC,EACpC,KAAK,qCAAqC,EAC1C,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,mCAAmC,EACnC,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,KAAK,+BAA+B,EACpC,wBAAwB,GACzB,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// Flight contract types — offers, orders, segments, search, booking.
+// FlightConnectorAdapter contract.
+export { CAPABILITY_NOT_SUPPORTED, FlightCapabilityNotSupportedError, requireCapability, } from "./contract/adapter.js";
+export * from "./contract/types.js";
+export { fanOutFlightSearch, } from "./orchestration/fan-out.js";
+// Orchestration — fingerprinting + multi-connection fan-out.
+export { itineraryFingerprint } from "./orchestration/fingerprint.js";
+// ReferenceDataProvider — swappable provider for global reference data.
+export { dedupeCodes, } from "./reference/contract.js";
+export { createLocalPostgresReferenceProvider, referenceAircraft, referenceAirlines, referenceAirports, } from "./reference/local-postgres.js";
+export { createStaticBundleReferenceProvider, } from "./reference/static-bundle.js";
+// Snapshot capture for booking-time integration with the catalog plane.
+export { buildFlightSnapshotInput, } from "./snapshot.js";

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

@@ -0,0 +1,81 @@
+/**
+ * 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 type { FlightAdapterContext, FlightConnectorAdapter } from "../contract/adapter.js";
+import type { FlightOffer, FlightSearchRequest } from "../contract/types.js";
+/**
+ * One source's result — the primary offer plus alternates from other
+ * connections selling the same flight.
+ */
+export interface MergedFlightOffer {
+    itineraryFingerprint: string;
+    /** Cheapest offer for this itinerary across all responding connections. */
+    cheapest: FlightOffer;
+    /** Other offers for the same itinerary, sorted by total price ascending. */
+    alternates: FlightOffer[];
+    /** Connection ids that returned an offer for this itinerary. */
+    sourceConnectionIds: string[];
+}
+/**
+ * Per-connection status, returned alongside the merged offers so callers
+ * can surface "X provider timed out" without losing the rest of the results.
+ */
+export type ConnectionSearchStatus = "ok" | "timeout" | "error" | "not_found" | "capability_missing";
+export interface ConnectionResult {
+    connectionId: string;
+    status: ConnectionSearchStatus;
+    count: number;
+    latencyMs: number;
+    errorMessage?: string;
+}
+export interface FanOutFlightSearchOptions {
+    /** Adapters to fan out across. Each carries its own connectionId in capabilities. */
+    adapters: ReadonlyArray<{
+        connectionId: string;
+        adapter: FlightConnectorAdapter;
+        /** Optional override for the adapter context per connection. */
+        context?: Partial<FlightAdapterContext>;
+    }>;
+    request: FlightSearchRequest;
+    /**
+     * Per-connection timeout. Default 5000ms. One slow provider doesn't
+     * tank the whole search — its slot is reported as `timeout` and other
+     * results return on time.
+     */
+    perConnectionTimeoutMs?: number;
+    /**
+     * Optional caller-supplied limit on the merged offer count. The fan-out
+     * still queries every connection in full; this caps the merged result.
+     */
+    limit?: number;
+}
+export interface FanOutFlightSearchResult {
+    offers: MergedFlightOffer[];
+    perConnection: ConnectionResult[];
+}
+/**
+ * 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 declare function fanOutFlightSearch(options: FanOutFlightSearchOptions): Promise<FanOutFlightSearchResult>;
+interface ConnectionFanOutOk {
+    connectionId: string;
+    offers: FlightOffer[];
+}
+export type { ConnectionFanOutOk };
+//# sourceMappingURL=fan-out.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.d.ts","sourceRoot":"","sources":["../../src/orchestration/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAG5E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,EAAE,MAAM,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,WAAW,CAAA;IACrB,4EAA4E;IAC5E,UAAU,EAAE,WAAW,EAAE,CAAA;IACzB,gEAAgE;IAChE,mBAAmB,EAAE,MAAM,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,oBAAoB,CAAA;AAEpG,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,sBAAsB,CAAA;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,qFAAqF;IACrF,QAAQ,EAAE,aAAa,CAAC;QACtB,YAAY,EAAE,MAAM,CAAA;QACpB,OAAO,EAAE,sBAAsB,CAAA;QAC/B,gEAAgE;QAChE,OAAO,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAA;KACxC,CAAC,CAAA;IACF,OAAO,EAAE,mBAAmB,CAAA;IAC5B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B,aAAa,EAAE,gBAAgB,EAAE,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAgEnC;AAED,UAAU,kBAAkB;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAyED,YAAY,EAAE,kBAAkB,EAAE,CAAA"}