@openlup/platform 0.20.0 → 0.22.0

package/src/fulfillment/omnipack/mappers.ts

@@ -0,0 +1,261 @@
+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 {
+  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 = ""): OmnipackWebhookEvidence {
+  const payload = asRecord(body);
+  const shipments = readArray(payload.shipments).map(asRecord);
+  const trackingReferences = trackingReferencesFrom({ shipments });
+  return {
+    provider: "omnipack",
+    event: readString(payload.event) || fallbackEvent,
+    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,61 @@
+import { createHash } from "node:crypto";
+import { parseNormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentRefusal } from "../contracts/index.js";
+import type { OmnipackWebhookEvidence } from "./mappers.js";
+import type { OmnipackTrackingReferenceEvidence } from "./trackingReferences.js";
+import { 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");
+/** References are opaque identifiers, never arbitrary provider prose or URLs. */
+export function reference(value: string | null | undefined): string | null {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : 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;
+}
+export function publicUrl(value: string | null, approve: (url: string) => boolean): string | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    // Query-free URLs only: signing tokens and credentials never enter durable tracking.
+    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash && approve(url.href) ? url.href : null;
+  } catch { return null; }
+}
+function tracking(refs: OmnipackTrackingReferenceEvidence[], approve: (url: string) => boolean): FulfillmentObservation["trackingRefs"] {
+  return refs.flatMap(item => {
+    const trackingNumber = reference(item.trackingNumber);
+    return trackingNumber ? [{ trackingNumber, carrierRef: reference(item.carrier), serviceRef: reference(item.service), publicUrl: publicUrl(item.trackingUrl, approve) }] : [];
+  });
+}
+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;
+}): FulfillmentObservation {
+  const evidence = input.evidence;
+  const externalRef = reference(evidence.providerOrderId);
+  const providerFulfillmentRef = reference(evidence.fulfilmentNumber);
+  const orderNumber = reference(evidence.orderNumber);
+  const fulfillmentRef = reference(input.fulfillmentRef) ?? providerFulfillmentRef ?? externalRef ?? orderNumber;
+  if (!fulfillmentRef) throw refusal("missing_correlation", "normalize");
+  const occurredAt = timestamp(evidence.occurredAt);
+  if (evidence.occurredAt && !occurredAt) throw refusal("malformed", "normalize");
+  const key = digest(JSON.stringify([input.event, externalRef ?? orderNumber, providerFulfillmentRef, occurredAt]));
+  const status = input.status ?? localStatusFor(EVENT_TO_STATUS[input.event as OmnipackWebhookRouteEvent]);
+  const fact = parseNormalizedFulfillmentFact({
+    schemaVersion: 1, mapperVersion: "1", factId: key, providerKind: "omnipack", fulfillmentReference: 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 { fact, eventKind: input.event, eventKey: key, firstReceivedAt: input.receivedAt,
+    correlation: { orderRef: null, fulfillmentRef: reference(input.fulfillmentRef), externalRef, orderNumber, providerFulfillmentRef, parcelRef: null },
+    trackingRefs: tracking(evidence.trackingReferences, input.approveTrackingUrl) };
+}

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;
+}

package/src/fulfillment/omnipack/omnipackProductPackPayload.ts

@@ -0,0 +1,47 @@
+// Pure builder for the OmniPack product-pack request (POST /products/{sku}/packs). A pack is
+// one EAN bound to a product: quantity === 1 is a sellable unit, quantity > 1 is a collective
+// carton (N units behind one barcode). One SKU therefore maps to MANY packs (unit barcode / alternate barcode
+// / collective carton). Mirrors the product/inbound payload convention (pure builder in
+// server/_lib, wired through the client). The exact OmniPack request key names live behind the
+// constants below so finalizing them against the (auth-gated) OmniPack product API docs is a
+// one-line edit.
+
+// Product-pack request key names (confirm against the OmniPack product-pack API docs).
+const KEY_EAN = "ean";
+const KEY_QUANTITY = "quantity";
+
+export type OmnipackPackKind = "unit" | "collective";
+
+export interface OmnipackProductPackInput {
+  ean: string;
+  quantity: number;
+}
+
+export class OmnipackProductPackPayloadError extends Error {
+  constructor(readonly code: string) {
+    super(`omnipack_product_pack_payload_invalid: ${code}`);
+    this.name = "OmnipackProductPackPayloadError";
+  }
+}
+
+function requireNonEmpty(value: string | null | undefined, code: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new OmnipackProductPackPayloadError(code);
+  return trimmed;
+}
+
+// A pack with quantity 1 is a sellable unit; quantity > 1 is a collective carton. Pure so the
+// push worker and the DB layer derive the same `kind` from the same rule.
+export function omnipackPackKindForQuantity(quantity: number): OmnipackPackKind {
+  return quantity > 1 ? "collective" : "unit";
+}
+
+// Builds the product-pack payload. EAN is required (OmniPack matches physical goods by barcode);
+// quantity must be a positive integer (the number of sellable units behind this EAN).
+export function buildOmnipackProductPackPayload(input: OmnipackProductPackInput): Record<string, unknown> {
+  const ean = requireNonEmpty(input.ean, "missing_ean");
+  if (!Number.isInteger(input.quantity) || input.quantity <= 0) {
+    throw new OmnipackProductPackPayloadError("invalid_quantity");
+  }
+  return { [KEY_EAN]: ean, [KEY_QUANTITY]: input.quantity };
+}