@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/omnipack/mappers.ts

@@ -0,0 +1,282 @@
+import {
+  mapOmnipackTrackingReferences,
+  type OmnipackTrackingReferenceEvidence,
+} from "./trackingReferences.js";
+
+export interface OmnipackOrderCreatedEvidence {
+  provider: "omnipack";
+  providerOrderId: string;
+  raw: Record<string, unknown>;
+}
+
+export interface OmnipackProductCreatedEvidence {
+  provider: "omnipack";
+  sku: string;
+  raw: Record<string, unknown>;
+}
+
+export interface OmnipackStockEvidence {
+  provider: "omnipack";
+  sku: string;
+  totalQuantity: number;
+  forSaleQuantity: number;
+  reservedOrUnavailableQuantity: number;
+  stockTruth: "external_stock_master_with_local_reservations";
+}
+
+export interface OmnipackStockMovementEvidence {
+  provider: "omnipack";
+  sku: string;
+  occurredAt: string | null;
+  quantity: number;
+  operationType: string | null;
+  warehouseDocumentNumber: string | null;
+  lotNumber: string | null;
+  expirationDate: string | null;
+}
+
+export interface OmnipackFulfilmentEvidence {
+  provider: "omnipack";
+  providerOrderId: string | null;
+  fulfilmentNumber: string;
+  externalNumber: string | null;
+  orderNumber: string | null;
+  createdAt: string | null;
+  updatedAt: string | null;
+  status: string | null;
+  subStatus: string | null;
+  trackingNumbers: string[];
+  trackingReferences: OmnipackTrackingReferenceEvidence[];
+  items: Array<{ sku: string; quantity: number; lotNumber: string | null; expirationDate: string | null }>;
+}
+
+export interface OmnipackFulfilmentRequestEvidence {
+  provider: "omnipack";
+  warehouseDocumentNumber: string;
+  warehouseName: string | null;
+  state: string | null;
+}
+
+export interface OmnipackWebhookEvidence {
+  rejectedTrackingRefs?: number;
+  rejectedServices?: number;
+  rejectedTrackingUrls?: number;
+  provider: "omnipack";
+  event: string;
+  providerOrderId: string | null;
+  orderNumber: string | null;
+  fulfilmentNumber: string | null;
+  occurredAt: string | null;
+  trackingNumbers: string[];
+  trackingReferences: OmnipackTrackingReferenceEvidence[];
+  shippingMethods: string[];
+}
+
+export function mapOmnipackOrderCreatedResponse(body: unknown): OmnipackOrderCreatedEvidence {
+  const response = asRecord(body);
+  const providerOrderId = readString(response.orderId);
+  if (!providerOrderId) throw new Error("omnipack_order_response_invalid");
+  return {
+    provider: "omnipack",
+    providerOrderId,
+    raw: sanitizeOmnipackPayload(response),
+  };
+}
+
+// Catalog load (test-readiness). The product/inbound responses are evidence only — we read
+// back authoritative stock via getStock. We tolerate a sparse response body and fall back to
+// the request-side sku/reference so an idempotent re-create still yields usable evidence.
+export function mapOmnipackProductCreatedResponse(body: unknown, requestSku: string): OmnipackProductCreatedEvidence {
+  const response = asRecord(body);
+  return {
+    provider: "omnipack",
+    sku: readString(response.sku) || requestSku,
+    raw: sanitizeOmnipackPayload(response),
+  };
+}
+
+export function mapOmnipackStockResponse(body: unknown): OmnipackStockEvidence[] {
+  const stockItems = readArray(asRecord(asRecord(body)._embedded).stockItems);
+  return stockItems.map((item) => {
+    const row = asRecord(item);
+    const totalQuantity = readNumber(row.totalQuantity);
+    const forSaleQuantity = readNumber(row.forSaleQuantity);
+    const unavailable = [
+      row.expireSoonQuantity,
+      row.faultyQuantity,
+      row.complaintsQuantity,
+      row.withheldQuantity,
+      row.packagingQuantity,
+      row.processingQuantity,
+      row.unpackingQuantity,
+    ].map(readNumber).reduce((sum, value) => sum + value, 0);
+    return {
+      provider: "omnipack",
+      sku: readString(row.sku),
+      totalQuantity,
+      forSaleQuantity,
+      reservedOrUnavailableQuantity: unavailable,
+      stockTruth: "external_stock_master_with_local_reservations",
+    };
+  });
+}
+
+export function mapOmnipackStockMovementsResponse(body: unknown): OmnipackStockMovementEvidence[] {
+  return readArray(asRecord(body)._embedded).map((item) => {
+    const row = asRecord(item);
+    return {
+      provider: "omnipack",
+      sku: readString(row.sku),
+      occurredAt: readNullableString(row.occurredAt),
+      quantity: readNumber(row.quantity),
+      operationType: readNullableString(row.operationType),
+      warehouseDocumentNumber: readNullableString(row.warehouseDocumentNumber),
+      lotNumber: readNullableString(row.productLotNumber),
+      expirationDate: readNullableString(row.expirationDate),
+    };
+  });
+}
+
+export function mapOmnipackFulfilmentsResponse(body: unknown): OmnipackFulfilmentEvidence[] {
+  const fulfilments = readArray(asRecord(asRecord(body)._embedded).fulfilments);
+  return fulfilments.map((item) => {
+    const row = asRecord(item);
+    const trackingReferences = trackingReferencesFrom(row);
+    return {
+      provider: "omnipack",
+      providerOrderId: readNullableString(row.orderId) ?? readNullableString(row.providerOrderId),
+      fulfilmentNumber: readString(row.fulfilmentNumber),
+      externalNumber: readNullableString(row.externalNumber),
+      orderNumber: readNullableString(row.orderNumber),
+      createdAt: readNullableString(row.createdAt),
+      updatedAt: readNullableString(row.updatedAt),
+      status: readNullableString(row.status),
+      subStatus: readNullableString(row.subStatus),
+      trackingNumbers: trackingReferences.map((ref) => ref.trackingNumber),
+      trackingReferences,
+      items: readArray(row.items).map((rawItem) => {
+        const fulfilmentItem = asRecord(rawItem);
+        return {
+          sku: readString(fulfilmentItem.sku),
+          quantity: readNumber(fulfilmentItem.quantity),
+          lotNumber: readNullableString(fulfilmentItem.productLotNumber),
+          expirationDate: readNullableString(fulfilmentItem.expirationDate),
+        };
+      }),
+    };
+  });
+}
+
+export function mapOmnipackFulfilmentRequestsResponse(body: unknown): OmnipackFulfilmentRequestEvidence[] {
+  const requests = readArray(asRecord(asRecord(body)._embedded).fulfilmentRequests);
+  return requests.map((item) => {
+    const row = asRecord(item);
+    return {
+      provider: "omnipack",
+      warehouseDocumentNumber: readString(row.warehouseDocumentNumber),
+      warehouseName: readNullableString(row.warehouseName),
+      state: readNullableString(row.state),
+    };
+  });
+}
+
+export function mapOmnipackWebhookPayload(body: unknown, fallbackEvent = "", admitTrackingNumber?: (value: string) => boolean,
+  admitMetadata?: { service(value: string): boolean; url(value: string): boolean }): OmnipackWebhookEvidence {
+  const payload = asRecord(body);
+  const shipments = readArray(payload.shipments).map(asRecord);
+  let rejectedTrackingRefs = 0, rejectedServices = 0, rejectedTrackingUrls = 0;
+  // Count every supplied spelling before extraction, tracking refusal or first-wins deduplication.
+  if (admitMetadata) for (const row of shipments) {
+    for (const value of [row.shippingMethod, row.service]) {
+      if (value != null && (typeof value !== "string" || !admitMetadata.service(value))) rejectedServices++;
+    }
+    for (const value of [row.trackingUrl, row.trackingURL, row.trackingLink, row.publicTrackingUrl]) {
+      if (value != null && (typeof value !== "string" || !admitMetadata.url(value))) rejectedTrackingUrls++;
+    }
+  }
+  // Admit and count original entries before the contributed extractor trims/deduplicates.
+  const admitted = admitTrackingNumber ? shipments.filter(row => {
+    if (admitTrackingNumber(readString(row.trackingNo) || readString(row.trackingNumber))) return true;
+    rejectedTrackingRefs++; return false;
+  }) : shipments;
+  const trackingReferences = trackingReferencesFrom({ shipments: admitted });
+  return {
+    provider: "omnipack",
+    event: readString(payload.event) || fallbackEvent,
+    ...(rejectedTrackingRefs ? { rejectedTrackingRefs } : {}),
+    ...(admitMetadata ? { rejectedServices, rejectedTrackingUrls } : {}),
+    providerOrderId: readNullableString(payload.orderId) ?? readNullableString(payload.providerOrderId),
+    orderNumber: readNullableString(payload.orderNumber),
+    fulfilmentNumber: readNullableString(payload.fulfilmentNumber),
+    occurredAt: readNullableString(payload.occurredAt),
+    trackingNumbers: trackingReferences.map((ref) => ref.trackingNumber),
+    trackingReferences,
+    shippingMethods: shipments.map((shipment) => readString(shipment.shippingMethod)).filter(Boolean),
+  };
+}
+
+export function sanitizeOmnipackPayload(input: Record<string, unknown>): Record<string, unknown> {
+  const blocked = new Set([
+    "authorization",
+    "Authorization",
+    "password",
+    "email",
+    "phone",
+    "firstName",
+    "lastName",
+    "name",
+    "address",
+    "street",
+    "streetNumber",
+    "houseNo",
+    "flatNo",
+    "city",
+    "postalCode",
+  ]);
+  return sanitizeRecord(input, blocked);
+}
+
+function sanitizeRecord(input: Record<string, unknown>, blocked: Set<string>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input)
+      .filter(([key]) => !blocked.has(key))
+      .map(([key, value]) => [key, sanitizeValue(value, blocked)]),
+  );
+}
+
+function sanitizeValue(input: unknown, blocked: Set<string>): unknown {
+  if (Array.isArray(input)) return input.map((value) => sanitizeValue(value, blocked));
+  if (input && typeof input === "object") return sanitizeRecord(input as Record<string, unknown>, blocked);
+  return input;
+}
+
+function asRecord(input: unknown): Record<string, unknown> {
+  return input && typeof input === "object" && !Array.isArray(input) ? input as Record<string, unknown> : {};
+}
+
+function readArray(input: unknown): unknown[] {
+  return Array.isArray(input) ? input : [];
+}
+
+function readString(input: unknown): string {
+  return typeof input === "string" ? input : "";
+}
+
+function readNullableString(input: unknown): string | null {
+  const value = readString(input);
+  return value || null;
+}
+
+function readNumber(input: unknown): number {
+  return typeof input === "number" && Number.isFinite(input) ? input : 0;
+}
+
+function trackingReferencesFrom(row: Record<string, unknown>): OmnipackTrackingReferenceEvidence[] {
+  return mapOmnipackTrackingReferences({
+    shipments: readArray(row.shipments),
+    trackingNumbers: readArray(row.trackingNumbers),
+    readString,
+    readNullableString,
+    asRecord,
+  });
+}

