@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/paidFulfillmentRecovery.js

@@ -0,0 +1,154 @@
+const COMMERCE_ORDER_PAID_EVENT_TYPE = "commerce.order.paid";
+export function collectPaidFulfillmentRecoveryCandidates(input) {
+    const minimumAgeSeconds = input.minimumAgeSeconds ?? 30 * 60;
+    const minimumAgeMs = minimumAgeSeconds * 1000;
+    const dispatchSubmissionStaleSeconds = input.dispatchSubmissionStaleSeconds ?? 5 * 60;
+    const fulfillmentByOrder = groupBy(input.fulfillmentOrders, (row) => row.order_id);
+    const dispatchRefsByFulfillment = groupBy(input.dispatchRefs ?? [], (row) => row.fulfillment_order_id);
+    const outboxByOrder = latestBy(input.orderPaidOutboxEvents.filter((row) => row.event_type === COMMERCE_ORDER_PAID_EVENT_TYPE), (row) => row.aggregate_id ?? "");
+    const candidates = [];
+    let checkedOrders = 0;
+    for (const order of input.orders) {
+        const status = clean(order.status);
+        if (!["paid", "fulfillment_pending"].includes(status))
+            continue;
+        const ageSeconds = secondsSince(order.updated_at ?? order.created_at ?? "", input.now);
+        if (ageSeconds * 1000 < minimumAgeMs)
+            continue;
+        checkedOrders += 1;
+        const outbox = outboxByOrder.get(order.id);
+        const fulfillments = fulfillmentByOrder.get(order.id) ?? [];
+        if (fulfillments.length === 0) {
+            candidates.push(candidateForMissingFulfillment(order, outbox, ageSeconds));
+            continue;
+        }
+        for (const fulfillment of fulfillments) {
+            const providerKind = clean(fulfillment.provider_kind);
+            if (providerKind !== input.providerRef)
+                continue;
+            const latestDispatchRef = latestBy(dispatchRefsByFulfillment.get(fulfillment.id) ?? [], (row) => row.fulfillment_order_id).get(fulfillment.id);
+            const decision = dispatchRecoveryDecision({
+                dispatchRef: latestDispatchRef,
+                fulfillmentCreatedAt: fulfillment.updated_at ?? fulfillment.created_at,
+                now: input.now,
+                missingRefGraceSeconds: minimumAgeSeconds,
+                staleSeconds: dispatchSubmissionStaleSeconds,
+            });
+            if (!decision)
+                continue;
+            candidates.push({
+                ...baseCandidate(order, outbox, ageSeconds),
+                fulfillmentOrderId: fulfillment.id,
+                providerKind: input.providerRef,
+                dispatchRefId: latestDispatchRef?.id ?? null,
+                dispatchStatus: clean(latestDispatchRef?.status) || null,
+                ...decision,
+            });
+        }
+    }
+    candidates.sort((a, b) => b.ageSeconds - a.ageSeconds || a.orderId.localeCompare(b.orderId));
+    return { checkedOrders, candidates };
+}
+function candidateForMissingFulfillment(order, outbox, ageSeconds) {
+    const outboxStatus = clean(outbox?.status);
+    const decision = !outbox
+        ? recoveryDecision("order_paid_outbox_missing", "inspect_missing_order_paid_outbox")
+        : outboxStatus === "discarded"
+            ? recoveryDecision("order_paid_outbox_discarded", "requeue_discarded_order_paid_outbox", "automatic_local_requeue_safe")
+            : outboxStatus === "processed"
+                ? recoveryDecision("order_paid_outbox_processed_without_fulfillment", "inspect_processed_without_effect")
+                : recoveryDecision("paid_order_without_fulfillment_order", "wait_for_outbox", "wait_for_existing_automation");
+    return { ...baseCandidate(order, outbox, ageSeconds), ...decision };
+}
+function baseCandidate(order, outbox, ageSeconds) {
+    return {
+        orderId: order.id,
+        orderStatus: clean(order.status),
+        orderMode: clean(order.mode) || null,
+        fulfillmentOrderId: null,
+        providerKind: null,
+        dispatchRefId: null,
+        dispatchStatus: null,
+        outboxEventId: outbox?.id ?? null,
+        outboxStatus: clean(outbox?.status) || null,
+        outboxAttempts: typeof outbox?.attempts === "number" ? outbox.attempts : null,
+        ageSeconds,
+    };
+}
+function dispatchRecoveryDecision(input) {
+    const { dispatchRef, now, staleSeconds } = input;
+    if (!dispatchRef) {
+        if (!isAtLeastAgeOrUnknown(input.fulfillmentCreatedAt, now, input.missingRefGraceSeconds))
+            return null;
+        return recoveryDecision("provider_fulfillment_without_dispatch_ref", "inspect_missing_dispatch_ref");
+    }
+    const status = clean(dispatchRef.status);
+    if (status === "draft") {
+        return recoveryDecision("provider_dispatch_in_progress", "monitor_dispatch", "wait_for_existing_automation");
+    }
+    if (status === "submitting") {
+        return isAtLeastAgeOrUnknown(dispatchRef.updated_at ?? dispatchRef.created_at, now, staleSeconds)
+            ? recoveryDecision("provider_dispatch_submission_stale", "inspect_stale_dispatch_submission")
+            : recoveryDecision("provider_dispatch_in_progress", "monitor_dispatch", "wait_for_existing_automation");
+    }
+    if (status === "uncertain") {
+        return recoveryDecision("provider_dispatch_outcome_uncertain", "inspect_uncertain_dispatch");
+    }
+    if (status === "failed") {
+        return recoveryDecision("provider_dispatch_failed", "inspect_failed_dispatch");
+    }
+    if (status === "created") {
+        return dispatchRef.provider_order_id?.trim()
+            ? null
+            : recoveryDecision("provider_dispatch_created_without_provider_order_id", "inspect_created_dispatch_without_provider_order_id");
+    }
+    if (["cancel_requested", "cancelled"].includes(status)) {
+        return recoveryDecision("provider_dispatch_terminal_without_progress", "inspect_terminal_dispatch");
+    }
+    return recoveryDecision("provider_dispatch_status_unknown", "inspect_unknown_dispatch_status");
+}
+function recoveryDecision(reason, recommendedAction, recoveryPosture = "operator_review_required") {
+    return { reason, recommendedAction, recoveryPosture };
+}
+function latestBy(rows, key) {
+    const result = new Map();
+    for (const row of rows) {
+        const rowKey = key(row);
+        if (!rowKey)
+            continue;
+        const current = result.get(rowKey);
+        if (!current || timestamp(row.updated_at ?? row.created_at) >= timestamp(current.updated_at ?? current.created_at)) {
+            result.set(rowKey, row);
+        }
+    }
+    return result;
+}
+function groupBy(rows, key) {
+    const groups = new Map();
+    for (const row of rows) {
+        const rowKey = key(row);
+        const group = groups.get(rowKey);
+        if (group)
+            group.push(row);
+        else
+            groups.set(rowKey, [row]);
+    }
+    return groups;
+}
+function clean(value) {
+    return value?.trim().toLowerCase() ?? "";
+}
+function timestamp(value) {
+    const parsed = value ? Date.parse(value) : 0;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function secondsSince(value, now) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return 0;
+    return Math.max(0, Math.floor((now.getTime() - parsed) / 1000));
+}
+function isAtLeastAgeOrUnknown(value, now, seconds) {
+    const parsed = timestamp(value);
+    return parsed <= 0 || now.getTime() - parsed > seconds * 1000;
+}

