@openlup/platform 0.21.0 → 0.22.0

package/dist/fulfillment/providerStockAvailability.d.ts

@@ -0,0 +1,13 @@
+import type { FulfillmentStockSyncPort, LocalStock } from "./contracts/index.js";
+type StockLine = Awaited<ReturnType<FulfillmentStockSyncPort["readLocalInventoryStock"]>>[number];
+export declare function aggregateAtpCompatibleStock(lines: readonly StockLine[], now: Date): Map<string, LocalStock>;
+/** Cap the host-local movement window at UTC today, preserving donor overlap. */
+export declare function stockMovementWindow(cursor: {
+    lastMovementOccurredAt: string | null;
+    lastStockSyncedAt: string | null;
+} | null, now: Date, timeZone: string): {
+    startLocalDate: string;
+    endLocalDate: string;
+};
+export declare function emptyLocal(sku: string): LocalStock;
+export {};

package/dist/fulfillment/providerStockAvailability.js

@@ -0,0 +1,51 @@
+export function aggregateAtpCompatibleStock(lines, now) {
+    const requestedAt = now.toISOString();
+    const balances = new Map();
+    for (const line of lines.filter((item) => isAtpUsable(item, requestedAt))) {
+        const current = balances.get(line.skuRef) ?? emptyLocal(line.skuRef);
+        current.onHand += line.quantity.onHand;
+        current.reserved += line.quantity.reserved;
+        current.unavailable += line.quantity.unavailable;
+        current.safetyStock += line.quantity.safetyStock;
+        balances.set(line.skuRef, current);
+    }
+    return balances;
+}
+/** Cap the host-local movement window at UTC today, preserving donor overlap. */
+export function stockMovementWindow(cursor, now, timeZone) {
+    const startAt = new Date(cursor?.lastMovementOccurredAt ?? cursor?.lastStockSyncedAt ?? now.toISOString());
+    const safeStartAt = Number.isNaN(startAt.getTime()) ? now : startAt;
+    const endLocalDate = minDate(localDate(now, timeZone), utcDate(now));
+    return {
+        startLocalDate: minDate(localDate(safeStartAt, timeZone), endLocalDate),
+        endLocalDate,
+    };
+}
+function utcDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function minDate(a, b) {
+    return a <= b ? a : b;
+}
+function isAtpUsable(line, requestedAt) {
+    if (!line.fulfillable || line.locationStatus !== "active")
+        return false;
+    if (line.lotStatus && line.lotStatus !== "available")
+        return false;
+    if (line.expiresAt && Date.parse(line.expiresAt) <= Date.parse(requestedAt))
+        return false;
+    return true;
+}
+export function emptyLocal(sku) {
+    return { skuRef: sku, onHand: 0, reserved: 0, unavailable: 0, safetyStock: 0 };
+}
+function localDate(date, timeZone) {
+    const parts = new Intl.DateTimeFormat("en", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(date);
+    const byType = new Map(parts.map((part) => [part.type, part.value]));
+    return `${byType.get("year")}-${byType.get("month")}-${byType.get("day")}`;
+}

package/dist/fulfillment/providerStockSyncWorker.d.ts

@@ -0,0 +1,37 @@
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider } from "./contracts/index.js";
+type Threshold = Parameters<FulfillmentStockSyncPort["resolveLowStockEvidence"]>[0]["activeThresholdKinds"][number];
+interface StockSyncResult {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    mismatches: number;
+    reservationCoverage: number;
+    unclassified: number;
+    lowStock: number;
+    movements: number;
+    replayed: number;
+    failures: number;
+    providerCalls: number;
+    readBacks: number;
+    skipped: boolean;
+    syncRunId: string;
+    lastMovementOccurredAt: string | null;
+    reason?: string;
+}
+export declare function runFulfillmentStockSyncWorker(input: {
+    port: FulfillmentStockSyncPort;
+    provider: FulfillmentStockSyncProvider;
+    movementBatchSize: number;
+    staleSyncThresholdHours?: number;
+    now?: () => Date;
+    compatibility: {
+        syncRunId(now: Date): string;
+        staleEvidenceSku: string;
+        timeZone: string;
+        currentKey(run: string, sku: string): string;
+        snapshotKey(run: string, sku: string): string;
+        lowStockKey(sku: string, threshold: Threshold): string;
+        staleKey(lastSyncedAt: string): string;
+    };
+}): Promise<StockSyncResult>;
+export {};

