@openlup/platform 0.22.0 → 0.24.0

package/dist/fulfillment/omnipack/client.js

@@ -24,11 +24,11 @@ export function createOmnipackClient(config, fetchImpl) {
             const body = await requestJson(fetchImpl, config, "createProductPack", path, post(payload));
             return mapOmnipackProductPackCreatedResponse(body, sku, ean);
         },
-        async getStock() {
-            return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }));
+        async getStock(options) {
+            return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }, options?.refuseRedirectRetry));
         },
         async getStockMovements(params) {
-            return mapOmnipackStockMovementsResponse(await requestJson(fetchImpl, config, "getStockMovements", withQuery("/stock-movements", params), { method: "GET" }));
+            return mapOmnipackStockMovementsResponse(await requestJson(fetchImpl, config, "getStockMovements", withQuery("/stock-movements", params), { method: "GET" }, true));
         },
         async getFulfilmentsPage(params) {
             const body = await requestJson(fetchImpl, config, "getFulfilments", withQuery("/fulfilments", params), { method: "GET" });
@@ -49,30 +49,41 @@ export function createOmnipackClient(config, fetchImpl) {
         },
     };
 }
-async function requestJson(fetchImpl, config, operation, path, init) {
+async function requestJson(fetchImpl, config, operation, path, init, refuseRedirectRetry = false) {
     const method = (init.method ?? "GET").toUpperCase();
     const attempts = method === "GET" ? config.safeReadRetries + 1 : 1;
+    // Dispatch/readback diagnostics must not change product-sync or stock retry policy.
+    const diagnoseRedirectFailure = refuseRedirectRetry || operation === "createOrder"
+        || operation === "getFulfilments" || operation === "getFulfilmentRequests";
     let lastError = null;
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
         let submitted = false;
+        let responseBodyRead;
+        const dispatchFacts = () => operation === "createOrder" ? { submissionAttempted: submitted,
+            ...(responseBodyRead !== undefined ? { responseBodyRead } : {}) } : {};
         try {
             const base = new URL(config.baseUrl);
             const url = new URL(path, base);
             if (url.origin !== base.origin || url.username || url.password || url.protocol !== "https:")
                 throw new Error("Invalid fulfillment path");
             const response = await fetchWithTimeout(fetchImpl, url, config, init, () => { submitted = true; });
+            responseBodyRead = false;
+            const body = await readJsonBody(response).then(value => { responseBodyRead = true; return value; }).catch(error => {
+                if (response.ok)
+                    throw error;
+                return null;
+            });
             if (response.ok)
-                return await readJsonBody(response);
+                return body;
             const retryable = method === "GET" && isRetryableStatus(response.status);
             // A failed body read cannot erase the rejection status already received.
-            const body = await readJsonBody(response).catch(() => null);
-            lastError = new OmnipackProviderError({
+            lastError = Object.assign(new OmnipackProviderError({
                 operation,
                 status: response.status,
-                code: readProviderErrorCode(body) ?? `http_${response.status}`,
+                code: refuseRedirectRetry && response.status >= 300 && response.status < 400 ? "redirect_refused" : readProviderErrorCode(body) ?? `http_${response.status}`,
                 retryable,
                 mayHaveSucceeded: mayPostHaveSucceeded(method, response.status),
-            });
+            }), dispatchFacts());
             if (!retryable || attempt === attempts)
                 throw lastError;
         }
@@ -80,14 +91,14 @@ async function requestJson(fetchImpl, config, operation, path, init) {
             const retryable = method === "GET" && attempt < attempts;
             lastError = submitted && error instanceof OmnipackProviderError
                 ? error
-                : new OmnipackProviderError({
+                : Object.assign(new OmnipackProviderError({
                     operation,
                     status: null,
-                    code: "network_error",
+                    code: diagnoseRedirectFailure && isRedirectRefusal(error) ? "redirect_refused" : "network_error",
                     retryable,
                     mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
-                });
-            if (!retryable)
+                }), dispatchFacts());
+            if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused"))
                 throw lastError;
         }
     }
@@ -160,3 +171,10 @@ function readProviderErrorCode(body) {
 function isRetryableStatus(status) {
     return status === 408 || status === 429 || status >= 500;
 }
+// Fetch implementations expose redirect refusal as an exception, sometimes through cause.
+// Inspect it only to select a closed diagnostic; no exception text leaves this adapter.
+function isRedirectRefusal(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /redirect/i.test(error.message) || (error.cause instanceof Error && /redirect/i.test(error.cause.message));
+}

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

@@ -1,5 +1,6 @@
-import type { FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "../contracts/index.js";
+import type { FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentObservationPagePort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "../contracts/index.js";
 import { type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
+import { type OmnipackObservationCodecs } from "./observation.js";
 export { omnipackFulfillmentCapabilities } from "./capabilities.js";
 /** Node-only, explicit construction. Secrets are supplied per call, never retained as values. */
 export interface OmnipackFulfillmentAdapterConfig {
@@ -35,6 +36,7 @@ export interface OmnipackFulfillmentAdapterConfig {
     mintEvidenceReference: () => `evidence:${string}`;
     mintSyncRunId: () => string;
     approveTrackingUrl: (url: string) => boolean;
+    observationCodecs?: OmnipackObservationCodecs;
     /** Writes occur only through deliberate calls; scheduled composition must remain pull-only. */
     product?: {
         resolvePushMetadata: (sku: string) => Promise<Record<string, unknown> | null>;
@@ -47,6 +49,7 @@ export declare function createOmnipackFulfillmentAdapter(config: OmnipackFulfill
     label: FulfillmentLabelPort;
     observation: FulfillmentObservationPort;
     readback: FulfillmentReadbackPort;
+    reconciliation: FulfillmentObservationPagePort;
     stockSync: FulfillmentStockSyncProvider;
     productSync: FulfillmentProductSyncProvider;
 };

package/dist/fulfillment/omnipack/index.js

@@ -1,11 +1,47 @@
+import { z } from "zod";
+import { publicTrackingUrl } from "../observationProjection.js";
 import { createOmnipackClient, OmnipackProviderError } from "./client.js";
 import { omnipackFulfillmentCapabilities } from "./capabilities.js";
 import { buildOmnipackDispatchCommand, serializeOmnipackDispatchPayload, stableDispatchHash } from "./omnipackDispatchPayload.js";
 import { mapOmnipackWebhookPayload } from "./mappers.js";
 import { verifyOmnipackWebhookToken } from "./omnipackWebhookPayload.js";
-import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
-import { digest, eventKind, observation, reference, refusal, timestamp } from "./observation.js";
+import { createReconciliationPagePort, reconciliationObservation } from "./reconciliation.js";
+import { dispatchEvidence, operationError } from "../dispatchProjection.js";
+import { correlationReference, digest, eventKind, observation, reference, refusal, timestamp } from "./observation.js";
 export { omnipackFulfillmentCapabilities } from "./capabilities.js";
+// Internal error projection: retain diagnostics without exposing a provider payload or cause.
+class OmnipackSyncError extends Error {
+    reason;
+    phase = "sync";
+    retryable;
+    providerFailure;
+    status;
+    code;
+    constructor(reason, operation, error) {
+        super(reason === "io_failure" ? `OmniPack request failed: ${operation}` : `OmniPack sync refused: ${reason}`);
+        this.reason = reason;
+        this.name = "OmnipackSyncError";
+        this.providerFailure = reason === "io_failure";
+        this.retryable = error instanceof OmnipackProviderError ? error.retryable : false;
+        this.status = error instanceof OmnipackProviderError ? error.status : null;
+        this.code = error instanceof OmnipackProviderError ? error.code : null;
+    }
+}
+function syncFailure(operation, error) {
+    return error instanceof OmnipackSyncError ? error : new OmnipackSyncError("io_failure", operation, error);
+}
+function requireProductSku(sku) {
+    // URL resolution collapses dot segments; encodeURIComponent rejects lone surrogates.
+    // Keep these SKUs in the listing so the worker counts a visible per-SKU failure.
+    try {
+        if (!sku.trim() || sku === "." || sku === "..")
+            throw Error();
+        encodeURIComponent(sku);
+    }
+    catch {
+        throw new OmnipackSyncError("malformed", "getProduct");
+    }
+}
 /** No route, schedule, environment reader or default binding is installed. */
 export function createOmnipackFulfillmentAdapter(config) {
     const maxRetainedSubmissions = config.maxRetainedSubmissions === undefined ? 10_000 : config.maxRetainedSubmissions;
@@ -48,13 +84,13 @@ export function createOmnipackFulfillmentAdapter(config) {
     };
     const requireSync = () => {
         if (!capabilities.selected || !capabilities.readiness.ready)
-            throw refusal(capabilities.selected ? "not_ready" : "disabled", "sync");
+            throw new OmnipackSyncError(capabilities.selected ? "not_ready" : "disabled", "selection");
     };
     const syncIdentity = () => {
         const syncRunId = reference(config.mintSyncRunId());
         const collectedAt = timestamp(config.clock());
         if (!syncRunId || !collectedAt)
-            throw refusal("malformed", "sync");
+            throw new OmnipackSyncError("malformed", "sync");
         return { providerRef: capabilities.providerRef, syncRunId, collectedAt, sourceRevision: null, revisionSource: "collection" };
     };
     // Shared computation: host metadata and serialized bytes live only for this call.
@@ -81,9 +117,12 @@ export function createOmnipackFulfillmentAdapter(config) {
                 selectedDelivery: { providerKind: capabilities.providerRef, carrierKind: request.selection.carrierRef,
                     serviceCode: request.selection.serviceRef, deliveryKind: request.selection.deliveryKind, pickupPoint: request.selection.pickupPoint } }, lines,
         });
-        const evidence = { commandFingerprint: command.requestFingerprint,
+        const evidence = dispatchEvidence({ commandFingerprint: command.requestFingerprint,
             contactRevision: { schemaVersion: request.contactRevision.schemaVersion, source: request.contactRevision.source, revision: request.contactRevision.revision },
-            providerRef: capabilities.providerRef, carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef };
+            providerRef: capabilities.providerRef, carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
+            transcript: { itemCount: command.providerPayload.items.length,
+                items: command.providerPayload.items.map(item => ({ skuRef: item.sku, quantity: item.quantity, lotRef: item.lotNumber ?? null, expirationDate: item.expirationDate ?? null })),
+                deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
         return { body: command.body, evidence };
     };
     return {
@@ -107,7 +146,7 @@ export function createOmnipackFulfillmentAdapter(config) {
                 let requestCommandDigest;
                 try {
                     // Validate the closed evidence and its request-bound values without consulting preparation state.
-                    if (Object.keys(evidence).length !== 5 || Object.keys(evidence.contactRevision).length !== 3
+                    if (Object.keys(evidence).length !== 6 || Object.keys(evidence.contactRevision).length !== 3
                         || typeof evidence.commandFingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(evidence.commandFingerprint)
                         || !reference(evidence.providerRef)
                         || !reference(evidence.carrierRef) || !reference(evidence.serviceRef)
@@ -121,6 +160,8 @@ export function createOmnipackFulfillmentAdapter(config) {
                         || evidence.carrierRef !== request.selection.carrierRef || evidence.serviceRef !== request.selection.serviceRef)
                         throw Error();
                     evidenceKey = serializeOmnipackDispatchPayload(evidence).body;
+                    if (serializeOmnipackDispatchPayload(dispatchEvidence(evidence)).body !== evidenceKey)
+                        throw Error();
                     requestCommandDigest = commandDigest(request);
                     const submitted = submissions.get(evidence.commandFingerprint);
                     if (submitted) {
@@ -142,7 +183,7 @@ export function createOmnipackFulfillmentAdapter(config) {
                     let command;
                     try {
                         command = await buildCommand(commandRequest);
-                        if (command.evidence.commandFingerprint !== fingerprint)
+                        if (command.evidence.commandFingerprint !== fingerprint || serializeOmnipackDispatchPayload(command.evidence).body !== evidenceKey)
                             throw Error();
                     }
                     catch {
@@ -161,9 +202,10 @@ export function createOmnipackFulfillmentAdapter(config) {
                             providerAttemptKey: `attempt:${proof}`, labelKey: `label:${proof}` };
                     }
                     catch (error) {
-                        return error instanceof OmnipackProviderError && !error.mayHaveSucceeded
-                            ? { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal("io_failure", "dispatch") }
-                            : { kind: "unknown", effectMayHaveSucceeded: true, refusal: refusal("io_failure", "dispatch") };
+                        const detail = operationError(error instanceof OmnipackProviderError ? error : { code: "provider_dispatch_failed", status: null, retryable: true, mayHaveSucceeded: true });
+                        return !detail.mayHaveSucceeded
+                            ? { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail }
+                            : { kind: "unknown", effectMayHaveSucceeded: true, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail };
                     }
                     finally {
                         command.body = "";
@@ -198,14 +240,31 @@ export function createOmnipackFulfillmentAdapter(config) {
                         return { kind: "refused", refusal: refusal("malformed", "normalize") };
                     if ("event" in payload && (typeof payload.event !== "string" || !eventKind(payload.event)))
                         return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
-                    const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent);
+                    const original = payload;
+                    // Validate calendar fields here only; keep compact offsets and local
+                    // timestamps and minute precision accepted by the base parser,
+                    // without rewriting key bytes.
+                    if (original.occurredAt !== undefined && original.occurredAt !== null
+                        && (typeof original.occurredAt !== "string" || !timestamp(original.occurredAt)
+                            || !z.iso.datetime({ offset: true, local: true })
+                                .or(z.iso.datetime({ offset: true, local: true, precision: -1 }))
+                                .safeParse(original.occurredAt.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2")).success))
+                        return { kind: "refused", refusal: refusal("malformed", "normalize"), diagnostics: { invalidTimestamp: true } };
+                    const rejectedCorrelationRefs = [original.orderId, original.providerOrderId, original.orderNumber, original.fulfilmentNumber]
+                        .filter(value => value !== undefined && value !== null && (typeof value !== "string" || !correlationReference(value, config.observationCodecs))).length;
+                    if (rejectedCorrelationRefs)
+                        return { kind: "refused", refusal: refusal("missing_correlation", "normalize"), diagnostics: { rejectedCorrelationRefs } };
+                    const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent, value => correlationReference(value, config.observationCodecs) !== null, {
+                        service: value => correlationReference(value, config.observationCodecs) !== null,
+                        url: value => publicTrackingUrl(value, config.approveTrackingUrl, config.observationCodecs?.trackingUrl) !== null,
+                    });
                     const event = eventKind(evidence.event);
                     if (!event || event !== config.notification.expectedEvent)
                         return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
-                    if (![evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => reference(value)))
+                    if (![evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => correlationReference(value, config.observationCodecs)))
                         return { kind: "refused", refusal: refusal("missing_correlation", "normalize") };
                     return { kind: "verified", observation: observation({ evidence, event, receivedAt: input.receivedAt,
-                            rawDigest: digest(rawBody), evidenceRef: config.mintEvidenceReference(), source: "provider_webhook", approveTrackingUrl: config.approveTrackingUrl }) };
+                            rawDigest: digest(rawBody), evidenceRef: config.mintEvidenceReference(), source: "provider_webhook", approveTrackingUrl: config.approveTrackingUrl, observationCodecs: config.observationCodecs }) };
                 }
                 catch {
                     return { kind: "refused", refusal: refusal("malformed", "normalize") };
@@ -228,55 +287,47 @@ export function createOmnipackFulfillmentAdapter(config) {
                         ? row.fulfilmentNumber === input.externalRef : row.providerOrderId === input.externalRef);
                     if (matches.length !== 1)
                         return { kind: "unknown", refusal: refusal("local_missing", "readback") };
-                    const row = matches[0];
-                    const normalized = normalizeStatus(row.status);
-                    if (!normalized)
-                        return { kind: "unknown", refusal: refusal("unsupported_event", "readback") };
-                    const status = localStatusFor(normalized);
-                    const event = { provider_received: "shipment.accepted", picking: "order.processing_started", packed: "order.picked", in_transit: "order.shipped", delivered: "order.delivered", exception: "parcel.exception" }[status];
-                    const evidence = { provider: "omnipack", event, providerOrderId: row.providerOrderId, orderNumber: row.orderNumber,
-                        fulfilmentNumber: row.fulfilmentNumber, occurredAt: row.updatedAt, trackingNumbers: row.trackingNumbers,
-                        trackingReferences: row.trackingReferences, shippingMethods: [] };
-                    return { kind: "found", externalRef: input.externalRef, createdAt: timestamp(row.createdAt), updatedAt: timestamp(row.updatedAt),
-                        observation: observation({ evidence, event, status, fulfillmentRef: input.fulfillmentRef, receivedAt: config.clock(),
-                            rawDigest: digest(JSON.stringify(evidence)), evidenceRef: config.mintEvidenceReference(), source: "provider_reconciliation", approveTrackingUrl: config.approveTrackingUrl }) };
+                    const mapped = reconciliationObservation(matches[0], config, input.fulfillmentRef);
+                    return mapped.kind === "unmapped" ? { kind: "unknown", refusal: refusal("unsupported_event", "readback") } : { ...mapped, externalRef: input.externalRef };
                 }
                 catch {
                     return { kind: "unknown", refusal: refusal("io_failure", "readback") };
                 }
             },
         },
+        reconciliation: createReconciliationPagePort(client, config, () => !capabilities.selected || !capabilities.readiness.ready
+            ? refusal(capabilities.selected ? "not_ready" : "disabled", "readback") : null),
         stockSync: {
             async getStock() {
                 requireSync();
                 try {
                     const identity = syncIdentity();
-                    return (await client.getStock()).map(row => {
+                    return (await client.getStock({ refuseRedirectRetry: true })).map((row, itemIndex) => {
                         const skuRef = reference(row.sku);
                         if (!skuRef)
-                            throw refusal("malformed", "sync");
+                            return { kind: "rejected", itemIndex, reason: "invalid_sku_ref" };
                         return { ...identity, skuRef, quantityKind: "snapshot", totalQuantity: row.totalQuantity,
                             forSaleQuantity: row.forSaleQuantity, reservedOrUnavailableQuantity: row.reservedOrUnavailableQuantity };
                     });
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw stockFailure(error, "get_stock");
                 }
             },
             async getStockMovements(input) {
                 requireSync();
                 try {
                     const identity = syncIdentity();
-                    return (await client.getStockMovements(input)).map(row => {
+                    return (await client.getStockMovements(input)).map((row, itemIndex) => {
                         const skuRef = reference(row.sku);
                         if (!skuRef)
-                            throw refusal("malformed", "sync");
+                            return { kind: "rejected", itemIndex, reason: "invalid_sku_ref" };
                         return { ...identity, skuRef, quantityKind: "movement", quantity: row.quantity, occurredAt: timestamp(row.occurredAt),
                             operationType: reference(row.operationType), documentRef: reference(row.warehouseDocumentNumber), lotRef: reference(row.lotNumber), expirationDate: /^\d{4}-\d\d-\d\d$/u.test(row.expirationDate ?? "") ? row.expirationDate : null };
                     });
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw stockFailure(error, "get_stock_movements");
                 }
             },
         },
@@ -290,37 +341,38 @@ export function createOmnipackFulfillmentAdapter(config) {
                     await client.createProduct(metadata, sku);
                     return { replayed: false };
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw syncFailure("createProduct", error);
                 }
             },
             async getProductPacks(sku) {
                 requireSync();
+                requireProductSku(sku);
                 try {
-                    return (await client.getProduct(sku)).packs.filter(pack => /^\d{8,14}$/u.test(pack.ean) && Number.isSafeInteger(pack.quantity) && pack.quantity > 0).map(pack => ({ ean: pack.ean, quantity: pack.quantity }));
+                    return (await client.getProduct(sku)).packs.map(pack => ({ ean: pack.ean, quantity: pack.quantity }));
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw syncFailure("getProduct", error);
                 }
             },
             async addProductPack(sku, pack) {
                 requireSync();
                 if (!/^\d{8,14}$/u.test(pack.ean) || !Number.isSafeInteger(pack.quantity) || pack.quantity <= 0)
-                    throw refusal("malformed", "sync");
+                    throw new OmnipackSyncError("malformed", "sync");
                 try {
                     await client.createProductPack(sku, { ean: pack.ean, quantity: pack.quantity }, pack.ean);
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw syncFailure("createProductPack", error);
                 }
             },
             async listStockedSkus() {
                 requireSync();
                 try {
-                    return [...new Set((await client.getStock()).flatMap(row => reference(row.sku) ? [row.sku] : []))];
+                    return [...new Set((await client.getStock()).flatMap(row => row.sku.trim() ? [row.sku] : []))];
                 }
-                catch {
-                    throw refusal("io_failure", "sync");
+                catch (error) {
+                    throw syncFailure("getStock", error);
                 }
             },
         },
@@ -347,3 +399,13 @@ function commandDigest(request) {
             pickupPointId: request.selection.pickupPoint?.id ?? null },
     });
 }
+/** Translate only the contributed client's typed error; never copy a message or payload. */
+function stockFailure(error, operation) {
+    const failure = syncFailure(operation === "get_stock" ? "getStock" : "getStockMovements", error);
+    if (!(error instanceof OmnipackProviderError))
+        return failure;
+    const retryable = error.code !== "redirect_refused" && (error.retryable || error.code === "network_error");
+    return Object.assign(failure, { retryable, providerError: {
+            operation, status: error.status, code: error.code, retryable,
+        } });
+}

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

@@ -53,6 +53,9 @@ export interface OmnipackFulfilmentRequestEvidence {
     state: string | null;
 }
 export interface OmnipackWebhookEvidence {
+    rejectedTrackingRefs?: number;
+    rejectedServices?: number;
+    rejectedTrackingUrls?: number;
     provider: "omnipack";
     event: string;
     providerOrderId: string | null;
@@ -69,5 +72,8 @@ export declare function mapOmnipackStockResponse(body: unknown): OmnipackStockEv
 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 mapOmnipackWebhookPayload(body: unknown, fallbackEvent?: string, admitTrackingNumber?: (value: string) => boolean, admitMetadata?: {
+    service(value: string): boolean;
+    url(value: string): boolean;
+}): OmnipackWebhookEvidence;
 export declare function sanitizeOmnipackPayload(input: Record<string, unknown>): Record<string, unknown>;

package/dist/fulfillment/omnipack/mappers.js

@@ -102,13 +102,35 @@ export function mapOmnipackFulfilmentRequestsResponse(body) {
         };
     });
 }
-export function mapOmnipackWebhookPayload(body, fallbackEvent = "") {
+export function mapOmnipackWebhookPayload(body, fallbackEvent = "", admitTrackingNumber, admitMetadata) {
     const payload = asRecord(body);
     const shipments = readArray(payload.shipments).map(asRecord);
-    const trackingReferences = trackingReferencesFrom({ shipments });
+    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),

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

@@ -1,13 +1,19 @@
-import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentRefusal } from "../contracts/index.js";
+export { reference } from "../dispatchProjection.js";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs, 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;
+/** Share admission with the durable sink, including explicit deny allowlists. */
+export declare function correlationReference(value: string | null | undefined, codecs?: OmnipackObservationCodecs): string | null;
+export interface OmnipackObservationCodecs extends FulfillmentObservationCodecs {
+    normalizeCarrier?(input: {
+        carrierRef: string | null;
+        serviceRef: string | null;
+    }): 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"];
@@ -18,4 +24,5 @@ export declare function observation(input: {
     source: "provider_webhook" | "provider_reconciliation";
     fulfillmentRef?: string;
     approveTrackingUrl: (url: string) => boolean;
+    observationCodecs?: OmnipackObservationCodecs;
 }): FulfillmentObservation;

package/dist/fulfillment/omnipack/observation.js

@@ -1,12 +1,15 @@
+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 { EVENT_TO_STATUS } from "./omnipackWebhookPayload.js";
+import { buildProviderEventId, 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;
+/** Share admission with the durable sink, including explicit deny allowlists. */
+export function correlationReference(value, codecs = {}) {
+    return admittedReference(value, codecs.approveReference);
 }
 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;
@@ -14,44 +17,56 @@ export function timestamp(value) {
 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;
+function tracking(refs, codecs, approve) {
+    let rejectedTrackingRefs = 0, rejectedServices = 0, rejectedTrackingUrls = 0;
+    const trackingRefs = [];
+    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 });
     }
-    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) }] : [];
-    });
+    return { trackingRefs, rejectedTrackingRefs, rejectedServices, rejectedTrackingUrls };
 }
 export function observation(input) {
     const evidence = input.evidence;
-    const externalRef = reference(evidence.providerOrderId);
-    const providerFulfillmentRef = reference(evidence.fulfilmentNumber);
-    const orderNumber = reference(evidence.orderNumber);
+    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)
+    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");
-    const key = digest(JSON.stringify([input.event, externalRef ?? orderNumber, providerFulfillmentRef, occurredAt]));
+    // 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]);
     const fact = parseNormalizedFulfillmentFact({
-        schemaVersion: 1, mapperVersion: "1", factId: key, providerKind: "omnipack", fulfillmentReference: fulfillmentRef,
+        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) => ["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) };
+    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/dist/fulfillment/omnipack/reconciliation.d.ts

@@ -0,0 +1,15 @@
+import type { FulfillmentObservationPagePort, FulfillmentReconciliationObservation } from "../contracts/index.js";
+import type { OmnipackClient } from "./client.js";
+import type { OmnipackFulfilmentEvidence } from "./mappers.js";
+import { refusal, type OmnipackObservationCodecs } from "./observation.js";
+type Config = {
+    observationCodecs?: OmnipackObservationCodecs;
+    clock(): string;
+    mintEvidenceReference(): `evidence:${string}`;
+    approveTrackingUrl(url: string): boolean;
+};
+export declare function reconciliationObservation(row: OmnipackFulfilmentEvidence, config: Config, fulfillmentRef?: string): Extract<FulfillmentReconciliationObservation, {
+    kind: "found" | "unmapped";
+}>;
+export declare function createReconciliationPagePort(client: OmnipackClient, config: Config, ready: () => ReturnType<typeof refusal> | null): FulfillmentObservationPagePort;
+export {};