@openlup/platform 0.17.0 → 0.19.0

package/dist/promotions/quotePromotionV2.js

@@ -0,0 +1,186 @@
+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, acquisition }) {
+    /** Automatic v2 benefits. Code claims remain outside quote evaluation. */
+    async function evaluateAutomaticPromotionV2(input) {
+        const byMode = input.clientId
+            ? await input.promoDataPort.countPaidOrdersByMode(input.clientId)
+            : { oneTime: 0, subscription: 0 };
+        const [rows, counts, deviceRedeemed] = await Promise.all([
+            input.promoDataPort.listActivePromotions(),
+            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",
+            cart_subtotal_minor: input.currentProductMinor,
+            shipping_amount_minor: input.shippingMinor,
+            client_orders_count: byMode.oneTime + byMode.subscription,
+            client_subscription_orders_count: byMode.subscription,
+            client_onetime_orders_count: byMode.oneTime,
+            device_first_order_redeemed: deviceRedeemed,
+            email_eligibility_confirmed: input.emailEligibilityConfirmed === true,
+            applied_codes: [],
+        };
+        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)
+            .filter((row) => {
+            const familyId = typeof row.v2_mirror_of === "string" ? row.v2_mirror_of : row.id;
+            const count = counts.get(familyId) ?? { global: 0, perCustomer: 0 };
+            return (row.redemption_limit_global == null || count.global < row.redemption_limit_global) &&
+                (!input.clientId || row.redemption_limit_per_customer == null || count.perCustomer < row.redemption_limit_per_customer);
+        });
+        const candidates = eligibleRows.map(toCandidate);
+        const result = evaluatePromotionAdjustmentsV2({
+            purchaseScope: input.mode === "subscription" ? "subscription_initial" : "one_time",
+            referenceProductMinor: input.referenceProductMinor,
+            currentProductMinor: input.currentProductMinor,
+            shippingMinor: input.shippingMinor,
+            minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+        }, candidates);
+        const v2Discounts = result.adjustments.map((adjustment) => {
+            const source = eligibleRows.find((row) => row.id === adjustment.promotionId);
+            const customerSemantic = source ? promotionCustomerSemantic(source) : undefined;
+            return {
+                promotionId: adjustment.promotionId,
+                label: adjustment.name,
+                appliesTo: adjustment.lane === "shipping" ? "shipping" : "order_total",
+                amountOffMinor: adjustment.amountOffMinor,
+                reasonCode: `promotion_v2:${adjustment.kind}`,
+                ...(customerSemantic ? { customerSemantic } : {}),
+            };
+        });
+        const legacyFloor = await evaluateOrderTotalDiscounts({
+            promoDataPort: legacyPromotionDataPort(acquisition
+                ? { ...input.promoDataPort, listActivePromotions: async () => effectiveRows } : input.promoDataPort),
+            clientId: input.clientId,
+            visitorId: input.visitorId,
+            mode: input.mode,
+            promoCodes: [...(input.promoCodes ?? [])],
+            regionCode: input.regionCode,
+            subtotalGrossMinor: input.currentProductMinor,
+            shippingGrossMinor: input.shippingMinor,
+            atTime: input.atTime,
+            emailEligibilityConfirmed: input.emailEligibilityConfirmed,
+        });
+        const discounts = withLegacyParityFloor(v2Discounts, reduceLegacyParityDiscounts(legacyFloor.discounts, input.promoCodes ?? []));
+        return {
+            discounts,
+            codeRejections: reconcileLegacyCodeOutcomes(input.promoCodes ?? [], discounts, legacyFloor),
+            ...(selection && input.acquisitionCapability === ACQUISITION_TERMS_CAPABILITY
+                ? { acquisitionTerms: selection.terms } : {}),
+        };
+    }
+    function legacyPromotionDataPort(port) {
+        return {
+            ...port,
+            listActivePromotions: async () => (await port.listActivePromotions()).filter((row) => row.promotion_engine_version !== "promotion-engine.v2"),
+        };
+    }
+    function toCandidate(row) {
+        const benefit = resolvePromotionBenefitDefinition(row);
+        const base = {
+            promotionId: row.id,
+            name: row.name,
+            source: "automatic",
+            scopes: ["one_time", "subscription_initial"],
+        };
+        if (benefit.kind === "target_percentage")
+            return { ...base, ...benefit };
+        if (benefit.kind === "percentage")
+            return { ...base, ...benefit };
+        if (benefit.kind === "fixed_amount")
+            return { ...base, ...benefit };
+        if (benefit.kind === "free_shipping")
+            return { ...base, ...benefit };
+        throw new Error("promotion_v2_benefit_invalid");
+    }
+    function withLegacyParityFloor(v2, legacy) {
+        return ["order_total", "shipping"].flatMap((lane) => {
+            const primary = v2.filter((item) => item.appliesTo === lane);
+            const floor = legacy.filter((item) => item.appliesTo === lane);
+            const primaryTotal = primary.reduce((sum, item) => sum + item.amountOffMinor, 0);
+            const floorTotal = floor.reduce((sum, item) => sum + item.amountOffMinor, 0);
+            if (floorTotal <= primaryTotal)
+                return primary;
+            return floor.map((item) => ({
+                ...item,
+                reasonCode: `promotion_v2:legacy_parity_floor:${item.reasonCode}`,
+            }));
+        });
+    }
+    /** Keep legacy's literal evaluation, then prevent one submitted identity from inflating its parity lane. */
+    function reduceLegacyParityDiscounts(discounts, submittedCodes) {
+        const firstSubmitted = new Map();
+        for (const code of submittedCodes) {
+            const identity = normalizeCode(code);
+            if (identity && !firstSubmitted.has(identity))
+                firstSubmitted.set(identity, code);
+        }
+        const chosen = new Map();
+        for (const [index, discount] of discounts.entries()) {
+            if (!discount.code)
+                continue;
+            const identity = normalizeCode(discount.code);
+            const submitted = firstSubmitted.get(identity);
+            if (!submitted)
+                continue;
+            const key = `${identity}:${discount.appliesTo}`;
+            const exact = discount.code === submitted;
+            const current = chosen.get(key);
+            if (!current || (exact && !current.exact))
+                chosen.set(key, { index, exact });
+        }
+        return discounts.filter((discount, index) => !discount.code || !firstSubmitted.has(normalizeCode(discount.code)) ||
+            chosen.get(`${normalizeCode(discount.code)}:${discount.appliesTo}`)?.index === index);
+    }
+    /**
+     * The parity floor evaluates legacy codes before the automatic-v2 lane winner is
+     * chosen. If that winner keeps equal-or-better money, turn a displaced applied
+     * legacy code into the stable neutral outcome instead of letting it disappear.
+     */
+    function reconcileLegacyCodeOutcomes(submittedCodes, discounts, legacy) {
+        const applied = new Set(discounts.flatMap((discount) => discount.code ? [normalizeCode(discount.code)] : []));
+        const legacyApplied = new Set(legacy.discounts.flatMap((discount) => discount.code ? [normalizeCode(discount.code)] : []));
+        const rejectionByCode = new Map();
+        for (const rejection of legacy.codeRejections) {
+            const identity = normalizeCode(rejection.code);
+            if (!rejectionByCode.has(identity))
+                rejectionByCode.set(identity, rejection);
+        }
+        const outcomes = [];
+        const seen = new Set();
+        for (const code of submittedCodes) {
+            const identity = normalizeCode(code);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            if (applied.has(identity))
+                continue;
+            const legacyRejection = rejectionByCode.get(identity);
+            if (legacyRejection) {
+                outcomes.push({ ...legacyRejection, code });
+            }
+            else if (legacyApplied.has(identity)) {
+                outcomes.push({ code, reason: "better_price_exists" });
+            }
+        }
+        return outcomes;
+    }
+    function normalizeCode(code) {
+        return code.trim().toUpperCase();
+    }
+    return { evaluateAutomaticPromotionV2, legacyPromotionDataPort };
+}

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/promotions/sql.d.ts

