@openlup/platform 0.16.0 → 0.18.0

package/src/promotions/quotePromotionV2.ts

@@ -0,0 +1,223 @@
+import { evaluatePromotionAdjustmentsV2, promoEligibilityFailure } from "@openlup/core/promo";
+import type {
+  PromoEvaluationCart,
+  PromotionAdjustmentCandidate,
+  PromotionRow,
+} from "@openlup/core/promo";
+import type { CommerceCodeRejection, CommerceQuoteDiscount } from "../pricing/index.js";
+import type { CreateQuoteRequest } from "../pricing/index.js";
+import type { CommercePromoDataPort } from "./promoDataPort.js";
+import { resolvePromotionBenefitDefinition } from "./promotionBenefitDefinition.js";
+import type { createQuotePromoDiscounts } from "./quotePromoDiscounts.js";
+type V2Row = PromotionRow & {
+  promotion_engine_version?: unknown;
+  benefit_lane?: unknown;
+  benefit_kind?: unknown;
+  benefit_value_bps?: unknown;
+  benefit_value_minor?: unknown;
+  v2_mirror_of?: unknown;
+};
+
+export function createQuotePromotionV2({ promotionCustomerSemantic, minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, evaluateOrderTotalDiscounts }: {
+  promotionCustomerSemantic: (row: PromotionRow) => CommerceQuoteDiscount["customerSemantic"];
+  minimumProductPayableMinor: number;
+  evaluateOrderTotalDiscounts: ReturnType<typeof createQuotePromoDiscounts>["evaluateOrderTotalDiscounts"];
+}) {
+  /** Automatic v2 benefits. Code claims remain outside quote evaluation. */
+  async function evaluateAutomaticPromotionV2(input: {
+    promoDataPort: CommercePromoDataPort;
+    clientId: string | null;
+    visitorId?: string | null;
+    mode: CreateQuoteRequest["mode"];
+    /** Raw request spellings stay intact for legacy exact-literal evaluation. */
+    promoCodes?: readonly string[];
+    regionCode: string;
+    referenceProductMinor: number;
+    currentProductMinor: number;
+    shippingMinor: number;
+    atTime: string;
+    emailEligibilityConfirmed?: boolean;
+  }): Promise<{ discounts: CommerceQuoteDiscount[]; codeRejections: CommerceCodeRejection[] }> {
+    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 cart: PromoEvaluationCart = {
+      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 = (rows 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)
+      .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: CommerceQuoteDiscount[] = 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(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),
+    };
+  }
+
+    function legacyPromotionDataPort(port: CommercePromoDataPort): CommercePromoDataPort {
+      return {
+        ...port,
+        listActivePromotions: async () => (await port.listActivePromotions()).filter(
+          (row) => (row as V2Row).promotion_engine_version !== "promotion-engine.v2",
+        ),
+      };
+    }
+
+    function toCandidate(row: V2Row): PromotionAdjustmentCandidate {
+      const benefit = resolvePromotionBenefitDefinition(row);
+      const base = {
+        promotionId: row.id,
+        name: row.name,
+        source: "automatic" as const,
+        scopes: ["one_time", "subscription_initial"] as const,
+      };
+      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: CommerceQuoteDiscount[],
+      legacy: CommerceQuoteDiscount[],
+    ): CommerceQuoteDiscount[] {
+      return (["order_total", "shipping"] as const).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: readonly CommerceQuoteDiscount[],
+      submittedCodes: readonly string[],
+    ): CommerceQuoteDiscount[] {
+      const firstSubmitted = new Map<string, string>();
+      for (const code of submittedCodes) {
+        const identity = normalizeCode(code);
+        if (identity && !firstSubmitted.has(identity)) firstSubmitted.set(identity, code);
+      }
+      const chosen = new Map<string, { index: number; exact: boolean }>();
+      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: readonly string[],
+      discounts: readonly CommerceQuoteDiscount[],
+      legacy: { discounts: readonly CommerceQuoteDiscount[]; codeRejections: readonly CommerceCodeRejection[] },
+    ): CommerceCodeRejection[] {
+      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<string, CommerceCodeRejection>();
+      for (const rejection of legacy.codeRejections) {
+        const identity = normalizeCode(rejection.code);
+        if (!rejectionByCode.has(identity)) rejectionByCode.set(identity, rejection);
+      }
+
+      const outcomes: CommerceCodeRejection[] = [];
+      const seen = new Set<string>();
+      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: string): string {
+      return code.trim().toUpperCase();
+    }
+
+    return { evaluateAutomaticPromotionV2, legacyPromotionDataPort };
+}

package/src/promotions/sql.ts

@@ -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) },
+] as const;

package/src/promotions/validation.ts

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

package/src/shipping/addressCanonLookupHandler.ts

@@ -0,0 +1,114 @@
+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 function createAddressCanonPostalCodeHandler({ lookupPort }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder) {
+  const { addressCanonPostalCodeLookupRequestSchema, addressCanonPostalCodeLookupResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    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 }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder) {
+  const { addressCanonLocalitiesLookupRequestSchema, addressCanonLocalitiesLookupResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    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 }: AddressCanonLookupDeps, schemas: AddressLookupSchemas, responder: BffResponder) {
+  const { addressCanonStreetsLookupRequestSchema, addressCanonStreetsLookupResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    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: HttpRequest, key: string): string | undefined {
+  const value = req.query?.[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function readOptionalQuery(req: HttpRequest, key: string): string | undefined {
+  const value = readQuery(req, key)?.trim();
+  return value || undefined;
+}
+
+function readLimit(req: HttpRequest, fallback: number): number {
+  const raw = readQuery(req, "limit");
+  if (!raw) return fallback;
+  return Number(raw);
+}

package/src/shipping/addressCanonical.ts

@@ -0,0 +1,31 @@
+import type { CanonicalAddressInput } from "./contracts/address.js";
+
+export function canonicalAddressKey(input: CanonicalAddressInput, defaultCountry: string): string {
+  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: string | null | undefined): string {
+  return value === "billing" || value === "shipping" || value === "both" ? value : "shipping";
+}
+
+function normalisePostalCode(value: string): string {
+  return value.replace(/[\s-]+/g, "").toUpperCase();
+}
+
+function normalise(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/ł/g, "l")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/\s+/g, " ");
+}

package/src/shipping/addressPorts.ts

@@ -0,0 +1,48 @@
+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>;
+}
+

