@voyant-travel/catalog 0.117.2

package/dist/snapshot/schema.js

@@ -0,0 +1,102 @@
+/**
+ * Booking snapshot graph — immutable frozen views of CatalogEntries captured
+ * at booking commit time.
+ *
+ * One booking can produce multiple snapshot rows (one per participating
+ * CatalogEntry — a TUI package booking captures the package, the referenced
+ * hotel, each selected excursion, the chosen departure, the selected flight).
+ * Snapshots are never mutated and are preserved through source disconnection.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.3 for the full design.
+ */
+import { typeId } from "@voyant-travel/db/lib/typeid-column";
+import { sql } from "drizzle-orm";
+import { jsonb, numeric, pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core";
+/**
+ * `booking_catalog_snapshot` — frozen view of a CatalogEntry captured at
+ * booking commit. One booking may produce many snapshot rows (one per
+ * participating CatalogEntry).
+ */
+export const bookingCatalogSnapshotTable = pgTable("booking_catalog_snapshot", {
+    id: typeId("booking_catalog_snapshot"),
+    // Booking the snapshot belongs to. Plain text reference (no FK) to
+    // preserve the cross-module decoupling rule (see schema-discipline.md).
+    booking_id: text("booking_id").notNull(),
+    // Which CatalogEntry this snapshot freezes.
+    entity_module: text("entity_module").notNull(),
+    entity_id: text("entity_id").notNull(),
+    // Source pointer — durable callback handle for post-book operations
+    // (modify, cancel, status sync, refund). The snapshot is audit truth;
+    // the source pointer is what you call back to.
+    source_kind: text("source_kind").notNull(),
+    source_provider: text("source_provider"),
+    source_connection_id: text("source_connection_id"),
+    source_ref: text("source_ref"),
+    // Frozen resolved view of the entity at booking time. Includes overlay
+    // values applied for the booking's (locale, audience, market). Opaque
+    // JSONB; finance queries the structured columns below instead.
+    frozen_payload: jsonb("frozen_payload").notNull(),
+    // The overlay values that were live at capture time. Audit needs this to
+    // reconstruct exactly what the customer saw — distinct from
+    // `frozen_payload` which is the resolved view, not the override values.
+    overlay_state_at_capture: jsonb("overlay_state_at_capture"),
+    // Structured pricing columns alongside the JSONB blob. Finance queries
+    // these directly without parsing. `pricing_basis_currency` denormalized
+    // to a separate column for indexed queries.
+    pricing_base_amount: numeric("pricing_base_amount", { precision: 18, scale: 4 }),
+    pricing_taxes: numeric("pricing_taxes", { precision: 18, scale: 4 }),
+    pricing_fees: numeric("pricing_fees", { precision: 18, scale: 4 }),
+    pricing_surcharges: numeric("pricing_surcharges", { precision: 18, scale: 4 }),
+    pricing_currency: text("pricing_currency"),
+    pricing_breakdown: jsonb("pricing_breakdown").$type(),
+    /**
+     * Frozen copy of the offers that applied to the source quote.
+     * Mirrors `catalog_quotes.pricing_applied_offers` and survives
+     * source-offer mutation / deletion so the audit row reflects what
+     * the customer was shown at booking time.
+     *
+     * Read path: `readPricingBasis` hydrates this onto
+     * `PricingBasis.appliedOffers`. The redemption subscriber reads
+     * from `catalog_quotes` (not here) to avoid an ordering race with
+     * the snapshot capture; this column is for long-term audit only.
+     *
+     * Per `docs/architecture/promotions-architecture.md` §7.1.3.
+     */
+    pricing_applied_offers: jsonb("pricing_applied_offers").$type(),
+    /**
+     * Caller-supplied idempotency key for the commit. When set, a
+     * second `bookEntity` call with the same key returns this row's
+     * booking instead of creating a new one. Per
+     * booking-journey-architecture §12.6.
+     */
+    idempotency_key: text("idempotency_key"),
+    captured_at: timestamp("captured_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    // A booking captures at most one snapshot per (entity_module, entity_id)
+    // pair — multiple captures of the same entity inside one booking would be
+    // a logic bug.
+    uniqueIndex("booking_catalog_snapshot_booking_entity_uniq").on(table.booking_id, table.entity_module, table.entity_id),
+    // Partial unique on idempotency_key — only enforced when set.
+    uniqueIndex("booking_catalog_snapshot_idempotency_uniq")
+        .on(table.idempotency_key)
+        .where(sql `idempotency_key is not null`),
+]);
+/**
+ * Helper to compose a `PricingBasis` from the structured columns of a
+ * snapshot row. Returns `null` if the snapshot has no pricing columns set
+ * (volatile-live fields without `on-quote` / `on-book` snapshot mode).
+ */
+export function readPricingBasis(row) {
+    if (row.pricing_base_amount == null || row.pricing_currency == null) {
+        return null;
+    }
+    return {
+        base_amount: Number(row.pricing_base_amount),
+        taxes: row.pricing_taxes != null ? Number(row.pricing_taxes) : 0,
+        fees: row.pricing_fees != null ? Number(row.pricing_fees) : 0,
+        surcharges: row.pricing_surcharges != null ? Number(row.pricing_surcharges) : 0,
+        currency: row.pricing_currency,
+        breakdown: row.pricing_breakdown ?? undefined,
+        appliedOffers: row.pricing_applied_offers ?? undefined,
+    };
+}

package/package.json

@@ -0,0 +1,210 @@
+{
+  "name": "@voyant-travel/catalog",
+  "version": "0.117.2",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js",
+      "default": "./dist/schema.js"
+    },
+    "./schema-sourced-entries": {
+      "types": "./dist/schema-sourced-entries.d.ts",
+      "import": "./dist/schema-sourced-entries.js",
+      "default": "./dist/schema-sourced-entries.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js",
+      "default": "./dist/contract.js"
+    },
+    "./provenance": {
+      "types": "./dist/provenance.d.ts",
+      "import": "./dist/provenance.js",
+      "default": "./dist/provenance.js"
+    },
+    "./overlay/schema": {
+      "types": "./dist/overlay/schema.d.ts",
+      "import": "./dist/overlay/schema.js",
+      "default": "./dist/overlay/schema.js"
+    },
+    "./overlay/resolver": {
+      "types": "./dist/overlay/resolver.d.ts",
+      "import": "./dist/overlay/resolver.js",
+      "default": "./dist/overlay/resolver.js"
+    },
+    "./snapshot/schema": {
+      "types": "./dist/snapshot/schema.d.ts",
+      "import": "./dist/snapshot/schema.js",
+      "default": "./dist/snapshot/schema.js"
+    },
+    "./indexer/contract": {
+      "types": "./dist/indexer/contract.d.ts",
+      "import": "./dist/indexer/contract.js",
+      "default": "./dist/indexer/contract.js"
+    },
+    "./indexer/typesense": {
+      "types": "./dist/indexer/typesense.d.ts",
+      "import": "./dist/indexer/typesense.js",
+      "default": "./dist/indexer/typesense.js"
+    },
+    "./search/routes": {
+      "types": "./dist/search/routes.d.ts",
+      "import": "./dist/search/routes.js",
+      "default": "./dist/search/routes.js"
+    },
+    "./search/rerank": {
+      "types": "./dist/search/rerank.d.ts",
+      "import": "./dist/search/rerank.js",
+      "default": "./dist/search/rerank.js"
+    },
+    "./search/semantic": {
+      "types": "./dist/search/semantic.d.ts",
+      "import": "./dist/search/semantic.js",
+      "default": "./dist/search/semantic.js"
+    },
+    "./search/federate": {
+      "types": "./dist/search/federate.d.ts",
+      "import": "./dist/search/federate.js",
+      "default": "./dist/search/federate.js"
+    },
+    "./embeddings/contract": {
+      "types": "./dist/embeddings/contract.d.ts",
+      "import": "./dist/embeddings/contract.js",
+      "default": "./dist/embeddings/contract.js"
+    },
+    "./embeddings/openai": {
+      "types": "./dist/embeddings/openai.d.ts",
+      "import": "./dist/embeddings/openai.js",
+      "default": "./dist/embeddings/openai.js"
+    },
+    "./embeddings/gemini": {
+      "types": "./dist/embeddings/gemini.d.ts",
+      "import": "./dist/embeddings/gemini.js",
+      "default": "./dist/embeddings/gemini.js"
+    },
+    "./embeddings/model-registry": {
+      "types": "./dist/embeddings/model-registry.d.ts",
+      "import": "./dist/embeddings/model-registry.js",
+      "default": "./dist/embeddings/model-registry.js"
+    },
+    "./drift/events": {
+      "types": "./dist/drift/events.d.ts",
+      "import": "./dist/drift/events.js",
+      "default": "./dist/drift/events.js"
+    },
+    "./events/taxonomy": {
+      "types": "./dist/events/taxonomy.d.ts",
+      "import": "./dist/events/taxonomy.js",
+      "default": "./dist/events/taxonomy.js"
+    },
+    "./adapter/contract": {
+      "types": "./dist/adapter/contract.d.ts",
+      "import": "./dist/adapter/contract.js",
+      "default": "./dist/adapter/contract.js"
+    },
+    "./adapter/schemas": {
+      "types": "./dist/adapter/schemas.d.ts",
+      "import": "./dist/adapter/schemas.js",
+      "default": "./dist/adapter/schemas.js"
+    },
+    "./services/overlay": {
+      "types": "./dist/services/overlay-service.d.ts",
+      "import": "./dist/services/overlay-service.js",
+      "default": "./dist/services/overlay-service.js"
+    },
+    "./services/snapshot": {
+      "types": "./dist/services/snapshot-service.d.ts",
+      "import": "./dist/services/snapshot-service.js",
+      "default": "./dist/services/snapshot-service.js"
+    },
+    "./services/indexer": {
+      "types": "./dist/services/indexer-service.d.ts",
+      "import": "./dist/services/indexer-service.js",
+      "default": "./dist/services/indexer-service.js"
+    },
+    "./services/sourced-entry": {
+      "types": "./dist/services/sourced-entry-service.d.ts",
+      "import": "./dist/services/sourced-entry-service.js",
+      "default": "./dist/services/sourced-entry-service.js"
+    },
+    "./services/content": {
+      "types": "./dist/services/content-service.d.ts",
+      "import": "./dist/services/content-service.js",
+      "default": "./dist/services/content-service.js"
+    },
+    "./booking-engine": {
+      "types": "./dist/booking-engine/index.d.ts",
+      "import": "./dist/booking-engine/index.js",
+      "default": "./dist/booking-engine/index.js"
+    },
+    "./booking-engine/schema": {
+      "types": "./dist/booking-engine/schema.d.ts",
+      "import": "./dist/booking-engine/schema.js",
+      "default": "./dist/booking-engine/schema.js"
+    },
+    "./booking-engine/draft-shape": {
+      "types": "./dist/booking-engine/draft-shape.d.ts",
+      "import": "./dist/booking-engine/draft-shape.js",
+      "default": "./dist/booking-engine/draft-shape.js"
+    },
+    "./booking-engine/contracts": {
+      "types": "./dist/booking-engine/contracts.d.ts",
+      "import": "./dist/booking-engine/contracts.js",
+      "default": "./dist/booking-engine/contracts.js"
+    },
+    "./booking-engine/drafts-schema": {
+      "types": "./dist/booking-engine/drafts-schema.d.ts",
+      "import": "./dist/booking-engine/drafts-schema.js",
+      "default": "./dist/booking-engine/drafts-schema.js"
+    }
+  },
+  "voyant": {
+    "schema": "./schema",
+    "requiresSchemas": [
+      "@voyant-travel/db"
+    ]
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.10",
+    "zod": "^4.1.4",
+    "@voyant-travel/catalog-contracts": "^0.107.1",
+    "@voyant-travel/core": "^0.109.0",
+    "@voyant-travel/db": "^0.108.0",
+    "@voyant-travel/hono": "^0.109.1"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.10",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "@voyant-travel/voyant-typescript-config": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/catalog"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "db:generate": "drizzle-kit generate"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}