@voyantjs/products 0.19.0 → 0.21.0

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

@@ -0,0 +1,129 @@
+/**
+ * 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
+ * `@voyantjs/catalog`.
+ *
+ * See `docs/architecture/catalog-architecture.md` §9.1 for the integration
+ * pattern this file establishes (replicated for cruises, hospitality, etc.
+ * in their own service-catalog-plane.ts files).
+ */
+import { type CaptureSnapshotInput, type DocumentBuilder, type DocumentEmitter, type IndexerDocument, type IndexerSlice, type PricingBasis, type Provenance, type ResolvedView, type ResolverScope, type Visibility } from "@voyantjs/catalog";
+import type { AnyDrizzleDb } from "@voyantjs/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.
+ *
+ * For Phase B v1, this is a naive per-row resolver that issues one overlay
+ * fetch per product. Real list paths (storefront browse, admin search)
+ * should 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.
+ *
+ * Production-grade batched overlay fetch is a TODO; the catalog plane
+ * supports it conceptually but `fetchOverlaysForEntity` is currently
+ * one-entity-at-a-time. A future `fetchOverlaysForEntities(db, [(module, id), ...])`
+ * lands with the indexer hot-path optimization.
+ */
+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 hospitality + 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>;
+/**
+ * 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.
+ */
+export declare function createProductDocumentEmitter(context: {
+    sellerOperatorId: string;
+}): 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.
+ */
+export declare function createProductDocumentBuilder(db: AnyDrizzleDb, context: {
+    sellerOperatorId: string;
+}): DocumentBuilder;
+/**
+ * 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":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,EAElB,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIhD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAc3C;;;;;;;;;;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,CAwC9B;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;;;;;;;;;;;;;;;;;;GAkBG;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;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,gBAAgB,EAAE,MAAM,CAAA;CACzB,GAAG,eAAe,CAAC,OAAO,QAAQ,CAAC,YAAY,CAAC,CAWhD;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACpC,eAAe,CAQjB;AAED;;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"}

package/dist/service-catalog-plane.js

@@ -0,0 +1,212 @@
+/**
+ * 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
+ * `@voyantjs/catalog`.
+ *
+ * See `docs/architecture/catalog-architecture.md` §9.1 for the integration
+ * pattern this file establishes (replicated for cruises, hospitality, etc.
+ * in their own service-catalog-plane.ts files).
+ */
+import { buildIndexerDocument, buildSnapshotInputFromView, createFieldPolicyRegistry, resolveEntityView, } from "@voyantjs/catalog";
+import { eq } from "drizzle-orm";
+import { productCatalogPolicy } from "./catalog-policy.js";
+import { products } from "./schema-core.js";
+/**
+ * Lazy-initialized registry. Built once per process; the field-policy file
+ * is static so this is safe to memoize.
+ */
+let _registry;
+function getProductsRegistry() {
+    if (!_registry) {
+        _registry = createFieldPolicyRegistry(productCatalogPolicy);
+    }
+    return _registry;
+}
+/**
+ * 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 function productRowToProjection(row, context) {
+    const projection = new Map([
+        // Provenance — synthesized for owned products.
+        ["source.kind", "owned"],
+        ["seller.operator_id", context.sellerOperatorId],
+        // Identity
+        ["id", row.id],
+        ["createdAt", row.createdAt],
+        ["updatedAt", row.updatedAt],
+        // Merchandisable
+        ["name", row.name],
+        ["description", row.description],
+        ["tags[]", row.tags],
+        // Structural
+        ["status", row.status],
+        ["bookingMode", row.bookingMode],
+        ["capacityMode", row.capacityMode],
+        ["visibility", row.visibility],
+        ["activated", row.activated],
+        ["productTypeId", row.productTypeId],
+        ["facilityId", row.facilityId],
+        ["supplierId", row.supplierId],
+        ["pax", row.pax],
+        ["startDate", row.startDate],
+        ["endDate", row.endDate],
+        ["timezone", row.timezone],
+        ["reservationTimeoutMinutes", row.reservationTimeoutMinutes],
+        // Pricing (configured defaults — quote-time prices come from pricing module)
+        ["sellAmountCents", row.sellAmountCents],
+        ["sellCurrency", row.sellCurrency],
+        // Internal / staff-only
+        ["costAmountCents", row.costAmountCents],
+        ["marginPercent", row.marginPercent],
+    ]);
+    return projection;
+}
+/**
+ * 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 function productProvenance(_row, _context) {
+    return {
+        source_kind: "owned",
+        source_freshness: "static",
+    };
+}
+/**
+ * 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 async function getResolvedProductById(db, id, context) {
+    const rows = await db.select().from(products).where(eq(products.id, id)).limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    const projection = productRowToProjection(row, {
+        sellerOperatorId: context.sellerOperatorId,
+    });
+    return resolveEntityView(db, getProductsRegistry(), "products", id, projection, context.scope);
+}
+/**
+ * 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.
+ *
+ * For Phase B v1, this is a naive per-row resolver that issues one overlay
+ * fetch per product. Real list paths (storefront browse, admin search)
+ * should 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.
+ *
+ * Production-grade batched overlay fetch is a TODO; the catalog plane
+ * supports it conceptually but `fetchOverlaysForEntity` is currently
+ * one-entity-at-a-time. A future `fetchOverlaysForEntities(db, [(module, id), ...])`
+ * lands with the indexer hot-path optimization.
+ */
+export async function listResolvedProducts(db, rows, context) {
+    const registry = getProductsRegistry();
+    const views = [];
+    for (const row of rows) {
+        const projection = productRowToProjection(row, {
+            sellerOperatorId: context.sellerOperatorId,
+        });
+        const view = await resolveEntityView(db, registry, "products", row.id, projection, context.scope);
+        views.push(view);
+    }
+    return views;
+}
+/**
+ * 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 hospitality + excursions) calls this and the
+ * other verticals' equivalents, collects the inputs, and passes them all
+ * to `captureSnapshotGraph` in one transaction.
+ */
+export async function buildProductSnapshotInput(db, productId, context) {
+    const view = await getResolvedProductById(db, productId, context);
+    if (!view)
+        return null;
+    return buildSnapshotInputFromView(view, {
+        entityModule: "products",
+        entityId: productId,
+        sourceKind: "owned",
+        pricingBasis: context.pricingBasis,
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Indexer document emission
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+export function createProductDocumentEmitter(context) {
+    const registry = getProductsRegistry();
+    return {
+        vertical: "products",
+        emit(source, slice) {
+            const projection = productRowToProjection(source, {
+                sellerOperatorId: context.sellerOperatorId,
+            });
+            return buildIndexerDocument(registry, projection, slice, source.id);
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function createProductDocumentBuilder(db, context) {
+    const emitter = createProductDocumentEmitter(context);
+    return async (entityId, slice) => {
+        const rows = await db.select().from(products).where(eq(products.id, entityId)).limit(1);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return emitter.emit(row, slice);
+    };
+}

package/dist/service-content-owned.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Owned-product content builder.
+ *
+ * Projects an owned product (the products module's own tables) into the
+ * vertical-shared `ProductContent` shape so the catalog content service
+ * can return rich detail for owned products via the same API that
+ * sourced products go through (`getProductContent`).
+ *
+ * Per sourced-content §3.3: `getProductContent` is the unified read
+ * surface for owned + sourced. v1 of service-content.ts only handled
+ * sourced (returning null for owned); this helper closes that gap.
+ *
+ * Locale resolution uses the catalog plane's standard
+ * `pickBestCachedLocale` against `product_translations` and
+ * `product_option_translations` rows — exact > language-match >
+ * fallback-chain > any. Matches the same scoring semantics the sourced
+ * cache reads use, so the same `BookingDraft.scope.locale` chain works
+ * for both owned and sourced products.
+ *
+ * The projection reads in parallel:
+ *   - `products` row → product summary + tags + supplier
+ *   - `product_translations` → localized name + description per locale
+ *   - `product_itineraries` + `product_days` → itinerary days (no
+ *     translation table today; falls back to source)
+ *   - `product_options` + `product_option_translations` → options +
+ *     localized labels
+ *   - `product_media` → hero + gallery
+ *
+ * Day translations don't exist in the schema yet — when
+ * `product_day_translations` lands, this function picks them up the
+ * same way.
+ */
+import type { ContentLocaleMatchKind } from "@voyantjs/catalog";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { type ProductContent } from "./content-shape.js";
+export interface BuildOwnedProductContentOptions {
+    /**
+     * Ordered locale preference chain — most-preferred first. Same shape
+     * the catalog plane's `pickBestCachedLocale` consumes. Pass-through
+     * from the caller's `BookingDraft.scope.locale` (storefront /
+     * operator UI).
+     */
+    preferredLocales: ReadonlyArray<string>;
+}
+export interface BuildOwnedProductContentResult {
+    /** The owned product projected to ProductContent. */
+    content: ProductContent;
+    /**
+     * The locale we actually served — may differ from
+     * `preferredLocales[0]` when a fallback was used. Per-product;
+     * options that fell back to a different locale don't override this
+     * (storefront UI hints at the product level).
+     */
+    servedLocale: string;
+    /**
+     * How well the served locale matched the chain. Surfaces in the UI
+     * as a "served in English" hint when content was served in a
+     * non-preferred language.
+     */
+    matchKind: ContentLocaleMatchKind;
+}
+/**
+ * Read the owned product + related rows and project to `ProductContent`,
+ * resolving translations against the supplied locale-preference chain.
+ * Returns null when the product doesn't exist.
+ */
+export declare function buildOwnedProductContent(db: AnyDrizzleDb, entityId: string, options: BuildOwnedProductContentOptions): Promise<BuildOwnedProductContentResult | null>;
+//# sourceMappingURL=service-content-owned.d.ts.map

package/dist/service-content-owned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-content-owned.d.ts","sourceRoot":"","sources":["../src/service-content-owned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAGhD,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,oBAAoB,CAAA;AAW3B,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,8BAA8B;IAC7C,qDAAqD;IACrD,OAAO,EAAE,cAAc,CAAA;IACvB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,SAAS,EAAE,sBAAsB,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,GAAG,IAAI,CAAC,CAmIhD"}

package/dist/service-content-owned.js

@@ -0,0 +1,224 @@
+/**
+ * Owned-product content builder.
+ *
+ * Projects an owned product (the products module's own tables) into the
+ * vertical-shared `ProductContent` shape so the catalog content service
+ * can return rich detail for owned products via the same API that
+ * sourced products go through (`getProductContent`).
+ *
+ * Per sourced-content §3.3: `getProductContent` is the unified read
+ * surface for owned + sourced. v1 of service-content.ts only handled
+ * sourced (returning null for owned); this helper closes that gap.
+ *
+ * Locale resolution uses the catalog plane's standard
+ * `pickBestCachedLocale` against `product_translations` and
+ * `product_option_translations` rows — exact > language-match >
+ * fallback-chain > any. Matches the same scoring semantics the sourced
+ * cache reads use, so the same `BookingDraft.scope.locale` chain works
+ * for both owned and sourced products.
+ *
+ * The projection reads in parallel:
+ *   - `products` row → product summary + tags + supplier
+ *   - `product_translations` → localized name + description per locale
+ *   - `product_itineraries` + `product_days` → itinerary days (no
+ *     translation table today; falls back to source)
+ *   - `product_options` + `product_option_translations` → options +
+ *     localized labels
+ *   - `product_media` → hero + gallery
+ *
+ * Day translations don't exist in the schema yet — when
+ * `product_day_translations` lands, this function picks them up the
+ * same way.
+ */
+import { pickBestCachedLocale } from "@voyantjs/catalog";
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { productContentSchema, validateProductContent, } from "./content-shape.js";
+import { productDays, productItineraries, productMedia, productOptions, productOptionTranslations, products, productTranslations, } from "./schema.js";
+/**
+ * Read the owned product + related rows and project to `ProductContent`,
+ * resolving translations against the supplied locale-preference chain.
+ * Returns null when the product doesn't exist.
+ */
+export async function buildOwnedProductContent(db, entityId, options) {
+    // biome-ignore lint/suspicious/noExplicitAny: drizzle's generic returning Pg infers the row shape but the AnyDrizzleDb wrapper widens it
+    const productRow = (await db.select().from(products).where(eq(products.id, entityId)).limit(1))[0];
+    if (!productRow)
+        return null;
+    const [optionRows, mediaRows, itineraryRows, productTrns] = await Promise.all([
+        db
+            .select()
+            .from(productOptions)
+            .where(eq(productOptions.productId, entityId))
+            .orderBy(asc(productOptions.sortOrder)),
+        db
+            .select()
+            .from(productMedia)
+            .where(eq(productMedia.productId, entityId))
+            .orderBy(asc(productMedia.sortOrder), asc(productMedia.createdAt)),
+        db
+            .select()
+            .from(productItineraries)
+            .where(eq(productItineraries.productId, entityId))
+            .orderBy(asc(productItineraries.sortOrder)),
+        db.select().from(productTranslations).where(eq(productTranslations.productId, entityId)),
+    ]);
+    // biome-ignore lint/suspicious/noExplicitAny: drizzle row shape
+    const defaultItinerary = itineraryRows.find((it) => it.isDefault) ?? itineraryRows[0];
+    const days = defaultItinerary
+        ? await db
+            .select()
+            .from(productDays)
+            .where(and(eq(productDays.itineraryId, defaultItinerary.id)))
+            .orderBy(asc(productDays.dayNumber))
+        : [];
+    // Pull option translations in one round-trip for every option in this
+    // product. Fan-out per-option would be wasteful when products
+    // typically have a small number of options.
+    const optionIds = optionRows.map((o) => o.id);
+    const optionTrns = optionIds.length > 0
+        ? await db
+            .select()
+            .from(productOptionTranslations)
+            .where(inArray(productOptionTranslations.optionId, optionIds))
+        : [];
+    // Pick the best product-level translation. Falls through to the
+    // source row's name/description when no translation row matches —
+    // pickBestCachedLocale returns the closest available, so the
+    // server-locale chip reflects what the user actually sees.
+    const bestProductTrn = pickBestProductTranslation(productTrns, options.preferredLocales);
+    const productServedLocale = bestProductTrn?.served_locale ?? sourceLocaleFor(productRow);
+    const productMatchKind = bestProductTrn?.match_kind ?? "any";
+    const cover = mediaRows.find((m) => m.isCover) ?? mediaRows[0] ?? undefined;
+    const localizedName = bestProductTrn?.candidate.name ?? productRow.name;
+    const localizedDescription = bestProductTrn?.candidate.shortDescription ??
+        bestProductTrn?.candidate.description ??
+        productRow.description ??
+        null;
+    const content = productContentSchema.parse({
+        product: {
+            id: productRow.id,
+            name: localizedName,
+            status: productRow.status,
+            description: localizedDescription,
+            hero_image_url: cover?.url ?? null,
+            duration_days: estimateDurationDays(days, productRow),
+            start_date: dateToIso(productRow.startDate),
+            end_date: dateToIso(productRow.endDate),
+            sell_currency: productRow.sellCurrency,
+            supplier: productRow.supplierId ?? null,
+            tags: Array.isArray(productRow.tags) ? productRow.tags : [],
+        },
+        options: optionRows.map((opt) => {
+            const trnsForOption = optionTrns.filter((t) => t.optionId === opt.id);
+            const bestOptionTrn = pickBestOptionTranslation(trnsForOption, options.preferredLocales);
+            return {
+                id: opt.id,
+                name: bestOptionTrn?.candidate.name ?? opt.name,
+                description: bestOptionTrn?.candidate.shortDescription ??
+                    bestOptionTrn?.candidate.description ??
+                    opt.description ??
+                    null,
+                units: [],
+                inclusions: [],
+            };
+        }),
+        days: days.map((d) => ({
+            // Days don't have a translation table today; source values flow
+            // through. When `product_day_translations` lands, slot in here
+            // with the same pickBestCachedLocale call.
+            day_number: d.dayNumber,
+            title: d.title ?? null,
+            description: d.description ?? null,
+            location: d.location ?? null,
+            services: [],
+        })),
+        media: mediaRows
+            .filter((m) => !m.isBrochure)
+            .map((m) => ({
+            url: m.url,
+            type: mediaType(m.mediaType),
+            caption: m.altText ?? null,
+            alt: m.altText ?? null,
+        })),
+        policies: [],
+        // Owned products have no scheduled-departure table in v1; sourced
+        // products carry departures via the upstream's getContent payload.
+        departures: [],
+    });
+    const validation = validateProductContent(content);
+    if (!validation.valid) {
+        throw new Error(`owned product ${entityId} projection failed validation: ${validation.reason}`);
+    }
+    return {
+        content,
+        servedLocale: productServedLocale,
+        matchKind: productMatchKind,
+    };
+}
+function pickBestProductTranslation(rows, preferred) {
+    if (rows.length === 0)
+        return null;
+    const candidates = rows.map((r) => ({
+        locale: r.languageTag,
+        name: r.name,
+        shortDescription: r.shortDescription,
+        description: r.description,
+    }));
+    return pickBestCachedLocale(candidates, preferred);
+}
+function pickBestOptionTranslation(rows, preferred) {
+    if (rows.length === 0)
+        return null;
+    const candidates = rows.map((r) => ({
+        locale: r.languageTag,
+        name: r.name,
+        shortDescription: r.shortDescription,
+        description: r.description,
+    }));
+    return pickBestCachedLocale(candidates, preferred);
+}
+/**
+ * When no translation rows exist for the product, the source row's
+ * `name` + `description` are surfaced. We don't know what locale they
+ * were authored in — operators tend to author in their default
+ * deployment locale (commonly en-GB / en-US for UK / US deployments).
+ * The caller's `defaultSourceLocale` would be a cleaner fix; for now
+ * we report `und` (BCP 47 "undetermined") so the storefront chip
+ * doesn't claim a specific locale we can't verify.
+ */
+function sourceLocaleFor(_productRow) {
+    return "und";
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function estimateDurationDays(days, productRow) {
+    if (days.length > 0) {
+        const max = Math.max(...days.map((d) => d.dayNumber));
+        return Number.isFinite(max) && max > 0 ? max : null;
+    }
+    if (productRow.startDate && productRow.endDate) {
+        const start = new Date(productRow.startDate);
+        const end = new Date(productRow.endDate);
+        if (!Number.isNaN(start.getTime()) && !Number.isNaN(end.getTime())) {
+            const diffMs = end.getTime() - start.getTime();
+            const days = Math.round(diffMs / (24 * 60 * 60 * 1000));
+            return days > 0 ? days : null;
+        }
+    }
+    return null;
+}
+function dateToIso(value) {
+    if (!value)
+        return null;
+    if (typeof value === "string")
+        return value;
+    return value.toISOString().slice(0, 10);
+}
+function mediaType(value) {
+    if (value === "video")
+        return "video";
+    if (value === "document")
+        return "document";
+    return "image";
+}