package/dist/fulfillment/paidHandoff.d.ts

@@ -0,0 +1,27 @@
+import type { OutboxHandler } from "@openlup/core/outbox";
+import type { OrderPaidFulfillmentPort } from "./paidHandoffPorts.js";
+interface OrderPaidRiskAssessmentPort {
+    assessPaidOrder(input: {
+        orderUuid: string;
+        outboxEventId: string;
+        signal: AbortSignal;
+    }): Promise<{
+        kind: "allow";
+        detail?: Record<string, unknown>;
+    } | {
+        kind: "review" | "block";
+        detail?: Record<string, unknown>;
+    } | {
+        kind: "retryable";
+        reason: string;
+    } | {
+        kind: "fatal";
+        reason: string;
+    }>;
+}
+export declare function createOutboxOrderPaidFulfillmentHandler(deps: {
+    fulfillmentPort: OrderPaidFulfillmentPort;
+    riskPort?: OrderPaidRiskAssessmentPort;
+    isRiskEnabled?: () => boolean;
+}): OutboxHandler<AbortSignal>;
+export {};

package/dist/fulfillment/paidHandoff.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+const COMMERCE_ORDER_PAID_EVENT_TYPE = "commerce.order.paid";
+const HANDLER_TIMEOUT_MS = 15_000;
+const outboxOrderPaidFulfillmentDescriptor = Object.freeze({
+    eventType: COMMERCE_ORDER_PAID_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+// Frozen minimal parse: validate only the orderUuid forwarded to the fulfillment
+// port. This handler owns the subset schema so a producer-side payload change
+// does not send otherwise valid in-flight events to the dead-letter queue.
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+})
+    .passthrough();
+export function createOutboxOrderPaidFulfillmentHandler(deps) {
+    return {
+        ...outboxOrderPaidFulfillmentDescriptor,
+        async handle(row, signal) {
+            const parsed = parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            // Risk gate (flag-OFF by default): assess the paid order before any
+            // fulfillment work. review/block → hold (ack without dispatch, the case is
+            // persisted for manual review); retryable/fatal map to the worker ladder.
+            if (deps.riskPort && deps.isRiskEnabled?.()) {
+                const risk = await deps.riskPort.assessPaidOrder({
+                    orderUuid: parsed.data.orderUuid,
+                    outboxEventId: row.id,
+                    signal,
+                });
+                switch (risk.kind) {
+                    case "allow":
+                        break;
+                    case "review":
+                    case "block":
+                        return {
+                            kind: "processed",
+                            detail: { skipped: "risk_review_hold", risk: risk.detail ?? {} },
+                        };
+                    case "retryable":
+                        return { kind: "retry", reason: truncateReason(risk.reason) };
+                    case "fatal":
+                        return { kind: "discard", reason: truncateReason(risk.reason) };
+                }
+            }
+            const result = await deps.fulfillmentPort.ensureFulfilledFromPaidOrder({
+                orderUuid: parsed.data.orderUuid,
+                outboxEventId: row.id,
+                signal,
+            });
+            switch (result.kind) {
+                case "completed":
+                case "skipped":
+                    return { kind: "processed", detail: result.detail };
+                case "manual_review":
+                    // Terminal but NOT a silent discard: the port already placed the
+                    // durable observable signal (an active fulfillment_exception hold).
+                    // Settle the event as processed so it is not parked in the discard/
+                    // error queue, and record why in the outbox metadata.
+                    return {
+                        kind: "processed",
+                        detail: {
+                            ...result.detail,
+                            outcome: "manual_review",
+                            reason: truncateReason(result.reason),
+                        },
+                    };
+                case "retryable":
+                    return { kind: "retry", reason: truncateReason(result.reason) };
+                case "snooze":
+                    return { kind: "snooze", reason: truncateReason(result.reason) };
+                case "fatal":
+                    return { kind: "discard", reason: truncateReason(result.reason) };
+            }
+        },
+    };
+}
+function truncateReason(value) { return value.length <= 300 ? value : `${value.slice(0, 300)}…`; }
+function parseOutboxPayload(schema, payload) {
+    const parsed = schema.safeParse(payload);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const detail = parsed.error.issues.map(issue => `${issue.path.join(".") || "payload"}: ${issue.message}`).join("; ");
+    return { ok: false, outcome: { kind: "discard", reason: `contract_parse_failed: ${truncateReason(detail)}` } };
+}

