@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/omnipack/mappers.d.ts

@@ -0,0 +1,73 @@
+import { 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 declare function mapOmnipackOrderCreatedResponse(body: unknown): OmnipackOrderCreatedEvidence;
+export declare function mapOmnipackProductCreatedResponse(body: unknown, requestSku: string): OmnipackProductCreatedEvidence;
+export declare function mapOmnipackStockResponse(body: unknown): OmnipackStockEvidence[];
+export declare function mapOmnipackStockMovementsResponse(body: unknown): OmnipackStockMovementEvidence[];
+export declare function mapOmnipackFulfilmentsResponse(body: unknown): OmnipackFulfilmentEvidence[];
+export declare function mapOmnipackFulfilmentRequestsResponse(body: unknown): OmnipackFulfilmentRequestEvidence[];
+export declare function mapOmnipackWebhookPayload(body: unknown, fallbackEvent?: string): OmnipackWebhookEvidence;
+export declare function sanitizeOmnipackPayload(input: Record<string, unknown>): Record<string, unknown>;

package/dist/fulfillment/omnipack/mappers.js

@@ -0,0 +1,177 @@
+import { mapOmnipackTrackingReferences, } from "./trackingReferences.js";
+export function mapOmnipackOrderCreatedResponse(body) {
+    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, requestSku) {
+    const response = asRecord(body);
+    return {
+        provider: "omnipack",
+        sku: readString(response.sku) || requestSku,
+        raw: sanitizeOmnipackPayload(response),
+    };
+}
+export function mapOmnipackStockResponse(body) {
+    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) {
+    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) {
+    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) {
+    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, fallbackEvent = "") {
+    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) {
+    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, blocked) {
+    return Object.fromEntries(Object.entries(input)
+        .filter(([key]) => !blocked.has(key))
+        .map(([key, value]) => [key, sanitizeValue(value, blocked)]));
+}
+function sanitizeValue(input, blocked) {
+    if (Array.isArray(input))
+        return input.map((value) => sanitizeValue(value, blocked));
+    if (input && typeof input === "object")
+        return sanitizeRecord(input, blocked);
+    return input;
+}
+function asRecord(input) {
+    return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}
+function readArray(input) {
+    return Array.isArray(input) ? input : [];
+}
+function readString(input) {
+    return typeof input === "string" ? input : "";
+}
+function readNullableString(input) {
+    const value = readString(input);
+    return value || null;
+}
+function readNumber(input) {
+    return typeof input === "number" && Number.isFinite(input) ? input : 0;
+}
+function trackingReferencesFrom(row) {
+    return mapOmnipackTrackingReferences({
+        shipments: readArray(row.shipments),
+        trackingNumbers: readArray(row.trackingNumbers),
+        readString,
+        readNullableString,
+        asRecord,
+    });
+}

package/dist/fulfillment/omnipack/observation.d.ts

@@ -0,0 +1,21 @@
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentRefusal } from "../contracts/index.js";
+import type { OmnipackWebhookEvidence } from "./mappers.js";
+import { type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
+export declare const refusal: (reason: FulfillmentRefusal["reason"], phase: FulfillmentRefusal["phase"], retryable?: boolean) => FulfillmentRefusal;
+export declare const digest: (bytes: string | Uint8Array) => string;
+/** References are opaque identifiers, never arbitrary provider prose or URLs. */
+export declare function reference(value: string | null | undefined): string | null;
+export declare function timestamp(value: string | null): string | null;
+export declare function eventKind(value: string): OmnipackWebhookRouteEvent | null;
+export declare function publicUrl(value: string | null, approve: (url: string) => boolean): string | null;
+export declare 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;

package/dist/fulfillment/omnipack/observation.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { parseNormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import { EVENT_TO_STATUS } from "./omnipackWebhookPayload.js";
+import { localStatusFor } from "./omnipackStatusVocabulary.js";
+export const refusal = (reason, phase, retryable = false) => ({ reason, phase, retryable });
+export const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** References are opaque identifiers, never arbitrary provider prose or URLs. */
+export function reference(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : null;
+}
+export function timestamp(value) {
+    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) {
+    return Object.hasOwn(EVENT_TO_STATUS, value) ? value : null;
+}
+export function publicUrl(value, approve) {
+    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, approve) {
+    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) {
+    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]);
+    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) => ["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/dist/fulfillment/omnipack/omnipackDispatchPayload.d.ts

@@ -0,0 +1,36 @@
+import { buildOmnipackOutboundOrderEvidence, type OmnipackOutboundOrderPayload, type OmnipackOutboundDeliverySelection } from "./omnipackOutboundOrderPayload.js";
+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 declare function buildOmnipackDispatchCommand(candidate: OmnipackDispatchCandidate): {
+    providerPayload: OmnipackOutboundOrderPayload;
+    body: string;
+    sanitizedRequest: {
+        deliveryContactRevision: number;
+    };
+    requestFingerprint: string;
+};
+export declare function buildOmnipackDispatchPayloadFromCandidate(candidate: OmnipackDispatchCandidate): OmnipackOutboundOrderPayload;
+export declare function stableDispatchHash(value: unknown): string;
+export declare function serializeOmnipackDispatchPayload(value: unknown): {
+    body: string;
+    requestFingerprint: string;
+};

package/dist/fulfillment/omnipack/omnipackDispatchPayload.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { buildOmnipackOutboundOrderEvidence, buildOmnipackOutboundOrderPayload, } from "./omnipackOutboundOrderPayload.js";
+export { buildOmnipackOutboundOrderEvidence as buildSanitizedEvidence };
+export function buildOmnipackDispatchCommand(candidate) {
+    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) {
+    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) {
+    return serializeOmnipackDispatchPayload(value).requestFingerprint;
+}
+// Materialize once: the digest and createOrder consume these exact UTF-8 bytes.
+export function serializeOmnipackDispatchPayload(value) {
+    const body = JSON.stringify(sortRecord(value));
+    return { body, requestFingerprint: createHash("sha256").update(body).digest("hex") };
+}
+function sortRecord(value) {
+    if (Array.isArray(value))
+        return value.map(sortRecord);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).sort().map(([key, child]) => [key, sortRecord(child)]));
+}
+function nullableText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/fulfillment/omnipack/omnipackOutboundOrderPayload.d.ts

