@openlup/platform 0.17.0 → 0.19.0

package/dist/promotions/promotionQuoteBinding.js

@@ -0,0 +1,87 @@
+import { acquisitionQuoteBinding } from "../pricing/index.js";
+/** The five sections the token hashes separately so a mismatch can name itself. */
+export const PROMOTION_QUOTE_MONEY_SECTIONS = [
+    "lines",
+    "discounts",
+    "shipping",
+    "totals",
+    "currency",
+];
+/** `other` is the honest answer for a token minted before section bindings existed. */
+export const PROMOTION_QUOTE_MISMATCH_FIELDS = [
+    ...PROMOTION_QUOTE_MONEY_SECTIONS,
+    "other",
+];
+/**
+ * Discount order is preserved: the promotion engine emits its lanes
+ * deterministically, so a reordering is a real evaluation difference.
+ */
+export function projectPromotionQuoteMoney(quote, acquisitionTerms, shippingTerms) {
+    return {
+        ...acquisitionQuoteBinding(acquisitionTerms),
+        currency: quote.currency,
+        totalGross: quote.totalGross,
+        netTotal: quote.netTotal,
+        taxTotal: quote.taxTotal,
+        subtotalGross: quote.subtotalGross,
+        discountTotalGross: quote.discountTotalGross,
+        shippingGross: quote.shippingGross ?? null,
+        shippingDiscountGross: quote.shippingDiscountGross ?? null,
+        ...(shippingTerms ? { shippingTerms } : {}),
+        lines: quote.lines.map((line) => ({
+            sku: line.sku,
+            quantity: line.quantity,
+            unitPriceGross: line.unitPriceGross,
+            lineSubtotalGross: line.lineSubtotalGross,
+            tax: {
+                vatRateBps: line.tax.vatRateBps,
+                netAmount: line.tax.netAmount,
+                vatAmount: line.tax.vatAmount,
+                grossAmount: line.tax.grossAmount,
+            },
+        })),
+        discounts: quote.discounts.map((discount) => ({
+            promotionId: discount.promotionId,
+            appliesTo: discount.appliesTo,
+            amountOffMinor: discount.amountOffMinor,
+            promotionCodeId: discount.promotionCodeId ?? null,
+            promotionDefinitionFingerprint: discount.promotionDefinitionFingerprint ?? null,
+            promotionBenefitKind: discount.promotionBenefitKind ?? null,
+            promotionBenefitValueBps: discount.promotionBenefitValueBps ?? null,
+            promotionBenefitValueMinor: discount.promotionBenefitValueMinor ?? null,
+        })),
+    };
+}
+/** Same projection, partitioned. The union of these five sections is the whole projection. */
+export function promotionQuoteMoneySections(quote, acquisitionTerms, shippingTerms) {
+    const money = projectPromotionQuoteMoney(quote, acquisitionTerms, shippingTerms);
+    return {
+        lines: money.lines,
+        discounts: money.discounts,
+        shipping: {
+            shippingGross: money.shippingGross,
+            shippingDiscountGross: money.shippingDiscountGross,
+            ...(money.shippingTerms ? { shippingTerms: money.shippingTerms } : {}),
+        },
+        totals: {
+            ...acquisitionQuoteBinding(money.acquisitionTerms),
+            totalGross: money.totalGross,
+            netTotal: money.netTotal,
+            taxTotal: money.taxTotal,
+            subtotalGross: money.subtotalGross,
+            discountTotalGross: money.discountTotalGross,
+        },
+        currency: money.currency,
+    };
+}
+/** Key-sorted, `undefined`-dropping JSON. Every acceptance binding hashes this shape. */
+export function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value).filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/promotions/quoteAcquisitionBinding.d.ts

@@ -0,0 +1,6 @@
+import type { PromotionRow } from "@openlup/core/promo";
+import type { AcquisitionFinancialPolicy } from "../pricing/index.js";
+export interface QuoteAcquisitionBinding<Request = unknown> {
+    financialPolicy: AcquisitionFinancialPolicy<PromotionRow>;
+    capability(request: Request): unknown;
+}

package/dist/promotions/quoteAcquisitionBinding.js

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

package/dist/promotions/quoteAutomaticPromotions.d.ts

