@openlup/platform 0.23.0 → 0.24.0

package/dist/invoicing/settlementSync.d.ts

@@ -0,0 +1,18 @@
+import type { InvoiceSettlementPort, InvoiceSettlementItem } from "./contracts/settlement.js";
+/** Preserve each immutable balance item, nullable links and original host key.
+ * Transport, resolution and richer durable item storage remain host-owned.
+ * Legacy batch/payment receipts may collapse items: later reuse is returned as
+ * identity_mismatch without another write; processing continues. Only an item-capable
+ * recorder can produce distinct recorded receipts. This records bank evidence only and has no payment-success writer.
+ */
+export declare function syncInvoicePayoutSettlements<Item>(input: {
+    list(limit: number): Promise<readonly Item[]>;
+    project(item: Item): InvoiceSettlementItem | Promise<InvoiceSettlementItem>;
+    settlement: Pick<InvoiceSettlementPort, "record">;
+    limit?: number;
+}): Promise<{
+    checked: number;
+    recorded: number;
+    replayed: number;
+    items: Awaited<ReturnType<InvoiceSettlementPort["record"]>>[];
+}>;

package/dist/invoicing/settlementSync.js

@@ -0,0 +1,32 @@
+/** Preserve each immutable balance item, nullable links and original host key.
+ * Transport, resolution and richer durable item storage remain host-owned.
+ * Legacy batch/payment receipts may collapse items: later reuse is returned as
+ * identity_mismatch without another write; processing continues. Only an item-capable
+ * recorder can produce distinct recorded receipts. This records bank evidence only and has no payment-success writer.
+ */
+export async function syncInvoicePayoutSettlements(input) {
+    const items = await input.list(input.limit ?? 10);
+    const result = { checked: items.length, recorded: 0, replayed: 0, items: [] };
+    const receipts = new Map();
+    for (const item of items) {
+        const evidence = await input.project(item);
+        const write = await input.settlement.record(evidence);
+        if (write.kind !== "recorded" || write.itemRef !== evidence.itemRef) {
+            // Unknown/conflict/unsupported are never counted as accepted evidence.
+            throw new Error(write.kind === "conflict" ? write.code : write.kind === "unknown" ? "unknown" : "unsupported");
+        }
+        const scope = JSON.stringify([evidence.providerRef, evidence.batchRef, evidence.itemRef, evidence.providerPaymentRef]);
+        const previous = receipts.get(write.settlementItemRef);
+        if (previous !== undefined && previous !== scope) {
+            result.items.push({ kind: "conflict", itemRef: evidence.itemRef, code: "identity_mismatch" });
+            continue;
+        }
+        receipts.set(write.settlementItemRef, scope);
+        result.items.push(write);
+        if (write.replayed)
+            result.replayed += 1;
+        else
+            result.recorded += 1;
+    }
+    return result;
+}

package/dist/invoicing/snapshot.d.ts

@@ -0,0 +1,52 @@
+interface Options {
+    defaultLineLabel: string;
+    deliveryLabel: string;
+    defaultTaxRate: string;
+}
+/** Compatibility projection of a claimed host snapshot, not a second store contract.
+ * Seller/date/kind/payment selection remains with the host; no environment is read.
+ */
+export declare function mapInvoiceClaimToProviderSnapshot<Seller, Kind, Payment>(input: {
+    orderRef: string;
+    issueDate: string;
+    sellDate: string;
+    currency: string;
+    seller: Seller;
+    buyerSnapshot: Record<string, unknown>;
+    documentKind: Kind;
+    governmentClearanceRequired: boolean;
+    payment: Payment;
+    linesSnapshot: unknown[];
+    totalGrossMinor: number;
+    totalNetMinor: number;
+    orderMoney: unknown;
+}, options: Options & {
+    defaultBuyerLabel: string;
+}): {
+    orderRef: string;
+    issueDate: string;
+    sellDate: string;
+    currency: string;
+    seller: Seller;
+    buyer: {
+        name: string;
+        email: string | null;
+        taxId: string | null;
+        companyName: string | null;
+        address: {
+            readonly line1: string | null;
+            readonly postalCode: string | null;
+            readonly city: string | null;
+            readonly country: string | null;
+        };
+    };
+    documentKind: Kind;
+    governmentClearanceRequired: boolean;
+    payment: Payment;
+    lines: (Pick<import("./contracts/facts.js").InvoiceLine, "quantity" | "unitGrossMinor" | "unitNetMinor" | "totalGrossMinor" | "totalNetMinor"> & {
+        name: string;
+        vatRate: string;
+    })[];
+    chargedTotalGrossMinor: number;
+};
+export {};

