@openlup/platform 0.20.0 → 0.22.0

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

@@ -0,0 +1,170 @@
+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;
+}
+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 {
+    getStock(): Promise<StockSnapshot[]>;
+    getStockMovements(input?: {
+        startLocalDate?: string;
+        endLocalDate?: string;
+        size?: number;
+    }): Promise<StockMovement[]>;
+}
+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";

package/dist/fulfillment/currentFulfillmentParcel.js

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

package/dist/fulfillment/delayReadModel.d.ts

@@ -0,0 +1,11 @@
+import type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+export type DeliveryAlignmentRow = Record<string, unknown>;
+export type DeliveryAlignmentRowsReader = FulfillmentCustomerAlignmentRowsReader;
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export declare function readFulfillmentDelay(readRows: DeliveryAlignmentRowsReader | undefined, nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Promise<Map<string, CustomerDeliveryAlignment> | FulfillmentNativeUnsupported>;
+export declare function mapCurrentDeliveryAlignments(rows: DeliveryAlignmentRow[], nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Map<string, CustomerDeliveryAlignment>;

package/dist/fulfillment/delayReadModel.js

@@ -0,0 +1,45 @@
+import { isNativeUnsupported } from './handlerSupport.js';
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export async function readFulfillmentDelay(readRows, nextCycleAtBySubscription) {
+    const subscriptionIds = [...nextCycleAtBySubscription.keys()].filter(Boolean);
+    if (!readRows || subscriptionIds.length === 0)
+        return new Map();
+    const rows = await readRows(subscriptionIds);
+    if (isNativeUnsupported(rows))
+        return rows;
+    return mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription);
+}
+export function mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription) {
+    const result = new Map();
+    for (const row of rows) {
+        const subscriptionId = text(row.subscription_id);
+        if (!subscriptionId || result.has(subscriptionId))
+            continue;
+        const state = text(row.state);
+        if (state === "protected") {
+            result.set(subscriptionId, { state });
+            continue;
+        }
+        if (state === "aligned" && sameInstant(nullableText(row.aligned_next_cycle_at), nextCycleAtBySubscription.get(subscriptionId) ?? null)) {
+            result.set(subscriptionId, { state });
+        }
+    }
+    return result;
+}
+function sameInstant(left, right) {
+    if (!left || !right)
+        return false;
+    const leftTime = new Date(left).getTime();
+    const rightTime = new Date(right).getTime();
+    return Number.isFinite(leftTime) && leftTime === rightTime;
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function nullableText(value) {
+    return typeof value === "string" && value ? value : null;
+}

package/dist/fulfillment/deliveryAlignmentReadModel.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+/** Server-authorized projection; database browser roles have no direct access. */
+export declare function readDeliveryAlignment(db: PgExecutor, fulfillmentRef: string): ReturnType<DeliveryAlignmentPort['read']>;

package/dist/fulfillment/deliveryAlignmentReadModel.js

@@ -0,0 +1,12 @@
+/** Server-authorized projection; database browser roles have no direct access. */
+export async function readDeliveryAlignment(db, fulfillmentRef) {
+    const result = await db.query(`SELECT alignment.state, alignment.aligned_next_cycle_at
+    FROM public.fulfillment_shipments shipment
+    LEFT JOIN public.subscription_delivery_alignment_cases alignment ON alignment.predecessor_order_id=shipment.order_id
+    WHERE shipment.id=$1::uuid
+    ORDER BY (alignment.state IN ('protected','manual_review')) DESC, alignment.created_at ASC LIMIT 1`, [fulfillmentRef]);
+    const row = result.rows[0];
+    const date = row?.aligned_next_cycle_at;
+    return { disposition: row?.state === 'aligned' ? 'aligned' : row?.state === 'protected' ? 'outstanding' : 'manual_review',
+        nextCycleAt: date instanceof Date ? date.toISOString() : typeof date === 'string' ? date : null };
+}

package/dist/fulfillment/dispatchProjection.d.ts

@@ -0,0 +1,7 @@
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchResult } from "./contracts/index.js";
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export declare function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence;
+export declare function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult;
+export declare function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & {
+    externalRef: string;
+};

package/dist/fulfillment/dispatchProjection.js