@@ -0,0 +1,26 @@
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import type { CreateQuoteOptions } from "../pricing/index.js";
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+import type { createQuotePromoDiscounts, QuoteDiscountResult } from "./quotePromoDiscounts.js";
+import type { createQuotePromotionV2 } from "./quotePromotionV2.js";
+export declare function createQuoteAutomaticPromotions<Request extends CreateQuoteRequest & {
+    visitorId?: string;
+}>({ resolveEmailEligibility, evaluateOrderTotalDiscounts, evaluateAutomaticPromotionV2, legacyPromotionDataPort, acquisition }: {
+    acquisition?: QuoteAcquisitionBinding<Request>;
+    resolveEmailEligibility(request: Request): boolean;
+    evaluateOrderTotalDiscounts: ReturnType<typeof createQuotePromoDiscounts>["evaluateOrderTotalDiscounts"];
+    evaluateAutomaticPromotionV2: ReturnType<typeof createQuotePromotionV2>["evaluateAutomaticPromotionV2"];
+    legacyPromotionDataPort: ReturnType<typeof createQuotePromotionV2>["legacyPromotionDataPort"];
+}): {
+    resolveAutomaticQuotePromotions: (input: {
+        promoDataPort?: CommercePromoDataPort;
+        request: Request;
+        options?: CreateQuoteOptions;
+        regionCode: string;
+        referenceProductMinor: number;
+        subtotalGrossMinor: number;
+        shippingGrossMinor: number;
+        atTime: string;
+    }) => Promise<QuoteDiscountResult>;
+};

package/dist/promotions/quoteAutomaticPromotions.js

@@ -0,0 +1,60 @@
+import { selectAcquisitionTerms, assertAcquisitionTermsCapability, ACQUISITION_TERMS_CAPABILITY } from "../pricing/index.js";
+import { PROMOTION_ENGINE_V2 } from "../pricing/index.js";
+export function createQuoteAutomaticPromotions({ resolveEmailEligibility, evaluateOrderTotalDiscounts, evaluateAutomaticPromotionV2, legacyPromotionDataPort, acquisition }) {
+    async function resolveAutomaticQuotePromotions(input) {
+        if (!input.promoDataPort)
+            return { discounts: [], codeRejections: [] };
+        let promoDataPort = input.promoDataPort;
+        let selection = null;
+        let acquisitionCapability;
+        if (acquisition) {
+            const clientId = input.options?.clientId ?? null;
+            const [paid, allRows] = await Promise.all([
+                clientId ? promoDataPort.countPaidOrdersByMode(clientId) : Promise.resolve({ oneTime: 0, subscription: 0 }),
+                promoDataPort.listActivePromotions(),
+            ]);
+            const existingSubscriber = input.request.mode === "subscription" && paid.subscription > 0;
+            const rows = existingSubscriber ? allRows.filter((row) => !acquisition.financialPolicy.facts(row).metadataPresent && row.eligibility.first_subscription_purchase !== true) : allRows;
+            promoDataPort = { ...promoDataPort, listActivePromotions: async () => rows, countPaidOrdersByMode: async () => paid };
+            selection = input.request.mode === "subscription" && !existingSubscriber
+                ? selectAcquisitionTerms(rows, input.atTime, input.regionCode, acquisition.financialPolicy) : null;
+            acquisitionCapability = acquisition.capability(input.request);
+            assertAcquisitionTermsCapability(selection, acquisitionCapability, input.options?.pricingPolicy?.promotionEngineVersion);
+        }
+        const emailEligibilityConfirmed = resolveEmailEligibility(input.request);
+        if (input.options?.pricingPolicy?.promotionEngineVersion === PROMOTION_ENGINE_V2) {
+            return evaluateAutomaticPromotionV2({
+                promoDataPort,
+                clientId: input.options.clientId ?? null,
+                visitorId: input.request.visitorId ?? null,
+                mode: input.request.mode,
+                promoCodes: input.request.promoCodes,
+                regionCode: input.regionCode,
+                referenceProductMinor: input.referenceProductMinor,
+                currentProductMinor: input.subtotalGrossMinor,
+                shippingMinor: input.shippingGrossMinor,
+                atTime: input.atTime,
+                emailEligibilityConfirmed,
+                ...(acquisition ? { acquisitionCapability } : {}),
+            });
+        }
+        const pending = evaluateOrderTotalDiscounts({
+            promoDataPort: legacyPromotionDataPort(promoDataPort),
+            clientId: input.options?.clientId ?? null,
+            visitorId: input.request.visitorId ?? null,
+            mode: input.request.mode,
+            promoCodes: input.request.promoCodes,
+            regionCode: input.regionCode,
+            subtotalGrossMinor: input.subtotalGrossMinor,
+            shippingGrossMinor: input.shippingGrossMinor,
+            atTime: input.atTime,
+            emailEligibilityConfirmed,
+        });
+        if (!acquisition)
+            return pending;
+        const result = await pending;
+        return selection && acquisitionCapability === ACQUISITION_TERMS_CAPABILITY
+            ? { ...result, acquisitionTerms: selection.terms } : result;
+    }
+    return { resolveAutomaticQuotePromotions };
+}

