@voyant-travel/inventory 0.1.0

package/dist/service-catalog-plane-taxonomy.js

@@ -0,0 +1,242 @@
+/**
+ * Projection extension that joins product → categories (with ancestor walk)
+ * and product → tags, contributing taxonomy fields onto the product search
+ * document.
+ *
+ * Wire via `createProductDocumentBuilder({ extensions: [taxonomyExtension] })`.
+ * Requires the registry to include `productTaxonomyCatalogPolicy` —
+ * otherwise the contributed fields are silently dropped by the indexer's
+ * field-policy filter.
+ *
+ * Hierarchy denormalization: Typesense can't recurse, so a product linked
+ * to "Hiking" (parent: "Adventure") needs both labels in `categories[]` for
+ * the "Adventure" filter to match. The projection walks the parent chain
+ * iteratively, filtering inactive ancestors (so an operator-paused parent
+ * stops surfacing its still-active children under the parent filter).
+ *
+ * Localization (#502): when a `product_category_translations` /
+ * `product_tag_translations` row exists for the slice's locale, its `name`
+ * wins. Otherwise the projection falls back to the canonical
+ * `productCategories.name` / `productTags.name` (the legacy single-locale
+ * column). This makes the upgrade non-breaking — operators that haven't
+ * created translations keep seeing the English label on every locale slice
+ * exactly as before.
+ *
+ * Slugs stay single-locale on `productCategories.slug` (per #502 non-goals
+ * — operators want stable URLs that don't shift when translations are
+ * edited).
+ */
+import { and, eq, inArray } from "drizzle-orm";
+import { productCategories, productCategoryProducts, productCategoryTranslations, productTagProducts, productTags, productTagTranslations, } from "./schema-taxonomy.js";
+/**
+ * Resolve linked category ids for a product, ordered by the operator-set
+ * `sortOrder` on `product_category_products` (lowest first). Direct links
+ * only — ancestors are walked separately.
+ */
+async function fetchDirectCategoryLinks(db, productId) {
+    return db
+        .select({
+        categoryId: productCategoryProducts.categoryId,
+        sortOrder: productCategoryProducts.sortOrder,
+    })
+        .from(productCategoryProducts)
+        .where(eq(productCategoryProducts.productId, productId));
+}
+/**
+ * Walk up the parent chain from a set of seed category ids, filtering
+ * inactive rows. Returns every active row reachable from the seeds.
+ *
+ * Iterative breadth-first to bound depth and avoid Drizzle recursive-CTE
+ * complexity. Real-world category trees are O(depth ≤ 5), so this issues
+ * at most a handful of `inArray` lookups regardless of breadth.
+ *
+ * Cycle-protected via a visited set — a misconfigured parent loop won't
+ * spin the indexer.
+ */
+async function walkActiveCategoryChain(db, seedIds) {
+    const resolved = new Map();
+    const visited = new Set();
+    let frontier = Array.from(new Set(seedIds));
+    while (frontier.length > 0) {
+        for (const id of frontier)
+            visited.add(id);
+        const rows = await db
+            .select({
+            id: productCategories.id,
+            parentId: productCategories.parentId,
+            name: productCategories.name,
+            slug: productCategories.slug,
+            active: productCategories.active,
+        })
+            .from(productCategories)
+            .where(and(inArray(productCategories.id, frontier), eq(productCategories.active, true)));
+        const nextFrontier = [];
+        for (const row of rows) {
+            resolved.set(row.id, row);
+            if (row.parentId && !visited.has(row.parentId) && !resolved.has(row.parentId)) {
+                nextFrontier.push(row.parentId);
+            }
+        }
+        frontier = Array.from(new Set(nextFrontier));
+    }
+    return resolved;
+}
+async function fetchProductTags(db, productId) {
+    return db
+        .select({ id: productTags.id, name: productTags.name })
+        .from(productTagProducts)
+        .innerJoin(productTags, eq(productTagProducts.tagId, productTags.id))
+        .where(eq(productTagProducts.productId, productId));
+}
+/**
+ * Look up locale-specific category names for the given category ids. Returns
+ * a Map keyed by category id; entries only exist when a translation row was
+ * found for the slice locale. Callers fall back to the canonical
+ * `productCategories.name` for any missing entry.
+ */
+async function fetchCategoryTranslations(db, categoryIds, languageTag) {
+    if (categoryIds.length === 0)
+        return new Map();
+    const rows = await db
+        .select({
+        categoryId: productCategoryTranslations.categoryId,
+        name: productCategoryTranslations.name,
+    })
+        .from(productCategoryTranslations)
+        .where(and(inArray(productCategoryTranslations.categoryId, categoryIds), eq(productCategoryTranslations.languageTag, languageTag)));
+    const out = new Map();
+    for (const row of rows)
+        out.set(row.categoryId, row.name);
+    return out;
+}
+async function fetchTagTranslations(db, tagIds, languageTag) {
+    if (tagIds.length === 0)
+        return new Map();
+    const rows = await db
+        .select({
+        tagId: productTagTranslations.tagId,
+        name: productTagTranslations.name,
+    })
+        .from(productTagTranslations)
+        .where(and(inArray(productTagTranslations.tagId, tagIds), eq(productTagTranslations.languageTag, languageTag)));
+    const out = new Map();
+    for (const row of rows)
+        out.set(row.tagId, row.name);
+    return out;
+}
+/**
+ * Pure aggregation kernel. `categoryNameByLocale` and `tagNameByLocale`
+ * carry slice-locale translations; entries override the canonical name on
+ * the row. Missing entries fall back to the canonical name. Slug stays
+ * canonical regardless — there's no per-locale slug.
+ */
+function buildTaxonomyProjection(directLinks, resolvedCategories, tags, categoryNameByLocale = new Map(), tagNameByLocale = new Map()) {
+    // Primary = first direct link (by sortOrder asc, then category name asc)
+    // that resolved as active. Tie-break uses the canonical row name so the
+    // ordering is stable across slice locales — a translation that sorts
+    // differently shouldn't shuffle which category is "primary".
+    const sortedDirect = [...directLinks].sort((a, b) => {
+        if (a.sortOrder !== b.sortOrder)
+            return a.sortOrder - b.sortOrder;
+        const nameA = resolvedCategories.get(a.categoryId)?.name ?? "";
+        const nameB = resolvedCategories.get(b.categoryId)?.name ?? "";
+        return nameA.localeCompare(nameB);
+    });
+    let primary = null;
+    for (const link of sortedDirect) {
+        const row = resolvedCategories.get(link.categoryId);
+        if (row) {
+            primary = row;
+            break;
+        }
+    }
+    // Categories[] = direct links + ancestors, deduped, ordered by direct-link
+    // sortOrder first then ancestor walk order. Stable enough that storefronts
+    // can rely on `categories[0]` being a representative label.
+    const seenIds = new Set();
+    const categoryIds = [];
+    const categoryNames = [];
+    const categorySlugs = [];
+    function emit(row) {
+        if (seenIds.has(row.id))
+            return;
+        seenIds.add(row.id);
+        categoryIds.push(row.id);
+        // Locale override wins; otherwise use the canonical row.name.
+        categoryNames.push(categoryNameByLocale.get(row.id) ?? row.name);
+        categorySlugs.push(row.slug);
+    }
+    // Pass 1: direct links first, in operator-controlled order.
+    for (const link of sortedDirect) {
+        const row = resolvedCategories.get(link.categoryId);
+        if (row)
+            emit(row);
+    }
+    // Pass 2: ancestors of direct links, walking up via parentId.
+    for (const link of sortedDirect) {
+        let cursor = resolvedCategories.get(link.categoryId)?.parentId ?? null;
+        const guard = new Set(); // local guard against malformed loops
+        while (cursor && !guard.has(cursor)) {
+            guard.add(cursor);
+            const parentRow = resolvedCategories.get(cursor);
+            if (!parentRow)
+                break;
+            emit(parentRow);
+            cursor = parentRow.parentId;
+        }
+    }
+    return {
+        categoryIds,
+        categoryNames,
+        categorySlugs,
+        primaryCategoryId: primary?.id ?? null,
+        primaryCategoryName: primary ? (categoryNameByLocale.get(primary.id) ?? primary.name) : null,
+        primaryCategorySlug: primary?.slug ?? null,
+        tagIds: tags.map((t) => t.id),
+        tagLabels: tags.map((t) => tagNameByLocale.get(t.id) ?? t.name),
+    };
+}
+/**
+ * Construct the taxonomy projection extension.
+ *
+ * Returns a `ProductProjectionExtension` ready to pass to
+ * `createProductDocumentBuilder`.
+ */
+export function createProductTaxonomyProjectionExtension() {
+    return {
+        name: "products:taxonomy",
+        async project(db, productId, slice) {
+            const [directLinks, tags] = await Promise.all([
+                fetchDirectCategoryLinks(db, productId),
+                fetchProductTags(db, productId),
+            ]);
+            const seedIds = directLinks.map((l) => l.categoryId);
+            const resolvedCategories = seedIds.length > 0
+                ? await walkActiveCategoryChain(db, seedIds)
+                : new Map();
+            // Translations cover the FULL chain (direct + ancestors), so look up
+            // by every resolved-category id, not just the seed set.
+            const allCategoryIds = Array.from(resolvedCategories.keys());
+            const tagIds = tags.map((t) => t.id);
+            const [categoryNameByLocale, tagNameByLocale] = await Promise.all([
+                fetchCategoryTranslations(db, allCategoryIds, slice.locale),
+                fetchTagTranslations(db, tagIds, slice.locale),
+            ]);
+            const projection = buildTaxonomyProjection(directLinks, resolvedCategories, tags, categoryNameByLocale, tagNameByLocale);
+            return new Map([
+                ["categories[]", projection.categoryNames],
+                ["categoryIds[]", projection.categoryIds],
+                ["categorySlugs[]", projection.categorySlugs],
+                ["primaryCategoryId", projection.primaryCategoryId],
+                ["primaryCategoryName", projection.primaryCategoryName],
+                ["primaryCategorySlug", projection.primaryCategorySlug],
+                ["tagLabels[]", projection.tagLabels],
+                ["tagIds[]", projection.tagIds],
+            ]);
+        },
+    };
+}
+// Internal exports for unit tests — kept separate from the public surface.
+export const __test__ = {
+    buildTaxonomyProjection,
+};

