@openlup/platform 0.21.0 → 0.23.0

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

@@ -0,0 +1,100 @@
+/** Frozen host facts; no catalogue, registry or country-policy reread on retry.
+ * Carrier: donor providerPorts snapshot and invoiceContracts LocalInvoiceSnapshot;
+ * native invoicing_install_facts adds dates/refs/policyVersion and explicit totals.
+ */
+export interface InvoiceSeller {
+    readonly name: string;
+    readonly address: {
+        readonly line1: string;
+        readonly postalCode: string;
+        readonly city: string;
+    };
+    readonly taxIdentifier: {
+        readonly scheme: string;
+        readonly value: string;
+    };
+    readonly registrationIds?: readonly {
+        readonly scheme: string;
+        readonly value: string;
+    }[];
+    readonly bankAccount: string | null;
+    /** Opaque host routing reference, interpreted only by the selected adapter. */
+    readonly routingRef: string | null;
+}
+export interface InvoiceBuyer {
+    readonly name: string;
+    readonly email: string | null;
+    readonly taxIdentifier: {
+        readonly scheme: string;
+        readonly value: string;
+    } | null;
+    readonly companyName: string | null;
+    readonly address: {
+        readonly line1: string | null;
+        readonly postalCode: string | null;
+        readonly city: string | null;
+        readonly country: string | null;
+    } | null;
+}
+/** Safe integer minor amounts; taxRateBps is a rate, never a fiscal-support claim.
+ * Preserve array order and quantityUnit; no inferred shipping residual or FX.
+ */
+export interface InvoiceLine {
+    readonly description: string;
+    readonly quantity: number;
+    readonly quantityUnit?: string;
+    readonly unitNetMinor: number;
+    readonly unitGrossMinor: number;
+    readonly totalNetMinor: number;
+    readonly totalTaxMinor: number;
+    readonly totalGrossMinor: number;
+    readonly taxRateBps: number;
+    readonly taxRateLabel?: string;
+    readonly positionKind: "item" | "delivery" | null;
+    readonly catalogTotalGrossMinor: number | null;
+    readonly discountAllocatedMinor: number | null;
+    readonly shippingGrossMinor: number | null;
+    readonly shippingDiscountMinor: number | null;
+}
+export interface InvoiceFacts {
+    readonly factRevision: string;
+    readonly policyVersion: string;
+    readonly refs: {
+        readonly orderId: string;
+        readonly orderRef: string;
+        readonly invoiceRef: string;
+    };
+    readonly dates: {
+        readonly issueDate: string;
+        readonly sellDate: string;
+        readonly handedOverAt: string | null;
+        readonly paymentCompletedAt: string | null;
+    };
+    /** Host-defined kind selected through the identifier/tax seam, never guessed. */
+    readonly documentKind: string;
+    readonly clearanceRequired: boolean;
+    readonly currency: string;
+    readonly buyer: InvoiceBuyer;
+    /** Supplied separately for execution; P8 freezes it at first claim before provider I/O. */
+    readonly seller?: InvoiceSeller;
+    readonly payment: {
+        readonly intentRef: string;
+        readonly providerRef: string | null;
+        readonly providerPaymentRef: string | null;
+        readonly amountMinor: number;
+        readonly currency: string;
+        readonly localSettlementState: "matched" | "unavailable";
+    };
+    readonly orderMoney: {
+        readonly subtotalMinor: number;
+        readonly discountMinor: number;
+        readonly shippingMinor: number;
+        readonly shippingDiscountMinor: number;
+        readonly totalMinor: number;
+    } | null;
+    readonly lines: readonly InvoiceLine[];
+    readonly totalNetMinor: number;
+    readonly totalTaxMinor: number;
+    readonly totalGrossMinor: number;
+    readonly chargedTotalGrossMinor: number;
+}

package/dist/invoicing/contracts/facts.js

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

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