package/dist/promotions/quotePromoDiscounts.d.ts

@@ -0,0 +1,36 @@
+import type { ResolvedAcquisitionTerms } from "../pricing/index.js";
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import type { CommerceCodeRejection, CommerceQuoteDiscount } from "../pricing/index.js";
+import type { PromotionRow } from "@openlup/core/promo";
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+export interface QuoteDiscountResult {
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    /** Applied discounts: order_total (clamped to subtotal) + at most one shipping discount. */
+    discounts: CommerceQuoteDiscount[];
+    /** Submitted coupon codes that produced no discount, with the reason. */
+    codeRejections: CommerceCodeRejection[];
+}
+export declare function createQuotePromoDiscounts({ promotionCustomerSemantic, acquisition }: {
+    acquisition?: Pick<QuoteAcquisitionBinding, "financialPolicy">;
+    promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"];
+}): {
+    evaluateOrderTotalDiscounts: (input: {
+        promoDataPort: CommercePromoDataPort;
+        clientId: string | null;
+        visitorId?: string | null;
+        mode: CreateQuoteRequest["mode"];
+        promoCodes: string[];
+        regionCode: string;
+        subtotalGrossMinor: number;
+        shippingGrossMinor?: number;
+        atTime: string;
+        /**
+         * True when a customer email drove eligibility resolution (the request carried
+         * `customerEligibilityContext.email`). Demotes the device-redemption guard to
+         * advisory so an email-eligible customer on a used device still gets the
+         * first-order price. See {@link PromoEvaluationCart.email_eligibility_confirmed}.
+         */
+        emailEligibilityConfirmed?: boolean;
+    }) => Promise<QuoteDiscountResult>;
+};

package/dist/promotions/quotePromoDiscounts.js

