@voyantjs/promotions 0.28.3

package/dist/service-catalog-plane-promotions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Projection extension that decorates the product search document with
+ * promotional-offer annotations declared by `productPromotionsCatalogPolicy`
+ * (in `@voyantjs/products/catalog-policy-promotions`).
+ *
+ * Lives in `@voyantjs/promotions` because:
+ *   - The data lives here.
+ *   - `promotions` already depends on `@voyantjs/products` for the
+ *     `product_category_products` / `product_destinations` link tables;
+ *     importing the `ProductProjectionExtension` contract type from
+ *     products is the same direction.
+ *
+ * Wire via `createProductDocumentBuilder({ extensions: [...promotionsExt] })`
+ * after composing `productPromotionsCatalogPolicy` into the registry.
+ *
+ * Annotation-only contract (per §3.7 of the architecture doc): this
+ * extension does NOT touch `priceFromAmountCents` (that's emitted by the
+ * pricing extension and the two extensions can't read each other's
+ * output). It only emits `bestOffer*` + `originalPriceFromAmountCents` +
+ * `conditionalOffer*`. Storefront consumers compute the effective price
+ * client-side.
+ *
+ * `originalPriceFromAmountCents` resolution: by default we read
+ * `products.sell_amount_cents` directly (works for simple products with
+ * row-level pricing). Operators with option-driven pricing should pass
+ * `loadOriginalPrice` to wire the same MIN-across-options resolver the
+ * pricing extension uses; otherwise the strikethrough may not match the
+ * customer-visible list price for option-driven products.
+ *
+ * Per docs/architecture/promotions-architecture.md §6.
+ */
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import type { IndexerSlice, ProductProjectionExtension } from "@voyantjs/products/service-catalog-plane";
+import { type AppliedOffer, type ConditionalOffer, type EvaluationResult } from "./service-evaluator.js";
+export interface PromotionsProjectionOptions {
+    /**
+     * Resolve the un-discounted "from price" + currency for a product.
+     * The result drives `originalPriceFromAmountCents` + the evaluator's
+     * `basePriceCents` / `baseCurrency` inputs.
+     *
+     * Defaults to a direct read of `products.sell_amount_cents` +
+     * `products.sell_currency` — works for simple row-priced products.
+     * Operators with option-driven pricing should wire this to the same
+     * MIN-across-options resolver the pricing extension uses.
+     *
+     * Returns `null` for amountCents when the product has no configured
+     * base price (the extension then short-circuits to an empty projection
+     * since there's no base for the evaluator to discount).
+     */
+    loadOriginalPrice?: (db: AnyDrizzleDb, productId: string) => Promise<{
+        amountCents: number | null;
+        currency: string | null;
+    }>;
+    /** Override `now()` for testing. Defaults to wall-clock time at projection. */
+    now?: () => Date;
+}
+/**
+ * Map an `IndexerSlice.audience` (which can include `staff-admin`) onto the
+ * evaluator's narrower `Visibility` enum. Both `staff` and `staff-admin`
+ * map to `staff` for offer-evaluation purposes — both are operator-internal
+ * surfaces that should see the same promotional inventory.
+ */
+declare function sliceAudience(slice: IndexerSlice): "staff" | "customer" | "partner" | "supplier";
+export declare function createProductPromotionsProjectionExtension(options?: PromotionsProjectionOptions): ProductProjectionExtension;
+declare function toProjectionMap(best: AppliedOffer | null, conditional: ConditionalOffer | null, originalPrice: number | null): ReadonlyMap<string, unknown>;
+export declare const __test__: {
+    toProjectionMap: typeof toProjectionMap;
+    EMPTY_PROJECTION: ReadonlyMap<string, unknown>;
+    sliceAudience: typeof sliceAudience;
+};
+export type { EvaluationResult };
+//# sourceMappingURL=service-catalog-plane-promotions.d.ts.map