@@ -0,0 +1,246 @@
+import type { InvoiceFacts, InvoiceSeller } from "./facts.js";
+import type { InvoiceDocumentIdentity, InvoiceProof, InvoiceProviderPort, InvoiceUnsupported } from "./provider.js";
+import type { InvoiceArtifactResult, InvoiceClearanceObservation, InvoiceDeliveryPort } from "./delivery.js";
+import type { InvoiceCompanyLookupPort } from "./companyLookup.js";
+import type { InvoiceSettlementPort } from "./settlement.js";
+import type { InvoiceCapabilities } from "./capabilities.js";
+import type { InvoiceStorePort } from "./store.js";
+/** Host facts, fiscal routing, M07 reads, storage, registry, M04 delivery and M12
+ * history are required selections. Every missing native capability refuses before
+ * any write; an owed duty remains observable. This interface grants no authority.
+ */
+export interface InvoiceHostPorts {
+    facts: {
+        read(orderId: string): Promise<{
+            readonly kind: "found";
+            readonly facts: InvoiceFacts;
+        } | {
+            readonly kind: "unknown";
+            readonly code: "missing_facts";
+        } | InvoiceUnsupported>;
+    };
+    /** Read the current host seller for the next claim, never per duty. Null orderId
+     * means an unscoped claim (including corrections). P8 freezes this seller at
+     * first claim; revisionRef feeds the claim wrapper's revision argument.
+     */
+    seller: {
+        read(input: {
+            readonly orderId: string | null;
+        }): Promise<{
+            readonly kind: "found";
+            readonly seller: InvoiceSeller;
+            readonly revisionRef: string;
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+    };
+    /** Read-only projection of the final claimed M07 identity, never a refund writer.
+     * Missing nullable money is unavailable, never fabricated zero or mismatch.
+     */
+    money: {
+        read(input: {
+            readonly intentRef: string;
+            readonly providerRef: string;
+            readonly providerPaymentRef: string | null;
+            readonly expectedMoney: {
+                readonly amountMinor: number;
+                readonly currency: string;
+            };
+        }): Promise<{
+            readonly kind: "observed";
+            readonly status: "succeeded" | "failed" | "pending";
+            readonly amountMinor: number | null;
+            readonly currency: string | null;
+            readonly proof: InvoiceProof;
+        } | {
+            readonly kind: "absent";
+            readonly evidence: InvoiceProof & {
+                readonly exact: true;
+                readonly complete: true;
+                readonly scope: Parameters<InvoiceHostPorts["money"]["read"]>[0];
+            };
+        } | {
+            readonly kind: "unknown" | "unavailable";
+            readonly code: "money_unavailable";
+        } | InvoiceUnsupported>;
+    };
+    artifacts: {
+        read(input: {
+            readonly identity: InvoiceDocumentIdentity;
+            readonly kind: "pdf" | "structured_document" | "clearance_receipt";
+        }): Promise<InvoiceArtifactResult>;
+        /** Ownership must already be authorized; response bytes are not a storage receipt. */
+        download(input: {
+            readonly identity: InvoiceDocumentIdentity;
+            readonly artifactRef: string;
+        }): Promise<{
+            readonly kind: "downloaded";
+            readonly content: Uint8Array;
+            readonly contentType: string;
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+        persist(input: {
+            readonly identity: InvoiceDocumentIdentity;
+            readonly kind: "pdf" | "structured_document" | "clearance_receipt";
+            readonly content: Uint8Array;
+            readonly contentType: string;
+        }): Promise<Exclude<InvoiceArtifactResult, {
+            kind: "absent";
+        }>>;
+    };
+    /** Host identifier/tax/rounding policy; refs must match the selected descriptor.
+     * No jurisdictional default is supplied. Carrier: TaxIdRoutingPort and injected
+     * canonical tax safety in accountingProviderSnapshot.
+     */
+    fiscal: {
+        verify(input: {
+            readonly facts: InvoiceFacts;
+            readonly policies: InvoiceCapabilities["policies"];
+        }): Promise<{
+            readonly kind: "verified";
+            readonly documentKind: string;
+            readonly clearanceRequired: boolean;
+            readonly proof: InvoiceProof;
+        } | {
+            readonly kind: "refused";
+            readonly code: "blocked" | "money_mismatch";
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+    };
+    registry: InvoiceCompanyLookupPort;
+    delivery: InvoiceDeliveryPort;
+    clearance: {
+        observe(input: {
+            readonly identity: InvoiceDocumentIdentity;
+            readonly providerDocumentRef: string;
+        }): Promise<{
+            readonly kind: "observed";
+            readonly observation: InvoiceClearanceObservation;
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+    };
+    settlement: InvoiceSettlementPort;
+    policy: {
+        /** Carrier: channelInvoicePolicyGate and the approved explicit operator skip.
+         * Suppression receipts have no fabricated document ID. Host persists attribution.
+         * Executor decides before installFacts: suppressed orders get no local document.
+         * Readback consumers merge recorded receipts with duty readback.
+         * Transient read failures return unknown without recording a receipt.
+         */
+        decide(input: {
+            readonly requestKey: string;
+            readonly lookup: {
+                readonly by: "order";
+                readonly orderId: string;
+            } | {
+                readonly by: "fulfillmentOrder";
+                readonly fulfillmentOrderRef: string;
+            };
+        }): Promise<{
+            readonly kind: "issue";
+            readonly policyVersion: string;
+        } | {
+            readonly kind: "policy_suppressed";
+            readonly outcome: "channel_issues" | "no_document";
+            readonly policyVersion: string;
+            readonly requestKey: string;
+        } | {
+            readonly kind: "operator_skipped";
+            readonly outcome: "operator_skip";
+            readonly actorRef: string;
+            readonly reason: string;
+            readonly requestKey: string;
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+        receipts(orderId: string): Promise<readonly (Extract<Awaited<ReturnType<InvoiceHostPorts["policy"]["decide"]>>, {
+            kind: "policy_suppressed" | "operator_skipped";
+        }> & {
+            readonly recordedAt: string;
+        })[] | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+    };
+    /** Authenticate and authorize ownership before reading artifacts. Safe projection
+     * only: no buyer/seller payload, raw provider errors, signed URL or arbitrary meta.
+     * Found is a complete owned projection; incomplete reads return unknown.
+     * Carrier: donor document history + customer download ticket owner/lineage.
+     */
+    accountHistory: {
+        read(input: {
+            readonly accountRef: string;
+            readonly orderId: string;
+        }): Promise<{
+            readonly kind: "found";
+            readonly accountRef: string;
+            readonly orderId: string;
+            readonly documents: readonly {
+                readonly documentRef: string;
+                readonly invoiceRef: string;
+                readonly parentDocumentRef: string | null;
+                readonly role: "original" | "correction" | "replacement";
+                readonly status: string;
+                readonly issuedAt: string | null;
+                readonly clearance: {
+                    readonly state: InvoiceClearanceObservation["state"];
+                    readonly reference: string | null;
+                } | null;
+                readonly documentKind: string | null;
+                readonly artifact: "invoice" | "correction";
+                readonly providerDocumentNumber: string | null;
+                readonly totalGrossMinor: number | null;
+                readonly currency: string;
+                readonly emailState: "not_requested" | "pending" | "provider_accepted" | "failed";
+                readonly isCurrent: boolean;
+                readonly createdAt: string;
+                readonly downloadAvailable: boolean;
+            }[];
+        } | {
+            readonly kind: "denied";
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+        resolveDownload(input: {
+            readonly accountRef: string;
+            readonly orderId: string;
+            readonly documentRef: string;
+        }): Promise<{
+            readonly kind: "authorized";
+            readonly identity: InvoiceDocumentIdentity;
+            readonly artifactRef: string;
+            readonly fileName: string;
+            readonly parentDocumentRef: string | null;
+        } | {
+            readonly kind: "denied";
+        } | {
+            readonly kind: "unknown";
+            readonly code: "unknown";
+        } | InvoiceUnsupported>;
+    };
+}
+/** Future service composition inputs only; no constructor, worker or runtime route
+ * is supplied in P1. Closures/credentials must never be serialized with options.
+ */
+export interface InvoiceServicesOptions {
+    readonly enabled?: boolean;
+    readonly selection: {
+        readonly providerRef: string;
+    } | null;
+    readonly capability: InvoiceCapabilities | null;
+    readonly provider: InvoiceProviderPort | null;
+    readonly store: InvoiceStorePort | null;
+    readonly host: InvoiceHostPorts;
+    readiness(): Promise<{
+        readonly kind: "ready";
+    } | InvoiceUnsupported>;
+}

package/dist/invoicing/contracts/host.js

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

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

@@ -0,0 +1,16 @@
+/** @consumer Frozen fact provider and installed declaration consumer. */
+export type { InvoiceFacts, InvoiceLine, InvoiceSeller, InvoiceBuyer } from "./facts.js";
+/** @consumer A4 issue/correction bridge, adapters and operator proof readback. */
+export type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceWriteResult, InvoiceReadbackResult, InvoiceProviderPort, InvoiceUnsupported, InvoiceDiagnosticCode, InvoiceProof } from "./provider.js";
+/** @consumer Host artifact storage/download binding. */
+export type { InvoiceArtifactResult, InvoiceClearanceObservation } from "./delivery.js";
+/** @consumer Host payout item recorder and resolver. */
+export type { InvoiceSettlementResult, InvoiceSettlementPort, InvoiceSettlementItem } from "./settlement.js";
+/** @consumer Explicit host selection and readInvoiceCapabilities. */
+export type { InvoiceCapabilities } from "./capabilities.js";
+/** @consumer Injected registry adapter (A5). */
+export type { InvoiceCompanyLookupPort } from "./companyLookup.js";
+/** @consumer Managed/native persistence adapter and operator duty readback; no implementation supplied. */
+export type { InvoiceStorePort, InvoiceDutyReadback } from "./store.js";
+/** @consumer Host composition and offline port-fit witnesses. */
+export type { InvoiceHostPorts, InvoiceServicesOptions } from "./host.js";

package/dist/invoicing/contracts/index.js

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

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

@@ -0,0 +1,126 @@
+import type { InvoiceFacts } from "./facts.js";
+/** Original host key bytes, immutable revision and exact lookup scope travel together.
+ * Carrier: providerPorts create options + approved exact-lookup envelope (fit probe).
+ */
+export interface InvoiceIdentity {
+    readonly providerRef: string;
+    readonly requestKey: string;
+    /** Persisted create identity from claim, distinct from original host request key. */
+    readonly providerCreateIdentity: string;
+    readonly factRevision: string;
+    readonly orderRef: string;
+    readonly invoiceRef: string;
+    readonly operation: "issue" | "full_reversal" | "remote_void";
+    readonly correctionRef: string | null;
+    readonly parentProviderDocumentRef: string | null;
+}
+/** Document rows and donor delivery/history carriers need no issue-duty metadata.
+ * @consumer Host artifacts, clearance, delivery and authorized download adapters.
+ */
+export interface InvoiceDocumentIdentity {
+    readonly providerRef: string;
+    readonly documentRef: string;
+    readonly providerDocumentRef: string | null;
+    readonly orderRef: string;
+    readonly invoiceRef: string;
+    readonly parentProviderDocumentRef: string | null;
+}
+/** A closed diagnostic allowlist in the neutral contract. Codes only.
+ * @consumer A4 bridge and provider/store adapters. */
+export type InvoiceDiagnosticCode = "faulted" | "missing_facts" | "legacy_facts_unproved" | "retryable" | "blocked" | "unsupported" | "unknown" | "absent" | "host_binding_required" | "selection_required" | "disabled" | "identity_mismatch" | "parent_mismatch" | "money_mismatch" | "money_unavailable" | "invalid_artifact" | "uncertain_delivery";
+/** Missing binding or capability: nothing written.
+ * @consumer Host and provider adapters. */
+export interface InvoiceUnsupported {
+    readonly kind: "unsupported";
+    readonly code: "host_binding_required" | "unsupported";
+    readonly retryable: false;
+    readonly effectMayHaveSucceeded: false;
+}
+/** Evidence references/fingerprints are adapter-filtered; never raw payloads or errors.
+ * @consumer Host recorder, operator readback and adapters. */
+export interface InvoiceProof {
+    readonly evidenceRef: string;
+    readonly fingerprint: string;
+    readonly observedAt: string;
+}
+/** Refused proves a definite provider refusal with no effect; post-request adapter
+ * or transport faults are unknown, even when no acknowledgement was received.
+ */
+export type InvoiceWriteResult = {
+    readonly kind: "issued";
+    readonly identity: InvoiceIdentity;
+    readonly providerDocumentRef: string;
+    readonly providerDocumentNumber: string | null;
+    readonly proof: InvoiceProof;
+    readonly replayed: boolean;
+} | {
+    readonly kind: "refused";
+    readonly identity: InvoiceIdentity;
+    readonly code: Extract<InvoiceDiagnosticCode, "blocked" | "retryable" | "missing_facts" | "identity_mismatch" | "parent_mismatch" | "money_mismatch">;
+    readonly retryable: boolean;
+    readonly effectMayHaveSucceeded: false;
+} | {
+    readonly kind: "unknown";
+    readonly identity: InvoiceIdentity;
+    readonly code: "unknown";
+    readonly effectMayHaveSucceeded: true;
+} | InvoiceUnsupported;
+/** Exact scope is the full identity, including operation, parent and revision.
+ * Incomplete/truncated/failed lookup is unknown. Only exact complete absence can
+ * authorize another create; found is proof, never a nullable lookup shortcut.
+ */
+export type InvoiceReadbackResult = {
+    readonly kind: "found";
+    readonly identity: InvoiceIdentity;
+    readonly providerDocumentRef: string;
+    readonly providerDocumentNumber: string | null;
+    readonly proof: InvoiceProof;
+} | {
+    readonly kind: "absent";
+    readonly identity: InvoiceIdentity;
+    readonly evidence: InvoiceProof & {
+        readonly exact: true;
+        readonly complete: true;
+        readonly scope: InvoiceIdentity;
+    };
+} | {
+    readonly kind: "unknown";
+    readonly identity: InvoiceIdentity;
+    readonly code: "unknown";
+} | InvoiceUnsupported;
+/** Correction bridge: positive immutable BEFORE facts, explicit zero AFTER,
+ * stable correctionRef and parent proof. Retry requires exact recovery before I/O.
+ * Carrier: donor createFullCorrection options and accountingProviderSnapshot.
+ * @consumer A4 conforming correction bridge and issue/readback adapters.
+ */
+export interface InvoiceProviderPort {
+    issue(input: {
+        readonly identity: InvoiceIdentity & {
+            readonly operation: "issue";
+            readonly correctionRef: null;
+            readonly parentProviderDocumentRef: null;
+        };
+        readonly facts: InvoiceFacts;
+        readonly recoveryLookupRequired: boolean;
+    }): Promise<InvoiceWriteResult>;
+    correct(input: {
+        readonly identity: InvoiceIdentity & {
+            readonly operation: "full_reversal";
+            readonly correctionRef: string;
+            readonly parentProviderDocumentRef: string;
+        };
+        readonly before: InvoiceFacts;
+        readonly after: {
+            readonly totalNetMinor: 0;
+            readonly totalTaxMinor: 0;
+            readonly totalGrossMinor: 0;
+        };
+        readonly reason: string;
+        readonly recoveryLookupRequired: boolean;
+    }): Promise<InvoiceWriteResult>;
+    read(input: InvoiceIdentity): Promise<InvoiceReadbackResult>;
+    /** Remote void stays cut; always refuse before I/O, never substitute local void. */
+    void(input: InvoiceIdentity & {
+        readonly operation: "remote_void";
+    }): Promise<InvoiceUnsupported>;
+}

package/dist/invoicing/contracts/provider.js

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

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 {};