@@ -0,0 +1,146 @@
+import { filterAcquisitionPromotions } from "../pricing/index.js";
+import { evaluatePromos, promoEligibilityFailure } from "@openlup/core/promo";
+export function createQuotePromoDiscounts({ promotionCustomerSemantic, acquisition }) {
+    /**
+     * Evaluate active promotions for this cart and map them to quote discounts. Two lanes:
+     * `order_total` promos are clamped to the subtotal (so `discountTotal <= subtotal`), and
+     * a single `free_shipping` promo is emitted as an `appliesTo:"shipping"` discount clamped
+     * to `shippingGrossMinor` — it is NOT suppressed by an exclusive order-total promo and is
+     * NOT counted against the subtotal. Per-mode paid-order counts drive `first_subscription_purchase`
+     * and `first_onetime_purchase` independently; all counts are server-authoritative (resolved
+     * from the clientId, never client input), so eligibility cannot be forged.
+     */
+    async function evaluateOrderTotalDiscounts(input) {
+        if (input.subtotalGrossMinor <= 0)
+            return { discounts: [], codeRejections: [] };
+        const byMode = input.clientId
+            ? await input.promoDataPort.countPaidOrdersByMode(input.clientId)
+            : { oneTime: 0, subscription: 0 };
+        // Cap pre-filter: drop a promo that has reached its global or per-customer redemption
+        // limit BEFORE evaluation, so caps are enforced at quote time and a paid order is never
+        // failed on a cap. A per-customer cap can only be checked for an authenticated client.
+        const [allCandidates, redemptionCounts, deviceFirstOrderRedeemed] = await Promise.all([
+            input.promoDataPort.listActivePromotions(),
+            input.promoDataPort.redemptionCounts(input.clientId),
+            input.promoDataPort.deviceFirstOrderRedeemed(input.visitorId ?? null),
+        ]);
+        const customerCandidates = acquisition && input.mode === "subscription" && byMode.subscription > 0
+            ? allCandidates.filter((row) => !acquisition.financialPolicy.facts(row).metadataPresent && row.eligibility.first_subscription_purchase !== true)
+            : allCandidates;
+        const effectiveCandidates = acquisition && input.mode === "subscription"
+            ? filterAcquisitionPromotions(customerCandidates, input.atTime, input.regionCode, acquisition.financialPolicy) : customerCandidates;
+        const candidates = effectiveCandidates.filter((promo) => !capReached(promo, redemptionCounts.get(promo.id), input.clientId));
+        const cart = {
+            region_code: input.regionCode,
+            cart_mode: input.mode === "subscription" ? "subscription" : "one_time",
+            cart_subtotal_minor: input.subtotalGrossMinor,
+            shipping_amount_minor: input.shippingGrossMinor ?? 0,
+            client_orders_count: byMode.oneTime + byMode.subscription,
+            client_subscription_orders_count: byMode.subscription,
+            client_onetime_orders_count: byMode.oneTime,
+            device_first_order_redeemed: deviceFirstOrderRedeemed,
+            email_eligibility_confirmed: input.emailEligibilityConfirmed === true,
+            // The engine compares code literals. Preserve the customer's submitted spelling
+            // for the public rejection, but feed known legacy codes in their canonical
+            // spelling so eligibility and applied-discount matching are case-insensitive.
+            applied_codes: canonicalSubmittedCodes(input.promoCodes, allCandidates),
+        };
+        const applied = evaluatePromos({ cart, candidates, now: input.atTime });
+        const discounts = [];
+        let running = 0;
+        for (const promo of applied) {
+            const source = candidates.find((candidate) => candidate.id === promo.promotion_id);
+            const customerSemantic = source ? promotionCustomerSemantic(source) : undefined;
+            const isShipping = promo.discount_type === "free_shipping";
+            const cap = isShipping ? cart.shipping_amount_minor : input.subtotalGrossMinor - running;
+            if (cap <= 0) {
+                if (isShipping)
+                    continue;
+                break;
+            }
+            const amountOffMinor = Math.min(promo.amount_off_minor, cap);
+            if (amountOffMinor <= 0)
+                continue;
+            if (!isShipping)
+                running += amountOffMinor;
+            discounts.push({
+                promotionId: promo.promotion_id,
+                ...(promo.code ? { code: promo.code } : {}),
+                // Human-facing label preserves the promotion name instead of its reason code.
+                ...(promo.name ? { label: promo.name } : {}),
+                appliesTo: isShipping ? "shipping" : "order_total",
+                amountOffMinor,
+                reasonCode: promo.reason_code,
+                ...(customerSemantic ? { customerSemantic } : {}),
+            });
+        }
+        return {
+            discounts,
+            codeRejections: classifyRejections(input, cart, allCandidates, redemptionCounts, discounts),
+        };
+    }
+    /**
+     * For each submitted coupon code that produced no discount, classify why. Uses the
+     * pre-cap candidate set so an exhausted per-customer cap reads as `already_used` rather
+     * than `not_recognized`. An eligible code that was merely outranked by a larger promo
+     * is a neutral `better_price_exists`: it was not applied because the customer already
+     * has an equally good or better automatic price. Applied shipping-code discounts count
+     * as applied too.
+     */
+    function classifyRejections(input, cart, allCandidates, redemptionCounts, discounts) {
+        const rejections = [];
+        for (const code of input.promoCodes) {
+            const promo = resolveSubmittedCoupon(code, allCandidates);
+            if (!promo) {
+                rejections.push({ code, reason: "not_recognized" });
+                continue;
+            }
+            // A legacy literal may be bound to more than one promotion/lane. A shipping
+            // benefit can legitimately apply even when the first matching product row
+            // fails scope, so the visible applied discount always wins over rejection.
+            if (discounts.some((discount) => sameCode(discount.code, code) || sameCode(discount.code, promo.code))) {
+                continue;
+            }
+            if (capReached(promo, redemptionCounts.get(promo.id), input.clientId)) {
+                rejections.push({ code, reason: "already_used" });
+                continue;
+            }
+            const failure = promoEligibilityFailure(promo, cart, input.atTime);
+            if (failure)
+                rejections.push({ code, reason: failure });
+            else if (!discounts.some((discount) => discount.code === promo.code)) {
+                rejections.push({ code, reason: "better_price_exists" });
+            }
+        }
+        return rejections;
+    }
+    function canonicalSubmittedCodes(codes, candidates) {
+        return codes.map((code) => resolveSubmittedCoupon(code, candidates)?.code ?? code);
+    }
+    /**
+     * Legacy permits normalized-code collisions. Preserve its exact-literal
+     * matching first; case-insensitive recovery is safe only for one identity.
+     */
+    function resolveSubmittedCoupon(code, candidates) {
+        const couponCandidates = candidates.filter((promo) => promo.trigger_type === "coupon_code" && promo.code !== null);
+        const exact = couponCandidates.find((promo) => promo.code === code);
+        if (exact)
+            return exact;
+        const normalized = couponCandidates.filter((promo) => sameCode(promo.code, code));
+        return normalized.length === 1 ? normalized[0] : undefined;
+    }
+    function sameCode(left, right) {
+        return typeof left === "string" && typeof right === "string" &&
+            left.trim().toUpperCase() === right.trim().toUpperCase();
+    }
+    function capReached(promo, counts, clientId) {
+        const { global, perCustomer } = counts ?? { global: 0, perCustomer: 0 };
+        if (promo.redemption_limit_global != null && global >= promo.redemption_limit_global)
+            return true;
+        if (clientId && promo.redemption_limit_per_customer != null && perCustomer >= promo.redemption_limit_per_customer) {
+            return true;
+        }
+        return false;
+    }
+    return { evaluateOrderTotalDiscounts };
+}

