@voyant-travel/inventory 0.1.0

package/dist/catalog-policy-promotions.js

@@ -0,0 +1,270 @@
+/**
+ * Catalog plane field policy for product → promotional-offer denormalization.
+ *
+ * Promotions are projected as **annotations only** — this policy does NOT
+ * touch the existing `priceFromAmountCents` field (that's emitted by the
+ * pricing extension and the two extensions can't read each other's output;
+ * see `docs/architecture/promotions-architecture.md` §3.7). Instead, we
+ * emit `bestOffer*` + `originalPriceFromAmountCents` and storefront
+ * consumers compute the effective price client-side:
+ *
+ *   effective = bestOfferDiscountKind === "percentage"
+ *     ? round(price × (1 - bestOfferDiscountPercent/100))
+ *     : price - bestOfferDiscountAmountCents
+ *
+ * Catalog filter / sort behavior continues to use `priceFromAmountCents`
+ * (the list price). A customer searching `< $200` won't find a
+ * `$250 → $180` discounted product via the filter — acknowledged v1
+ * limitation, see §15.1 of the architecture doc.
+ *
+ * Conditional offers are surfaced separately so storefront cards can
+ * render hints like "From 4 pax: extra 5% off" — the catalog plane
+ * doesn't know pax at index time, so any offer with a `minPax` condition
+ * lands here instead of in `bestOffer*`.
+ *
+ * Wire this policy into the products registry by composing with
+ * `productCatalogPolicy`:
+ *
+ *   const registry = createFieldPolicyRegistry([
+ *     ...productCatalogPolicy,
+ *     ...productPromotionsCatalogPolicy,
+ *   ])
+ *
+ * and wire `createProductPromotionsProjectionExtension` (from
+ * `@voyant-travel/commerce` promotion projection support) into
+ * `createProductDocumentBuilder` so the values land in the doc.
+ *
+ * Out of scope here:
+ *   - Localized offer names. Offers are operator-managed in one language
+ *     for v1 (`localized: false`); a `promotional_offer_translations`
+ *     table mirrors `destinations_translations` if/when needed.
+ *   - Discount-aware filter / sort. Requires the §15.1 ordered-extensions
+ *     contract change; deferred.
+ */
+import { defineFieldPolicy } from "@voyant-travel/catalog/contract";
+const PRODUCT_PROMOTIONS_FIELD_POLICY = [
+    // ── Best-offer existence flag ────────────────────────────────────────────
+    // Storefront filters use this for "show only products on sale" and to
+    // suppress an empty badge.
+    {
+        path: "hasOffer",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Best-offer ID ────────────────────────────────────────────────────────
+    // Used for deep-linking from a search card to the offer-detail page.
+    {
+        path: "bestOfferId",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Best-offer name (display) ────────────────────────────────────────────
+    // Single-locale in v1 — see file-header notes.
+    {
+        path: "bestOfferName",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Best-offer discount kind ─────────────────────────────────────────────
+    // `"percentage"` | `"fixed_amount"` | `null`. Drives storefront's badge
+    // rendering (% vs $).
+    {
+        path: "bestOfferDiscountKind",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Best-offer percentage (when kind = percentage) ───────────────────────
+    {
+        path: "bestOfferDiscountPercent",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Best-offer cents off (when kind = fixed_amount) ──────────────────────
+    {
+        path: "bestOfferDiscountAmountCents",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Original (un-discounted) price ───────────────────────────────────────
+    // Populated only when an offer applies (so consumers know what to
+    // strike through). When `null`, no offer applies and consumers should
+    // render `priceFromAmountCents` plain.
+    {
+        path: "originalPriceFromAmountCents",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Conditional-offer existence flag ─────────────────────────────────────
+    // Surfaced when an offer has a `minPax` condition the catalog plane
+    // can't satisfy at index time. Storefront uses this for the "From N
+    // pax: extra X% off" hint.
+    {
+        path: "hasConditionalOffer",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "conditionalOfferId",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "conditionalOfferName",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "conditionalOfferDiscountKind",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "conditionalOfferDiscountPercent",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "conditionalOfferDiscountAmountCents",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Conditional-offer minPax threshold ───────────────────────────────────
+    // Drives the "From N pax" message text.
+    {
+        path: "conditionalOfferMinPax",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+];
+/**
+ * Resolved promotions policy. Compose with `productCatalogPolicy` when
+ * building the products registry.
+ */
+export const productPromotionsCatalogPolicy = defineFieldPolicy(PRODUCT_PROMOTIONS_FIELD_POLICY);
+export { PRODUCT_PROMOTIONS_FIELD_POLICY };

package/dist/catalog-policy-taxonomy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Catalog plane field policy for product → taxonomy denormalization
+ * (categories + tags).
+ *
+ * These fields don't live on the `products` table — they're joined from
+ * `product_category_products` → `product_categories` (with parent walk for
+ * hierarchy denormalization) and `product_tag_products` → `product_tags` at
+ * index time and projected onto the product search document. See
+ * `docs/architecture/catalog-architecture.md` §5.4 — the search index is the
+ * canonical place for cross-entity denormalization.
+ *
+ * Storefront product cards filter and display by taxonomy:
+ *   - "Adventure tours" (filter: `categories[]` includes "Adventure")
+ *   - A product tagged "Hiking" (parent "Adventure") MUST also surface under
+ *     the "Adventure" filter — Typesense can't recurse, so the projection
+ *     denormalizes the full ancestor chain into `categories[]` /
+ *     `categoryIds[]`.
+ *   - "Family-friendly" (filter: `tags[]` includes "Family-friendly")
+ *
+ * Wire this policy into the products registry by composing with
+ * `productCatalogPolicy`:
+ *
+ *   const registry = createFieldPolicyRegistry([
+ *     ...productCatalogPolicy,
+ *     ...productTaxonomyCatalogPolicy,
+ *   ])
+ *
+ * and wire `createProductTaxonomyProjectionExtension` into
+ * `createProductDocumentBuilder` so the values land in the doc.
+ *
+ * Localization (#502): `product_category_translations` and
+ * `product_tag_translations` tables back the locale-aware label fields.
+ * Slice-locale rows win; if no row exists for the slice, the projection
+ * falls back to the canonical `productCategories.name` /
+ * `productTags.name`. Slug stays single-locale on `productCategories.slug`
+ * (per #502 non-goals — operators want stable URLs that don't shift when
+ * translations are edited).
+ *
+ * Out of scope here:
+ *   - Per-locale slugs. One canonical slug per category.
+ *   - Tag hierarchy. Tags are flat by design.
+ */
+import { type FieldPolicyInput } from "@voyant-travel/catalog/contract";
+declare const PRODUCT_TAXONOMY_FIELD_POLICY: FieldPolicyInput[];
+/**
+ * Resolved taxonomy policy. Compose with `productCatalogPolicy` when
+ * building the products registry.
+ */
+export declare const productTaxonomyCatalogPolicy: import("@voyant-travel/catalog").FieldPolicy[];
+export { PRODUCT_TAXONOMY_FIELD_POLICY };
+//# sourceMappingURL=catalog-policy-taxonomy.d.ts.map

package/dist/catalog-policy-taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-policy-taxonomy.d.ts","sourceRoot":"","sources":["../src/catalog-policy-taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAE1F,QAAA,MAAM,6BAA6B,EAAE,gBAAgB,EAiJpD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,gDAAmD,CAAA;AAE5F,OAAO,EAAE,6BAA6B,EAAE,CAAA"}

package/dist/catalog-policy-taxonomy.js

@@ -0,0 +1,191 @@
+/**
+ * Catalog plane field policy for product → taxonomy denormalization
+ * (categories + tags).
+ *
+ * These fields don't live on the `products` table — they're joined from
+ * `product_category_products` → `product_categories` (with parent walk for
+ * hierarchy denormalization) and `product_tag_products` → `product_tags` at
+ * index time and projected onto the product search document. See
+ * `docs/architecture/catalog-architecture.md` §5.4 — the search index is the
+ * canonical place for cross-entity denormalization.
+ *
+ * Storefront product cards filter and display by taxonomy:
+ *   - "Adventure tours" (filter: `categories[]` includes "Adventure")
+ *   - A product tagged "Hiking" (parent "Adventure") MUST also surface under
+ *     the "Adventure" filter — Typesense can't recurse, so the projection
+ *     denormalizes the full ancestor chain into `categories[]` /
+ *     `categoryIds[]`.
+ *   - "Family-friendly" (filter: `tags[]` includes "Family-friendly")
+ *
+ * Wire this policy into the products registry by composing with
+ * `productCatalogPolicy`:
+ *
+ *   const registry = createFieldPolicyRegistry([
+ *     ...productCatalogPolicy,
+ *     ...productTaxonomyCatalogPolicy,
+ *   ])
+ *
+ * and wire `createProductTaxonomyProjectionExtension` into
+ * `createProductDocumentBuilder` so the values land in the doc.
+ *
+ * Localization (#502): `product_category_translations` and
+ * `product_tag_translations` tables back the locale-aware label fields.
+ * Slice-locale rows win; if no row exists for the slice, the projection
+ * falls back to the canonical `productCategories.name` /
+ * `productTags.name`. Slug stays single-locale on `productCategories.slug`
+ * (per #502 non-goals — operators want stable URLs that don't shift when
+ * translations are edited).
+ *
+ * Out of scope here:
+ *   - Per-locale slugs. One canonical slug per category.
+ *   - Tag hierarchy. Tags are flat by design.
+ */
+import { defineFieldPolicy } from "@voyant-travel/catalog/contract";
+const PRODUCT_TAXONOMY_FIELD_POLICY = [
+    // ── Category labels (denormalized with ancestors, locale-aware) ──────────
+    // One entry per category in the linked-category-plus-ancestors set, deduped.
+    // A product linked to "Hiking" (parent: "Adventure") emits both
+    // ["Hiking", "Adventure"] so any-level filter matches a single equality.
+    // Locale-keyed since #502 — falls back to canonical name when no
+    // translation exists for the slice's locale.
+    {
+        path: "categories[]",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "entry-locale",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: true,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Category IDs (denormalized with ancestors) ───────────────────────────
+    // Same denormalization as `categories[]` but for ID-based filters
+    // (landing pages pinned to a category id rather than a label).
+    {
+        path: "categoryIds[]",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Category slugs (locale-stable, denormalized with ancestors) ──────────
+    // Storefront category-page links want stable URLs that don't shift when
+    // labels are edited. `product_categories.slug` exists today.
+    {
+        path: "categorySlugs[]",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Primary category (single, for badge display) ─────────────────────────
+    // Picked as the directly-linked category with the lowest sortOrder on
+    // `product_category_products` (the operator-controlled per-product
+    // ordering); ties broken by category name. Ancestors are NOT considered
+    // for primary — operators pin a leaf via the link table. Null when the
+    // product has no category links.
+    {
+        path: "primaryCategoryId",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        // Locale-aware since #502 — the primary's name follows the same
+        // translation lookup as `categories[]`.
+        path: "primaryCategoryName",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "entry-locale",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: true,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "primaryCategorySlug",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Tag labels ───────────────────────────────────────────────────────────
+    // `products.tags` (a free-form `text[]` column) already projects to
+    // `tags[]` from the base product policy. The structured `product_tags`
+    // table is a separate, normalized taxonomy — its labels land here under
+    // `tagLabels[]` to avoid colliding with the legacy column. One entry per
+    // linked tag.
+    {
+        // Locale-aware since #502 — falls back to canonical `productTags.name`
+        // when no `product_tag_translations` row exists for the slice's locale.
+        path: "tagLabels[]",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "entry-locale",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: true,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "tagIds[]",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+];
+/**
+ * Resolved taxonomy policy. Compose with `productCatalogPolicy` when
+ * building the products registry.
+ */
+export const productTaxonomyCatalogPolicy = defineFieldPolicy(PRODUCT_TAXONOMY_FIELD_POLICY);
+export { PRODUCT_TAXONOMY_FIELD_POLICY };

package/dist/catalog-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Catalog plane field policy for Inventory-owned products.
+ *
+ * Declares every product field's governance under the
+ * `@voyant-travel/catalog` 12-attribute contract. Phase B shake-out
+ * adoption — see `docs/architecture/catalog-architecture.md` §9.1.
+ *
+ * Scope of this file:
+ *   - The root `products` table (from `schema-core.ts`).
+ *   - Provenance + identity fields the catalog plane needs to track.
+ *
+ * Out of scope (deferred to follow-up adoption passes):
+ *   - `productOptions`, `optionUnits`, `productDays`, `productNotes`,
+ *     `productVersions` — promoted child entities (per composition rule §6.2);
+ *     each gets its own micro-registry when wired in.
+ *   - The split of `tags` into `marketing_tags` + `facet_tags` per the
+ *     human-readable / machine-evaluable rule (§7.1). Today's schema has a
+ *     single `tags` column; declared here as merchandisable with a TODO.
+ */
+import { type FieldPolicyInput } from "@voyant-travel/catalog/contract";
+/**
+ * Field-policy declarations for `products`. Pass through `defineFieldPolicy`
+ * to apply inheritance and produce the runtime registry.
+ */
+declare const PRODUCT_FIELD_POLICY: FieldPolicyInput[];
+/**
+ * Resolved field-policy registry for products. Verticals adopt the catalog
+ * plane by exporting this; templates wire it into the indexer, overlay
+ * resolver, and snapshot capture pipeline.
+ */
+export declare const productCatalogPolicy: import("@voyant-travel/catalog").FieldPolicy[];
+export { PRODUCT_FIELD_POLICY };
+//# sourceMappingURL=catalog-policy.d.ts.map

package/dist/catalog-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-policy.d.ts","sourceRoot":"","sources":["../src/catalog-policy.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAE1F;;;GAGG;AACH,QAAA,MAAM,oBAAoB,EAAE,gBAAgB,EAisB3C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,gDAA0C,CAAA;AAE3E,OAAO,EAAE,oBAAoB,EAAE,CAAA"}