@openlup/platform 0.17.0 → 0.18.0

package/src/promotions/quoteAutomaticPromotions.ts

@@ -0,0 +1,58 @@
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import { PROMOTION_ENGINE_V2 } 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 function createQuoteAutomaticPromotions<Request extends CreateQuoteRequest & { visitorId?: string }>({ resolveEmailEligibility, evaluateOrderTotalDiscounts, evaluateAutomaticPromotionV2, legacyPromotionDataPort }: {
+  resolveEmailEligibility(request: Request): boolean;
+  evaluateOrderTotalDiscounts: ReturnType<typeof createQuotePromoDiscounts>["evaluateOrderTotalDiscounts"];
+  evaluateAutomaticPromotionV2: ReturnType<typeof createQuotePromotionV2>["evaluateAutomaticPromotionV2"];
+  legacyPromotionDataPort: ReturnType<typeof createQuotePromotionV2>["legacyPromotionDataPort"];
+}) {
+  async function resolveAutomaticQuotePromotions(input: {
+    promoDataPort?: CommercePromoDataPort;
+    request: Request;
+    options?: CreateQuoteOptions;
+    regionCode: string;
+    referenceProductMinor: number;
+    subtotalGrossMinor: number;
+    shippingGrossMinor: number;
+    atTime: string;
+  }): Promise<QuoteDiscountResult> {
+    if (!input.promoDataPort) return { discounts: [], codeRejections: [] };
+
+    const emailEligibilityConfirmed = resolveEmailEligibility(input.request);
+    if (input.options?.pricingPolicy?.promotionEngineVersion === PROMOTION_ENGINE_V2) {
+      return evaluateAutomaticPromotionV2({
+        promoDataPort: input.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,
+      });
+    }
+
+    return evaluateOrderTotalDiscounts({
+      promoDataPort: legacyPromotionDataPort(input.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,
+    });
+  }
+
+  return { resolveAutomaticQuotePromotions };
+}

package/src/promotions/quotePromoDiscounts.ts

@@ -0,0 +1,185 @@
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import type { CommerceCodeRejection, CommerceQuoteDiscount } from "../pricing/index.js";
+import { evaluatePromos, promoEligibilityFailure } from "@openlup/core/promo";
+import type { PromoEvaluationCart, PromotionRow } from "@openlup/core/promo";
+import type { CommercePromoDataPort, PromotionRedemptionCount } from "./promoDataPort.js";
+export interface QuoteDiscountResult {
+  /** 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 function createQuotePromoDiscounts({ promotionCustomerSemantic }: { promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"] }) {
+  /**
+   * 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: {
+    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> {
+    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 candidates = allCandidates.filter(
+      (promo) => !capReached(promo, redemptionCounts.get(promo.id), input.clientId),
+    );
+
+    const cart: PromoEvaluationCart = {
+      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: CommerceQuoteDiscount[] = [];
+    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: { clientId: string | null; promoCodes: string[]; atTime: string },
+    cart: PromoEvaluationCart,
+    allCandidates: PromotionRow[],
+    redemptionCounts: Map<string, PromotionRedemptionCount>,
+    discounts: readonly CommerceQuoteDiscount[],
+  ): CommerceCodeRejection[] {
+    const rejections: CommerceCodeRejection[] = [];
+    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: readonly string[], candidates: readonly PromotionRow[]): string[] {
+    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: string, candidates: readonly PromotionRow[]): PromotionRow | undefined {
+    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: string | null | undefined, right: string | null | undefined): boolean {
+    return typeof left === "string" && typeof right === "string" &&
+      left.trim().toUpperCase() === right.trim().toUpperCase();
+  }
+
+  function capReached(
+    promo: PromotionRow,
+    counts: PromotionRedemptionCount | undefined,
+    clientId: string | null,
+  ): boolean {
+    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/src/promotions/quotePromotionCodeAdjustments.ts

@@ -0,0 +1,277 @@
+import { evaluatePromotionAdjustmentsV2 } from "@openlup/core/promo";
+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 function createQuotePromotionCodeAdjustments({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }: { minimumProductPayableMinor: number }) {
+  async function applyPromotionCodesV2(input: ApplyPromotionCodesV2Input): Promise<{
+    discounts: CommerceQuoteDiscount[]; codeRejections: CommerceCodeRejection[]; codeRejectionDetails: CommerceCodeRejectionDetail[];
+  }> {
+    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<string>();
+    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: CommerceQuoteDiscount[] = 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: CommerceCodeRejection[] = 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: ApplyPromotionCodesV2Input, discounts: readonly CommerceQuoteDiscount[]) {
+    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,
+    } as const;
+  }
+
+  function sumLane(discounts: readonly CommerceQuoteDiscount[], shipping: boolean): number {
+    return discounts
+      .filter((discount) => (discount.appliesTo === "shipping") === shipping)
+      .reduce((sum, discount) => sum + discount.amountOffMinor, 0);
+  }
+
+  function dedupeRejections(
+    rejections: readonly CommerceCodeRejection[],
+    firstSubmittedByIdentity: ReadonlyMap<string, string> = new Map(),
+    authoritativeFrom = rejections.length,
+  ): CommerceCodeRejection[] {
+    const byCode = new Map<string, CommerceCodeRejection>();
+    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: readonly CommerceCodeRejectionDetail[],
+    firstSubmittedByIdentity: ReadonlyMap<string, string> = new Map(),
+  ): CommerceCodeRejectionDetail[] {
+    const byCode = new Map<string, CommerceCodeRejectionDetail>();
+    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: readonly CommerceCodeRejectionDetail[], sourceRejections: readonly CommerceCodeRejection[], selectedRejections: readonly CommerceCodeRejection[]): CommerceCodeRejectionDetail[] {
+    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: readonly string[]): string[] {
+    const seen = new Set<string>();
+    const first: string[] = [];
+    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: readonly CommerceQuoteDiscount[], firstSubmittedByIdentity: ReadonlyMap<string, string>): CommerceQuoteDiscount[] {
+    const chosen = new Map<string, { index: number; exactFirstSpelling: boolean }>();
+    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: readonly CommerceQuoteDiscount[], firstSubmittedByIdentity: ReadonlyMap<string, string>): CommerceQuoteDiscount[] {
+    return discounts.map((discount) => {
+      if (!discount.code) return discount;
+      const code = firstSubmittedByIdentity.get(normalize(discount.code));
+      return code ? { ...discount, code } : discount;
+    });
+  }
+
+  function submittedRank(code: string, firstSubmittedByIdentity: ReadonlyMap<string, string>): number {
+    const rank = [...firstSubmittedByIdentity.keys()].indexOf(normalize(code));
+    return rank < 0 ? Number.MAX_SAFE_INTEGER : rank;
+  }
+
+  function orderSubmittedCodeSlots<T extends { code?: string | null }>(values: T[], firstSubmittedByIdentity: ReadonlyMap<string, string>): T[] {
+    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: string): string {
+    return code.trim().toUpperCase();
+  }
+
+  function mapEngineRejectionReason(reason: PromotionCodeRejectionReason): CommerceCodeRejectionReason {
+    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 };
+}