@openlup/platform 0.17.0 → 0.18.0

package/dist/promotions/promotionClaims.js

@@ -0,0 +1,57 @@
+import { promotionRedemptionMap } from "./promoDataPort.js";
+import { parsePromotionClaimSweepCounts, } from "./promotionClaimSweepPort.js";
+const ACTIVE_SQL = "SELECT public.commerce_promotion_active_definitions() AS result";
+const COUNTS_SQL = "SELECT public.commerce_promotion_paid_order_counts($1::uuid) AS result";
+const REDEMPTIONS_SQL = "SELECT * FROM public.commerce_promotion_redemption_counts($1::uuid)";
+const DEVICE_SQL = "SELECT public.commerce_promotion_device_first_order_redeemed($1) AS result";
+const SWEEP_SQL = "SELECT public.commerce_sweep_stale_promotion_claims($1,$2,$3,$4) AS result";
+export function createPostgresCommercePromoDataPort(executor) {
+    return {
+        async listActivePromotions() {
+            const value = scalar(await executor.query(ACTIVE_SQL));
+            if (!Array.isArray(value))
+                throw new Error("promotions_list_invalid_response");
+            return value;
+        },
+        async countPaidOrders(clientId) {
+            const counts = paidCounts(scalar(await executor.query(COUNTS_SQL, [clientId])));
+            return counts.oneTime + counts.subscription;
+        },
+        async countPaidOrdersByMode(clientId) {
+            return paidCounts(scalar(await executor.query(COUNTS_SQL, [clientId])));
+        },
+        async redemptionCounts(clientId) {
+            return promotionRedemptionMap((await executor.query(REDEMPTIONS_SQL, [clientId])).rows);
+        },
+        async deviceFirstOrderRedeemed(visitorId) {
+            if (!visitorId?.trim())
+                return false;
+            return scalar(await executor.query(DEVICE_SQL, [visitorId])) === true;
+        },
+    };
+}
+export function createPostgresPromotionClaimSweepPort(executor) {
+    return {
+        async sweep(input) {
+            return parsePromotionClaimSweepCounts(scalar(await executor.query(SWEEP_SQL, [
+                input.now, input.limit, input.claimLeaseMinutes, input.graceMinutes,
+            ])));
+        },
+    };
+}
+function scalar(result) {
+    if (result.rows.length !== 1 || !("result" in result.rows[0])) {
+        throw new Error("promotion_claim_response_invalid");
+    }
+    return result.rows[0].result;
+}
+function paidCounts(value) {
+    const row = value && typeof value === "object" ? value : {};
+    const oneTime = Number(row.oneTime ?? -1);
+    const subscription = Number(row.subscription ?? -1);
+    if (!Number.isSafeInteger(oneTime) || oneTime < 0
+        || !Number.isSafeInteger(subscription) || subscription < 0) {
+        throw new Error("promotion_paid_order_counts_invalid_response");
+    }
+    return { oneTime, subscription };
+}

package/dist/promotions/promotionCodePreview.d.ts

@@ -0,0 +1,11 @@
+import type { PromotionCodePreviewRequest, PromotionCodePreviewResponse } from "./contracts/index.js";
+export declare const PROMOTION_ENGINE_VERSION: "promotion-engine.v2";
+export declare function createPromotionCodePreview({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }: {
+    minimumProductPayableMinor: number;
+}): {
+    generatePromotionCode: () => string;
+    normalizePromotionCode: (code: string) => string;
+    promotionPreviewProof: (input: PromotionCodePreviewRequest, secret: string) => string;
+    verifyPromotionPreviewProof: (input: PromotionCodePreviewRequest, proof: string, secret: string) => boolean;
+    previewPromotionCode: (input: PromotionCodePreviewRequest, secret: string) => PromotionCodePreviewResponse;
+};

package/dist/promotions/promotionCodePreview.js

