@openlup/platform 0.17.0 → 0.19.0

package/dist/pricing/dbBackedCommerceQuotePort.js

@@ -0,0 +1,223 @@
+import { buildLineBreakdown } from "@openlup/core/pricing";
+import { COMMERCE_CONTRACT_VERSION, PROMOTION_ENGINE_V2 } from "./contracts/index.js";
+import { CommerceQuoteError } from "./quotePorts.js";
+import { splitIncludedVat } from "./quoteSchemas.js";
+import { assertSubscriptionCheapest, buildSkuIndex, calculateIncludedVat, eligibleQtyForMode, mapPricingComponent, moneyIn, resolveOneTimeComparison, resolveStrictQuotePrice, sum, toGrossMinor } from "./dbBackedCommerceQuoteHelpers.js";
+import { assertSupportedCommerceTaxProfile } from "./taxProfileGuard.js";
+import { catalogFactsForQuoteLine, projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+const STRICT_D1_COMMERCE_CHANNEL = "D2C";
+export function createDbBackedCommerceQuotePort(deps) {
+    const { taxProfile, supportedTaxProfiles, regionCode, currency, now = () => new Date().toISOString(), quoteCatalogReadPort, isStrictD1Quote, pricingResolverPort, commercePriceAuthorityPort, shippingFlatMinor, resolveAutomaticQuotePromotions, applyPromotionCodesV2, hasPromotionCodePort, lineContext, quoteContext, resolveQuoteShippingPromotions, } = deps;
+    assertSupportedCommerceTaxProfile(taxProfile, supportedTaxProfiles);
+    const money = moneyIn(currency);
+    async function createServerAuthoritativeQuote(request, options) {
+        const atTime = now();
+        const skuIndex = await buildSkuIndex(quoteCatalogReadPort);
+        const pricedLines = await Promise.all(request.lines.map(async (requestLine) => {
+            const entry = skuIndex.get(requestLine.sku);
+            if (!entry || (requestLine.variantId && requestLine.variantId !== entry.item.variantId)) {
+                throw new CommerceQuoteError("UNKNOWN_SKU", "Unknown commerce SKU", {
+                    sku: requestLine.sku,
+                    variantId: requestLine.variantId ?? null,
+                });
+            }
+            const modeAtLine = requestLine.modeAtLine ?? request.mode;
+            if (!entry.item.sellability[modeAtLine === "one_time" ? "oneTime" : "subscription"]) {
+                throw new CommerceQuoteError("UNKNOWN_SKU", "Commerce SKU is not sellable in this purchase mode", {
+                    sku: requestLine.sku,
+                    variantId: entry.item.variantId,
+                    mode: modeAtLine,
+                });
+            }
+            const eligibleCartQty = eligibleQtyForMode(request, modeAtLine);
+            const strictResolution = isStrictD1Quote
+                ? await resolveStrictQuotePrice({
+                    commercePriceAuthorityPort: commercePriceAuthorityPort,
+                    variantId: entry.item.variantId,
+                    mode: modeAtLine,
+                    regionCode,
+                    currency,
+                    channel: STRICT_D1_COMMERCE_CHANNEL,
+                    atTime,
+                })
+                : undefined;
+            const resolved = strictResolution?.resolved ?? await pricingResolverPort.resolvePrice({
+                variantId: entry.item.variantId,
+                mode: modeAtLine,
+                lineQty: requestLine.quantity,
+                eligibleCartQty,
+                regionCode,
+                currency,
+                atTime,
+            });
+            if (!resolved) {
+                throw new CommerceQuoteError("PRICE_NOT_CONFIGURED", "Commerce price is not configured", {
+                    sku: requestLine.sku,
+                    variantId: entry.item.variantId,
+                    mode: modeAtLine,
+                });
+            }
+            const oneTime = strictResolution?.base ?? await resolveOneTimeComparison({
+                pricingResolverPort: pricingResolverPort,
+                variantId: entry.item.variantId,
+                lineQty: requestLine.quantity,
+                eligibleCartQty,
+                regionCode,
+                currency,
+                atTime,
+            });
+            const promotionReference = hasPromotionCodePort && request.promoCodes.length > 0
+                ? strictResolution?.base ?? await resolveOneTimeComparison({
+                    pricingResolverPort: pricingResolverPort,
+                    variantId: entry.item.variantId,
+                    lineQty: requestLine.quantity,
+                    eligibleCartQty: 1,
+                    regionCode,
+                    currency,
+                    atTime,
+                })
+                : oneTime;
+            assertSubscriptionCheapest({
+                requestSku: requestLine.sku,
+                modeAtLine,
+                resolved,
+                oneTime,
+                vatRateBps: taxProfile.vatRateBps,
+            });
+            const unitPriceGrossMinor = toGrossMinor(resolved, taxProfile.vatRateBps);
+            const baseUnitGrossMinor = oneTime ? toGrossMinor(oneTime, taxProfile.vatRateBps) : unitPriceGrossMinor;
+            const grossMinor = unitPriceGrossMinor * requestLine.quantity;
+            const tax = calculateIncludedVat(grossMinor, taxProfile.vatRateBps);
+            const pricingComponents = buildLineBreakdown({
+                variant_id: entry.item.variantId,
+                line_qty: requestLine.quantity,
+                base_unit_price_minor: baseUnitGrossMinor,
+                resolved_unit_price_minor: unitPriceGrossMinor,
+                matched_tier_min_qty: resolved.matchedMinQty,
+                mode_at_line: modeAtLine,
+                mode_resolved_via_fallback: resolved.mode === "any",
+            }).map((component) => mapPricingComponent(component, "line"));
+            const catalogFacts = isStrictD1Quote
+                ? catalogFactsForQuoteLine(true, entry.item, resolved, oneTime, modeAtLine, atTime, currency, unitPriceGrossMinor, grossMinor, toGrossMinor(oneTime, taxProfile.vatRateBps), strictResolution?.policy)
+                : undefined;
+            return {
+                line: {
+                    sku: entry.item.skuCode,
+                    productSlug: entry.item.productSlug,
+                    quantity: requestLine.quantity,
+                    unitPriceGross: money(unitPriceGrossMinor),
+                    lineSubtotalGross: money(grossMinor),
+                    tax: {
+                        ...taxProfile,
+                        netAmount: money(tax.netMinor),
+                        vatAmount: money(tax.vatMinor),
+                        grossAmount: money(grossMinor),
+                    },
+                    pricingComponents,
+                    ...(catalogFacts ? { catalogFacts } : {}),
+                },
+                pricingComponents,
+                ...lineContext(requestLine, entry.item),
+                referenceGrossMinor: toGrossMinor(promotionReference ?? oneTime ?? resolved, taxProfile.vatRateBps)
+                    * requestLine.quantity,
+            };
+        }));
+        const lines = pricedLines.map((entry) => entry.line);
+        const quoteComponents = pricedLines.flatMap((entry) => entry.pricingComponents);
+        const context = quoteContext(request, pricedLines);
+        const subtotalGrossMinor = sum(lines.map((line) => line.lineSubtotalGross.amountMinor));
+        const referenceProductMinor = sum(pricedLines.map((entry) => entry.referenceGrossMinor));
+        const netTotalMinor = sum(lines.map((line) => line.tax.netAmount.amountMinor));
+        const taxTotalMinor = sum(lines.map((line) => line.tax.vatAmount.amountMinor));
+        let shippingGrossMinor;
+        let promotionResult;
+        let hasShipping;
+        let shippingTerms;
+        let acquisitionTerms;
+        if (resolveQuoteShippingPromotions) {
+            const resolved = await resolveQuoteShippingPromotions({ request, options, regionCode, currency, referenceProductMinor, subtotalGrossMinor, atTime });
+            shippingGrossMinor = resolved.shippingGrossMinor;
+            promotionResult = resolved;
+            hasShipping = resolved.hasShipping;
+            shippingTerms = resolved.shippingTerms;
+            acquisitionTerms = resolved.acquisitionTerms;
+        }
+        else {
+            // Shipping is a flat per-order gross from settings; absent settings port ⇒ no
+            // shipping (byte-identical to pre-shipping quotes). Resolved before promo eval so
+            // the free-shipping lane has a real amount to zero.
+            shippingGrossMinor = shippingFlatMinor
+                ? await shippingFlatMinor()
+                : 0;
+            const automaticPromotionResult = await resolveAutomaticQuotePromotions({
+                request,
+                options,
+                regionCode,
+                referenceProductMinor,
+                subtotalGrossMinor,
+                shippingGrossMinor,
+                atTime,
+            });
+            promotionResult = await applyPromotionCodesV2({
+                preserveLegacyDiscountsWhenNoCandidates: options?.pricingPolicy?.promotionEngineVersion !== PROMOTION_ENGINE_V2,
+                clientId: options?.clientId ?? null,
+                mode: request.mode,
+                promoCodes: request.promoCodes,
+                referenceProductMinor: sum(pricedLines.map((entry) => entry.referenceGrossMinor)),
+                subtotalGrossMinor,
+                shippingGrossMinor,
+                discounts: automaticPromotionResult.discounts,
+                codeRejections: automaticPromotionResult.codeRejections,
+                atTime,
+            });
+            hasShipping = shippingFlatMinor != null;
+        }
+        const { discounts, codeRejections, codeRejectionDetails } = promotionResult;
+        // Two lanes: order_total/line discounts reduce the subtotal; a shipping discount
+        // (free-shipping promo) reduces the shipping gross. They are summed and validated
+        // independently by the quote schema.
+        const orderDiscountMinor = discounts
+            .filter((d) => d.appliesTo !== "shipping")
+            .reduce((total, d) => total + d.amountOffMinor, 0);
+        const shippingDiscountMinor = discounts
+            .filter((d) => d.appliesTo === "shipping")
+            .reduce((total, d) => total + d.amountOffMinor, 0);
+        const { netMinor: discountNetMinor, vatMinor: discountVatMinor } = splitIncludedVat(orderDiscountMinor, taxProfile.vatRateBps);
+        const ship = splitIncludedVat(shippingGrossMinor, taxProfile.vatRateBps);
+        const shipDiscount = splitIncludedVat(shippingDiscountMinor, taxProfile.vatRateBps);
+        const shippingFields = hasShipping
+            ? {
+                shippingGross: money(shippingGrossMinor),
+                shippingDiscountGross: money(shippingDiscountMinor),
+            }
+            : {};
+        return {
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            quote: {
+                currency,
+                taxIncluded: true,
+                lines,
+                discounts,
+                ...(codeRejections.length ? { codeRejections } : {}),
+                ...(codeRejectionDetails.length ? { codeRejectionDetails } : {}),
+                pricingComponents: quoteComponents,
+                context: {
+                    ...context(),
+                    ...(resolveQuoteShippingPromotions && acquisitionTerms ? { acquisitionTerms } : {}),
+                    ...(resolveQuoteShippingPromotions && shippingTerms ? { shippingTerms } : {}),
+                    ...(options?.pricingPolicy ? { pricingPolicy: options.pricingPolicy } : {}),
+                },
+                subtotalGross: money(subtotalGrossMinor),
+                discountTotalGross: money(orderDiscountMinor),
+                ...shippingFields,
+                totalGross: money(subtotalGrossMinor - orderDiscountMinor + shippingGrossMinor - shippingDiscountMinor),
+                netTotal: money(netTotalMinor - discountNetMinor + ship.netMinor - shipDiscount.netMinor),
+                taxTotal: money(taxTotalMinor - discountVatMinor + ship.vatMinor - shipDiscount.vatMinor),
+            },
+        };
+    }
+    return {
+        createQuote: async (request, options) => projectPublicQuoteSnapshot(await createServerAuthoritativeQuote(request, options)),
+        createServerAuthoritativeQuote,
+    };
+}

package/dist/pricing/dbBackedCommerceQuoteSnapshotVerifier.d.ts

@@ -0,0 +1,4 @@
+import type { z } from "zod";
+import { type CreateQuoteResponse } from "./contracts/quote.js";
+import { type CommerceQuotePort, type CommerceQuoteSnapshotVerifierPort } from "./quotePorts.js";
+export declare function createDbBackedCommerceQuoteSnapshotVerifier<Request, Response extends CreateQuoteResponse>(quotePort: CommerceQuotePort<Request, Response>, quoteRequestFromSnapshot: (snapshot: Response) => Request, createQuoteResponseSchema: z.ZodType<Response>): CommerceQuoteSnapshotVerifierPort<Response>;

package/dist/pricing/dbBackedCommerceQuoteSnapshotVerifier.js

@@ -0,0 +1,25 @@
+import { isDeepStrictEqual } from "node:util";
+import { CommerceQuoteSnapshotError, } from "./quotePorts.js";
+import { projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+import { createExpectedQuote } from "./commerceQuoteSnapshotExpect.js";
+export function createDbBackedCommerceQuoteSnapshotVerifier(quotePort, quoteRequestFromSnapshot, createQuoteResponseSchema) {
+    async function verifyAndEnrich(snapshot) {
+        const publicSnapshot = projectPublicQuoteSnapshot(snapshot);
+        const expected = await createExpectedQuote(quotePort.createServerAuthoritativeQuote
+            ? { createQuote: quotePort.createServerAuthoritativeQuote.bind(quotePort) }
+            : quotePort, quoteRequestFromSnapshot(publicSnapshot), {
+            invalidResponseMessage: "Commerce DB-backed quote verifier returned invalid response",
+            catalogMismatchMessage: "Commerce quote snapshot does not match current DB-backed catalog pricing",
+        }, createQuoteResponseSchema);
+        if (!isDeepStrictEqual(publicSnapshot, projectPublicQuoteSnapshot(expected))) {
+            throw new CommerceQuoteSnapshotError("QUOTE_SNAPSHOT_MISMATCH", "Commerce quote snapshot does not match current DB-backed catalog pricing", {
+                reason: "snapshot_does_not_match_db_backed_quote",
+                skus: publicSnapshot.quote.lines.map((line) => line.sku),
+            });
+        }
+        return expected;
+    }
+    return {
+        verifyQuoteSnapshot: verifyAndEnrich,
+    };
+}

package/dist/pricing/index.d.ts

@@ -0,0 +1,52 @@
+export * from "./contracts/index.js";
+export { CommercePriceAuthorityError } from "./ports.js";
+export type { CommercePriceAuthorityPort } from "./ports.js";
+export { createCommercePriceAuthorityPort, createConcurrentCommercePriceAuthorityPort, selectUniqueEffectivePriceList } from "./commercePriceAuthority.js";
+export type { CommercePriceAuthorityReadPort, TimedAuthorityValue } from "./commercePriceAuthority.js";
+export { subscriptionPricePolicySemanticsSchema, subscriptionPricePolicyCanonicalInputSchema, subscriptionPricePolicyRevisionSchema, SubscriptionPricePolicyDigestError, canonicalSubscriptionPricePolicyTuple, digestSubscriptionPricePolicy, assertSubscriptionPricePolicyDigest, deriveSubscriptionUnitPrice } from "./subscriptionPricePolicy.js";
+export { offerPolicyVersionSchema, promotionEngineVersionSchema, pricingPolicyRequestSchema, pricingPolicySnapshotSchema } from "./offerPolicySchemas.js";
+export { createPricingPolicyToken, verifyPricingPolicyToken, resolvePricingPolicy } from "./pricingPolicyToken.js";
+export type { PricingPolicyTokenPayload } from "./pricingPolicyToken.js";
+export { CommercePricingPolicyUnavailableError, PRICING_POLICY_REQUEST_REASONS, CommercePricingPolicyRequestError, mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+export type { PricingPolicyRequestReason, SafePricingPolicyReason, PricingPolicyFailureMapping } from "./commercePricingPolicyErrors.js";
+export { CommerceQuoteError, CommerceQuoteSnapshotError } from "./quotePorts.js";
+export type { CreateQuoteOptions, CommerceQuotePort, CommerceQuoteSnapshotVerifierPort, CommerceQuoteErrorCode, CommerceQuoteSnapshotErrorCode } from "./quotePorts.js";
+export { createCommerceQuotePrimitives } from "./quotePrimitives.js";
+export { createCommerceQuoteSchemas, splitIncludedVat, quoteMoneyCurrenciesMatch } from "./quoteSchemas.js";
+export { quoteDiscountSchema, hasValidV2PromotionEvidence } from "./quotePromotionEvidence.js";
+export { quoteCodeRejectionDetailSchema } from "./quoteCodeRejectionDetails.js";
+export { catalogFactsProvenanceSchema, rejectCatalogFactsFromPublicQuote } from "./catalogFactsSchemas.js";
+export { createCatalogFactsProvenance, catalogFactsForQuoteLine, projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+export { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+export type { CommerceQuoteCatalogItem, CommerceQuoteCatalogReadPort, CommerceQuoteCatalogReadRefusalCode } from "./commerceQuoteCatalogReadPort.js";
+export { assertSupportedCommerceTaxProfile } from "./taxProfileGuard.js";
+export { buildSkuIndex, eligibleQtyForMode, resolveOneTimeComparison, resolveStrictQuotePrice, assertSubscriptionCheapest, toGrossMinor, calculateIncludedVat, mapPricingComponent, moneyIn, sum } from "./dbBackedCommerceQuoteHelpers.js";
+export type { SkuIndexEntry, StrictQuotePriceResolution } from "./dbBackedCommerceQuoteHelpers.js";
+export { createDbBackedCommerceQuotePort } from "./dbBackedCommerceQuotePort.js";
+export type { DbBackedCommerceQuotePortDeps, QuotePromotionResult } from "./dbBackedCommerceQuotePort.js";
+export { createExpectedQuote } from "./commerceQuoteSnapshotExpect.js";
+export type { QuoteSnapshotExpectMessages } from "./commerceQuoteSnapshotExpect.js";
+export { createDbBackedCommerceQuoteSnapshotVerifier } from "./dbBackedCommerceQuoteSnapshotVerifier.js";
+export { createCommerceQuoteHandler } from "./commerceQuoteHandler.js";
+export type { CommerceQuoteHandlerDeps } from "./commerceQuoteHandler.js";
+export { createCommerceQuoteBatchHandler } from "./commerceQuoteBatchHandler.js";
+export type { CommerceQuoteBatchHandlerDeps } from "./commerceQuoteBatchHandler.js";
+export { createCommerceOfferPricingSchemas } from "./offerPricingSchemas.js";
+export { projectCommerceOfferPricing } from "./commerceOfferPricing.js";
+export type { CommerceOfferPricingDeps } from "./commerceOfferPricing.js";
+export { createCommerceOfferPricingHandler, COMMERCE_OFFER_PRICING_CACHE_CONTROL, COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL, OFFER_POLICY_CAPABILITY_HEADER, OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER } from "./commerceOfferPricingHandler.js";
+export type { CommerceOfferPricingHandlerDeps } from "./commerceOfferPricingHandler.js";
+export { createCommerceOfferPricingCache } from "./commerceOfferPricingCache.js";
+export type { CommerceOfferPricingCache } from "./commerceOfferPricingCache.js";
+export { OFFER_POLICY_V2_READINESS_CONTRACT, createOfferPolicyReadinessCache, readOfferPolicyV2Readiness, resetOfferPolicyReadinessCacheForTests } from "./offerPolicyReadiness.js";
+export type { OfferPolicyV2Readiness, OfferPolicyReadinessPort, OfferPolicyReadinessCache } from "./offerPolicyReadiness.js";
+export * from "./acquisitionFinancialPolicy.js";
+export * from "./acquisitionTermsSchemas.js";
+export * from "./acquisitionTerms.js";
+export * from "./quoteAcquisitionTerms.js";
+export * from "./acquisitionQuoteBinding.js";
+export * from "./acquisitionOfferPricingSchemas.js";
+export * from "./acquisitionOfferPricing.js";
+export * from "./acquisitionOfferPricingHandler.js";
+export * from "./acquisitionReadiness.js";
+export type { QuoteShippingPromotionInput, QuoteShippingPromotionResult } from "./quoteShippingPromotions.js";

package/dist/pricing/index.js

@@ -0,0 +1,36 @@
+export * from "./contracts/index.js";
+export { CommercePriceAuthorityError } from "./ports.js";
+export { createCommercePriceAuthorityPort, createConcurrentCommercePriceAuthorityPort, selectUniqueEffectivePriceList } from "./commercePriceAuthority.js";
+export { subscriptionPricePolicySemanticsSchema, subscriptionPricePolicyCanonicalInputSchema, subscriptionPricePolicyRevisionSchema, SubscriptionPricePolicyDigestError, canonicalSubscriptionPricePolicyTuple, digestSubscriptionPricePolicy, assertSubscriptionPricePolicyDigest, deriveSubscriptionUnitPrice } from "./subscriptionPricePolicy.js";
+export { offerPolicyVersionSchema, promotionEngineVersionSchema, pricingPolicyRequestSchema, pricingPolicySnapshotSchema } from "./offerPolicySchemas.js";
+export { createPricingPolicyToken, verifyPricingPolicyToken, resolvePricingPolicy } from "./pricingPolicyToken.js";
+export { CommercePricingPolicyUnavailableError, PRICING_POLICY_REQUEST_REASONS, CommercePricingPolicyRequestError, mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+export { CommerceQuoteError, CommerceQuoteSnapshotError } from "./quotePorts.js";
+export { createCommerceQuotePrimitives } from "./quotePrimitives.js";
+export { createCommerceQuoteSchemas, splitIncludedVat, quoteMoneyCurrenciesMatch } from "./quoteSchemas.js";
+export { quoteDiscountSchema, hasValidV2PromotionEvidence } from "./quotePromotionEvidence.js";
+export { quoteCodeRejectionDetailSchema } from "./quoteCodeRejectionDetails.js";
+export { catalogFactsProvenanceSchema, rejectCatalogFactsFromPublicQuote } from "./catalogFactsSchemas.js";
+export { createCatalogFactsProvenance, catalogFactsForQuoteLine, projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+export { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+export { assertSupportedCommerceTaxProfile } from "./taxProfileGuard.js";
+export { buildSkuIndex, eligibleQtyForMode, resolveOneTimeComparison, resolveStrictQuotePrice, assertSubscriptionCheapest, toGrossMinor, calculateIncludedVat, mapPricingComponent, moneyIn, sum } from "./dbBackedCommerceQuoteHelpers.js";
+export { createDbBackedCommerceQuotePort } from "./dbBackedCommerceQuotePort.js";
+export { createExpectedQuote } from "./commerceQuoteSnapshotExpect.js";
+export { createDbBackedCommerceQuoteSnapshotVerifier } from "./dbBackedCommerceQuoteSnapshotVerifier.js";
+export { createCommerceQuoteHandler } from "./commerceQuoteHandler.js";
+export { createCommerceQuoteBatchHandler } from "./commerceQuoteBatchHandler.js";
+export { createCommerceOfferPricingSchemas } from "./offerPricingSchemas.js";
+export { projectCommerceOfferPricing } from "./commerceOfferPricing.js";
+export { createCommerceOfferPricingHandler, COMMERCE_OFFER_PRICING_CACHE_CONTROL, COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL, OFFER_POLICY_CAPABILITY_HEADER, OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER } from "./commerceOfferPricingHandler.js";
+export { createCommerceOfferPricingCache } from "./commerceOfferPricingCache.js";
+export { OFFER_POLICY_V2_READINESS_CONTRACT, createOfferPolicyReadinessCache, readOfferPolicyV2Readiness, resetOfferPolicyReadinessCacheForTests } from "./offerPolicyReadiness.js";
+export * from "./acquisitionFinancialPolicy.js";
+export * from "./acquisitionTermsSchemas.js";
+export * from "./acquisitionTerms.js";
+export * from "./quoteAcquisitionTerms.js";
+export * from "./acquisitionQuoteBinding.js";
+export * from "./acquisitionOfferPricingSchemas.js";
+export * from "./acquisitionOfferPricing.js";
+export * from "./acquisitionOfferPricingHandler.js";
+export * from "./acquisitionReadiness.js";

package/dist/pricing/offerPolicyReadiness.d.ts

@@ -0,0 +1,21 @@
+export declare const OFFER_POLICY_V2_READINESS_CONTRACT = "commerce-offer-policy-v2-readiness.v1";
+export interface OfferPolicyV2Readiness {
+    contractVersion: typeof OFFER_POLICY_V2_READINESS_CONTRACT;
+    ready: boolean;
+    checkedAt: string;
+    reasons: string[];
+}
+export interface OfferPolicyReadinessPort {
+    readOfferPolicyV2Readiness(): Promise<unknown>;
+}
+export interface OfferPolicyReadinessCache {
+    read(port: OfferPolicyReadinessPort): Promise<OfferPolicyV2Readiness>;
+    clear(): void;
+}
+export declare function createOfferPolicyReadinessCache(input?: {
+    now?: () => number;
+    positiveTtlMs?: number;
+    negativeTtlMs?: number;
+}): OfferPolicyReadinessCache;
+export declare function readOfferPolicyV2Readiness(port: OfferPolicyReadinessPort): Promise<OfferPolicyV2Readiness>;
+export declare function resetOfferPolicyReadinessCacheForTests(isTest: boolean): void;

package/dist/pricing/offerPolicyReadiness.js

@@ -0,0 +1,79 @@
+export const OFFER_POLICY_V2_READINESS_CONTRACT = "commerce-offer-policy-v2-readiness.v1";
+export function createOfferPolicyReadinessCache(input = {}) {
+    const now = input.now ?? Date.now;
+    const positiveTtlMs = Math.min(60_000, Math.max(0, input.positiveTtlMs ?? 60_000));
+    const negativeTtlMs = Math.min(5_000, Math.max(0, input.negativeTtlMs ?? 5_000));
+    let cached = null;
+    let inFlight = null;
+    return {
+        read(port) {
+            const current = now();
+            if (cached && cached.expiresAtMs > current)
+                return Promise.resolve(cached.readiness);
+            if (inFlight)
+                return inFlight;
+            const startedAtMs = current;
+            inFlight = loadFailClosed(port)
+                .then((readiness) => {
+                cached = {
+                    readiness,
+                    // Bound staleness from the start of the database read. A slow RPC
+                    // must consume the TTL, not extend a green decision past 60s.
+                    expiresAtMs: startedAtMs + (readiness.ready ? positiveTtlMs : negativeTtlMs),
+                };
+                return readiness;
+            })
+                .finally(() => {
+                inFlight = null;
+            });
+            return inFlight;
+        },
+        clear() {
+            cached = null;
+            inFlight = null;
+        },
+    };
+}
+const sharedCache = createOfferPolicyReadinessCache();
+export function readOfferPolicyV2Readiness(port) {
+    return sharedCache.read(port);
+}
+export function resetOfferPolicyReadinessCacheForTests(isTest) {
+    if (isTest)
+        sharedCache.clear();
+}
+async function loadFailClosed(port) {
+    try {
+        const parsed = parseReadiness(await port.readOfferPolicyV2Readiness());
+        return parsed ?? unavailable("readiness_contract_invalid");
+    }
+    catch {
+        return unavailable("readiness_rpc_unavailable");
+    }
+}
+function parseReadiness(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.contractVersion !== OFFER_POLICY_V2_READINESS_CONTRACT ||
+        typeof record.ready !== "boolean" ||
+        typeof record.checkedAt !== "string" ||
+        !Number.isFinite(Date.parse(record.checkedAt)) ||
+        !Array.isArray(record.reasons) ||
+        !record.reasons.every((reason) => typeof reason === "string"))
+        return null;
+    return {
+        contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+        ready: record.ready,
+        checkedAt: record.checkedAt,
+        reasons: record.reasons,
+    };
+}
+function unavailable(reason) {
+    return {
+        contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+        ready: false,
+        checkedAt: new Date(0).toISOString(),
+        reasons: [reason],
+    };
+}

package/dist/pricing/offerPolicySchemas.d.ts

@@ -0,0 +1,25 @@
+import { z } from "./validation.js";
+export declare const offerPolicyVersionSchema: z.ZodEnum<{
+    "commerce.offer-policy.v1": "commerce.offer-policy.v1";
+    "commerce.offer-policy.v2": "commerce.offer-policy.v2";
+}>;
+export declare const promotionEngineVersionSchema: z.ZodEnum<{
+    "promotion-engine.v1": "promotion-engine.v1";
+    "promotion-engine.v2": "promotion-engine.v2";
+}>;
+/** Client capability plus an opaque server-signed assignment. Never a version selector. */
+export declare const pricingPolicyRequestSchema: z.ZodObject<{
+    capability: z.ZodOptional<z.ZodLiteral<"commerce.offer-policy.v2">>;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const pricingPolicySnapshotSchema: z.ZodObject<{
+    offerPolicyVersion: z.ZodEnum<{
+        "commerce.offer-policy.v1": "commerce.offer-policy.v1";
+        "commerce.offer-policy.v2": "commerce.offer-policy.v2";
+    }>;
+    promotionEngineVersion: z.ZodEnum<{
+        "promotion-engine.v1": "promotion-engine.v1";
+        "promotion-engine.v2": "promotion-engine.v2";
+    }>;
+    pricingPolicyToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;

package/dist/pricing/offerPolicySchemas.js

@@ -0,0 +1,15 @@
+import { z } from "./validation.js";
+import { OFFER_POLICY_V1, OFFER_POLICY_V2, PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2, OFFER_POLICY_V2_CAPABILITY } from "./contracts/index.js";
+export const offerPolicyVersionSchema = z.enum([OFFER_POLICY_V1, OFFER_POLICY_V2]);
+export const promotionEngineVersionSchema = z.enum([PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2]);
+/** Client capability plus an opaque server-signed assignment. Never a version selector. */
+export const pricingPolicyRequestSchema = z.object({
+    capability: z.literal(OFFER_POLICY_V2_CAPABILITY).optional(),
+    token: z.string().trim().min(32).max(2048).optional(),
+}).strict();
+export const pricingPolicySnapshotSchema = z.object({
+    offerPolicyVersion: offerPolicyVersionSchema,
+    promotionEngineVersion: promotionEngineVersionSchema,
+    pricingPolicyToken: z.string().trim().min(32).max(2048).optional(),
+}).strict().refine((value) => (value.offerPolicyVersion === OFFER_POLICY_V1 && value.promotionEngineVersion === PROMOTION_ENGINE_V1) ||
+    (value.offerPolicyVersion === OFFER_POLICY_V2 && value.promotionEngineVersion === PROMOTION_ENGINE_V2), { message: "offer policy and promotion engine versions must be paired" });