@openlup/platform 0.21.0 → 0.23.0

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

@@ -0,0 +1,72 @@
+import type { NormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import type { CanonicalLocalFulfillmentStatus } from "./index.js";
+import type { FulfillmentRefusal } from "./dispatch.js";
+/** Explicit adopter policy, forwarded through each durable observation projection. */
+export interface FulfillmentObservationCodecs {
+    approveReference?(value: string): boolean;
+    /** Overrides the query/fragment default; HTTPS, no credentials and URL approval still apply. */
+    trackingUrl?(url: string): string | null;
+}
+export interface FulfillmentTrackingReference {
+    trackingNumber: string; /** Normalized carrier kind, never a raw provider code. */
+    carrierRef: string | null;
+    serviceRef: string | null;
+    publicUrl: string | null;
+}
+/** Durable normalized envelope. eventKey, not the receivedAt-bearing fact fingerprint, deduplicates retries. */
+export interface FulfillmentObservation {
+    fact: NormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+    eventKind: "shipment.accepted" | "order.processing_started" | "order.picked" | "order.shipped" | "order.delivered" | "parcel.exception" | "parcel.cancelled";
+    eventKey: string;
+    firstReceivedAt: string;
+    correlation: {
+        orderRef: string | null;
+        fulfillmentRef: string | null;
+        externalRef: string | null;
+        orderNumber: string | null;
+        providerFulfillmentRef: string | null;
+        parcelRef: string | null;
+    };
+    trackingRefs: readonly FulfillmentTrackingReference[];
+    /** Original provider status tokens; canonical status does not identify an occurrence. */
+    providerStatus?: {
+        primary: string | null;
+        subStatus: string | null;
+    };
+    diagnostics?: {
+        redactedFieldCount?: number;
+        admission?: {
+            rejectedTrackingRefs: number;
+            rejectedTrackingUrls: number;
+        };
+        refusal?: FulfillmentRefusal;
+        stockContention?: {
+            sqlState: "55P03";
+            phase: "provider_stock_consumed";
+            retryable: true;
+        };
+        annotation?: "recorded" | "failed";
+        recoveredPickedReceipt?: {
+            receiptRef: string;
+            closed: boolean;
+        };
+    };
+}
+export interface FulfillmentObservationPort {
+    /** Authenticate untouched bytes before parsing. Inputs live only during verification. */
+    verifyAndNormalize(input: {
+        rawBody: Uint8Array;
+        headers: Readonly<Record<string, string>>;
+        receivedAt: string;
+    }): Promise<{
+        kind: "verified";
+        observation: FulfillmentObservation;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+        diagnostics?: {
+            invalidTimestamp?: true;
+            rejectedCorrelationRefs?: number;
+        };
+    }>;
+}

package/dist/fulfillment/contracts/observation.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/operator.d.ts

@@ -0,0 +1,64 @@
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+/** Host transaction inputs. actorUserId and idempotencyKey are required for attribution and replay receipts. */
+interface MutationInput {
+    idempotencyKey: string;
+    actorUserId: string;
+    metadata?: Record<string, unknown>;
+}
+interface ParcelMutationInput extends MutationInput {
+    fulfillmentOrderId: string;
+}
+type AdminCommerceFulfillmentCreateRequest = MutationInput & {
+    orderId: string;
+};
+type AdminCommerceFulfillmentRecordProviderAttemptRequest = ParcelMutationInput & {
+    providerKind: string;
+    status: 'recorded' | 'succeeded' | 'failed';
+    requestPayload?: Record<string, unknown>;
+    responsePayload?: Record<string, unknown>;
+    error?: string | null;
+};
+type AdminCommerceFulfillmentRecordLabelRequest = ParcelMutationInput & {
+    providerKind: string;
+    providerTrackingId: string;
+    labelUrl?: string | null;
+    deliveryEstimateDays?: number | null;
+    rawProviderPayload?: Record<string, unknown>;
+};
+type AdminCommerceFulfillmentHandOffRequest = ParcelMutationInput;
+type AdminCommerceFulfillmentTrackingEventRequest = ParcelMutationInput & {
+    status: 'in_transit' | 'delivered' | 'exception';
+    providerTrackingId?: string;
+    rawEvent?: Record<string, unknown>;
+};
+type AdminCommerceFulfillmentCancelRequest = ParcelMutationInput & {
+    reason: string;
+};
+export interface FulfillmentOperatorMutationResult {
+    contractVersion: 'commerce.fulfillment.v0';
+    fulfillmentOrderId: string;
+    orderId: string;
+    status: 'created' | 'packed' | 'label_pending' | 'label_created' | 'handed_over' | 'in_transit' | 'delivered' | 'exception' | 'cancelled';
+    replayed: boolean;
+}
+export interface FulfillmentOperatorMutationPort {
+    createCommerceFulfillmentOrder(request: AdminCommerceFulfillmentCreateRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentProviderAttempt(request: AdminCommerceFulfillmentRecordProviderAttemptRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentLabel(request: AdminCommerceFulfillmentRecordLabelRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    handOffCommerceFulfillmentOrder(request: AdminCommerceFulfillmentHandOffRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentTrackingEvent(request: AdminCommerceFulfillmentTrackingEventRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    cancelCommerceFulfillmentOrder(request: AdminCommerceFulfillmentCancelRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+}
+export {};

package/dist/fulfillment/contracts/operator.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/read.d.ts

@@ -0,0 +1,110 @@
+import type { SubscriptionCycleStatus } from '@openlup/core/subscription';
+import type { PaymentIntentStatus } from '@openlup/core/payment';
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export type FulfillmentOrderStatus = 'draft' | 'pending_payment' | 'paid' | 'failed' | 'expired' | 'fulfillment_pending' | 'cancelled' | 'fulfilled' | 'refunded';
+export type FulfillmentPaymentStatus = 'not_started' | PaymentIntentStatus;
+export interface FulfillmentCommerceOrder {
+    id: string;
+    orderId: string;
+    clientId: string | null;
+    status: 'created' | 'packed' | 'label_pending' | 'label_created' | 'handed_over' | 'in_transit' | 'delivered' | 'exception' | 'cancelled';
+    providerKind: string | null;
+    providerTrackingId: string | null;
+    shippingAddress: {
+        addressId: string;
+        clientId: string;
+        label: string | null;
+        line1: string;
+        line2: string | null;
+        city: string;
+        postalCode: string;
+        country: string;
+    };
+    lines: {
+        id: string | null;
+        orderItemId: string;
+        skuId: string;
+        sku: string;
+        title: string | null;
+        quantity: number;
+        inventoryReservationIds: string[];
+        productSnapshot: Record<string, unknown>;
+    }[];
+    payment: {
+        paymentIntentId: string;
+        paymentStatus: FulfillmentPaymentStatus;
+        providerPaymentId: string | null;
+    };
+    inventory: {
+        status: 'not_checked' | 'reserved' | 'missing' | 'released' | 'expired' | 'consumed' | 'review_required';
+        reservationId: string | null;
+        reservationStatus: 'reserved' | 'consumed' | 'released' | 'expired' | null;
+        expiresAt: string | null;
+        locationId: string | null;
+        locationCode: string | null;
+    };
+    omsEligibility: {
+        allowed: boolean;
+        reason: 'order_not_paid' | 'payment_not_succeeded' | 'subscription_cycle_not_paid' | 'active_hold' | 'missing_shipping_address' | 'inventory_review' | 'risk_review' | null;
+    };
+    latestOperation: {
+        id: string;
+        type: 'created' | 'packed' | 'provider_attempt_recorded' | 'label_created' | 'handed_over' | 'tracking_event_recorded' | 'cancelled';
+        occurredAt: string;
+        actorUserId: string | null;
+        payload: Record<string, unknown>;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FulfillmentOrdersListRequest {
+    page: number;
+    pageSize: number;
+    status?: FulfillmentCommerceOrder['status'];
+}
+export interface FulfillmentOrderDetailRequest {
+    fulfillmentOrderId?: string;
+    orderId?: string;
+}
+export interface FulfillmentOrdersListResponse {
+    contractVersion: 'commerce.fulfillment.v0';
+    orders: FulfillmentCommerceOrder[];
+    totalCount: number;
+    page: number;
+    pageSize: number;
+}
+export interface FulfillmentOrderDetailResponse {
+    contractVersion: 'commerce.fulfillment.v0';
+    order: FulfillmentCommerceOrder;
+}
+/** Host-owned persisted projections. Payment statuses already come from the payments projection. */
+export interface FulfillmentCommerceReadPort {
+    listCommerceFulfillmentOrders(request: FulfillmentOrdersListRequest): Promise<FulfillmentOrdersListResponse | FulfillmentNativeUnsupported>;
+    getCommerceFulfillmentOrderDetail(request: FulfillmentOrderDetailRequest): Promise<FulfillmentOrderDetailResponse | null | FulfillmentNativeUnsupported>;
+}
+export interface FulfillmentShipmentsOverviewRequest {
+    shippedFilter: 'today' | '7d' | '30d' | 'all';
+}
+/** Bucket rows are opaque host data; native shipment counts cannot replace these buckets. */
+export interface FulfillmentShipmentsOverviewResponse {
+    approved: Record<string, unknown>[];
+    packing: Record<string, unknown>[];
+    shippedToday: number;
+    shipped: Record<string, unknown>[];
+}
+export interface FulfillmentShipmentsOverviewPort {
+    getShipmentsOverview(request: FulfillmentShipmentsOverviewRequest): Promise<FulfillmentShipmentsOverviewResponse | FulfillmentNativeUnsupported>;
+}
+/** Existing commerce eligibility remains host-owned; the read model only supplies its facts. */
+export interface FulfillmentCommerceReadPolicy {
+    evaluateCommerceFulfillmentEligibility(input: {
+        orderMode: 'one_time' | 'subscription_cycle';
+        orderStatus: FulfillmentOrderStatus;
+        paymentStatus: FulfillmentPaymentStatus;
+        subscriptionCycleStatus: SubscriptionCycleStatus | null;
+        activeHoldCount: number;
+        hasShippingAddress: boolean;
+        inventoryStatus: FulfillmentCommerceOrder['inventory']['status'];
+    }): FulfillmentCommerceOrder['omsEligibility'];
+}
+export type { FulfillmentProgressInput, FulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/contracts/read.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/readback.d.ts

@@ -0,0 +1,59 @@
+import type { FulfillmentObservation } from "./observation.js";
+import type { FulfillmentRefusal } from "./dispatch.js";
+export type FulfillmentReadbackResult = {
+    kind: "found";
+    externalRef: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    observation: FulfillmentObservation;
+} | {
+    kind: "absent";
+    scope: {
+        providerRef: string;
+        requestKey: string;
+        fulfillmentRef: string;
+        externalRef: string | null;
+    };
+    proof: {
+        kind: "authoritative_exact_lookup";
+        evidenceRef: `evidence:${string}`;
+        checkedAt: string;
+    };
+} | {
+    kind: "unknown";
+    refusal: FulfillmentRefusal;
+} | {
+    kind: "unsupported";
+    refusal: FulfillmentRefusal;
+};
+export interface FulfillmentReadbackPort {
+    /** Empty pages and missing local rows cannot certify external absence. */
+    read(input: {
+        providerRef: string;
+        requestKey: string;
+        fulfillmentRef: string;
+        externalRef: string | null;
+        mode: "command" | "parcel";
+    }): Promise<FulfillmentReadbackResult>;
+}
+/** Collection observation is separate from authoritative exact lookup. */
+export type FulfillmentReconciliationObservation = FulfillmentReadbackResult | {
+    kind: "unmapped";
+    externalRef: string | null;
+    evidence: Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics">;
+};
+export interface FulfillmentObservationPagePort {
+    readPage(input: {
+        page: number;
+        size: number;
+    }): Promise<{
+        kind: "page";
+        rows: readonly FulfillmentReconciliationObservation[];
+    } | {
+        kind: "page_exhausted";
+    } | {
+        kind: "failed";
+        refusal: FulfillmentRefusal;
+        error?: import("./dispatch.js").FulfillmentOperationError;
+    }>;
+}

package/dist/fulfillment/contracts/readback.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/replacement.d.ts

@@ -0,0 +1,34 @@
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export interface FulfillmentReplacementRequest {
+    idempotencyKey: string;
+    actorUserId: string;
+    orderId: string;
+    reason: 'damaged' | 'lost' | 'returned_undelivered' | 'other';
+    metadata?: Record<string, unknown>;
+}
+export interface FulfillmentReplacementResult {
+    contractVersion: 'commerce.v0';
+    operation: {
+        id: string;
+        orderId: string;
+        type: 'hold_created' | 'hold_released' | 'fulfillment_reviewed' | 'support_note' | 'shipping_address_updated' | 'order_marked_refunded' | 'order_cancelled_manual' | 'replacement_shipment_requested';
+        holdId: string | null;
+        actorUserId: string | null;
+        occurredAt: string;
+        payload: Record<string, unknown>;
+    };
+    replacement: {
+        fulfillmentOrderId: string;
+        orderId: string;
+        sequenceNo: number;
+        replacesFulfillmentOrderId: string;
+        reason: FulfillmentReplacementRequest['reason'];
+        status: string;
+    };
+    releasedHoldIds: string[];
+    replayed: boolean;
+}
+/** Host owns atomic paid/contact/current-parcel/hold/reservation checks and actor-bound fingerprint/replay receipts. No confirmation or dispatch operation exists here. */
+export interface FulfillmentReplacementPort {
+    requestReplacementShipment(request: FulfillmentReplacementRequest): Promise<FulfillmentReplacementResult | FulfillmentNativeUnsupported>;
+}

package/dist/fulfillment/contracts/replacement.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/store.d.ts

@@ -0,0 +1,89 @@
+import type { DispatchEvidence, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentRefusal } from "./dispatch.js";
+export interface DispatchRecord {
+    dispatchRef: string;
+    requestKey: string;
+    fulfillmentRef: string;
+    orderRef: string;
+    parcelRef: string | null;
+    externalRef: string | null;
+    mode: "shadow" | "stage" | "live";
+    status: "draft" | "submitting" | "created" | "uncertain" | "failed" | "cancel_requested" | "cancelled";
+    evidence: DispatchEvidence;
+    replayed: boolean;
+    acceptance?: Extract<FulfillmentDispatchResult, {
+        kind: "accepted";
+    }> | null;
+}
+export interface FulfillmentStorePort {
+    read(requestKey: string): Promise<DispatchRecord | null>;
+    readCandidate(fulfillmentRef: string): Promise<FulfillmentDispatchRequest | null>;
+    prepare(fulfillmentRef: string): Promise<{
+        disposition: "ready" | "withheld";
+        contactRevision: number | null;
+    }>;
+    /** Evidence comes from adapter prepare, before any external submission. */
+    claim(input: {
+        requestKey: string;
+        fulfillmentRef: string;
+        orderRef: string;
+        parcelRef: string | null;
+        mode: DispatchRecord["mode"];
+        evidence: DispatchEvidence;
+    }): Promise<{
+        kind: "claimed";
+        record: DispatchRecord;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    /** G14: idempotent mapped attempt; persist only prepared, sanitized evidence. */
+    recordProviderAttempt(attemptKey: string, fulfillmentRef: string, preparedEvidence: DispatchEvidence, mode: DispatchRecord["mode"], status: "recorded"): Promise<{
+        replayed: boolean;
+    }>;
+    /** Bind submission to the same prepared command fingerprint recorded by claim. */
+    begin(input: {
+        dispatchRef: string;
+        commandFingerprint: string;
+    }): Promise<{
+        kind: "begun";
+        record: DispatchRecord;
+        begun: boolean;
+        replayed: boolean;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    /** Accepted rescue retains externalRef as uncertain; only acknowledge closes the local acceptance atomically. */
+    finalize(input: {
+        dispatchRef: string;
+        result: FulfillmentDispatchResult;
+    }): Promise<DispatchRecord>;
+    acknowledge(input: {
+        dispatchRef: string;
+        acceptance: Extract<FulfillmentDispatchResult, {
+            kind: "accepted";
+        }>;
+    }): Promise<{
+        acknowledged: boolean;
+        replayed: boolean;
+        record: DispatchRecord;
+    }>;
+    markStaleSubmissionsUncertain(staleBefore: string): Promise<number>;
+}
+export interface FulfillmentPaidHandoffPort {
+    ensureObligation(input: {
+        requestKey: string;
+        orderRef: string;
+        paidFactRef: string;
+    }): Promise<{
+        fulfillmentRef: string;
+        replayed: boolean;
+    }>;
+    acknowledge(input: {
+        requestKey: string;
+        fulfillmentRef: string;
+    }): Promise<{
+        acknowledged: boolean;
+        replayed: boolean;
+    }>;
+}

package/dist/fulfillment/contracts/store.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/sync.d.ts

@@ -0,0 +1,226 @@
+import type { FulfillmentRefusal } from "./dispatch.js";
+/** Collection identity never masquerades as a monotonic provider revision. */
+interface SyncIdentity {
+    providerRef: string;
+    syncRunId: string;
+    collectedAt: string;
+    sourceRevision: string | null;
+    revisionSource: "provider" | "collection" | "unknown";
+}
+export interface StockSnapshot extends SyncIdentity {
+    skuRef: string;
+    quantityKind: "snapshot";
+    totalQuantity: number;
+    forSaleQuantity: number;
+    reservedOrUnavailableQuantity: number;
+}
+export interface StockMovement extends SyncIdentity {
+    skuRef: string;
+    quantityKind: "movement";
+    quantity: number;
+    occurredAt: string | null;
+    operationType: string | null;
+    documentRef: string | null;
+    lotRef: string | null;
+    expirationDate: string | null;
+}
+export interface SyncCursor {
+    status: "idle" | "running" | "succeeded" | "failed";
+    lastStockSyncedAt: string | null;
+    lastMovementOccurredAt: string | null;
+    /** Sanitized continuation only; no credentials, URLs or arbitrary provider payload. */
+    continuation: {
+        nextRef: string | null;
+        startLocalDate: string | null;
+        endLocalDate: string | null;
+    };
+    /** G15: successful sellable coverage gaps; legacy absent values read as []. */
+    coverageGapSkus?: readonly string[];
+    refusal: FulfillmentRefusal | null;
+    /** Per-entry bounded diagnostics and run evidence in the existing cursor JSON, never raw errors. */
+    syncRunId?: string;
+    counts?: {
+        checked: number;
+        updated: number;
+        movements: number;
+        rejected: number;
+        failures: number;
+        providerCalls: number;
+        readBacks: number;
+    };
+    items?: readonly {
+        kind?: "stock" | "movement";
+        itemIndex: number;
+        skuRef: string | null;
+        status: "recorded" | "failed" | "rejected";
+        reason?: string;
+        activeReserved?: number;
+        sellableNow?: number | null;
+        coverageGapQuantity?: number;
+    }[];
+    alerts?: readonly {
+        skuRef: string;
+        thresholdKind: Exclude<Threshold, "forecast">;
+        severity: "info" | "warning" | "critical";
+        providerForSaleQuantity: number;
+        localAvailableQuantity: number;
+        detectedAt: string;
+        activeReserved?: number;
+        coverageGapQuantity?: number;
+        gapHours?: number;
+        thresholdHours?: number;
+    }[];
+    staleSync?: {
+        gapHours: number;
+        thresholdHours: number;
+        detectedAt: string;
+    };
+    error?: {
+        reason: string;
+        providerError?: {
+            operation: "get_stock" | "get_stock_movements";
+            status: number | null;
+            code: string;
+            retryable: boolean;
+        };
+    } | null;
+}
+export interface LocalStock {
+    skuRef: string;
+    onHand: number;
+    reserved: number;
+    unavailable: number;
+    safetyStock: number;
+}
+type Threshold = "safety_stock" | "reservation_coverage" | "forecast" | "stale_sync";
+type Conflict = "unknown_sku" | "ean_conflict" | "kind_quantity_conflict";
+export interface FulfillmentStockSyncProvider {
+    /** Rejected rows carry only their input index and a closed reason, never an unsafe reference. */
+    getStock(): Promise<(StockSnapshot | {
+        kind: "rejected";
+        itemIndex: number;
+        reason: "invalid_sku_ref";
+    })[]>;
+    getStockMovements(input?: {
+        startLocalDate?: string;
+        endLocalDate?: string;
+        size?: number;
+    }): Promise<(StockMovement | {
+        kind: "rejected";
+        itemIndex: number;
+        reason: "invalid_sku_ref";
+    })[]>;
+}
+export interface FulfillmentStockSyncPort {
+    readCursor(): Promise<SyncCursor | null>;
+    /** G16: unaggregated lines at the worker clock; quantity retains the four local balances. */
+    readLocalInventoryStock(requestedAt: string): Promise<readonly {
+        skuRef: string;
+        quantity: Pick<LocalStock, "onHand" | "reserved" | "unavailable" | "safetyStock">;
+        fulfillable: boolean;
+        locationStatus: "active" | "inactive";
+        lotStatus: "available" | "quarantined" | "expired" | "recalled" | null;
+        expiresAt: string | null;
+    }[]>;
+    readSkuInventoryClasses(skus: string[]): Promise<Map<string, "sellable" | "packaging" | null>>;
+    readActiveReservations(skus: string[], requestedAt: string): Promise<Map<string, number>>;
+    recordCursor(input: SyncCursor): Promise<void>;
+    recordStockSnapshot(input: {
+        requestKey: string;
+        snapshot: StockSnapshot;
+        local: LocalStock;
+        mismatchKind: "none";
+        inventoryClass: "sellable" | "packaging" | null;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordProviderStockCurrent(input: {
+        requestKey: string;
+        snapshot: StockSnapshot;
+        inventoryClass: "sellable" | "packaging" | null;
+        lastSyncedAt: string;
+        staleAfter: string;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordMovement(input: {
+        requestKey: string;
+        movement: StockMovement;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordLowStockEvidence(input: {
+        requestKey: string;
+        skuRef: string;
+        thresholdKind: Exclude<Threshold, "forecast">;
+        severity: "info" | "warning" | "critical";
+        providerForSaleQuantity: number;
+        localAvailableQuantity: number;
+        syncRunId: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    resolveLowStockEvidence(input: {
+        skuRef: string;
+        activeThresholdKinds: Threshold[];
+        syncRunId: string;
+    }): Promise<{
+        resolved: number;
+    }>;
+}
+interface ProductPack {
+    ean: string;
+    quantity: number;
+}
+export interface FulfillmentProductSyncProvider {
+    /** null means skipped (no private push metadata), never a newly created local SKU. */
+    ensureProduct(sku: string): Promise<{
+        replayed: boolean;
+    } | null>;
+    getProductPacks(sku: string): Promise<ProductPack[]>;
+    addProductPack(sku: string, pack: ProductPack): Promise<void>;
+    listStockedSkus(): Promise<string[]>;
+}
+export interface FulfillmentProductSyncPort {
+    listLocalProductPacks(): Promise<{
+        sku: string;
+        packs: (ProductPack & {
+            kind: "unit" | "collective";
+        })[];
+    }[]>;
+    markPackSynced(input: {
+        sku: string;
+        ean: string;
+    }): Promise<void>;
+    upsertPulledPack(input: {
+        sku: string;
+        ean: string;
+        quantity: number;
+        kind: "unit" | "collective";
+    }): Promise<{
+        conflict: "none" | "local_locked_mismatch" | "ean_owned_by_other_sku" | "sku_not_found";
+        replayed: boolean;
+    }>;
+    recordReconciliationEvidence(input: {
+        requestKey: string;
+        sku: string;
+        ean: string | null;
+        conflictKind: Conflict;
+        providerQuantity: number;
+        identity: SyncIdentity;
+        refusal: FulfillmentRefusal | null;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    resolveReconciliationEvidence(input: {
+        sku: string;
+        activeConflictKinds: Conflict[];
+        syncRunId: string;
+    }): Promise<{
+        resolved: number;
+    }>;
+}
+export {};

package/dist/fulfillment/contracts/sync.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/currentFulfillmentParcel.d.ts

@@ -0,0 +1,2 @@
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "@openlup/core/fulfillment";
+export type { FulfillmentParcelRow, ParcelAttributedRow } from "@openlup/core/fulfillment";