package/dist/promotions/quotePromotionCodeAdjustments.d.ts

@@ -0,0 +1,27 @@
+import type { PromotionCodeRejectionReason } from "@openlup/core/promo";
+import type { CommerceCodeRejection, CommerceCodeRejectionDetail, CommerceCodeRejectionReason, CommerceQuoteDiscount } from "../pricing/index.js";
+import type { PromotionCodeQuotePort } from "./promotionCodeQuotePort.js";
+export interface ApplyPromotionCodesV2Input {
+    port?: PromotionCodeQuotePort;
+    preserveLegacyDiscountsWhenNoCandidates?: boolean;
+    clientId: string | null;
+    mode: "one_time" | "subscription";
+    promoCodes: readonly string[];
+    referenceProductMinor: number;
+    subtotalGrossMinor: number;
+    shippingGrossMinor: number;
+    discounts: CommerceQuoteDiscount[];
+    codeRejections: CommerceCodeRejection[];
+    codeRejectionDetails?: CommerceCodeRejectionDetail[];
+    atTime: string;
+}
+export declare function createQuotePromotionCodeAdjustments({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }: {
+    minimumProductPayableMinor: number;
+}): {
+    applyPromotionCodesV2: (input: ApplyPromotionCodesV2Input) => Promise<{
+        discounts: CommerceQuoteDiscount[];
+        codeRejections: CommerceCodeRejection[];
+        codeRejectionDetails: CommerceCodeRejectionDetail[];
+    }>;
+    mapEngineRejectionReason: (reason: PromotionCodeRejectionReason) => CommerceCodeRejectionReason;
+};

package/dist/promotions/quotePromotionCodeAdjustments.js

