@openlup/platform 0.17.0 → 0.18.0

package/dist/pricing/catalogFactsProvenance.js

@@ -0,0 +1,64 @@
+import { CATALOG_FACTS_POLICY_PROVENANCE_VERSION, CATALOG_FACTS_PROVENANCE_VERSION } from "./contracts/provenance.js";
+import { catalogFactsProvenanceSchema, } from "./catalogFactsSchemas.js";
+import { CommerceQuoteError } from "./quotePorts.js";
+export function createCatalogFactsProvenance(input) {
+    if (input.policy) {
+        if (input.mode !== "subscription") {
+            throw new CommerceQuoteError("PRICING_INVARIANT_VIOLATION", "One-time quote facts cannot carry a subscription policy");
+        }
+        return catalogFactsProvenanceSchema.parse({
+            version: CATALOG_FACTS_POLICY_PROVENANCE_VERSION,
+            skuId: input.item.skuId,
+            documentRevisionId: input.item.documentRevision.id,
+            documentDigest: input.item.documentRevision.digest,
+            basePriceEntryId: input.base.priceEntryId,
+            policyRevisionId: input.policy.policyRevisionId,
+            policyDigest: input.policy.policyDigest,
+            mode: input.mode,
+            atTime: input.atTime,
+            currency: input.currency,
+            resolvedUnitAmountMinor: input.resolvedUnitAmountMinor,
+            resolvedLineAmountMinor: input.resolvedLineAmountMinor,
+            baseUnitAmountMinor: input.baseUnitAmountMinor,
+        });
+    }
+    return catalogFactsProvenanceSchema.parse({
+        version: CATALOG_FACTS_PROVENANCE_VERSION,
+        skuId: input.item.skuId,
+        documentRevisionId: input.item.documentRevision.id,
+        documentDigest: input.item.documentRevision.digest,
+        resolvedPriceEntryId: input.resolved.priceEntryId,
+        basePriceEntryId: input.base.priceEntryId,
+        mode: input.mode,
+        atTime: input.atTime,
+        currency: input.currency,
+        resolvedUnitAmountMinor: input.resolvedUnitAmountMinor,
+        resolvedLineAmountMinor: input.resolvedLineAmountMinor,
+        baseUnitAmountMinor: input.baseUnitAmountMinor,
+    });
+}
+export function catalogFactsForQuoteLine(enabled, item, resolved, base, mode, atTime, currency, resolvedUnitAmountMinor, resolvedLineAmountMinor, baseUnitAmountMinor, policy) {
+    if (!enabled)
+        return undefined;
+    const { id, digest } = item.documentRevision;
+    if (id === null || digest === null) {
+        throw new CommerceQuoteError("PRICE_NOT_CONFIGURED", "Strict catalog facts are unavailable", {
+            sku: item.skuCode,
+            variantId: item.variantId,
+        });
+    }
+    return createCatalogFactsProvenance({
+        item: { ...item, documentRevision: { id, digest } },
+        resolved, base, mode, atTime, currency, resolvedUnitAmountMinor, resolvedLineAmountMinor, baseUnitAmountMinor, policy,
+    });
+}
+/** Public responses retain every money field but never server-only catalog identifiers. */
+export function projectPublicQuoteSnapshot(snapshot) {
+    return {
+        ...snapshot,
+        quote: {
+            ...snapshot.quote,
+            lines: snapshot.quote.lines.map(({ catalogFacts: _catalogFacts, ...line }) => line),
+        },
+    };
+}