package/dist/invoicing/snapshot.js

@@ -0,0 +1,141 @@
+import { mapCanonicalIssueLines } from "./accountingCanonicalProviderLines.js";
+import { allocateChargedGrossTotals } from "./accountingLineAllocation.js";
+/** Compatibility projection of a claimed host snapshot, not a second store contract.
+ * Seller/date/kind/payment selection remains with the host; no environment is read.
+ */
+export function mapInvoiceClaimToProviderSnapshot(input, options) {
+    return {
+        orderRef: input.orderRef,
+        issueDate: input.issueDate,
+        sellDate: input.sellDate,
+        currency: input.currency,
+        seller: input.seller,
+        buyer: {
+            name: textValue(input.buyerSnapshot.name) ?? options.defaultBuyerLabel,
+            email: textValue(input.buyerSnapshot.email),
+            taxId: textValue(input.buyerSnapshot.taxId),
+            companyName: textValue(input.buyerSnapshot.companyName),
+            address: mapBuyerAddress(input.buyerSnapshot.address),
+        },
+        documentKind: input.documentKind,
+        governmentClearanceRequired: input.governmentClearanceRequired,
+        payment: input.payment,
+        lines: mapIssueLinesToChargedTotal(input.linesSnapshot, input.totalGrossMinor, input.totalNetMinor, input.orderMoney, options),
+        chargedTotalGrossMinor: input.totalGrossMinor,
+    };
+}
+// Canonical issue snapshots already carry effective item and explicit delivery
+// positions and are verified as a zero-delta passthrough. Historical snapshots
+// without positionKind retain the independent #1693 reconciliation below.
+function mapIssueLinesToChargedTotal(linesSnapshot, chargedTotalGrossMinor, chargedTotalNetMinor, orderMoney, options) {
+    const canonicalKinds = linesSnapshot.map((line) => textValue(isRecord(line) ? line.positionKind : null));
+    if (canonicalKinds.some(Boolean)) {
+        if (!canonicalKinds.every((kind) => kind === "item" || kind === "delivery")) {
+            throw new Error("accounting_invoice_canonical_positions_mixed_or_invalid");
+        }
+        return mapCanonicalIssueLines(linesSnapshot, chargedTotalGrossMinor, chargedTotalNetMinor, options.defaultLineLabel);
+    }
+    const parsed = linesSnapshot.map((line) => parseLineSnapshot(line, options));
+    const deliveryGrossMinor = readDeliveryGrossMinor(orderMoney, chargedTotalGrossMinor);
+    const chargedTotals = allocateChargedGrossTotals(parsed.map((line) => line.totalGrossMinor), chargedTotalGrossMinor - deliveryGrossMinor);
+    const positions = parsed.map((line, index) => {
+        const totalGrossMinor = chargedTotals[index];
+        const totalNetMinor = estimateNetMinor(totalGrossMinor, line.vatRate);
+        return {
+            name: line.name,
+            quantity: line.quantity,
+            unitGrossMinor: Math.round(totalGrossMinor / line.quantity),
+            unitNetMinor: Math.round(totalNetMinor / line.quantity),
+            totalGrossMinor,
+            totalNetMinor,
+            vatRate: line.vatRate,
+        };
+    });
+    if (deliveryGrossMinor > 0) {
+        positions.push(buildDeliveryPosition(deliveryGrossMinor, parsed, options));
+    }
+    return positions;
+}
+// Legacy-only compatibility: pre-canonical claims had no explicit delivery
+// position, so their effective delivery is the closed header residual. Current
+// canonical claims never enter this path and use persisted shipping columns.
+// Every inconsistent legacy shape degrades to 0 and then fails closed if the
+// catalog lines cannot reconcile to the charged header.
+function readDeliveryGrossMinor(orderMoney, chargedTotalGrossMinor) {
+    if (!isRecord(orderMoney))
+        return 0;
+    const subtotal = numberValue(orderMoney.subtotalCents);
+    const discount = numberValue(orderMoney.discountCents);
+    const total = numberValue(orderMoney.totalCents);
+    if (subtotal === null || discount === null || total === null)
+        return 0;
+    if (![subtotal, discount, total].every((value) => Number.isInteger(value) && value >= 0))
+        return 0;
+    if (discount > subtotal)
+        return 0;
+    if (total !== chargedTotalGrossMinor)
+        return 0;
+    const deliveryGrossMinor = chargedTotalGrossMinor - (subtotal - discount);
+    return deliveryGrossMinor > 0 ? deliveryGrossMinor : 0;
+}
+// Delivery is an ancillary supply and follows the goods' VAT rate; with mixed
+// item rates (or no item line to source a rate from) the correct rate is
+// ambiguous, so the claim fails closed into the outbox last_error.
+function buildDeliveryPosition(deliveryGrossMinor, itemLines, options) {
+    const rates = [...new Set(itemLines.map((line) => line.vatRate.trim()))];
+    if (rates.length === 0) {
+        throw new Error(`accounting_invoice_delivery_vat_rate_unavailable delivery=${deliveryGrossMinor}`);
+    }
+    if (rates.length > 1) {
+        throw new Error(`accounting_invoice_delivery_vat_rates_mixed rates=${rates.join(",")}`);
+    }
+    const vatRate = rates[0];
+    const totalNetMinor = estimateNetMinor(deliveryGrossMinor, vatRate);
+    return {
+        name: options.deliveryLabel,
+        quantity: 1,
+        unitGrossMinor: deliveryGrossMinor,
+        unitNetMinor: totalNetMinor,
+        totalGrossMinor: deliveryGrossMinor,
+        totalNetMinor,
+        vatRate,
+    };
+}
+function mapBuyerAddress(value) {
+    const address = isRecord(value) ? value : {};
+    return {
+        line1: textValue(address.line1),
+        postalCode: textValue(address.postalCode),
+        city: textValue(address.city),
+        country: textValue(address.country),
+    };
+}
+function parseLineSnapshot(value, options) {
+    const row = isRecord(value) ? value : {};
+    const quantity = numberValue(row.quantity) || 1;
+    const vatRate = textValue(row.vatRate) ?? options.defaultTaxRate;
+    // Legacy (pre-#1693) lines_snapshot rows carry only the per-unit
+    // unitGrossMinor, so the line total is unit price times quantity.
+    const unitGrossMinor = numberValue(row.unitGrossMinor);
+    const totalGrossMinor = numberValue(row.totalGrossMinor) ??
+        (unitGrossMinor === null ? 0 : unitGrossMinor * quantity);
+    return {
+        name: textValue(row.name) ?? options.defaultLineLabel,
+        quantity,
+        totalGrossMinor,
+        vatRate,
+    };
+}
+function estimateNetMinor(grossMinor, vatRate) {
+    const rate = Number(vatRate.replace(",", "."));
+    return Number.isFinite(rate) ? Math.round(grossMinor / (1 + rate / 100)) : grossMinor;
+}
+function textValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.23.0",
+    "@openlup/core": "0.24.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -48,7 +48,7 @@
     }
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "zod": "^4.6.6"
   },
   "exports": {
     "./http": {

package/release-gates.json

@@ -490,7 +490,21 @@
       "packageSmokeEvidence": [
         "test/packageBoundary.test.ts",
         "test/invoicing/contracts.test.ts",
-        "test/invoicing/portFit.test.ts"
+        "test/invoicing/portFit.test.ts",
+        "test/invoicing/adapterConformance.test.ts",
+        "test/invoicing/issue.test.ts",
+        "test/invoicing/canonicalLines.test.ts",
+        "test/invoicing/paymentReadback.test.ts",
+        "test/invoicing/handoff.test.ts",
+        "test/invoicing/postgresStore.test.ts",
+        "test/invoicing/continuity.test.ts",
+        "test/invoicing/artifacts.test.ts",
+        "test/invoicing/delivery.test.ts",
+        "test/invoicing/readback.test.ts",
+        "test/invoicing/settlementSync.test.ts",
+        "test/invoicing/readModel.test.ts",
+        "test/invoicing/bindings.test.ts",
+        "test/invoicing/sellerRevision.test.ts"
       ],
       "entrypoint": "dist/invoicing/index.d.ts",
       "snapshot": "api/invoicing.api.md"
@@ -510,19 +524,19 @@
   },
   "pack": {
     "code": {
-      "maxPackedBytes": 1126400,
+      "maxPackedBytes": 1228800,
       "maxFiles": 2000
     },
     "docs": {
-      "maxPackedBytes": 49152,
+      "maxPackedBytes": 57344,
       "maxFiles": 10
     },
-    "maxPackedBytes": 1351680,
-    "maxUnpackedBytes": 5734400,
+    "maxPackedBytes": 1474560,
+    "maxUnpackedBytes": 6553600,
     "maxFiles": 2100,
     "baseline": {
-      "version": "0.22.0",
-      "packedBytes": 1185082
+      "version": "0.23.0",
+      "packedBytes": 1251425
     },
     "browserEntries": {
       "./catalog/contracts": 4096,