@voyant-travel/catalog 0.117.2

package/dist/services/build-indexer-document.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { createFieldPolicyRegistry, defineFieldPolicy } from "../contract.js";
+import { buildIndexerDocument } from "./indexer-service.js";
+const registry = createFieldPolicyRegistry(defineFieldPolicy([
+    {
+        path: "title",
+        class: "merchandisable",
+        merge: "replace",
+        editRole: "marketing",
+        overrideFriction: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        visibility: ["staff", "customer", "partner"],
+    },
+    {
+        path: "description",
+        class: "merchandisable",
+        merge: "replace",
+        editRole: "marketing",
+        overrideFriction: "none",
+        snapshot: "on-book",
+        query: "blob-only", // stored on the entity row but not indexed
+        visibility: ["staff", "customer", "partner"],
+    },
+    {
+        path: "internal_notes",
+        class: "merchandisable",
+        merge: "replace",
+        editRole: "ops",
+        overrideFriction: "none",
+        snapshot: "never",
+        query: "indexed-column",
+        visibility: ["staff"],
+    },
+    {
+        path: "tags[]",
+        class: "merchandisable",
+        merge: "additive-set",
+        editRole: "marketing",
+        overrideFriction: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        visibility: ["staff", "customer", "partner"],
+    },
+]));
+const customerSlice = {
+    vertical: "products",
+    locale: "en-GB",
+    audience: "customer",
+    market: "default",
+};
+const adminSlice = {
+    vertical: "products",
+    locale: "en-GB",
+    audience: "staff-admin",
+    market: "default",
+};
+const projection = new Map([
+    ["title", "Bali Wellness"],
+    ["description", "A long description"],
+    ["internal_notes", "Margin tight, push hard in Q3"],
+    ["tags[]", ["wellness", "yoga"]],
+]);
+describe("buildIndexerDocument", () => {
+    it("includes the entity id in the returned document", () => {
+        const doc = buildIndexerDocument(registry, projection, customerSlice, "prod_xyz");
+        expect(doc.id).toBe("prod_xyz");
+    });
+    it("skips blob-only fields (description) — stored on row, not indexed", () => {
+        const doc = buildIndexerDocument(registry, projection, customerSlice, "prod_xyz");
+        expect(doc.fields).not.toHaveProperty("description");
+    });
+    it("excludes staff-only fields from customer-audience documents", () => {
+        const doc = buildIndexerDocument(registry, projection, customerSlice, "prod_xyz");
+        expect(doc.fields).not.toHaveProperty("internal_notes");
+        expect(doc.fields).toHaveProperty("title");
+    });
+    it("includes staff-only fields in admin documents (cross-audience denormalization)", () => {
+        const doc = buildIndexerDocument(registry, projection, adminSlice, "prod_xyz");
+        expect(doc.fields).toHaveProperty("internal_notes");
+        expect(doc.fields).toHaveProperty("title");
+    });
+    it("strips `[]` suffix from list-field names", () => {
+        const doc = buildIndexerDocument(registry, projection, customerSlice, "prod_xyz");
+        expect(doc.fields).toHaveProperty("tags");
+        expect(doc.fields).not.toHaveProperty("tags[]");
+        expect(doc.fields.tags).toEqual(["wellness", "yoga"]);
+    });
+    it("accepts natural projection keys for list policies", () => {
+        const doc = buildIndexerDocument(registry, new Map([["tags", ["wellness", "yoga"]]]), customerSlice, "prod_xyz");
+        expect(doc.fields.tags).toEqual(["wellness", "yoga"]);
+    });
+    it("ignores fields not declared in the registry", () => {
+        const projectionWithExtra = new Map([
+            ["title", "Hello"],
+            ["phantom_field", "????"],
+        ]);
+        const doc = buildIndexerDocument(registry, projectionWithExtra, customerSlice, "prod_xyz");
+        expect(doc.fields).toHaveProperty("title");
+        expect(doc.fields).not.toHaveProperty("phantom_field");
+    });
+});

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

