@openlup/platform 0.18.0 → 0.19.0

package/src/promotions/commerceQuoteReadPreparation.ts

@@ -0,0 +1,29 @@
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+
+/** Allocate inside one quote resolution; clone each evaluator's mutable raw view. */
+export function memoizeCommercePromoReads(inner: CommercePromoDataPort): CommercePromoDataPort {
+  const definitions = memoize(() => inner.listActivePromotions());
+  const paid = memoize((id: string) => inner.countPaidOrders(id));
+  const modes = memoize((id: string) => inner.countPaidOrdersByMode(id));
+  const redemptions = memoize((id: string | null) => inner.redemptionCounts(id));
+  const device = memoize((id: string | null) => inner.deviceFirstOrderRedeemed(id));
+  return {
+    listActivePromotions: async () => structuredClone(await definitions()),
+    countPaidOrders: paid,
+    countPaidOrdersByMode: async (id) => ({ ...await modes(id) }),
+    redemptionCounts: async (id) => structuredClone(await redemptions(id)),
+    deviceFirstOrderRedeemed: device,
+  };
+}
+function memoize<A extends readonly unknown[], T>(read: (...args: A) => Promise<T>): (...args: A) => Promise<T> {
+  const values = new Map<string, Promise<T>>();
+  return (...args) => {
+    const key = JSON.stringify(args);
+    let value = values.get(key);
+    if (!value) {
+      value = Promise.resolve().then(() => read(...args));
+      values.set(key, value);
+    }
+    return value;
+  };
+}

package/src/promotions/index.ts

@@ -20,3 +20,6 @@ export * from "./promotionClaimSweepPort.js";
 export * from "./promotionClaims.js";
 export * from "./sql.js";
 export type { PromotionStatus, AdminPromotion, AdminPromotionV2Mirror, AdminPromotionSemanticBenefit, AdminPromotionsListResponse, AdminPromotionUpdatePayload, AdminPromotionUpdateRequest, AdminPromotionUpdateResponse } from "./contracts/index.js";
+export type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+export { createQuoteShippingPromotions } from "./quoteShippingPolicy.js";
+export type { QuoteShippingPromotionsDeps } from "./quoteShippingPolicy.js";

package/src/promotions/promotionQuoteAcceptance.ts

@@ -1,3 +1,4 @@
+import type { ShippingTerms } from "../shipping/index.js";
 import type { ResolvedAcquisitionTerms } from "../pricing/index.js";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { z } from "zod";
@@ -48,6 +49,7 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     request: Request;
     quote: CommerceQuote;
     acquisitionTerms?: ResolvedAcquisitionTerms;
+    shippingTerms?: ShippingTerms;
     keyring: PromotionAcceptanceKeyring;
     now?: Date;
   }): string | null {
@@ -58,11 +60,12 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     request: Request;
     quote: CommerceQuote;
     acquisitionTerms?: ResolvedAcquisitionTerms;
+    shippingTerms?: ShippingTerms;
     keyring: PromotionAcceptanceKeyring;
     now?: Date;
   }): { token: string | null; diagnostic: PromotionAcceptanceDiagnostic } {
     const evidence = v2Discounts(input.quote);
-    if (evidence.length === 0 && !input.acquisitionTerms) return {
+    if (evidence.length === 0 && !input.acquisitionTerms && !input.shippingTerms) return {
       token: null,
       diagnostic: rejected("no_v2_adjustment"),
     };
@@ -83,8 +86,8 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
       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),
+      quoteBinding: quoteBinding(input.quote, input.keyring.current, input.acquisitionTerms, input.shippingTerms),
+      sectionBindings: sectionBindings(input.quote, input.keyring.current, input.acquisitionTerms, input.shippingTerms),
       totalMinor: input.quote.totalGross.amountMinor,
       currency: input.quote.totalGross.currency,
     });
@@ -105,6 +108,7 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     request: Request;
     quote: CommerceQuote;
     acquisitionTerms?: ResolvedAcquisitionTerms;
+    shippingTerms?: ShippingTerms;
     expectedTotal: { amountMinor: number; currency: string };
     keyring: PromotionAcceptanceKeyring;
     now?: Date;