package/dist/fulfillment/providerStockSyncWorker.js

@@ -0,0 +1,186 @@
+import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
+export async function runFulfillmentStockSyncWorker(input) {
+    const now = input.now?.() ?? new Date();
+    const staleThresholdHours = input.staleSyncThresholdHours && input.staleSyncThresholdHours > 0
+        ? input.staleSyncThresholdHours
+        : 6;
+    const syncRunId = input.compatibility.syncRunId(now);
+    const result = {
+        ok: true,
+        checked: 0,
+        updated: 0,
+        mismatches: 0,
+        reservationCoverage: 0,
+        unclassified: 0,
+        lowStock: 0,
+        movements: 0,
+        replayed: 0,
+        failures: 0,
+        providerCalls: 0,
+        readBacks: 0,
+        skipped: false,
+        syncRunId,
+        lastMovementOccurredAt: null,
+    };
+    const previousCursor = await input.port.readCursor();
+    // Stale-sync alert: if the last successful sync aged past the threshold, open a stale_sync
+    // low-stock evidence row (evidence/warn — never blocks sales); a healthy run resolves it
+    // below. A never-synced state (no prior cursor) is not "stale".
+    const lastSyncedMs = previousCursor?.lastStockSyncedAt ? Date.parse(previousCursor.lastStockSyncedAt) : null;
+    const staleGapHours = lastSyncedMs !== null && !Number.isNaN(lastSyncedMs) ? (now.getTime() - lastSyncedMs) / 3_600_000 : null;
+    const syncIsStale = staleGapHours !== null && staleGapHours >= staleThresholdHours;
+    if (syncIsStale) {
+        await input.port.recordLowStockEvidence({
+            requestKey: input.compatibility.staleKey(previousCursor.lastStockSyncedAt),
+            skuRef: input.compatibility.staleEvidenceSku,
+            thresholdKind: "stale_sync",
+            severity: "warning",
+            providerForSaleQuantity: 0,
+            localAvailableQuantity: 0,
+            syncRunId,
+        });
+    }
+    await input.port.recordCursor({
+        status: "running",
+        lastStockSyncedAt: null,
+        lastMovementOccurredAt: null,
+        continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+        coverageGapSkus: [], refusal: null,
+    });
+    const [localStock, providerStock] = await Promise.all([
+        input.port.readLocalInventoryStock(now.toISOString()),
+        input.provider.getStock(),
+    ]);
+    result.providerCalls += 1;
+    const stockItems = providerStock.filter((item) => item.skuRef.trim());
+    const skus = [...new Set(stockItems.map((item) => item.skuRef))];
+    const [inventoryClasses, activeReservations] = await Promise.all([
+        input.port.readSkuInventoryClasses(skus),
+        input.port.readActiveReservations(skus, now.toISOString()),
+    ]);
+    const movements = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
+    result.providerCalls += 1;
+    result.movements = movements.length;
+    result.lastMovementOccurredAt = latestOccurredAt(movements);
+    const localBySku = aggregateAtpCompatibleStock(localStock, now);
+    const coverageCandidates = [];
+    const currentCoverageGapSkus = new Set();
+    const packagingSkus = new Set();
+    const previousCoverageGapSkus = previousCursor?.status === "succeeded"
+        ? readStringSet(previousCursor.coverageGapSkus)
+        : new Set();
+    for (const stock of stockItems) {
+        try {
+            const local = localBySku.get(stock.skuRef) ?? emptyLocal(stock.skuRef);
+            const inventoryClass = inventoryClasses.get(stock.skuRef) ?? null;
+            const activeReserved = activeReservations.get(stock.skuRef) ?? 0;
+            const staleAfter = new Date(now.getTime() + staleThresholdHours * 3_600_000).toISOString();
+            const current = await input.port.recordProviderStockCurrent({
+                requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
+                snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
+            });
+            const snapshot = await input.port.recordStockSnapshot({
+                requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
+                snapshot: stock, local, mismatchKind: "none", inventoryClass,
+            });
+            result.checked += 1;
+            result.updated += (snapshot.replayed ? 0 : 1) + (current.replayed ? 0 : 1);
+            if (snapshot.replayed)
+                result.replayed += 1;
+            if (current.replayed)
+                result.replayed += 1;
+            if (snapshot.readBack)
+                result.readBacks += 1;
+            if (current.readBack)
+                result.readBacks += 1;
+            if (inventoryClass === null)
+                result.unclassified += 1;
+            if (inventoryClass === "packaging")
+                packagingSkus.add(stock.skuRef);
+            if (inventoryClass === "sellable") {
+                coverageCandidates.push({ stock, local, activeReserved });
+                if (activeReserved > stock.forSaleQuantity)
+                    currentCoverageGapSkus.add(stock.skuRef);
+            }
+        }
+        catch (error) {
+            result.ok = false;
+            result.failures += 1;
+            result.reason = result.reason ?? "stock_sync_operation_failed";
+        }
+    }
+    if (result.ok) {
+        for (const { stock, local, activeReserved } of coverageCandidates) {
+            const localAvailable = availableQuantity(local);
+            const confirmedCoverageGap = currentCoverageGapSkus.has(stock.skuRef) && previousCoverageGapSkus.has(stock.skuRef);
+            const lowStockSignals = lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap);
+            const activeThresholdKinds = lowStockSignals.map((signal) => signal.thresholdKind);
+            if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
+                activeThresholdKinds.push("reservation_coverage");
+            }
+            for (const signal of lowStockSignals) {
+                const evidence = await input.port.recordLowStockEvidence({
+                    requestKey: input.compatibility.lowStockKey(stock.skuRef, signal.thresholdKind),
+                    skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+                    providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, syncRunId,
+                });
+                if (evidence.replayed)
+                    result.replayed += 1;
+                result.lowStock += evidence.replayed ? 0 : 1;
+                if (signal.thresholdKind === "reservation_coverage")
+                    result.reservationCoverage += 1;
+            }
+            await input.port.resolveLowStockEvidence({
+                skuRef: stock.skuRef,
+                activeThresholdKinds,
+                syncRunId,
+            });
+        }
+        for (const sku of packagingSkus) {
+            await input.port.resolveLowStockEvidence({
+                skuRef: sku,
+                activeThresholdKinds: [],
+                syncRunId,
+            });
+        }
+    }
+    await input.port.recordCursor({
+        status: result.ok ? "succeeded" : "failed",
+        lastStockSyncedAt: result.ok ? now.toISOString() : null,
+        lastMovementOccurredAt: result.lastMovementOccurredAt,
+        continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+        coverageGapSkus: result.ok ? [...currentCoverageGapSkus].sort() : [],
+        refusal: result.ok ? null : { reason: "io_failure", phase: "sync", retryable: true },
+    });
+    // Recovery: a healthy run (succeeded, not itself stale) closes any open stale_sync row.
+    if (result.ok && !syncIsStale) {
+        await input.port.resolveLowStockEvidence({
+            skuRef: input.compatibility.staleEvidenceSku,
+            activeThresholdKinds: [],
+            syncRunId,
+        });
+    }
+    return result;
+}
+function lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap) {
+    const signals = [];
+    const remainingAfterReservations = Math.max(0, stock.forSaleQuantity - activeReserved);
+    if (local.safetyStock > 0 && remainingAfterReservations <= local.safetyStock) {
+        signals.push({ thresholdKind: "safety_stock", severity: remainingAfterReservations <= 0 ? "critical" : "warning" });
+    }
+    if (confirmedCoverageGap)
+        signals.push({ thresholdKind: "reservation_coverage", severity: "critical" });
+    return signals;
+}
+function readStringSet(value) {
+    return new Set(Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : []);
+}
+function availableQuantity(balance) {
+    return Math.max(0, balance.onHand - balance.reserved - balance.unavailable - balance.safetyStock);
+}
+function latestOccurredAt(movements) {
+    return movements
+        .map((movement) => movement.occurredAt)
+        .filter((value) => Boolean(value))
+        .sort((a, b) => Date.parse(b) - Date.parse(a))[0] ?? null;
+}

