@openlup/platform 0.23.0 → 0.25.0

package/dist/invoicing/issue.d.ts

@@ -0,0 +1,39 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+/** Donor issue sequencing over explicit compatibility callbacks. No transaction
+ * spans a callback; hosts bind their existing claim/preflight/finalizer contracts.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export declare function runInvoiceIssueJob<Claim extends {
+    attemptCount: number;
+}, Snapshot, Evidence, Result extends Pick<Extract<InvoiceWriteResult, {
+    kind: "issued";
+}>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+    createEnabled: boolean;
+    providerEnabled: boolean;
+    claim(): Promise<readonly Claim[]>;
+    localPreflight(claim: Claim): Promise<boolean>;
+    project(claim: Claim): Snapshot;
+    blockMapper(claim: Claim, code: string, error: unknown): Promise<unknown>;
+    readPayment(claim: Claim): Promise<Evidence>;
+    freshPreflight(claim: Claim, evidence: Evidence): Promise<boolean>;
+    /** Resolve only accepted/recovered document receipts; unknown/absent is not an ACK. */
+    create(snapshot: Snapshot, options: {
+        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/issue.js

@@ -0,0 +1,55 @@
+/** Donor issue sequencing over explicit compatibility callbacks. No transaction
+ * spans a callback; hosts bind their existing claim/preflight/finalizer contracts.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceIssueJob(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 {
+            if (!await input.localPreflight(claim)) {
+                failures += 1;
+                continue;
+            }
+            let snapshot;
+            try {
+                snapshot = input.project(claim);
+            }
+            catch (error) {
+                const canonicalCode = canonicalMapperErrorCode(error);
+                if (!canonicalCode)
+                    throw error;
+                await input.blockMapper(claim, canonicalCode, error);
+                failures += 1;
+                continue;
+            }
+            const providerEvidence = await input.readPayment(claim);
+            if (!await input.freshPreflight(claim, providerEvidence)) {
+                failures += 1;
+                continue;
+            }
+            const result = await input.create(snapshot, { recoveryLookupRequired: claim.attemptCount > 1 });
+            await input.finish(claim, result);
+            updated += 1;
+        }
+        catch (error) {
+            failures += 1;
+            if (input.isClaimFenceError(error))
+                continue;
+            await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+        }
+    }
+    return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function canonicalMapperErrorCode(error) {
+    if (!(error instanceof Error))
+        return null;
+    const match = /\b(accounting_invoice_canonical_[a-z0-9_]+)/.exec(error.message);
+    return match?.[1] ?? null;
+}
+function skipped(reason) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/dist/invoicing/migrations.d.ts

@@ -0,0 +1,48 @@
+/** Sparse native projections, not an installation chain. Install the full catalogue. */
+export declare const INVOICING_MIGRATIONS: {
+    readonly native: {
+        readonly correctionStorage: "child_document";
+        readonly fiscalScope: "explicit_host_facts";
+        readonly units: readonly [{
+            readonly position: 7;
+            readonly catalogPath: "db/platform/migrations/20260809210000_accounting_document_rail.sql";
+            readonly sha256: "f5c6c4b3d5ccdd7c7137669edba7d45c63685edc57fe982e3e8fd559214ccc8e";
+            readonly url: URL;
+        }, {
+            readonly position: 13;
+            readonly catalogPath: "db/platform/migrations/20260811150000_accounting_payout_rail.sql";
+            readonly sha256: "b127631196362d59ceb94700426766659589601c69a5adfb1b5d6bbeadf5b0db";
+            readonly url: URL;
+        }, {
+            readonly position: 15;
+            readonly catalogPath: "db/platform/migrations/20260812130000_accounting_document_lifecycle_rail.sql";
+            readonly sha256: "450ae24b8ba9438ea267cfbf52f9c78a790b1803f369c216577566952fa43b5f";
+            readonly url: URL;
+        }, {
+            readonly position: 77;
+            readonly catalogPath: "db/platform/migrations/20261022190000_invoicing_durable_duties.sql";
+            readonly sha256: "2d7bf98924b4ef29b3e8f902d768e45dd9c850242f4358a0193a0c00d0f3d081";
+            readonly url: URL;
+        }, {
+            readonly position: 78;
+            readonly catalogPath: "db/platform/migrations/20261022191000_invoicing_document_effects.sql";
+            readonly sha256: "0eac3453e2b82c43e4fff9e35bcd6daefdd0bb5f992937f7f411d690550428cf";
+            readonly url: URL;
+        }, {
+            readonly position: 79;
+            readonly catalogPath: "db/platform/migrations/20261022192000_invoicing_payment_decoupling.sql";
+            readonly sha256: "f4af30ee4c9365ea51bd0e95e5cc7ae869cf15dce5867fdd640f679438b36058";
+            readonly url: URL;
+        }, {
+            readonly position: 80;
+            readonly catalogPath: "db/platform/migrations/20261022195000_invoicing_seller_revision.sql";
+            readonly sha256: "5a6348d9af296cfc6383894e3489f70af1f3bb5026c0cc329daa9f3f95802b22";
+            readonly url: URL;
+        }];
+    };
+    readonly managed: {
+        readonly correctionStorage: "base_row";
+        readonly fiscalScope: "host_managed_projection";
+        readonly units: readonly ["supabase/migrations/20261022193000_invoicing_correction_claims.sql", "supabase/migrations/20261022193100_invoicing_correction_compatibility.sql", "supabase/migrations/20261022195100_invoicing_seller_revision.sql"];
+    };
+};

package/dist/invoicing/migrations.js

@@ -0,0 +1,25 @@
+/** Sparse native projections, not an installation chain. Install the full catalogue. */
+export const INVOICING_MIGRATIONS = {
+    native: {
+        correctionStorage: "child_document",
+        fiscalScope: "explicit_host_facts",
+        units: [
+            { position: 7, catalogPath: "db/platform/migrations/20260809210000_accounting_document_rail.sql", sha256: "f5c6c4b3d5ccdd7c7137669edba7d45c63685edc57fe982e3e8fd559214ccc8e", url: new URL("../../sql/20260809210000_accounting_document_rail.sql", import.meta.url) },
+            { position: 13, catalogPath: "db/platform/migrations/20260811150000_accounting_payout_rail.sql", sha256: "b127631196362d59ceb94700426766659589601c69a5adfb1b5d6bbeadf5b0db", url: new URL("../../sql/20260811150000_accounting_payout_rail.sql", import.meta.url) },
+            { position: 15, catalogPath: "db/platform/migrations/20260812130000_accounting_document_lifecycle_rail.sql", sha256: "450ae24b8ba9438ea267cfbf52f9c78a790b1803f369c216577566952fa43b5f", url: new URL("../../sql/20260812130000_accounting_document_lifecycle_rail.sql", import.meta.url) },
+            { position: 77, catalogPath: "db/platform/migrations/20261022190000_invoicing_durable_duties.sql", sha256: "2d7bf98924b4ef29b3e8f902d768e45dd9c850242f4358a0193a0c00d0f3d081", url: new URL("../../sql/20261022190000_invoicing_durable_duties.sql", import.meta.url) },
+            { position: 78, catalogPath: "db/platform/migrations/20261022191000_invoicing_document_effects.sql", sha256: "0eac3453e2b82c43e4fff9e35bcd6daefdd0bb5f992937f7f411d690550428cf", url: new URL("../../sql/20261022191000_invoicing_document_effects.sql", import.meta.url) },
+            { position: 79, catalogPath: "db/platform/migrations/20261022192000_invoicing_payment_decoupling.sql", sha256: "f4af30ee4c9365ea51bd0e95e5cc7ae869cf15dce5867fdd640f679438b36058", url: new URL("../../sql/20261022192000_invoicing_payment_decoupling.sql", import.meta.url) },
+            { position: 80, catalogPath: "db/platform/migrations/20261022195000_invoicing_seller_revision.sql", sha256: "5a6348d9af296cfc6383894e3489f70af1f3bb5026c0cc329daa9f3f95802b22", url: new URL("../../sql/20261022195000_invoicing_seller_revision.sql", import.meta.url) },
+        ],
+    },
+    managed: {
+        correctionStorage: "base_row",
+        fiscalScope: "host_managed_projection",
+        units: [
+            "supabase/migrations/20261022193000_invoicing_correction_claims.sql",
+            "supabase/migrations/20261022193100_invoicing_correction_compatibility.sql",
+            "supabase/migrations/20261022195100_invoicing_seller_revision.sql",
+        ],
+    },
+};

package/dist/invoicing/nativeUnsupported.d.ts

@@ -0,0 +1,9 @@
+import type { InvoiceHostPorts, InvoiceStorePort, InvoiceServicesOptions } from "./contracts/index.js";
+/** @consumer Host native binding / installed cold consumer. No executor, inputs,
+ * provider or storage is inspected: every missing native seam refuses before writes.
+ */
+export declare function createNativeUnsupportedInvoicePorts(): {
+    host: InvoiceHostPorts;
+    store: InvoiceStorePort;
+    provider: NonNullable<InvoiceServicesOptions["provider"]>;
+};

package/dist/invoicing/nativeUnsupported.js

@@ -0,0 +1,22 @@
+const refusal = Object.freeze({ kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false });
+/** @consumer Host native binding / installed cold consumer. No executor, inputs,
+ * provider or storage is inspected: every missing native seam refuses before writes.
+ */
+export function createNativeUnsupportedInvoicePorts() {
+    const unsupported = async () => refusal;
+    return {
+        host: {
+            facts: { read: unsupported }, seller: { read: unsupported }, money: { read: unsupported }, fiscal: { verify: unsupported },
+            artifacts: { read: unsupported, download: unsupported, persist: unsupported }, registry: { lookup: unsupported },
+            delivery: { send: unsupported }, clearance: { observe: unsupported }, settlement: { record: unsupported, resolve: unsupported },
+            policy: { decide: unsupported, receipts: unsupported }, accountHistory: { read: unsupported, resolveDownload: unsupported },
+        },
+        store: {
+            captureDuty: unsupported, installFacts: unsupported, sweep: unsupported, prepareFacts: unsupported, finishFacts: unsupported,
+            readDuties: unsupported, claim: unsupported, preflight: unsupported, finish: unsupported, fail: unsupported,
+            requestReversal: unsupported, requestLocalDocument: unsupported, listClearanceTargets: unsupported,
+            recordObservation: unsupported, claimDeliveries: unsupported, settleDelivery: unsupported,
+        },
+        provider: { issue: unsupported, correct: unsupported, read: unsupported, void: unsupported },
+    };
+}

package/dist/invoicing/paymentReadback.d.ts

@@ -0,0 +1,20 @@
+type PaymentEvidence = {
+    providerStatus: "succeeded" | "failed" | "pending" | "unknown" | "unavailable";
+    providerAmountCents: number | null;
+    providerCurrency: string | null;
+    providerEvidence: Record<string, unknown>;
+};
+export declare function readInvoicePaymentEvidence(payment: {
+    provider: string;
+    providerPaymentId: string | null;
+}, provider: {
+    readPayment(input: {
+        providerPaymentId: string;
+    }): Promise<{
+        status: "succeeded" | "failed" | "pending" | "unknown";
+        providerStatus: string;
+        amountMinor: number | null;
+        currency: string | null;
+    }>;
+} | undefined): Promise<PaymentEvidence>;
+export {};

package/dist/invoicing/paymentReadback.js

@@ -0,0 +1,47 @@
+export async function readInvoicePaymentEvidence(payment, provider) {
+    const providerName = payment.provider;
+    if (!provider || !payment.providerPaymentId) {
+        return unavailable(providerName, payment.providerPaymentId, provider ? "provider_payment_id_missing" : "provider_not_configured");
+    }
+    try {
+        const readback = await provider.readPayment({
+            providerPaymentId: payment.providerPaymentId,
+        });
+        return {
+            providerStatus: readback.status,
+            providerAmountCents: integerOrNull(readback.amountMinor),
+            providerCurrency: currencyOrNull(readback.currency),
+            providerEvidence: {
+                source: "provider_api",
+                provider: providerName,
+                providerPaymentId: payment.providerPaymentId,
+                providerStatus: readback.providerStatus.slice(0, 80),
+                amountAvailable: integerOrNull(readback.amountMinor) !== null,
+                currencyAvailable: currencyOrNull(readback.currency) !== null,
+            },
+        };
+    }
+    catch {
+        return unavailable(providerName, payment.providerPaymentId, "provider_read_failed");
+    }
+}
+function unavailable(provider, providerPaymentId, reason) {
+    return {
+        providerStatus: "unavailable",
+        providerAmountCents: null,
+        providerCurrency: null,
+        providerEvidence: {
+            source: "provider_api",
+            provider,
+            providerPaymentId,
+            unavailableReason: reason,
+        },
+    };
+}
+function integerOrNull(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function currencyOrNull(value) {
+    const normalized = value?.trim().toUpperCase() ?? "";
+    return /^[A-Z]{3}$/.test(normalized) ? normalized : null;
+}

package/dist/invoicing/postgresInvoiceStore.d.ts

@@ -0,0 +1,55 @@
+import type { InvoiceStorePort, InvoiceHostPorts, InvoiceProviderPort } from "./contracts/index.js";
+type InvoiceClaim = Parameters<InvoiceStorePort["preflight"]>[0]["claim"];
+type NativeStore = InvoiceStorePort & {
+    /** Read-only discovery before a host can install facts. Replays may repeat targets. */
+    discoverDuties(limit: number, afterDutyId?: string | null): Promise<readonly {
+        readonly dutyId: string;
+        readonly orderId: string;
+    }[]>;
+};
+type DeliveryClaim = Exclude<Awaited<ReturnType<InvoiceStorePort["claimDeliveries"]>>, {
+    kind: "unsupported";
+}>[number];
+type DeliveryProjection = {
+    /** Host-owned M04 keys, presentation and recipient resolution, after leasing.
+     * Return only the envelope for this document; a failed projection never sends.
+     */
+    projectDelivery(input: {
+        readonly deliveryRef: string;
+        readonly documentId: string;
+        readonly channel: string;
+        readonly recipientRef: string;
+        readonly attemptCount: number;
+    }): Promise<Pick<DeliveryClaim, "identity" | "delivery">>;
+};
+type Executor = {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+};
+/** Bind an autocommit executor. Never pass a transaction spanning host/provider I/O.
+ * Missing fiscal facts or delivery binding refuse before writes; no scheduler is installed.
+ */
+export declare function createPostgresInvoiceStore(db: Executor, options?: Partial<DeliveryProjection> & {
+    readonly seller?: InvoiceHostPorts["seller"];
+}): NativeStore;
+type MoneyEvidence = Awaited<ReturnType<InvoiceHostPorts["money"]["read"]>>;
+/** Native issue/readback binding; every store operation commits before host I/O.
+ * @consumer Explicit native host issue binding and installed-consumer conformance.
+ */
+export declare function runNativeInvoiceIssueJob(input: {
+    store: Pick<InvoiceStorePort, "claim" | "preflight" | "finish" | "fail">;
+    provider: Pick<InvoiceProviderPort, "issue" | "correct" | "read">;
+    money: InvoiceHostPorts["money"];
+    readLocalPayment(claim: InvoiceClaim): Promise<MoneyEvidence>;
+    providerRef: string;
+    orderId?: string | null;
+    limit?: number;
+    visibilitySeconds?: number;
+}): Promise<import("./contracts/provider.js").InvoiceUnsupported | {
+    checked: number;
+    updated: number;
+    failures: number;
+    ok: boolean;
+}>;
+export {};