@@ -0,0 +1,154 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+import { evaluatePromotionAdjustmentsV2, } from "@openlup/core/promo";
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const PROMOTION_ENGINE_VERSION = "promotion-engine.v2";
+export function createPromotionCodePreview({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }) {
+    function generatePromotionCode() {
+        const bytes = randomBytes(10);
+        let bits = 0;
+        let buffer = 0;
+        let code = "";
+        for (const byte of bytes) {
+            buffer = (buffer << 8) | byte;
+            bits += 8;
+            while (bits >= 5) {
+                bits -= 5;
+                code += CROCKFORD_BASE32[(buffer >>> bits) & 31];
+                buffer &= (1 << bits) - 1;
+            }
+        }
+        return code;
+    }
+    function normalizePromotionCode(code) {
+        return code.trim().toUpperCase();
+    }
+    function promotionPreviewProof(input, secret) {
+        assertPreviewSecret(secret);
+        assertSupportedPreviewBenefits(input);
+        return createHmac("sha256", secret).update(previewProofPayload(input)).digest("base64url");
+    }
+    function verifyPromotionPreviewProof(input, proof, secret) {
+        const expected = promotionPreviewProof(input, secret);
+        const expectedBytes = Buffer.from(expected);
+        const actualBytes = Buffer.from(proof);
+        return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+    }
+    function previewPromotionCode(input, secret) {
+        assertSupportedPreviewBenefits(input);
+        const eligible = input.context.referenceProductMinor >= input.minimumReferenceMinor;
+        const results = ["one_time", "subscription_initial"].map((scope) => {
+            const currentProductMinor = scope === "one_time"
+                ? input.context.oneTimeProductMinor
+                : input.context.subscriptionProductMinor;
+            const candidates = eligible
+                ? input.benefits
+                    .map((benefit) => toCandidate(benefit, input.scopes, currentProductMinor))
+                    .filter((candidate) => candidate !== null)
+                : [];
+            const result = evaluatePromotionAdjustmentsV2({
+                purchaseScope: scope,
+                referenceProductMinor: input.context.referenceProductMinor,
+                currentProductMinor,
+                shippingMinor: input.context.shippingMinor,
+                minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+            }, candidates);
+            return {
+                scope,
+                productPayableMinor: result.productPayableMinor,
+                shippingPayableMinor: result.shippingPayableMinor,
+                effectiveProductDiscountBps: result.effectiveProductDiscountBps,
+                winner: result.adjustments.some((adjustment) => adjustment.source === "code")
+                    ? "code"
+                    : "automatic",
+                floorApplied: result.adjustments.some((adjustment) => adjustment.floorApplied),
+                adjustments: result.adjustments.map((adjustment) => ({
+                    lane: adjustment.lane,
+                    kind: input.promotionEngineVersion === "promotion-engine.v1"
+                        && adjustment.promotionId === "preview-product"
+                        && input.benefits.some((benefit) => benefit.lane === "product" && benefit.kind === "percentage")
+                        ? "percentage"
+                        : adjustment.kind,
+                    amountOffMinor: adjustment.amountOffMinor,
+                    beforeMinor: adjustment.beforeMinor,
+                    afterMinor: adjustment.afterMinor,
+                })),
+            };
+        });
+        return {
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            promotionEngineVersion: input.promotionEngineVersion,
+            previewProof: promotionPreviewProof(input, secret),
+            results,
+        };
+    }
+    function previewProofPayload(input) {
+        return stableJson({
+            promotionEngineVersion: input.promotionEngineVersion,
+            minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+            minimumReferenceMinor: input.minimumReferenceMinor,
+            benefits: input.benefits,
+            scopes: input.scopes,
+            context: input.context,
+        });
+    }
+    function assertPreviewSecret(secret) {
+        if (Buffer.byteLength(secret, "utf8") < 32) {
+            throw new RangeError("promotion_preview_secret_too_short");
+        }
+    }
+    function assertSupportedPreviewBenefits(input) {
+        if (input.benefits.some((benefit) => "validationState" in benefit)) {
+            throw new RangeError("promotion_preview_unsupported_legacy_value");
+        }
+    }
+    function toCandidate(benefit, scopes, currentProductMinor) {
+        const base = {
+            promotionId: `preview-${benefit.lane}`,
+            codeId: "preview-code",
+            source: "code",
+            name: "Promotion code preview",
+            scopes,
+        };
+        if ("validationState" in benefit) {
+            throw new RangeError("promotion_preview_unsupported_legacy_value");
+        }
+        if (("valueBps" in benefit && benefit.valueBps === 0)
+            || ("valueMinor" in benefit && benefit.valueMinor === 0))
+            return null;
+        if (benefit.kind === "target_percentage")
+            return { ...base, ...benefit };
+        if (benefit.kind === "percentage" && benefit.lane === "product") {
+            const valueMinor = benefit.valueBps >= 10_000
+                ? currentProductMinor
+                : Number((BigInt(currentProductMinor) * BigInt(benefit.valueBps)) / 10000n);
+            return {
+                ...base,
+                lane: "product",
+                kind: "fixed_amount",
+                valueMinor,
+            };
+        }
+        if (benefit.kind === "percentage" && benefit.lane === "shipping" && benefit.valueBps >= 10_000) {
+            return { ...base, lane: "shipping", kind: "free_shipping" };
+        }
+        if (benefit.kind === "percentage")
+            return { ...base, ...benefit };
+        if (benefit.kind === "fixed_amount")
+            return { ...base, ...benefit };
+        return { ...base, ...benefit };
+    }
+    function stableJson(value) {
+        if (Array.isArray(value))
+            return `[${value.map(stableJson).join(",")}]`;
+        if (value && typeof value === "object") {
+            const record = value;
+            return `{${Object.keys(record)
+                .sort()
+                .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+                .join(",")}}`;
+        }
+        return JSON.stringify(value);
+    }
+    return { generatePromotionCode, normalizePromotionCode, promotionPreviewProof, verifyPromotionPreviewProof, previewPromotionCode };
+}