package/dist/service-catalog-plane-promotions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-catalog-plane-promotions.d.ts","sourceRoot":"","sources":["../src/service-catalog-plane-promotions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EACV,YAAY,EACZ,0BAA0B,EAC3B,MAAM,0CAA0C,CAAA;AAEjD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EAEtB,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,CAClB,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAErE,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAGzF;AAID,wBAAgB,0CAA0C,CACxD,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CAiC5B;AAED,iBAAS,eAAe,CACtB,IAAI,EAAE,YAAY,GAAG,IAAI,EACzB,WAAW,EAAE,gBAAgB,GAAG,IAAI,EACpC,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB9B;AA8BD,eAAO,MAAM,QAAQ;;;;CAAuD,CAAA;AAE5E,YAAY,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/service-catalog-plane-promotions.js

@@ -0,0 +1,119 @@
+/**
+ * Projection extension that decorates the product search document with
+ * promotional-offer annotations declared by `productPromotionsCatalogPolicy`
+ * (in `@voyantjs/products/catalog-policy-promotions`).
+ *
+ * Lives in `@voyantjs/promotions` because:
+ *   - The data lives here.
+ *   - `promotions` already depends on `@voyantjs/products` for the
+ *     `product_category_products` / `product_destinations` link tables;
+ *     importing the `ProductProjectionExtension` contract type from
+ *     products is the same direction.
+ *
+ * Wire via `createProductDocumentBuilder({ extensions: [...promotionsExt] })`
+ * after composing `productPromotionsCatalogPolicy` into the registry.
+ *
+ * Annotation-only contract (per §3.7 of the architecture doc): this
+ * extension does NOT touch `priceFromAmountCents` (that's emitted by the
+ * pricing extension and the two extensions can't read each other's
+ * output). It only emits `bestOffer*` + `originalPriceFromAmountCents` +
+ * `conditionalOffer*`. Storefront consumers compute the effective price
+ * client-side.
+ *
+ * `originalPriceFromAmountCents` resolution: by default we read
+ * `products.sell_amount_cents` directly (works for simple products with
+ * row-level pricing). Operators with option-driven pricing should pass
+ * `loadOriginalPrice` to wire the same MIN-across-options resolver the
+ * pricing extension uses; otherwise the strikethrough may not match the
+ * customer-visible list price for option-driven products.
+ *
+ * Per docs/architecture/promotions-architecture.md §6.
+ */
+import { createDrizzleOfferDataSource, evaluateOffersForProduct, } from "./service-evaluator.js";
+/**
+ * Map an `IndexerSlice.audience` (which can include `staff-admin`) onto the
+ * evaluator's narrower `Visibility` enum. Both `staff` and `staff-admin`
+ * map to `staff` for offer-evaluation purposes — both are operator-internal
+ * surfaces that should see the same promotional inventory.
+ */
+function sliceAudience(slice) {
+    if (slice.audience === "staff-admin")
+        return "staff";
+    return slice.audience;
+}
+const EMPTY_PROJECTION = toProjectionMap(null, null, null);
+export function createProductPromotionsProjectionExtension(options = {}) {
+    const loadOriginalPrice = options.loadOriginalPrice ?? defaultLoadOriginalPrice;
+    const nowFn = options.now ?? (() => new Date());
+    return {
+        name: "promotions:offers",
+        async project(db, productId, slice) {
+            const { amountCents, currency } = await loadOriginalPrice(db, productId);
+            if (amountCents == null || currency == null) {
+                // No base price configured → no offer math to do. Returning the
+                // empty projection ensures consumers see explicit nulls instead
+                // of stale prior values from the doc.
+                return EMPTY_PROJECTION;
+            }
+            const source = createDrizzleOfferDataSource(db);
+            const evaluation = await evaluateOffersForProduct(source, {
+                productId,
+                slice: { audience: sliceAudience(slice), market: slice.market },
+                date: nowFn(),
+                basePriceCents: amountCents,
+                baseCurrency: currency,
+                // pax + code intentionally omitted: catalog plane never knows
+                // these. minPax-conditioned offers land in `result.conditional`.
+            });
+            const conditional = evaluation.conditional[0] ?? null;
+            // Surface `originalPriceFromAmountCents` ONLY when an offer applies —
+            // §3.7 keeps the doc lean by leaving it null otherwise.
+            const original = evaluation.best != null ? amountCents : null;
+            return toProjectionMap(evaluation.best, conditional, original);
+        },
+    };
+}
+function toProjectionMap(best, conditional, originalPrice) {
+    return new Map([
+        ["hasOffer", best != null],
+        ["bestOfferId", best?.offerId ?? null],
+        ["bestOfferName", best?.offerName ?? null],
+        ["bestOfferDiscountKind", best?.discountKind ?? null],
+        ["bestOfferDiscountPercent", best?.discountPercent ?? null],
+        ["bestOfferDiscountAmountCents", best?.discountAmountCents ?? null],
+        ["originalPriceFromAmountCents", originalPrice],
+        ["hasConditionalOffer", conditional != null],
+        ["conditionalOfferId", conditional?.offerId ?? null],
+        ["conditionalOfferName", conditional?.offerName ?? null],
+        ["conditionalOfferDiscountKind", conditional?.discountKind ?? null],
+        ["conditionalOfferDiscountPercent", conditional?.discountPercent ?? null],
+        ["conditionalOfferDiscountAmountCents", conditional?.discountAmountCents ?? null],
+        [
+            "conditionalOfferMinPax",
+            conditional != null && conditional.unmet.kind === "min_pax"
+                ? conditional.unmet.required
+                : null,
+        ],
+    ]);
+}
+/**
+ * Default loader — single-column read against `products` so we don't pull
+ * the products schema into this file (would deepen the coupling). The
+ * column shape is stable enough that string-keyed access is safe; a
+ * schema rename would break far more than this projection.
+ */
+async function defaultLoadOriginalPrice(db, productId) {
+    // biome-ignore lint/suspicious/noExplicitAny: drizzle's typed sql is overkill for a single-row read
+    const dbAny = db;
+    const { sql } = await import("drizzle-orm");
+    const result = await dbAny.execute(sql `SELECT sell_amount_cents, sell_currency FROM products WHERE id = ${productId} LIMIT 1`);
+    // postgres-js returns array-like; node-postgres returns `{ rows }`. Handle both.
+    const rows = Array.isArray(result) ? result : (result?.rows ?? []);
+    const first = rows[0];
+    return {
+        amountCents: first?.sell_amount_cents ?? null,
+        currency: first?.sell_currency ?? null,
+    };
+}
+// Internal exports for unit tests — kept off the public surface.
+export const __test__ = { toProjectionMap, EMPTY_PROJECTION, sliceAudience };

