@voyantjs/flights-contracts 0.98.0 → 0.99.0

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from "./contract/schemas.js";
 export * from "./contract/types.js";
 export * from "./reference/contract.js";
 export * from "./reference/static-bundle.js";
+export * from "./snapshot.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./contract/schemas.js";
 export * from "./contract/types.js";
 export * from "./reference/contract.js";
 export * from "./reference/static-bundle.js";
+export * from "./snapshot.js";

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-contracts/snapshot";
+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,sCAAsC,CAAA;AAE9F,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/flights-contracts",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -38,6 +38,11 @@
       "types": "./dist/reference/static-bundle.d.ts",
       "import": "./dist/reference/static-bundle.js",
       "default": "./dist/reference/static-bundle.js"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot.d.ts",
+      "import": "./dist/snapshot.js",
+      "default": "./dist/snapshot.js"
     }
   },
   "files": [
@@ -47,7 +52,8 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@voyantjs/catalog-contracts": "0.99.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",