package/dist/promotions/promotionCodeQuotePort.d.ts

@@ -0,0 +1,25 @@
+import type { PromotionAdjustmentCandidate, PromotionPurchaseScope } from "@openlup/core/promo";
+import type { CommerceCodeRejection, CommerceCodeRejectionDetail } from "../pricing/index.js";
+export type ResolvedPromotionCodeCandidate = PromotionAdjustmentCandidate & {
+    codeRevision: number;
+    definitionFingerprint: string;
+    minimumReferenceMinor: number;
+    validTo: string | null;
+};
+export interface ResolvePromotionCodeQuoteInput {
+    codes: readonly string[];
+    clientId: string | null;
+    purchaseScope: PromotionPurchaseScope;
+    referenceProductMinor: number;
+    atTime: string;
+}
+export interface PromotionCodeQuoteResolution {
+    candidates: ResolvedPromotionCodeCandidate[];
+    codeRejections: CommerceCodeRejection[];
+    /** Additive v2 RPC detail; old RPC fallback returns an empty array. */
+    codeRejectionDetails: CommerceCodeRejectionDetail[];
+}
+/** Advisory quote read only. Capacity is authoritatively claimed by the order transaction. */
+export interface PromotionCodeQuotePort {
+    resolve(input: ResolvePromotionCodeQuoteInput): Promise<PromotionCodeQuoteResolution>;
+}

package/dist/promotions/promotionCodeQuotePort.js

@@ -0,0 +1 @@
+export {};

package/dist/promotions/promotionQuoteAcceptance.d.ts