@@ -0,0 +1,83 @@
+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 declare class OmnipackOutboundOrderPayloadError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function buildOmnipackOutboundOrderPayload(input: OmnipackOutboundOrderInput): OmnipackOutboundOrderPayload;
+export declare function buildOmnipackOutboundOrderEvidence(payload: OmnipackOutboundOrderPayload): Record<string, unknown>;

package/dist/fulfillment/omnipack/omnipackOutboundOrderPayload.js

@@ -0,0 +1,113 @@
+export class OmnipackOutboundOrderPayloadError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "OmnipackOutboundOrderPayloadError";
+    }
+}
+export function buildOmnipackOutboundOrderPayload(input) {
+    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),
+    });
+}
+export function buildOmnipackOutboundOrderEvidence(payload) {
+    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) {
+    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, selection) {
+    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, code) {
+    const text = optionalText(value);
+    if (!text)
+        throw new OmnipackOutboundOrderPayloadError(code);
+    return text;
+}
+function optionalText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function requiredQuantity(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new OmnipackOutboundOrderPayloadError("omnipack_order_payload_invalid_quantity");
+    }
+    return value;
+}
+function validOrderValue(value) {
+    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(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}

package/dist/fulfillment/omnipack/omnipackProductPackPayload.d.ts

@@ -0,0 +1,11 @@
+export type OmnipackPackKind = "unit" | "collective";
+export interface OmnipackProductPackInput {
+    ean: string;
+    quantity: number;
+}
+export declare class OmnipackProductPackPayloadError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function omnipackPackKindForQuantity(quantity: number): OmnipackPackKind;
+export declare function buildOmnipackProductPackPayload(input: OmnipackProductPackInput): Record<string, unknown>;

package/dist/fulfillment/omnipack/omnipackProductPackPayload.js

@@ -0,0 +1,38 @@
+// 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 class OmnipackProductPackPayloadError extends Error {
+    code;
+    constructor(code) {
+        super(`omnipack_product_pack_payload_invalid: ${code}`);
+        this.code = code;
+        this.name = "OmnipackProductPackPayloadError";
+    }
+}
+function requireNonEmpty(value, code) {
+    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) {
+    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) {
+    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 };
+}