package/src/fulfillment/omnipack/observation.ts

@@ -0,0 +1,79 @@
+import { admittedReference, reference } from "../dispatchProjection.js";
+import { projectObservation, publicTrackingUrl } from "../observationProjection.js";
+export { reference } from "../dispatchProjection.js";
+import { createHash } from "node:crypto";
+import { parseNormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentRefusal } from "../contracts/index.js";
+import type { OmnipackWebhookEvidence } from "./mappers.js";
+import type { OmnipackTrackingReferenceEvidence } from "./trackingReferences.js";
+import { buildProviderEventId, EVENT_TO_STATUS, type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
+import { localStatusFor } from "./omnipackStatusVocabulary.js";
+
+export const refusal = (reason: FulfillmentRefusal["reason"], phase: FulfillmentRefusal["phase"], retryable = false): FulfillmentRefusal => ({ reason, phase, retryable });
+export const digest = (bytes: string | Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+/** Share admission with the durable sink, including explicit deny allowlists. */
+export function correlationReference(value: string | null | undefined, codecs: OmnipackObservationCodecs = {}): string | null {
+  return admittedReference(value, codecs.approveReference);
+}
+export interface OmnipackObservationCodecs extends FulfillmentObservationCodecs {
+  normalizeCarrier?(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
+}
+export function timestamp(value: string | null): string | null {
+  return value && /^\d{4}-\d\d-\d\dT/u.test(value) && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+}
+export function eventKind(value: string): OmnipackWebhookRouteEvent | null {
+  return Object.hasOwn(EVENT_TO_STATUS, value) ? value as OmnipackWebhookRouteEvent : null;
+}
+function tracking(refs: OmnipackTrackingReferenceEvidence[], codecs: OmnipackObservationCodecs, approve: (url: string) => boolean) {
+  let rejectedTrackingRefs = 0, rejectedServices = 0, rejectedTrackingUrls = 0;
+  const trackingRefs: FulfillmentObservation["trackingRefs"][number][] = [];
+  for (const item of refs) {
+    if (item.service !== null && !correlationReference(item.service, codecs)) rejectedServices++;
+    if (item.trackingUrl !== null && !publicTrackingUrl(item.trackingUrl, approve, codecs.trackingUrl)) rejectedTrackingUrls++;
+    const trackingNumber = correlationReference(item.trackingNumber, codecs);
+    if (!trackingNumber) { rejectedTrackingRefs++; continue; }
+    // Service admission precedes any derivation. A refused service cannot leak a prefix.
+    const serviceRef = correlationReference(item.service, codecs);
+    const carrierRef = item.service !== null && !serviceRef ? null : reference(codecs.normalizeCarrier
+      ? codecs.normalizeCarrier({ carrierRef: item.carrier, serviceRef })
+      : serviceRef?.split("_")[0]?.toLowerCase());
+    trackingRefs.push({ trackingNumber, carrierRef, serviceRef: item.service, publicUrl: item.trackingUrl });
+  }
+  return { trackingRefs, rejectedTrackingRefs, rejectedServices, rejectedTrackingUrls };
+}
+export function observation(input: {
+  evidence: OmnipackWebhookEvidence; event: FulfillmentObservation["eventKind"]; status?: CanonicalLocalFulfillmentStatus;
+  receivedAt: string; rawDigest: string; evidenceRef: `evidence:${string}`;
+  source: "provider_webhook" | "provider_reconciliation"; fulfillmentRef?: string;
+  approveTrackingUrl: (url: string) => boolean;
+  observationCodecs?: OmnipackObservationCodecs;
+}): FulfillmentObservation {
+  const evidence = input.evidence;
+  const codecs = input.observationCodecs ?? {};
+  const externalRef = correlationReference(evidence.providerOrderId, codecs);
+  const providerFulfillmentRef = correlationReference(evidence.fulfilmentNumber, codecs);
+  const orderNumber = correlationReference(evidence.orderNumber, codecs);
+  const fulfillmentRef = reference(input.fulfillmentRef) ?? providerFulfillmentRef ?? externalRef ?? orderNumber;
+  if (!fulfillmentRef || input.source === "provider_webhook" && [evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => value !== null && !correlationReference(value, codecs))) throw refusal("missing_correlation", "normalize");
+  const occurredAt = timestamp(evidence.occurredAt);
+  if (evidence.occurredAt && !occurredAt) throw refusal("malformed", "normalize");
+  // Compose the key with the provider's
+  // original bytes, including minute precision and offsets, rather than the UTC fact.
+  const key = buildProviderEventId(evidence);
+  const normalizedTracking = tracking(evidence.trackingReferences, codecs, input.approveTrackingUrl);
+  const rejectedTrackingRefs = normalizedTracking.rejectedTrackingRefs + (evidence.rejectedTrackingRefs ?? 0)
+    + (evidence.rejectedServices ?? normalizedTracking.rejectedServices);
+  const status = input.status ?? localStatusFor(EVENT_TO_STATUS[input.event as OmnipackWebhookRouteEvent]);
+  const fact = parseNormalizedFulfillmentFact({
+    schemaVersion: 1, mapperVersion: "1", factId: digest(key), providerKind: "omnipack", fulfillmentReference: reference(fulfillmentRef) ?? digest(fulfillmentRef),
+    canonicalStatus: status, provenance: { source: input.source, authority: "provider_asserted" },
+    occurredAt, receivedAt: input.receivedAt,
+    rawEvent: { reference: input.evidenceRef, digestAlgorithm: "sha256", digest: input.rawDigest },
+  }, { isCanonicalStatus: (value): value is CanonicalLocalFulfillmentStatus =>
+    ["provider_received", "picking", "packed", "in_transit", "delivered", "exception", "cancelled"].includes(value) });
+  return projectObservation({ fact, eventKind: input.event, eventKey: key, firstReceivedAt: input.receivedAt,
+    correlation: { orderRef: null, fulfillmentRef: reference(input.fulfillmentRef), externalRef: evidence.providerOrderId, orderNumber: evidence.orderNumber, providerFulfillmentRef: evidence.fulfilmentNumber, parcelRef: null },
+    trackingRefs: normalizedTracking.trackingRefs, diagnostics: { admission: {
+      rejectedTrackingRefs, rejectedTrackingUrls: evidence.rejectedTrackingUrls ?? normalizedTracking.rejectedTrackingUrls,
+    } } }, input.approveTrackingUrl, codecs);
+}

package/src/fulfillment/omnipack/omnipackDispatchPayload.ts

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import {
+  buildOmnipackOutboundOrderEvidence,
+  buildOmnipackOutboundOrderPayload,
+  type OmnipackOutboundOrderPayload,
+  type OmnipackOutboundDeliverySelection,
+} from "./omnipackOutboundOrderPayload.js";
+// Structural slice consumed by the donor codec; persistence and orchestration stay outside.
+export interface OmnipackDispatchCandidate {
+  orderId: string;
+  orderNumber: string | null;
+  deliveryContact: {
+    revision: number;
+    recipientName: string | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    line1: string;
+    city: string;
+    postalCode: string;
+    country: string;
+    selectedDelivery: OmnipackOutboundDeliverySelection | null;
+  } | null;
+  lines: Array<{ sku: string; quantity: number; productSnapshot: Record<string, unknown> }>;
+}
+
+export { buildOmnipackOutboundOrderEvidence as buildSanitizedEvidence };
+
+export function buildOmnipackDispatchCommand(candidate: OmnipackDispatchCandidate) {
+  const providerPayload = buildOmnipackDispatchPayloadFromCandidate(candidate);
+  const sanitizedRequest = {
+    ...buildOmnipackOutboundOrderEvidence(providerPayload),
+    deliveryContactRevision: candidate.deliveryContact?.revision ?? 0,
+  };
+  const serialized = serializeOmnipackDispatchPayload(providerPayload);
+  return {
+    providerPayload,
+    body: serialized.body,
+    sanitizedRequest,
+    // The hash commits to the request that may create a real provider effect.
+    // Only its digest is persisted; the PII-bearing input is never evidence.
+    requestFingerprint: serialized.requestFingerprint,
+  };
+}
+
+export function buildOmnipackDispatchPayloadFromCandidate(
+  candidate: OmnipackDispatchCandidate,
+): OmnipackOutboundOrderPayload {
+  const contact = candidate.deliveryContact;
+  if (!contact) throw new Error("omnipack_order_payload_missing_delivery_contact");
+  return buildOmnipackOutboundOrderPayload({
+    orderNumber: candidate.orderNumber ?? candidate.orderId,
+    deliverySelection: contact.selectedDelivery,
+    recipient: {
+      name: contact.recipientName ?? "",
+      email: contact.contactEmail,
+      phone: contact.contactPhone,
+    },
+    address: {
+      line1: contact.line1,
+      city: contact.city,
+      postalCode: contact.postalCode,
+      country: contact.country,
+    },
+    items: candidate.lines.map((line) => ({
+      sku: line.sku,
+      quantity: line.quantity,
+      lotNumber: nullableText(line.productSnapshot.lotNumber ?? line.productSnapshot.lotCode),
+      expirationDate: nullableText(line.productSnapshot.expirationDate ?? line.productSnapshot.expiresAt),
+    })),
+  });
+}
+
+export function stableDispatchHash(value: unknown): string {
+  return serializeOmnipackDispatchPayload(value).requestFingerprint;
+}
+
+// Materialize once: the digest and createOrder consume these exact UTF-8 bytes.
+export function serializeOmnipackDispatchPayload(value: unknown): { body: string; requestFingerprint: string } {
+  const body = JSON.stringify(sortRecord(value));
+  return { body, requestFingerprint: createHash("sha256").update(body).digest("hex") };
+}
+
+function sortRecord(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortRecord);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).sort().map(([key, child]) => [key, sortRecord(child)]),
+  );
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/fulfillment/omnipack/omnipackOutboundOrderPayload.ts

@@ -0,0 +1,194 @@
+export type OmnipackOutboundDeliveryKind = "courier" | "parcel-locker";
+
+export interface OmnipackOutboundOrderInput {
+  orderNumber: string;
+  description?: string | null;
+  additionalCustomerOrderNumber?: string | null;
+  deliverySelection: OmnipackOutboundDeliverySelection | null;
+  recipient: {
+    name: string;
+    email: string | null;
+    phone: string | null;
+  };
+  address: {
+    line1: string;
+    city: string;
+    postalCode: string;
+    country: string;
+  };
+  items: Array<{
+    sku: string;
+    quantity: number;
+    lotNumber?: string | null;
+    expirationDate?: string | null;
+  }>;
+  orderValue?: { amount: number; currency: string } | null;
+}
+
+export interface OmnipackOutboundDeliverySelection {
+  providerKind?: string | null;
+  carrierKind?: string | null;
+  carrierCode?: string | null;
+  serviceCode?: string | null;
+  service?: string | null;
+  deliveryKind?: string | null;
+  kind?: string | null;
+  pickupPoint?: {
+    id?: string | null;
+    pointId?: string | null;
+    name?: string | null;
+    address?: {
+      line1?: string | null;
+      postalCode?: string | null;
+      city?: string | null;
+      country?: string | null;
+    } | null;
+  } | null;
+}
+
+export interface OmnipackOutboundOrderPayload {
+  orderNumber: string;
+  description?: string;
+  additionalCustomerOrderNumber?: string;
+  items: Array<{
+    sku: string;
+    quantity: number;
+    lotNumber?: string;
+    expirationDate?: string;
+  }>;
+  shippingDetails: {
+    carrier: string;
+    service: string;
+    address: {
+      name: string;
+      street: string;
+      city: string;
+      postCode: string;
+      phone: string;
+      email?: string;
+      country: string;
+    };
+    pickUpPoint?: string;
+  };
+  orderValue?: { amount: number; currency: string };
+}
+
+export class OmnipackOutboundOrderPayloadError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+    this.name = "OmnipackOutboundOrderPayloadError";
+  }
+}
+
+export function buildOmnipackOutboundOrderPayload(input: OmnipackOutboundOrderInput): OmnipackOutboundOrderPayload {
+  const orderNumber = requiredText(input.orderNumber, "omnipack_order_payload_missing_order_number");
+  const selection = input.deliverySelection;
+  const providerKind = optionalText(selection?.providerKind);
+  if (providerKind !== "omnipack") {
+    throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_missing_omnipack_delivery_selection");
+  }
+  const service = requiredText(selection?.serviceCode ?? selection?.service, "omnipack_order_payload_missing_service");
+  const carrier = service;
+  const deliveryKind = readDeliveryKind(selection);
+  const pickUpPoint = readPickUpPoint(deliveryKind, selection);
+  const items = input.items.map((item) => {
+    const lotNumber = optionalText(item.lotNumber);
+    const expirationDate = optionalText(item.expirationDate);
+    return {
+      sku: requiredText(item.sku, "omnipack_order_payload_missing_sku"),
+      quantity: requiredQuantity(item.quantity),
+      ...(lotNumber ? { lotNumber } : {}),
+      ...(expirationDate ? { expirationDate } : {}),
+    };
+  });
+  if (items.length === 0) {
+    throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_missing_items");
+  }
+
+  return compactRecord({
+    orderNumber,
+    description: optionalText(input.description),
+    additionalCustomerOrderNumber: optionalText(input.additionalCustomerOrderNumber),
+    items,
+    shippingDetails: compactRecord({
+      carrier,
+      service,
+      address: compactRecord({
+        name: requiredText(input.recipient.name, "omnipack_order_payload_missing_recipient_name"),
+        street: requiredText(input.address.line1, "omnipack_order_payload_missing_address_street"),
+        city: requiredText(input.address.city, "omnipack_order_payload_missing_address_city"),
+        postCode: requiredText(input.address.postalCode, "omnipack_order_payload_missing_address_post_code"),
+        phone: requiredText(input.recipient.phone, "omnipack_order_payload_missing_recipient_phone"),
+        email: optionalText(input.recipient.email),
+        country: requiredText(input.address.country, "omnipack_order_payload_missing_address_country"),
+      }),
+      pickUpPoint,
+    }),
+    orderValue: validOrderValue(input.orderValue),
+  }) as OmnipackOutboundOrderPayload;
+}
+
+export function buildOmnipackOutboundOrderEvidence(payload: OmnipackOutboundOrderPayload): Record<string, unknown> {
+  return {
+    provider: "omnipack",
+    requestKind: "outbound_order",
+    orderNumber: payload.orderNumber,
+    carrier: payload.shippingDetails.carrier,
+    service: payload.shippingDetails.service,
+    pickUpPoint: payload.shippingDetails.pickUpPoint ?? null,
+    itemCount: payload.items.length,
+    items: payload.items.map((item) => ({
+      sku: item.sku,
+      quantity: item.quantity,
+      lotNumber: item.lotNumber ?? null,
+      expirationDate: item.expirationDate ?? null,
+    })),
+    stockTruth: "external_stock_master_with_local_reservations",
+  };
+}
+
+function readDeliveryKind(selection: OmnipackOutboundDeliverySelection | null): OmnipackOutboundDeliveryKind {
+  const value = optionalText(selection?.deliveryKind ?? selection?.kind);
+  if (value === "courier" || value === "parcel-locker") return value;
+  throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_missing_delivery_kind");
+}
+
+function readPickUpPoint(
+  deliveryKind: OmnipackOutboundDeliveryKind,
+  selection: OmnipackOutboundDeliverySelection | null,
+): string | undefined {
+  if (deliveryKind !== "parcel-locker") return undefined;
+  const point = optionalText(selection?.pickupPoint?.id ?? selection?.pickupPoint?.pointId);
+  if (!point) throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_missing_pickup_point");
+  return point;
+}
+
+function requiredText(value: unknown, code: string): string {
+  const text = optionalText(value);
+  if (!text) throw new OmnipackOutboundOrderPayloadError(code);
+  return text;
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function requiredQuantity(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_invalid_quantity");
+  }
+  return value;
+}
+
+function validOrderValue(value: OmnipackOutboundOrderInput["orderValue"]): OmnipackOutboundOrderPayload["orderValue"] | undefined {
+  if (!value) return undefined;
+  if (typeof value.amount !== "number" || value.amount <= 0 || !Number.isFinite(value.amount)) {
+    throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_invalid_order_value");
+  }
+  const currency = requiredText(value.currency, "omnipack_order_payload_missing_order_value_currency");
+  return { amount: value.amount, currency };
+}
+
+function compactRecord<T extends Record<string, unknown>>(record: T): T {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T;
+}