@@ -0,0 +1,65 @@
+import type { ResolvedAcquisitionTerms } from "../pricing/index.js";
+import type { CommerceQuote } from "../pricing/index.js";
+import type { PromotionAcceptanceTelemetry } from "./promotionAcceptanceTelemetry.js";
+import { type PromotionQuoteMismatchField } from "./promotionQuoteBinding.js";
+export declare const PROMOTION_ACCEPTANCE_MAX_TTL_MS: number;
+export declare const PROMOTION_ACCEPTANCE_CLOCK_SKEW_MS = 60000;
+export interface PromotionAcceptanceKeyring {
+    current: string;
+    previous?: string | null;
+}
+export type PromotionAcceptanceDiagnostic = {
+    accepted: boolean;
+    reason: PromotionAcceptanceTelemetry["reason"];
+    keySlot: PromotionAcceptanceTelemetry["keySlot"];
+    expiryBucket: PromotionAcceptanceTelemetry["expiryBucket"];
+    /** Present only on `quote_mismatch`: which money section diverged. */
+    mismatchField?: PromotionQuoteMismatchField;
+};
+export declare function createPromotionQuoteAcceptance<Request extends {
+    promoCodes: string[];
+}>({ projectRequest }: {
+    projectRequest(request: Request): unknown;
+}): {
+    issuePromotionQuoteAcceptance: (input: {
+        request: Request;
+        quote: CommerceQuote;
+        acquisitionTerms?: ResolvedAcquisitionTerms;
+        keyring: PromotionAcceptanceKeyring;
+        now?: Date;
+    }) => string | null;
+    issuePromotionQuoteAcceptanceWithOutcome: (input: {
+        request: Request;
+        quote: CommerceQuote;
+        acquisitionTerms?: ResolvedAcquisitionTerms;
+        keyring: PromotionAcceptanceKeyring;
+        now?: Date;
+    }) => {
+        token: string | null;
+        diagnostic: PromotionAcceptanceDiagnostic;
+    };
+    verifyPromotionQuoteAcceptance: (input: {
+        token: string;
+        request: Request;
+        quote: CommerceQuote;
+        acquisitionTerms?: ResolvedAcquisitionTerms;
+        expectedTotal: {
+            amountMinor: number;
+            currency: string;
+        };
+        keyring: PromotionAcceptanceKeyring;
+        now?: Date;
+    }) => boolean;
+    verifyPromotionQuoteAcceptanceWithOutcome: (input: {
+        token: string;
+        request: Request;
+        quote: CommerceQuote;
+        acquisitionTerms?: ResolvedAcquisitionTerms;
+        expectedTotal: {
+            amountMinor: number;
+            currency: string;
+        };
+        keyring: PromotionAcceptanceKeyring;
+        now?: Date;
+    }) => PromotionAcceptanceDiagnostic;
+};

package/dist/promotions/promotionQuoteAcceptance.js

