@openlup/platform 0.21.0 → 0.22.0

package/src/fulfillment/omnipack/omnipackProductPayload.ts

@@ -0,0 +1,67 @@
+// Pure builder for the OmniPack product-registration request (catalog load). Mirrors the
+// outbound-order payload convention (pure module 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-registration request key names (confirm against the OmniPack product API docs).
+const KEY_SKU = "sku";
+const KEY_EAN = "ean";
+const KEY_GROUP = "group";
+const KEY_NAME = "name";
+const KEY_DIMENSIONS = "dimensions";
+
+export interface OmnipackProductPack {
+  weightGrams: number;
+  lengthMm: number;
+  widthMm: number;
+  heightMm: number;
+}
+
+export interface OmnipackProductInput {
+  sku: string;
+  ean: string | null;
+  productGroup: string;
+  title: string;
+  pack: OmnipackProductPack | null;
+}
+
+export class OmnipackProductPayloadError extends Error {
+  constructor(readonly code: string) {
+    super(`omnipack_product_payload_invalid: ${code}`);
+    this.name = "OmnipackProductPayloadError";
+  }
+}
+
+function requireNonEmpty(value: string | null | undefined, code: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new OmnipackProductPayloadError(code);
+  return trimmed;
+}
+
+function requirePositive(value: number, code: string): number {
+  if (!Number.isFinite(value) || value <= 0) throw new OmnipackProductPayloadError(code);
+  return value;
+}
+
+// Builds the product-registration payload. EAN, group, title and a full pack are required —
+// OmniPack matches physical goods by EAN and a batch-tracked group needs known dimensions.
+export function buildOmnipackProductPayload(input: OmnipackProductInput): Record<string, unknown> {
+  const sku = requireNonEmpty(input.sku, "missing_sku");
+  const ean = requireNonEmpty(input.ean, "missing_ean");
+  const group = requireNonEmpty(input.productGroup, "missing_product_group");
+  const name = requireNonEmpty(input.title, "missing_title");
+  if (!input.pack) throw new OmnipackProductPayloadError("missing_pack");
+
+  return {
+    [KEY_SKU]: sku,
+    [KEY_EAN]: ean,
+    [KEY_GROUP]: group,
+    [KEY_NAME]: name,
+    [KEY_DIMENSIONS]: {
+      weight: requirePositive(input.pack.weightGrams, "invalid_pack_weight"),
+      length: requirePositive(input.pack.lengthMm, "invalid_pack_length"),
+      width: requirePositive(input.pack.widthMm, "invalid_pack_width"),
+      height: requirePositive(input.pack.heightMm, "invalid_pack_height"),
+    },
+  };
+}

package/src/fulfillment/omnipack/omnipackReconciliationPayload.ts

@@ -0,0 +1,7 @@
+export function providerOccurrenceKey(
+  fulfillmentOrderId: string,
+  providerStatus: string,
+  occurredAt: string | null,
+): string {
+  return `${fulfillmentOrderId}:${providerStatus}:${occurredAt ?? "unknown-time"}`;
+}

package/src/fulfillment/omnipack/omnipackStatusVocabulary.ts

