@voyantjs/products 0.20.0 → 0.21.0

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";
+}

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"}