@@ -0,0 +1,125 @@
+/**
+ * Catalog content-service primitives.
+ *
+ * Phase C of the sourced-content architecture. This module is the runtime
+ * home for per-vertical content services.
+ *
+ * The pure, dependency-free primitives — `isStale`, `pickBestCachedLocale`,
+ * `parseJsonPointer` / `applyJsonPointerOverlay`, and
+ * `mergeOverlaysIntoContent` — now live in `@voyant-travel/catalog-contracts`
+ * so external adapter authors can compose and validate content payloads
+ * without the catalog runtime. They are re-exported here so existing
+ * `@voyant-travel/catalog` import paths stay stable.
+ *
+ * What remains defined here are the runtime-bound primitives that need a
+ * Drizzle/Postgres connection and therefore cannot live in the contracts
+ * package:
+ *
+ *   - `withContentRefreshLock` — Postgres advisory-lock singleflight for
+ *                                cross-worker SWR refresh dedup.
+ *   - `createInvalidateOnDrift` / `buildDriftInvalidationPredicate` —
+ *                                content-drift → cache-invalidation against
+ *                                a per-vertical `*_sourced_content` table.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.4, §3.4.1, §3.5.3,
+ * §3.5.4.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { PgColumn, PgTable } from "drizzle-orm/pg-core";
+import type { ContentDriftEvent } from "../drift/events.js";
+export { applyJsonPointerOverlay, type ContentLocaleMatchKind, type ContentLocaleResolution, type ContentOverlay, isStale, JsonPointerError, type MergeOverlaysOptions, mergeOverlaysIntoContent, parseJsonPointer, pickBestCachedLocale, } from "@voyant-travel/catalog-contracts/content";
+/**
+ * Acquire a Postgres advisory lock keyed on
+ * `content:${entityModule}:${entityId}:${locale}:${market}` and run
+ * `fn`. If the lock is held by another worker, returns `null` without
+ * running `fn` — the caller serves the stale row and lets the
+ * lock-holder do the refresh.
+ *
+ * Uses session-level `pg_try_advisory_lock` + `pg_advisory_unlock`. The
+ * lock is released when the function returns or throws. Caller is
+ * responsible for serving stale data when this returns null.
+ *
+ * Cross-worker dedup is the point — in-process Map-based singleflight
+ * only collapses requests inside one worker; CF Workers / multi-pod
+ * deployments need DB-level coordination (see sourced-content §3.4).
+ */
+export declare function withContentRefreshLock<T>(db: AnyDrizzleDb, options: {
+    entityModule: string;
+    entityId: string;
+    locale: string;
+    market?: string;
+}, fn: () => Promise<T>): Promise<T | null>;
+/**
+ * Build the SQL predicate that matches cache rows affected by a
+ * `ContentDriftEvent`. Verticals call this to scope an invalidation
+ * `UPDATE … SET fresh_until = now()` against their own content table.
+ *
+ * Predicate semantics:
+ *   - Always matches `entity_module = event.entity_module` AND
+ *     `entity_id = event.entity_id`.
+ *   - When `event.locale` is set, narrows to that locale only;
+ *     otherwise matches all locales.
+ *   - When `event.market` is set, narrows to that market only;
+ *     otherwise matches all markets.
+ *
+ * Returned shape is a `BuiltDriftPredicate` carrying the column names
+ * the vertical needs to match, plus the values. Verticals build their
+ * `where(...)` clause from this; we don't import per-vertical tables
+ * here.
+ */
+export interface BuiltDriftPredicate {
+    entity_module: string;
+    entity_id: string;
+    locale: string | null;
+    market: string | null;
+}
+/**
+ * Per-vertical `invalidateOnDrift(db, event)` runner. Built via
+ * `createInvalidateOnDrift(table)` against the vertical's
+ * `*_sourced_content` table. When a `ContentDriftEvent` fires, the
+ * vertical's wired runner sets `fresh_until = now()` on every row
+ * matching `(entity_module, entity_id [, locale [, market]])` so the
+ * next read serves stale + schedules a SWR refresh (sourced-content
+ * §3.4.1).
+ */
+export type InvalidateOnDrift = (db: AnyDrizzleDb, event: ContentDriftEvent) => Promise<{
+    invalidated: number;
+}>;
+/**
+ * Column shape every vertical's `*_sourced_content` table satisfies.
+ * The factory uses these to build the WHERE clause without importing
+ * per-vertical tables — keeps the catalog package neutral.
+ */
+export interface VerticalContentInvalidatableTable {
+    entity_id: PgColumn;
+    locale: PgColumn;
+    market: PgColumn;
+    fresh_until: PgColumn;
+}
+export interface CreateInvalidateOnDriftOptions {
+    /**
+     * Entity module this invalidator handles (e.g. `"products"`,
+     * `"cruises"`). Events targeting other modules are skipped silently.
+     * Templates wire one runner per vertical and dispatch by
+     * `event.entity_module`.
+     */
+    entityModule: string;
+}
+/**
+ * Build a per-vertical `invalidateOnDrift` runner against the
+ * vertical's `*_sourced_content` drizzle table. The returned function
+ * is the sourced-content §3.4.1 invalidation primitive — verticals
+ * subscribe their runner to the drift-event bus.
+ *
+ * Semantics:
+ *   - Skips events whose `entity_module` doesn't match `options.entityModule`.
+ *     Templates compose runners across verticals; mismatched events are
+ *     not this runner's concern.
+ *   - When the event scopes `locale` and/or `market`, the WHERE clause
+ *     narrows accordingly. Wildcards (event.locale unset / event.market
+ *     unset) match all rows for that axis — full-entity invalidation.
+ *   - Returns `{ invalidated }` count for ops dashboards.
+ */
+export declare function createInvalidateOnDrift<TTable extends PgTable & VerticalContentInvalidatableTable>(table: TTable, options: CreateInvalidateOnDriftOptions): InvalidateOnDrift;
+export declare function buildDriftInvalidationPredicate(event: ContentDriftEvent): BuiltDriftPredicate;
+//# sourceMappingURL=content-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-service.d.ts","sourceRoot":"","sources":["../../src/services/content-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAM3D,OAAO,EACL,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,OAAO,EACP,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0CAA0C,CAAA;AAMjD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE;IACP,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,EACD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CASnB;AA2CD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,iBAAiB,KACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAErC;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,QAAQ,CAAA;IACnB,MAAM,EAAE,QAAQ,CAAA;IAChB,MAAM,EAAE,QAAQ,CAAA;IAChB,WAAW,EAAE,QAAQ,CAAA;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,OAAO,GAAG,iCAAiC,EAChG,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,8BAA8B,GACtC,iBAAiB,CA2BnB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAO7F"}