package/src/shipping/addressSchemas.ts

@@ -0,0 +1,28 @@
+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;
+}

package/src/shipping/adminShippingRateHandler.ts

@@ -0,0 +1,72 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { AdminShippingRateHandlerDeps, ShippingRateHandlerSchemas } from "./shippingRatePorts.js";
+
+export function createAdminShippingRateHandler({
+  dataPort,
+  authorizeAdmin,
+  resolveAdmin,
+}: AdminShippingRateHandlerDeps, schemas: ShippingRateHandlerSchemas, responder: BffResponder) {
+  const { adminShippingRateResponseSchema, adminSetShippingRateRequestSchema, adminSetShippingRateResponseSchema, contractVersion: COMMERCE_CONTRACT_VERSION } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    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/src/shipping/contracts/address.ts

@@ -0,0 +1,71 @@
+export interface CanonicalAddressInput {
+  clientId?: string | null;
+  kind?: string | null;
+  line1: string;
+  line2?: string | null;
+  city: string;
+  postalCode: string;
+  country?: string | null;
+}
+
+export interface AddressCanonSource {
+  sourceKind: string;
+  status: "active" | "inactive" | "disabled_pending_license";
+  displayName: string;
+  officialUrl: string;
+  sourceRevision: string | null;
+  sourceUpdatedAt: string | null;
+}
+export interface AddressCanonLocalityCandidate {
+  localityId: string; countryCode: string; name: string; tercCode: string; simcCode: string;
+  municipalityName: string | null; municipalityTercCode: string | null;
+  countyName: string | null; voivodeshipName: string | null;
+  sources: AddressCanonSource[]; postalCode: string | null;
+  confidence: "exact" | "ambiguous" | "partial";
+  resolutionLevel: "postal_code" | "locality" | "street" | "address_point";
+}
+export interface AddressCanonStreet {
+  streetId: string; localityId: string; name: string; ulicCode: string | null; sources: AddressCanonSource[];
+}
+export interface AddressCanonPostalCodeLookupRequest { postalCode: string; limit: number }
+export interface AddressCanonLocalitiesLookupRequest { q: string; limit: number }
+export interface AddressCanonStreetsLookupRequest { localityId: string; q?: string; limit: number }
+export interface AddressCanonPostalCodeLookupResponse {
+  contractVersion: "address.canon.v1"; query: { postalCode: string }; resolutionLevel: "postal_code";
+  candidates: AddressCanonLocalityCandidate[]; sources: AddressCanonSource[];
+}
+export interface AddressCanonLocalitiesLookupResponse {
+  contractVersion: "address.canon.v1"; query: { q: string }; resolutionLevel: "locality";
+  candidates: AddressCanonLocalityCandidate[]; sources: AddressCanonSource[];
+}
+export interface AddressCanonStreetsLookupResponse {
+  contractVersion: "address.canon.v1"; query: { localityId: string; q: string | null }; resolutionLevel: "street";
+  streets: AddressCanonStreet[]; sources: AddressCanonSource[];
+}
+export type CustomerAddressKind = "shipping" | "billing" | "both";
+export interface CustomerAddress {
+  addressId: string; kind: CustomerAddressKind; label: string | null; recipientName: string | null;
+  contactPhone: string | null; companyName: string | null; taxId: string | null;
+  line1: string; line2: string | null; city: string; postalCode: string; country: string;
+  isDefault: boolean; deliveryNotes: string | null; courierInstructions: string | null;
+  lastUsedAt: string | null; createdAt: string; updatedAt: string;
+}
+export interface CustomerOrdererProfile {
+  profileId: string; label: string | null; fullName: string; email: string; phone: string | null;
+  companyName: string | null; taxId: string | null;
+  companyVerificationLevel?: "registry_verified" | "provider_verified" | "manual_unverified" | "invalid" | null;
+  companyIdentitySource?: string | null; companyIdentityEvidenceHash?: string | null;
+  isDefault: boolean; createdAt: string; updatedAt: string;
+}
+export type CustomerAddressesRequest = Record<string, never>;
+export interface CustomerAddressesResponse {
+  contractVersion: "customer.addresses.v1"; ordererProfiles: CustomerOrdererProfile[]; addresses: CustomerAddress[];
+}
+export interface CustomerAddressUpsertRequest {
+  idempotencyKey: string; addressId?: string; kind: CustomerAddressKind;
+  label?: string | null; recipientName?: string | null; contactPhone?: string | null;
+  companyName?: string | null; taxId?: string | null;
+  line1: string; line2?: string | null; city: string; postalCode: string; country?: string;
+  isDefault?: boolean; deliveryNotes?: string | null; courierInstructions?: string | null;
+}
+export interface CustomerAddressDeleteRequest { idempotencyKey: string; addressId: string }