package/dist/fulfillment/paidHandoffPorts.d.ts

@@ -0,0 +1,24 @@
+export type OrderPaidFulfillmentResult = {
+    kind: "completed" | "skipped";
+    detail?: Record<string, unknown>;
+} | {
+    kind: "retryable";
+    reason: string;
+} | {
+    kind: "snooze";
+    reason: string;
+} | {
+    kind: "fatal";
+    reason: string;
+} | {
+    kind: "manual_review";
+    reason: string;
+    detail?: Record<string, unknown>;
+};
+export interface OrderPaidFulfillmentPort {
+    ensureFulfilledFromPaidOrder(input: {
+        orderUuid: string;
+        outboxEventId: string;
+        signal: AbortSignal;
+    }): Promise<OrderPaidFulfillmentResult>;
+}

package/dist/fulfillment/paidHandoffPorts.js

@@ -0,0 +1,3 @@
+// Neutral port owned by the commerce.order.paid dispatch handler. Concrete
+// persistence and provider adapters belong to the host composition.
+export {};

package/dist/fulfillment/postgresDeliveryAlignment.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import { type PgExecutor } from './postgresDispatchStore.js';
+/** Trusted arrival ingestion only. Operator replacement attestation has no caller here. */
+export declare function createPostgresDeliveryAlignmentPort(db: PgExecutor): DeliveryAlignmentPort;