@@ -0,0 +1,14 @@
+/** Sparse projections of canonical units, never an install chain. */
+export declare const PROMOTIONS_MIGRATIONS: readonly [{
+    readonly id: "20260817180000_promotion_claim_lifecycle";
+    readonly catalogPath: "db/platform/migrations/20260817180000_promotion_claim_lifecycle.sql";
+    readonly position: 47;
+    readonly sha256: "86ba6f2e610ea2d2a39057c029a1fc7f106fc94f1658becf719a41e14ddabc7d";
+    readonly url: URL;
+}, {
+    readonly id: "20260817180100_promotion_claim_lifecycle_validation";
+    readonly catalogPath: "db/platform/migrations/20260817180100_promotion_claim_lifecycle_validation.sql";
+    readonly position: 48;
+    readonly sha256: "a958ce7b18762e43ef15e34b5ff947fc1d6a9b6aa419bca5f2b84e412ac14868";
+    readonly url: URL;
+}];

package/dist/promotions/sql.js

@@ -0,0 +1,5 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const PROMOTIONS_MIGRATIONS = [
+    { id: "20260817180000_promotion_claim_lifecycle", catalogPath: "db/platform/migrations/20260817180000_promotion_claim_lifecycle.sql", position: 47, sha256: "86ba6f2e610ea2d2a39057c029a1fc7f106fc94f1658becf719a41e14ddabc7d", url: new URL("../../sql/20260817180000_promotion_claim_lifecycle.sql", import.meta.url) },
+    { id: "20260817180100_promotion_claim_lifecycle_validation", catalogPath: "db/platform/migrations/20260817180100_promotion_claim_lifecycle_validation.sql", position: 48, sha256: "a958ce7b18762e43ef15e34b5ff947fc1d6a9b6aa419bca5f2b84e412ac14868", url: new URL("../../sql/20260817180100_promotion_claim_lifecycle_validation.sql", import.meta.url) },
+];

package/dist/promotions/validation.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/promotions/validation.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/dist/shipping/addressCanonLookupHandler.d.ts

@@ -0,0 +1,7 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { AddressCanonLookupDeps } from "./addressPorts.js";
+import type { AddressLookupSchemas } from "./addressSchemas.js";
+export declare function createAddressCanonPostalCodeHandler({ lookupPort }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAddressCanonLocalitiesHandler({ lookupPort }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAddressCanonStreetsHandler({ lookupPort }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/shipping/addressCanonLookupHandler.js

@@ -0,0 +1,105 @@
+export function createAddressCanonPostalCodeHandler({ lookupPort }, schemas, responder) {
+    const { addressCanonPostalCodeLookupRequestSchema, addressCanonPostalCodeLookupResponseSchema } = schemas;
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        const parsed = addressCanonPostalCodeLookupRequestSchema.safeParse({
+            postalCode: readQuery(req, "postalCode"),
+            limit: readLimit(req, 10),
+        });
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid address canon postal-code request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await lookupPort.lookupPostalCode(parsed.data);
+            const response = addressCanonPostalCodeLookupResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Address canon postal-code lookup failed validation");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Address canon postal-code lookup failed");
+        }
+    };
+}
+export function createAddressCanonLocalitiesHandler({ lookupPort }, schemas, responder) {
+    const { addressCanonLocalitiesLookupRequestSchema, addressCanonLocalitiesLookupResponseSchema } = schemas;
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        const parsed = addressCanonLocalitiesLookupRequestSchema.safeParse({
+            q: readQuery(req, "q"),
+            limit: readLimit(req, 10),
+        });
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid address canon localities request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await lookupPort.searchLocalities(parsed.data);
+            const response = addressCanonLocalitiesLookupResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Address canon localities lookup failed validation");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Address canon localities lookup failed");
+        }
+    };
+}
+export function createAddressCanonStreetsHandler({ lookupPort }, schemas, responder) {
+    const { addressCanonStreetsLookupRequestSchema, addressCanonStreetsLookupResponseSchema } = schemas;
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        const parsed = addressCanonStreetsLookupRequestSchema.safeParse({
+            localityId: readQuery(req, "localityId"),
+            q: readOptionalQuery(req, "q"),
+            limit: readLimit(req, 20),
+        });
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid address canon streets request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await lookupPort.listStreets(parsed.data);
+            const response = addressCanonStreetsLookupResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Address canon streets lookup failed validation");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Address canon streets lookup failed");
+        }
+    };
+}
+function readQuery(req, key) {
+    const value = req.query?.[key];
+    return Array.isArray(value) ? value[0] : value;
+}
+function readOptionalQuery(req, key) {
+    const value = readQuery(req, key)?.trim();
+    return value || undefined;
+}
+function readLimit(req, fallback) {
+    const raw = readQuery(req, "limit");
+    if (!raw)
+        return fallback;
+    return Number(raw);
+}

