@openlup/platform 0.22.0 → 0.24.0

package/dist/invoicing/contracts/settlement.d.ts

@@ -0,0 +1,66 @@
+import type { InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** One immutable balance item, never unique by batch+payment alone.
+ * Carrier: accountingControlContracts settlement + payout balance transaction ID.
+ * Null links and bankReceivedAt are facts; settlement is not an invoice gate.
+ * @consumer Host payout item recorder.
+ */
+export interface InvoiceSettlementItem {
+    readonly requestKey: string;
+    readonly providerRef: string;
+    readonly batchRef: string;
+    readonly itemRef: string;
+    readonly providerPaymentRef: string;
+    readonly paymentIntentRef: string | null;
+    readonly paymentRef: string | null;
+    readonly invoiceRef: string | null;
+    readonly grossMinor: number;
+    readonly feeMinor: number;
+    readonly netMinor: number;
+    readonly currency: string;
+    readonly status: "matched" | "unmatched" | "mismatch" | "bank_pending";
+    readonly bankReceivedAt: string | null;
+    readonly proof: InvoiceProof;
+}
+type ItemScope = Pick<InvoiceSettlementItem, "providerRef" | "batchRef" | "itemRef" | "providerPaymentRef">;
+export type InvoiceSettlementResult = {
+    readonly kind: "found";
+    readonly scope: ItemScope;
+    readonly paymentIntentRef: string | null;
+    readonly paymentRef: string | null;
+    readonly invoiceRef: string | null;
+    readonly proof: InvoiceProof;
+} | {
+    readonly kind: "absent";
+    readonly scope: ItemScope;
+    readonly evidence: InvoiceProof & {
+        readonly exact: true;
+        readonly complete: true;
+        readonly scope: ItemScope;
+    };
+} | {
+    readonly kind: "recorded";
+    readonly itemRef: string;
+    readonly settlementItemRef: string;
+    readonly replayed: boolean;
+} | {
+    readonly kind: "conflict";
+    readonly itemRef: string;
+    readonly code: "identity_mismatch" | "money_mismatch";
+} | {
+    readonly kind: "unknown";
+    readonly itemRef: string;
+    readonly code: "unknown";
+} | InvoiceUnsupported;
+/** Host recorder/resolver owns richer item identity. Unsupported before any write
+ * when a native batch/payment row cannot represent distinct items or nullable links.
+ * @consumer Host payout item recorder/resolver.
+ */
+export interface InvoiceSettlementPort {
+    record(item: InvoiceSettlementItem): Promise<Exclude<InvoiceSettlementResult, {
+        kind: "found" | "absent";
+    }>>;
+    resolve(input: ItemScope): Promise<Exclude<InvoiceSettlementResult, {
+        kind: "recorded" | "conflict";
+    }>>;
+}
+export {};

package/dist/invoicing/contracts/settlement.js

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

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

@@ -0,0 +1,277 @@
+import type { InvoiceHostPorts } from "./host.js";
+import type { InvoiceFacts, InvoiceClaimedFacts } from "./facts.js";
+import type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported, InvoiceWriteResult, InvoiceReadbackResult } from "./provider.js";
+import type { InvoiceClearanceObservation, InvoiceArtifactResult, InvoiceDeliveryPort } from "./delivery.js";
+type InvoiceDutyStatus = "owed" | "blocked" | "ready" | "processing" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
+/** Native duty/lease fields map to the pinned invoicing_* fixtures. Managed hosts
+ * translate their outboxId/attemptCount fences; never claim transaction equality.
+ */
+export interface InvoiceClaim {
+    readonly dutyId: string;
+    readonly documentId: string;
+    readonly requestId: string;
+    readonly token: string;
+    readonly generation: number;
+    readonly leaseUntil: string;
+    readonly identity: InvoiceIdentity;
+    readonly facts: InvoiceClaimedFacts;
+    readonly action: "create" | "readback";
+    readonly correction: {
+        readonly before: InvoiceFacts;
+        readonly reason: string;
+        readonly after: {
+            readonly totalNetMinor: 0;
+            readonly totalTaxMinor: 0;
+            readonly totalGrossMinor: 0;
+        };
+    } | null;
+}
+/** Exact camel-case shape returned by invoicing_duty_readback. This is not
+ * payment truth's accountingRequested; empty duties never assert invoice absence.
+ * @consumer Operator owed-duty readback.
+ */
+export interface InvoiceDutyReadback {
+    readonly orderId: string;
+    readonly captureFaults: readonly {
+        readonly sourceId: string;
+        readonly state: "retryable" | "faulted" | "resolved";
+        readonly attempts: number;
+        readonly availableAt: string;
+    }[];
+    readonly duties: readonly {
+        readonly dutyId: string;
+        readonly parentDutyId: string | null;
+        readonly documentId: string | null;
+        readonly state: "owed" | "blocked" | "claimed" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
+        readonly attempts: number;
+        readonly factAttempts: number;
+        readonly diagnosticCode: "faulted" | "missing_facts" | "legacy_facts_unproved" | "retryable" | "blocked" | "unsupported" | "unknown" | "absent" | null;
+        readonly createdAt: string;
+        readonly availableAt: string;
+        readonly leaseUntil: string | null;
+    }[];
+}
+/** Every operation is one local transaction; commit before external I/O. Native
+ * success atomically saves late identity and compensation; stale catch writes nothing.
+ * Compatibility stores bind provider selection at construction; the structural
+ * native store accepts it per claim and persists the first provider on the duty.
+ * No implementation, executor or migration is installed by these declarations.
+ */
+export interface InvoiceStorePort {
+    /** Never call inside a renewal money, dunning or dispatch transaction without
+     * isolation: capture failure must not propagate; the sweep recovers.
+     */
+    captureDuty(input: {
+        readonly requestKey: string;
+        readonly sourceKind: "paid" | "handoff";
+        readonly sourceId: string;
+        readonly orderId: string;
+        readonly occurredAt: string;
+        readonly evidence: {
+            readonly settlementIntentId: string;
+            readonly amountMinor: number;
+            readonly currency: string;
+        } | {
+            readonly shipmentId: string;
+            readonly handedOverAt: string;
+        };
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: InvoiceDutyStatus;
+    } | {
+        readonly kind: "conflict";
+        readonly code: "identity_mismatch";
+    } | InvoiceUnsupported>;
+    installFacts(input: {
+        readonly dutyId: string;
+        readonly facts: InvoiceFacts;
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: InvoiceDutyStatus;
+        readonly replayed?: boolean;
+    } | InvoiceUnsupported>;
+    /** Pinned split facts lease: sweep and prepare commit separately; finishing
+     * requires the same token and authoritative document/fact match. No host I/O
+     * under the duty lock, and unsupported never silently drops an owed duty.
+     */
+    sweep(limit: number): Promise<{
+        readonly collected: number;
+        readonly claims: readonly {
+            readonly dutyId: string;
+            readonly token: string;
+        }[];
+    } | InvoiceUnsupported>;
+    prepareFacts(input: {
+        readonly dutyId: string;
+        readonly token: string;
+    }): Promise<{
+        readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "stale";
+        readonly documentId?: string;
+        readonly requestId?: string;
+        readonly code?: "retryable" | "legacy_facts_unproved";
+    } | InvoiceUnsupported>;
+    finishFacts(input: {
+        readonly dutyId: string;
+        readonly token: string;
+        readonly result: Omit<Exclude<Awaited<ReturnType<InvoiceStorePort["prepareFacts"]>>, InvoiceUnsupported>, "status"> & {
+            readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported";
+        };
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "faulted" | "stale";
+    } | InvoiceUnsupported>;
+    readDuties(orderId: string): Promise<InvoiceDutyReadback | InvoiceUnsupported>;
+    /** Filter order before locking/limit; never lease unrelated orders then filter.
+     * P7 host composition reads the injected seller before the separate first-claim SQL wrapper;
+     * its revisionRef supplies p_revision, without requiring a duty from the caller.
+     */
+    claim(input: {
+        readonly limit: number;
+        readonly visibilitySeconds: number;
+        readonly providerRef: string;
+        readonly orderId?: string | null;
+    }): Promise<readonly InvoiceClaim[] | InvoiceUnsupported>;
+    preflight(input: {
+        readonly claim: InvoiceClaim;
+        readonly amountMinor: number | null;
+        readonly currency: string | null;
+    } & ({
+        readonly status: "succeeded" | "failed" | "pending" | "unknown" | "unavailable";
+        readonly proof: InvoiceProof | null;
+    } | {
+        readonly status: "absent";
+        readonly evidence: Extract<Awaited<ReturnType<InvoiceHostPorts["money"]["read"]>>, {
+            kind: "absent";
+        }>["evidence"];
+    })): Promise<{
+        readonly kind: "ready" | "blocked" | "mismatch" | "unavailable" | "stale";
+    } | InvoiceUnsupported>;
+    finish(input: {
+        readonly claim: InvoiceClaim;
+        readonly result: Extract<InvoiceWriteResult, {
+            kind: "issued";
+        }> | Extract<InvoiceReadbackResult, {
+            kind: "found";
+        }>;
+    }): Promise<{
+        readonly kind: "issued";
+        readonly replayed: boolean;
+    } | {
+        readonly kind: "stale";
+    } | InvoiceUnsupported>;
+    /** Retryable requires a definite refusal (effectMayHaveSucceeded:false) or a
+     * pre-I/O failure and phase before_send. Every other failure maps to unknown.
+     * Native result kinds other than stale/voided map to recorded.
+     */
+    fail(input: {
+        readonly claim: InvoiceClaim;
+        readonly retrySeconds: number;
+    } & ({
+        readonly kind: "absent";
+        readonly evidence: Extract<InvoiceReadbackResult, {
+            kind: "absent";
+        }>;
+    } | {
+        readonly kind: "retryable";
+        readonly phase: "before_send";
+        readonly proof: InvoiceProof | null;
+    } | {
+        readonly kind: "blocked" | "unsupported" | "unknown";
+        readonly proof: InvoiceProof | null;
+    })): Promise<{
+        readonly kind: "recorded" | "voided" | "stale";
+    } | InvoiceUnsupported>;
+    /** Native post-write unsupported maps to unsupported_recorded, retaining duty/replay.
+     * Missing means no M09 duty, never invoice absence: retain/retry the reversal
+     * intent and route legacy documents to the incumbent path.
+     */
+    requestReversal(input: {
+        readonly requestKey: string;
+        readonly orderId: string;
+        readonly reason: "order_canceled" | "order_refunded";
+        readonly proof: InvoiceProof;
+    }): Promise<{
+        readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested";
+        readonly dutyId?: string;
+        readonly replayed?: boolean;
+    } | {
+        readonly kind: "unsupported_recorded";
+        readonly dutyId?: string;
+        readonly replayed?: boolean;
+    } | {
+        readonly kind: "conflict";
+        readonly code: "identity_mismatch";
+    } | InvoiceUnsupported>;
+    /** Existing local-only request remains distinct from fiscal issuance. */
+    requestLocalDocument(input: {
+        readonly requestKey: string;
+        readonly orderId: string;
+        readonly providerRef: string;
+    }): Promise<{
+        readonly kind: "requested";
+        readonly documentId: string;
+        readonly invoiceRef: string;
+        readonly status: string;
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+    listClearanceTargets(limit: number): Promise<readonly {
+        readonly documentId: string;
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly providerDocumentNumber: string | null;
+        readonly state: InvoiceClearanceObservation["state"];
+    }[] | InvoiceUnsupported>;
+    /** Native maps clearance state unsupported to observation kind unsupported;
+     * provider_mismatch returns InvoiceUnsupported before recording anything.
+     */
+    recordObservation(input: {
+        readonly requestKey: string;
+        readonly documentId: string;
+        readonly eventRef: string;
+        readonly eventKind: "clearance" | "artifacts" | "unsupported" | "provider_mismatch";
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly providerDocumentNumber: string | null;
+        readonly clearance: InvoiceClearanceObservation | null;
+        readonly artifacts: readonly Extract<InvoiceArtifactResult, {
+            kind: "found";
+        }>["artifact"][];
+        readonly observedAt: string;
+        readonly payloadHash: string;
+        readonly source: "provider_api" | "provider_webhook" | "manual_reconciliation";
+    }): Promise<{
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+    /** Verify M04 binding before claiming; document rows need no M09 issue duty. */
+    claimDeliveries(input: {
+        readonly limit: number;
+        readonly visibilitySeconds: number;
+        readonly requireClearance: boolean;
+        readonly orderId?: string | null;
+    }): Promise<readonly {
+        readonly token: string;
+        readonly generation: number;
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly delivery: Omit<Parameters<InvoiceDeliveryPort["send"]>[0], "filename" | "content" | "contentType">;
+    }[] | InvoiceUnsupported>;
+    /** Native uncertain settlement passes p_receipt NULL and retains a non-null
+     * receiptRef hint in p_evidence; managed uses it as the provider message id.
+     * Managed failed_before_send uses the retrySeconds RPC argument. Native
+     * failed_before_send carries { phase: 'before_send', retryable, retrySeconds }
+     * in p_evidence: whole seconds clamp to 60..86400, absent/invalid uses 900.
+     * retryable:false parks at infinity, with failed status and last_error visible.
+     */
+    settleDelivery(input: {
+        readonly deliveryRef: string;
+        readonly token: string;
+        readonly generation: number;
+        readonly providerDocumentRef: string;
+        readonly retrySeconds: number;
+        readonly result: Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, InvoiceUnsupported>;
+    }): Promise<{
+        readonly kind: "recorded" | "stale";
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+}
+export {};

package/dist/invoicing/contracts/store.js

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

package/dist/invoicing/contribution.d.ts

@@ -0,0 +1,21 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Inert descriptors for the host's existing registry and executor. No registration. */
+export declare function createInvoiceContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    invoicing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+    handlers: Contribution["handlers"];
+    schedules: Contribution["schedules"];
+    routes: Contribution["routes"];
+}): {
+    contributions: Contribution[];
+    ports: {
+        [k: string]: ((...args: never[]) => unknown) | null;
+    };
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+    triggers: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};

package/dist/invoicing/contribution.js

@@ -0,0 +1,19 @@
+/** Inert descriptors for the host's existing registry and executor. No registration. */
+export function createInvoiceContribution(input) {
+    const contribution = {
+        manifest: {
+            name: "@openlup/platform", version: input.version, kind: "rail",
+            module: { id: "invoicing", kind: "capability", provides: ["./invoicing"], dependsOn: [] },
+            emits: [], handles: input.handlers.map(handler => handler.eventType), env: [],
+            schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })),
+            requiredPorts: Object.keys(input.invoicing), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+        },
+        handlers: input.handlers, schedules: input.schedules, routes: input.routes,
+    };
+    return {
+        contributions: [contribution],
+        ports: Object.fromEntries(Object.entries(input.invoicing).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/invoicing:${name}`, fn])),
+        routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/invoicing:${route.id}`, route.handle])),
+        triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/invoicing:${schedule.id}`, schedule.run])),
+    };
+}

package/dist/invoicing/correction.d.ts

@@ -0,0 +1,42 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export declare function runInvoiceCorrectionJob<Claim extends {
+    outboxId: string;
+    attemptCount: number;
+    providerInvoiceId: string;
+    correctionReason: string;
+    payload: Record<string, unknown>;
+}, Snapshot, Result extends Pick<Extract<InvoiceWriteResult, {
+    kind: "issued";
+}>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+    createEnabled: boolean;
+    providerEnabled: boolean;
+    claim(): Promise<readonly Claim[]>;
+    project(claim: Claim): Snapshot;
+    /** Resolve accepted/recovered receipts only; unknown is never an ACK or absence. */
+    create(snapshot: Snapshot, options: {
+        correctionReason: string;
+        correctedProviderInvoiceId: string;
+        correctionRef: string;
+        recoveryLookupRequired: boolean;
+    }): Promise<Result>;
+    finish(claim: Claim, result: Result): Promise<unknown>;
+    isClaimFenceError(error: unknown): boolean;
+    fail(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+}): Promise<{
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    reason: string;
+    failures: number;
+} | {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    failures: number;
+}>;

package/dist/invoicing/correction.js

@@ -0,0 +1,44 @@
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceCorrectionJob(input) {
+    if (!input.createEnabled)
+        return skipped("create_disabled");
+    if (!input.providerEnabled)
+        return skipped("provider_disabled");
+    const claims = await input.claim();
+    let updated = 0;
+    let failures = 0;
+    for (const claim of claims) {
+        try {
+            const correctionRef = `accounting-correction:${claim.outboxId}`;
+            if (claim.payload.providerCreateIdentity !== correctionRef) {
+                throw new Error("accounting_correction_recovery_identity_missing");
+            }
+            const snapshot = input.project(claim);
+            const result = await input.create(snapshot, {
+                correctionReason: claim.correctionReason,
+                correctedProviderInvoiceId: claim.providerInvoiceId,
+                correctionRef,
+                recoveryLookupRequired: claim.attemptCount > 1,
+            });
+            await input.finish(claim, result);
+            updated += 1;
+        }
+        catch (error) {
+            failures += 1;
+            if (input.isClaimFenceError(error))
+                continue;
+            try {
+                await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+            }
+            catch (failureError) {
+                if (!input.isClaimFenceError(failureError))
+                    throw failureError;
+            }
+        }
+    }
+    return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/dist/invoicing/delivery.d.ts

@@ -0,0 +1,85 @@
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+import type { InvoiceStorePort } from "./contracts/store.js";
+import type { InvoiceDeliveryPort } from "./contracts/delivery.js";
+type DeliveryOutcome = Omit<Extract<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, {
+    kind: "provider_accepted";
+}>, "proof"> | Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, {
+    kind: "provider_accepted";
+}>;
+/** Donor sequencing over host claims, original keys, M04 transport and fenced
+ * finalizers. Native hosts MUST bind terminalFailure before leasing work.
+ * With CTL-M09-3's 191000 pin, failedBeforeSend settles failed_before_send with
+ * evidence { phase: 'before_send', retrySeconds }: whole seconds clamped
+ * to 60..86400, absent/invalid uses 900;
+ * terminalFailure uses { phase: 'before_send', retryable: false } for no reclaim.
+ * Native store mode refuses before claim unless its host projection is bound.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+type DeliveryJobInput<Claim, Result extends DeliveryOutcome> = {
+    enabled: boolean;
+    providerEnabled: boolean;
+    deliveryEnabled: boolean;
+    claim(): Promise<readonly Claim[] | InvoiceUnsupported>;
+    attemptCount(claim: Claim): number;
+    validate(claim: Claim): void;
+    download(claim: Claim): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+    filename(claim: Claim): string;
+    /** A rejected promise proves failure BEFORE transport entry. Once entered,
+     * the M04 binding must return uncertain, including timeout/lost ACK. */
+    send(claim: Claim, document: {
+        filename: string;
+        content: Uint8Array;
+        contentType: string;
+    }): Promise<Result>;
+    failedBeforeSend(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+    /** Must durably stop reclaim using the same fence. Native failed_before_send
+     * evidence { phase: 'before_send', retryable: false } sets available_at to infinity. */
+    terminalFailure(claim: Claim, result: Extract<Result, {
+        kind: "failed_before_send" | "unsupported";
+    }>): Promise<unknown>;
+    uncertain(claim: Claim, result: Extract<Result, {
+        kind: "uncertain";
+    }>): Promise<unknown>;
+    accepted(claim: Claim, result: Extract<Result, {
+        kind: "provider_accepted";
+    }>): Promise<unknown>;
+    finalizeUncertain(claim: Claim, receiptRef: string): Promise<unknown>;
+};
+type NativeClaim = Exclude<Awaited<ReturnType<InvoiceStorePort["claimDeliveries"]>>, InvoiceUnsupported>[number];
+type NativeDeliveryJobInput = {
+    enabled: boolean;
+    providerEnabled: boolean;
+    deliveryEnabled: boolean;
+    store: Pick<InvoiceStorePort, "claimDeliveries" | "settleDelivery">;
+    claimOptions: Parameters<InvoiceStorePort["claimDeliveries"]>[0];
+    download(claim: NativeClaim): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+    filename(claim: NativeClaim): string;
+    send: InvoiceDeliveryPort["send"];
+};
+/** Host callback mode preserves donor sequencing. Native store mode supplies
+ * fenced terminal/backoff finalizers and the M04 envelope from claimDeliveries.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+export declare function runInvoiceDeliveryJob(input: NativeDeliveryJobInput): ReturnType<typeof runDeliveryJob>;
+export declare function runInvoiceDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>): ReturnType<typeof runDeliveryJob>;
+declare function runDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>): Promise<{
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    reason: string;
+    failures: number;
+} | {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    failures: number;
+}>;
+export {};

package/dist/invoicing/delivery.js

@@ -0,0 +1,79 @@
+import { assertInvoicePdf } from "./artifacts.js";
+export function runInvoiceDeliveryJob(input) {
+    if (!("store" in input))
+        return runDeliveryJob(input);
+    const settle = async (claim, result, retrySeconds = 900) => {
+        const outcome = await input.store.settleDelivery({ deliveryRef: claim.delivery.deliveryRef, token: claim.token,
+            generation: claim.generation, providerDocumentRef: claim.providerDocumentRef, retrySeconds, result });
+        if (outcome.kind !== "recorded")
+            throw new Error("invoicing_delivery_fence");
+    };
+    return runDeliveryJob({
+        enabled: input.enabled, providerEnabled: input.providerEnabled, deliveryEnabled: input.deliveryEnabled,
+        claim: () => input.store.claimDeliveries(input.claimOptions), attemptCount: claim => claim.generation,
+        validate: () => { }, download: input.download, filename: input.filename,
+        send: (claim, document) => input.send({ ...claim.delivery, ...document }),
+        failedBeforeSend: (claim, _error, retrySeconds) => settle(claim, { kind: "failed_before_send", retryable: true, code: "retryable" }, retrySeconds),
+        terminalFailure: (claim, result) => settle(claim, result.kind === "failed_before_send" ? result
+            : { kind: "failed_before_send", retryable: false, code: "retryable" }),
+        uncertain: (claim, result) => settle(claim, result), accepted: (claim, result) => settle(claim, result),
+        finalizeUncertain: (claim, receiptRef) => settle(claim, { kind: "uncertain", code: "uncertain_delivery", receiptRef }),
+    });
+}
+async function runDeliveryJob(input) {
+    if (!input.enabled)
+        return skipped("provider_email_disabled");
+    if (!input.providerEnabled)
+        return skipped("provider_disabled");
+    if (!input.deliveryEnabled)
+        return skipped("email_delivery_provider_disabled");
+    // JS hosts missing a mandatory terminal policy must refuse before claiming.
+    if (typeof input.terminalFailure !== "function")
+        return skipped("host_binding_required");
+    const claims = await input.claim();
+    if (!Array.isArray(claims))
+        return skipped("host_binding_required");
+    let updated = 0;
+    let failures = 0;
+    for (const claim of claims) {
+        let result;
+        const retrySeconds = Math.min(3600, 300 * Math.max(1, input.attemptCount(claim)));
+        try {
+            input.validate(claim);
+            const pdf = await input.download(claim);
+            assertInvoicePdf(pdf);
+            result = await input.send(claim, { ...pdf, filename: input.filename(claim) });
+        }
+        catch (error) {
+            failures += 1;
+            await input.failedBeforeSend(claim, error, retrySeconds);
+            continue;
+        }
+        if (result.kind === "failed_before_send" || result.kind === "unsupported") {
+            failures += 1;
+            if (result.kind === "failed_before_send" && result.retryable) {
+                await input.failedBeforeSend(claim, result, retrySeconds);
+            }
+            else {
+                await input.terminalFailure(claim, result);
+            }
+            continue;
+        }
+        if (result.kind === "uncertain") {
+            failures += 1;
+            await input.uncertain(claim, result);
+            continue;
+        }
+        try {
+            await input.accepted(claim, result);
+            updated += 1;
+        }
+        catch {
+            failures += 1;
+            // Acceptance plus a lost local ACK cannot become a retryable send.
+            await input.finalizeUncertain(claim, result.receiptRef).catch(() => undefined);
+        }
+    }
+    return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }