Catalog

​

Key concepts

​

What it owns

• The field-policy contract (./contract): the FieldPolicy type, the governance enums, and the inheritance loader. Each vertical writes its own policy file.
• The provenance shape (./provenance) and the durable sourced-entry store that records what is known locally about each sourced row.
• The overlay store (./overlay): the Drizzle schema and the resolver-merge logic with the full locale x audience x market fallback chain. It accepts writes from the admin UI, external CMS plugins, bulk import, and AI copy pipelines, all governed by the same field policy.
• The booking snapshot graph (./snapshot): the booking_catalog_snapshot table and capture helpers, including structured pricing_basis columns finance and refund engines query.
• The search index projection (./indexer): the engine-agnostic IndexerAdapter contract and a native Typesense implementation (the v1 default), plus per-(locale, audience, market) document materialization and the admin-vs-storefront denormalization topology. Browse-time price sort and filter is first-class through indexed price summaries, with an optional two-stage live rerank helper (./search/rerank).
• The drift event stream (./drift): typed events emitted when an upstream field changes materially, severity-graded by the policy registry.
• The catalog event taxonomy (./events): visibility-filtered payload builders emitted through @voyant-travel/core/events and consumed by the existing webhook pipeline for near-real-time cross-deployment freshness.
• The booking engine (./booking-engine): the vertical-agnostic quoteEntity / bookEntity / cancelEntity lifecycle and the SourceAdapterRegistry that dispatches by source_kind.

​

Working with it

import { defineFieldPolicy } from "@voyant-travel/catalog/contract";

export const productCatalogPolicy = defineFieldPolicy([
  {
    path: "title",
    class: "merchandisable",
    merge: "replace",
    drift: "medium",
    reindex: "entry-locale",
    snapshot: "on-book",
    query: "indexed-column",
    localized: true,
    visibility: ["staff", "customer", "partner"],
    editRole: "marketing",
    overrideFriction: "none",
    sourceFreshness: "sync",
  },
  {
    path: "priceFromAmountCents",
    class: "volatile-indexed",
    merge: "source-only",
    drift: "low",
    reindex: "entry",
    snapshot: "never",
    query: "indexed-column",
    localized: false,
    visibility: ["staff", "customer"],
    editRole: "none",
    overrideFriction: "approval",
    sourceFreshness: "sync",
  },
  // ...one row per projected field
]);

import { createCatalogSearchHonoModule, executeSemanticSearch } from "@voyant-travel/catalog";

export const catalogSearchModule = createCatalogSearchHonoModule({
  resolveRuntime: (c) => buildCatalogSearchRuntime(c),
  executeSearch: ({ adapter, embeddings, slice, request }) =>
    executeSemanticSearch({ adapter, embeddings, slice, request }),
});

// A storefront listing request against a scheduled (departures-first) surface.
await fetch("/v1/public/catalog/search", {
  method: "POST",
  body: JSON.stringify({
    vertical: "products",
    query: "",
    mode: "keyword",
    sort: "departure-asc",
    projection: "storefront-card",
    pagination: { limit: 12 },
    facets: [{ field: "categorySlugs[]" }, { field: "departureMonths[]" }],
  }),
});

import { createSourceAdapterRegistry } from "@voyant-travel/catalog";

const registry = createSourceAdapterRegistry();
registry.register(demoAdapter()); // source.kind: "demo"
registry.register(voyantConnectAdapter({ /* credentials */ })); // "voyant-connect"

// quoteEntity -> bookEntity captures a booking_catalog_snapshot row for both
// owned and sourced inventory, with identical audit shape. A source.kind that
// has no registered adapter fails with NO_ADAPTER_REGISTERED.

​

Links to other modules

• inventory is the operated-inventory authoring side. It writes its own catalog policy file and projects Products into the plane; catalog never depends on inventory.
• commerce reads the catalog plane: a commercial decision takes a Catalog Item reference and resolves price, availability, and sellability through the matching adapter.
• bookings is where the booking engine lands its rows. The engine reuses bookings as the shared parent so an itinerary can mix owned and sourced lines, and stamps the source pointer and snapshot on each.
• distribution is the outbound inverse: when a booking commits on Voyant, distribution pushes it upstream through the same SourceAdapter contract, extended with pushBooking / pushAvailability / pushContent.
• finance queries the snapshot’s structured pricing_basis for invoicing and refunds.

​

React package

​

Next steps