@voyantjs/finance 0.3.0 → 0.4.0

package/dist/service-settlement.d.ts

@@ -0,0 +1,36 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { Invoice as FinanceInvoice, InvoiceExternalRef } from "./schema.js";
+import type { PolledInvoiceSettlementResult, PollInvoiceSettlementInput } from "./validation.js";
+type SettlementInvoice = FinanceInvoice;
+type SettlementExternalRef = InvoiceExternalRef;
+export interface InvoiceSettlementPollerContext {
+    db: PostgresJsDatabase;
+    invoice: SettlementInvoice;
+    externalRef: SettlementExternalRef;
+    bindings: Record<string, unknown>;
+}
+export interface InvoiceSettlementPollerResult {
+    externalId?: string | null;
+    externalNumber?: string | null;
+    externalUrl?: string | null;
+    status?: string | null;
+    paidAmountCents?: number | null;
+    unpaidAmountCents?: number | null;
+    syncedAt?: string | Date | null;
+    settledAt?: string | Date | null;
+    referenceNumber?: string | null;
+    syncError?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export type InvoiceSettlementPoller = (context: InvoiceSettlementPollerContext) => Promise<InvoiceSettlementPollerResult>;
+export interface FinanceSettlementRuntimeOptions {
+    bindings?: Record<string, unknown>;
+    invoiceSettlementPollers?: Record<string, InvoiceSettlementPoller>;
+}
+export declare const financeSettlementService: {
+    pollInvoiceSettlement(db: PostgresJsDatabase, invoiceId: string, input: PollInvoiceSettlementInput, runtime?: FinanceSettlementRuntimeOptions): Promise<PolledInvoiceSettlementResult | {
+        status: "not_found";
+    }>;
+};
+export {};
+//# sourceMappingURL=service-settlement.d.ts.map

package/dist/service-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-settlement.d.ts","sourceRoot":"","sources":["../src/service-settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,KAAK,EAAE,OAAO,IAAI,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhF,OAAO,KAAK,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AAEhG,KAAK,iBAAiB,GAAG,cAAc,CAAA;AACvC,KAAK,qBAAqB,GAAG,kBAAkB,CAAA;AAE/C,MAAM,WAAW,8BAA8B;IAC7C,EAAE,EAAE,kBAAkB,CAAA;IACtB,OAAO,EAAE,iBAAiB,CAAA;IAC1B,WAAW,EAAE,qBAAqB,CAAA;IAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,6BAA6B;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAChC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,8BAA8B,KACpC,OAAO,CAAC,6BAA6B,CAAC,CAAA;AAE3C,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAA;CACnE;AAyED,eAAO,MAAM,wBAAwB;8BAE7B,kBAAkB,aACX,MAAM,SACV,0BAA0B,YACxB,+BAA+B,GACvC,OAAO,CAAC,6BAA6B,GAAG;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC;CAwIpE,CAAA"}

package/dist/service-settlement.js

@@ -0,0 +1,172 @@
+import { financeService } from "./service.js";
+function coerceRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function toIsoString(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+function normalizeMoney(value) {
+    if (typeof value !== "number" || Number.isNaN(value))
+        return null;
+    return Math.round(value);
+}
+function resolveReferenceNumber(input, pollResult, externalRef, invoice) {
+    return (input.referenceNumber ??
+        pollResult.referenceNumber ??
+        pollResult.externalNumber ??
+        pollResult.externalId ??
+        externalRef.externalNumber ??
+        externalRef.externalId ??
+        invoice.invoiceNumber);
+}
+function resolvePaymentDate(input, pollResult) {
+    return (input.paymentDate ??
+        toIsoString(pollResult.settledAt) ??
+        toIsoString(pollResult.syncedAt) ??
+        new Date().toISOString());
+}
+async function synchronizeExternalRef(db, invoiceId, externalRef, pollResult) {
+    const syncedAt = toIsoString(pollResult.syncedAt) ?? new Date().toISOString();
+    const row = await financeService.registerInvoiceExternalRef(db, invoiceId, {
+        provider: externalRef.provider,
+        externalId: pollResult.externalId ?? externalRef.externalId ?? null,
+        externalNumber: pollResult.externalNumber ?? externalRef.externalNumber ?? null,
+        externalUrl: pollResult.externalUrl ?? externalRef.externalUrl ?? null,
+        status: pollResult.status ?? externalRef.status ?? null,
+        metadata: pollResult.metadata ?? coerceRecord(externalRef.metadata) ?? null,
+        syncedAt,
+        syncError: pollResult.syncError ?? null,
+    });
+    return {
+        row,
+        syncedAt,
+    };
+}
+export const financeSettlementService = {
+    async pollInvoiceSettlement(db, invoiceId, input, runtime = {}) {
+        let invoice = await financeService.getInvoiceById(db, invoiceId);
+        if (!invoice) {
+            return { status: "not_found" };
+        }
+        const externalRefs = await financeService.listInvoiceExternalRefs(db, invoiceId);
+        const refsToPoll = input.provider
+            ? externalRefs.filter((externalRef) => externalRef.provider === input.provider)
+            : externalRefs;
+        const results = [];
+        for (const externalRef of refsToPoll) {
+            const poller = runtime.invoiceSettlementPollers?.[externalRef.provider];
+            if (!poller) {
+                const synced = await synchronizeExternalRef(db, invoice.id, externalRef, {
+                    syncError: "No settlement poller configured",
+                });
+                results.push({
+                    provider: externalRef.provider,
+                    externalRefId: synced.row?.id ?? externalRef.id,
+                    externalId: synced.row?.externalId ?? externalRef.externalId ?? null,
+                    externalNumber: synced.row?.externalNumber ?? externalRef.externalNumber ?? null,
+                    externalUrl: synced.row?.externalUrl ?? externalRef.externalUrl ?? null,
+                    status: synced.row?.status ?? externalRef.status ?? null,
+                    paidAmountCents: null,
+                    unpaidAmountCents: null,
+                    syncedAt: toIsoString(synced.row?.syncedAt) ?? synced.syncedAt,
+                    settledAt: null,
+                    createdPaymentId: null,
+                    newlyAppliedAmountCents: 0,
+                    syncError: synced.row?.syncError ?? "No settlement poller configured",
+                });
+                continue;
+            }
+            try {
+                const pollResult = await poller({
+                    db,
+                    invoice,
+                    externalRef,
+                    bindings: runtime.bindings ?? {},
+                });
+                const synced = await synchronizeExternalRef(db, invoice.id, externalRef, pollResult);
+                const paidAmountCents = normalizeMoney(pollResult.paidAmountCents);
+                const unpaidAmountCents = normalizeMoney(pollResult.unpaidAmountCents);
+                let newlyAppliedAmountCents = 0;
+                let createdPaymentId = null;
+                if (input.reconcilePayment && paidAmountCents !== null) {
+                    const cappedPaidAmountCents = Math.min(invoice.totalCents, Math.max(0, paidAmountCents));
+                    const outstandingAmountCents = Math.max(0, invoice.totalCents - invoice.paidCents);
+                    newlyAppliedAmountCents = Math.min(outstandingAmountCents, Math.max(0, cappedPaidAmountCents - invoice.paidCents));
+                    if (newlyAppliedAmountCents > 0) {
+                        const payment = await financeService.createPayment(db, invoice.id, {
+                            amountCents: newlyAppliedAmountCents,
+                            currency: invoice.currency,
+                            baseCurrency: invoice.baseCurrency ?? null,
+                            baseAmountCents: invoice.baseCurrency && invoice.baseCurrency === invoice.currency
+                                ? newlyAppliedAmountCents
+                                : null,
+                            fxRateSetId: invoice.fxRateSetId ?? null,
+                            paymentMethod: input.paymentMethod,
+                            paymentInstrumentId: null,
+                            paymentAuthorizationId: null,
+                            paymentCaptureId: null,
+                            status: "completed",
+                            referenceNumber: resolveReferenceNumber(input, pollResult, externalRef, invoice),
+                            paymentDate: resolvePaymentDate(input, pollResult),
+                            notes: input.notes ??
+                                `Settlement reconciled from ${externalRef.provider} external reference`,
+                        });
+                        createdPaymentId = payment?.id ?? null;
+                        invoice = (await financeService.getInvoiceById(db, invoice.id)) ?? invoice;
+                    }
+                }
+                results.push({
+                    provider: externalRef.provider,
+                    externalRefId: synced.row?.id ?? externalRef.id,
+                    externalId: synced.row?.externalId ?? externalRef.externalId ?? null,
+                    externalNumber: synced.row?.externalNumber ?? externalRef.externalNumber ?? null,
+                    externalUrl: synced.row?.externalUrl ?? externalRef.externalUrl ?? null,
+                    status: synced.row?.status ?? externalRef.status ?? null,
+                    paidAmountCents,
+                    unpaidAmountCents,
+                    syncedAt: toIsoString(synced.row?.syncedAt) ?? synced.syncedAt,
+                    settledAt: toIsoString(pollResult.settledAt),
+                    createdPaymentId,
+                    newlyAppliedAmountCents,
+                    syncError: synced.row?.syncError ?? pollResult.syncError ?? null,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Settlement polling failed";
+                const synced = await synchronizeExternalRef(db, invoice.id, externalRef, {
+                    syncError: message,
+                });
+                results.push({
+                    provider: externalRef.provider,
+                    externalRefId: synced.row?.id ?? externalRef.id,
+                    externalId: synced.row?.externalId ?? externalRef.externalId ?? null,
+                    externalNumber: synced.row?.externalNumber ?? externalRef.externalNumber ?? null,
+                    externalUrl: synced.row?.externalUrl ?? externalRef.externalUrl ?? null,
+                    status: synced.row?.status ?? externalRef.status ?? null,
+                    paidAmountCents: null,
+                    unpaidAmountCents: null,
+                    syncedAt: toIsoString(synced.row?.syncedAt) ?? synced.syncedAt,
+                    settledAt: null,
+                    createdPaymentId: null,
+                    newlyAppliedAmountCents: 0,
+                    syncError: synced.row?.syncError ?? message,
+                });
+            }
+        }
+        invoice = (await financeService.getInvoiceById(db, invoice.id)) ?? invoice;
+        return {
+            invoiceId: invoice.id,
+            invoiceStatus: invoice.status,
+            paidCents: invoice.paidCents,
+            balanceDueCents: invoice.balanceDueCents,
+            results,
+        };
+    },
+};