package/dist/pricing/catalogFactsSchemas.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * Server-only evidence for a strict quote line. V1 remains readable for
+ * historical and explicitly pre-cutover legacy subscription observations; v2
+ * records the policy which derived a current subscription amount.
+ */
+export declare const catalogFactsProvenanceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    skuId: z.ZodString;
+    documentRevisionId: z.ZodString;
+    documentDigest: z.ZodString;
+    basePriceEntryId: z.ZodString;
+    atTime: z.ZodString;
+    currency: z.ZodString;
+    resolvedUnitAmountMinor: z.ZodNumber;
+    resolvedLineAmountMinor: z.ZodNumber;
+    baseUnitAmountMinor: z.ZodNumber;
+    version: z.ZodLiteral<"catalog_facts_v1">;
+    resolvedPriceEntryId: z.ZodString;
+    mode: z.ZodEnum<{
+        subscription: "subscription";
+        one_time: "one_time";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    skuId: z.ZodString;
+    documentRevisionId: z.ZodString;
+    documentDigest: z.ZodString;
+    basePriceEntryId: z.ZodString;
+    atTime: z.ZodString;
+    currency: z.ZodString;
+    resolvedUnitAmountMinor: z.ZodNumber;
+    resolvedLineAmountMinor: z.ZodNumber;
+    baseUnitAmountMinor: z.ZodNumber;
+    version: z.ZodLiteral<"catalog_facts_v2">;
+    policyRevisionId: z.ZodString;
+    policyDigest: z.ZodString;
+    mode: z.ZodLiteral<"subscription">;
+}, z.core.$strict>]>;
+/** Reject server-only provenance at every HTTP response schema boundary. */
+export declare function rejectCatalogFactsFromPublicQuote(response: {
+    quote: {
+        lines: readonly {
+            catalogFacts?: unknown;
+        }[];
+    };
+}, ctx: z.RefinementCtx, pathPrefix?: Array<string | number>): void;

package/dist/pricing/catalogFactsSchemas.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { CATALOG_FACTS_PROVENANCE_VERSION, CATALOG_FACTS_POLICY_PROVENANCE_VERSION } from "./contracts/provenance.js";
+const catalogFactsFields = {
+    skuId: z.string().uuid(),
+    documentRevisionId: z.string().uuid(),
+    documentDigest: z.string().regex(/^[a-f0-9]{64}$/iu),
+    basePriceEntryId: z.string().trim().min(1).max(120),
+    atTime: z.string().datetime({ offset: true }),
+    currency: z.string().regex(/^[A-Z]{3}$/u),
+    resolvedUnitAmountMinor: z.number().int().min(0),
+    resolvedLineAmountMinor: z.number().int().min(0),
+    baseUnitAmountMinor: z.number().int().min(0),
+};
+/**
+ * Server-only evidence for a quote line resolved from the strict current
+ * catalog facts port. V1 records authored price-entry observations; v2
+ * records policy-derived subscription money without inventing such an entry.
+ */
+const catalogFactsV1ProvenanceSchema = z
+    .object({
+    version: z.literal(CATALOG_FACTS_PROVENANCE_VERSION),
+    resolvedPriceEntryId: z.string().trim().min(1).max(120),
+    mode: z.enum(["one_time", "subscription"]),
+    ...catalogFactsFields,
+})
+    .strict();
+const catalogFactsV2ProvenanceSchema = z
+    .object({
+    version: z.literal(CATALOG_FACTS_POLICY_PROVENANCE_VERSION),
+    // A policy-derived subscription price has no authored subscription price
+    // entry. Its immutable evidence is the exact base anchor plus this policy.
+    policyRevisionId: z.string().uuid(),
+    policyDigest: z.string().regex(/^[a-f0-9]{64}$/iu),
+    mode: z.literal("subscription"),
+    ...catalogFactsFields,
+})
+    .strict();
+/**
+ * Server-only evidence for a strict quote line. V1 remains readable for
+ * historical and explicitly pre-cutover legacy subscription observations; v2
+ * records the policy which derived a current subscription amount.
+ */
+export const catalogFactsProvenanceSchema = z.union([
+    catalogFactsV1ProvenanceSchema,
+    catalogFactsV2ProvenanceSchema,
+]);
+/** Reject server-only provenance at every HTTP response schema boundary. */
+export function rejectCatalogFactsFromPublicQuote(response, ctx, pathPrefix = ["quote"]) {
+    response.quote.lines.forEach((line, index) => {
+        if (line.catalogFacts !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "catalog facts are server-only",
+                path: [...pathPrefix, "lines", index, "catalogFacts"],
+            });
+        }
+    });
+}

package/dist/pricing/commerceOfferPricing.d.ts

