@openlup/platform 0.17.0 → 0.18.0

package/src/shipping/contracts/delivery.ts

@@ -0,0 +1,114 @@
+export type DeliveryKind = "parcel-locker" | "courier";
+export type DeliveryProviderKind = string;
+export type DeliveryCarrierKind = string;
+export type DeliveryService = string;
+
+export interface PickupPoint {
+  id: string;
+  provider: DeliveryCarrierKind;
+  name: string;
+  address: { line1: string; postalCode: string; city: string; country: string };
+}
+export interface DeliveryOption {
+  id: string;
+  kind: DeliveryKind;
+  deliveryKind: DeliveryKind;
+  providerKind: DeliveryProviderKind;
+  carrierKind: DeliveryCarrierKind;
+  carrierCode: string;
+  service: DeliveryService;
+  serviceCode: string;
+  label: string;
+  description: string;
+  pickupPointRequired: boolean;
+  addressRequired: boolean;
+}
+export interface DeliveryOptionsResponse {
+  contractVersion: "shipping.delivery_selection.v1";
+  options: DeliveryOption[];
+}
+export interface PickupPointValidationRequest { pointId: string; carrierKind: DeliveryCarrierKind }
+export interface PickupPointValidationResponse {
+  contractVersion: "shipping.delivery_selection.v1";
+  valid: boolean;
+  pickupPoint: PickupPoint | null;
+}
+export interface PickupPointSearchRequest {
+  carrierKind: DeliveryCarrierKind;
+  latitude?: number;
+  longitude?: number;
+  postalCode?: string;
+  city?: string;
+  query?: string;
+  limit?: number;
+}
+export interface PickupPointSearchResult {
+  id: string;
+  carrierKind: DeliveryCarrierKind;
+  name: string;
+  address: PickupPoint["address"];
+  location: { latitude: number; longitude: number } | null;
+  locationDescription: string | null;
+  openingHours: string | null;
+  distanceMeters: number | null;
+  pointKind: "locker" | "service_point" | null;
+  appAssisted: boolean;
+}
+export interface PickupPointSearchResponse {
+  contractVersion: "shipping.pickup_point_search.v1";
+  carrierKind: DeliveryCarrierKind;
+  points: PickupPointSearchResult[];
+}
+
+export type DeliverySelectionSummaryKind = "courier" | "parcel-locker";
+
+export interface DeliverySelectionSummary {
+  deliveryKind: DeliverySelectionSummaryKind;
+  providerKind: string | null;
+  carrierKind: string | null;
+  carrierCode: string | null;
+  serviceCode: string | null;
+  pickupPoint: {
+    id: string;
+    name: string;
+    address: {
+      line1: string;
+      postalCode: string;
+      city: string;
+      country: string;
+    } | null;
+  } | null;
+  source?: string | null;
+}
+
+export type DeliverySelectionSourceKey =
+  | "shippingDeliveryContact"
+  | "orderDeliveryContactOverride"
+  | "orderDeliveryContact"
+  | "fulfillmentMetadata"
+  | "orderMetadata"
+  | "orderRuntimeFinalize"
+  | "shippingAddressSnapshot"
+  | "addressMetadata";
+
+export interface DeliverySelectionSources {
+  /** commerce_fulfillment_orders.metadata.selectedDelivery */
+  fulfillmentMetadata?: unknown;
+  /** commerce_orders.metadata.selectedDelivery (and .runtimeFinalize.selectedDelivery) */
+  orderMetadata?: unknown;
+  /** shipping_address_snapshot.selectedDelivery */
+  shippingAddressSnapshot?: unknown;
+  /** addresses.metadata.selectedDelivery */
+  addressMetadata?: unknown;
+}
+
+export interface DeliverySelectionEvidence {
+  /** The canonical selectedDelivery object, or null when no source carries one. */
+  selection: Record<string, unknown> | null;
+  /** Normalized (trimmed, lowercased) providerKind, or null when absent/blank. */
+  providerKind: string | null;
+  /** Which authoritative source was resolved (priority order), or null. A
+   * canonical contact can be the source even when its selection is invalid. */
+  source: DeliverySelectionSourceKey | null;
+}
+

package/src/shipping/contracts/index.ts

@@ -0,0 +1,18 @@
+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";

package/src/shipping/contracts/shippingRate.ts