@@ -0,0 +1,202 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { projectPromotionQuoteMoney, promotionQuoteMoneySections, PROMOTION_QUOTE_MONEY_SECTIONS, stableJson, } from "./promotionQuoteBinding.js";
+export const PROMOTION_ACCEPTANCE_MAX_TTL_MS = 72 * 60 * 60 * 1_000;
+export const PROMOTION_ACCEPTANCE_CLOCK_SKEW_MS = 60_000;
+const payloadSchema = z.object({
+    v: z.literal(1),
+    kid: z.string().regex(/^[0-9a-f]{16}$/),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().positive(),
+    engine: z.literal("promotion-engine.v2"),
+    requestBinding: z.string().regex(/^[0-9a-f]{64}$/),
+    codeBinding: z.string().regex(/^[0-9a-f]{64}$/),
+    quoteBinding: z.string().regex(/^[0-9a-f]{64}$/),
+    // Legacy payloads still parse, but their whole-quote binding is rejected.
+    // Quote refresh issues a new money-bound token; missing sections report other.
+    sectionBindings: z.object(Object.fromEntries(PROMOTION_QUOTE_MONEY_SECTIONS
+        .map((section) => [section, z.string().regex(/^[0-9a-f]{64}$/)]))).strict().optional(),
+    totalMinor: z.number().int().nonnegative(),
+    currency: z.string().length(3),
+}).strict();
+export function createPromotionQuoteAcceptance({ projectRequest }) {
+    function issuePromotionQuoteAcceptance(input) {
+        return issuePromotionQuoteAcceptanceWithOutcome(input).token;
+    }
+    function issuePromotionQuoteAcceptanceWithOutcome(input) {
+        const evidence = v2Discounts(input.quote);
+        if (evidence.length === 0 && !input.acquisitionTerms)
+            return {
+                token: null,
+                diagnostic: rejected("no_v2_adjustment"),
+            };
+        assertSecret(input.keyring.current);
+        const nowMs = (input.now ?? new Date()).getTime();
+        const codeExpiry = Math.min(...evidence.map((discount) => discount.promotionCodeValidTo ? Date.parse(discount.promotionCodeValidTo) : Number.POSITIVE_INFINITY));
+        const exp = Math.min(nowMs + PROMOTION_ACCEPTANCE_MAX_TTL_MS, codeExpiry);
+        if (!Number.isFinite(exp) || exp <= nowMs)
+            return {
+                token: null,
+                diagnostic: rejected("ttl_invalid"),
+            };
+        const payload = payloadSchema.parse({
+            v: 1,
+            kid: keyId(input.keyring.current),
+            iat: nowMs,
+            exp,
+            engine: "promotion-engine.v2",
+            requestBinding: requestBinding(input.request, input.keyring.current),
+            codeBinding: codeBinding(input.request.promoCodes, input.keyring.current),
+            quoteBinding: quoteBinding(input.quote, input.keyring.current, input.acquisitionTerms),
+            sectionBindings: sectionBindings(input.quote, input.keyring.current, input.acquisitionTerms),
+            totalMinor: input.quote.totalGross.amountMinor,
+            currency: input.quote.totalGross.currency,
+        });
+        const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+        return {
+            token: `${encoded}.${sign(encoded, input.keyring.current)}`,
+            diagnostic: {
+                accepted: true,
+                reason: "issued",
+                keySlot: "current",
+                expiryBucket: expiryBucket(exp, nowMs),
+            },
+        };
+    }
+    function verifyPromotionQuoteAcceptance(input) {
+        return verifyPromotionQuoteAcceptanceWithOutcome(input).accepted;
+    }
+    function verifyPromotionQuoteAcceptanceWithOutcome(input) {
+        const verified = verifyEnvelopeWithOutcome(input.token, input.keyring, input.now ?? new Date());
+        if (verified.verified === false)
+            return verified.diagnostic;
+        const { payload, secret } = verified;
+        const base = { keySlot: verified.keySlot, expiryBucket: verified.expiryBucket };
+        if (payload.requestBinding !== requestBinding(input.request, secret)) {
+            return { accepted: false, reason: "request_mismatch", ...base };
+        }
+        if (payload.codeBinding !== codeBinding(input.request.promoCodes, secret)) {
+            return { accepted: false, reason: "code_mismatch", ...base };
+        }
+        if (payload.quoteBinding !== quoteBinding(input.quote, secret, input.acquisitionTerms)) {
+            const mismatchField = namedMismatchField(payload.sectionBindings, input.quote, secret, input.acquisitionTerms);
+            return { accepted: false, reason: "quote_mismatch", mismatchField, ...base };
+        }
+        if (payload.totalMinor !== input.expectedTotal.amountMinor) {
+            return { accepted: false, reason: "total_mismatch", ...base };
+        }
+        if (payload.currency !== input.expectedTotal.currency) {
+            return { accepted: false, reason: "currency_mismatch", ...base };
+        }
+        if (v2Discounts(input.quote).length === 0 && !input.acquisitionTerms) {
+            return { accepted: false, reason: "no_v2_adjustment_in_quote", ...base };
+        }
+        return { accepted: true, reason: "accepted", ...base };
+    }
+    function verifyEnvelopeWithOutcome(token, keyring, now) {
+        const [encoded, signature, extra] = token.split(".");
+        if (!encoded || !signature || extra || encoded.length > 8_192 || signature.length !== 43) {
+            return { verified: false, diagnostic: rejected("malformed") };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        }
+        catch {
+            return { verified: false, diagnostic: rejected("malformed") };
+        }
+        const payload = payloadSchema.safeParse(parsed);
+        if (!payload.success)
+            return { verified: false, diagnostic: rejected("malformed") };
+        const candidates = [
+            { slot: "current", secret: keyring.current },
+            { slot: "previous", secret: keyring.previous },
+        ].filter((candidate) => typeof candidate.secret === "string" && candidate.secret.length >= 32);
+        const candidate = candidates.find((value) => keyId(value.secret) === payload.data.kid);
+        if (!candidate)
+            return { verified: false, diagnostic: rejected("unknown_key") };
+        if (!safeEqual(signature, sign(encoded, candidate.secret))) {
+            return { verified: false, diagnostic: rejected("signature_invalid") };
+        }
+        const nowMs = now.getTime();
+        const safeBase = { keySlot: candidate.slot, expiryBucket: expiryBucket(payload.data.exp, nowMs) };
+        if (payload.data.exp <= payload.data.iat ||
+            payload.data.exp - payload.data.iat > PROMOTION_ACCEPTANCE_MAX_TTL_MS) {
+            return { verified: false, diagnostic: { accepted: false, reason: "ttl_invalid", ...safeBase } };
+        }
+        if (payload.data.iat > nowMs + PROMOTION_ACCEPTANCE_CLOCK_SKEW_MS) {
+            return { verified: false, diagnostic: { accepted: false, reason: "not_yet_valid", ...safeBase } };
+        }
+        if (nowMs >= payload.data.exp) {
+            return { verified: false, diagnostic: { accepted: false, reason: "expired", ...safeBase } };
+        }
+        return {
+            verified: true,
+            payload: payload.data,
+            secret: candidate.secret,
+            keySlot: candidate.slot,
+            expiryBucket: expiryBucket(payload.data.exp, nowMs),
+        };
+    }
+    function rejected(reason) {
+        return { accepted: false, reason, keySlot: "none", expiryBucket: "none" };
+    }
+    function expiryBucket(exp, now) {
+        const remaining = exp - now;
+        if (remaining <= 0)
+            return "expired";
+        if (remaining < 60 * 60 * 1_000)
+            return "lt_1h";
+        if (remaining < 24 * 60 * 60 * 1_000)
+            return "1_24h";
+        return "24_72h";
+    }
+    function v2Discounts(quote) {
+        return quote.discounts.filter((discount) => discount.promotionEngineVersion === "promotion-engine.v2" &&
+            discount.reasonCode === "promotion_code_v2");
+    }
+    function requestBinding(request, secret) {
+        return hmac(secret, stableJson(projectRequest(request)));
+    }
+    function codeBinding(codes, secret) {
+        return hmac(secret, stableJson([...new Set(codes.map((code) => code.trim().toUpperCase()))].sort()));
+    }
+    function quoteBinding(quote, secret, acquisitionTerms) {
+        return hmac(secret, stableJson(projectPromotionQuoteMoney(quote, acquisitionTerms)));
+    }
+    function sectionBindings(quote, secret, acquisitionTerms) {
+        const sections = promotionQuoteMoneySections(quote, acquisitionTerms);
+        return Object.fromEntries(PROMOTION_QUOTE_MONEY_SECTIONS
+            .map((section) => [section, hmac(secret, stableJson(sections[section]))]));
+    }
+    /**
+     * The verifier holds only the issuer's HMACs, never the issued quote, so the
+     * differing section is found by comparing per-section hashes in a fixed order.
+     */
+    function namedMismatchField(issued, quote, secret, acquisitionTerms) {
+        if (!issued)
+            return "other";
+        const verified = sectionBindings(quote, secret, acquisitionTerms);
+        return PROMOTION_QUOTE_MONEY_SECTIONS
+            .find((section) => issued[section] !== verified[section]) ?? "other";
+    }
+    function keyId(secret) {
+        return createHash("sha256").update(secret).digest("hex").slice(0, 16);
+    }
+    function hmac(secret, value) {
+        return createHmac("sha256", secret).update(value).digest("hex");
+    }
+    function sign(encoded, secret) {
+        return createHmac("sha256", secret).update(encoded).digest("base64url");
+    }
+    function safeEqual(left, right) {
+        const a = Buffer.from(left);
+        const b = Buffer.from(right);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    function assertSecret(secret) {
+        if (secret.length < 32)
+            throw new Error("promotion_acceptance_secret_invalid");
+    }
+    return { issuePromotionQuoteAcceptance, issuePromotionQuoteAcceptanceWithOutcome, verifyPromotionQuoteAcceptance, verifyPromotionQuoteAcceptanceWithOutcome };
+}

package/dist/promotions/promotionQuoteBinding.d.ts

@@ -0,0 +1,71 @@
+import { type ResolvedAcquisitionTerms } from "../pricing/index.js";
+import type { CommerceMoney, CommerceQuote, CommerceQuoteDiscount } from "../pricing/index.js";
+/**
+ * The canonical money projection an acceptance token binds.
+ *
+ * ⛔ The token protects **what the customer pays**, never how it was presented
+ * or which server-only evidence produced it. Everything outside this projection
+ * is deliberately unbound: `label`, `reasonCode`, `customerSemantic`, `code`,
+ * `promotionCodeRevision`, `promotionCodeScopes`, `promotionMinimumReferenceMinor`,
+ * `promotionCodeValidTo`, `floorApplied`, `context`, `codeRejections`,
+ * `codeRejectionDetails`, `pricingComponents` and `catalogFacts`. Those differ
+ * legitimately between the two surfaces that share one token — the public quote
+ * route signs the contract-parsed public projection while the checkout guard
+ * verifies the raw server-authoritative quote, which carries `catalogFacts`
+ * (with a per-request `atTime`) that the public projection strips — so binding
+ * them turned every strict-path v2 code checkout into a permanent rejection.
+ *
+ * What stays bound is every amount and every discount identity: change a price,
+ * a quantity, a tax split, shipping, a discount amount, which promotion granted
+ * it, or what it applies to, and the token stops verifying.
+ */
+export interface PromotionQuoteMoneyLine {
+    sku: string;
+    quantity: number;
+    unitPriceGross: CommerceMoney;
+    lineSubtotalGross: CommerceMoney;
+    tax: {
+        vatRateBps: number;
+        netAmount: CommerceMoney;
+        vatAmount: CommerceMoney;
+        grossAmount: CommerceMoney;
+    };
+}
+export interface PromotionQuoteMoneyDiscount {
+    promotionId: string;
+    appliesTo: CommerceQuoteDiscount["appliesTo"];
+    amountOffMinor: number;
+    promotionCodeId: string | null;
+    promotionDefinitionFingerprint: string | null;
+    promotionBenefitKind: NonNullable<CommerceQuoteDiscount["promotionBenefitKind"]> | null;
+    promotionBenefitValueBps: number | null;
+    promotionBenefitValueMinor: number | null;
+}
+export interface PromotionQuoteMoneyProjection {
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    currency: string;
+    totalGross: CommerceMoney;
+    netTotal: CommerceMoney;
+    taxTotal: CommerceMoney;
+    subtotalGross: CommerceMoney;
+    discountTotalGross: CommerceMoney;
+    shippingGross: CommerceMoney | null;
+    shippingDiscountGross: CommerceMoney | null;
+    lines: PromotionQuoteMoneyLine[];
+    discounts: PromotionQuoteMoneyDiscount[];
+}
+/** The five sections the token hashes separately so a mismatch can name itself. */
+export declare const PROMOTION_QUOTE_MONEY_SECTIONS: readonly ["lines", "discounts", "shipping", "totals", "currency"];
+export type PromotionQuoteMoneySection = (typeof PROMOTION_QUOTE_MONEY_SECTIONS)[number];
+/** `other` is the honest answer for a token minted before section bindings existed. */
+export declare const PROMOTION_QUOTE_MISMATCH_FIELDS: readonly ["lines", "discounts", "shipping", "totals", "currency", "other"];
+export type PromotionQuoteMismatchField = (typeof PROMOTION_QUOTE_MISMATCH_FIELDS)[number];
+/**
+ * Discount order is preserved: the promotion engine emits its lanes
+ * deterministically, so a reordering is a real evaluation difference.
+ */
+export declare function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerms?: ResolvedAcquisitionTerms): PromotionQuoteMoneyProjection;
+/** Same projection, partitioned. The union of these five sections is the whole projection. */
+export declare function promotionQuoteMoneySections(quote: CommerceQuote, acquisitionTerms?: ResolvedAcquisitionTerms): Record<PromotionQuoteMoneySection, unknown>;
+/** Key-sorted, `undefined`-dropping JSON. Every acceptance binding hashes this shape. */
+export declare function stableJson(value: unknown): string;