@voyant-travel/finance 0.180.0 → 0.181.0

package/dist/booking-tax-runtime.js

@@ -1,5 +1,6 @@
 import { defineGraphRuntimeFactory } from "@voyant-travel/core/project";
 import { createBookingTaxPreviewApiExtension, createBookingTaxSettingsApiExtension, } from "./booking-tax.js";
+import { INVOICE_FX_SETTINGS_RUNTIME_KEY } from "./invoice-fx.js";
 import { createFinanceBookingTaxRuntime } from "./runtime.js";
 import { financeOperatorSettingsRuntimePort } from "./runtime-port.js";
 // ─────────────────────────────────────────────────────────────────
@@ -35,7 +36,8 @@ export function resolveBookingTaxRouteOptions(c, runtimeKey, fallback) {
     }
 }
 export const createBookingTaxSettingsVoyantRuntime = defineGraphRuntimeFactory(async ({ getPort }) => {
-    const options = createFinanceBookingTaxRuntime(await getPort(financeOperatorSettingsRuntimePort));
+    const settings = await getPort(financeOperatorSettingsRuntimePort);
+    const options = createFinanceBookingTaxRuntime(settings);
     const configured = createBookingTaxSettingsApiExtension(options);
     const selected = {
         ...configured,
@@ -45,6 +47,13 @@ export const createBookingTaxSettingsVoyantRuntime = defineGraphRuntimeFactory(a
                 container.register(BOOKING_TAX_SETTINGS_RUNTIME_KEY, {
                     resolveRoutesOptions: () => options,
                 });
+                // The same operator-settings port also backs invoice-FX settings, so the
+                // invoice-fx routes (in the core finance module) can persist the base
+                // currency without a separate extension/graph plugin.
+                container.register(INVOICE_FX_SETTINGS_RUNTIME_KEY, {
+                    resolveInvoiceFxSettings: settings.resolveInvoiceFxSettings,
+                    updateInvoiceFxSettings: settings.updateInvoiceFxSettings,
+                });
             },
         },
     };

package/dist/invoice-fx.d.ts

@@ -71,6 +71,16 @@ type InvoiceFxRouteEnv = Env & {
         container?: ModuleContainer;
     };
 };
+/**
+ * Container key under which the operator-settings bridge registers persistable
+ * invoice-FX settings (base currency + commission). When present, it overlays
+ * the base route runtime so `PATCH /invoice-fx-settings` can actually write.
+ */
+export declare const INVOICE_FX_SETTINGS_RUNTIME_KEY = "finance.invoiceFxSettingsRuntime";
+export interface InvoiceFxSettingsRuntime {
+    resolveInvoiceFxSettings: ResolveInvoiceFxSettings;
+    updateInvoiceFxSettings: UpdateInvoiceFxSettings;
+}
 export declare function resolveInvoiceFxSettingsOrDefault(db: PostgresJsDatabase, options?: InvoiceFxOptions): Promise<ResolvedInvoiceFxSettings>;
 export declare function resolveInvoiceFxContext(db: PostgresJsDatabase, invoice: InvoiceFxInvoice, options?: InvoiceFxOptions): Promise<InvoiceFxContext | null>;
 export declare function createVoyantDataFxExchangeRateResolver(options: VoyantDataFxResolverOptions): ResolveInvoiceExchangeRate;

package/dist/invoice-fx.js

@@ -13,10 +13,27 @@ const invoiceExchangeRateQuerySchema = z.object({
     quoteCurrency: z.string().min(3).max(8),
     date: z.string().optional(),
 });
