@voyantjs/products 0.19.0 → 0.21.0

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

@@ -0,0 +1,90 @@
+/**
+ * Product content synthesizer — fallback for thin adapters that declare
+ * `supportsContentFetch: false`.
+ *
+ * Per sourced-content §3.6, the synthesizer's job is to produce the
+ * **most complete** content payload it legitimately can from what the
+ * catalog plane already knows: the durable sourced-entry projection,
+ * the editorial overlay store, and plane-level provenance metadata.
+ *
+ * Returns the same shape as a real `getContent` so consumers (detail
+ * pages, the booking journey, snapshot capture) cannot tell the two
+ * paths apart from the type signature. Fields the synthesizer cannot
+ * fill render as typed empty states — never as missing properties.
+ *
+ * What it does NOT do:
+ *   - Mine prior snapshot rows (those carry customer-scoped PII and
+ *     are point-in-time, not generic content).
+ *   - Machine-translate (that's the adapter's `getContent` +
+ *     `machine_translated: true` path).
+ *   - Synthesize plausible-but-unverified fields ("hotels usually have
+ *     a pool" is not a basis for an amenity).
+ *   - Cache its own output (inputs change at projection / overlay
+ *     write time; a cache layer would just complicate invalidation).
+ */
+import type { ProvenanceReadResult } from "@voyantjs/catalog";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { type ProductContent } from "./content-shape.js";
+export interface SynthesizeProductContentOptions {
+    /**
+     * The provenance read for the entity. Carries the durable projection
+     * captured at discover() time — the synthesizer's primary input.
+     */
+    provenance: Extract<ProvenanceReadResult, {
+        kind: "sourced";
+    }>;
+    /**
+     * Optional locale-aware overlays. When present, layered on top via
+     * RFC 6901 JSON pointer paths. Caller passes overlays already
+     * filtered to the active scope (locale, audience, market) per the
+     * variant fallback chain.
+     */
+    overlays?: ReadonlyArray<{
+        field_path: string;
+        value: unknown;
+    }>;
+}
+export interface SynthesizedProductContent {
+    /** The synthesized payload. Validated against the products/v1 schema. */
+    content: ProductContent;
+    /** Schema version stamped on the synthesized payload. */
+    content_schema_version: string;
+    /**
+     * The locale this synthesis represents. Synthesizer output isn't
+     * locale-pinned at the projection level — projections capture the
+     * adapter's canonical fields. Caller's locale is reported back so
+     * UI / SWR machinery can stamp it consistently.
+     */
+    served_locale: string;
+    /**
+     * Whether the upstream adapter is rich (this synthesis is a fallback)
+     * vs. thin (this synthesis is the real path).
+     */
+    source_kind: string;
+    /**
+     * Source provenance hints for UI badges ("served by …", "limited
+     * content available").
+     */
+    source_provider?: string;
+}
+/**
+ * Synthesize a `ProductContent` payload from projection + overlay +
+ * plane metadata. Pure-ish: takes a provenance read result and an
+ * optional overlay list; returns a typed-empty-state-filled content
+ * blob.
+ */
+export declare function synthesizeProductContent(scope: {
+    locale: string;
+}, options: SynthesizeProductContentOptions): SynthesizedProductContent;
+/**
+ * Drizzle-bound convenience wrapper: fetches active overlays for the
+ * entity and runs the synthesizer. Verticals call this from their
+ * content service when no `getContent` adapter is registered (or when
+ * the synthesizer is the fallback for missing-cache + thin-adapter).
+ */
+export declare function synthesizeProductContentFromDb(db: AnyDrizzleDb, scope: {
+    locale: string;
+}, provenance: Extract<ProvenanceReadResult, {
+    kind: "sourced";
+}>): Promise<SynthesizedProductContent>;
+//# sourceMappingURL=service-content-synthesizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-content-synthesizer.d.ts","sourceRoot":"","sources":["../src/service-content-synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAA;AAE3B,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC,oBAAoB,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;IAC9D;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACjE;AAED,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,OAAO,EAAE,cAAc,CAAA;IACvB,yDAAyD;IACzD,sBAAsB,EAAE,MAAM,CAAA;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EACzB,OAAO,EAAE,+BAA+B,GACvC,yBAAyB,CAoC3B;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EACzB,UAAU,EAAE,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GAC7D,OAAO,CAAC,yBAAyB,CAAC,CAMpC"}