package/dist/shipping/addressCanonical.d.ts

@@ -0,0 +1,2 @@
+import type { CanonicalAddressInput } from "./contracts/address.js";
+export declare function canonicalAddressKey(input: CanonicalAddressInput, defaultCountry: string): string;

package/dist/shipping/addressCanonical.js

@@ -0,0 +1,26 @@
+export function canonicalAddressKey(input, defaultCountry) {
+    return [
+        normalise(input.clientId ?? ""),
+        normaliseKind(input.kind),
+        normalise(input.country ?? defaultCountry),
+        normalisePostalCode(input.postalCode),
+        normalise(input.city),
+        normalise(input.line1),
+        normalise(input.line2 ?? ""),
+    ].join("|");
+}
+function normaliseKind(value) {
+    return value === "billing" || value === "shipping" || value === "both" ? value : "shipping";
+}
+function normalisePostalCode(value) {
+    return value.replace(/[\s-]+/g, "").toUpperCase();
+}
+function normalise(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/ł/g, "l")
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/\s+/g, " ");
+}

package/dist/shipping/addressPorts.d.ts

@@ -0,0 +1,39 @@
+import type { AddressCanonLocalitiesLookupRequest, AddressCanonLocalitiesLookupResponse, AddressCanonPostalCodeLookupRequest, AddressCanonPostalCodeLookupResponse, AddressCanonStreetsLookupRequest, AddressCanonStreetsLookupResponse } from "./contracts/address.js";
+export interface AddressCanonLookupPort {
+    lookupPostalCode(request: AddressCanonPostalCodeLookupRequest): Promise<AddressCanonPostalCodeLookupResponse>;
+    searchLocalities(request: AddressCanonLocalitiesLookupRequest): Promise<AddressCanonLocalitiesLookupResponse>;
+    listStreets(request: AddressCanonStreetsLookupRequest): Promise<AddressCanonStreetsLookupResponse>;
+}
+import type { HttpRequest } from "../http/index.js";
+import type { CustomerAddressesResponse, CustomerAddressUpsertRequest, CustomerAddressDeleteRequest } from "./contracts/address.js";
+export interface AddressCanonLookupDeps {
+    lookupPort: AddressCanonLookupPort;
+}
+export interface CustomerAddressBookPort {
+    getAddressBook(userId: string): Promise<CustomerAddressesResponse | null>;
+}
+export interface CustomerAddressMutationPort {
+    upsertAddress(userId: string, input: CustomerAddressUpsertRequest): Promise<CustomerAddressesResponse | null>;
+    deleteAddress(userId: string, input: CustomerAddressDeleteRequest): Promise<CustomerAddressesResponse | null>;
+}
+export interface CustomerAddressesDeps {
+    addressBookPort: CustomerAddressBookPort;
+    addressMutationPort?: CustomerAddressMutationPort;
+    authenticateUser: (req: HttpRequest) => Promise<{
+        ok: true;
+        userId: string;
+    } | {
+        ok: false;
+        code: "UNAUTHORIZED";
+        message: string;
+    }>;
+}
+type Row = Record<string, unknown>;
+export interface CustomerAddressReadStore {
+    readAddresses(clientId: string): Promise<Row[]>;
+    readOrdererProfiles(clientId: string): Promise<Row[]>;
+    addressUsedByActiveSubscription(clientId: string, addressId: string): Promise<boolean>;
+    findCanonicalAddressId(clientId: string, canonicalKey: string): Promise<string | null>;
+    clearDefaultAddress(clientId: string, kind: string, updatedAt: string): Promise<void>;
+}
+export {};

package/dist/shipping/addressPorts.js

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

package/dist/shipping/addressSchemas.d.ts