package/dist/service-evaluator.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Promotions rule evaluator — the heart of §5.
+ *
+ * One pure function (`evaluateOffersForProduct`) used by both callers
+ * (catalog plane projection in PR3 + checkout quote in PR4). The evaluator
+ * doesn't bind to a database — it takes an `OfferDataSource` interface so
+ * the catalog projection can reuse one cached candidate set across many
+ * products in a slice, and unit tests can supply in-memory fixtures
+ * without a DB mock.
+ *
+ * The DB-backed `OfferDataSource` factory (`createDrizzleOfferDataSource`)
+ * is provided too — that's what PR3/PR4 wire up.
+ *
+ * Per docs/architecture/promotions-architecture.md §5.
+ *
+ * Not yet exported from the package barrel — PR3 wires it via the catalog
+ * plane adapter, PR4 via the checkout adapter.
+ */
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { type PromotionalOffer } from "./schema.js";
+export interface OfferEvaluationContext {
+    productId: string;
+    slice: {
+        audience: "staff" | "customer" | "partner" | "supplier";
+        market: string;
+    };
+    /** Total travelers. Absent at catalog-index time; supplied at checkout. */
+    pax?: number;
+    /** Defaults to `now()` when undefined. */
+    date?: Date;
+    /** Customer-typed promotion code; case-insensitive match. */
+    code?: string;
+    basePriceCents: number;
+    baseCurrency: string;
+}
+export interface AppliedOffer {
+    offerId: string;
+    offerName: string;
+    /** The actual cents off attributed to this offer. */
+    discountAppliedCents: number;
+    /** `basePriceCents - discountAppliedCents` (per-row, the price the offer alone would yield). */
+    discountedPriceCents: number;
+    /** Matches the surrounding `ctx.baseCurrency` — carried per-row so the redemption recorder can insert without context. */
+    currency: string;
+    discountKind: "percentage" | "fixed_amount";
+    discountPercent: number | null;
+    discountAmountCents: number | null;
+    /** The literal code the customer entered (case preserved); null for auto-applied. */
+    appliedCode: string | null;
+    stackable: boolean;
+}
+/**
+ * An offer that *would* apply if a missing input were supplied — typically
+ * a `minPax` condition the catalog-plane caller can't satisfy because pax
+ * isn't known at index time. Surfaced for storefront UI hints like
+ * "From 4 pax: extra 5% off".
+ */
+export interface ConditionalOffer {
+    offerId: string;
+    offerName: string;
+    discountKind: "percentage" | "fixed_amount";
+    discountPercent: number | null;
+    discountAmountCents: number | null;
+    unmet: {
+        kind: "min_pax";
+        required: number;
+    };
+}
+/** Outcome of code validation when `ctx.code` is supplied. `null` when ctx.code was not set. */
+export type CodeStatus = null | {
+    kind: "code_valid";
+} | {
+    kind: "code_not_found";
+} | {
+    kind: "code_expired";
+} | {
+    kind: "code_not_yet_valid";
+} | {
+    kind: "code_not_applicable";
+    reason: "scope" | "min_pax" | "currency";
+};
+export interface EvaluationResult {
+    /** All applied offers (1+ when stacking; 0 when no offer applies). May include a code-gated offer alongside auto offers. */
+    applied: AppliedOffer[];
+    /** The single best offer (largest discount among the applied set), or null if none. Always references one row in `applied`. */
+    best: AppliedOffer | null;
+    /** Conditionally applicable — a missing input would make them apply. Only populated by the catalog-plane caller (no `ctx.pax`). Empty for checkout. */
+    conditional: ConditionalOffer[];
+    total: {
+        discountAppliedCents: number;
+        discountedPriceCents: number;
+    };
+    /** Set when `ctx.code` was supplied. Drives the checkout caller's `invalidReason` mapping (§7.2). */
+    codeStatus: CodeStatus;
+}
+/**
+ * Read-only data access the evaluator needs. Decoupled from drizzle so
+ * unit tests can supply in-memory fixtures and so the catalog projection
+ * can cache `fetchActiveAutoCandidates` once per slice.
+ */
+export interface OfferDataSource {
+    /** All active offers whose validity window includes `date` AND `code IS NULL`. */
+    fetchActiveAutoCandidates(date: Date): Promise<PromotionalOffer[]>;
+    /** Active offer matching `lower(code) = lower(input)`, or null. */
+    findActiveOfferByCode(code: string): Promise<PromotionalOffer | null>;
+    /** Subset of `offerIds` whose `promotional_offer_products` table has a row for `productId`. */
+    productMatchesAnyScope(productId: string, offerIds: string[]): Promise<Set<string>>;
+}
+export declare function createDrizzleOfferDataSource(db: AnyDrizzleDb): OfferDataSource;
+export declare function evaluateOffersForProduct(source: OfferDataSource, ctx: OfferEvaluationContext): Promise<EvaluationResult>;
+//# sourceMappingURL=service-evaluator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-evaluator.d.ts","sourceRoot":"","sources":["../src/service-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/service-evaluator.js

