@voyant-travel/finance 0.119.5

package/dist/service-reports.d.ts

@@ -0,0 +1,37 @@
+import type { AgingReportQuery, PostgresJsDatabase, ProfitabilityQuery, RevenueReportQuery } from "./service-shared.js";
+export declare const financeReportService: {
+    getRevenueReport(db: PostgresJsDatabase, query: RevenueReportQuery): Omit<import("drizzle-orm/pg-core").PgSelectBase<"invoices", {
+        month: import("drizzle-orm").SQL<string>;
+        totalCents: import("drizzle-orm").SQL<number>;
+        count: import("drizzle-orm").SQL<number>;
+    }, "partial", Record<"invoices", "not-null">, false, "where" | "groupBy" | "orderBy", {
+        month: string;
+        totalCents: number;
+        count: number;
+    }[], {
+        month: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+        totalCents: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+        count: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+    }>, "where" | "groupBy" | "orderBy">;
+    getAgingReport(db: PostgresJsDatabase, query: AgingReportQuery): Omit<import("drizzle-orm/pg-core").PgSelectBase<"invoices", {
+        bucket: import("drizzle-orm").SQL<string>;
+        totalCents: import("drizzle-orm").SQL<number>;
+        count: import("drizzle-orm").SQL<number>;
+    }, "partial", Record<"invoices", "not-null">, false, "where" | "groupBy", {
+        bucket: string;
+        totalCents: number;
+        count: number;
+    }[], {
+        bucket: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+        totalCents: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+        count: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
+    }>, "where" | "groupBy">;
+    getProfitabilityReport(db: PostgresJsDatabase, query: ProfitabilityQuery): Promise<{
+        bookingId: string;
+        bookingNumber: string;
+        sellAmountCents: number | null;
+        costAmountCents: number | null;
+        marginPercent: number | null;
+    }[]>;
+};
+//# sourceMappingURL=service-reports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-reports.d.ts","sourceRoot":"","sources":["../src/service-reports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,qBAAqB,CAAA;AAG5B,eAAO,MAAM,oBAAoB;yBACV,kBAAkB,SAAS,kBAAkB;;;;;;;;;;;;;uBAiB/C,kBAAkB,SAAS,gBAAgB;;;;;;;;;;;;;+BA8B7B,kBAAkB,SAAS,kBAAkB;mBAsB/D,MAAM;uBACF,MAAM;yBACJ,MAAM,GAAG,IAAI;yBACb,MAAM,GAAG,IAAI;uBACf,MAAM,GAAG,IAAI;;CAGjC,CAAA"}

package/dist/service-reports.js

@@ -0,0 +1,62 @@
+import { and, asc, bookings, gte, invoices, lte, sql } from "./service-shared.js";
+export const financeReportService = {
+    getRevenueReport(db, query) {
+        return (db
+            .select({
+            month: sql `to_char(date_trunc('month', ${invoices.issueDate}::date), 'YYYY-MM')`,
+            totalCents: sql `coalesce(sum(${invoices.totalCents}), 0)::int`,
+            count: sql `count(*)::int`,
+        })
+            .from(invoices)
+            .where(and(gte(invoices.issueDate, query.from), lte(invoices.issueDate, query.to)))
+            // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+            .groupBy(sql `date_trunc('month', ${invoices.issueDate}::date)`)
+            // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+            .orderBy(sql `date_trunc('month', ${invoices.issueDate}::date)`));
+    },
+    getAgingReport(db, query) {
+        const asOf = query.asOf ?? new Date().toISOString().slice(0, 10);
+        return db
+            .select({
+            bucket: sql `
+          case
+            when ${invoices.dueDate}::date >= ${asOf}::date then 'current'
+            when ${asOf}::date - ${invoices.dueDate}::date <= 30 then '1-30'
+            when ${asOf}::date - ${invoices.dueDate}::date <= 60 then '31-60'
+            when ${asOf}::date - ${invoices.dueDate}::date <= 90 then '61-90'
+            else '90+'
+          end`,
+            totalCents: sql `coalesce(sum(${invoices.balanceDueCents}), 0)::int`,
+            count: sql `count(*)::int`,
+        })
+            .from(invoices)
+            .where(and(
+        // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+        sql `${invoices.balanceDueCents} > 0`, 
+        // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+        sql `${invoices.status} != 'void'`, 
+        // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+        sql `${invoices.status} != 'paid'`))
+            .groupBy(sql `1`);
+    },
+    async getProfitabilityReport(db, query) {
+        const conditions = [];
+        if (query.from) {
+            conditions.push(gte(bookings.startDate, query.from));
+        }
+        if (query.to) {
+            conditions.push(lte(bookings.startDate, query.to));
+        }
+        return (await db
+            .select({
+            bookingId: bookings.id,
+            bookingNumber: bookings.bookingNumber,
+            sellAmountCents: bookings.sellAmountCents,
+            costAmountCents: bookings.costAmountCents,
+            marginPercent: bookings.marginPercent,
+        })
+            .from(bookings)
+            .where(conditions.length > 0 ? and(...conditions) : undefined)
+            .orderBy(asc(bookings.startDate), asc(bookings.createdAt)));
+    },
+};

package/dist/service-settlement.d.ts

@@ -0,0 +1,46 @@
+import type { EventBus } from "@voyant-travel/core";
+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>;
+    eventBus?: EventBus;
+}
+export interface InvoiceSettledEvent {
+    invoiceId: string;
+    paymentId: string;
+    provider: string;
+    newlyAppliedAmountCents: number;
+    paidCents: number;
+    balanceDueCents: number;
+}
+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,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,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;IAClE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;CACxB;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;CA0JpE,CAAA"}

package/dist/service-settlement.js

@@ -0,0 +1,185 @@
+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;
+                        if (createdPaymentId) {
+                            await runtime.eventBus?.emit("invoice.settled", {
+                                invoiceId: invoice.id,
+                                paymentId: createdPaymentId,
+                                provider: externalRef.provider,
+                                newlyAppliedAmountCents,
+                                paidCents: invoice.paidCents,
+                                balanceDueCents: invoice.balanceDueCents,
+                            }, {
+                                category: "domain",
+                                source: "service",
+                            });
+                        }
+                    }
+                }
+                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,
+        };
+    },
+};