@@ -0,0 +1,103 @@
+// Provider status translation only; lifecycle effects remain host-owned.
+export type NormalizedProviderStatus =
+  | "new"
+  | "in_fulfillment"
+  | "ready_for_packing"
+  | "awaiting_courier"
+  | "shipping"
+  | "delivered"
+  | "shipping_failed"
+  | "returned_to_sender"
+  | "cancelled"
+  | "suspended";
+
+// Provider strings arrive in varied spelling ("IN_FULFILLMENT", "in_fulfillment",
+// "Shipping") — compare on a canonical token so casing/separator drift can never
+// silently zero the pull.
+export function canonicalStatusToken(value: string | null | undefined): string | null {
+  const token = value?.trim().toLowerCase().replace(/[\s_-]+/g, "_");
+  return token || null;
+}
+
+// Map the provider primary `status` to our normalized enum. subStatus is NOT
+// consulted: it is recorded verbatim as evidence but never changes the local
+// state (the provider-status mapping lives entirely in the primary status).
+// Returns null for an unknown/UNKNOWN primary status → the worker quarantines it
+// as omnipack_unknown_provider_status (loud, self-diagnosing) rather than skipping.
+export function normalizeStatus(status: string | null): NormalizedProviderStatus | null {
+  switch (canonicalStatusToken(status)) {
+    case "new":
+      return "new";
+    case "in_fulfillment":
+      return "in_fulfillment";
+    case "ready_for_packing":
+      return "ready_for_packing";
+    case "awaiting_courier":
+      return "awaiting_courier";
+    case "shipping":
+      return "shipping";
+    case "delivered":
+      return "delivered";
+    case "shipping_failed":
+      return "shipping_failed";
+    case "returned_to_sender":
+      return "returned_to_sender";
+    case "cancelled":
+      return "cancelled";
+    case "suspended":
+      return "suspended";
+    // "unknown" is OmniPack's documented exceptional value ("in general it
+    // shouldn't happen") — quarantine it like any unmapped status.
+    default:
+      return null;
+  }
+}
+
+// Local fulfillment status vocabulary (the canonical set used across the
+// commerce domain): provider_received | picking | packed | in_transit |
+// delivered | cancelled | exception. Both ingestion paths — the poller and the
+// webhook — map into it here and nowhere else.
+//
+// A total Record rather than a `switch`: a new member of the union is then a
+// compile error instead of a silent fall-through to whatever the last branch
+// returned. The webhook path used to carry exactly that hole (its private
+// mapper defaulted every unnamed token to `delivered`, the most consequential
+// terminal state); routing it through this table removed it.
+const LOCAL_STATUS_BY_PROVIDER_STATUS: Record<NormalizedProviderStatus, string> = {
+  // Created / on hold at the provider. READY_FOR_EXPORT means validation passed
+  // and waits for export to warehouse execution; EXPORTED means handed to
+  // warehouse execution. Neither proves a label, stock coverage, WMS
+  // acceptance, cut-off passage, or literal picking. Neither is shipped.
+  new: "provider_received",
+  // Canonical `picking` is the coarse provider-neutral warehouse-preparation
+  // bucket; IN_FULFILLMENT evidence does not prove a literal picker action, and
+  // it does NOT consume provider stock — see stockConsumedFor below.
+  in_fulfillment: "picking",
+  // Picking completed, awaiting packing. This is the domain's finished-picking
+  // consumption boundary: the webhook path maps the same physical moment
+  // (order.picked) to local `packed` and consumes provider stock, so the poller
+  // must not lag a state behind (push/pull parity). `packed` is not in the
+  // handover set, so no dispatch email fires here.
+  ready_for_packing: "packed",
+  // Packed, waiting for the courier to collect. Stock is consumed; the parcel
+  // is NOT yet handed over, so no dispatch email fires here.
+  awaiting_courier: "packed",
+  // Courier has the parcel — this is the ship boundary: handover + tracking +
+  // the shipment.dispatched customer email.
+  shipping: "in_transit",
+  delivered: "delivered",
+  // Shipping failed / order suspended pending merchant clarification / returned
+  // to sender / provider-side cancellation: all route to an operational
+  // fulfillment_exception hold for OMS review. The verified vendor source emits
+  // the existing reassurance-only event before delivery; after durable delivery
+  // the hold remains but the future-tense event is suppressed. The distinct
+  // provider status is preserved as the hold reason.
+  shipping_failed: "exception",
+  suspended: "exception",
+  returned_to_sender: "exception",
+  cancelled: "exception",
+};
+
+export function localStatusFor(status: NormalizedProviderStatus): string {
+  return LOCAL_STATUS_BY_PROVIDER_STATUS[status];
+}

package/src/fulfillment/omnipack/omnipackWebhookPayload.ts