@@ -0,0 +1,7 @@
+/** Browser DTOs for the incumbent flat-rate administration API. */
+export interface AdminShippingRateResponse {
+  contractVersion: "commerce.v0";
+  shippingFlatMinor: number;
+}
+export interface AdminSetShippingRateRequest { shippingFlatMinor: number }
+export interface AdminSetShippingRateResponse extends AdminShippingRateResponse { updated: true }

package/src/shipping/customerAddressesHandler.ts

@@ -0,0 +1,100 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { CustomerAddressesDeps } from "./addressPorts.js";
+import type { CustomerAddressSchemas } from "./addressSchemas.js";
+
+export function createCustomerAddressesHandler({
+  addressBookPort,
+  addressMutationPort,
+  authenticateUser,
+}: CustomerAddressesDeps, schemas: CustomerAddressSchemas, responder: BffResponder) {
+  const { customerAddressesResponseSchema, isMutationConflict } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (!["GET", "POST", "PATCH", "DELETE"].includes(req.method ?? "")) {
+      sendMethodNotAllowed(res, ["GET", "POST", "PATCH", "DELETE"]);
+      return;
+    }
+
+    let authentication: Awaited<ReturnType<CustomerAddressesDeps["authenticateUser"]>>;
+    try {
+      authentication = await authenticateUser(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer authentication failed");
+      return;
+    }
+
+    if (authentication.ok === false) {
+      sendBffError(res, authentication.code, authentication.message);
+      return;
+    }
+
+    try {
+      const addressBook = await runAddressRequest(req, authentication.userId, {
+        addressBookPort,
+        addressMutationPort,
+      }, schemas);
+      if (!addressBook) {
+        sendBffError(res, "FORBIDDEN", "No customer account linked to this session");
+        return;
+      }
+
+      const response = customerAddressesResponseSchema.safeParse(addressBook);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Customer addresses returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      if (error instanceof InvalidAddressRequest) {
+        sendBffError(res, "BAD_REQUEST", error.message, {
+          details: error.validation.flatten(),
+        });
+        return;
+      }
+      if (isMutationConflict(error)) {
+        sendBffError(res, "CONFLICT", error.message);
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer addresses request failed");
+    }
+  };
+}
+
+async function runAddressRequest(
+  req: HttpRequest,
+  userId: string,
+  ports: Pick<CustomerAddressesDeps, "addressBookPort" | "addressMutationPort">,
+  schemas: CustomerAddressSchemas,
+) {
+  const { customerAddressesRequestSchema, customerAddressDeleteRequestSchema, customerAddressUpsertRequestSchema } = schemas;
+  if (req.method === "GET") {
+    const request = customerAddressesRequestSchema.safeParse(req.query ?? {});
+    if (!request.success) throw new InvalidAddressRequest("Invalid customer addresses request", request.error);
+    return ports.addressBookPort.getAddressBook(userId);
+  }
+
+  if (!ports.addressMutationPort) {
+    throw new Error("Customer address mutations are not configured");
+  }
+
+  if (req.method === "DELETE") {
+    const request = customerAddressDeleteRequestSchema.safeParse(req.body);
+    if (!request.success) throw new InvalidAddressRequest("Invalid customer address delete request", request.error);
+    return ports.addressMutationPort.deleteAddress(userId, request.data);
+  }
+
+  const request = customerAddressUpsertRequestSchema.safeParse(req.body);
+  if (!request.success) throw new InvalidAddressRequest("Invalid customer address upsert request", request.error);
+  return ports.addressMutationPort.upsertAddress(userId, request.data);
+}
+
+class InvalidAddressRequest extends Error {
+  constructor(
+    message: string,
+    public readonly validation: { flatten: () => unknown },
+  ) {
+    super(message);
+  }
+}

package/src/shipping/customerSelfServiceAddressModels.ts

@@ -0,0 +1,124 @@
+import type { CanonicalAddressInput, CustomerAddressUpsertRequest, CustomerAddress, CustomerOrdererProfile } from "./contracts/address.js";
+import type { CustomerAddressReadStore } from "./addressPorts.js";
+
+export async function readAddresses(store: CustomerAddressReadStore, clientId: string): Promise<CustomerAddress[]> {
+  return (await store.readAddresses(clientId)).map((row) => ({
+    addressId: text(row.id),
+    kind: text(row.kind) as CustomerAddress["kind"],
+    label: nullableText(row.label),
+    recipientName: nullableText(row.recipient_name),
+    contactPhone: nullableText(row.contact_phone),
+    companyName: nullableText(row.company_name),
+    taxId: nullableText(row.tax_id),
+    line1: text(row.line1),
+    line2: nullableText(row.line2),
+    city: text(row.city),
+    postalCode: text(row.postal_code),
+    country: text(row.country),
+    isDefault: Boolean(row.is_default),
+    deliveryNotes: nullableText(row.delivery_notes),
+    courierInstructions: nullableText(row.courier_instructions),
+    lastUsedAt: nullableText(row.last_used_at),
+    createdAt: text(row.created_at),
+    updatedAt: text(row.updated_at),
+  }));
+}
+
+export async function readOrdererProfiles(
+  store: CustomerAddressReadStore,
+  clientId: string,
+): Promise<CustomerOrdererProfile[]> {
+  return (await store.readOrdererProfiles(clientId)).map((row) => ({
+    profileId: text(row.id),
+    label: nullableText(row.label),
+    fullName: text(row.full_name),
+    email: text(row.email),
+    phone: nullableText(row.phone),
+    companyName: nullableText(row.company_name),
+    taxId: nullableText(row.tax_id),
+    companyVerificationLevel: companyVerificationLevel(row.company_verification_level),
+    companyIdentitySource: nullableText(row.company_identity_source),
+    companyIdentityEvidenceHash: nullableText(row.company_identity_evidence_hash),
+    isDefault: Boolean(row.is_default),
+    createdAt: text(row.created_at),
+    updatedAt: text(row.updated_at),
+  }));
+}
+
+export async function addressUsedByActiveSubscription(
+  store: CustomerAddressReadStore,
+  clientId: string,
+  addressId: string,
+) {
+  return store.addressUsedByActiveSubscription(clientId, addressId);
+}
+
+export function addressRow(clientId: string, input: CustomerAddressUpsertRequest, canonicalAddressKey: (input: CanonicalAddressInput) => string) {
+  return {
+    client_id: clientId,
+    kind: input.kind,
+    label: input.label ?? null,
+    recipient_name: input.recipientName ?? null,
+    contact_phone: input.contactPhone ?? null,
+    company_name: input.companyName ?? null,
+    tax_id: input.taxId ?? null,
+    line1: input.line1,
+    line2: input.line2 ?? null,
+    city: input.city,
+    postal_code: input.postalCode,
+    country: input.country,
+    is_default: input.isDefault ?? false,
+    delivery_notes: input.deliveryNotes ?? null,
+    courier_instructions: input.courierInstructions ?? null,
+    canonical_key: canonicalAddressKey({
+      clientId,
+      kind: input.kind,
+      line1: input.line1,
+      line2: input.line2,
+      city: input.city,
+      postalCode: input.postalCode,
+      country: input.country,
+    }),
+    source: "customer_account",
+    updated_at: new Date().toISOString(),
+  };
+}
+
+export async function findCanonicalAddressId(
+  store: CustomerAddressReadStore,
+  clientId: string,
+  input: CustomerAddressUpsertRequest,
+  canonicalAddressKey: (input: CanonicalAddressInput) => string,
+): Promise<string | null> {
+  const key = canonicalAddressKey({
+    clientId,
+    kind: input.kind,
+    line1: input.line1,
+    line2: input.line2,
+    city: input.city,
+    postalCode: input.postalCode,
+    country: input.country,
+  });
+  return store.findCanonicalAddressId(clientId, key);
+}
+
+export async function clearDefaultAddress(store: CustomerAddressReadStore, clientId: string, kind: string) {
+  await store.clearDefaultAddress(clientId, kind, new Date().toISOString());
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function companyVerificationLevel(value: unknown): CustomerOrdererProfile["companyVerificationLevel"] {
+  return value === "registry_verified" ||
+    value === "provider_verified" ||
+    value === "manual_unverified" ||
+    value === "invalid"
+    ? value
+    : null;
+}

package/src/shipping/deliverySelectionHandler.ts

@@ -0,0 +1,94 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { DeliverySelectionSchemas } from "./handlerSchemas.js";
+import type { DeliverySelectionPort } from "./deliverySelectionPort.js";
+import type { PickupPointSearchPort } from "./pickupPointSearchPort.js";
+
+export const DELIVERY_SELECTION_CONTRACT_VERSION = "shipping.delivery_selection.v1";
+export const PICKUP_POINT_SEARCH_CONTRACT_VERSION = "shipping.pickup_point_search.v1";
+
+export function createDeliveryOptionsHandler(port: DeliverySelectionPort, schemas: DeliverySelectionSchemas, responder: BffResponder) {
+  const { deliveryOptionsResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const response = deliveryOptionsResponseSchema.safeParse({
+      contractVersion: DELIVERY_SELECTION_CONTRACT_VERSION,
+      options: await port.listOptions(),
+    });
+    if (!response.success) {
+      sendBffError(res, "INVALID_RESPONSE", "Delivery options returned invalid response");
+      return;
+    }
+
+    sendBffSuccess(res, response.data, { contractVersion: DELIVERY_SELECTION_CONTRACT_VERSION });
+  };
+}
+
+export function createPickupPointSearchHandler(port: PickupPointSearchPort, schemas: DeliverySelectionSchemas, responder: BffResponder) {
+  const { pickupPointSearchRequestSchema, pickupPointSearchResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = pickupPointSearchRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid pickup point search request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    const points = await port.searchPickupPoints(request.data);
+    const response = pickupPointSearchResponseSchema.safeParse({
+      contractVersion: PICKUP_POINT_SEARCH_CONTRACT_VERSION,
+      carrierKind: request.data.carrierKind,
+      points,
+    });
+    if (!response.success) {
+      sendBffError(res, "INVALID_RESPONSE", "Pickup point search returned invalid response");
+      return;
+    }
+
+    sendBffSuccess(res, response.data, { contractVersion: PICKUP_POINT_SEARCH_CONTRACT_VERSION });
+  };
+}
+
+export function createPickupPointValidationHandler(port: DeliverySelectionPort, schemas: DeliverySelectionSchemas, responder: BffResponder) {
+  const { pickupPointValidationRequestSchema, pickupPointValidationResponseSchema } = schemas;
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = pickupPointValidationRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid pickup point validation request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    const pickupPoint = await port.validatePickupPoint(request.data);
+    const response = pickupPointValidationResponseSchema.safeParse({
+      contractVersion: DELIVERY_SELECTION_CONTRACT_VERSION,
+      valid: Boolean(pickupPoint),
+      pickupPoint,
+    });
+    if (!response.success) {
+      sendBffError(res, "INVALID_RESPONSE", "Pickup point validation returned invalid response");
+      return;
+    }
+
+    sendBffSuccess(res, response.data, { contractVersion: DELIVERY_SELECTION_CONTRACT_VERSION });
+  };
+}

package/src/shipping/deliverySelectionPort.ts

@@ -0,0 +1,10 @@
+import type {
+  DeliveryCarrierKind,
+  DeliveryOption,
+  PickupPoint,
+} from "./contracts/index.js";
+
+export interface DeliverySelectionPort {
+  listOptions(): Promise<DeliveryOption[]>;
+  validatePickupPoint(input: { pointId: string; carrierKind: DeliveryCarrierKind }): Promise<PickupPoint | null>;
+}

package/src/shipping/deliverySelectionSummary.ts

@@ -0,0 +1,56 @@
+import type { DeliverySelectionSummary, DeliverySelectionSummaryKind } from "./contracts/delivery.js";
+
+export function summarizeDeliverySelection(
+  selection: Record<string, unknown> | null | undefined,
+  source: string | null = null,
+): DeliverySelectionSummary | null {
+  if (!selection) return null;
+  const deliveryKind = readDeliveryKind(selection.deliveryKind ?? selection.kind);
+  if (!deliveryKind) return null;
+  return {
+    deliveryKind,
+    providerKind: text(selection.providerKind),
+    carrierKind: text(selection.carrierKind),
+    carrierCode: text(selection.carrierCode),
+    serviceCode: text(selection.serviceCode ?? selection.service),
+    pickupPoint: deliveryKind === "parcel-locker" ? readPickupPoint(selection.pickupPoint) : null,
+    ...(source ? { source } : {}),
+  };
+}
+
+function readDeliveryKind(value: unknown): DeliverySelectionSummaryKind | null {
+  if (value === "courier" || value === "parcel-locker") return value;
+  return null;
+}
+
+function readPickupPoint(value: unknown): DeliverySelectionSummary["pickupPoint"] {
+  const point = record(value);
+  if (!point) return null;
+  const id = text(point.id ?? point.pointId);
+  const name = text(point.name);
+  if (!id || !name) return null;
+  return {
+    id,
+    name,
+    address: readPickupPointAddress(point.address),
+  };
+}
+
+function readPickupPointAddress(value: unknown): NonNullable<DeliverySelectionSummary["pickupPoint"]>["address"] {
+  const address = record(value);
+  if (!address) return null;
+  const line1 = text(address.line1);
+  const postalCode = text(address.postalCode);
+  const city = text(address.city);
+  const country = text(address.country);
+  if (!line1 || !postalCode || !city || !country) return null;
+  return { line1, postalCode, city, country };
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}

package/src/shipping/handlerSchemas.ts

@@ -0,0 +1,19 @@
+import type {
+  DeliveryOptionsResponse, PickupPointSearchRequest, PickupPointSearchResponse,
+  PickupPointValidationRequest, PickupPointValidationResponse,
+} from "./contracts/index.js";
+
+type Schema<T> = {
+  safeParse(input: unknown):
+    | { success: true; data: T }
+    | { success: false; error: { flatten(): unknown } };
+};
+
+/** The host supplies its existing validators, including provider policy and errors. */
+export interface DeliverySelectionSchemas {
+  deliveryOptionsResponseSchema: Schema<DeliveryOptionsResponse>;
+  pickupPointValidationRequestSchema: Schema<PickupPointValidationRequest>;
+  pickupPointValidationResponseSchema: Schema<PickupPointValidationResponse>;
+  pickupPointSearchRequestSchema: Schema<PickupPointSearchRequest>;
+  pickupPointSearchResponseSchema: Schema<PickupPointSearchResponse>;
+}

package/src/shipping/index.ts

@@ -0,0 +1,23 @@
+export type {
+  DeliverySelectionSummaryKind, DeliverySelectionSummary,
+  DeliverySelectionSourceKey, DeliverySelectionSources, DeliverySelectionEvidence,
+} from "./contracts/delivery.js";
+export type { DeliverySelectionPort } from "./deliverySelectionPort.js";
+export type { PickupPointSearchPort } from "./pickupPointSearchPort.js";
+export type { DeliverySelectionSchemas } from "./handlerSchemas.js";
+export {
+  createDeliveryOptionsHandler, createPickupPointSearchHandler, createPickupPointValidationHandler,
+  DELIVERY_SELECTION_CONTRACT_VERSION, PICKUP_POINT_SEARCH_CONTRACT_VERSION,
+} from "./deliverySelectionHandler.js";
+export { summarizeDeliverySelection } from "./deliverySelectionSummary.js";
+export { resolveDeliverySelectionEvidence } from "./readDeliverySelectionEvidence.js";
+export type { CanonicalAddressInput } from "./contracts/address.js";
+export type { AddressCanonLookupPort, AddressCanonLookupDeps, CustomerAddressesDeps, CustomerAddressBookPort, CustomerAddressMutationPort, CustomerAddressReadStore } from "./addressPorts.js";
+export type { AddressLookupSchemas, CustomerAddressSchemas } from "./addressSchemas.js";
+export { createAddressCanonPostalCodeHandler, createAddressCanonLocalitiesHandler, createAddressCanonStreetsHandler } from "./addressCanonLookupHandler.js";
+export { createCustomerAddressesHandler } from "./customerAddressesHandler.js";
+export { canonicalAddressKey } from "./addressCanonical.js";
+export { readAddresses, readOrdererProfiles, addressUsedByActiveSubscription, addressRow, findCanonicalAddressId, clearDefaultAddress } from "./customerSelfServiceAddressModels.js";
+export type { AdminShippingRateResponse, AdminSetShippingRateRequest, AdminSetShippingRateResponse } from "./contracts/shippingRate.js";
+export { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
+export type { AdminShippingRateHandlerDeps, ShippingRateDataPort, ShippingRateHandlerSchemas } from "./shippingRatePorts.js";

package/src/shipping/pickupPointSearchPort.ts

@@ -0,0 +1,8 @@
+import type {
+  PickupPointSearchRequest,
+  PickupPointSearchResult,
+} from "./contracts/index.js";
+
+export interface PickupPointSearchPort {
+  searchPickupPoints(request: PickupPointSearchRequest): Promise<PickupPointSearchResult[]>;
+}

package/src/shipping/readDeliverySelectionEvidence.ts

@@ -0,0 +1,51 @@
+import type { DeliverySelectionEvidence, DeliverySelectionSourceKey, DeliverySelectionSources } from "./contracts/delivery.js";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (Array.isArray(value)) return asRecord(value[0]);
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : null;
+}
+
+function normalizeProviderKind(selection: Record<string, unknown> | null): string | null {
+  const providerKind = selection?.providerKind;
+  return typeof providerKind === "string" && providerKind.trim()
+    ? providerKind.trim().toLowerCase()
+    : null;
+}
+
+// New-format order/parcel contacts are authoritative. The wider historical
+// ladder remains below them so old rows stay readable without letting a mutable
+// address-book selection replace a frozen provider request.
+export function resolveDeliverySelectionEvidence(
+  sources: DeliverySelectionSources,
+): DeliverySelectionEvidence {
+  const orderMetadata = asRecord(sources.orderMetadata);
+  const runtimeFinalize = asRecord(orderMetadata?.runtimeFinalize);
+  const shippingSnapshot = asRecord(sources.shippingAddressSnapshot);
+  const canonical: Array<[DeliverySelectionSourceKey, unknown]> = [
+    ["shippingDeliveryContact", shippingSnapshot?.deliveryContact],
+    ["orderDeliveryContactOverride", orderMetadata?.deliveryContactOverride],
+    ["orderDeliveryContact", runtimeFinalize?.deliveryContact],
+  ];
+  for (const [source, contactValue] of canonical) {
+    if (contactValue === undefined || contactValue === null) continue;
+    const selection = asRecord(asRecord(contactValue)?.selectedDelivery);
+    return { selection, providerKind: normalizeProviderKind(selection), source };
+  }
+
+  const legacy: Array<[DeliverySelectionSourceKey, unknown]> = [
+    ["fulfillmentMetadata", asRecord(sources.fulfillmentMetadata)?.selectedDelivery],
+    ["orderMetadata", orderMetadata?.selectedDelivery],
+    ["orderRuntimeFinalize", runtimeFinalize?.selectedDelivery],
+    ["shippingAddressSnapshot", shippingSnapshot?.selectedDelivery],
+    ["addressMetadata", asRecord(sources.addressMetadata)?.selectedDelivery],
+  ];
+
+  for (const [source, candidate] of legacy) {
+    const selection = asRecord(candidate);
+    if (selection) {
+      return { selection, providerKind: normalizeProviderKind(selection), source };
+    }
+  }
+
+  return { selection: null, providerKind: null, source: null };
+}

package/src/shipping/shippingRatePorts.ts

@@ -0,0 +1,36 @@
+import type { HttpResponse } from "../http/index.js";
+import type { AdminShippingRateResponse, AdminSetShippingRateRequest, AdminSetShippingRateResponse } from "./contracts/shippingRate.js";
+
+/** Only the incumbent flat-rate reads, writes and best-effort audit. */
+export interface ShippingRateDataPort {
+  getShippingFlatMinor(): Promise<number>;
+  setShippingFlatMinor(minor: number): Promise<void>;
+  recordPromotionAudit(entry: {
+    actorId: string;
+    actorEmail: string | null;
+    action: "shipping_rate_change";
+    promotionId: string;
+    newValue: Record<string, unknown>;
+  }): Promise<void>;
+}
+type Authorization =
+  | { ok: true; userId: string; role: "admin" | "distributor"; isMachineActor: boolean }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string; identityCode?: string };
+export interface AdminShippingRateHandlerDeps {
+  dataPort: ShippingRateDataPort;
+  authorizeAdmin: () => Promise<Authorization>;
+  /** The host retains its authorization/error response context. */
+  resolveAdmin: (authorizeAdmin: () => Promise<Authorization>, res: HttpResponse) => Promise<{ userId: string } | null>;
+}
+type Schema<T> = {
+  safeParse(input: unknown):
+    | { success: true; data: T }
+    | { success: false; error: { flatten(): unknown } };
+};
+/** Required host validation; there is no default amount policy. */
+export interface ShippingRateHandlerSchemas {
+  contractVersion: AdminShippingRateResponse["contractVersion"];
+  adminShippingRateResponseSchema: Schema<AdminShippingRateResponse>;
+  adminSetShippingRateRequestSchema: Schema<AdminSetShippingRateRequest>;
+  adminSetShippingRateResponseSchema: Schema<AdminSetShippingRateResponse>;
+}