@voyantjs/promotions 0.28.3

package/dist/schema.js

@@ -0,0 +1,126 @@
+/**
+ * Promotional offers schema — three tables backing the promotions module.
+ *
+ * Per docs/architecture/promotions-architecture.md §4:
+ *   - `promotional_offers` (root): the offer header (name, discount type/value,
+ *     scope JSONB, conditions JSONB, validity window, optional code).
+ *   - `promotional_offer_products` (link): denormalized materialization of the
+ *     offer's product set for the product-shaped scopes (`products`,
+ *     `categories`, `destinations`). Slice-shaped scopes (`global`, `markets`,
+ *     `audiences`) leave this table empty for that offer.
+ *   - `promotional_offer_redemptions` (audit): one row per (offer, booking).
+ *     Aggregated by the redemption recorder when a booking spans multiple
+ *     line-item snapshots that share an applied offer.
+ *
+ * Cross-module FK rules: `product_id` and `booking_id` are plain `text`
+ * columns with no `.references()` per the cross-module decoupling rule
+ * (see docs/architecture/schema-discipline.md). Cross-module integrity is
+ * enforced at the service layer.
+ */
+import { typeId } from "@voyantjs/db/lib/typeid-column";
+import { sql } from "drizzle-orm";
+import { boolean, index, integer, jsonb, numeric, pgEnum, pgTable, primaryKey, text, timestamp, uniqueIndex, } from "drizzle-orm/pg-core";
+export const promotionalOfferDiscountTypeEnum = pgEnum("promotional_offer_discount_type", [
+    "percentage",
+    "fixed_amount",
+]);
+export const promotionalOffers = pgTable("promotional_offers", {
+    id: typeId("promotional_offers"),
+    name: text("name").notNull(),
+    slug: text("slug").notNull(),
+    description: text("description"),
+    discountType: promotionalOfferDiscountTypeEnum("discount_type").notNull(),
+    /** Required when `discountType = 'percentage'`. e.g. 20.00 → 20% off. */
+    discountPercent: numeric("discount_percent", { precision: 5, scale: 2 }),
+    /** Required when `discountType = 'fixed_amount'`. */
+    discountAmountCents: integer("discount_amount_cents"),
+    /** Required when `discountType = 'fixed_amount'`. ISO 4217. */
+    currency: text("currency"),
+    /** Discriminated union — see §3.2. Source of truth for editing. */
+    scope: jsonb("scope").$type().notNull(),
+    /** Typed JSONB; `{ minPax?: number }` in v1. */
+    conditions: jsonb("conditions").$type().notNull().default({}),
+    validFrom: timestamp("valid_from", { withTimezone: true }),
+    validUntil: timestamp("valid_until", { withTimezone: true }),
+    /** NULL = auto-applied. Non-NULL = code-gated; stored lowercase. */
+    code: text("code"),
+    stackable: boolean("stackable").notNull().default(false),
+    active: boolean("active").notNull().default(true),
+    metadata: jsonb("metadata"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    // Hot-path range scan for the rule evaluator: "all currently-valid active offers".
+    index("idx_promotional_offers_active_validity").on(table.active, table.validFrom, table.validUntil),
+    // Slugs unique across active rows; archiving frees up the slug for reuse.
+    uniqueIndex("uidx_promotional_offers_slug_active").on(table.slug).where(sql `active = true`),
+    // Code uniqueness: case-insensitive (stored lowercase, compared lowercase),
+    // active rows only. Archived offers can recycle their code.
+    uniqueIndex("uidx_promotional_offers_code_active")
+        .on(sql `lower(code)`)
+        .where(sql `code is not null and active = true`),
+]);
+/**
+ * Denormalized scope materialization. Populated by the service layer on
+ * offer create/update for `scope.kind ∈ {products, categories, destinations}`.
+ * The catalog projection joins against this table on the hot path.
+ *
+ * `product_id` is a plain text column — no Drizzle `.references()` per the
+ * cross-module decoupling rule.
+ */
+export const promotionalOfferProducts = pgTable("promotional_offer_products", {
+    offerId: text("offer_id")
+        .notNull()
+        .references(() => promotionalOffers.id, { onDelete: "cascade" }),
+    productId: text("product_id").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.offerId, table.productId] }),
+    index("idx_pop_product").on(table.productId),
+]);
+/**
+ * Per-booking redemption record. ON DELETE RESTRICT on `offer_id` so an
+ * offer with redemptions cannot be deleted (operators must archive instead).
+ *
+ * The `(offer_id, booking_id)` unique constraint enforces "one row per
+ * (offer, booking)" — the redemption recorder aggregates `discount_applied_cents`
+ * across multiple line-item snapshots that share an offer before inserting,
+ * and the recorder upsert (`ON CONFLICT … DO UPDATE`) is idempotent against
+ * subscriber retries.
+ */
+export const promotionalOfferRedemptions = pgTable("promotional_offer_redemptions", {
+    id: typeId("promotional_offer_redemptions"),
+    offerId: text("offer_id")
+        .notNull()
+        .references(() => promotionalOffers.id, { onDelete: "restrict" }),
+    bookingId: text("booking_id").notNull(),
+    /** The literal code the customer entered (case preserved); NULL for auto-applied. */
+    codeUsed: text("code_used"),
+    discountAppliedCents: integer("discount_applied_cents").notNull(),
+    currency: text("currency").notNull(),
+    redeemedAt: timestamp("redeemed_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    index("idx_por_offer").on(table.offerId),
+    index("idx_por_booking").on(table.bookingId),
+    uniqueIndex("uidx_por_offer_booking").on(table.offerId, table.bookingId),
+]);
+/**
+ * Boundary-scheduler watermark — a single row tracking the last_tick the
+ * boundary scheduler observed. Per §9.2 of the architecture doc, the
+ * scheduler queries offers whose `valid_from` / `valid_until` falls
+ * BETWEEN `last_tick` and `now()` to detect lifecycle transitions.
+ *
+ * Single-row convention: rows are upserted with id = `BOUNDARY_SCHEDULER_STATE_ID`
+ * (typeid `pofs_default`). The unique constraint on `singleton_key` enforces
+ * "at most one row" defensively even if a future caller forgot the convention.
+ */
+export const promotionalOfferSchedulerState = pgTable("promotional_offer_scheduler_state", {
+    id: typeId("promotional_offer_scheduler_state"),
+    /**
+     * Sentinel column for single-row enforcement — always set to
+     * `'singleton'`. The unique index on this column means a second
+     * insert with a different id would still fail.
+     */
+    singletonKey: text("singleton_key").notNull().default("singleton"),
+    lastTick: timestamp("last_tick", { withTimezone: true }).notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [uniqueIndex("uidx_pofs_singleton").on(table.singletonKey)]);

package/dist/service-booking-confirmed.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Booking-confirmed redemption subscriber — records one row per
+ * (offer, booking) in `promotional_offer_redemptions` after a booking
+ * commits, by reading `pricing_applied_offers` from `catalog_quotes`
+ * (joined to the booking via the existing `consumed_booking_id` column).
+ *
+ * Why a subscriber rather than a `BookEntityDeps` hook: `bookEntity`
+ * does sequential writes without an enclosing `db.transaction(...)`,
+ * and the owned `quickCreate` path opens its own transaction in
+ * `@voyantjs/finance`. There is no single commit transaction to be
+ * atomic with — claiming "atomic with commit" would be misleading.
+ *
+ * Per docs/architecture/promotions-architecture.md §3.6 + §7.3.
+ *
+ * The recorder reads from `catalog_quotes` (the source of truth, written
+ * by `quoteEntity`) NOT from `booking_catalog_snapshot` to avoid an
+ * ordering race with the catalog-bridge's `captureSnapshotGraph`
+ * subscriber (both fire on the same `booking.confirmed` event).
+ *
+ * Idempotent on retry: the unique `(offer_id, booking_id)` index on
+ * `promotional_offer_redemptions` (per §4.3) lets the upsert refresh the
+ * aggregate cleanly even if the subscriber is replayed.
+ */
+import type { AnyDrizzleDb } from "@voyantjs/db";
+export interface RecordRedemptionsResult {
+    /** Number of distinct quotes scanned for this booking. */
+    quotesScanned: number;
+    /** Number of distinct offers aggregated across those quotes. */
+    offersFound: number;
+    /** Number of redemption rows upserted. Equals `offersFound` on success. */
+    rowsUpserted: number;
+}
+/**
+ * Aggregate `pricing_applied_offers` across every consumed quote for the
+ * booking and upsert one redemption row per offer.
+ *
+ * Aggregation rules (per §3.5):
+ *   - Multiple snapshots in the same booking sharing the same offer →
+ *     ONE redemption row with `discount_applied_cents` summed across all
+ *     occurrences.
+ *   - `code_used` defaults to the first non-null `appliedCode` seen for
+ *     that offer (auto-applied + code-gated never share the same
+ *     offer ID).
+ *   - `currency` carried from the AppliedOffer row directly.
+ */
+export declare function recordPromotionRedemptionsForBooking(db: AnyDrizzleDb, bookingId: string): Promise<RecordRedemptionsResult>;
+/**
+ * Wiring guidance for the operator template — the canonical subscriber
+ * pattern (mirrors how `catalog-bridge.ts` wires `captureSnapshotGraph`):
+ *
+ *   eventBus.subscribe<BookingConfirmedEvent>("booking.confirmed", async ({ data }) => {
+ *     await withDbFromEnv(env, async (db) => {
+ *       try {
+ *         await recordPromotionRedemptionsForBooking(db, data.bookingId)
+ *       } catch (err) {
+ *         // Failing here leaves the booking committed without a
+ *         // redemption row. Ops can backfill from
+ *         // `pricing_applied_offers` on the snapshot. Log so the gap
+ *         // is visible.
+ *         console.warn("[promotions] redemption subscriber failed", { …err })
+ *       }
+ *     })
+ *   })
+ *
+ * The factory is intentionally kept in the template (not here) because:
+ *   - The subscriber needs the template's `withDbFromEnv` from
+ *     `templates/operator/src/api/lib/db.ts` (the Pool lifecycle helper
+ *     introduced in #510 / #512). That helper isn't exported from a
+ *     package.
+ *   - Keeping the package package-side core (`recordPromotionRedemptionsForBooking`)
+ *     and the wiring template-side mirrors the existing catalog-bridge
+ *     subscriber pattern.
+ */
+export declare const __test__: {
+    recordPromotionRedemptionsForBooking: typeof recordPromotionRedemptionsForBooking;
+};
+//# sourceMappingURL=service-booking-confirmed.d.ts.map

package/dist/service-booking-confirmed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-booking-confirmed.d.ts","sourceRoot":"","sources":["../src/service-booking-confirmed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAMhD,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oCAAoC,CACxD,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,uBAAuB,CAAC,CA0ElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,eAAO,MAAM,QAAQ;;CAA2C,CAAA"}

package/dist/service-booking-confirmed.js

@@ -0,0 +1,134 @@
+/**
+ * Booking-confirmed redemption subscriber — records one row per
+ * (offer, booking) in `promotional_offer_redemptions` after a booking
+ * commits, by reading `pricing_applied_offers` from `catalog_quotes`
+ * (joined to the booking via the existing `consumed_booking_id` column).
+ *
+ * Why a subscriber rather than a `BookEntityDeps` hook: `bookEntity`
+ * does sequential writes without an enclosing `db.transaction(...)`,
+ * and the owned `quickCreate` path opens its own transaction in
+ * `@voyantjs/finance`. There is no single commit transaction to be
+ * atomic with — claiming "atomic with commit" would be misleading.
+ *
+ * Per docs/architecture/promotions-architecture.md §3.6 + §7.3.
+ *
+ * The recorder reads from `catalog_quotes` (the source of truth, written
+ * by `quoteEntity`) NOT from `booking_catalog_snapshot` to avoid an
+ * ordering race with the catalog-bridge's `captureSnapshotGraph`
+ * subscriber (both fire on the same `booking.confirmed` event).
+ *
+ * Idempotent on retry: the unique `(offer_id, booking_id)` index on
+ * `promotional_offer_redemptions` (per §4.3) lets the upsert refresh the
+ * aggregate cleanly even if the subscriber is replayed.
+ */
+import { catalogQuotesTable } from "@voyantjs/catalog/booking-engine";
+import { eq, sql } from "drizzle-orm";
+import { promotionalOfferRedemptions } from "./schema.js";
+/**
+ * Aggregate `pricing_applied_offers` across every consumed quote for the
+ * booking and upsert one redemption row per offer.
+ *
+ * Aggregation rules (per §3.5):
+ *   - Multiple snapshots in the same booking sharing the same offer →
+ *     ONE redemption row with `discount_applied_cents` summed across all
+ *     occurrences.
+ *   - `code_used` defaults to the first non-null `appliedCode` seen for
+ *     that offer (auto-applied + code-gated never share the same
+ *     offer ID).
+ *   - `currency` carried from the AppliedOffer row directly.
+ */
+export async function recordPromotionRedemptionsForBooking(db, bookingId) {
+    const rows = await db
+        .select({ pricing_applied_offers: catalogQuotesTable.pricing_applied_offers })
+        .from(catalogQuotesTable)
+        .where(eq(catalogQuotesTable.consumed_booking_id, bookingId));
+    if (rows.length === 0) {
+        return { quotesScanned: 0, offersFound: 0, rowsUpserted: 0 };
+    }
+    // Aggregate per offerId across all quotes.
+    const aggregated = new Map();
+    for (const row of rows) {
+        const offers = row.pricing_applied_offers ?? [];
+        for (const offer of offers) {
+            const existing = aggregated.get(offer.offerId);
+            if (existing) {
+                existing.discountAppliedCents += offer.discountAppliedCents;
+                // First non-null wins — the code-gated offer (if any) is
+                // typically a single occurrence.
+                if (existing.codeUsed == null && offer.appliedCode != null) {
+                    existing.codeUsed = offer.appliedCode;
+                }
+            }
+            else {
+                aggregated.set(offer.offerId, {
+                    discountAppliedCents: offer.discountAppliedCents,
+                    currency: offer.currency,
+                    codeUsed: offer.appliedCode,
+                });
+            }
+        }
+    }
+    if (aggregated.size === 0) {
+        return { quotesScanned: rows.length, offersFound: 0, rowsUpserted: 0 };
+    }
+    const insertValues = Array.from(aggregated.entries()).map(([offerId, summary]) => ({
+        offerId,
+        bookingId,
+        codeUsed: summary.codeUsed,
+        discountAppliedCents: summary.discountAppliedCents,
+        currency: summary.currency,
+    }));
+    // ON CONFLICT DO UPDATE so subscriber retries refresh the aggregate
+    // cleanly — important because the event bus may replay this event.
+    // Cast: AnyDrizzleDb's union doesn't unify .insert().onConflictDoUpdate()
+    // across drivers at the type level (same workaround as the boundary
+    // scheduler).
+    await db
+        .insert(promotionalOfferRedemptions)
+        .values(insertValues)
+        .onConflictDoUpdate({
+        target: [promotionalOfferRedemptions.offerId, promotionalOfferRedemptions.bookingId],
+        // EXCLUDED refers to the would-be-inserted row — we want the freshly-
+        // computed aggregate (from `insertValues`) to overwrite any stale prior
+        // row, not a no-op self-assignment. Without `excluded.*` here, a partial
+        // earlier write would never get corrected on retry / replay despite
+        // this code path claiming idempotent refresh semantics.
+        set: {
+            discountAppliedCents: sql `excluded.discount_applied_cents`,
+            codeUsed: sql `excluded.code_used`,
+        },
+    });
+    return {
+        quotesScanned: rows.length,
+        offersFound: aggregated.size,
+        rowsUpserted: aggregated.size,
+    };
+}
+/**
+ * Wiring guidance for the operator template — the canonical subscriber
+ * pattern (mirrors how `catalog-bridge.ts` wires `captureSnapshotGraph`):
+ *
+ *   eventBus.subscribe<BookingConfirmedEvent>("booking.confirmed", async ({ data }) => {
+ *     await withDbFromEnv(env, async (db) => {
+ *       try {
+ *         await recordPromotionRedemptionsForBooking(db, data.bookingId)
+ *       } catch (err) {
+ *         // Failing here leaves the booking committed without a
+ *         // redemption row. Ops can backfill from
+ *         // `pricing_applied_offers` on the snapshot. Log so the gap
+ *         // is visible.
+ *         console.warn("[promotions] redemption subscriber failed", { …err })
+ *       }
+ *     })
+ *   })
+ *
+ * The factory is intentionally kept in the template (not here) because:
+ *   - The subscriber needs the template's `withDbFromEnv` from
+ *     `templates/operator/src/api/lib/db.ts` (the Pool lifecycle helper
+ *     introduced in #510 / #512). That helper isn't exported from a
+ *     package.
+ *   - Keeping the package package-side core (`recordPromotionRedemptionsForBooking`)
+ *     and the wiring template-side mirrors the existing catalog-bridge
+ *     subscriber pattern.
+ */
+export const __test__ = { recordPromotionRedemptionsForBooking };

package/dist/service-boundary-scheduler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Promotions boundary scheduler — emits `promotion.changed` events when
+ * offers cross their `valid_from` / `valid_until` boundaries since the
+ * last tick.
+ *
+ * The catalog projection is `now()`-dependent (active offers fire at
+ * `valid_from`, expire at `valid_until`). Without a scheduled trigger,
+ * an indexed product document continues to show an expired discount
+ * until something else reindexes it. This scheduler is what guarantees
+ * the storefront eventually sees the boundary transition — within the
+ * cron interval (5 min by default in the operator template).
+ *
+ * Per docs/architecture/promotions-architecture.md §9.2.
+ *
+ * Operator template wires this to a Cloudflare Workers cron in
+ * `src/api/promotion-scheduled.ts` + `wrangler.jsonc`.
+ *
+ * Idempotent on retry: the scheduler's effect is "emit `promotion.changed`
+ * events for crossings since `last_tick`". Re-running with the same
+ * `last_tick` re-emits the same events; the catalog bridge's reindex
+ * subscriber is idempotent (reindexing the same product twice is a
+ * no-op modulo the eventual-consistency window).
+ */
+import type { EventBus } from "@voyantjs/core";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { type PromotionChangedAffected, type PromotionChangedSource } from "./events.js";
+export interface BoundarySchedulerOptions {
+    /**
+     * How far back to look on the very first tick (when no watermark row
+     * exists yet). Defaults to 24h — covers same-day deployments where the
+     * scheduler starts after some offers have already crossed their
+     * `valid_from`. Pin to a small value if you'd rather only catch
+     * forward-going crossings.
+     */
+    initialLookbackMs?: number;
+    /** Override `now()` for testing. */
+    now?: () => Date;
+}
+/**
+ * One detected boundary crossing. Returned in `result.crossings` so callers
+ * without an event bus (e.g., Cloudflare Workers cron handlers, where the
+ * in-process bus from the running app isn't reachable) can dispatch the
+ * reindex inline.
+ */
+export interface BoundaryCrossing {
+    offerId: string;
+    source: PromotionChangedSource;
+    affected: PromotionChangedAffected;
+}
+export interface BoundarySchedulerResult {
+    /** Wall clock at the start of this tick — the new watermark. */
+    tickedAt: Date;
+    /** Watermark used as the lower bound for the crossing scan. */
+    lastTick: Date;
+    /** Offers crossing `valid_from` in the window — emit with source="updated". */
+    validFromCrossings: number;
+    /** Offers crossing `valid_until` in the window — emit with source="expired". */
+    validUntilCrossings: number;
+    /** Total events emitted to the bus when one was provided (else 0). */
+    emitted: number;
+    /**
+     * Every crossing detected this tick. Always populated — independent of
+     * whether an event bus was supplied. Lets cron-style callers dispatch
+     * the reindex inline when no bus is reachable.
+     */
+    crossings: BoundaryCrossing[];
+}
+export interface BoundarySchedulerDeps {
+    db: AnyDrizzleDb;
+    eventBus?: EventBus;
+}
+/**
+ * Run a single boundary-scheduler tick. Safe to call repeatedly; the
+ * watermark advances monotonically.
+ */
+export declare function runPromotionBoundaryScheduler(deps: BoundarySchedulerDeps, options?: BoundarySchedulerOptions): Promise<BoundarySchedulerResult>;
+declare function readWatermark(db: AnyDrizzleDb, tickedAt: Date, initialLookbackMs: number): Promise<Date>;
+declare function writeWatermark(db: AnyDrizzleDb, tickedAt: Date): Promise<void>;
+export declare const __test__: {
+    SINGLETON_KEY: "singleton";
+    readWatermark: typeof readWatermark;
+    writeWatermark: typeof writeWatermark;
+};
+export {};
+//# sourceMappingURL=service-boundary-scheduler.d.ts.map

package/dist/service-boundary-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-boundary-scheduler.d.ts","sourceRoot":"","sources":["../src/service-boundary-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIhD,OAAO,EAEL,KAAK,wBAAwB,EAE7B,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAA;AAYpB,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,sBAAsB,CAAA;IAC9B,QAAQ,EAAE,wBAAwB,CAAA;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,gEAAgE;IAChE,QAAQ,EAAE,IAAI,CAAA;IACd,+DAA+D;IAC/D,QAAQ,EAAE,IAAI,CAAA;IACd,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,CAAA;IAC1B,gFAAgF;IAChF,mBAAmB,EAAE,MAAM,CAAA;IAC3B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,YAAY,CAAA;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,qBAAqB,EAC3B,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAiElC;AA+BD,iBAAe,aAAa,CAC1B,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,IAAI,EACd,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B7E;AAGD,eAAO,MAAM,QAAQ;;;;CAAmD,CAAA"}

package/dist/service-boundary-scheduler.js

@@ -0,0 +1,141 @@
+/**
+ * Promotions boundary scheduler — emits `promotion.changed` events when
+ * offers cross their `valid_from` / `valid_until` boundaries since the
+ * last tick.
+ *
+ * The catalog projection is `now()`-dependent (active offers fire at
+ * `valid_from`, expire at `valid_until`). Without a scheduled trigger,
+ * an indexed product document continues to show an expired discount
+ * until something else reindexes it. This scheduler is what guarantees
+ * the storefront eventually sees the boundary transition — within the
+ * cron interval (5 min by default in the operator template).
+ *
+ * Per docs/architecture/promotions-architecture.md §9.2.
+ *
+ * Operator template wires this to a Cloudflare Workers cron in
+ * `src/api/promotion-scheduled.ts` + `wrangler.jsonc`.
+ *
+ * Idempotent on retry: the scheduler's effect is "emit `promotion.changed`
+ * events for crossings since `last_tick`". Re-running with the same
+ * `last_tick` re-emits the same events; the catalog bridge's reindex
+ * subscriber is idempotent (reindexing the same product twice is a
+ * no-op modulo the eventual-consistency window).
+ */
+import { and, eq, gt, lte } from "drizzle-orm";
+import { PROMOTION_CHANGED_EVENT, } from "./events.js";
+import { promotionalOfferSchedulerState, promotionalOffers, } from "./schema.js";
+import { resolveScopeProductIds } from "./service.js";
+/** Sentinel value for the single-row scheduler-state table's `singleton_key`. */
+const SINGLETON_KEY = "singleton";
+/**
+ * Run a single boundary-scheduler tick. Safe to call repeatedly; the
+ * watermark advances monotonically.
+ */
+export async function runPromotionBoundaryScheduler(deps, options = {}) {
+    const initialLookbackMs = options.initialLookbackMs ?? 24 * 60 * 60 * 1000;
+    const nowFn = options.now ?? (() => new Date());
+    const tickedAt = nowFn();
+    const lastTick = await readWatermark(deps.db, tickedAt, initialLookbackMs);
+    // Fetch every active offer whose `valid_from` OR `valid_until` falls in
+    // the (lastTick, tickedAt] window. Two passes (one per boundary) so we
+    // can attribute the right `source` per emission.
+    const validFromRows = await deps.db
+        .select()
+        .from(promotionalOffers)
+        .where(and(eq(promotionalOffers.active, true), gt(promotionalOffers.validFrom, lastTick), lte(promotionalOffers.validFrom, tickedAt)));
+    const validUntilRows = await deps.db
+        .select()
+        .from(promotionalOffers)
+        .where(and(eq(promotionalOffers.active, true), gt(promotionalOffers.validUntil, lastTick), lte(promotionalOffers.validUntil, tickedAt)));
+    // Resolve `affected` once per offer (each call hits the link table) so we
+    // can both populate the returned `crossings[]` and feed the optional
+    // event bus from the same payload.
+    const validFromCrossings = await buildCrossings(deps.db, validFromRows, "updated");
+    const validUntilCrossings = await buildCrossings(deps.db, validUntilRows, "expired");
+    const crossings = [...validFromCrossings, ...validUntilCrossings];
+    let emitted = 0;
+    if (deps.eventBus) {
+        for (const crossing of crossings) {
+            const payload = {
+                offerId: crossing.offerId,
+                source: crossing.source,
+                affected: crossing.affected,
+            };
+            await deps.eventBus.emit(PROMOTION_CHANGED_EVENT, payload, {
+                category: "domain",
+                source: "service",
+            });
+            emitted++;
+        }
+    }
+    await writeWatermark(deps.db, tickedAt);
+    return {
+        tickedAt,
+        lastTick,
+        validFromCrossings: validFromRows.length,
+        validUntilCrossings: validUntilRows.length,
+        emitted,
+        crossings,
+    };
+}
+async function buildCrossings(db, offers, source) {
+    const out = [];
+    for (const offer of offers) {
+        out.push({
+            offerId: offer.id,
+            source,
+            affected: await resolveAffected(db, offer.scope),
+        });
+    }
+    return out;
+}
+async function resolveAffected(db, scope) {
+    // `resolveScopeProductIds` is typed against `PostgresJsDatabase` to match
+    // the rest of `service.ts`. The structural compatibility across drizzle
+    // driver flavors makes the cast safe at runtime — only `.select(...)` is
+    // used here.
+    const productIds = await resolveScopeProductIds(db, scope);
+    if (productIds === null)
+        return { kind: "all" };
+    return { kind: "products", productIds };
+}
+async function readWatermark(db, tickedAt, initialLookbackMs) {
+    const rows = await db
+        .select({ lastTick: promotionalOfferSchedulerState.lastTick })
+        .from(promotionalOfferSchedulerState)
+        .where(eq(promotionalOfferSchedulerState.singletonKey, SINGLETON_KEY))
+        .limit(1);
+    const existing = rows[0];
+    if (existing)
+        return existing.lastTick;
+    return new Date(tickedAt.getTime() - initialLookbackMs);
+}
+async function writeWatermark(db, tickedAt) {
+    // Upsert keyed on the singleton sentinel — first call inserts, every
+    // subsequent call advances the existing row's `last_tick`.
+    //
+    // Cast: `AnyDrizzleDb` is a union of three driver flavors whose
+    // `.insert(...).onConflictDoUpdate(...)` return types differ at the
+    // type level (NeonHttp returns a different QueryResult shape than
+    // postgres-js / NeonWs). Runtime is identical — drizzle's PgDatabase
+    // surface is structurally the same across drivers — so the cast is
+    // safe. Same pattern as elsewhere in the workspace where service code
+    // accepts the union but uses a write that only typechecks against one
+    // concrete driver.
+    await db
+        .insert(promotionalOfferSchedulerState)
+        .values({
+        singletonKey: SINGLETON_KEY,
+        lastTick: tickedAt,
+        updatedAt: tickedAt,
+    })
+        .onConflictDoUpdate({
+        target: promotionalOfferSchedulerState.singletonKey,
+        set: {
+            lastTick: tickedAt,
+            updatedAt: tickedAt,
+        },
+    });
+}
+// Exposed for tests so they can probe the watermark without recreating the SQL.
+export const __test__ = { SINGLETON_KEY, readWatermark, writeWatermark };

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

@@ -0,0 +1,22 @@
+/**
+ * Catalog evaluator adapter — bridges `@voyantjs/catalog`'s
+ * `PromotionEvaluationInput` / `PromotionEvaluationOutput` contract to
+ * this package's internal evaluator.
+ *
+ * Wire via:
+ *
+ *   const deps: QuoteEntityDeps = {
+ *     // ...
+ *     evaluatePromotions: createCatalogPromotionEvaluator(db),
+ *   }
+ *
+ * Per docs/architecture/promotions-architecture.md §3.6 + §7.1.
+ */
+import type { PromotionEvaluationInput, PromotionEvaluationOutput } from "@voyantjs/catalog/booking-engine";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+/**
+ * Build the `evaluatePromotions` hook the catalog booking engine wires
+ * onto `QuoteEntityDeps`. Closes over the request-scoped db.
+ */
+export declare function createCatalogPromotionEvaluator(db: AnyDrizzleDb): (input: PromotionEvaluationInput) => Promise<PromotionEvaluationOutput>;
+//# sourceMappingURL=service-catalog-evaluator.d.ts.map

package/dist/service-catalog-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-catalog-evaluator.d.ts","sourceRoot":"","sources":["../src/service-catalog-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIhD;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,YAAY,GACf,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAazE"}

package/dist/service-catalog-evaluator.js

@@ -0,0 +1,33 @@
+/**
+ * Catalog evaluator adapter — bridges `@voyantjs/catalog`'s
+ * `PromotionEvaluationInput` / `PromotionEvaluationOutput` contract to
+ * this package's internal evaluator.
+ *
+ * Wire via:
+ *
+ *   const deps: QuoteEntityDeps = {
+ *     // ...
+ *     evaluatePromotions: createCatalogPromotionEvaluator(db),
+ *   }
+ *
+ * Per docs/architecture/promotions-architecture.md §3.6 + §7.1.
+ */
+import { createDrizzleOfferDataSource, evaluateOffersForProduct } from "./service-evaluator.js";
+/**
+ * Build the `evaluatePromotions` hook the catalog booking engine wires
+ * onto `QuoteEntityDeps`. Closes over the request-scoped db.
+ */
+export function createCatalogPromotionEvaluator(db) {
+    const source = createDrizzleOfferDataSource(db);
+    return async (input) => {
+        const result = await evaluateOffersForProduct(source, input);
+        // Shapes are 1:1 between the two `AppliedOffer` / `CodeStatus`
+        // declarations — catalog's contract intentionally mirrors the
+        // evaluator's so the bridge is just a structural pass-through.
+        return {
+            applied: result.applied,
+            total: result.total,
+            codeStatus: result.codeStatus,
+        };
+    };
+}