@@ -0,0 +1,73 @@
+import { timingSafeEqual } from "node:crypto";
+import type { OmnipackWebhookEvidence } from "./mappers.js";
+import type { NormalizedProviderStatus } from "./omnipackStatusVocabulary.js";
+
+export interface OmnipackWebhookRequest { headers: Record<string, string | string[] | undefined> }
+export type OmnipackWebhookRouteEvent = "shipment.accepted" | "order.processing_started" | "order.picked" | "order.shipped" | "order.delivered";
+
+export const EVENT_TO_STATUS: Record<OmnipackWebhookRouteEvent, NormalizedProviderStatus> = {
+  "shipment.accepted": "new",
+  "order.processing_started": "in_fulfillment",
+  "order.picked": "ready_for_packing",
+  "order.shipped": "shipping",
+  "order.delivered": "delivered",
+};
+
+export function verifyOmnipackWebhookToken(req: OmnipackWebhookRequest, expectedToken: string | undefined): boolean {
+  if (!expectedToken) return false;
+  const authorization = readHeader(req, "authorization");
+  if (safeEqual(authorization, `Bearer ${expectedToken}`)) return true;
+  if (verifyBasicAuth(authorization, expectedToken)) return true;
+  return safeEqual(readHeader(req, "x-omnipack-webhook-token"), expectedToken);
+}
+
+export function buildProviderEventId(evidence: OmnipackWebhookEvidence): string {
+  return [
+    evidence.event,
+    evidence.providerOrderId ?? evidence.orderNumber ?? "unknown-order",
+    evidence.fulfilmentNumber ?? "unknown-fulfilment",
+    evidence.occurredAt ?? "unknown-time",
+  ].join(":");
+}
+
+function readHeader(req: OmnipackWebhookRequest, name: string): string | undefined {
+  const direct = req.headers[name];
+  if (typeof direct === "string") return direct;
+  if (Array.isArray(direct)) return direct[0];
+  const lowerName = name.toLowerCase();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (key.toLowerCase() !== lowerName) continue;
+    if (typeof value === "string") return value;
+    if (Array.isArray(value)) return value[0];
+  }
+  return undefined;
+}
+
+function verifyBasicAuth(authorization: string | undefined, expectedToken: string): boolean {
+  const match = authorization?.match(/^Basic\s+(.+)$/i);
+  if (!match) return false;
+  const credentials = decodeBase64(match[1]);
+  if (!credentials) return false;
+  const separator = credentials.indexOf(":");
+  if (separator <= 0) return false;
+  const username = credentials.slice(0, separator);
+  if (!username.trim()) return false;
+  const password = credentials.slice(separator + 1);
+  if (!password) return false;
+  return safeEqual(password, expectedToken);
+}
+
+function decodeBase64(value: string): string | null {
+  try {
+    return Buffer.from(value, "base64").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function safeEqual(actual: string | undefined, expected: string): boolean {
+  if (!actual) return false;
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}

package/src/fulfillment/omnipack/productSyncMappers.ts

@@ -0,0 +1,74 @@
+// Response mappers for the two-way OmniPack product sync (one SKU ↔ many EANs / "packs").
+// Kept separate from the order/stock/fulfilment mappers so the product-sync surface stays a
+// cohesive, independently-testable module. Self-contained tiny readers (no cross-file coupling)
+// mirror the defensive parsing convention used in mappers.ts.
+import { sanitizeOmnipackPayload } from "./mappers.js";
+
+export interface OmnipackProductPackEvidence {
+  ean: string;
+  quantity: number;
+}
+
+// GET /products/{sku} — the product with its packs[]. The pack list is authoritative for what
+// OmniPack currently holds; the push diff and the pull reconciliation both read it.
+export interface OmnipackProductEvidence {
+  provider: "omnipack";
+  sku: string;
+  packs: OmnipackProductPackEvidence[];
+  raw: Record<string, unknown>;
+}
+
+export interface OmnipackProductPackCreatedEvidence {
+  provider: "omnipack";
+  sku: string;
+  ean: string;
+  raw: Record<string, unknown>;
+}
+
+// We tolerate a sparse body and fall back to the request-side sku; packs without an EAN are
+// dropped (an EAN-less pack is not addressable for the host↔OmniPack diff).
+export function mapOmnipackProductResponse(body: unknown, requestSku: string): OmnipackProductEvidence {
+  const response = asRecord(body);
+  const packs = readArray(response.packs)
+    .map((entry) => {
+      const pack = asRecord(entry);
+      return { ean: readString(pack.ean), quantity: readNumber(pack.quantity) };
+    })
+    .filter((pack) => pack.ean.length > 0);
+  return {
+    provider: "omnipack",
+    sku: readString(response.sku) || requestSku,
+    packs,
+    raw: sanitizeOmnipackPayload(response),
+  };
+}
+
+export function mapOmnipackProductPackCreatedResponse(
+  body: unknown,
+  requestSku: string,
+  requestEan: string,
+): OmnipackProductPackCreatedEvidence {
+  const response = asRecord(body);
+  return {
+    provider: "omnipack",
+    sku: readString(response.sku) || requestSku,
+    ean: readString(response.ean) || requestEan,
+    raw: sanitizeOmnipackPayload(response),
+  };
+}
+
+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 readNumber(input: unknown): number {
+  return typeof input === "number" && Number.isFinite(input) ? input : 0;
+}

package/src/fulfillment/omnipack/providerError.ts

@@ -0,0 +1,64 @@
+export class OmnipackProviderError extends Error {
+  readonly provider = "omnipack";
+  readonly operation: string;
+  readonly status: number | null;
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly mayHaveSucceeded: boolean;
+
+  constructor(input: {
+    operation: string;
+    status: number | null;
+    code: string;
+    retryable: boolean;
+    mayHaveSucceeded: boolean;
+  }) {
+    super(`OmniPack request failed: ${input.operation}`);
+    this.name = "OmnipackProviderError";
+    this.operation = input.operation;
+    this.status = input.status;
+    this.code = input.code;
+    this.retryable = input.retryable;
+    this.mayHaveSucceeded = input.mayHaveSucceeded;
+  }
+}
+
+export interface SanitizedOmnipackProviderError {
+  code: string;
+  mayHaveSucceeded: boolean;
+  message: string;
+  operation: string | null;
+  retryable: boolean;
+  status: number | null;
+}
+
+export function sanitizeOmnipackProviderError(error: unknown): SanitizedOmnipackProviderError {
+  if (error instanceof OmnipackProviderError) {
+    return {
+      code: error.code,
+      mayHaveSucceeded: error.mayHaveSucceeded,
+      message: error.message,
+      operation: error.operation,
+      retryable: error.retryable,
+      status: error.status,
+    };
+  }
+  return {
+    code: "omnipack_provider_error",
+    mayHaveSucceeded: true,
+    message: "OmniPack request failed",
+    operation: null,
+    retryable: true,
+    status: null,
+  };
+}
+
+export function mayPostHaveSucceeded(method: string, status: number | null): boolean {
+  if (method !== "POST") return false;
+  return status === null
+    || status === 408
+    || status === 409
+    || status === 425
+    || status === 429
+    || status >= 500;
+}

package/src/fulfillment/omnipack/trackingReferences.ts

@@ -0,0 +1,77 @@
+// Provider-payload extraction only. This infra layer stays free of domain
+// imports (provider-infra boundary): it surfaces the feed's raw carrier
+// evidence (carrier code, service, feed-supplied URL) and leaves carrier
+// normalization + tracking-URL building to the fulfillment domain
+// (enrichOmnipackTrackingReference + the shipping carrier registry).
+export interface OmnipackTrackingReferenceEvidence {
+  provider: "omnipack";
+  trackingNumber: string;
+  trackingUrl: string | null;
+  /** Raw provider carrier/platform code. */
+  carrier: string | null;
+  carrierKind: string | null;
+  service: string | null;
+}
+
+export function mapOmnipackTrackingReferences(input: {
+  shipments?: unknown[];
+  trackingNumbers?: unknown[];
+  readString: (value: unknown) => string;
+  readNullableString: (value: unknown) => string | null;
+  asRecord: (value: unknown) => Record<string, unknown>;
+}): OmnipackTrackingReferenceEvidence[] {
+  const fromShipments = (input.shipments ?? [])
+    .map(input.asRecord)
+    .map((shipment) => {
+      const trackingNumber = input.readString(shipment.trackingNo) || input.readString(shipment.trackingNumber);
+      if (!trackingNumber) return null;
+      const service = input.readNullableString(shipment.shippingMethod) ?? input.readNullableString(shipment.service);
+      return {
+        provider: "omnipack" as const,
+        trackingNumber,
+        trackingUrl:
+          input.readNullableString(shipment.trackingUrl) ??
+          input.readNullableString(shipment.trackingURL) ??
+          input.readNullableString(shipment.trackingLink) ??
+          input.readNullableString(shipment.publicTrackingUrl),
+        carrier: input.readNullableString(shipment.carrier) ?? input.readNullableString(shipment.carrierCode),
+        carrierKind: carrierKindFromService(service),
+        service,
+      };
+    })
+    .filter((ref): ref is OmnipackTrackingReferenceEvidence => ref !== null);
+
+  const fallbackNumbers = (input.trackingNumbers ?? [])
+    .map(input.readString)
+    .filter(Boolean)
+    .map((trackingNumber) => ({
+      provider: "omnipack" as const,
+      trackingNumber,
+      trackingUrl: null,
+      carrier: null,
+      carrierKind: null,
+      service: null,
+    }));
+
+  return uniqueTrackingReferences([...fromShipments, ...fallbackNumbers]);
+}
+
+function uniqueTrackingReferences(
+  refs: OmnipackTrackingReferenceEvidence[],
+): OmnipackTrackingReferenceEvidence[] {
+  const seen = new Set<string>();
+  const result: OmnipackTrackingReferenceEvidence[] = [];
+  for (const ref of refs) {
+    const key = ref.trackingNumber.trim();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    result.push({ ...ref, trackingNumber: key });
+  }
+  return result;
+}
+
+function carrierKindFromService(service: string | null): string | null {
+  if (!service) return null;
+  const [carrier] = service.split("_");
+  return carrier ? carrier.toLowerCase() : null;
+}