package/dist/service-content-synthesizer.js

@@ -0,0 +1,171 @@
+/**
+ * Product content synthesizer — fallback for thin adapters that declare
+ * `supportsContentFetch: false`.
+ *
+ * Per sourced-content §3.6, the synthesizer's job is to produce the
+ * **most complete** content payload it legitimately can from what the
+ * catalog plane already knows: the durable sourced-entry projection,
+ * the editorial overlay store, and plane-level provenance metadata.
+ *
+ * Returns the same shape as a real `getContent` so consumers (detail
+ * pages, the booking journey, snapshot capture) cannot tell the two
+ * paths apart from the type signature. Fields the synthesizer cannot
+ * fill render as typed empty states — never as missing properties.
+ *
+ * What it does NOT do:
+ *   - Mine prior snapshot rows (those carry customer-scoped PII and
+ *     are point-in-time, not generic content).
+ *   - Machine-translate (that's the adapter's `getContent` +
+ *     `machine_translated: true` path).
+ *   - Synthesize plausible-but-unverified fields ("hotels usually have
+ *     a pool" is not a basis for an amenity).
+ *   - Cache its own output (inputs change at projection / overlay
+ *     write time; a cache layer would just complicate invalidation).
+ */
+import { fetchOverlaysForEntity, mergeOverlaysIntoContent } from "@voyantjs/catalog";
+import { PRODUCTS_CONTENT_SCHEMA_VERSION, productContentSchema, } from "./content-shape.js";
+/**
+ * Synthesize a `ProductContent` payload from projection + overlay +
+ * plane metadata. Pure-ish: takes a provenance read result and an
+ * optional overlay list; returns a typed-empty-state-filled content
+ * blob.
+ */
+export function synthesizeProductContent(scope, options) {
+    const projection = options.provenance.projection;
+    const product = pickProductSummary(projection, options.provenance);
+    const media = pickMedia(projection);
+    const policies = pickPolicies(projection);
+    const baseContent = {
+        product,
+        options: [],
+        days: [],
+        media,
+        policies,
+        departures: [],
+    };
+    let merged = baseContent;
+    if (options.overlays && options.overlays.length > 0) {
+        const result = mergeOverlaysIntoContent(baseContent, options.overlays, {
+            validate(p) {
+                const r = productContentSchema.safeParse(p);
+                return r.success
+                    ? { valid: true }
+                    : { valid: false, reason: r.error.issues[0]?.message ?? "invalid" };
+            },
+        });
+        merged = productContentSchema.parse(result);
+    }
+    return {
+        content: merged,
+        content_schema_version: PRODUCTS_CONTENT_SCHEMA_VERSION,
+        served_locale: scope.locale,
+        source_kind: options.provenance.provenance.source_kind,
+        source_provider: options.provenance.provenance.source_provider,
+    };
+}
+/**
+ * Drizzle-bound convenience wrapper: fetches active overlays for the
+ * entity and runs the synthesizer. Verticals call this from their
+ * content service when no `getContent` adapter is registered (or when
+ * the synthesizer is the fallback for missing-cache + thin-adapter).
+ */
+export async function synthesizeProductContentFromDb(db, scope, provenance) {
+    const overlays = await fetchOverlaysForEntity(db, "products", entityIdFromProvenance(provenance));
+    return synthesizeProductContent(scope, {
+        provenance,
+        overlays: overlays.map((o) => ({ field_path: o.field_path, value: o.value })),
+    });
+}
+function entityIdFromProvenance(provenance) {
+    // The sourced-entry row's entry_id is the catalog-side TypeID; the
+    // products module-side id is on the projection row. Synthesizer
+    // callers thread the products-module entity_id through scope; we
+    // take it off the projection's `id` field when the adapter set it,
+    // falling back to the entry_id (which is wrong for read paths but
+    // safe for tests).
+    const fromProjection = provenance.projection.id;
+    if (typeof fromProjection === "string" && fromProjection.length > 0) {
+        return fromProjection;
+    }
+    return provenance.entry_id;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Field pickers
+// ─────────────────────────────────────────────────────────────────────────────
+function pickProductSummary(projection, provenance) {
+    return {
+        id: stringOr(projection.id, "") || provenance.entry_id,
+        name: stringOr(projection.name, "") || stringOr(projection.title, "") || "Unnamed product",
+        status: stringOr(projection.status, undefined),
+        description: stringOr(projection.description, null),
+        highlights: stringArrayOr(projection.highlights, []),
+        hero_image_url: stringOr(projection.hero_image_url, null),
+        duration_days: numberOr(projection.duration_days, null),
+        start_date: stringOr(projection.start_date, null),
+        end_date: stringOr(projection.end_date, null),
+        sell_currency: stringOr(projection.sell_currency, null),
+        supplier: stringOr(projection.supplier, null) ??
+            stringOr(projection.supplier_name, null) ??
+            provenance.provenance.source_provider ??
+            null,
+        country: stringOr(projection.country, null),
+        departure_city: stringOr(projection.departure_city, null),
+        tags: stringArrayOr(projection.tags, []),
+    };
+}
+function pickMedia(projection) {
+    const heroUrl = stringOr(projection.hero_image_url, null);
+    const out = [];
+    if (heroUrl) {
+        out.push({ url: heroUrl, type: "image", caption: null, alt: null });
+    }
+    // Some adapters send a `media` array on the projection. Accept it
+    // when shaped reasonably; ignore otherwise rather than synthesize.
+    const additional = projection.media;
+    if (Array.isArray(additional)) {
+        for (const item of additional) {
+            if (item && typeof item === "object") {
+                const obj = item;
+                const url = stringOr(obj.url, null);
+                if (!url)
+                    continue;
+                out.push({
+                    url,
+                    type: pickMediaType(obj.type),
+                    caption: stringOr(obj.caption, null),
+                    alt: stringOr(obj.alt, null),
+                });
+            }
+        }
+    }
+    return out;
+}
+function pickMediaType(value) {
+    if (value === "video")
+        return "video";
+    if (value === "document")
+        return "document";
+    return "image";
+}
+function pickPolicies(projection) {
+    const policies = [];
+    const cancel = stringOr(projection.cancellation_policy, null);
+    if (cancel)
+        policies.push({ kind: "cancellation", body: cancel });
+    const payment = stringOr(projection.payment_terms, null);
+    if (payment)
+        policies.push({ kind: "payment", body: payment });
+    return policies;
+}
+function stringOr(value, fallback) {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function numberOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function stringArrayOr(value, fallback) {
+    if (!Array.isArray(value))
+        return fallback;
+    const out = value.filter((v) => typeof v === "string");
+    return out.length > 0 ? out : fallback;
+}

package/dist/service-content.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Product content service — `getProductContent` with owned-vs-sourced
+ * dispatch, locale-resolved cache reads, SWR refresh, and synthesizer
+ * fallback.
+ *
+ * One entry point per vertical; the catalog plane stays neutral about
+ * per-vertical content shapes. Detail routes (operator and storefront)
+ * call `getProductContent(db, entityId, scope, options)` and get back a
+ * fully-resolved `ContentLocaleResolution<ProductContent>` regardless
+ * of whether the row is owned or sourced.
+ *
+ * Owned rows (entities in the products table without a sourced-entry
+ * row) read from the products tables directly — out of scope for this
+ * file in v1; callers that need owned reads compose them around this
+ * service. Phase D ships sourced + synthesizer; owned dispatch
+ * narrows when first sourced template adopts.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.3, §3.4, §3.6.
+ */
+import { type ContentLocaleResolution, type InvalidateOnDrift, type SourceAdapter, type SourceAdapterContext } from "@voyantjs/catalog";
+import type { SourceAdapterRegistry } from "@voyantjs/catalog/booking-engine";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { type ProductContent } from "./content-shape.js";
+export interface ProductContentScope {
+    /**
+     * Ordered locale preference, most-preferred first. The deployment's
+     * configured fallback chain should be appended by the caller (e.g.
+     * `["ro-RO", "ro", "en-GB", "en"]` for a ro-RO storefront request).
+     */
+    preferredLocales: ReadonlyArray<string>;
+    /** Optional market — `'*'` (any) by default. */
+    market?: string;
+    /** Optional currency for SWR refresh. Not used by the cache. */
+    currency?: string;
+    /**
+     * When false, the read service skips machine-translated rows in
+     * favor of the next-best non-MT match. False on operator-side views
+     * where ops want to see "real" content before deciding to override.
+     * Default: true (storefront-friendly).
+     */
+    acceptMachineTranslated?: boolean;
+}
+export interface GetProductContentOptions {
+    /**
+     * Adapter registry — used to resolve the adapter for SWR refresh
+     * and cache-miss fetches. Required because the read service needs
+     * to know which adapter handles a given source_kind.
+     */
+    registry: SourceAdapterRegistry;
+    /**
+     * Builds the per-call adapter context (typically supplies the
+     * connection_id + correlation_id).
+     */
+    buildAdapterContext?: (adapter: SourceAdapter) => SourceAdapterContext;
+    /**
+     * Optional sink for per-overlay diagnostics emitted by the
+     * content-shape-aware merger.
+     */
+    onOverlayError?: (event: {
+        field_path: string;
+        reason: string;
+    }) => void;
+    /**
+     * Bypass a fresh cache row and fetch directly from the source adapter.
+     * Use this for volatile fields embedded in content payloads, such as
+     * sourced departure capacity, where a 24h rich-content TTL is too coarse.
+     */
+    forceFresh?: boolean;
+}
+/**
+ * The successful result of a content read. Carries the resolved content
+ * payload, locale-match metadata, and freshness markers so callers can
+ * render UI hints ("served in English").
+ */
+export interface ResolvedProductContent {
+    content: ProductContent;
+    resolution: ContentLocaleResolution<{
+        locale: string;
+        payload: ProductContent;
+    }>;
+    /** Where the resolved content came from. */
+    source: "sourced-cache" | "sourced-fresh" | "synthesized" | "owned";
+    /** True when the cache row was stale and a background refresh was scheduled. */
+    served_stale: boolean;
+    /** True for synthesizer output. */
+    synthesized: boolean;
+    /** True when the upstream marked this content machine-translated. */
+    machine_translated: boolean;
+}
+/**
+ * Read the rich product content for one entity, resolving locale
+ * preference, applying overlays, and refreshing in the background when
+ * stale. Returns `null` only when the entity is unknown (no
+ * sourced-entry row, no owned row).
+ */
+export declare function getProductContent(db: AnyDrizzleDb, entityId: string, scope: ProductContentScope, options: GetProductContentOptions): Promise<ResolvedProductContent | null>;
+/**
+ * Drift event consumer — sets `fresh_until = now()` on every cache row
+ * matching the event's (entity_module, entity_id [, locale [, market]])
+ * scope. The next read serves stale + schedules a SWR refresh.
+ *
+ * Templates subscribe this to the catalog plane's drift-event bus.
+ * Per sourced-content §3.4.1.
+ */
+export declare const invalidateProductContentOnDrift: InvalidateOnDrift;
+//# sourceMappingURL=service-content.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-content.d.ts","sourceRoot":"","sources":["../src/service-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,uBAAuB,EAK5B,KAAK,iBAAiB,EAKtB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAGhD,OAAO,EAGL,KAAK,cAAc,EAGpB,MAAM,oBAAoB,CAAA;AAe3B,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,EAAE,qBAAqB,CAAA;IAC/B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,oBAAoB,CAAA;IACtE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IACxE;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,uBAAuB,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,CAAC,CAAA;IAChF,4CAA4C;IAC5C,MAAM,EAAE,eAAe,GAAG,eAAe,GAAG,aAAa,GAAG,OAAO,CAAA;IACnE,gFAAgF;IAChF,YAAY,EAAE,OAAO,CAAA;IACrB,mCAAmC;IACnC,WAAW,EAAE,OAAO,CAAA;IACpB,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA+KxC;AAoQD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,iBAG7C,CAAA"}