package/dist/fulfillment/providerTrackingReferences.d.ts

@@ -0,0 +1,15 @@
+import type { FulfillmentTrackingReference } from "./contracts/index.js";
+export declare function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean;
+/** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
+export declare function enrichTrackingReference(ref: FulfillmentTrackingReference, deliveryCarrier: {
+    carrierRef: string | null;
+    serviceRef: string | null;
+} | null, codecs: {
+    normalizeCarrier(input: {
+        carrierRef: string | null;
+        serviceRef: string | null;
+    }): string | null;
+    publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
+}): FulfillmentTrackingReference;
+/** First occurrence wins, including its selection, after trimming the number. */
+export declare function uniqueTrackingReferences(refs: readonly FulfillmentTrackingReference[]): FulfillmentTrackingReference[];

package/dist/fulfillment/providerTrackingReferences.js

@@ -0,0 +1,23 @@
+export function trackingReferenceComplete(ref) {
+    return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
+}
+/** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
+export function enrichTrackingReference(ref, deliveryCarrier, codecs) {
+    const providerCarrier = ref.carrierRef ?? codecs.normalizeCarrier(ref);
+    const carrierRef = providerCarrier ?? codecs.normalizeCarrier({ carrierRef: deliveryCarrier?.carrierRef ?? null, serviceRef: deliveryCarrier?.serviceRef ?? null });
+    return { trackingNumber: ref.trackingNumber, publicUrl: ref.publicUrl ?? codecs.publicUrl(carrierRef, ref.trackingNumber),
+        carrierRef, serviceRef: ref.serviceRef ?? (providerCarrier ? null : deliveryCarrier?.serviceRef ?? null) };
+}
+/** First occurrence wins, including its selection, after trimming the number. */
+export function uniqueTrackingReferences(refs) {
+    const seen = new Set();
+    const result = [];
+    for (const ref of refs) {
+        const trackingNumber = ref.trackingNumber.trim();
+        if (!trackingNumber || seen.has(trackingNumber))
+            continue;
+        seen.add(trackingNumber);
+        result.push({ trackingNumber, publicUrl: ref.publicUrl ?? null, carrierRef: ref.carrierRef ?? null, serviceRef: ref.serviceRef ?? null });
+    }
+    return result;
+}

