@voyantjs/flights 0.55.1 → 0.57.0

package/README.md

@@ -23,8 +23,13 @@ pnpm add @voyantjs/flights
   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.
+  + optional capability-gated methods for holds, seat maps, post-book seat
+  selection, check-in, exchange, refund, void, SSR, ancillaries, and order
+  listing). Provider-agnostic; implementations come from Voyant Connect,
+  third-party providers, or operator-built adapters.
+- **`./contract/schemas`** — zod schemas for the public flight contract
+  request, response, enum, and value-object shapes. Use these at HTTP, queue,
+  RPC, and adapter boundaries instead of re-declaring runtime validators.
 - **`./orchestration/fingerprint`** — Itinerary fingerprint helper. Two
   providers selling the same flight produce identical fingerprints.
 - **`./orchestration/fan-out`** — Multi-connection fan-out search:
@@ -84,6 +89,15 @@ const result = await fanOutFlightSearch({
 // result.perConnection — status + latency per connection.
 ```
 
+### Runtime validation
+
+```typescript
+import { flightBookRequestSchema } from "@voyantjs/flights/contract/schemas"
+import type { FlightBookRequest } from "@voyantjs/flights/contract/types"
+
+const request: FlightBookRequest = flightBookRequestSchema.parse(await req.json())
+```
+
 ### Reference data — operator's own Postgres tables
 
 ```typescript

package/dist/contract/adapter.d.ts

@@ -12,10 +12,18 @@
  *
  * See `docs/architecture/catalog-flights-architecture.md` §3.
  */
-import type { AncillaryRequest, AncillaryResponse, FlightBookRequest, FlightCapability, FlightOffer, FlightOrder, FlightOrderStatus, FlightSearchPaginationMeta, FlightSearchRequest, SeatMapRequest, SeatMapResponse } from "./types.js";
+import type { AncillaryRequest, AncillaryResponse, CheckInRequest, CheckInResponse, FlightBookRequest, FlightCapability, FlightModifyRequest, FlightModifyResponse, FlightOffer, FlightOrder, FlightOrderStatus, FlightRefundRequest, FlightRefundResponse, FlightSearchPaginationMeta, FlightSearchRequest, FlightVoidResponse, SeatMapRequest, SeatMapResponse, SeatSelectionRequest, SeatSelectionResponse, SsrRequest, SsrResponse } from "./types.js";
+export interface AdapterLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export type FlightAdapterEnvironment = "sandbox" | "production";
 /**
  * Context passed to every adapter call. Identifies the connection and
- * carries credentials, optional point-of-sale, tracing identifiers.
+ * carries credentials, optional point-of-sale, tracing identifiers,
+ * cancellation, idempotency, logging, and environment selection signals.
  *
  * `deps` is an escape hatch for adapter-specific runtime dependencies that
  * shouldn't bleed into the contract — e.g. a Postgres handle for a demo
@@ -27,7 +35,18 @@ export interface FlightAdapterContext {
     credentials?: Record<string, string>;
     /** Operator's IATA office id / pseudo-city / point-of-sale, when applicable. */
     pointOfSale?: string;
+    /** Upstream trace id, usually propagated from the caller. */
     correlationId?: string;
+    /** Per-call request id for adapter-local tracing. */
+    requestId?: string;
+    /** Idempotency key for replay-safe writes: book, modify, refund, void. */
+    idempotencyKey?: string;
+    /** Adapter-scoped logger with provider/connection/request metadata bound in. */
+    logger?: AdapterLogger;
+    /** Cancellation signal propagated from the orchestration layer. */
+    signal?: AbortSignal;
+    /** Selects the supplier environment when the adapter supports both. */
+    environment?: FlightAdapterEnvironment;
     deps?: Record<string, unknown>;
 }
 export interface FlightSearchResponse {
@@ -113,7 +132,14 @@ 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. */
+    /**
+     * Re-price an offer immediately before booking.
+     *
+     * This is also the canonical re-quote path for offers approaching
+     * `FlightOffer.expiresAt` or `lastTicketingDate`. Callers should invoke it
+     * before booking whenever the offer is older than the provider's freshness
+     * window or the UI is resuming a saved/held offer.
+     */
     priceOffer(ctx: FlightAdapterContext, request: FlightPriceRequest): Promise<FlightPriceResponse>;
     /**
      * Book the flight. Behavior depends on `paymentIntent`:
@@ -150,6 +176,18 @@ export interface FlightConnectorAdapter {
      * are submitted at book time via `FlightBookRequest.ancillaries.seats`.
      */
     getSeatMap?(ctx: FlightAdapterContext, request: SeatMapRequest): Promise<SeatMapResponse>;
+    /** `flight/seat-selection` — change/add seat selections on an existing order. */
+    selectSeats?(ctx: FlightAdapterContext, request: SeatSelectionRequest): Promise<SeatSelectionResponse>;
+    /** `flight/checkin` — initiate or complete online check-in for passengers. */
+    checkIn?(ctx: FlightAdapterContext, request: CheckInRequest): Promise<CheckInResponse>;
+    /** `flight/exchange` — change an existing order's itinerary, fare, pax, or extras. */
+    modifyOrder?(ctx: FlightAdapterContext, request: FlightModifyRequest): Promise<FlightModifyResponse>;
+    /** `flight/refund` — refund a ticketed order after the ticketing/void window. */
+    refundOrder?(ctx: FlightAdapterContext, request: FlightRefundRequest): Promise<FlightRefundResponse>;
+    /** `flight/void` — void a ticketed order inside the supplier void window. */
+    voidOrder?(ctx: FlightAdapterContext, orderId: string): Promise<FlightVoidResponse>;
+    /** `flight/ssr` — add a special service request such as wheelchair, meal, or UMNR. */
+    addSpecialServiceRequest?(ctx: FlightAdapterContext, request: SsrRequest): Promise<SsrResponse>;
 }
 /**
  * Standard error code for capability-gated methods that aren't supported

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

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

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

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

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

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

package/dist/contract/adapter.test.js

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+import { FlightCapabilityNotSupportedError, requireCapability, } from "./adapter.js";
+import { FLIGHT_CAPABILITIES } from "./types.js";
+const offer = {
+    offerId: "offer_1",
+    source: "test",
+    itineraries: [
+        {
+            segments: [
+                {
+                    segmentId: "seg_1",
+                    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.00", currency: "USD" },
+            taxes: { amount: "100.00", currency: "USD" },
+            total: { amount: "600.00", currency: "USD" },
+        },
+    ],
+    totalPrice: { amount: "600.00", currency: "USD" },
+};
+const order = {
+    orderId: "order_1",
+    pnr: "ABC123",
+    status: "ticketed",
+    offer,
+    passengers: [
+        {
+            passengerId: "pax_1",
+            type: "adult",
+            firstName: "Ada",
+            lastName: "Lovelace",
+            dateOfBirth: "1980-01-01",
+        },
+    ],
+    totalPrice: offer.totalPrice,
+    createdAt: "2026-10-01T10:00:00Z",
+};
+function makeCoreAdapter() {
+    return {
+        capabilities: { provider: "core", declared: [] },
+        async searchFlights() {
+            return { offers: [offer] };
+        },
+        async priceOffer() {
+            return { offer, valid: true };
+        },
+        async bookFlight() {
+            return { order };
+        },
+        async getOrder() {
+            return { order };
+        },
+        async cancelOrder() {
+            return { order: { ...order, status: "cancelled" } };
+        },
+    };
+}
+describe("FlightConnectorAdapter contract", () => {
+    it("allows core-only adapters to omit every optional capability method", async () => {
+        const adapter = makeCoreAdapter();
+        await expect(adapter.searchFlights({ connectionId: "conn" }, {})).resolves.toEqual({
+            offers: [offer],
+        });
+        expect(adapter.selectSeats).toBeUndefined();
+        expect(adapter.checkIn).toBeUndefined();
+        expect(adapter.modifyOrder).toBeUndefined();
+        expect(adapter.refundOrder).toBeUndefined();
+        expect(adapter.voidOrder).toBeUndefined();
+        expect(adapter.addSpecialServiceRequest).toBeUndefined();
+    });
+    it("allows adapters to implement every declared capability method", async () => {
+        const adapter = {
+            ...makeCoreAdapter(),
+            capabilities: {
+                provider: "full",
+                declared: Object.values(FLIGHT_CAPABILITIES),
+            },
+            async listOrders() {
+                return { orders: [order], pagination: { total: 1, hasMore: false } };
+            },
+            async ticketOrder() {
+                return { order };
+            },
+            async getAncillaries() {
+                return { catalog: { baggage: [], assistance: [], extras: [] } };
+            },
+            async getSeatMap() {
+                return {
+                    seatMap: {
+                        segmentId: "seg_1",
+                        cabin: "economy",
+                        columnLayout: ["A", "B", "C", null, "D", "E", "F"],
+                        rows: [],
+                    },
+                };
+            },
+            async selectSeats(_ctx, request) {
+                return { order, selections: request.selections };
+            },
+            async checkIn() {
+                return { order, status: "checked_in", boardingPasses: [] };
+            },
+            async modifyOrder() {
+                return { order, priceDifference: { amount: "0.00", currency: "USD" } };
+            },
+            async refundOrder() {
+                return { order: { ...order, status: "cancelled" }, refundedAmount: order.totalPrice };
+            },
+            async voidOrder() {
+                return { order: { ...order, status: "cancelled" }, voidedAt: "2026-10-01T11:00:00Z" };
+            },
+            async addSpecialServiceRequest() {
+                return { order, status: "requested" };
+            },
+        };
+        await expect(adapter.selectSeats?.({ connectionId: "conn" }, { orderId: order.orderId, selections: [] })).resolves.toEqual({ order, selections: [] });
+        await expect(adapter.refundOrder?.({ connectionId: "conn" }, { orderId: order.orderId })).resolves.toEqual({
+            order: { ...order, status: "cancelled" },
+            refundedAmount: order.totalPrice,
+        });
+    });
+    it("types the new adapter context fields as optional runtime signals", () => {
+        const controller = new AbortController();
+        const loggerMessages = [];
+        const context = {
+            connectionId: "conn",
+            requestId: "req_1",
+            correlationId: "corr_1",
+            idempotencyKey: "idem_1",
+            environment: "sandbox",
+            signal: controller.signal,
+            logger: {
+                debug: (message) => loggerMessages.push(message),
+                info: (message) => loggerMessages.push(message),
+                warn: (message) => loggerMessages.push(message),
+                error: (message) => loggerMessages.push(message),
+            },
+        };
+        context.logger?.info("context ready");
+        expect(context.requestId).toBe("req_1");
+        expect(context.signal).toBe(controller.signal);
+        expect(loggerMessages).toEqual(["context ready"]);
+    });
+    it.each([
+        [FLIGHT_CAPABILITIES.SEAT_SELECTION, "selectSeats"],
+        [FLIGHT_CAPABILITIES.CHECKIN, "checkIn"],
+        [FLIGHT_CAPABILITIES.EXCHANGE, "modifyOrder"],
+        [FLIGHT_CAPABILITIES.REFUND, "refundOrder"],
+        [FLIGHT_CAPABILITIES.VOID, "voidOrder"],
+        [FLIGHT_CAPABILITIES.SSR, "addSpecialServiceRequest"],
+    ])("throws the standard not-supported error for %s", (capability, operation) => {
+        expect(() => requireCapability({ provider: "core", declared: [] }, capability, operation)).toThrow(FlightCapabilityNotSupportedError);
+        try {
+            requireCapability({ provider: "core", declared: [] }, capability, operation);
+        }
+        catch (error) {
+            expect(error).toMatchObject({ provider: "core", capability, operation });
+        }
+    });
+});

package/dist/contract/post-book-types.d.ts

@@ -0,0 +1,90 @@
+import type { AncillarySelection, FlightOffer, FlightOrder, FlightPassenger, Money } from "./types.js";
+export interface SeatAssignment {
+    passengerId: string;
+    segmentId: string;
+    seatNumber: string;
+    /** Per-pax seat fee. Omitted = included in fare or already paid. */
+    price?: Money;
+    /** Provider-specific data — opaque round-trip. */
+    providerData?: Record<string, unknown>;
+}
+export interface SeatSelectionRequest {
+    orderId: string;
+    selections: SeatAssignment[];
+}
+export interface SeatSelectionResponse {
+    order: FlightOrder;
+    selections: SeatAssignment[];
+    /** Total additional charge collected for the seat change, if any. */
+    additionalAmount?: Money;
+}
+export type CheckInStatus = "initiated" | "checked_in" | "failed";
+export interface CheckInRequest {
+    orderId: string;
+    passengerIds?: string[];
+    segmentIds?: string[];
+}
+export interface FlightBoardingPass {
+    passengerId: string;
+    segmentId: string;
+    boardingPassId?: string;
+    seatNumber?: string;
+    sequenceNumber?: string;
+    zone?: string;
+    /** Provider-specific data — opaque round-trip. */
+    providerData?: Record<string, unknown>;
+}
+export interface CheckInResponse {
+    order: FlightOrder;
+    status: CheckInStatus;
+    boardingPasses?: FlightBoardingPass[];
+}
+export type FlightModifyReason = "customer_request" | "schedule_change" | "name_correction" | "disruption" | "operational";
+export interface FlightModifyRequest {
+    orderId: string;
+    /** Re-priced replacement offer when the modification changes itinerary/fare. */
+    offer?: FlightOffer;
+    /** Replacement passenger details for corrections allowed by the provider. */
+    passengers?: FlightPassenger[];
+    /** Add or replace ancillary picks as part of the modification. */
+    ancillaries?: AncillarySelection;
+    reason?: FlightModifyReason;
+}
+export interface FlightModifyResponse {
+    order: FlightOrder;
+    /** Positive means collect more from the traveler; negative means credit due. */
+    priceDifference?: Money;
+    penalties?: Money[];
+}
+export type FlightRefundReason = "customer_request" | "schedule_change" | "disruption" | "duplicate_booking" | "medical" | "other";
+export interface FlightRefundRequest {
+    orderId: string;
+    reason?: FlightRefundReason;
+    /** Omit for a full refund; provide for supplier-supported partial refunds. */
+    amount?: Money;
+}
+export interface FlightRefundResponse {
+    order: FlightOrder;
+    refundId?: string;
+    refundedAmount: Money;
+    penalties?: Money[];
+}
+export interface FlightVoidResponse {
+    order: FlightOrder;
+    voidId?: string;
+    voidedAt: string;
+}
+export type SsrCode = "WCHR" | "WCHS" | "WCHC" | "BLND" | "DEAF" | "MAAS" | "UMNR" | "INFT" | "PETC" | "VGML" | "KSML" | "MOML" | "OTHER";
+export interface SsrRequest {
+    orderId: string;
+    code: SsrCode;
+    passengerIds?: string[];
+    segmentIds?: string[];
+    text?: string;
+}
+export interface SsrResponse {
+    order: FlightOrder;
+    ssrId?: string;
+    status: "requested" | "confirmed" | "rejected";
+}
+//# sourceMappingURL=post-book-types.d.ts.map

package/dist/contract/post-book-types.d.ts.map

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

package/dist/contract/post-book-types.js

@@ -0,0 +1 @@
+export {};