@openlup/platform 0.18.0 → 0.20.0

package/dist/promotions/quoteAutomaticPromotions.js

@@ -1,12 +1,30 @@
+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 }) {
+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: input.promoDataPort,
+                promoDataPort,
                 clientId: input.options.clientId ?? null,
                 visitorId: input.request.visitorId ?? null,
                 mode: input.request.mode,
@@ -17,10 +35,11 @@ export function createQuoteAutomaticPromotions({ resolveEmailEligibility, evalua
                 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,
@@ -31,6 +50,11 @@ export function createQuoteAutomaticPromotions({ resolveEmailEligibility, evalua
             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

@@ -1,14 +1,18 @@
+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 }: {
+export declare function createQuotePromoDiscounts({ promotionCustomerSemantic, acquisition }: {
+    acquisition?: Pick<QuoteAcquisitionBinding, "financialPolicy">;
     promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"];
 }): {
     evaluateOrderTotalDiscounts: (input: {

package/dist/promotions/quotePromoDiscounts.js

@@ -1,5 +1,6 @@
+import { filterAcquisitionPromotions } from "../pricing/index.js";
 import { evaluatePromos, promoEligibilityFailure } from "@openlup/core/promo";
-export function createQuotePromoDiscounts({ promotionCustomerSemantic }) {
+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
@@ -23,7 +24,12 @@ export function createQuotePromoDiscounts({ promotionCustomerSemantic }) {
             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 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",

package/dist/promotions/quotePromotionV2.d.ts

@@ -1,9 +1,12 @@
+import type { QuoteAcquisitionBinding } from "./quoteAcquisitionBinding.js";
+import type { QuoteDiscountResult } from "./quotePromoDiscounts.js";
 import type { PromotionRow } from "@openlup/core/promo";
-import type { CommerceCodeRejection, CommerceQuoteDiscount } from "../pricing/index.js";
+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 }: {
+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"];
@@ -21,9 +24,7 @@ export declare function createQuotePromotionV2({ promotionCustomerSemantic, mini
         shippingMinor: number;
         atTime: string;
         emailEligibilityConfirmed?: boolean;
-    }) => Promise<{
-        discounts: CommerceQuoteDiscount[];
-        codeRejections: CommerceCodeRejection[];
-    }>;
+        acquisitionCapability?: unknown;
+    }) => Promise<QuoteDiscountResult>;
     legacyPromotionDataPort: (port: CommercePromoDataPort) => CommercePromoDataPort;
 };

package/dist/promotions/quotePromotionV2.js

@@ -1,6 +1,7 @@
+import { filterAcquisitionPromotions, selectAcquisitionTerms, assertAcquisitionTermsCapability, ACQUISITION_TERMS_CAPABILITY } from "../pricing/index.js";
 import { evaluatePromotionAdjustmentsV2, promoEligibilityFailure } from "@openlup/core/promo";
 import { resolvePromotionBenefitDefinition } from "./promotionBenefitDefinition.js";
-export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, evaluateOrderTotalDiscounts }) {
+export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, evaluateOrderTotalDiscounts, acquisition }) {
     /** Automatic v2 benefits. Code claims remain outside quote evaluation. */
     async function evaluateAutomaticPromotionV2(input) {
         const byMode = input.clientId
@@ -11,6 +12,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 = {
             region_code: input.regionCode,
             cart_mode: input.mode === "subscription" ? "subscription" : "one_time",
@@ -23,7 +32,7 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
             email_eligibility_confirmed: input.emailEligibilityConfirmed === true,
             applied_codes: [],
         };
-        const eligibleRows = rows
+        const eligibleRows = effectiveRows
             .filter((row) => row.promotion_engine_version === "promotion-engine.v2")
             .filter((row) => row.trigger_type === "automatic")
             .filter((row) => promoEligibilityFailure(row, cart, input.atTime) === null)
@@ -54,7 +63,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,
@@ -69,6 +79,8 @@ export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProdu
         return {
             discounts,
             codeRejections: reconcileLegacyCodeOutcomes(input.promoCodes ?? [], discounts, legacyFloor),
+            ...(selection && input.acquisitionCapability === ACQUISITION_TERMS_CAPABILITY
+                ? { acquisitionTerms: selection.terms } : {}),
         };
     }
     function legacyPromotionDataPort(port) {

package/dist/promotions/quoteShippingPolicy.d.ts

@@ -0,0 +1,23 @@
+import type { CreateQuoteRequest, QuoteShippingPromotionInput, QuoteShippingPromotionResult } from "../pricing/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";
+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 declare function createQuoteShippingPromotions<Request extends CreateQuoteRequest & {
+    visitorId?: string;
+}>(deps: QuoteShippingPromotionsDeps<Request>): {
+    resolveQuoteShippingPromotions: (input: QuoteShippingPromotionInput<Request>) => Promise<QuoteShippingPromotionResult>;
+};

package/dist/promotions/quoteShippingPolicy.js

@@ -0,0 +1,47 @@
+import { PROMOTION_ENGINE_V2 } from "../pricing/index.js";
+import { resolveShippingPolicy, resolveThresholdShipping } from "../shipping/index.js";
+import { memoizeCommercePromoReads } from "./commerceQuoteReadPreparation.js";
+/** Evaluate both lanes again only when the post-product-discount threshold changes the fee. */
+export function createQuoteShippingPromotions(deps) {
+    async function resolveQuoteShippingPromotions(input) {
+        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;
+        const port = deps.promotionCodeQuotePort ? {
+            resolve: async (request) => structuredClone(await (candidates ??= deps.promotionCodeQuotePort.resolve(request))),
+        } : undefined;
+        async function evaluate(shippingGrossMinor) {
+            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/dist/shipping/bindings.d.ts

@@ -0,0 +1,62 @@
+import type { ReadinessReport, SchemaObservation } from "@openlup/core/readiness";
+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;
+    /** Core report for the selected shipping contribution, observed by the host. */
+    nativeRateReadiness?: ReadinessReport;
+    /** Same-database Core observation of the applied shipping seed and required objects. */
+    nativeRateSchema?: SchemaObservation;
+    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 declare function createShippingBindings(deps: ShippingBindingDependencies): ShippingBindings;
+export {};

package/dist/shipping/bindings.js

@@ -0,0 +1,56 @@
+import { createCustomerAddressesHandler } from "./customerAddressesHandler.js";
+import { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
+import { createDeliveryOptionsHandler, createPickupPointSearchHandler, createPickupPointValidationHandler } from "./deliverySelectionHandler.js";
+/** Explicit selected stores and host validation; importing this module activates nothing. */
+export function createShippingBindings(deps) {
+    const native = deps.dataKind === "postgres";
+    const addressWrites = native ? "shipping_native_address_writes_unsupported" : null;
+    const nativeRateReady = typeof deps.nativeStore?.shippingRateDataPort?.getShippingFlatMinor === "function"
+        && typeof deps.nativeStore?.shippingRateDataPort?.setShippingFlatMinor === "function"
+        && typeof deps.nativeStore?.shippingRateDataPort?.recordPromotionAudit === "function"
+        && deps.nativeRateReadiness?.state === "ready"
+        && typeof deps.nativeRateReadiness.candidate?.database === "string"
+        && deps.nativeRateReadiness.candidate.database.length > 0
+        && deps.nativeRateSchema?.database === deps.nativeRateReadiness.candidate.database
+        && deps.nativeRateSchema.version === "20261021200000_shipping_flat_rate_seed"
+        && ["public.commerce_settings", "public.commerce_settings.value_minor", "public.commerce_settings.updated_at"].every(name => deps.nativeRateSchema?.objects?.some(entry => entry.present === true && entry.object?.name === name
+            && entry.object.kind === (name === "public.commerce_settings" ? "table" : "column")));
+    const flatRateSave = native && !nativeRateReady ? "shipping_native_flat_rate_save_unsupported" : null;
+    const refused = (reason) => ({
+        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 && flatRateSave)
+        return refused(flatRateSave);
+    const selected = 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 = { 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/dist/shipping/contracts/index.d.ts

@@ -1,3 +1,4 @@
 export type { DeliveryKind, DeliveryProviderKind, DeliveryCarrierKind, DeliveryService, PickupPoint, DeliveryOption, DeliveryOptionsResponse, PickupPointValidationRequest, PickupPointValidationResponse, PickupPointSearchRequest, PickupPointSearchResult, PickupPointSearchResponse, } from "./delivery.js";
 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/dist/shipping/contracts/threshold.d.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/dist/shipping/contracts/threshold.js

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

package/dist/shipping/index.d.ts

@@ -15,3 +15,20 @@ 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";
+/** Sparse canonical projections, never an install chain. */
+export declare const SHIPPING_MIGRATIONS: readonly [{
+    readonly id: "20260807140000_read_parity_catalog";
+    readonly catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql";
+    readonly position: 1;
+    readonly sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea";
+    readonly url: URL;
+}, {
+    readonly id: "20261021200000_shipping_flat_rate_seed";
+    readonly catalogPath: "db/platform/migrations/20261021200000_shipping_flat_rate_seed.sql";
+    readonly position: 72;
+    readonly sha256: "34f8696f515a2cc072395db5a3de2d9b09643d13236ee3851d0d78123f907eae";
+    readonly url: URL;
+}];

package/dist/shipping/index.js

@@ -6,3 +6,10 @@ export { createCustomerAddressesHandler } from "./customerAddressesHandler.js";
 export { canonicalAddressKey } from "./addressCanonical.js";
 export { readAddresses, readOrdererProfiles, addressUsedByActiveSubscription, addressRow, findCanonicalAddressId, clearDefaultAddress } from "./customerSelfServiceAddressModels.js";
 export { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
+export { createShippingBindings } from "./bindings.js";
+export { shippingTermsSchema, shippingPolicySchema, parseShippingTerms, hasShippingTerms, normalizeShippingPolicy, resolveShippingPolicy, resolveThresholdShipping } from "./thresholdPolicy.js";
+/** Sparse canonical projections, never an install chain. */
+export const SHIPPING_MIGRATIONS = [
+    { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+    { id: "20261021200000_shipping_flat_rate_seed", catalogPath: "db/platform/migrations/20261021200000_shipping_flat_rate_seed.sql", position: 72, sha256: "34f8696f515a2cc072395db5a3de2d9b09643d13236ee3851d0d78123f907eae", url: new URL("../../sql/20261021200000_shipping_flat_rate_seed.sql", import.meta.url) },
+];

package/dist/shipping/thresholdPolicy.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { ShippingPolicy, ShippingSettings, ShippingTerms } from "./contracts/threshold.js";
+export declare const shippingTermsSchema: z.ZodObject<{
+    version: z.ZodLiteral<"shipping-threshold.v1">;
+    currency: z.ZodString;
+    flatMinor: z.ZodNumber;
+    freeThresholdMinor: z.ZodNumber;
+}, z.core.$strict>;
+export declare const shippingPolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<"shipping-policy.v1">;
+    current: z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        flatMinor: z.ZodNumber;
+        freeThresholdMinor: z.ZodNumber;
+        effectiveFrom: z.ZodString;
+    }, z.core.$strict>>;
+    scheduled: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        flatMinor: z.ZodNumber;
+        freeThresholdMinor: z.ZodNumber;
+        effectiveFrom: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Absence selects legacy behavior; malformed retained promises refuse. */
+export declare function parseShippingTerms(value: unknown): ShippingTerms | undefined;
+export declare function hasShippingTerms(quote: {
+    context?: {
+        shippingTerms?: unknown;
+    };
+}): boolean;
+/** Resolve effective entries on read, without a scheduled write. */
+export declare function normalizeShippingPolicy(policy: ShippingPolicy, asOf: Date | string): ShippingPolicy;
+export declare function resolveShippingPolicy(settings: ShippingSettings, asOf: Date | string, currency: string): {
+    configured: boolean;
+    flatMinor: number;
+    terms?: ShippingTerms;
+};
+/** Only product payable after discounts counts; equality receives free delivery. */
+export declare function resolveThresholdShipping(terms: ShippingTerms, productPayableMinor: number): {
+    grossMinor: number;
+    remainingMinor: number;
+};

package/dist/shipping/thresholdPolicy.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+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) {
+    return value === undefined ? undefined : shippingTermsSchema.parse(value);
+}
+export function hasShippingTerms(quote) {
+    return quote.context?.shippingTerms !== undefined;
+}
+/** Resolve effective entries on read, without a scheduled write. */
+export function normalizeShippingPolicy(policy, asOf) {
+    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);
+    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, asOf, currency) {
+    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, productPayableMinor) {
+    const payable = minorSchema.parse(productPayableMinor);
+    const remainingMinor = Math.max(0, terms.freeThresholdMinor - payable);
+    return { grossMinor: remainingMinor > 0 ? terms.flatMinor : 0, remainingMinor };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.18.0",
+    "@openlup/core": "0.20.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"