@@ -0,0 +1,264 @@
+/**
+ * Promotions rule evaluator — the heart of §5.
+ *
+ * One pure function (`evaluateOffersForProduct`) used by both callers
+ * (catalog plane projection in PR3 + checkout quote in PR4). The evaluator
+ * doesn't bind to a database — it takes an `OfferDataSource` interface so
+ * the catalog projection can reuse one cached candidate set across many
+ * products in a slice, and unit tests can supply in-memory fixtures
+ * without a DB mock.
+ *
+ * The DB-backed `OfferDataSource` factory (`createDrizzleOfferDataSource`)
+ * is provided too — that's what PR3/PR4 wire up.
+ *
+ * Per docs/architecture/promotions-architecture.md §5.
+ *
+ * Not yet exported from the package barrel — PR3 wires it via the catalog
+ * plane adapter, PR4 via the checkout adapter.
+ */
+import { and, eq, inArray, isNull, lte, or, sql } from "drizzle-orm";
+import { promotionalOfferProducts, promotionalOffers } from "./schema.js";
+// ---------- DB-backed source factory (used by PR3 + PR4) ----------
+export function createDrizzleOfferDataSource(db) {
+    return {
+        async fetchActiveAutoCandidates(date) {
+            return db
+                .select()
+                .from(promotionalOffers)
+                .where(and(eq(promotionalOffers.active, true), isNull(promotionalOffers.code), or(isNull(promotionalOffers.validFrom), lte(promotionalOffers.validFrom, date)), or(isNull(promotionalOffers.validUntil), sql `${promotionalOffers.validUntil} >= ${date}`)));
+        },
+        async findActiveOfferByCode(code) {
+            const rows = await db
+                .select()
+                .from(promotionalOffers)
+                .where(and(eq(promotionalOffers.active, true), sql `lower(${promotionalOffers.code}) = ${code.toLowerCase()}`))
+                .limit(1);
+            return rows[0] ?? null;
+        },
+        async productMatchesAnyScope(productId, offerIds) {
+            if (offerIds.length === 0)
+                return new Set();
+            const rows = await db
+                .select({ offerId: promotionalOfferProducts.offerId })
+                .from(promotionalOfferProducts)
+                .where(and(eq(promotionalOfferProducts.productId, productId), inArray(promotionalOfferProducts.offerId, offerIds)));
+            return new Set(rows.map((r) => r.offerId));
+        },
+    };
+}
+// ---------- Internal helpers ----------
+function discountKind(offer) {
+    return offer.discountType;
+}
+function discountFields(offer) {
+    return {
+        discountKind: discountKind(offer),
+        discountPercent: offer.discountPercent != null ? Number(offer.discountPercent) : null,
+        discountAmountCents: offer.discountAmountCents,
+    };
+}
+/**
+ * Cents off a given base for a single offer. Caps fixed_amount at the
+ * available base so a discount can never exceed the price.
+ */
+function computeDiscount(offer, basePriceCents) {
+    if (basePriceCents <= 0)
+        return 0;
+    if (offer.discountType === "percentage") {
+        if (offer.discountPercent == null)
+            return 0;
+        const pct = Number(offer.discountPercent);
+        return Math.round((basePriceCents * pct) / 100);
+    }
+    if (offer.discountAmountCents == null)
+        return 0;
+    return Math.min(offer.discountAmountCents, basePriceCents);
+}
+function matchesScope(scope, ctx, offerMatchesProduct) {
+    switch (scope.kind) {
+        case "global":
+            return true;
+        case "products":
+        case "categories":
+        case "destinations":
+            return offerMatchesProduct;
+        case "markets":
+            return scope.marketIds.includes(ctx.slice.market);
+        case "audiences":
+            return scope.audiences.includes(ctx.slice.audience);
+    }
+}
+function evaluateConditions(conditions, ctx) {
+    if (conditions.minPax != null) {
+        if (ctx.pax === undefined) {
+            return { kind: "conditional", unmet: { kind: "min_pax", required: conditions.minPax } };
+        }
+        if (ctx.pax < conditions.minPax) {
+            return { kind: "excluded", reason: "min_pax" };
+        }
+    }
+    return { kind: "ok" };
+}
+function currencyMatches(offer, ctx) {
+    if (offer.discountType !== "fixed_amount")
+        return true;
+    return offer.currency === ctx.baseCurrency;
+}
+/**
+ * Stacking pick (§5.2.6 + §3.3):
+ *   - Pick the single best non-stackable offer (largest cents off the base).
+ *   - Separately compose all `stackable` offers sequentially (deterministic
+ *     order: by offerId ascending) — each stackable offer applies to the
+ *     RUNNING base after prior stackables, which produces the multiplicative
+ *     formula for percentage stackables and well-defined behavior for
+ *     fixed_amount or mixed-type stackables.
+ *   - Take whichever path yields the larger total discount. Ties → prefer
+ *     the single non-stackable (simpler customer-facing receipt).
+ */
+function pickStacking(applied, basePriceCents) {
+    const stackable = [];
+    const nonStackable = [];
+    for (const offer of applied) {
+        if (offer.stackable)
+            stackable.push(offer);
+        else
+            nonStackable.push(offer);
+    }
+    // Best single non-stackable
+    let bestNonStackable = null;
+    let bestNonStackableDiscount = 0;
+    for (const offer of nonStackable) {
+        const d = computeDiscount(offer, basePriceCents);
+        if (d > bestNonStackableDiscount) {
+            bestNonStackable = offer;
+            bestNonStackableDiscount = d;
+        }
+    }
+    // Composed stackables (sequential, sorted by offerId for determinism)
+    const sortedStackable = [...stackable].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    let stackableBase = basePriceCents;
+    const stackableRows = [];
+    for (const offer of sortedStackable) {
+        const d = computeDiscount(offer, stackableBase);
+        if (d <= 0)
+            continue;
+        stackableRows.push({ offer, appliedCents: d });
+        stackableBase -= d;
+    }
+    const stackableTotal = basePriceCents - stackableBase;
+    if (bestNonStackable && bestNonStackableDiscount >= stackableTotal) {
+        return {
+            rows: [{ offer: bestNonStackable, appliedCents: bestNonStackableDiscount }],
+            runningBase: basePriceCents - bestNonStackableDiscount,
+        };
+    }
+    return { rows: stackableRows, runningBase: stackableBase };
+}
+function toAppliedOffer(row, ctx, appliedCode) {
+    const fields = discountFields(row.offer);
+    return {
+        offerId: row.offer.id,
+        offerName: row.offer.name,
+        discountAppliedCents: row.appliedCents,
+        discountedPriceCents: ctx.basePriceCents - row.appliedCents,
+        currency: ctx.baseCurrency,
+        discountKind: fields.discountKind,
+        discountPercent: fields.discountPercent,
+        discountAmountCents: fields.discountAmountCents,
+        appliedCode: row.offer.code != null ? appliedCode : null,
+        stackable: row.offer.stackable,
+    };
+}
+// ---------- Public entry point ----------
+export async function evaluateOffersForProduct(source, ctx) {
+    const date = ctx.date ?? new Date();
+    // Step 1: code lookup (when supplied) — classify validity AHEAD of the
+    // scope/conditions/currency filters so we can produce a precise
+    // `code_expired` / `code_not_yet_valid` reason instead of conflating
+    // them with `code_not_found`.
+    let codeOffer = null;
+    let preFilterCodeStatus = null;
+    if (ctx.code !== undefined) {
+        const found = await source.findActiveOfferByCode(ctx.code);
+        if (found == null) {
+            preFilterCodeStatus = { kind: "code_not_found" };
+        }
+        else if (found.validUntil != null && found.validUntil < date) {
+            preFilterCodeStatus = { kind: "code_expired" };
+        }
+        else if (found.validFrom != null && found.validFrom > date) {
+            preFilterCodeStatus = { kind: "code_not_yet_valid" };
+        }
+        else {
+            codeOffer = found;
+            // Tentatively valid; finalize after scope/conditions/currency filters.
+        }
+    }
+    // Step 2: auto-offer candidate fetch
+    const autoCandidates = await source.fetchActiveAutoCandidates(date);
+    const allCandidates = codeOffer ? [...autoCandidates, codeOffer] : autoCandidates;
+    // Pre-fetch product link membership in one query (§5.2.3 — uniform hot path).
+    const offerIds = allCandidates.map((o) => o.id);
+    const productMatchSet = await source.productMatchesAnyScope(ctx.productId, offerIds);
+    // Steps 3 + 4 + 5: scope / conditions / currency filter, partition.
+    const applied = [];
+    const conditional = [];
+    let codeOfferRejection = null;
+    for (const offer of allCandidates) {
+        if (!matchesScope(offer.scope, ctx, productMatchSet.has(offer.id))) {
+            if (offer === codeOffer)
+                codeOfferRejection = { kind: "scope" };
+            continue;
+        }
+        const cond = evaluateConditions(offer.conditions, ctx);
+        if (cond.kind === "conditional") {
+            conditional.push({
+                offerId: offer.id,
+                offerName: offer.name,
+                ...discountFields(offer),
+                unmet: cond.unmet,
+            });
+            continue;
+        }
+        if (cond.kind === "excluded") {
+            if (offer === codeOffer)
+                codeOfferRejection = { kind: "min_pax" };
+            continue;
+        }
+        if (!currencyMatches(offer, ctx)) {
+            if (offer === codeOffer)
+                codeOfferRejection = { kind: "currency" };
+            continue;
+        }
+        applied.push(offer);
+    }
+    // Finalize codeStatus after the filter pass.
+    let codeStatus = preFilterCodeStatus;
+    if (ctx.code !== undefined && codeStatus === null) {
+        if (codeOfferRejection != null) {
+            codeStatus = { kind: "code_not_applicable", reason: codeOfferRejection.kind };
+        }
+        else {
+            codeStatus = { kind: "code_valid" };
+        }
+    }
+    // Step 6 + 7: stacking pick + assemble result.
+    const { rows, runningBase } = pickStacking(applied, ctx.basePriceCents);
+    const appliedRows = rows.map((r) => toAppliedOffer(r, ctx, r.offer === codeOffer ? (ctx.code ?? null) : null));
+    let best = null;
+    for (const row of appliedRows) {
+        if (best == null || row.discountAppliedCents > best.discountAppliedCents) {
+            best = row;
+        }
+    }
+    return {
+        applied: appliedRows,
+        best,
+        conditional,
+        total: {
+            discountAppliedCents: ctx.basePriceCents - runningBase,
+            discountedPriceCents: runningBase,
+        },
+        codeStatus,
+    };
+}