@@ -0,0 +1,25 @@
+import { type CommerceOfferPricingResponse } from "./contracts/offer.js";
+import { type PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import { type CommerceQuotePort } from "./quotePorts.js";
+import type { CommerceQuoteCatalogItem } from "./commerceQuoteCatalogReadPort.js";
+export interface CommerceOfferPricingDeps<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string> {
+    quoteCatalogReadPort: {
+        listQuoteCatalogItems(): Promise<Item[]>;
+    };
+    quoteWithPromotions: CommerceQuotePort;
+    quoteWithoutPromotions: CommerceQuotePort;
+    pricingPolicy?: PricingPolicySnapshot;
+    isOfferProduct(product: Item): boolean;
+    requestFor(product: Item, mode: "one_time" | "subscription"): CreateQuoteRequest;
+    unitCount: number;
+    minimumProductPayableMinor: number;
+    scopeV1: ScopeV1;
+    scopeV2: ScopeV2;
+}
+/**
+ * Product-only acquisition projection over the same quote ports used by
+ * configurator checkout. It never prices delivery and is never accepted as a
+ * checkout expectation; its only consumer is non-transactional "from" copy.
+ */
+export declare function projectCommerceOfferPricing<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string>({ quoteCatalogReadPort, quoteWithPromotions, quoteWithoutPromotions, pricingPolicy, isOfferProduct, requestFor, unitCount: COMMERCE_MIN_AUTO_ORDER_UNITS, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, scopeV1, scopeV2, }: CommerceOfferPricingDeps<Item, ScopeV1, ScopeV2>): Promise<CommerceOfferPricingResponse<ScopeV1, ScopeV2>>;

package/dist/pricing/commerceOfferPricing.js

@@ -0,0 +1,139 @@
+import { COMMERCE_OFFER_PRICING_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, } from "./contracts/offer.js";
+import { OFFER_POLICY_V2, PROMOTION_ENGINE_V2, } from "./contracts/offerPolicy.js";
+import { CommerceQuoteError, } from "./quotePorts.js";
+function recordOfferPricingExclusion(diagnostic) {
+    try {
+        console.info(JSON.stringify(diagnostic));
+    }
+    catch {
+        // A private diagnostic sink must never alter the projection it observes.
+    }
+}
+/**
+ * Product-only acquisition projection over the same quote ports used by
+ * configurator checkout. It never prices delivery and is never accepted as a
+ * checkout expectation; its only consumer is non-transactional "from" copy.
+ */
+export async function projectCommerceOfferPricing({ quoteCatalogReadPort, quoteWithPromotions, quoteWithoutPromotions, pricingPolicy, isOfferProduct, requestFor, unitCount: COMMERCE_MIN_AUTO_ORDER_UNITS, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, scopeV1, scopeV2, }) {
+    const products = (await quoteCatalogReadPort.listQuoteCatalogItems()).filter(isOfferProduct);
+    if (products.length === 0)
+        throw new Error("commerce_offer_pricing_unavailable");
+    const settled = await Promise.all(products.map(async (product) => {
+        try {
+            return {
+                product,
+                entry: await projectProduct(product, quoteWithPromotions, quoteWithoutPromotions, requestFor, COMMERCE_MIN_AUTO_ORDER_UNITS, pricingPolicy),
+            };
+        }
+        catch (error) {
+            // One SKU the strict money authority cannot price must not remove every
+            // PDP price block. Only that refusal degrades; an infrastructure failure
+            // or a violated pricing invariant still refuses the whole projection.
+            if (error instanceof CommerceQuoteError && error.code === "PRICE_NOT_CONFIGURED") {
+                recordOfferPricingExclusion({
+                    event: "commerce_offer_pricing_product_excluded",
+                    product_slug: product.productSlug,
+                    refusal_code: typeof error.details.reason === "string" ? error.details.reason : "unknown",
+                });
+                return null;
+            }
+            throw error;
+        }
+    }));
+    const priced = settled.flatMap((outcome) => (outcome ? [outcome] : []));
+    const projected = priced.map((outcome) => outcome.entry);
+    // The minimum below is the customer-facing "from" figure. Over an EMPTY set it
+    // would be meaningless, so a projection that priced nothing refuses exactly as
+    // an empty catalogue does rather than answering with an invented floor.
+    if (projected.length === 0)
+        throw new Error("commerce_offer_pricing_unavailable");
+    const oneTime = minimumBy(projected, (entry) => entry.oneTime.unitGross.amountMinor);
+    const subscription = minimumBy(projected, (entry) => entry.subscriptionInitial.unitGross.amountMinor);
+    const legacy = {
+        contractVersion: COMMERCE_OFFER_PRICING_CONTRACT_VERSION,
+        scope: scopeV1,
+        products: projected,
+        minimum: { oneTime, subscription },
+    };
+    if (pricingPolicy?.offerPolicyVersion !== OFFER_POLICY_V2 ||
+        pricingPolicy.promotionEngineVersion !== PROMOTION_ENGINE_V2)
+        return legacy;
+    // The representative quote must come from a product that actually PRICED. Using
+    // the catalogue's first product would re-raise the very refusal just excluded
+    // and refuse the whole response despite another product having priced.
+    const representative = await quoteWithPromotions.createQuote(requestFor(priced[0].product, "one_time"), pricingPolicy ? { pricingPolicy } : undefined);
+    // An absent shipping figure is zero in the currency the quote came back in.
+    // It used to be zero in a named currency, which is a coercion rather than a
+    // default: a quote in one currency would have carried a shipping line in
+    // another, and the two would have been summed.
+    const quoteCurrency = representative.quote.currency;
+    const gross = representative.quote.shippingGross ?? { amountMinor: 0, currency: quoteCurrency };
+    const discountGross = representative.quote.shippingDiscountGross
+        ?? { amountMinor: 0, currency: quoteCurrency };
+    return {
+        contractVersion: COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION,
+        scope: scopeV2,
+        pricingPolicy,
+        products: projected,
+        minimum: { oneTime, subscription },
+        shipping: {
+            gross,
+            discountGross,
+            payable: { amountMinor: gross.amountMinor - discountGross.amountMinor, currency: gross.currency },
+        },
+        // Both halves come from the injected settlement policy, which supplies the
+        // denomination and left the amount, which was one major unit written out as
+        // a hundredths-assuming literal.
+        minimumProductPayable: {
+            amountMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+            currency: quoteCurrency,
+        },
+    };
+}
+async function projectProduct(product, quoteWithPromotions, quoteWithoutPromotions, requestFor, COMMERCE_MIN_AUTO_ORDER_UNITS, pricingPolicy) {
+    const options = pricingPolicy ? { pricingPolicy } : undefined;
+    const [oneTime, subscriptionInitial, subscriptionRecurring] = await Promise.all([
+        quoteWithPromotions.createQuote(requestFor(product, "one_time"), options),
+        quoteWithPromotions.createQuote(requestFor(product, "subscription"), options),
+        quoteWithoutPromotions.createQuote(requestFor(product, "subscription"), options),
+    ]);
+    const oneTimeProductGross = productGross(oneTime.quote);
+    const initialProductGross = productGross(subscriptionInitial.quote);
+    const recurringProductGross = productGross(subscriptionRecurring.quote);
+    const anchorUnitGross = oneTime.quote.lines[0]?.unitPriceGross;
+    if (!anchorUnitGross)
+        throw new Error("commerce_offer_pricing_line_missing");
+    const anchorPackageGross = anchorUnitGross.amountMinor * COMMERCE_MIN_AUTO_ORDER_UNITS;
+    return {
+        productSlug: product.productSlug,
+        unitCount: COMMERCE_MIN_AUTO_ORDER_UNITS,
+        oneTime: price(oneTimeProductGross, oneTime.quote.currency, COMMERCE_MIN_AUTO_ORDER_UNITS),
+        subscriptionInitial: price(initialProductGross, subscriptionInitial.quote.currency, COMMERCE_MIN_AUTO_ORDER_UNITS),
+        subscriptionRecurring: price(recurringProductGross, subscriptionRecurring.quote.currency, COMMERCE_MIN_AUTO_ORDER_UNITS),
+        catalogAnchorUnitGross: anchorUnitGross,
+        initialDiscountPercent: discountPercent(anchorPackageGross, initialProductGross),
+        recurringDiscountPercent: discountPercent(anchorPackageGross, recurringProductGross),
+    };
+}
+function productGross(quote) {
+    return quote.subtotalGross.amountMinor - quote.discountTotalGross.amountMinor;
+}
+// Carries whatever currency the quote came back in; it is not this helper's job
+// to name one (src/lib/currency/platformCurrency.ts owns that question).
+function price(amountMinor, currency, COMMERCE_MIN_AUTO_ORDER_UNITS) {
+    return {
+        packageGross: { amountMinor, currency },
+        unitGross: {
+            amountMinor: Math.round(amountMinor / COMMERCE_MIN_AUTO_ORDER_UNITS),
+            currency,
+        },
+    };
+}
+function discountPercent(anchorMinor, effectiveMinor) {
+    if (anchorMinor <= 0 || effectiveMinor >= anchorMinor)
+        return 0;
+    return Math.round(((anchorMinor - effectiveMinor) / anchorMinor) * 100);
+}
+function minimumBy(entries, amount) {
+    return entries.reduce((minimum, entry) => amount(entry) < amount(minimum) ? entry : minimum);
+}

package/dist/pricing/commerceOfferPricingCache.d.ts

@@ -0,0 +1,10 @@
+import type { CommerceOfferPricingResponse } from "./contracts/offer.js";
+/** One bounded value and one in-flight load per runtime instance. */
+export interface CommerceOfferPricingCache<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse> {
+    read(key: string, load: () => Promise<Response>): Promise<Response>;
+}
+export declare function createCommerceOfferPricingCache<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse>(input: {
+    ttlMs: number;
+    failureTtlMs?: number;
+    now?: () => number;
+}): CommerceOfferPricingCache<Response>;

package/dist/pricing/commerceOfferPricingCache.js

@@ -0,0 +1,44 @@
+export function createCommerceOfferPricingCache(input) {
+    const now = input.now ?? Date.now;
+    const failureTtlMs = input.failureTtlMs ?? 0;
+    const cached = new Map();
+    const failed = new Map();
+    const pending = new Map();
+    return {
+        read(key, load) {
+            const cachedEntry = cached.get(key);
+            const failedEntry = failed.get(key);
+            if (cachedEntry && cachedEntry.expiresAt > now())
+                return Promise.resolve(cachedEntry.value);
+            if (failedEntry && failedEntry.expiresAt > now())
+                return Promise.reject(failedEntry.error);
+            const pendingEntry = pending.get(key);
+            if (pendingEntry)
+                return pendingEntry;
+            const startedAt = now();
+            const current = load()
+                .then((value) => {
+                // Bound freshness from the pricing instant, not from completion of a
+                // potentially slow DB read.
+                cached.set(key, { value, expiresAt: startedAt + input.ttlMs });
+                failed.delete(key);
+                return value;
+            })
+                .catch((error) => {
+                // A public cold endpoint must not hammer a degraded database once per
+                // request. Keep only the failure object, briefly, and never turn it
+                // into stale pricing data; callers still receive the same rejection.
+                if (failureTtlMs > 0) {
+                    failed.set(key, { error, expiresAt: now() + failureTtlMs });
+                }
+                throw error;
+            })
+                .finally(() => {
+                if (pending.get(key) === current)
+                    pending.delete(key);
+            });
+            pending.set(key, current);
+            return current;
+        },
+    };
+}

package/dist/pricing/commerceOfferPricingHandler.d.ts

@@ -0,0 +1,21 @@
+import type { PricingPolicyRequest, PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import { type CommerceOfferPricingResponse } from "./contracts/offer.js";
+export declare const COMMERCE_OFFER_PRICING_CACHE_CONTROL = "public, max-age=0, s-maxage=5, must-revalidate";
+export declare const COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL = "private, no-store";
+export declare const OFFER_POLICY_CAPABILITY_HEADER = "x-commerce-offer-policy-capability";
+export declare const OFFER_POLICY_TOKEN_HEADER = "x-commerce-pricing-policy-token";
+export declare const OFFER_POLICY_VISITOR_HEADER = "x-commerce-visitor-id";
+export interface CommerceOfferPricingHandlerDeps<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse> {
+    responder: BffResponder;
+    commerceOfferPricingResponseSchema: z.ZodType<Response>;
+    readOfferPricing(pricingPolicy?: PricingPolicySnapshot): Promise<Response>;
+    requirePricingPolicy?: boolean;
+    resolvePricingPolicy?(request: {
+        visitorId: string;
+        pricingPolicy: PricingPolicyRequest;
+    }): PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+export declare function createCommerceOfferPricingHandler<Response extends CommerceOfferPricingResponse>({ responder, commerceOfferPricingResponseSchema, readOfferPricing, resolvePricingPolicy, requirePricingPolicy, }: CommerceOfferPricingHandlerDeps<Response>): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/pricing/commerceOfferPricingHandler.js

@@ -0,0 +1,78 @@
+import { pricingPolicyRequestSchema, } from "./offerPolicySchemas.js";
+// Price/promotion validity can end at any instant. Keep the public cache very
+// short and omit stale-while-revalidate; a future contract may expose the next
+// validity boundary and clamp this exactly to it.
+export const COMMERCE_OFFER_PRICING_CACHE_CONTROL = "public, max-age=0, s-maxage=5, must-revalidate";
+export const COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL = "private, no-store";
+export const OFFER_POLICY_CAPABILITY_HEADER = "x-commerce-offer-policy-capability";
+export const OFFER_POLICY_TOKEN_HEADER = "x-commerce-pricing-policy-token";
+export const OFFER_POLICY_VISITOR_HEADER = "x-commerce-visitor-id";
+const ROUTER_QUERY_KEYS = new Set(["path", "__bffPath"]);
+export function createCommerceOfferPricingHandler({ responder, commerceOfferPricingResponseSchema, readOfferPricing, resolvePricingPolicy, requirePricingPolicy = false, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        const userQueryKeys = Object.keys(req.query ?? {}).filter((key) => !ROUTER_QUERY_KEYS.has(key));
+        if (userQueryKeys.length > 0) {
+            sendBffError(res, "BAD_REQUEST", "Commerce offer pricing does not accept query parameters");
+            return;
+        }
+        try {
+            const policyRequest = readPolicyRequest(req);
+            if (policyRequest === null) {
+                sendBffError(res, "BAD_REQUEST", "Commerce offer pricing policy capability is invalid");
+                return;
+            }
+            if (!policyRequest && requirePricingPolicy) {
+                // A caller that sent no capability headers is an incomplete request,
+                // not an unavailable origin — the same attribution the missing-visitor
+                // branch above already applies.
+                sendBffError(res, "BAD_REQUEST", "Commerce offer pricing requires offer policy v2", {
+                    details: {
+                        reason: "pricing_policy_request_invalid",
+                        stage: "pricing_policy",
+                        policyReason: "v2_capability_required",
+                    },
+                });
+                return;
+            }
+            const pricingPolicy = policyRequest && resolvePricingPolicy
+                ? await resolvePricingPolicy(policyRequest)
+                : undefined;
+            const parsed = commerceOfferPricingResponseSchema.safeParse(await readOfferPricing(pricingPolicy));
+            if (!parsed.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Commerce offer pricing returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, parsed.data, { contractVersion: parsed.data.contractVersion }, {
+                cacheControl: policyRequest
+                    ? COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL
+                    : COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+            });
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Commerce offer pricing is unavailable");
+        }
+    };
+}
+function readPolicyRequest(req) {
+    const capability = singleHeader(req, OFFER_POLICY_CAPABILITY_HEADER);
+    const token = singleHeader(req, OFFER_POLICY_TOKEN_HEADER);
+    if (!capability && !token)
+        return undefined;
+    const visitorId = singleHeader(req, OFFER_POLICY_VISITOR_HEADER);
+    if (!visitorId || visitorId.length > 120)
+        return null;
+    const parsed = pricingPolicyRequestSchema.safeParse({
+        ...(capability ? { capability } : {}),
+        ...(token ? { token } : {}),
+    });
+    return parsed.success ? { visitorId, pricingPolicy: parsed.data } : null;
+}
+function singleHeader(req, name) {
+    const value = req.headers?.[name];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/pricing/commercePriceAuthority.d.ts

@@ -0,0 +1,26 @@
+import type { CommercePriceAuthorityQuery } from "./contracts/index.js";
+import { type CommercePriceAuthorityPort } from "./ports.js";
+import type { ResolvedPrice } from "@openlup/core/pricing";
+export interface TimedAuthorityValue<T> {
+    value: T;
+    validFrom: string;
+    validTo: string | null;
+}
+export interface CommercePriceAuthorityReadPort {
+    listPriceLists(context: Pick<CommercePriceAuthorityQuery, "regionCode" | "currency">): Promise<ReadonlyArray<TimedAuthorityValue<string>>>;
+    listExactBaseEntries(input: {
+        variantId: string;
+        priceListId: string;
+    }): Promise<ReadonlyArray<TimedAuthorityValue<ResolvedPrice>>>;
+    listExactLegacySubscriptionEntries(input: {
+        variantId: string;
+        priceListId: string;
+    }): Promise<ReadonlyArray<TimedAuthorityValue<ResolvedPrice>>>;
+    listSubscriptionPolicyHistory(context: Pick<CommercePriceAuthorityQuery, "regionCode" | "currency" | "channel"> & {
+        priceListId: string;
+    }): Promise<ReadonlyArray<TimedAuthorityValue<unknown>>>;
+}
+/** Provider-neutral strict money algorithm; adapters own only persistence reads and row mapping. */
+export declare function createCommercePriceAuthorityPort(reads: CommercePriceAuthorityReadPort): CommercePriceAuthorityPort;
+/** The current money context requires one list; creation order cannot resolve overlap. */
+export declare function selectUniqueEffectivePriceList(priceLists: readonly TimedAuthorityValue<string>[], atTime: string): string;

package/dist/pricing/commercePriceAuthority.js

@@ -0,0 +1,79 @@
+import { CommercePriceAuthorityError, } from "./ports.js";
+import { SubscriptionPricePolicyDigestError, assertSubscriptionPricePolicyDigest, deriveSubscriptionUnitPrice, } from "./subscriptionPricePolicy.js";
+/** Provider-neutral strict money algorithm; adapters own only persistence reads and row mapping. */
+export function createCommercePriceAuthorityPort(reads) {
+    return {
+        async resolvePrice(query) {
+            const atTime = query.atTime ?? new Date().toISOString();
+            const priceListId = selectUniqueEffectivePriceList(await reads.listPriceLists(query), atTime);
+            const baseCandidates = effective(await reads.listExactBaseEntries({
+                variantId: query.variantId,
+                priceListId,
+            }), atTime);
+            if (baseCandidates.length === 0)
+                throw new CommercePriceAuthorityError("base_price_not_found");
+            if (baseCandidates.length !== 1)
+                throw new CommercePriceAuthorityError("base_price_ambiguous");
+            if (baseCandidates[0].value.amountKind !== "gross") {
+                throw new CommercePriceAuthorityError("base_price_amount_kind_invalid");
+            }
+            const base = { ...baseCandidates[0].value, resolvedAt: atTime };
+            if (query.mode === "one_time")
+                return { kind: "one_time", base, unitPriceMinor: base.unitPriceMinor };
+            const policyHistory = await reads.listSubscriptionPolicyHistory({
+                priceListId: base.priceListId,
+                regionCode: query.regionCode,
+                currency: query.currency,
+                channel: query.channel,
+            });
+            if (policyHistory.length === 0) {
+                const legacyCandidates = effective(await reads.listExactLegacySubscriptionEntries({
+                    variantId: query.variantId,
+                    priceListId: base.priceListId,
+                }), atTime);
+                if (legacyCandidates.length === 0)
+                    throw new CommercePriceAuthorityError("legacy_subscription_price_not_found");
+                if (legacyCandidates.length !== 1)
+                    throw new CommercePriceAuthorityError("legacy_subscription_price_ambiguous");
+                const legacyResolved = { ...legacyCandidates[0].value, resolvedAt: atTime };
+                return { kind: "subscription_legacy", base, unitPriceMinor: legacyResolved.unitPriceMinor, legacyResolved };
+            }
+            const effectivePolicies = effective(policyHistory, atTime);
+            if (effectivePolicies.length === 0)
+                throw new CommercePriceAuthorityError("subscription_price_policy_not_effective");
+            if (effectivePolicies.length !== 1)
+                throw new CommercePriceAuthorityError("subscription_price_policy_ambiguous");
+            try {
+                const policy = await assertSubscriptionPricePolicyDigest(effectivePolicies[0].value);
+                return {
+                    kind: "subscription_policy",
+                    base,
+                    unitPriceMinor: deriveSubscriptionUnitPrice(base.unitPriceMinor, policy),
+                    policy,
+                };
+            }
+            catch (error) {
+                throw new CommercePriceAuthorityError(error instanceof SubscriptionPricePolicyDigestError
+                    ? "subscription_price_policy_digest_mismatch"
+                    : "subscription_price_policy_invalid");
+            }
+        },
+    };
+}
+/** The current money context requires one list; creation order cannot resolve overlap. */
+export function selectUniqueEffectivePriceList(priceLists, atTime) {
+    const candidates = effective(priceLists, atTime);
+    if (candidates.length === 0)
+        throw new CommercePriceAuthorityError("active_price_list_not_found");
+    if (candidates.length !== 1)
+        throw new CommercePriceAuthorityError("active_price_list_ambiguous");
+    return candidates[0].value;
+}
+function effective(values, atTime) {
+    const atMs = Date.parse(atTime);
+    return values.filter(({ validFrom, validTo }) => {
+        const fromMs = Date.parse(validFrom);
+        const toMs = validTo === null ? null : Date.parse(validTo);
+        return Number.isFinite(atMs) && Number.isFinite(fromMs) && fromMs <= atMs && (toMs === null || toMs > atMs);
+    });
+}

package/dist/pricing/commercePricingPolicyErrors.d.ts

@@ -0,0 +1,40 @@
+/** The server cannot assign a policy right now. Caller-independent: retrying an
+ * identical request only succeeds once production configuration changes. */
+export declare class CommercePricingPolicyUnavailableError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Every reason a caller-side refusal can carry. ⛔ Each one answers `400`, which
+ * puts it outside every 5xx monitor, so each one owes a dedicated monitor of its
+ * own; a host's observability check can read this tuple and fail when a reason
+ * has none. Adding a member here without adding a monitor is the regression this
+ * tuple exists to prevent: reclassifying `v2_capability_required` from `503` to
+ * `400` once silently removed the only alert on a site-wide unpriceable-quote
+ * outage.
+ */
+export declare const PRICING_POLICY_REQUEST_REASONS: readonly ["v2_capability_required", "v2_visitor_id_required"];
+export type PricingPolicyRequestReason = (typeof PRICING_POLICY_REQUEST_REASONS)[number];
+/** The request itself lacks the context a v2 assignment needs. Caller-fixable,
+ * and never evidence that pricing is down. The reason is typed off
+ * PRICING_POLICY_REQUEST_REASONS so a new one cannot skip its monitor. */
+export declare class CommercePricingPolicyRequestError extends Error {
+    readonly reason: PricingPolicyRequestReason;
+    constructor(reason: PricingPolicyRequestReason);
+}
+export type SafePricingPolicyReason = "v2_capability_required" | "v2_visitor_id_required" | "signing_secret_unavailable" | "v1_assignment_rejected" | "v2_assignment_config_invalid" | "v2_readiness_not_ready" | "other";
+export interface PricingPolicyFailureMapping {
+    code: "BAD_REQUEST" | "UPSTREAM_UNAVAILABLE";
+    details: {
+        reason: "pricing_policy_request_invalid" | "pricing_policy_unavailable";
+        stage: "pricing_policy";
+        policyReason: SafePricingPolicyReason;
+    };
+}
+/**
+ * Single owner of the status a pricing-policy refusal earns, shared by every
+ * route that resolves one. A caller-attributable gap answers `400`; only a
+ * server that genuinely cannot price answers `503`, so a `503` on these routes
+ * stays a truthful outage signal.
+ */
+export declare function mapPricingPolicyFailure(error: unknown): PricingPolicyFailureMapping | null;