@openlup/platform 0.17.0 → 0.19.0

package/src/shipping/bindings.ts

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

package/src/shipping/contracts/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 }

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,19 @@
+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/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/contracts/threshold.ts

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

package/src/shipping/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>;
+}