@@ -117,6 +121,7 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     request: Request;
     quote: CommerceQuote;
     acquisitionTerms?: ResolvedAcquisitionTerms;
+    shippingTerms?: ShippingTerms;
     expectedTotal: { amountMinor: number; currency: string };
     keyring: PromotionAcceptanceKeyring;
     now?: Date;
@@ -131,8 +136,8 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     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);
+    if (payload.quoteBinding !== quoteBinding(input.quote, secret, input.acquisitionTerms, input.shippingTerms)) {
+      const mismatchField = namedMismatchField(payload.sectionBindings, input.quote, secret, input.acquisitionTerms, input.shippingTerms);
       return { accepted: false, reason: "quote_mismatch", mismatchField, ...base };
     }
     if (payload.totalMinor !== input.expectedTotal.amountMinor) {
@@ -141,7 +146,7 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     if (payload.currency !== input.expectedTotal.currency) {
       return { accepted: false, reason: "currency_mismatch", ...base };
     }
-    if (v2Discounts(input.quote).length === 0 && !input.acquisitionTerms) {
+    if (v2Discounts(input.quote).length === 0 && !input.acquisitionTerms && !input.shippingTerms) {
       return { accepted: false, reason: "no_v2_adjustment_in_quote", ...base };
     }
     return { accepted: true, reason: "accepted", ...base };
@@ -227,16 +232,17 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     return hmac(secret, stableJson([...new Set(codes.map((code) => code.trim().toUpperCase()))].sort()));
   }
 
-  function quoteBinding(quote: CommerceQuote, secret: string, acquisitionTerms?: ResolvedAcquisitionTerms): string {
-    return hmac(secret, stableJson(projectPromotionQuoteMoney(quote, acquisitionTerms)));
+  function quoteBinding(quote: CommerceQuote, secret: string, acquisitionTerms?: ResolvedAcquisitionTerms, shippingTerms?: ShippingTerms): string {
+    return hmac(secret, stableJson(projectPromotionQuoteMoney(quote, acquisitionTerms, shippingTerms)));
   }
 
   function sectionBindings(
     quote: CommerceQuote,
     secret: string,
     acquisitionTerms?: ResolvedAcquisitionTerms,
+    shippingTerms?: ShippingTerms,
   ): Record<PromotionQuoteMoneySectionKey, string> {
-    const sections = promotionQuoteMoneySections(quote, acquisitionTerms);
+    const sections = promotionQuoteMoneySections(quote, acquisitionTerms, shippingTerms);
     return Object.fromEntries(PROMOTION_QUOTE_MONEY_SECTIONS
       .map((section) => [section, hmac(secret, stableJson(sections[section]))])) as Record<
         PromotionQuoteMoneySectionKey, string>;
@@ -251,9 +257,10 @@ export function createPromotionQuoteAcceptance<Request extends { promoCodes: str
     quote: CommerceQuote,
     secret: string,
     acquisitionTerms?: ResolvedAcquisitionTerms,
+    shippingTerms?: ShippingTerms,
   ): PromotionQuoteMismatchField {
     if (!issued) return "other";
-    const verified = sectionBindings(quote, secret, acquisitionTerms);
+    const verified = sectionBindings(quote, secret, acquisitionTerms, shippingTerms);
     return PROMOTION_QUOTE_MONEY_SECTIONS
       .find((section) => issued[section] !== verified[section]) ?? "other";
   }

package/src/promotions/promotionQuoteBinding.ts

@@ -1,3 +1,4 @@
+import type { ShippingTerms } from "../shipping/index.js";
 import { acquisitionQuoteBinding, type ResolvedAcquisitionTerms } from "../pricing/index.js";
 import type {
   CommerceMoney,
@@ -50,6 +51,7 @@ export interface PromotionQuoteMoneyDiscount {
 
 export interface PromotionQuoteMoneyProjection {
   acquisitionTerms?: ResolvedAcquisitionTerms;
+  shippingTerms?: ShippingTerms;
   currency: string;
   totalGross: CommerceMoney;
   netTotal: CommerceMoney;
@@ -85,7 +87,7 @@ export type PromotionQuoteMismatchField = (typeof PROMOTION_QUOTE_MISMATCH_FIELD
  * Discount order is preserved: the promotion engine emits its lanes
  * deterministically, so a reordering is a real evaluation difference.
  */
-export function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerms?: ResolvedAcquisitionTerms): PromotionQuoteMoneyProjection {
+export function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerms?: ResolvedAcquisitionTerms, shippingTerms?: ShippingTerms): PromotionQuoteMoneyProjection {
   return {
     ...acquisitionQuoteBinding(acquisitionTerms),
     currency: quote.currency,
@@ -96,6 +98,7 @@ export function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerm
     discountTotalGross: quote.discountTotalGross,
     shippingGross: quote.shippingGross ?? null,
     shippingDiscountGross: quote.shippingDiscountGross ?? null,
+    ...(shippingTerms ? { shippingTerms } : {}),
     lines: quote.lines.map((line) => ({
       sku: line.sku,
       quantity: line.quantity,
@@ -125,14 +128,16 @@ export function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerm
 export function promotionQuoteMoneySections(
   quote: CommerceQuote,
   acquisitionTerms?: ResolvedAcquisitionTerms,
+  shippingTerms?: ShippingTerms,
 ): Record<PromotionQuoteMoneySection, unknown> {
-  const money = projectPromotionQuoteMoney(quote, acquisitionTerms);
+  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),

package/src/promotions/quoteAcquisitionBinding.ts

@@ -0,0 +1,7 @@
+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/src/promotions/quoteAutomaticPromotions.ts

@@ -1,3 +1,5 @@
+import { selectAcquisitionTerms, assertAcquisitionTermsCapability, ACQUISITION_TERMS_CAPABILITY } from "../pricing/index.js";
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
 import type { CreateQuoteRequest } from "../pricing/index.js";
 import { PROMOTION_ENGINE_V2 } from "../pricing/index.js";
 import type { CreateQuoteOptions } from "../pricing/index.js";
@@ -5,7 +7,8 @@ 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 }: {
+export 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"];
@@ -23,10 +26,28 @@ export function createQuoteAutomaticPromotions<Request extends CreateQuoteReques
   }): Promise<QuoteDiscountResult> {
     if (!input.promoDataPort) return { discounts: [], codeRejections: [] };
 
+    let promoDataPort = input.promoDataPort;
+    let selection = null;
+    let acquisitionCapability: unknown;
+    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: input.promoDataPort,
+        promoDataPort,
         clientId: input.options.clientId ?? null,
         visitorId: input.request.visitorId ?? null,
         mode: input.request.mode,
@@ -37,11 +58,12 @@ export function createQuoteAutomaticPromotions<Request extends CreateQuoteReques
         shippingMinor: input.shippingGrossMinor,
         atTime: input.atTime,
         emailEligibilityConfirmed,
+        ...(acquisition ? { acquisitionCapability } : {}),
       });
     }
 
-    return evaluateOrderTotalDiscounts({
-      promoDataPort: legacyPromotionDataPort(input.promoDataPort),
+    const pending = evaluateOrderTotalDiscounts({
+      promoDataPort: legacyPromotionDataPort(promoDataPort),
       clientId: input.options?.clientId ?? null,
       visitorId: input.request.visitorId ?? null,
       mode: input.request.mode,
@@ -52,6 +74,10 @@ export function createQuoteAutomaticPromotions<Request extends CreateQuoteReques
       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/src/promotions/quotePromoDiscounts.ts

@@ -1,16 +1,20 @@
+import { filterAcquisitionPromotions } from "../pricing/index.js";
+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 { evaluatePromos, promoEligibilityFailure } from "@openlup/core/promo";
 import type { PromoEvaluationCart, PromotionRow } from "@openlup/core/promo";
 import type { CommercePromoDataPort, PromotionRedemptionCount } 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 function createQuotePromoDiscounts({ promotionCustomerSemantic }: { promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"] }) {
+export function createQuotePromoDiscounts({ promotionCustomerSemantic, acquisition }: { acquisition?: Pick<QuoteAcquisitionBinding, "financialPolicy">; 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
@@ -52,7 +56,12 @@ export function createQuotePromoDiscounts({ promotionCustomerSemantic }: { promo
       input.promoDataPort.redemptionCounts(input.clientId),
       input.promoDataPort.deviceFirstOrderRedeemed(input.visitorId ?? null),
     ]);
-    const candidates = allCandidates.filter(
+    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),
     );
 

package/src/promotions/quotePromotionV2.ts

@@ -1,3 +1,6 @@
+import { filterAcquisitionPromotions, selectAcquisitionTerms, assertAcquisitionTermsCapability, ACQUISITION_TERMS_CAPABILITY } from "../pricing/index.js";
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+import type { QuoteDiscountResult } from "./quotePromoDiscounts.js";
 import { evaluatePromotionAdjustmentsV2, promoEligibilityFailure } from "@openlup/core/promo";
 import type {
   PromoEvaluationCart,
@@ -18,7 +21,8 @@ type V2Row = PromotionRow & {
   v2_mirror_of?: unknown;
 };
 
-export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, evaluateOrderTotalDiscounts }: {
+export 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"];
@@ -37,7 +41,8 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
     shippingMinor: number;
     atTime: string;
     emailEligibilityConfirmed?: boolean;
-  }): Promise<{ discounts: CommerceQuoteDiscount[]; codeRejections: CommerceCodeRejection[] }> {
+    acquisitionCapability?: unknown;
+  }): Promise<QuoteDiscountResult> {
     const byMode = input.clientId
       ? await input.promoDataPort.countPaidOrdersByMode(input.clientId)
       : { oneTime: 0, subscription: 0 };
@@ -46,6 +51,14 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
       input.promoDataPort.redemptionCounts(input.clientId),
       input.promoDataPort.deviceFirstOrderRedeemed(input.visitorId ?? null),
     ]);
+    const existingSubscriber = input.mode === "subscription" && byMode.subscription > 0;
+    const candidatesForCustomer = acquisition && existingSubscriber ? rows.filter((row) =>
+      !acquisition.financialPolicy.facts(row).metadataPresent && row.eligibility.first_subscription_purchase !== true) : rows;
+    const selection = acquisition && input.mode === "subscription" && !existingSubscriber
+      ? selectAcquisitionTerms(candidatesForCustomer, input.atTime, input.regionCode, acquisition.financialPolicy) : null;
+    if (acquisition) assertAcquisitionTermsCapability(selection, input.acquisitionCapability, "promotion-engine.v2");
+    const effectiveRows = acquisition && input.mode === "subscription"
+      ? filterAcquisitionPromotions(candidatesForCustomer, input.atTime, input.regionCode, acquisition.financialPolicy) : candidatesForCustomer;
     const cart: PromoEvaluationCart = {
       region_code: input.regionCode,
       cart_mode: input.mode === "subscription" ? "subscription" : "one_time",
@@ -59,7 +72,7 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
       applied_codes: [],
     };
 
-    const eligibleRows = (rows as V2Row[])
+    const eligibleRows = (effectiveRows as V2Row[])
       .filter((row) => row.promotion_engine_version === "promotion-engine.v2")
       .filter((row) => row.trigger_type === "automatic")
       .filter((row) => promoEligibilityFailure(row, cart, input.atTime) === null)
@@ -91,7 +104,8 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
       };
     });
     const legacyFloor = await evaluateOrderTotalDiscounts({
-      promoDataPort: legacyPromotionDataPort(input.promoDataPort),
+      promoDataPort: legacyPromotionDataPort(acquisition
+        ? { ...input.promoDataPort, listActivePromotions: async () => effectiveRows } : input.promoDataPort),
       clientId: input.clientId,
       visitorId: input.visitorId,
       mode: input.mode,
@@ -109,6 +123,8 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
     return {
       discounts,
       codeRejections: reconcileLegacyCodeOutcomes(input.promoCodes ?? [], discounts, legacyFloor),
+      ...(selection && input.acquisitionCapability === ACQUISITION_TERMS_CAPABILITY
+        ? { acquisitionTerms: selection.terms } : {}),
     };
   }
 

package/src/promotions/quoteShippingPolicy.ts

@@ -0,0 +1,61 @@
+import { PROMOTION_ENGINE_V2 } from "../pricing/index.js";
+import type { CreateQuoteRequest, QuoteShippingPromotionInput, QuoteShippingPromotionResult } from "../pricing/index.js";
+import { resolveShippingPolicy, resolveThresholdShipping } from "../shipping/index.js";
+import type { ShippingSettings } from "../shipping/index.js";
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+import type { PromotionCodeQuotePort } from "./promotionCodeQuotePort.js";
+import type { createQuoteAutomaticPromotions } from "./quoteAutomaticPromotions.js";
+import type { createQuotePromotionCodeAdjustments } from "./quotePromotionCodeAdjustments.js";
+import { memoizeCommercePromoReads } from "./commerceQuoteReadPreparation.js";
+
+export interface QuoteShippingPromotionsDeps<Request extends CreateQuoteRequest & { visitorId?: string }> {
+  promoDataPort?: CommercePromoDataPort;
+  promotionCodeQuotePort?: PromotionCodeQuotePort;
+  commerceSettingsPort?: { getShippingSettings(): Promise<ShippingSettings> };
+  resolveAutomaticQuotePromotions: ReturnType<typeof createQuoteAutomaticPromotions<Request>>["resolveAutomaticQuotePromotions"];
+  applyPromotionCodesV2: ReturnType<typeof createQuotePromotionCodeAdjustments>["applyPromotionCodesV2"];
+}
+/** Evaluate both lanes again only when the post-product-discount threshold changes the fee. */
+export function createQuoteShippingPromotions<Request extends CreateQuoteRequest & { visitorId?: string }>(deps: QuoteShippingPromotionsDeps<Request>) {
+  async function resolveQuoteShippingPromotions(input: QuoteShippingPromotionInput<Request>): Promise<QuoteShippingPromotionResult> {
+    const settings = deps.commerceSettingsPort
+      ? await deps.commerceSettingsPort.getShippingSettings()
+      : { legacyFlatMinor: 0, policy: null };
+    const shipping = resolveShippingPolicy(settings, input.atTime, input.currency);
+    const promoDataPort = deps.promoDataPort ? memoizeCommercePromoReads(deps.promoDataPort) : undefined;
+    let candidates: ReturnType<PromotionCodeQuotePort["resolve"]> | undefined;
+    const port: PromotionCodeQuotePort | undefined = deps.promotionCodeQuotePort ? {
+      resolve: async (request) => structuredClone(await (candidates ??= deps.promotionCodeQuotePort!.resolve(request))),
+    } : undefined;
+    async function evaluate(shippingGrossMinor: number) {
+      const automatic = await deps.resolveAutomaticQuotePromotions({ ...input, promoDataPort, shippingGrossMinor });
+      const adjusted = await deps.applyPromotionCodesV2({
+        port,
+        preserveLegacyDiscountsWhenNoCandidates: input.options?.pricingPolicy?.promotionEngineVersion !== PROMOTION_ENGINE_V2,
+        clientId: input.options?.clientId ?? null,
+        mode: input.request.mode,
+        promoCodes: input.request.promoCodes,
+        referenceProductMinor: input.referenceProductMinor,
+        subtotalGrossMinor: input.subtotalGrossMinor,
+        shippingGrossMinor,
+        discounts: automatic.discounts,
+        codeRejections: automatic.codeRejections,
+        atTime: input.atTime,
+      });
+      return { ...adjusted, acquisitionTerms: automatic.acquisitionTerms };
+    }
+    let shippingGrossMinor = shipping.flatMinor;
+    let result = await evaluate(shippingGrossMinor);
+    const productDiscount = result.discounts.filter((discount) => discount.appliesTo !== "shipping")
+      .reduce((total, discount) => total + discount.amountOffMinor, 0);
+    if (shipping.terms) {
+      const resolved = resolveThresholdShipping(shipping.terms, input.subtotalGrossMinor - productDiscount);
+      if (resolved.grossMinor !== shippingGrossMinor) {
+        shippingGrossMinor = resolved.grossMinor;
+        result = await evaluate(shippingGrossMinor);
+      }
+    }
+    return { ...result, shippingGrossMinor, shippingTerms: shipping.terms, hasShipping: deps.commerceSettingsPort != null };
+  }
+  return { resolveQuoteShippingPromotions };
+}

package/src/shipping/bindings.ts

@@ -0,0 +1,74 @@
+import type { BffResponder } from "../bff/index.js";
+import type { CustomerAddressBookPort, CustomerAddressMutationPort, CustomerAddressesDeps } from "./addressPorts.js";
+import type { CustomerAddressSchemas } from "./addressSchemas.js";
+import type { DeliverySelectionPort } from "./deliverySelectionPort.js";
+import type { DeliverySelectionSchemas } from "./handlerSchemas.js";
+import type { PickupPointSearchPort } from "./pickupPointSearchPort.js";
+import type { AdminShippingRateHandlerDeps, ShippingRateDataPort, ShippingRateHandlerSchemas } from "./shippingRatePorts.js";
+import { createCustomerAddressesHandler } from "./customerAddressesHandler.js";
+import { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
+import { createDeliveryOptionsHandler, createPickupPointSearchHandler, createPickupPointValidationHandler } from "./deliverySelectionHandler.js";
+
+type Store = {
+  addressBookPort?: CustomerAddressBookPort;
+  addressMutationPort?: CustomerAddressMutationPort;
+  shippingRateDataPort?: ShippingRateDataPort;
+};
+export interface ShippingBindingDependencies {
+  dataKind: string;
+  createManagedStore?: () => Store | null;
+  nativeStore?: Omit<Store, "addressMutationPort"> | null;
+  responder: BffResponder;
+  selection?: { port: DeliverySelectionPort; searchPort: PickupPointSearchPort; schemas: DeliverySelectionSchemas };
+  addresses?: { schemas: CustomerAddressSchemas; authenticateUser: CustomerAddressesDeps["authenticateUser"]; requireWrites: boolean };
+  rate?: { schemas: ShippingRateHandlerSchemas; authorizeAdmin: AdminShippingRateHandlerDeps["authorizeAdmin"]; resolveAdmin: AdminShippingRateHandlerDeps["resolveAdmin"] };
+}
+export interface ShippingBindings {
+  store: Store;
+  handlers: {
+    options: ReturnType<typeof createDeliveryOptionsHandler> | null;
+    search: ReturnType<typeof createPickupPointSearchHandler> | null;
+    validate: ReturnType<typeof createPickupPointValidationHandler> | null;
+    addresses: ReturnType<typeof createCustomerAddressesHandler> | null;
+    rate: ReturnType<typeof createAdminShippingRateHandler> | null;
+  };
+  readiness: { ready: boolean; reason: string | null };
+  unsupported: { addressWrites: string | null; flatRateSave: string | null };
+}
+
+/** Explicit selected stores and host validation; importing this module activates nothing. */
+export function createShippingBindings(deps: ShippingBindingDependencies): ShippingBindings {
+  const native = deps.dataKind === "postgres";
+  const addressWrites = native ? "shipping_native_address_writes_unsupported" : null;
+  const flatRateSave = native ? "shipping_native_flat_rate_save_unsupported" : null;
+  const refused = (reason: string): ShippingBindings => ({
+    store: {}, handlers: { options: null, search: null, validate: null, addresses: null, rate: null },
+    readiness: { ready: false, reason }, unsupported: { addressWrites, flatRateSave },
+  });
+  if (!native && deps.dataKind !== "supabase") return refused("shipping_store_incompatible");
+  if (native && deps.addresses?.requireWrites) return refused(addressWrites!);
+  if (native && deps.rate) return refused(flatRateSave!);
+  const selected: Store | null | undefined = native ? deps.nativeStore : deps.createManagedStore?.();
+  if ((deps.addresses || deps.rate) && !selected) return refused("shipping_store_required");
+  // Native address mutations remain unavailable even if an untyped host plants a writer.
+  const store: Store = { addressBookPort: selected?.addressBookPort, shippingRateDataPort: selected?.shippingRateDataPort,
+    addressMutationPort: native ? undefined : selected?.addressMutationPort };
+  if (deps.addresses && (typeof store.addressBookPort?.getAddressBook !== "function"
+    || typeof deps.addresses.authenticateUser !== "function"
+    || (deps.addresses.requireWrites && ![store.addressMutationPort?.upsertAddress, store.addressMutationPort?.deleteAddress].every(fn => typeof fn === "function")))) return refused("shipping_address_store_incompatible");
+  if (deps.rate && (![store.shippingRateDataPort?.getShippingFlatMinor, store.shippingRateDataPort?.setShippingFlatMinor,
+    store.shippingRateDataPort?.recordPromotionAudit, deps.rate.authorizeAdmin, deps.rate.resolveAdmin].every(fn => typeof fn === "function"))) return refused("shipping_rate_store_incompatible");
+  if (deps.selection && ![deps.selection.port?.listOptions, deps.selection.port?.validatePickupPoint, deps.selection.searchPort?.searchPickupPoints].every(fn => typeof fn === "function")) return refused("shipping_selection_incompatible");
+  return {
+    store,
+    handlers: {
+      options: deps.selection ? createDeliveryOptionsHandler(deps.selection.port, deps.selection.schemas, deps.responder) : null,
+      search: deps.selection ? createPickupPointSearchHandler(deps.selection.searchPort, deps.selection.schemas, deps.responder) : null,
+      validate: deps.selection ? createPickupPointValidationHandler(deps.selection.port, deps.selection.schemas, deps.responder) : null,
+      addresses: deps.addresses ? createCustomerAddressesHandler({ addressBookPort: store.addressBookPort!, addressMutationPort: store.addressMutationPort,
+        authenticateUser: deps.addresses.authenticateUser }, deps.addresses.schemas, deps.responder) : null,
+      rate: deps.rate ? createAdminShippingRateHandler({ dataPort: store.shippingRateDataPort!, authorizeAdmin: deps.rate.authorizeAdmin,
+        resolveAdmin: deps.rate.resolveAdmin }, deps.rate.schemas, deps.responder) : null,
+    }, readiness: { ready: true, reason: null }, unsupported: { addressWrites, flatRateSave },
+  };
+}

package/src/shipping/contracts/index.ts

@@ -16,3 +16,4 @@ export type {
   CanonicalAddressInput, AddressCanonSource, AddressCanonLocalityCandidate, AddressCanonStreet, AddressCanonPostalCodeLookupRequest, AddressCanonLocalitiesLookupRequest, AddressCanonStreetsLookupRequest, AddressCanonPostalCodeLookupResponse, AddressCanonLocalitiesLookupResponse, AddressCanonStreetsLookupResponse, CustomerAddressKind, CustomerAddress, CustomerOrdererProfile, CustomerAddressesRequest, CustomerAddressesResponse, CustomerAddressUpsertRequest, CustomerAddressDeleteRequest
 } from "./address.js";
 export type { AdminShippingRateResponse, AdminSetShippingRateRequest, AdminSetShippingRateResponse } from "./shippingRate.js";
+export type { ShippingTerms, ShippingPolicyEntry, ShippingPolicy, ShippingSettings } from "./threshold.js";

package/src/shipping/contracts/threshold.ts

@@ -0,0 +1,22 @@
+/** Shipping promises selected by an opt-in host policy. Runtime validation is server-only. */
+export interface ShippingTerms {
+  version: "shipping-threshold.v1";
+  currency: string;
+  flatMinor: number;
+  freeThresholdMinor: number;
+}
+export interface ShippingPolicyEntry {
+  enabled: boolean;
+  flatMinor: number;
+  freeThresholdMinor: number;
+  effectiveFrom: string;
+}
+export interface ShippingPolicy {
+  version: "shipping-policy.v1";
+  current: ShippingPolicyEntry | null;
+  scheduled?: ShippingPolicyEntry | null;
+}
+export interface ShippingSettings {
+  legacyFlatMinor: number;
+  policy: ShippingPolicy | null;
+}

package/src/shipping/index.ts

@@ -21,3 +21,6 @@ export { readAddresses, readOrdererProfiles, addressUsedByActiveSubscription, ad
 export type { AdminShippingRateResponse, AdminSetShippingRateRequest, AdminSetShippingRateResponse } from "./contracts/shippingRate.js";
 export { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
 export type { AdminShippingRateHandlerDeps, ShippingRateDataPort, ShippingRateHandlerSchemas } from "./shippingRatePorts.js";
+export { createShippingBindings, type ShippingBindingDependencies, type ShippingBindings } from "./bindings.js";
+export type { ShippingTerms, ShippingPolicyEntry, ShippingPolicy, ShippingSettings } from "./contracts/threshold.js";
+export { shippingTermsSchema, shippingPolicySchema, parseShippingTerms, hasShippingTerms, normalizeShippingPolicy, resolveShippingPolicy, resolveThresholdShipping } from "./thresholdPolicy.js";

package/src/shipping/thresholdPolicy.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import type { ShippingPolicy, ShippingPolicyEntry, ShippingSettings, ShippingTerms } from "./contracts/threshold.js";
+
+const minorSchema = z.number().int().nonnegative().max(2_147_483_647);
+const instantSchema = z.string().datetime({ offset: true }).refine((value) => {
+  const [year, month, day] = value.slice(0, 10).split("-").map(Number);
+  const days = new Date(Date.UTC(year, month, 0)).getUTCDate();
+  return day <= days && Number.isFinite(Date.parse(value));
+}, "Invalid calendar date");
+
+export const shippingTermsSchema = z.object({
+  version: z.literal("shipping-threshold.v1"),
+  currency: z.string().regex(/^[A-Z]{3}$/),
+  flatMinor: minorSchema,
+  freeThresholdMinor: minorSchema,
+}).strict();
+const entrySchema = z.object({
+  enabled: z.boolean(), flatMinor: minorSchema, freeThresholdMinor: minorSchema,
+  effectiveFrom: instantSchema,
+}).strict();
+export const shippingPolicySchema = z.object({
+  version: z.literal("shipping-policy.v1"),
+  current: entrySchema.nullable(), scheduled: entrySchema.nullable().optional(),
+}).strict().refine((policy) => !policy.current || !policy.scheduled ||
+  Date.parse(policy.current.effectiveFrom) < Date.parse(policy.scheduled.effectiveFrom),
+"Scheduled policy must follow current policy");
+
+/** Absence selects legacy behavior; malformed retained promises refuse. */
+export function parseShippingTerms(value: unknown): ShippingTerms | undefined {
+  return value === undefined ? undefined : shippingTermsSchema.parse(value);
+}
+export function hasShippingTerms(quote: { context?: { shippingTerms?: unknown } }): boolean {
+  return quote.context?.shippingTerms !== undefined;
+}
+/** Resolve effective entries on read, without a scheduled write. */
+export function normalizeShippingPolicy(policy: ShippingPolicy, asOf: Date | string): ShippingPolicy {
+  const parsed = shippingPolicySchema.parse(policy);
+  const now = new Date(asOf).getTime();
+  if (!Number.isFinite(now)) throw new Error("shipping_policy_invalid_as_of");
+  const entries = [parsed.current, parsed.scheduled].filter((entry): entry is ShippingPolicyEntry => !!entry);
+  const effective = entries.filter((entry) => Date.parse(entry.effectiveFrom) <= now);
+  const future = entries.filter((entry) => Date.parse(entry.effectiveFrom) > now);
+  if (future.length > 1) throw new Error("shipping_policy_multiple_scheduled_changes");
+  return { version: parsed.version, current: effective[effective.length - 1] ?? null, scheduled: future[0] ?? null };
+}
+export function resolveShippingPolicy(settings: ShippingSettings, asOf: Date | string, currency: string): {
+  configured: boolean; flatMinor: number; terms?: ShippingTerms;
+} {
+  if (settings.policy === null) return { configured: false, flatMinor: minorSchema.parse(settings.legacyFlatMinor) };
+  const { current } = normalizeShippingPolicy(settings.policy, asOf);
+  if (!current?.enabled) return { configured: true, flatMinor: 0 };
+  const terms = shippingTermsSchema.parse({
+    version: "shipping-threshold.v1", currency,
+    flatMinor: current.flatMinor, freeThresholdMinor: current.freeThresholdMinor,
+  });
+  return { configured: true, flatMinor: terms.flatMinor, terms };
+}
+/** Only product payable after discounts counts; equality receives free delivery. */
+export function resolveThresholdShipping(terms: ShippingTerms, productPayableMinor: number): {
+  grossMinor: number; remainingMinor: number;
+} {
+  const payable = minorSchema.parse(productPayableMinor);
+  const remainingMinor = Math.max(0, terms.freeThresholdMinor - payable);
+  return { grossMinor: remainingMinor > 0 ? terms.flatMinor : 0, remainingMinor };
+}