package/dist/fulfillment/replacementRefusals.d.ts

@@ -0,0 +1,5 @@
+export declare const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS: readonly ["invalid_input", "idempotency_conflict", "order_not_found", "order_not_replaceable", "missing_client", "missing_shipping_address", "shipping_address_not_found", "payment_not_succeeded", "subscription_cycle_not_paid", "no_parcel_to_replace", "undispatched_replacement_exists", "missing_order_items", "missing_catalog_sku", "missing_inventory_reservation", "blocked_by_payment_not_succeeded_hold", "blocked_by_inventory_review_hold", "blocked_by_risk_review_hold", "blocked_by_address_review_hold", "blocked_by_manual_support_hold"];
+export declare const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS: readonly ["inventory_external_provider_insufficient_available_stock", "inventory_external_provider_stock_stale", "inventory_external_provider_stock_missing", "inventory_external_provider_sku_not_found", "inventory_external_provider_location_missing", "inventory_reservation_insufficient_available_stock", "inventory_reservation_allocation_incomplete", "inventory_reservation_payment_status_not_reservable", "inventory_reservation_invalid_quantity"];
+export declare const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export declare const FULFILLMENT_REPLACEMENT_REFUSALS: readonly ["invalid_input", "idempotency_conflict", "order_not_found", "order_not_replaceable", "missing_client", "missing_shipping_address", "shipping_address_not_found", "payment_not_succeeded", "subscription_cycle_not_paid", "no_parcel_to_replace", "undispatched_replacement_exists", "missing_order_items", "missing_catalog_sku", "missing_inventory_reservation", "blocked_by_payment_not_succeeded_hold", "blocked_by_inventory_review_hold", "blocked_by_risk_review_hold", "blocked_by_address_review_hold", "blocked_by_manual_support_hold", "inventory_external_provider_insufficient_available_stock", "inventory_external_provider_stock_stale", "inventory_external_provider_stock_missing", "inventory_external_provider_sku_not_found", "inventory_external_provider_location_missing", "inventory_reservation_insufficient_available_stock", "inventory_reservation_allocation_incomplete", "inventory_reservation_payment_status_not_reservable", "inventory_reservation_invalid_quantity", "unspecified_refusal"];
+export type FulfillmentReplacementRefusal = (typeof FULFILLMENT_REPLACEMENT_REFUSALS)[number];

package/dist/fulfillment/replacementRefusals.js