package/dist/fulfillment/postgresDeliveryAlignment.js

@@ -0,0 +1,12 @@
+import { nativeCall } from './postgresDispatchStore.js';
+import { readDeliveryAlignment } from './deliveryAlignmentReadModel.js';
+/** Trusted arrival ingestion only. Operator replacement attestation has no caller here. */
+export function createPostgresDeliveryAlignmentPort(db) {
+    return {
+        read: ref => readDeliveryAlignment(db, ref),
+        async recordArrival(v) {
+            const receipt = await nativeCall(db, 'fulfillment_record_alignment_arrival', [v.requestKey, v.parcelRef, v.deliveredAt, v.evidenceRef]);
+            return { ...await readDeliveryAlignment(db, v.parcelRef), replayed: receipt.replayed };
+        },
+    };
+}

package/dist/fulfillment/postgresDispatchStore.d.ts

@@ -0,0 +1,16 @@
+import type { FulfillmentDispatchRequest, FulfillmentStorePort } from './contracts/index.js';
+import type { createFulfillmentCommandLedger } from './providerCommandLedger.js';
+/** Caller supplies a driver and its selected host preparation/data boundary. */
+export interface PgExecutor {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+export declare function nativeCall<T>(db: PgExecutor, name: string, values: unknown[]): Promise<T>;
+export declare function createPostgresFulfillmentDispatchStore(db: PgExecutor, host: {
+    /** Synchronize authoritative withholding/contact revision on prepare and every source edit. */
+    prepare(fulfillmentRef: string): ReturnType<FulfillmentStorePort['prepare']>;
+    readCandidate(fulfillmentRef: string): Promise<FulfillmentDispatchRequest | null>;
+}): FulfillmentStorePort & {
+    commandLedger: ReturnType<typeof createFulfillmentCommandLedger>;
+};

package/dist/fulfillment/postgresDispatchStore.js

@@ -0,0 +1,44 @@
+import { dispatchEvidence, dispatchResult } from './dispatchProjection.js';
+export async function nativeCall(db, name, values) {
+    const result = await db.query(`SELECT public.${name}(${values.map((_, index) => `$${index + 1}`).join(',')}) AS response`, values);
+    if (!result.rows[0] || result.rows[0].response === undefined)
+        throw new Error('fulfillment_native_response_missing');
+    return result.rows[0].response;
+}
+export function createPostgresFulfillmentDispatchStore(db, host) {
+    return {
+        readCandidate: ref => host.readCandidate(ref),
+        prepare: ref => host.prepare(ref),
+        async read(key) {
+            const result = await db.query('SELECT public.fulfillment_dispatch_read(ref) AS response FROM public.fulfillment_dispatch_refs ref WHERE request_key=$1', [key]);
+            return result.rows[0]?.response ?? null;
+        },
+        claim: input => nativeCall(db, 'fulfillment_dispatch_claim', [input.requestKey, input.fulfillmentRef, input.orderRef, input.parcelRef, input.mode, JSON.stringify(dispatchEvidence(input.evidence))]),
+        recordProviderAttempt: (key, ref, evidence, mode) => nativeCall(db, 'fulfillment_record_provider_attempt', [key, ref, JSON.stringify(dispatchEvidence(evidence)), mode]),
+        begin: input => nativeCall(db, 'fulfillment_dispatch_begin', [input.dispatchRef, input.commandFingerprint]),
+        finalize: input => nativeCall(db, 'fulfillment_dispatch_finish', [input.dispatchRef, JSON.stringify(dispatchResult(input.result)), false]),
+        acknowledge: input => nativeCall(db, 'fulfillment_dispatch_finish', [input.dispatchRef, JSON.stringify(dispatchResult(input.acceptance)), true]),
+        async markStaleSubmissionsUncertain(staleBefore) {
+            const result = await db.query("UPDATE public.fulfillment_dispatch_refs SET status='uncertain',updated_at=now() WHERE status='submitting' AND updated_at<$1 RETURNING id", [staleBefore]);
+            return result.rows.length;
+        },
+        commandLedger: commandLedger(db),
+    };
+}
+function commandLedger(db) {
+    const fence = (v) => [v.commandId, v.claimToken, v.claimGeneration, v.expectedVersion];
+    return {
+        enqueue: v => nativeCall(db, 'commerce_fulfillment_enqueue_provider_command', [v.fulfillmentRef, v.providerRef, v.commandKind, v.contractVersion, v.idempotencyKey, v.commandKeyFingerprint, v.commandPayloadFingerprint, v.providerIdempotencyKeyFingerprint, v.routingFingerprint, v.configurationFingerprint, v.correlationKeyFingerprint, v.retryBudget]),
+        async claim(v) {
+            const result = await db.query('SELECT public.commerce_fulfillment_claim_provider_commands($1,$2,$3,$4,$5) AS response', [v.providerRef, v.commandKind, v.limit, v.claimOwnerFingerprint, v.leaseSeconds]);
+            return result.rows.map(row => row.response);
+        },
+        markSubmitting: v => nativeCall(db, 'commerce_fulfillment_mark_command_submitting', [...fence(v), v.providerAttemptRef]),
+        applyWriteOutcome: v => nativeCall(db, 'commerce_fulfillment_apply_command_write_outcome', [...fence(v), v.identityFingerprint, v.kind, v.reason, v.kind === 'rejected' ? v.retryNotBefore : null, v.kind === 'accepted' ? v.providerReferenceFingerprint : null, v.providerAttemptRef, v.kind === 'rejected' ? v.proof.kind : null, v.kind === 'rejected' ? v.proof.fingerprint : null, v.kind === 'rejected' ? v.proof.observedAt : null, v.kind === 'rejected' ? v.proof.source : null]),
+        confirm: v => nativeCall(db, 'commerce_fulfillment_confirm_provider_command', [...fence(v), v.identityFingerprint, v.providerAttemptRef, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source]),
+        reconcile: v => nativeCall(db, 'commerce_fulfillment_reconcile_provider_command', [v.commandId, v.expectedVersion, v.identityFingerprint, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source]),
+        resolve: v => nativeCall(db, 'commerce_fulfillment_resolve_uncertain_command', [v.commandId, v.expectedVersion, v.identityFingerprint, v.decision, v.reason, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source, v.decision === 'retry_wait' ? v.retryNotBefore : null]),
+        release: v => nativeCall(db, 'commerce_fulfillment_release_or_cancel_command', [...fence(v), v.action, v.reason]),
+        recoverExpired: v => nativeCall(db, 'commerce_fulfillment_recover_expired_provider_commands', [v.limit]),
+    };
+}

package/dist/fulfillment/postgresEvidenceReadPort.d.ts

@@ -0,0 +1,25 @@
+import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
+interface AdminLowStockEvidenceItem {
+    id: string;
+    sku: string;
+    thresholdKind: string;
+    severity: string;
+    status: string;
+    providerForSaleQuantity: number | null;
+    localAvailableQuantity: number | null;
+    forecastDays: null;
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+    resolvedAt: string | null;
+}
+interface FulfillmentLowStockEvidencePort {
+    getLowStockEvidence(input: {
+        statusFilter: 'all' | 'open' | 'resolved';
+    }): Promise<{
+        statusFilter: string;
+        openCount: number;
+        items: AdminLowStockEvidenceItem[];
+    }>;
+}
+export declare function createPostgresFulfillmentLowStockEvidencePort(executor: PgQueryExecutor, sourceKey: string): FulfillmentLowStockEvidencePort;
+export {};

package/dist/fulfillment/postgresEvidenceReadPort.js

@@ -0,0 +1,45 @@
+const READ = `SELECT id, sku, threshold_kind, severity, status,
+    provider_for_sale_quantity, local_available_quantity,
+    first_seen_at, last_seen_at, resolved_at
+  FROM public.fulfillment_stock_evidence
+  WHERE source_key = $1::text AND ($2::text = 'all' OR status = $2::text)
+  ORDER BY last_seen_at DESC, id ASC`;
+const COUNT = `SELECT count(*)::integer AS count
+  FROM public.fulfillment_stock_evidence
+  WHERE source_key = $1::text AND status = 'open'`;
+export function createPostgresFulfillmentLowStockEvidencePort(executor, sourceKey) {
+    const key = sourceKey.trim();
+    if (!key)
+        throw new Error("fulfillment_stock_source_key_required");
+    return { async getLowStockEvidence({ statusFilter }) {
+            const [rows, count] = await Promise.all([
+                executor.query(READ, [key, statusFilter]),
+                executor.query(COUNT, [key]),
+            ]);
+            return {
+                statusFilter,
+                openCount: integer(count.rows[0]?.count),
+                items: rows.rows.map(mapItem),
+            };
+        } };
+}
+function mapItem(row) {
+    return {
+        id: String(row.id),
+        sku: String(row.sku),
+        thresholdKind: row.threshold_kind,
+        severity: row.severity,
+        status: row.status,
+        providerForSaleQuantity: nullableInteger(row.provider_for_sale_quantity),
+        localAvailableQuantity: nullableInteger(row.local_available_quantity),
+        forecastDays: null,
+        firstSeenAt: nullableText(row.first_seen_at),
+        lastSeenAt: nullableText(row.last_seen_at),
+        resolvedAt: nullableText(row.resolved_at),
+    };
+}
+function integer(value) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+function nullableInteger(value) { return value === null ? null : integer(value); }
+function nullableText(value) { return value instanceof Date ? value.toISOString() : typeof value === "string" && value ? value : null; }

package/dist/fulfillment/postgresPaidFulfillmentRecovery.d.ts

@@ -0,0 +1,25 @@
+import type { collectPaidFulfillmentRecoveryCandidates } from './paidFulfillmentRecovery.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+type RecoveryInput = Parameters<typeof collectPaidFulfillmentRecoveryCandidates>[0];
+/** Read the selected native port's local obligations; never infer external absence. */
+export declare function createPostgresPaidFulfillmentRecoveryOpsPort(db: PgExecutor, selection: {
+    portKey: string;
+    providerRef: string;
+}): {
+    readRecoveryInputs(input: {
+        minimumAgeSeconds: number;
+        limit: number;
+        now: Date;
+        orderIds?: string[];
+    }): Promise<Pick<RecoveryInput, "orders" | "fulfillmentOrders" | "dispatchRefs" | "orderPaidOutboxEvents">>;
+    requeueDiscardedOrderPaidOutboxEvents(input: {
+        eventIds: string[];
+        limit?: number;
+        requeuedBy: string;
+        reason: string;
+    }): Promise<{
+        requeuedCount: number;
+        eventIds: string[];
+    }>;
+};
+export {};

package/dist/fulfillment/postgresPaidFulfillmentRecovery.js

@@ -0,0 +1,26 @@
+/** Read the selected native port's local obligations; never infer external absence. */
+export function createPostgresPaidFulfillmentRecoveryOpsPort(db, selection) {
+    return {
+        async readRecoveryInputs(input) {
+            const ids = [...new Set(input.orderIds ?? [])];
+            const orders = (await db.query(`SELECT id,status,metadata->>'mode' AS mode,created_at::text,updated_at::text FROM public.commerce_orders
+        WHERE status=ANY($1::text[]) AND updated_at<=$2 AND ($4::uuid[]='{}'::uuid[] OR id=ANY($4::uuid[])) ORDER BY updated_at ASC LIMIT $3`, [['paid', 'fulfillment_pending'], new Date(input.now.getTime() - input.minimumAgeSeconds * 1000), input.limit, ids])).rows;
+            const orderIds = orders.map(row => row.id);
+            if (!orderIds.length)
+                return { orders: [], fulfillmentOrders: [], dispatchRefs: [], orderPaidOutboxEvents: [] };
+            const [shipments, refs, events] = await Promise.all([
+                db.query('SELECT id,order_id,$3::text AS provider_kind,status,created_at::text,updated_at::text FROM public.fulfillment_shipments WHERE order_id=ANY($1::uuid[]) AND port_key=$2 ORDER BY created_at DESC', [orderIds, selection.portKey, selection.providerRef]),
+                db.query('SELECT ref.id,ref.shipment_id AS fulfillment_order_id,ref.external_ref AS provider_order_id,ref.status,ref.updated_at::text FROM public.fulfillment_dispatch_refs ref JOIN public.fulfillment_shipments shipment ON shipment.id=ref.shipment_id WHERE ref.order_id=ANY($1::uuid[]) AND shipment.port_key=$2', [orderIds, selection.portKey]),
+                db.query("SELECT id,event_type,status,aggregate_id,created_at::text,available_at::text,attempts,metadata->>'updatedAt' AS updated_at FROM public.outbox_events WHERE event_type=$1 AND aggregate_id=ANY($2::uuid[]) ORDER BY created_at DESC", ['commerce.order.paid', orderIds]),
+            ]);
+            return { orders, fulfillmentOrders: shipments.rows, dispatchRefs: refs.rows, orderPaidOutboxEvents: events.rows };
+        },
+        async requeueDiscardedOrderPaidOutboxEvents(input) {
+            const ids = [...new Set(input.eventIds.filter(Boolean))];
+            if (!ids.length)
+                return { requeuedCount: 0, eventIds: [] };
+            const result = await db.query('SELECT id FROM public.outbox_requeue_discarded(p_event_ids=>$1::uuid[],p_event_type=>$2,p_limit=>$3,p_requeued_by=>$4,p_reason=>$5)', [ids, 'commerce.order.paid', input.limit ?? ids.length, input.requeuedBy, input.reason]);
+            return { requeuedCount: result.rows.length, eventIds: result.rows.map(row => String(row.id)) };
+        },
+    };
+}

package/dist/fulfillment/postgresPaidHandoffStore.d.ts

@@ -0,0 +1,4 @@
+import type { FulfillmentPaidHandoffPort } from './contracts/index.js';
+import { type PgExecutor } from './postgresDispatchStore.js';
+/** Select an existing native port explicitly; never route by a private provider default. */
+export declare function createPostgresPaidFulfillmentHandoffStore(db: PgExecutor, portKey: string): FulfillmentPaidHandoffPort;

package/dist/fulfillment/postgresPaidHandoffStore.js

@@ -0,0 +1,10 @@
+import { nativeCall } from './postgresDispatchStore.js';
+/** Select an existing native port explicitly; never route by a private provider default. */
+export function createPostgresPaidFulfillmentHandoffStore(db, portKey) {
+    if (!portKey.trim())
+        throw new Error('fulfillment_port_key_required');
+    return {
+        ensureObligation: v => nativeCall(db, 'fulfillment_ensure_paid_handoff', [v.requestKey, v.orderRef, v.paidFactRef, portKey]),
+        acknowledge: v => nativeCall(db, 'fulfillment_ack_paid_handoff', [v.requestKey, v.fulfillmentRef]),
+    };
+}

package/dist/fulfillment/postgresShipmentSpine.d.ts

@@ -0,0 +1,63 @@
+import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
+interface ShipmentSpineResult {
+    shipmentId: string;
+    orderId: string;
+    status: string;
+    replayed: boolean;
+}
+interface ShipmentRequest {
+    idempotencyKey: string;
+    shipmentId: string;
+    metadata?: Record<string, unknown>;
+    requestedAt?: string;
+    externalRef?: string;
+}
+interface ShipmentSpineMutationPort {
+    createShipment(input: {
+        idempotencyKey: string;
+        orderId: string;
+        metadata?: Record<string, unknown>;
+        requestedAt?: string;
+    }): Promise<ShipmentSpineResult>;
+    recordLabel(input: ShipmentRequest): Promise<ShipmentSpineResult>;
+    handOff(input: ShipmentRequest): Promise<ShipmentSpineResult>;
+    recordTracking(input: ShipmentRequest & {
+        status: 'in_transit' | 'delivered';
+    }): Promise<ShipmentSpineResult>;
+    cancel(input: ShipmentRequest & {
+        reason: string;
+    }): Promise<ShipmentSpineResult>;
+    raiseException(input: ShipmentRequest & {
+        reason: string;
+    }): Promise<ShipmentSpineResult>;
+}
+export interface PostgresFulfillmentShipmentSpineOptions {
+    portKey: string;
+    evidenceChannel?: "poll" | "push";
+    requiredProviderType?: "simulator";
+}
+/** Direct node-postgres adapter for the provider-neutral public shipment rail. */
+export declare function createPostgresFulfillmentShipmentSpinePort(executor: PgQueryExecutor, options: PostgresFulfillmentShipmentSpineOptions): ShipmentSpineMutationPort & {
+    localPersistence: ReturnType<typeof localPersistence>;
+};
+/** G17 native local persistence, composed on the same injected executor. */
+declare function localPersistence(executor: PgQueryExecutor): {
+    readLocalFulfillmentState(ref: string): Promise<{
+        status: string | null;
+        latestStatusOccurredAt: string | null;
+        handedOverAt: string | null;
+    }>;
+    recordObservation(observation: import("./contracts/index.js").FulfillmentObservation): Promise<{
+        replayed: boolean;
+    }>;
+    recordStatusEvidence(ref: {
+        fulfillmentRef: string;
+    }, observation: import("./contracts/index.js").FulfillmentObservation): Promise<{
+        replayed: boolean;
+    }>;
+    markProcessed(eventKey: string, outcome: {
+        status: "processed" | "ignored";
+        refusal?: import("./contracts/index.js").FulfillmentRefusal;
+    }): Promise<void>;
+};
+export {};