@@ -0,0 +1,30 @@
+import type { AddressCanonPostalCodeLookupRequest, AddressCanonPostalCodeLookupResponse, AddressCanonLocalitiesLookupRequest, AddressCanonLocalitiesLookupResponse, AddressCanonStreetsLookupRequest, AddressCanonStreetsLookupResponse, CustomerAddressesRequest, CustomerAddressesResponse, CustomerAddressUpsertRequest, CustomerAddressDeleteRequest } from "./contracts/address.js";
+type Schema<T> = {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            flatten(): unknown;
+        };
+    };
+};
+/** Host-owned format, source and geographic validation. */
+export interface AddressLookupSchemas {
+    addressCanonPostalCodeLookupRequestSchema: Schema<AddressCanonPostalCodeLookupRequest>;
+    addressCanonPostalCodeLookupResponseSchema: Schema<AddressCanonPostalCodeLookupResponse>;
+    addressCanonLocalitiesLookupRequestSchema: Schema<AddressCanonLocalitiesLookupRequest>;
+    addressCanonLocalitiesLookupResponseSchema: Schema<AddressCanonLocalitiesLookupResponse>;
+    addressCanonStreetsLookupRequestSchema: Schema<AddressCanonStreetsLookupRequest>;
+    addressCanonStreetsLookupResponseSchema: Schema<AddressCanonStreetsLookupResponse>;
+}
+/** Host-owned validation and mutation-conflict identity. */
+export interface CustomerAddressSchemas {
+    customerAddressesRequestSchema: Schema<CustomerAddressesRequest>;
+    customerAddressesResponseSchema: Schema<CustomerAddressesResponse>;
+    customerAddressUpsertRequestSchema: Schema<CustomerAddressUpsertRequest>;
+    customerAddressDeleteRequestSchema: Schema<CustomerAddressDeleteRequest>;
+    isMutationConflict(error: unknown): error is Error;
+}
+export {};

package/dist/shipping/addressSchemas.js

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

package/dist/shipping/adminShippingRateHandler.d.ts

@@ -0,0 +1,4 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { AdminShippingRateHandlerDeps, ShippingRateHandlerSchemas } from "./shippingRatePorts.js";
+export declare function createAdminShippingRateHandler({ dataPort, authorizeAdmin, resolveAdmin, }: AdminShippingRateHandlerDeps, schemas: ShippingRateHandlerSchemas, responder: BffResponder): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/shipping/adminShippingRateHandler.js

@@ -0,0 +1,64 @@
+export function createAdminShippingRateHandler({ dataPort, authorizeAdmin, resolveAdmin, }, schemas, responder) {
+    const { adminShippingRateResponseSchema, adminSetShippingRateRequestSchema, adminSetShippingRateResponseSchema, contractVersion: COMMERCE_CONTRACT_VERSION } = schemas;
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "GET" && req.method !== "POST") {
+            sendMethodNotAllowed(res, ["GET", "POST"]);
+            return;
+        }
+        const authz = await resolveAdmin(authorizeAdmin, res);
+        if (!authz)
+            return;
+        if (req.method === "GET") {
+            try {
+                const shippingFlatMinor = await dataPort.getShippingFlatMinor();
+                const response = adminShippingRateResponseSchema.safeParse({
+                    contractVersion: COMMERCE_CONTRACT_VERSION,
+                    shippingFlatMinor,
+                });
+                if (!response.success) {
+                    sendBffError(res, "INVALID_RESPONSE", "Shipping rate returned invalid response");
+                    return;
+                }
+                sendBffSuccess(res, response.data);
+            }
+            catch {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipping rate read failed");
+            }
+            return;
+        }
+        const parsed = adminSetShippingRateRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid shipping rate request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        try {
+            await dataPort.setShippingFlatMinor(parsed.data.shippingFlatMinor);
+            // Best-effort audit (never blocks the mutation result).
+            await dataPort
+                .recordPromotionAudit({
+                actorId: authz.userId,
+                actorEmail: null,
+                action: "shipping_rate_change",
+                promotionId: "shipping_flat_minor",
+                newValue: { shippingFlatMinor: parsed.data.shippingFlatMinor },
+            })
+                .catch(() => undefined);
+            const response = adminSetShippingRateResponseSchema.safeParse({
+                contractVersion: COMMERCE_CONTRACT_VERSION,
+                updated: true,
+                shippingFlatMinor: parsed.data.shippingFlatMinor,
+            });
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Shipping rate set returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipping rate set failed");
+        }
+    };
+}

package/dist/shipping/bindings.d.ts

@@ -0,0 +1,57 @@
+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 declare function createShippingBindings(deps: ShippingBindingDependencies): ShippingBindings;
+export {};