@@ -0,0 +1,38 @@
+export const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS = [
+    "invalid_input",
+    "idempotency_conflict",
+    "order_not_found",
+    "order_not_replaceable",
+    "missing_client",
+    "missing_shipping_address",
+    "shipping_address_not_found",
+    "payment_not_succeeded",
+    "subscription_cycle_not_paid",
+    "no_parcel_to_replace",
+    "undispatched_replacement_exists",
+    "missing_order_items",
+    "missing_catalog_sku",
+    "missing_inventory_reservation",
+    "blocked_by_payment_not_succeeded_hold",
+    "blocked_by_inventory_review_hold",
+    "blocked_by_risk_review_hold",
+    "blocked_by_address_review_hold",
+    "blocked_by_manual_support_hold",
+];
+export const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS = [
+    "inventory_external_provider_insufficient_available_stock",
+    "inventory_external_provider_stock_stale",
+    "inventory_external_provider_stock_missing",
+    "inventory_external_provider_sku_not_found",
+    "inventory_external_provider_location_missing",
+    "inventory_reservation_insufficient_available_stock",
+    "inventory_reservation_allocation_incomplete",
+    "inventory_reservation_payment_status_not_reservable",
+    "inventory_reservation_invalid_quantity",
+];
+export const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export const FULFILLMENT_REPLACEMENT_REFUSALS = [
+    ...FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS,
+    ...FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS,
+    UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL,
+];

package/dist/fulfillment/replacementShipmentHandler.d.ts

@@ -0,0 +1,5 @@
+import { type BaseDeps, type FulfillmentHandlerRequest } from './handlerSupport.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+export declare function createAdminCommerceOrderRequestReplacementShipmentHandler<Response>({ authorizeAdmin, respond, omsPort, }: BaseDeps<Response> & {
+    omsPort: FulfillmentReplacementPort;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;

package/dist/fulfillment/replacementShipmentHandler.js

@@ -0,0 +1,46 @@
+import { adminCommerceOrderRequestReplacementShipmentRequestSchema, adminCommerceOrderRequestReplacementShipmentResponseSchema } from './handlerSchemas.js';
+import { authorize, CommerceFulfillmentConflictError, isNativeUnsupported } from './handlerSupport.js';
+export function createAdminCommerceOrderRequestReplacementShipmentHandler({ authorizeAdmin, respond, omsPort, }) {
+    const { sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderRequestReplacementShipmentRequestSchema, req.body ?? {}, "Invalid admin commerce replacement shipment request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.requestReplacementShipment({ ...request, actorUserId: auth.userId }), adminCommerceOrderRequestReplacementShipmentResponseSchema, "Admin commerce replacement shipment returned invalid response", "Admin commerce replacement shipment failed");
+    };
+}
+function parseOmsRequest(res, respond, schema, input, message) {
+    const request = schema.safeParse(input);
+    if (!request.success) {
+        respond.sendBffError(res, 'BAD_REQUEST', message, { details: request.error.flatten() });
+        return undefined;
+    }
+    return request.data;
+}
+async function sendOmsMutationResponse(res, respond, action, schema, invalidMessage, failureMessage) {
+    try {
+        const result = await action();
+        if (isNativeUnsupported(result)) {
+            respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', 'Native fulfillment operation unsupported', { details: result });
+            return;
+        }
+        const response = schema.safeParse(result);
+        if (!response.success) {
+            respond.sendBffError(res, 'INVALID_RESPONSE', invalidMessage);
+            return;
+        }
+        respond.sendBffSuccess(res, response.data);
+    }
+    catch (error) {
+        if (error instanceof CommerceFulfillmentConflictError) {
+            respond.sendBffError(res, 'CONFLICT', error.message, { details: error.details });
+            return;
+        }
+        respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', failureMessage);
+    }
+}

package/dist/fulfillment/schemaCapabilities.d.ts

@@ -0,0 +1,13 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export declare const FULFILLMENT_NATIVE_CAPABILITIES: {
+    readonly shipment: "supported";
+    readonly commandFence: "supported";
+    readonly deliveryAlignment: "supported";
+    readonly stockEvidence: "supported";
+    readonly observationPersistence: "supported";
+    readonly localInventoryBalances: "host_required";
+    readonly dispatchContactPreparation: "host_required";
+    readonly productPacks: "unsupported";
+    readonly providerAccess: "unsupported";
+    readonly automaticReplacementConfirmation: "unsupported";
+};

package/dist/fulfillment/schemaCapabilities.js

@@ -0,0 +1,7 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export const FULFILLMENT_NATIVE_CAPABILITIES = {
+    shipment: 'supported', commandFence: 'supported', deliveryAlignment: 'supported',
+    stockEvidence: 'supported', observationPersistence: 'supported',
+    localInventoryBalances: 'host_required', dispatchContactPreparation: 'host_required',
+    productPacks: 'unsupported', providerAccess: 'unsupported', automaticReplacementConfirmation: 'unsupported',
+};