+/**
+ * Container key under which the operator-settings bridge registers persistable
+ * invoice-FX settings (base currency + commission). When present, it overlays
+ * the base route runtime so `PATCH /invoice-fx-settings` can actually write.
+ */
+export const INVOICE_FX_SETTINGS_RUNTIME_KEY = "finance.invoiceFxSettingsRuntime";
 function getInvoiceFxRuntime(options, bindings, container) {
-    return ((container?.has(FINANCE_ROUTE_RUNTIME_CONTAINER_KEY)
+    const base = (container?.has(FINANCE_ROUTE_RUNTIME_CONTAINER_KEY)
         ? container.resolve(FINANCE_ROUTE_RUNTIME_CONTAINER_KEY)
-        : undefined) ?? buildFinanceRouteRuntime(bindings, options));
+        : undefined) ?? buildFinanceRouteRuntime(bindings, options);
+    // Overlay the operator-settings-backed resolver/updater at request time so the
+    // wiring is independent of module-bootstrap ordering.
+    if (container?.has(INVOICE_FX_SETTINGS_RUNTIME_KEY)) {
+        const settings = container.resolve(INVOICE_FX_SETTINGS_RUNTIME_KEY);
+        return {
+            ...base,
+            resolveInvoiceFxSettings: settings.resolveInvoiceFxSettings,
+            updateInvoiceFxSettings: settings.updateInvoiceFxSettings,
+        };
+    }
+    return base;
 }
 export async function resolveInvoiceFxSettingsOrDefault(db, options = {}) {
     const settings = await resolveConfiguredInvoiceFxSettings(db, options);

package/dist/reporting-definitions.d.ts

@@ -14,6 +14,7 @@ export declare const financeReceivablesDatasetDefinition: {
     requiredScopes: string[];
     defaultLimit: number;
     maximumLimit: number;
+    defaultDateField: string;
     fields: ({
         id: string;
         label: string;

package/dist/reporting-definitions.js

@@ -14,6 +14,7 @@ export const financeReceivablesDatasetDefinition = {
     requiredScopes: ["finance:read"],
     defaultLimit: 100,
     maximumLimit: 1_000,
+    defaultDateField: "issueDate",
     fields: [
         {
             id: "issueDate",

package/dist/reporting.d.ts

@@ -1,7 +1,8 @@
 import type { ReportDatasetContribution, ReportDatasetExecutionInput, ReportResult } from "@voyant-travel/reporting-contracts";
+import { ReportDatasetQueryError } from "@voyant-travel/reporting-contracts";
 import { type SQL } from "drizzle-orm";
 /** A query shape outside Finance's deliberately small reporting surface. */
-export declare class FinanceReportingQueryError extends Error {
+export declare class FinanceReportingQueryError extends ReportDatasetQueryError {
     constructor(message: string);
 }
 /**

package/dist/reporting.js

@@ -1,3 +1,4 @@
+import { ReportDatasetQueryError } from "@voyant-travel/reporting-contracts";
 import { hasApiKeyPermission, permissionStringsToPermissions } from "@voyant-travel/types/api-keys";
 import { sql } from "drizzle-orm";
 import { FINANCE_RECEIVABLES_DATASET_ID, financeReceivablesDatasetDefinition, } from "./reporting-definitions.js";
@@ -74,8 +75,67 @@ const semanticReceivables = sql `
   WHERE invoice.invoice_type = 'invoice'
     AND invoice.status IN ('issued', 'partially_paid', 'paid', 'overdue')
 `;
+/** Reserved report parameter that switches money measures to the operator base currency. */
+const REPORT_CURRENCY_PARAM = "reportCurrency";
+const BASE_CURRENCY_MODE = "base";
+/**
+ * Base-currency variant of {@link semanticReceivables}. Every monetary figure is
+ * read from the record's persisted base-currency snapshot (`base_*_cents`), which
+ * was converted at the moment the record was created using that day's FX rate set
+ * — so aggregating across documents is exact and recording-time accurate. Records
+ * without an FX snapshot (base currency/amount unset) are excluded rather than
+ * silently counted at parity.
+ */
+const baseReceivables = sql `
+  SELECT
+    invoice.issue_date AS "issueDate",
+    invoice.due_date AS "dueDate",
+    invoice.status::text AS status,
+    invoice.base_currency AS currency,
+    invoice.base_total_cents::bigint AS "grossIssuedCents",
+    credit_totals.credited_cents::bigint AS "creditedCents",
+    greatest(invoice.base_total_cents::bigint - credit_totals.credited_cents, 0) AS "netIssuedCents",
+    payment_totals.settled_cents::bigint AS "settledCents",
+    payment_totals.refunded_cents::bigint AS "refundedCents",
+    greatest(
+      invoice.base_total_cents::bigint
+        - credit_totals.credited_cents
+        - payment_totals.settled_cents,
+      0
+    ) AS "outstandingBalanceCents"
+  FROM invoices invoice
+  LEFT JOIN LATERAL (
+    SELECT coalesce(sum(credit.base_amount_cents), 0)::bigint AS credited_cents
+    FROM credit_notes credit
+    WHERE credit.invoice_id = invoice.id
+      AND credit.status IN ('issued', 'applied')
+      AND credit.base_amount_cents IS NOT NULL
+  ) credit_totals ON true
+  LEFT JOIN LATERAL (
+    SELECT
+      coalesce(
+        sum(
+          CASE WHEN payment.status = 'completed' THEN payment.base_amount_cents ELSE 0 END
+        ),
+        0
+      )::bigint AS settled_cents,
+      coalesce(
+        sum(
+          CASE WHEN payment.status = 'refunded' THEN payment.base_amount_cents ELSE 0 END
+        ),
+        0
+      )::bigint AS refunded_cents
+    FROM payments payment
+    WHERE payment.invoice_id = invoice.id
+      AND payment.base_amount_cents IS NOT NULL
+  ) payment_totals ON true
+  WHERE invoice.invoice_type = 'invoice'
+    AND invoice.status IN ('issued', 'partially_paid', 'paid', 'overdue')
+    AND invoice.base_currency IS NOT NULL
+    AND invoice.base_total_cents IS NOT NULL
+`;
 /** A query shape outside Finance's deliberately small reporting surface. */
-export class FinanceReportingQueryError extends Error {
+export class FinanceReportingQueryError extends ReportDatasetQueryError {
     constructor(message) {
         super(message);
         this.name = "FinanceReportingQueryError";
@@ -88,6 +148,9 @@ export class FinanceReportingQueryError extends Error {
  */
 export function compileFinanceReceivablesQuery(input) {
     const { query, parameters } = input;
+    // Page-level "show in base currency": read money from recording-time base
+    // snapshots so every amount is already in one currency (the operator base).
+    const baseMode = parameters[REPORT_CURRENCY_PARAM] === BASE_CURRENCY_MODE;
     if (!Number.isInteger(input.maximumRows) || input.maximumRows < 1) {
         throw new FinanceReportingQueryError("maximumRows must be a positive integer.");
     }
@@ -173,7 +236,8 @@ export function compileFinanceReceivablesQuery(input) {
     const currencyIsExplicit = aggregateQuery
         ? groups.has("currency")
         : query.select.some((selection) => selection.kind === "field" && selection.field === "currency");
-    if (moneySelections.length > 0 &&
+    if (!baseMode &&
+        moneySelections.length > 0 &&
         !currencyIsExplicit &&
         !hasSingleCurrencyFilter(query, parameters)) {
         throw new FinanceReportingQueryError("Currency measures must include or group by currency, or be filtered to exactly one currency.");
@@ -190,7 +254,7 @@ export function compileFinanceReceivablesQuery(input) {
     const rowLimit = Math.min(query.limit ?? input.maximumRows, input.maximumRows);
     return {
         statement: sql `
-      WITH receivable AS (${semanticReceivables})
+      WITH receivable AS (${baseMode ? baseReceivables : semanticReceivables})
       SELECT ${selectSql}
       FROM receivable
       ${filters.length ? sql `WHERE ${sql.join(filters, sql ` AND `)}` : sql ``}

package/dist/runtime-port.d.ts

@@ -4,6 +4,7 @@ import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { BookingTaxRouteOptions } from "./booking-tax.js";
 import type { CheckoutRoutesOptions } from "./checkout-routes.js";
 import type { CheckoutPaymentStarter } from "./checkout-service.js";
+import type { ResolveInvoiceFxSettings, UpdateInvoiceFxSettings } from "./invoice-fx.js";
 import type { PaymentPolicy } from "./payment-policy.js";
 import type { PaymentPolicyEntityContext } from "./payment-policy-cascade.js";
 import type { BookingScheduleRoutesOptions } from "./payment-schedule/routes.js";
@@ -24,6 +25,10 @@ export interface FinanceOperatorSettingsRuntime {
      * settled proforma should be auto-converted to a fiscal invoice.
      */
     resolveInvoicingMode: (db: PostgresJsDatabase) => Promise<"direct" | "proforma-first">;
+    /** Resolve the operator's invoice-FX settings (base currency, commission). */
+    resolveInvoiceFxSettings: ResolveInvoiceFxSettings;
+    /** Persist the operator's invoice-FX settings. */
+    updateInvoiceFxSettings: UpdateInvoiceFxSettings;
 }
 export interface FinanceNotificationsRuntime {
     resolveNotificationDispatcher: NonNullable<CheckoutRoutesOptions["resolveNotificationDispatcher"]>;

package/dist/runtime-port.js

@@ -20,6 +20,8 @@ export const financeOperatorSettingsRuntimePort = objectPort("finance.operator-s
     "resolveBookingTaxSettings",
     "updateBookingTaxSettings",
     "resolveInvoicingMode",
+    "resolveInvoiceFxSettings",
+    "updateInvoiceFxSettings",
 ]);
 export const financeNotificationsRuntimePort = objectPort("finance.notifications.runtime", ["resolveNotificationDispatcher", "listBookingReminderRuns"]);
 export const financeFxReferenceRuntimePort = objectPort("finance.fx-reference.runtime", ["resolveReferenceRate"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/finance",
-  "version": "0.180.0",
+  "version": "0.181.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -157,15 +157,15 @@
     "hono": "^4.12.27",
     "zod": "^4.4.3",
     "@voyant-travel/action-ledger": "^0.111.9",
-    "@voyant-travel/bookings": "^0.180.0",
+    "@voyant-travel/bookings": "^0.181.0",
     "@voyant-travel/core": "^0.130.0",
-    "@voyant-travel/db": "^0.117.0",
+    "@voyant-travel/db": "^0.117.1",
     "@voyant-travel/types": "^0.109.8",
-    "@voyant-travel/finance-contracts": "^0.107.0",
+    "@voyant-travel/finance-contracts": "^0.107.1",
     "@voyant-travel/hono": "^0.131.2",
-    "@voyant-travel/payments": "^0.2.6",
+    "@voyant-travel/payments": "^0.3.0",
     "@voyant-travel/public-document-delivery": "^0.4.8",
-    "@voyant-travel/reporting-contracts": "^0.2.1",
+    "@voyant-travel/reporting-contracts": "^0.3.0",
     "@voyant-travel/storage": "^0.111.6",
     "@voyant-travel/utils": "^0.108.0",
     "@voyant-travel/tools": "^0.3.0"