package/dist/services/content-service.js

@@ -0,0 +1,139 @@
+/**
+ * Catalog content-service primitives.
+ *
+ * Phase C of the sourced-content architecture. This module is the runtime
+ * home for per-vertical content services.
+ *
+ * The pure, dependency-free primitives — `isStale`, `pickBestCachedLocale`,
+ * `parseJsonPointer` / `applyJsonPointerOverlay`, and
+ * `mergeOverlaysIntoContent` — now live in `@voyant-travel/catalog-contracts`
+ * so external adapter authors can compose and validate content payloads
+ * without the catalog runtime. They are re-exported here so existing
+ * `@voyant-travel/catalog` import paths stay stable.
+ *
+ * What remains defined here are the runtime-bound primitives that need a
+ * Drizzle/Postgres connection and therefore cannot live in the contracts
+ * package:
+ *
+ *   - `withContentRefreshLock` — Postgres advisory-lock singleflight for
+ *                                cross-worker SWR refresh dedup.
+ *   - `createInvalidateOnDrift` / `buildDriftInvalidationPredicate` —
+ *                                content-drift → cache-invalidation against
+ *                                a per-vertical `*_sourced_content` table.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.4, §3.4.1, §3.5.3,
+ * §3.5.4.
+ */
+import { and, eq, sql } from "drizzle-orm";
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure content primitives — single source of truth in @voyant-travel/catalog-contracts
+// ─────────────────────────────────────────────────────────────────────────────
+export { applyJsonPointerOverlay, isStale, JsonPointerError, mergeOverlaysIntoContent, parseJsonPointer, pickBestCachedLocale, } from "@voyant-travel/catalog-contracts/content";
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-worker singleflight via Postgres advisory lock
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Acquire a Postgres advisory lock keyed on
+ * `content:${entityModule}:${entityId}:${locale}:${market}` and run
+ * `fn`. If the lock is held by another worker, returns `null` without
+ * running `fn` — the caller serves the stale row and lets the
+ * lock-holder do the refresh.
+ *
+ * Uses session-level `pg_try_advisory_lock` + `pg_advisory_unlock`. The
+ * lock is released when the function returns or throws. Caller is
+ * responsible for serving stale data when this returns null.
+ *
+ * Cross-worker dedup is the point — in-process Map-based singleflight
+ * only collapses requests inside one worker; CF Workers / multi-pod
+ * deployments need DB-level coordination (see sourced-content §3.4).
+ */
+export async function withContentRefreshLock(db, options, fn) {
+    const key = contentLockKey(options);
+    const acquired = await tryAdvisoryLock(db, key);
+    if (!acquired)
+        return null;
+    try {
+        return await fn();
+    }
+    finally {
+        await releaseAdvisoryLock(db, key);
+    }
+}
+function contentLockKey(options) {
+    return `content:${options.entityModule}:${options.entityId}:${options.locale}:${options.market ?? "*"}`;
+}
+async function tryAdvisoryLock(db, key) {
+    // pg_try_advisory_lock(bigint) — hash the string into a bigint. Use
+    // hashtextextended which Postgres exposes for stable string hashing
+    // (bigint output, not int4 like hashtext).
+    const rows = await db.execute(
+    // agent-quality: raw-sql reviewed -- owner: catalog; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+    sql `SELECT pg_try_advisory_lock(hashtextextended(${key}, 0)) AS locked`);
+    // Drizzle's execute() result shape varies by driver; we accept both
+    // an array-shaped result and a `.rows` wrapper.
+    const first = pickFirstRow(rows);
+    return Boolean(first?.locked);
+}
+async function releaseAdvisoryLock(db, key) {
+    // agent-quality: raw-sql reviewed -- owner: catalog; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+    await db.execute(sql `SELECT pg_advisory_unlock(hashtextextended(${key}, 0))`);
+}
+function pickFirstRow(result) {
+    if (Array.isArray(result))
+        return result[0];
+    if (result && typeof result === "object" && "rows" in result) {
+        const rows = result.rows;
+        if (Array.isArray(rows))
+            return rows[0];
+    }
+    return undefined;
+}
+/**
+ * Build a per-vertical `invalidateOnDrift` runner against the
+ * vertical's `*_sourced_content` drizzle table. The returned function
+ * is the sourced-content §3.4.1 invalidation primitive — verticals
+ * subscribe their runner to the drift-event bus.
+ *
+ * Semantics:
+ *   - Skips events whose `entity_module` doesn't match `options.entityModule`.
+ *     Templates compose runners across verticals; mismatched events are
+ *     not this runner's concern.
+ *   - When the event scopes `locale` and/or `market`, the WHERE clause
+ *     narrows accordingly. Wildcards (event.locale unset / event.market
+ *     unset) match all rows for that axis — full-entity invalidation.
+ *   - Returns `{ invalidated }` count for ops dashboards.
+ */
+export function createInvalidateOnDrift(table, options) {
+    return async function invalidateOnDrift(db, event) {
+        if (event.entity_module !== options.entityModule) {
+            return { invalidated: 0 };
+        }
+        const conditions = [eq(table.entity_id, event.entity_id)];
+        if (event.locale)
+            conditions.push(eq(table.locale, event.locale));
+        if (event.market)
+            conditions.push(eq(table.market, event.market));
+        const where = conditions.length === 1 ? conditions[0] : and(...conditions);
+        // Drizzle's update-set typing is generic over the table's
+        // $inferInsert keys; the generic wrapper here narrows away those
+        // keys, so we use raw SQL for the SET clause and the table reference
+        // for the WHERE/RETURNING. This keeps the SQL identical to a
+        // typed-call while the catalog package stays neutral about the
+        // vertical's exact table schema.
+        // biome-ignore lint/suspicious/noExplicitAny: see comment above -- owner: catalog; existing suppression is intentional pending typed cleanup.
+        const updateBuilder = db.update(table);
+        const result = (await updateBuilder
+            .set({ fresh_until: sql `now()` })
+            .where(where)
+            .returning({ entity_id: table.entity_id }));
+        return { invalidated: result.length };
+    };
+}
+export function buildDriftInvalidationPredicate(event) {
+    return {
+        entity_module: event.entity_module,
+        entity_id: event.entity_id,
+        locale: event.locale ?? null,
+        market: event.market ?? null,
+    };
+}

package/dist/services/content-service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content-service.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-service.test.d.ts","sourceRoot":"","sources":["../../src/services/content-service.test.ts"],"names":[],"mappings":""}