package/dist/service-catalog-plane.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Catalog-plane integration for the products service.
+ *
+ * Adds catalog-aware service methods alongside the existing `productsService`
+ * surface in `service.ts`. Routes opt in: the original `getProductById` /
+ * `listProducts` continue to return raw DB rows; the methods here return
+ * resolved CatalogEntry views with overlays + visibility filtering applied.
+ *
+ * Existing service code is untouched. Migration is per-route, gradual.
+ *
+ * Naming note: this file is `service-catalog-plane.ts` (not `service-catalog.ts`)
+ * because the existing `service-catalog.ts` handles the products module's own
+ * catalog management (categories, tags, types). The "catalog plane" is the
+ * cross-vertical projection / overlay / snapshot infrastructure from
+ * `@voyant-travel/catalog`.
+ *
+ * See `docs/architecture/catalog-architecture.md` §9.1 for the integration
+ * pattern this file establishes (replicated for cruises, accommodations, etc.
+ * in their own service-catalog-plane.ts files).
+ */
+import { type CaptureSnapshotInput, type DocumentBuilder, type DocumentEmitter, type FieldPolicy, type FieldPolicyRegistry, type IndexerDocument, type IndexerSlice, type PricingBasis, type Provenance, type ResolvedView, type ResolverScope, type Visibility } from "@voyant-travel/catalog";
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import { products } from "./schema-core.js";
+/**
+ * Maps a product row to a field-keyed projection consumable by the catalog
+ * resolver. Field paths match the policy registry declarations in
+ * `catalog-policy.ts`.
+ *
+ * Provenance fields (`source.kind`, `source.ref`, `seller.operator_id`) are
+ * synthesized: today's products module models operator-owned inventory
+ * exclusively, so `source.kind = "owned"` and `source.ref = undefined`.
+ * When sourced products land (e.g. via Voyant Connect), this helper picks
+ * up the provenance from a parallel provenance row instead.
+ */
+export declare function productRowToProjection(row: typeof products.$inferSelect, context: {
+    sellerOperatorId: string;
+}): ReadonlyMap<string, unknown>;
+/**
+ * Returns the Provenance tuple for a product row. Owned products synthesize
+ * a `source.kind: "owned"` provenance with `static` freshness; sourced
+ * products (Voyant Connect / GDS / direct API) carry their actual source
+ * connection identity. Phase 1 ships only the owned form.
+ */
+export declare function productProvenance(_row: typeof products.$inferSelect, _context: {
+    sellerOperatorId: string;
+}): Provenance;
+/** Service-context the catalog-aware methods need. Templates wire this in. */
+export interface ProductCatalogContext {
+    /** The deployment's operator/tenant identifier — synthesized into provenance. */
+    sellerOperatorId: string;
+    /** Variant scope for the request. */
+    scope: ResolverScope;
+}
+/**
+ * Catalog-aware product fetch. Returns the resolved view (source projection
+ * + active overlays + visibility filtering) instead of the raw DB row.
+ *
+ * The original `productsService.getProductById` continues to return raw
+ * rows — routes that haven't migrated to the catalog plane keep working.
+ *
+ * Returns `null` if no product with `id` exists.
+ */
+export declare function getResolvedProductById(db: AnyDrizzleDb, id: string, context: ProductCatalogContext): Promise<ResolvedView | null>;
+/**
+ * Catalog-aware product list. Returns resolved views per row.
+ *
+ * Caller fetches the rows (typically via the existing `productsService.listProducts`
+ * with whatever filtering / pagination / sort the route applies) and passes
+ * them in. This keeps query construction in the existing service layer and
+ * adds the catalog overlay step on top.
+ *
+ * Overlays for the whole page are fetched in ONE query via
+ * `fetchOverlaysForEntities` and applied in-memory per product — the
+ * per-product output is byte-identical to calling `resolveEntityView`
+ * once per row, minus the N-1 sequential round trips.
+ *
+ * Real high-volume list paths (storefront browse, admin search) should
+ * still go through the search index instead — `IndexerService.search` is
+ * already wired for that purpose. Use this method for small admin-facing
+ * lists or detail-page composition where the index isn't on the read path.
+ */
+export declare function listResolvedProducts(db: AnyDrizzleDb, rows: ReadonlyArray<typeof products.$inferSelect>, context: ProductCatalogContext): Promise<ResolvedView[]>;
+/**
+ * Build a `CaptureSnapshotInput` for a product to feed into the catalog
+ * plane's `captureSnapshot` / `captureSnapshotGraph` helpers at booking
+ * commit time. Fetches the product, resolves its view (overlays applied,
+ * visibility filter for the supplied scope), and returns the snapshot
+ * input shape.
+ *
+ * Returns `null` if the product doesn't exist.
+ *
+ * Composition: a single-product booking calls this once and passes the
+ * result to `captureSnapshot`. A composite booking (e.g. a tour-package
+ * booking with referenced accommodations + excursions) calls this and the
+ * other verticals' equivalents, collects the inputs, and passes them all
+ * to `captureSnapshotGraph` in one transaction.
+ */
+export declare function buildProductSnapshotInput(db: AnyDrizzleDb, productId: string, context: ProductCatalogContext & {
+    pricingBasis?: PricingBasis;
+}): Promise<Omit<CaptureSnapshotInput, "bookingId"> | null>;
+/**
+ * A projection extension contributes additional field-keyed entries to the
+ * product search document. The builder runs all extensions in parallel after
+ * fetching the product row, then merges their entries into the base
+ * projection before emitting.
+ *
+ * Used by child-entity registries (destinations, taxonomy, departures, etc.)
+ * to denormalize fields onto the product doc. See architecture §5.4 — the
+ * search index is the canonical place for cross-entity denormalization.
+ *
+ * `buildIndexerDocument` silently drops entries whose paths aren't registered
+ * in the field-policy registry — so an extension's contributed registry must
+ * be composed into the registry passed to `createProductDocumentBuilder` for
+ * its fields to actually land in the document.
+ */
+export interface ProductProjectionExtension {
+    /** Identifier — used for diagnostics and logging only. */
+    readonly name: string;
+    /**
+     * Contribute additional projection entries for one product. The slice
+     * carries locale and audience for translation lookups and audience
+     * filtering.
+     */
+    project(db: AnyDrizzleDb, productId: string, slice: IndexerSlice): Promise<ReadonlyMap<string, unknown>>;
+}
+/**
+ * Compose the registry from the base product policy plus any contributing
+ * extensions' policies. Templates wire this when they enable child-entity
+ * registries.
+ */
+export declare function createProductsRegistry(...extensionPolicies: ReadonlyArray<ReadonlyArray<FieldPolicy>>): FieldPolicyRegistry;
+/**
+ * Construct a sync `DocumentEmitter` for products. The emitter takes a
+ * pre-fetched product row + a slice and returns the indexer document
+ * (filtered by visibility, with blob-only fields skipped).
+ *
+ * Bulk-reindex pipelines that already have rows in hand call this directly.
+ * Live reindex paths use `createProductDocumentBuilder` below, which fetches
+ * the row before emitting.
+ *
+ * Pass a custom `registry` when the deployment composes additional
+ * child-entity policies; otherwise the default products registry is used.
+ */
+export declare function createProductDocumentEmitter(context: {
+    sellerOperatorId: string;
+    registry?: FieldPolicyRegistry;
+}): DocumentEmitter<typeof products.$inferSelect>;
+/**
+ * Async `DocumentBuilder` for products — fetches the row by id, then emits.
+ * Plug this into `IndexerService.reindexEntity` for live reindex events.
+ *
+ * Returns `null` if the product no longer exists (e.g. it was deleted
+ * between the reindex enqueue and the worker picking it up). Callers can
+ * treat `null` as a delete signal.
+ *
+ * `extensions` denormalize child-entity fields onto the product doc. They
+ * run in parallel after the base row is fetched. An extension that throws
+ * fails the whole build — failures here would otherwise produce silently
+ * incomplete documents.
+ *
+ * Pass a custom `registry` (composed via `createProductsRegistry`) when
+ * extensions contribute fields beyond the base products policy.
+ */
+export declare function createProductDocumentBuilder(db: AnyDrizzleDb, context: {
+    sellerOperatorId: string;
+    extensions?: ReadonlyArray<ProductProjectionExtension>;
+    registry?: FieldPolicyRegistry;
+}): DocumentBuilder;
+/**
+ * Product-owned storefront-card projection. This extension keeps the
+ * customer catalog slice directly renderable by denormalizing localized
+ * routing, card media, duration, and map coordinates into the search doc.
+ */
+export declare function createProductStorefrontCardProjectionExtension(): ProductProjectionExtension;
+/**
+ * Re-exports for routes that only import from this file.
+ */
+export type { CaptureSnapshotInput, DocumentBuilder, DocumentEmitter, IndexerDocument, IndexerSlice, PricingBasis, Provenance, ResolvedView, ResolverScope, Visibility, };
+//# sourceMappingURL=service-catalog-plane.d.ts.map

package/dist/service-catalog-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-catalog-plane.d.ts","sourceRoot":"","sources":["../src/service-catalog-plane.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EAExB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,EAGlB,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAgB3C;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,QAAQ,CAAC,YAAY,EACjC,OAAO,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACpC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CA8C9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,QAAQ,CAAC,YAAY,EAClC,QAAQ,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACrC,UAAU,CAKZ;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAA;IACxB,qCAAqC;IACrC,KAAK,EAAE,aAAa,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,aAAa,CAAC,OAAO,QAAQ,CAAC,YAAY,CAAC,EACjD,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,YAAY,EAAE,CAAC,CAkBzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,qBAAqB,GAAG;IAAE,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GAC/D,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC,CASzD;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,OAAO,CACL,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACzC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,iBAAiB,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,GAC9D,mBAAmB,CAOrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAC/B,GAAG,eAAe,CAAC,OAAO,QAAQ,CAAC,YAAY,CAAC,CAWhD;AAsBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE;IACP,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAAA;IACtD,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAC/B,GACA,eAAe,CA2BjB;AAED;;;;GAIG;AACH,wBAAgB,8CAA8C,IAAI,0BAA0B,CA0F3F;AA4ED;;GAEG;AACH,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,GACX,CAAA"}