@@ -0,0 +1,18 @@
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export function dispatchEvidence(evidence) {
+    return {
+        commandFingerprint: evidence.commandFingerprint,
+        contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source: evidence.contactRevision.source, revision: evidence.contactRevision.revision },
+        providerRef: evidence.providerRef, carrierRef: evidence.carrierRef, serviceRef: evidence.serviceRef,
+    };
+}
+export function dispatchResult(result) {
+    switch (result.kind) {
+        case "accepted": return { kind: "accepted", externalRef: result.externalRef, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, evidence: dispatchEvidence(result.evidence) };
+        case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+        case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+    }
+}
+export function acceptedProviderProof(record) {
+    return Boolean(record?.externalRef && (record.status === "created" || record.status === "uncertain"));
+}

package/dist/fulfillment/fulfillmentObservationEffects.d.ts

@@ -0,0 +1,66 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+/** Ledger effects for an already accepted observation; acceptance and retry belong to the caller. */
+interface FulfillmentObservationPort<TrackingStatus> {
+    markProviderStockConsumed(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    markHandedOver(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+        suppressDispatched: boolean;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    recordTrackingReference(input: {
+        idempotencyKey: string;
+        orderId: string;
+        fulfillmentOrderId: string;
+        trackingNumber: string;
+        trackingUrl: string | null;
+        carrierKind: string | null;
+        service: string | null;
+        status: TrackingStatus;
+        observation: FulfillmentObservation;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+}
+interface FulfillmentObservationTrackingReference {
+    trackingNumber: string;
+    trackingUrl?: string | null;
+    carrierKind?: string | null;
+    service?: string | null;
+}
+interface FulfillmentObservationInput<LocalStatus, TrackingStatus> {
+    port: FulfillmentObservationPort<TrackingStatus>;
+    localStatus: LocalStatus;
+    ids: {
+        orderId: string;
+        fulfillmentOrderId: string;
+    };
+    observation: FulfillmentObservation;
+    trackingRefs: readonly FulfillmentObservationTrackingReference[];
+    stockIdempotencyKey: string;
+    handoffIdempotencyKey: string;
+    trackingIdempotencyKey: (trackingNumber: string) => string;
+    issueAccountingInvoice?: () => Promise<void>;
+    onReplayed?: () => void;
+    onTrackingRecorded?: (result: {
+        replayed: boolean;
+        readBack: boolean;
+    }) => void;
+}
+/** Pure status decisions/projection; the mechanism owns every effect and await. */
+interface FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus> {
+    consumesStock(status: LocalStatus): boolean;
+    handsOver(status: LocalStatus): boolean;
+    suppressDispatched(status: LocalStatus): boolean;
+    trackingStatus(status: LocalStatus): TrackingStatus;
+}
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export declare function applyFulfillmentObservationEffects<LocalStatus, TrackingStatus>(input: FulfillmentObservationInput<LocalStatus, TrackingStatus>, policy: FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus>): Promise<void>;
+export {};

package/dist/fulfillment/fulfillmentObservationEffects.js

@@ -0,0 +1,36 @@
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export async function applyFulfillmentObservationEffects(input, policy) {
+    const { fulfillmentOrderId, orderId } = input.ids;
+    if (policy.consumesStock(input.localStatus)) {
+        const consumed = await input.port.markProviderStockConsumed({
+            idempotencyKey: input.stockIdempotencyKey,
+            fulfillmentOrderId,
+        });
+        if (consumed.replayed)
+            input.onReplayed?.();
+    }
+    if (!policy.handsOver(input.localStatus))
+        return;
+    const handoff = await input.port.markHandedOver({
+        idempotencyKey: input.handoffIdempotencyKey,
+        fulfillmentOrderId,
+        suppressDispatched: policy.suppressDispatched(input.localStatus),
+    });
+    if (handoff.replayed)
+        input.onReplayed?.();
+    for (const trackingRef of input.trackingRefs) {
+        const tracking = await input.port.recordTrackingReference({
+            idempotencyKey: input.trackingIdempotencyKey(trackingRef.trackingNumber),
+            orderId,
+            fulfillmentOrderId,
+            trackingNumber: trackingRef.trackingNumber,
+            trackingUrl: trackingRef.trackingUrl ?? null,
+            carrierKind: trackingRef.carrierKind ?? null,
+            service: trackingRef.service ?? null,
+            status: policy.trackingStatus(input.localStatus),
+            observation: input.observation,
+        });
+        input.onTrackingRecorded?.(tracking);
+    }
+    await input.issueAccountingInvoice?.();
+}