@@ -0,0 +1,223 @@
+import { evaluatePromotionAdjustmentsV2 } from "@openlup/core/promo";
+export function createQuotePromotionCodeAdjustments({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }) {
+    async function applyPromotionCodesV2(input) {
+        const submittedV2Codes = firstSubmittedCodes(input.promoCodes);
+        if (!input.port || submittedV2Codes.length === 0) {
+            return {
+                discounts: input.discounts,
+                codeRejections: input.codeRejections,
+                codeRejectionDetails: input.codeRejectionDetails ?? [],
+            };
+        }
+        const firstSubmittedByIdentity = new Map(submittedV2Codes.map((code) => [normalize(code), code]));
+        const resolution = await input.port.resolve({
+            codes: submittedV2Codes,
+            clientId: input.clientId,
+            purchaseScope: input.mode === "subscription" ? "subscription_initial" : "one_time",
+            referenceProductMinor: input.referenceProductMinor,
+            atTime: input.atTime,
+        });
+        if (resolution.candidates.length === 0) {
+            const discounts = input.preserveLegacyDiscountsWhenNoCandidates
+                ? input.discounts
+                : reduceProvisionalLegacyDiscounts(input.discounts, firstSubmittedByIdentity);
+            const appliedLegacyCodes = new Set(discounts.flatMap((discount) => discount.code ? [normalize(discount.code)] : []));
+            const codeRejections = dedupeRejections([
+                ...input.codeRejections,
+                ...resolution.codeRejections,
+            ], firstSubmittedByIdentity, input.codeRejections.length).filter((rejection) => !appliedLegacyCodes.has(normalize(rejection.code)));
+            return {
+                discounts: input.preserveLegacyDiscountsWhenNoCandidates
+                    ? discounts
+                    : orderSubmittedCodeSlots(projectSubmittedCodeSpelling(discounts, firstSubmittedByIdentity), firstSubmittedByIdentity),
+                codeRejections,
+                codeRejectionDetails: dedupeRejectionDetails([
+                    ...selectedRejectionDetails(input.codeRejectionDetails ?? [], input.codeRejections, codeRejections),
+                    ...selectedRejectionDetails(resolution.codeRejectionDetails, resolution.codeRejections, codeRejections),
+                ], firstSubmittedByIdentity),
+            };
+        }
+        const provisionalLegacyDiscounts = reduceProvisionalLegacyDiscounts(input.discounts, firstSubmittedByIdentity);
+        const appliedLegacyCodes = new Set(provisionalLegacyDiscounts.flatMap((discount) => discount.code ? [normalize(discount.code)] : []));
+        const result = evaluatePromotionAdjustmentsV2(adjustmentContext(input, provisionalLegacyDiscounts), resolution.candidates);
+        const byAdjustmentIdentity = new Map(resolution.candidates.map((candidate) => [
+            `${candidate.promotionId}:${candidate.codeId}`,
+            candidate,
+        ]));
+        const replacedLegacyLanes = new Set();
+        const effectiveAdjustments = result.adjustments.flatMap((adjustment) => {
+            const candidate = adjustment.codeId
+                ? byAdjustmentIdentity.get(`${adjustment.promotionId}:${adjustment.codeId}`)
+                : undefined;
+            if (!candidate || candidate.source !== "code" || !candidate.code) {
+                throw new Error("promotion_code_quote_candidate_identity_missing");
+            }
+            const appliesTo = adjustment.lane === "shipping" ? "shipping" : "order_total";
+            const identity = normalize(candidate.code);
+            const matchingLegacy = provisionalLegacyDiscounts.filter((discount) => discount.appliesTo === appliesTo && discount.code && normalize(discount.code) === identity);
+            if (matchingLegacy.length === 0)
+                return [{ adjustment, candidate }];
+            // Re-score without the matching provisional legacy identity and retain the
+            // single adjustment that gives the customer the lower lane payable.
+            const withoutMatchingLegacy = provisionalLegacyDiscounts.filter((discount) => !(discount.appliesTo === appliesTo && discount.code && normalize(discount.code) === identity));
+            const replacement = evaluatePromotionAdjustmentsV2(adjustmentContext(input, withoutMatchingLegacy), [candidate]).adjustments[0];
+            const legacyAmount = matchingLegacy.reduce((sum, discount) => sum + discount.amountOffMinor, 0);
+            if (!replacement || replacement.amountOffMinor < legacyAmount)
+                return [];
+            replacedLegacyLanes.add(`${identity}:${appliesTo}`);
+            return [{ adjustment: replacement, candidate }];
+        });
+        const retainedDiscounts = projectSubmittedCodeSpelling(provisionalLegacyDiscounts.filter((discount) => !(discount.code && replacedLegacyLanes.has(`${normalize(discount.code)}:${discount.appliesTo}`))), firstSubmittedByIdentity);
+        const v2Discounts = effectiveAdjustments.map(({ adjustment, candidate }) => ({
+            promotionId: adjustment.promotionId,
+            code: firstSubmittedByIdentity.get(normalize(candidate.code)) ?? candidate.code,
+            label: adjustment.name,
+            appliesTo: adjustment.lane === "shipping" ? "shipping" : "order_total",
+            amountOffMinor: adjustment.amountOffMinor,
+            reasonCode: "promotion_code_v2",
+            promotionEngineVersion: "promotion-engine.v2",
+            promotionCodeId: candidate.codeId,
+            promotionCodeRevision: candidate.codeRevision,
+            promotionDefinitionFingerprint: candidate.definitionFingerprint,
+            promotionCodeScopes: [...candidate.scopes],
+            promotionMinimumReferenceMinor: candidate.minimumReferenceMinor,
+            promotionCodeValidTo: candidate.validTo,
+            promotionBenefitKind: candidate.kind,
+            promotionBenefitValueBps: candidate.valueBps,
+            promotionBenefitValueMinor: candidate.valueMinor,
+            floorApplied: adjustment.floorApplied,
+        }));
+        const appliedV2Codes = new Set(v2Discounts.flatMap((discount) => discount.code ? [normalize(discount.code)] : []));
+        const engineRejections = result.rejectedCodes.flatMap((rejection) => rejection.code && !appliedLegacyCodes.has(normalize(rejection.code))
+            ? [{
+                    code: firstSubmittedByIdentity.get(normalize(rejection.code)) ?? rejection.code,
+                    reason: mapEngineRejectionReason(rejection.reason),
+                }]
+            : []);
+        const appliedCodes = new Set([...retainedDiscounts.flatMap((discount) => discount.code ? [normalize(discount.code)] : []), ...appliedV2Codes]);
+        const mergedRejections = dedupeRejections([
+            ...input.codeRejections,
+            ...resolution.codeRejections,
+            ...engineRejections,
+        ], firstSubmittedByIdentity, input.codeRejections.length).filter((rejection) => !appliedCodes.has(normalize(rejection.code)));
+        const codeRejectionDetails = dedupeRejectionDetails([
+            ...selectedRejectionDetails(input.codeRejectionDetails ?? [], input.codeRejections, mergedRejections),
+            ...selectedRejectionDetails(resolution.codeRejectionDetails, resolution.codeRejections, mergedRejections),
+        ], firstSubmittedByIdentity);
+        return {
+            discounts: orderSubmittedCodeSlots([...retainedDiscounts, ...v2Discounts], firstSubmittedByIdentity),
+            codeRejections: mergedRejections,
+            codeRejectionDetails,
+        };
+    }
+    function adjustmentContext(input, discounts) {
+        return {
+            purchaseScope: input.mode === "subscription" ? "subscription_initial" : "one_time",
+            referenceProductMinor: input.referenceProductMinor,
+            currentProductMinor: input.subtotalGrossMinor - sumLane(discounts, false),
+            shippingMinor: input.shippingGrossMinor - sumLane(discounts, true),
+            minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+        };
+    }
+    function sumLane(discounts, shipping) {
+        return discounts
+            .filter((discount) => (discount.appliesTo === "shipping") === shipping)
+            .reduce((sum, discount) => sum + discount.amountOffMinor, 0);
+    }
+    function dedupeRejections(rejections, firstSubmittedByIdentity = new Map(), authoritativeFrom = rejections.length) {
+        const byCode = new Map();
+        for (const [index, rejection] of rejections.entries()) {
+            const identity = normalize(rejection.code);
+            const current = byCode.get(identity);
+            if (!current || (index >= authoritativeFrom && current.reason === "not_recognized")) {
+                byCode.set(identity, { ...rejection, code: firstSubmittedByIdentity.get(identity) ?? rejection.code });
+            }
+        }
+        return orderSubmittedCodeSlots([...byCode.values()], firstSubmittedByIdentity);
+    }
+    function dedupeRejectionDetails(details, firstSubmittedByIdentity = new Map()) {
+        const byCode = new Map();
+        for (const detail of details) {
+            const identity = normalize(detail.code);
+            if (!byCode.has(identity)) {
+                byCode.set(identity, { ...detail, code: firstSubmittedByIdentity.get(identity) ?? detail.code });
+            }
+        }
+        return orderSubmittedCodeSlots([...byCode.values()], firstSubmittedByIdentity);
+    }
+    function selectedRejectionDetails(details, sourceRejections, selectedRejections) {
+        const selected = new Map(selectedRejections.map((rejection) => [normalize(rejection.code), rejection.reason]));
+        const matchingSources = new Set(sourceRejections.flatMap((rejection) => selected.get(normalize(rejection.code)) === rejection.reason ? [normalize(rejection.code)] : []));
+        return details.filter((detail) => matchingSources.has(normalize(detail.code)));
+    }
+    function firstSubmittedCodes(codes) {
+        const seen = new Set();
+        const first = [];
+        for (const code of codes) {
+            const identity = normalize(code);
+            if (!identity || seen.has(identity))
+                continue;
+            seen.add(identity);
+            first.push(code);
+        }
+        return first;
+    }
+    /** Collapse legacy exact-literal collisions to one submitted identity per lane. */
+    function reduceProvisionalLegacyDiscounts(discounts, firstSubmittedByIdentity) {
+        const chosen = new Map();
+        for (const [index, discount] of discounts.entries()) {
+            if (!discount.code)
+                continue;
+            const identity = normalize(discount.code);
+            const firstSubmitted = firstSubmittedByIdentity.get(identity);
+            if (!firstSubmitted)
+                continue;
+            const key = `${identity}:${discount.appliesTo}`;
+            const exactFirstSpelling = discount.code === firstSubmitted;
+            const current = chosen.get(key);
+            if (!current || (exactFirstSpelling && !current.exactFirstSpelling)) {
+                chosen.set(key, { index, exactFirstSpelling });
+            }
+        }
+        return discounts.filter((discount, index) => {
+            if (!discount.code)
+                return true;
+            const identity = normalize(discount.code);
+            if (!firstSubmittedByIdentity.has(identity))
+                return true;
+            return chosen.get(`${identity}:${discount.appliesTo}`)?.index === index;
+        });
+    }
+    function projectSubmittedCodeSpelling(discounts, firstSubmittedByIdentity) {
+        return discounts.map((discount) => {
+            if (!discount.code)
+                return discount;
+            const code = firstSubmittedByIdentity.get(normalize(discount.code));
+            return code ? { ...discount, code } : discount;
+        });
+    }
+    function submittedRank(code, firstSubmittedByIdentity) {
+        const rank = [...firstSubmittedByIdentity.keys()].indexOf(normalize(code));
+        return rank < 0 ? Number.MAX_SAFE_INTEGER : rank;
+    }
+    function orderSubmittedCodeSlots(values, firstSubmittedByIdentity) {
+        const ordered = values.map((value, index) => ({ value, index })).filter(({ value }) => value.code && submittedRank(value.code, firstSubmittedByIdentity) < Number.MAX_SAFE_INTEGER)
+            .sort((left, right) => submittedRank(left.value.code, firstSubmittedByIdentity) - submittedRank(right.value.code, firstSubmittedByIdentity) || left.index - right.index).map(({ value }) => value);
+        let index = 0;
+        return values.map((value) => value.code && submittedRank(value.code, firstSubmittedByIdentity) < Number.MAX_SAFE_INTEGER ? ordered[index++] : value);
+    }
+    function normalize(code) {
+        return code.trim().toUpperCase();
+    }
+    function mapEngineRejectionReason(reason) {
+        switch (reason) {
+            case "better_price_exists":
+                return "better_price_exists";
+            case "scope_not_applicable":
+                return "scope_not_applicable";
+            default:
+                return "not_eligible";
+        }
+    }
+    return { applyPromotionCodesV2, mapEngineRejectionReason };
+}