package/dist/fulfillment/shipmentsOverviewHandler.d.ts

@@ -0,0 +1,16 @@
+import { type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import type { FulfillmentShipmentsOverviewPort, FulfillmentShipmentsOverviewResponse } from './contracts/read.js';
+export interface FulfillmentShipmentsOverviewHandlerDeps<Response> {
+    respond: FulfillmentHandlerResponder<Response>;
+    overviewPort: FulfillmentShipmentsOverviewPort;
+    responseSchema: {
+        safeParse(input: unknown): {
+            success: true;
+            data: FulfillmentShipmentsOverviewResponse;
+        } | {
+            success: false;
+        };
+    };
+    authorizeAdmin: (req: FulfillmentHandlerRequest) => Promise<boolean>;
+}
+export declare function createFulfillmentShipmentsOverviewHandler<Response>({ respond, overviewPort, responseSchema: adminShipmentsOverviewResponseSchema, authorizeAdmin, }: FulfillmentShipmentsOverviewHandlerDeps<Response>): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;

package/dist/fulfillment/shipmentsOverviewHandler.js

@@ -0,0 +1,54 @@
+import { isNativeUnsupported } from './handlerSupport.js';
+import { z } from 'zod';
+const adminShipmentsOverviewRequestSchema = z.object({
+    shippedFilter: z.enum(['today', '7d', '30d', 'all']).default('7d'),
+});
+export function createFulfillmentShipmentsOverviewHandler({ respond, overviewPort, responseSchema: adminShipmentsOverviewResponseSchema, authorizeAdmin, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        let authorized = false;
+        try {
+            authorized = await authorizeAdmin(req);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+            return;
+        }
+        if (!authorized) {
+            sendBffError(res, "UNAUTHORIZED", "Admin session required");
+            return;
+        }
+        const request = adminShipmentsOverviewRequestSchema.safeParse({
+            shippedFilter: scalarQuery(req.query.shippedFilter),
+        });
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid shipments overview request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await overviewPort.getShipmentsOverview(request.data);
+            if (isNativeUnsupported(result)) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+                return;
+            }
+            const response = adminShipmentsOverviewResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Shipments overview returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipments overview read failed");
+        }
+    };
+}
+function scalarQuery(value) {
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/fulfillment/statusMap.d.ts

@@ -0,0 +1,2 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";
+export type { FulfillmentStatusStage, FulfillmentStatusMap } from "@openlup/core/fulfillment";

package/dist/fulfillment/statusMap.js

@@ -0,0 +1 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";

package/dist/fulfillment/trackingProgress.d.ts

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/trackingProgress.js

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/verifiedIngress.d.ts

@@ -0,0 +1,52 @@
+import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
+type DispatchRef = {
+    orderRef: string;
+    fulfillmentRef: string;
+    dispatchRef: string;
+    externalRef: string | null;
+};
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export declare function verifyAndNormalizeFulfillmentObservation(input: {
+    enabled: boolean;
+    provider: FulfillmentObservationPort;
+    verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
+    localPersistence: {
+        /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
+        recordObservation(observation: FulfillmentObservation): Promise<{
+            replayed: boolean;
+        }>;
+        /** Idempotent; only called after completion or a classified superseding conflict. */
+        markProcessed(eventKey: string, outcome: {
+            status: "processed" | "ignored";
+            refusal?: FulfillmentRefusal;
+        }): Promise<void>;
+    };
+    lifecycle: {
+        findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
+        acknowledgeDispatchAcceptance(ref: DispatchRef, observation: FulfillmentObservation): Promise<void>;
+        recordStatusEvidence(ref: DispatchRef, observation: FulfillmentObservation): Promise<{
+            replayed: boolean;
+        }>;
+        effects: EffectInput["port"];
+        keys: {
+            stock(ref: string): string;
+            handoff(ref: string): string;
+            tracking(eventKey: string, number: string): string;
+        };
+        issueAccountingInvoice?(ref: string): Promise<void>;
+        classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
+        annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
+    };
+}): Promise<{
+    kind: "refused";
+    refusal: FulfillmentRefusal;
+} | {
+    kind: "processed" | "ignored" | "superseded";
+    observation: FulfillmentObservation;
+    replayed: boolean;
+    trackingRefs: number;
+    trackingReadBacks: number;
+}>;
+export {};