package/dist/service-storefront.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Storefront resolvers — populate the previously-empty
+ * `/v1/public/products/:productId/offers` and `/v1/public/offers/:slug`
+ * endpoints in `@voyantjs/storefront` with real data.
+ *
+ * Wire via:
+ *
+ *   const storefrontModule = createStorefrontHonoModule({
+ *     offers: createPromotionsStorefrontResolvers(),
+ *   })
+ *
+ * Per docs/architecture/promotions-architecture.md §8.
+ *
+ * V1 limitations:
+ *   - Storefront calls don't carry an audience / market in the request
+ *     context, so the resolver only filters by `products` + `global`
+ *     scopes (the catalog plane handles audience-scoped projection).
+ *     `markets` and `audiences` scoped offers don't appear in this
+ *     listing endpoint.
+ *   - Locale-aware offer names: the schema doesn't store translations
+ *     yet (single-locale offer names per §12.1); `locale` is accepted
+ *     but ignored. A `promotional_offer_translations` table mirrors
+ *     `destinations_translations` if/when needed.
+ *   - `applicableDepartureIds`: always empty per §12.7 — departure-
+ *     scoped offers aren't modelled in v1.
+ *   - Only auto-applied offers (no code) appear in `listApplicableOffers`;
+ *     code-gated offers are still queryable via `getOfferBySlug`.
+ */
+import type { StorefrontOfferResolvers, StorefrontPromotionalOffer } from "@voyantjs/storefront";
+import { type PromotionalOffer } from "./schema.js";
+import type { PromotionalOfferScope } from "./validation.js";
+export declare function createPromotionsStorefrontResolvers(): StorefrontOfferResolvers;
+declare function matchesProduct(scope: PromotionalOfferScope, inLinkTable: boolean): boolean;
+declare function toStorefrontDto(offer: PromotionalOffer, applicableProductIds: string[]): StorefrontPromotionalOffer;
+export declare const __test__: {
+    matchesProduct: typeof matchesProduct;
+    toStorefrontDto: typeof toStorefrontDto;
+};
+export {};
+//# sourceMappingURL=service-storefront.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-storefront.d.ts","sourceRoot":"","sources":["../src/service-storefront.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EAAE,KAAK,gBAAgB,EAA+C,MAAM,aAAa,CAAA;AAChG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE5D,wBAAgB,mCAAmC,IAAI,wBAAwB,CAuE9E;AAMD,iBAAS,cAAc,CAAC,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAenF;AAuBD,iBAAS,eAAe,CACtB,KAAK,EAAE,gBAAgB,EACvB,oBAAoB,EAAE,MAAM,EAAE,GAC7B,0BAA0B,CA+B5B;AAED,eAAO,MAAM,QAAQ;;;CAAsC,CAAA"}