package/dist/promotions/quotePromotionV2.d.ts

@@ -0,0 +1,30 @@
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+import type { QuoteDiscountResult } from "./quotePromoDiscounts.js";
+import type { PromotionRow } from "@openlup/core/promo";
+import type { CommerceQuoteDiscount } from "../pricing/index.js";
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+import type { createQuotePromoDiscounts } from "./quotePromoDiscounts.js";
+export declare function createQuotePromotionV2({ promotionCustomerSemantic, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, evaluateOrderTotalDiscounts, acquisition }: {
+    acquisition?: QuoteAcquisitionBinding<CreateQuoteRequest>;
+    promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"];
+    minimumProductPayableMinor: number;
+    evaluateOrderTotalDiscounts: ReturnType<typeof createQuotePromoDiscounts>["evaluateOrderTotalDiscounts"];
+}): {
+    evaluateAutomaticPromotionV2: (input: {
+        promoDataPort: CommercePromoDataPort;
+        clientId: string | null;
+        visitorId?: string | null;
+        mode: CreateQuoteRequest["mode"];
+        /** Raw request spellings stay intact for legacy exact-literal evaluation. */
+        promoCodes?: readonly string[];
+        regionCode: string;
+        referenceProductMinor: number;
+        currentProductMinor: number;
+        shippingMinor: number;
+        atTime: string;
+        emailEligibilityConfirmed?: boolean;
+        acquisitionCapability?: unknown;
+    }) => Promise<QuoteDiscountResult>;
+    legacyPromotionDataPort: (port: CommercePromoDataPort) => CommercePromoDataPort;
+};