@openlup/platform 0.21.0 → 0.23.0

package/dist/fulfillment/observationProjection.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { parseFulfillmentFact } from "./normalizedFulfillmentFacts.js";
+import { admittedReference, durableStrings, reference } from "./dispatchProjection.js";
+import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
+const timestamp = z.iso.datetime({ offset: true });
+export function projectCorrelation(value, privacy = durableStrings(), codecs = {}) {
+    const token = (value) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+    return { orderRef: value.orderRef, fulfillmentRef: value.fulfillmentRef, externalRef: token(value.externalRef),
+        orderNumber: token(value.orderNumber), providerFulfillmentRef: token(value.providerFulfillmentRef), parcelRef: value.parcelRef };
+}
+export function projectProviderStatus(value, privacy = durableStrings()) {
+    return { primary: privacy.token(value.primary), subStatus: privacy.token(value.subStatus) };
+}
+function pollEvidence(value, privacy, codecs = {}) {
+    // Host identities and keys composed from admitted parts are already authoritative.
+    return { eventKey: value.eventKey, correlation: projectCorrelation(value.correlation, privacy, codecs),
+        ...(value.providerStatus ? { providerStatus: projectProviderStatus(value.providerStatus, privacy) } : {}) };
+}
+/** Unknown-status quarantine/ACK evidence has the same privacy boundary as observations. */
+export function projectPollEvidence(value) {
+    const privacy = durableStrings(value.diagnostics?.redactedFieldCount);
+    const safe = pollEvidence(value, privacy);
+    return { ...safe, ...(privacy.redactedFieldCount ? { diagnostics: { redactedFieldCount: privacy.redactedFieldCount } } : {}) };
+}
+/** One URL policy: strict default, optional adopter codec, and approval at every sink. */
+export function publicTrackingUrl(value, approve, codec) {
+    try {
+        const candidate = codec ? codec(value) : value;
+        if (!candidate)
+            return null;
+        const url = new URL(candidate);
+        return url.protocol === "https:" && !url.username && !url.password && (codec || (!url.search && !url.hash)) && approve?.(url.href) ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function projectTrackingReference(value, privacy = durableStrings(), approveTrackingUrl, codecs = {}) {
+    const token = (value) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+    const trackingNumber = token(value.trackingNumber);
+    if (trackingNumber === null)
+        return null;
+    const serviceRef = token(value.serviceRef);
+    // Even an opaque-looking derived carrier is unsafe when its service was refused.
+    const carrierRef = privacy.token(value.carrierRef, text => value.serviceRef !== null && serviceRef === null ? null : reference(text));
+    return { trackingNumber, carrierRef, serviceRef,
+        publicUrl: privacy.token(value.publicUrl, url => publicTrackingUrl(url, approveTrackingUrl, codecs.trackingUrl)) };
+}
+/** New boundary projection: arbitrary adapter properties are never durable. */
+export function projectObservation(value, approveTrackingUrl, codecs = {}) {
+    const privacy = durableStrings(value.diagnostics?.redactedFieldCount), token = privacy.token;
+    const diagnostics = {};
+    if (value.diagnostics?.admission) {
+        const count = (value) => Number.isSafeInteger(value) && value > 0 ? value : 0;
+        diagnostics.admission = { rejectedTrackingRefs: count(value.diagnostics.admission.rejectedTrackingRefs), rejectedTrackingUrls: count(value.diagnostics.admission.rejectedTrackingUrls) };
+    }
+    if (value.diagnostics?.refusal) {
+        const { reason, phase, retryable } = value.diagnostics.refusal;
+        diagnostics.refusal = { reason: token(reason), phase: token(phase), retryable };
+    }
+    if (value.diagnostics?.stockContention)
+        diagnostics.stockContention = { sqlState: "55P03", phase: "provider_stock_consumed", retryable: true };
+    if (value.diagnostics?.annotation)
+        diagnostics.annotation = token(value.diagnostics.annotation);
+    if (value.diagnostics?.recoveredPickedReceipt) {
+        const { receiptRef, closed } = value.diagnostics.recoveredPickedReceipt;
+        diagnostics.recoveredPickedReceipt = { receiptRef, closed };
+    }
+    const fact = parseFulfillmentFact(value.fact);
+    const safe = {
+        ...pollEvidence(value, privacy, codecs),
+        fact: { ...fact, mapperVersion: token(fact.mapperVersion) ?? "redacted" }, eventKind: (token(value.eventKind) ?? "redacted"),
+        firstReceivedAt: timestamp.parse(value.firstReceivedAt),
+        trackingRefs: value.trackingRefs.flatMap(ref => {
+            const projected = projectTrackingReference(ref, privacy, approveTrackingUrl, codecs);
+            return projected ? [projected] : [];
+        }),
+    };
+    if (privacy.redactedFieldCount)
+        diagnostics.redactedFieldCount = privacy.redactedFieldCount;
+    return { ...safe, ...(Object.keys(diagnostics).length ? { diagnostics } : {}) };
+}
+const HANDOVER_STATUSES = new Set(FULFILLMENT_STATUS_MAP.stages.filter(stage => stage.effects.handover).flatMap(stage => stage.localStatus));
+/** Donor finished-picking boundary is narrower than the coarse packing stage. */
+export const observationStatusPolicy = {
+    consumesStock: (status) => ["packed", "in_transit", "delivered"].includes(status),
+    handsOver: (status) => HANDOVER_STATUSES.has(status),
+    suppressDispatched: (status) => status === "delivered",
+    trackingStatus: (status) => status,
+};

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

@@ -0,0 +1,3 @@
+import type { FulfillmentCapabilityDescriptor } from "../contracts/index.js";
+/** Offline protocol capabilities; selection and account readiness belong to the host. */
+export declare const omnipackFulfillmentCapabilities: Readonly<FulfillmentCapabilityDescriptor>;

package/dist/fulfillment/omnipack/capabilities.js

@@ -0,0 +1,16 @@
+/** Offline protocol capabilities; selection and account readiness belong to the host. */
+export const omnipackFulfillmentCapabilities = Object.freeze({
+    providerRef: "omnipack", role: "warehouse", defaultOff: true, selected: false,
+    readiness: Object.freeze({ ready: false, refusal: Object.freeze({ reason: "not_ready", phase: "selection", retryable: false }) }),
+    operations: Object.freeze({
+        dispatch: Object.freeze({ supported: true }), readback: Object.freeze({ supported: true }),
+        exactAbsence: Object.freeze({ supported: false, reason: "not_exposed" }), verifyObservation: Object.freeze({ supported: true }),
+        syncStock: Object.freeze({ supported: true }), syncProducts: Object.freeze({ supported: true }),
+        labelCreate: Object.freeze({ supported: false, reason: "not_exposed" }), labelRead: Object.freeze({ supported: false, reason: "host_only" }),
+        labelVoid: Object.freeze({ supported: false, reason: "not_exposed" }), cancel: Object.freeze({ supported: false, reason: "not_exposed" }),
+        pickupPoint: Object.freeze({ supported: true }), courierPickup: Object.freeze({ supported: false, reason: "not_exposed" }),
+    }),
+    authentication: "token", freshness: "not_available", ownsDeliveredNotification: false,
+    stockAuthority: "external_stock_master_with_local_reservations", labelReadOwner: "host_storage",
+    actionPolicy: Object.freeze({ providerSpecificAdminActions: false, genericAdminActions: true, mutationSurface: "provider_adapter" }),
+});

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

@@ -0,0 +1,39 @@
+import { type OmnipackFulfilmentEvidence, type OmnipackFulfilmentRequestEvidence, type OmnipackOrderCreatedEvidence, type OmnipackProductCreatedEvidence, type OmnipackStockEvidence, type OmnipackStockMovementEvidence } from "./mappers.js";
+import { type OmnipackProductEvidence, type OmnipackProductPackCreatedEvidence } from "./productSyncMappers.js";
+export { OmnipackProviderError, sanitizeOmnipackProviderError, type SanitizedOmnipackProviderError, } from "./providerError.js";
+export interface OmnipackClientConfig {
+    baseUrl: string;
+    credentials: () => {
+        username: string;
+        password: string;
+    } | Promise<{
+        username: string;
+        password: string;
+    }>;
+    timeoutMs: number;
+    safeReadRetries: number;
+    productPath: string;
+}
+export interface OmnipackClient {
+    createOrder(body: string): Promise<OmnipackOrderCreatedEvidence>;
+    createProduct(payload: Record<string, unknown>, sku: string): Promise<OmnipackProductCreatedEvidence>;
+    getProduct(sku: string): Promise<OmnipackProductEvidence>;
+    createProductPack(sku: string, payload: Record<string, unknown>, ean: string): Promise<OmnipackProductPackCreatedEvidence>;
+    getStock(options?: {
+        refuseRedirectRetry: boolean;
+    }): Promise<OmnipackStockEvidence[]>;
+    getStockMovements(params?: OmnipackQueryParams): Promise<OmnipackStockMovementEvidence[]>;
+    getFulfilmentsPage(params?: OmnipackQueryParams): Promise<{
+        rows: OmnipackFulfilmentEvidence[];
+        complete: boolean;
+    }>;
+    getFulfilments(params?: OmnipackQueryParams): Promise<OmnipackFulfilmentEvidence[]>;
+    getFulfilmentRequests(params?: OmnipackQueryParams): Promise<OmnipackFulfilmentRequestEvidence[]>;
+}
+export interface OmnipackQueryParams {
+    startLocalDate?: string;
+    endLocalDate?: string;
+    page?: number;
+    size?: number;
+}
+export declare function createOmnipackClient(config: OmnipackClientConfig, fetchImpl: typeof fetch): OmnipackClient;

package/dist/fulfillment/omnipack/client.js

@@ -0,0 +1,172 @@
+import { mapOmnipackFulfilmentRequestsResponse, mapOmnipackFulfilmentsResponse, mapOmnipackOrderCreatedResponse, mapOmnipackProductCreatedResponse, mapOmnipackStockMovementsResponse, mapOmnipackStockResponse, sanitizeOmnipackPayload, } from "./mappers.js";
+import { mapOmnipackProductPackCreatedResponse, mapOmnipackProductResponse, } from "./productSyncMappers.js";
+import { mayPostHaveSucceeded, OmnipackProviderError } from "./providerError.js";
+export { OmnipackProviderError, sanitizeOmnipackProviderError, } from "./providerError.js";
+const PRODUCT_PACKS_SEGMENT = "packs";
+export function createOmnipackClient(config, fetchImpl) {
+    return {
+        async createOrder(body) {
+            return mapOmnipackOrderCreatedResponse(await requestJson(fetchImpl, config, "createOrder", "/orders", {
+                method: "POST",
+                body,
+            }));
+        },
+        async createProduct(payload, sku) {
+            const body = await requestJson(fetchImpl, config, "createProduct", config.productPath, post(payload));
+            return mapOmnipackProductCreatedResponse(body, sku);
+        },
+        async getProduct(sku) {
+            const path = productResourcePath(config.productPath, sku);
+            return mapOmnipackProductResponse(await requestJson(fetchImpl, config, "getProduct", path, { method: "GET" }), sku);
+        },
+        async createProductPack(sku, payload, ean) {
+            const path = `${productResourcePath(config.productPath, sku)}/${PRODUCT_PACKS_SEGMENT}`;
+            const body = await requestJson(fetchImpl, config, "createProductPack", path, post(payload));
+            return mapOmnipackProductPackCreatedResponse(body, sku, ean);
+        },
+        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" }, true));
+        },
+        async getFulfilmentsPage(params) {
+            const body = await requestJson(fetchImpl, config, "getFulfilments", withQuery("/fulfilments", params), { method: "GET" });
+            const rows = mapOmnipackFulfilmentsResponse(body);
+            // Only explicit single-page totals establish whole-collection uniqueness.
+            const record = body;
+            const page = record?.page;
+            const complete = page?.number === 0 && page.totalPages === 1 && page.totalElements === rows.length
+                && typeof page.size === "number" && Number.isSafeInteger(page.size) && page.size >= rows.length && page.size > 0
+                && !record?._links?.next && !record?.incomplete && !record?.partial;
+            return { rows, complete };
+        },
+        async getFulfilments(params) {
+            return mapOmnipackFulfilmentsResponse(await requestJson(fetchImpl, config, "getFulfilments", withQuery("/fulfilments", params), { method: "GET" }));
+        },
+        async getFulfilmentRequests(params) {
+            return mapOmnipackFulfilmentRequestsResponse(await requestJson(fetchImpl, config, "getFulfilmentRequests", withQuery("/fulfilment-requests", params), { method: "GET" }));
+        },
+    };
+}
+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;
+        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; });
+            if (response.ok)
+                return await readJsonBody(response);
+            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({
+                operation,
+                status: response.status,
+                code: refuseRedirectRetry && response.status >= 300 && response.status < 400 ? "redirect_refused" : readProviderErrorCode(body) ?? `http_${response.status}`,
+                retryable,
+                mayHaveSucceeded: mayPostHaveSucceeded(method, response.status),
+            });
+            if (!retryable || attempt === attempts)
+                throw lastError;
+        }
+        catch (error) {
+            const retryable = method === "GET" && attempt < attempts;
+            lastError = submitted && error instanceof OmnipackProviderError
+                ? error
+                : new OmnipackProviderError({
+                    operation,
+                    status: null,
+                    code: diagnoseRedirectFailure && isRedirectRefusal(error) ? "redirect_refused" : "network_error",
+                    retryable,
+                    mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
+                });
+            if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused"))
+                throw lastError;
+        }
+    }
+    throw lastError;
+}
+async function fetchWithTimeout(fetchImpl, url, config, init, onSubmit) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const credentials = await config.credentials();
+        const requestInit = {
+            ...init,
+            signal: controller.signal,
+            redirect: "error",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Basic ${Buffer.from(`${credentials.username}:${credentials.password}`).toString("base64")}`,
+                ...(init.headers ?? {}),
+            },
+        };
+        new Request(url, requestInit); // Validate construction before crossing the submission boundary.
+        controller.signal.throwIfAborted();
+        onSubmit();
+        return await fetchImpl(url, requestInit);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readJsonBody(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return sanitizeOmnipackPayload(JSON.parse(text));
+    }
+    catch {
+        return {};
+    }
+}
+// A non-retried JSON POST init (mutations must not be silently re-sent — requestJson keys retry
+// off the GET method).
+function post(payload) {
+    return { method: "POST", body: JSON.stringify(payload) };
+}
+// Per-product resource path (GET /products/{sku}, base for /packs). sku is percent-encoded; the
+// product path is right-trimmed so a trailing-slash path override does not double the slash.
+function productResourcePath(productPath, sku) {
+    return `${productPath.replace(/\/+$/, "")}/${encodeURIComponent(sku)}`;
+}
+function withQuery(path, params) {
+    const url = new URL(path, "https://example.test");
+    if (params?.startLocalDate)
+        url.searchParams.set("startLocalDate", params.startLocalDate);
+    if (params?.endLocalDate)
+        url.searchParams.set("endLocalDate", params.endLocalDate);
+    if (typeof params?.page === "number")
+        url.searchParams.set("page", String(params.page));
+    if (typeof params?.size === "number")
+        url.searchParams.set("size", String(params.size));
+    return `${url.pathname}${url.search}`;
+}
+function readProviderErrorCode(body) {
+    return typeof body === "object" && body !== null && "code" in body && typeof body.code === "string"
+        && /^[A-Z][A-Z0-9_]{0,63}$/.test(body.code)
+        ? body.code
+        : null;
+}
+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

@@ -0,0 +1,55 @@
+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 {
+    http: {
+        baseUrl: string;
+        credentials: () => {
+            username: string;
+            password: string;
+        } | Promise<{
+            username: string;
+            password: string;
+        }>;
+        fetchImpl: typeof fetch;
+        timeoutMs: number;
+        safeReadRetries: number;
+        productPath: string;
+    };
+    selected?: boolean;
+    /** Per-instance retention target; default 10,000. Evicts oldest completed submissions, never in-flight. */
+    maxRetainedSubmissions?: number;
+    /** Host account evidence, independent of credentials. Omission remains not ready. */
+    readiness?: FulfillmentCapabilityDescriptor["readiness"];
+    /** Called in prepare and again for new dispatches; return identical metadata for the same request or dispatch refuses. */
+    resolveProduct: (line: FulfillmentDispatchRequest["lines"][number]) => Promise<{
+        lotNumber?: string;
+        expirationDate?: string;
+    } | null>;
+    notification: {
+        token: () => string | undefined | Promise<string | undefined>;
+        expectedEvent: OmnipackWebhookRouteEvent;
+    };
+    clock: () => string;
+    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>;
+    };
+}
+/** No route, schedule, environment reader or default binding is installed. */
+export declare function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdapterConfig): {
+    capabilities: FulfillmentCapabilityDescriptor;
+    dispatch: FulfillmentDispatchPort;
+    label: FulfillmentLabelPort;
+    observation: FulfillmentObservationPort;
+    readback: FulfillmentReadbackPort;
+    reconciliation: FulfillmentObservationPagePort;
+    stockSync: FulfillmentStockSyncProvider;
+    productSync: FulfillmentProductSyncProvider;
+};