@voyant-travel/finance 0.173.0 → 0.175.0

package/dist/reporting-definitions.d.ts

@@ -0,0 +1,310 @@
+export declare const FINANCE_RECEIVABLES_DATASET_ID = "finance.receivables";
+/**
+ * Finance-owned semantics for issued customer receivables.
+ *
+ * Amounts remain in the document currency. Consumers must group by currency
+ * or constrain a query to one currency; the executor enforces that invariant.
+ */
+export declare const financeReceivablesDatasetDefinition: {
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    grain: string;
+    requiredScopes: string[];
+    defaultLimit: number;
+    maximumLimit: number;
+    fields: ({
+        id: string;
+        label: string;
+        description: string;
+        role: "dimension";
+        valueType: "date";
+        sensitivity: "internal";
+        requiredScopes: string[];
+        aggregations: never[];
+    } | {
+        id: string;
+        label: string;
+        role: "dimension";
+        valueType: "date";
+        sensitivity: "internal";
+        requiredScopes: string[];
+        aggregations: never[];
+        description?: undefined;
+    } | {
+        id: string;
+        label: string;
+        description: string;
+        role: "dimension";
+        valueType: "string";
+        sensitivity: "internal";
+        requiredScopes: string[];
+        aggregations: ("count" | "countDistinct")[];
+    } | {
+        id: string;
+        label: string;
+        description: string;
+        role: "measure";
+        valueType: "currency";
+        sensitivity: "sensitive";
+        requiredScopes: string[];
+        aggregations: "sum"[];
+    })[];
+};
+export declare const financeReportingWidgets: ({
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    query: {
+        dataset: {
+            id: string;
+            version: number;
+        };
+        select: ({
+            kind: "field";
+            field: string;
+            operation?: undefined;
+            as?: undefined;
+        } | {
+            kind: "aggregate";
+            operation: "sum";
+            field: string;
+            as: string;
+        } | {
+            kind: "aggregate";
+            operation: "count";
+            as: string;
+            field?: undefined;
+        })[];
+        filters: never[];
+        groupBy: {
+            field: string;
+        }[];
+        orderBy: {
+            by: string;
+            direction: "descending";
+        }[];
+        limit: number;
+    };
+    visualization: {
+        type: "bar";
+        options: {
+            category: string;
+            value: string;
+            currencyField: string;
+            minorUnit: boolean;
+            x?: undefined;
+            y?: undefined;
+            series?: undefined;
+        };
+    };
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    minimumSize: {
+        width: number;
+        height: number;
+    };
+    maximumSize: {
+        width: number;
+        height: number;
+    };
+} | {
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    query: {
+        dataset: {
+            id: string;
+            version: number;
+        };
+        select: ({
+            kind: "field";
+            field: string;
+            as: string;
+            operation?: undefined;
+        } | {
+            kind: "field";
+            field: string;
+            as?: undefined;
+            operation?: undefined;
+        } | {
+            kind: "aggregate";
+            operation: "sum";
+            field: string;
+            as: string;
+        })[];
+        filters: never[];
+        groupBy: ({
+            field: string;
+            timeGrain: "month";
+        } | {
+            field: string;
+            timeGrain?: undefined;
+        })[];
+        orderBy: {
+            by: string;
+            direction: "ascending";
+        }[];
+        limit: number;
+    };
+    visualization: {
+        type: "line";
+        options: {
+            x: string;
+            y: string;
+            series: string;
+            currencyField: string;
+            minorUnit: boolean;
+            category?: undefined;
+            value?: undefined;
+        };
+    };
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    minimumSize: {
+        width: number;
+        height: number;
+    };
+    maximumSize: {
+        width: number;
+        height: number;
+    };
+} | {
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    query: {
+        dataset: {
+            id: string;
+            version: number;
+        };
+        select: ({
+            kind: "field";
+            field: string;
+            operation?: undefined;
+            as?: undefined;
+        } | {
+            kind: "aggregate";
+            operation: "count";
+            as: string;
+            field?: undefined;
+        })[];
+        filters: never[];
+        groupBy: {
+            field: string;
+        }[];
+        orderBy: {
+            by: string;
+            direction: "descending";
+        }[];
+        limit: number;
+    };
+    visualization: {
+        type: "pie";
+        options: {
+            category: string;
+            value: string;
+            currencyField?: undefined;
+            minorUnit?: undefined;
+            x?: undefined;
+            y?: undefined;
+            series?: undefined;
+        };
+    };
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    minimumSize: {
+        width: number;
+        height: number;
+    };
+    maximumSize: {
+        width: number;
+        height: number;
+    };
+} | {
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    query: {
+        dataset: {
+            id: string;
+            version: number;
+        };
+        select: ({
+            kind: "field";
+            field: string;
+            operation?: undefined;
+            as?: undefined;
+        } | {
+            kind: "aggregate";
+            operation: "sum";
+            field: string;
+            as: string;
+        })[];
+        filters: never[];
+        groupBy: {
+            field: string;
+        }[];
+        orderBy: {
+            by: string;
+            direction: "descending";
+        }[];
+        limit: number;
+    };
+    visualization: {
+        type: "table";
+        options: {
+            currencyField: string;
+            minorUnit: boolean;
+            category?: undefined;
+            value?: undefined;
+            x?: undefined;
+            y?: undefined;
+            series?: undefined;
+        };
+    };
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    minimumSize: {
+        width: number;
+        height: number;
+    };
+    maximumSize: {
+        width: number;
+        height: number;
+    };
+})[];
+export declare const financeReportingTemplates: {
+    id: string;
+    version: number;
+    label: string;
+    description: string;
+    parameters: never[];
+    widgets: {
+        id: string;
+        source: {
+            kind: "preset";
+            widgetId: string;
+            version: number;
+        };
+        layout: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }[];
+}[];

package/dist/reporting-definitions.js

@@ -0,0 +1,271 @@
+export const FINANCE_RECEIVABLES_DATASET_ID = "finance.receivables";
+/**
+ * Finance-owned semantics for issued customer receivables.
+ *
+ * Amounts remain in the document currency. Consumers must group by currency
+ * or constrain a query to one currency; the executor enforces that invariant.
+ */
+export const financeReceivablesDatasetDefinition = {
+    id: FINANCE_RECEIVABLES_DATASET_ID,
+    version: 1,
+    label: "Receivables",
+    description: "Final, non-void customer invoices with issued credit notes and completed or refunded collections attributed in the invoice currency. Proformas and draft documents are excluded.",
+    grain: "One issued, partially paid, paid, or overdue final customer invoice.",
+    requiredScopes: ["finance:read"],
+    defaultLimit: 100,
+    maximumLimit: 1_000,
+    fields: [
+        {
+            id: "issueDate",
+            label: "Issue date",
+            description: "The final invoice issue date; trends bucket this date in UTC calendar units.",
+            role: "dimension",
+            valueType: "date",
+            sensitivity: "internal",
+            requiredScopes: ["finance:read"],
+            aggregations: [],
+        },
+        {
+            id: "dueDate",
+            label: "Due date",
+            role: "dimension",
+            valueType: "date",
+            sensitivity: "internal",
+            requiredScopes: ["finance:read"],
+            aggregations: [],
+        },
+        {
+            id: "status",
+            label: "Invoice status",
+            description: "Current status of the final invoice; draft, pending allocation, and void documents are outside this dataset.",
+            role: "dimension",
+            valueType: "string",
+            sensitivity: "internal",
+            requiredScopes: ["finance:read"],
+            aggregations: ["count", "countDistinct"],
+        },
+        {
+            id: "currency",
+            label: "Document currency",
+            description: "ISO currency of the final invoice. No report-time FX conversion is applied.",
+            role: "dimension",
+            valueType: "string",
+            sensitivity: "internal",
+            requiredScopes: ["finance:read"],
+            aggregations: ["count", "countDistinct"],
+        },
+        {
+            id: "grossIssuedCents",
+            label: "Gross issued",
+            description: "Final invoice total before issued or applied credit notes, in document-currency minor units.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+        {
+            id: "creditedCents",
+            label: "Credited",
+            description: "Issued or applied credit notes converted with their persisted invoice-currency snapshot, in minor units.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+        {
+            id: "netIssuedCents",
+            label: "Net issued",
+            description: "Gross final invoice value less issued or applied credit notes, attributed to the final invoice issue date.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+        {
+            id: "settledCents",
+            label: "Settled",
+            description: "Payments whose current status is completed, converted with their persisted invoice-currency snapshot.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+        {
+            id: "refundedCents",
+            label: "Refunded",
+            description: "Payments whose current status is refunded, converted with their persisted invoice-currency snapshot.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+        {
+            id: "outstandingBalanceCents",
+            label: "Outstanding balance",
+            description: "Net issued value less currently completed payments, floored at zero, in document-currency minor units.",
+            role: "measure",
+            valueType: "currency",
+            sensitivity: "sensitive",
+            requiredScopes: ["finance:read"],
+            aggregations: ["sum"],
+        },
+    ],
+};
+export const financeReportingWidgets = [
+    {
+        id: "finance.outstanding-by-currency",
+        version: 1,
+        label: "Outstanding by currency",
+        description: "Current unpaid final-invoice balance, kept separate by document currency.",
+        query: {
+            dataset: { id: FINANCE_RECEIVABLES_DATASET_ID, version: 1 },
+            select: [
+                { kind: "field", field: "currency" },
+                {
+                    kind: "aggregate",
+                    operation: "sum",
+                    field: "outstandingBalanceCents",
+                    as: "outstandingBalanceCents",
+                },
+                { kind: "aggregate", operation: "count", as: "invoiceCount" },
+            ],
+            filters: [],
+            groupBy: [{ field: "currency" }],
+            orderBy: [{ by: "outstandingBalanceCents", direction: "descending" }],
+            limit: 20,
+        },
+        visualization: {
+            type: "bar",
+            options: {
+                category: "currency",
+                value: "outstandingBalanceCents",
+                currencyField: "currency",
+                minorUnit: true,
+            },
+        },
+        defaultSize: { width: 4, height: 3 },
+        minimumSize: { width: 3, height: 2 },
+        maximumSize: { width: 12, height: 8 },
+    },
+    {
+        id: "finance.net-issued-trend",
+        version: 1,
+        label: "Net issued trend",
+        description: "Final invoices less issued/applied credit notes, attributed to the invoice issue month and separated by currency.",
+        query: {
+            dataset: { id: FINANCE_RECEIVABLES_DATASET_ID, version: 1 },
+            select: [
+                { kind: "field", field: "issueDate", as: "issueMonth" },
+                { kind: "field", field: "currency" },
+                {
+                    kind: "aggregate",
+                    operation: "sum",
+                    field: "netIssuedCents",
+                    as: "netIssuedCents",
+                },
+            ],
+            filters: [],
+            groupBy: [{ field: "issueDate", timeGrain: "month" }, { field: "currency" }],
+            orderBy: [
+                { by: "issueMonth", direction: "ascending" },
+                { by: "currency", direction: "ascending" },
+            ],
+            limit: 240,
+        },
+        visualization: {
+            type: "line",
+            options: {
+                x: "issueMonth",
+                y: "netIssuedCents",
+                series: "currency",
+                currencyField: "currency",
+                minorUnit: true,
+            },
+        },
+        defaultSize: { width: 8, height: 3 },
+        minimumSize: { width: 4, height: 3 },
+        maximumSize: { width: 12, height: 8 },
+    },
+    {
+        id: "finance.invoice-status-breakdown",
+        version: 1,
+        label: "Final invoice status",
+        description: "Count of recognized final invoices by their current receivable status.",
+        query: {
+            dataset: { id: FINANCE_RECEIVABLES_DATASET_ID, version: 1 },
+            select: [
+                { kind: "field", field: "status" },
+                { kind: "aggregate", operation: "count", as: "invoiceCount" },
+            ],
+            filters: [],
+            groupBy: [{ field: "status" }],
+            orderBy: [{ by: "invoiceCount", direction: "descending" }],
+            limit: 10,
+        },
+        visualization: { type: "pie", options: { category: "status", value: "invoiceCount" } },
+        defaultSize: { width: 4, height: 3 },
+        minimumSize: { width: 3, height: 3 },
+        maximumSize: { width: 8, height: 8 },
+    },
+    {
+        id: "finance.collections-by-currency",
+        version: 1,
+        label: "Collections by currency",
+        description: "Currently completed and refunded customer payments attributed to final invoices.",
+        query: {
+            dataset: { id: FINANCE_RECEIVABLES_DATASET_ID, version: 1 },
+            select: [
+                { kind: "field", field: "currency" },
+                { kind: "aggregate", operation: "sum", field: "settledCents", as: "settledCents" },
+                { kind: "aggregate", operation: "sum", field: "refundedCents", as: "refundedCents" },
+            ],
+            filters: [],
+            groupBy: [{ field: "currency" }],
+            orderBy: [{ by: "settledCents", direction: "descending" }],
+            limit: 20,
+        },
+        visualization: {
+            type: "table",
+            options: { currencyField: "currency", minorUnit: true },
+        },
+        defaultSize: { width: 4, height: 3 },
+        minimumSize: { width: 4, height: 2 },
+        maximumSize: { width: 12, height: 8 },
+    },
+];
+export const financeReportingTemplates = [
+    {
+        id: "finance.overview",
+        version: 1,
+        label: "Finance overview",
+        description: "Issued value, collections, outstanding receivables, and current final-invoice status.",
+        parameters: [],
+        widgets: [
+            {
+                id: "outstanding",
+                source: { kind: "preset", widgetId: "finance.outstanding-by-currency", version: 1 },
+                layout: { x: 0, y: 0, width: 4, height: 3 },
+            },
+            {
+                id: "net-issued",
+                source: { kind: "preset", widgetId: "finance.net-issued-trend", version: 1 },
+                layout: { x: 4, y: 0, width: 8, height: 3 },
+            },
+            {
+                id: "status",
+                source: { kind: "preset", widgetId: "finance.invoice-status-breakdown", version: 1 },
+                layout: { x: 0, y: 3, width: 4, height: 3 },
+            },
+            {
+                id: "collections",
+                source: { kind: "preset", widgetId: "finance.collections-by-currency", version: 1 },
+                layout: { x: 4, y: 3, width: 8, height: 3 },
+            },
+        ],
+    },
+];

package/dist/reporting.d.ts

@@ -0,0 +1,17 @@
+import type { ReportDatasetContribution, ReportDatasetExecutionInput, ReportResult } 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 {
+    constructor(message: string);
+}
+/**
+ * Compile the public single-dataset AST to parameter-bound SQL over the
+ * Finance-owned semantic receivables relation. Only the small set implemented
+ * here is accepted; query text can never address tables or columns directly.
+ */
+export declare function compileFinanceReceivablesQuery(input: ReportDatasetExecutionInput): {
+    statement: SQL;
+    columns: ReportResult["columns"];
+    rowLimit: number;
+};
+export declare const financeReceivablesDataset: ReportDatasetContribution;

package/dist/reporting.js

@@ -0,0 +1,363 @@
+import { hasApiKeyPermission, permissionStringsToPermissions } from "@voyant-travel/types/api-keys";
+import { sql } from "drizzle-orm";
+import { FINANCE_RECEIVABLES_DATASET_ID, financeReceivablesDatasetDefinition, } from "./reporting-definitions.js";
+import { executeBoundaryRows } from "./service-boundary-sql.js";
+const MONEY_FIELDS = new Set([
+    "grossIssuedCents",
+    "creditedCents",
+    "netIssuedCents",
+    "settledCents",
+    "refundedCents",
+    "outstandingBalanceCents",
+]);
+const fieldSql = {
+    issueDate: sql `receivable."issueDate"`,
+    dueDate: sql `receivable."dueDate"`,
+    status: sql `receivable.status`,
+    currency: sql `receivable.currency`,
+    grossIssuedCents: sql `receivable."grossIssuedCents"`,
+    creditedCents: sql `receivable."creditedCents"`,
+    netIssuedCents: sql `receivable."netIssuedCents"`,
+    settledCents: sql `receivable."settledCents"`,
+    refundedCents: sql `receivable."refundedCents"`,
+    outstandingBalanceCents: sql `receivable."outstandingBalanceCents"`,
+};
+const semanticReceivables = sql `
+  SELECT
+    invoice.issue_date AS "issueDate",
+    invoice.due_date AS "dueDate",
+    invoice.status::text AS status,
+    invoice.currency,
+    invoice.total_cents::bigint AS "grossIssuedCents",
+    credit_totals.credited_cents::bigint AS "creditedCents",
+    greatest(invoice.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.total_cents::bigint
+        - credit_totals.credited_cents
+        - payment_totals.settled_cents,
+      0
+    ) AS "outstandingBalanceCents"
+  FROM invoices invoice
+  LEFT JOIN LATERAL (
+    SELECT coalesce(sum(
+      CASE
+        WHEN credit.currency = invoice.currency THEN credit.amount_cents
+        WHEN credit.base_currency = invoice.currency THEN coalesce(credit.base_amount_cents, 0)
+        ELSE 0
+      END
+    ), 0)::bigint AS credited_cents
+    FROM credit_notes credit
+    WHERE credit.invoice_id = invoice.id
+      AND credit.status IN ('issued', 'applied')
+  ) credit_totals ON true
+  LEFT JOIN LATERAL (
+    SELECT
+      coalesce(sum(CASE WHEN payment.status = 'completed' THEN
+        CASE
+          WHEN payment.currency = invoice.currency THEN payment.amount_cents
+          WHEN payment.base_currency = invoice.currency THEN coalesce(payment.base_amount_cents, 0)
+          ELSE 0
+        END
+      ELSE 0 END), 0)::bigint AS settled_cents,
+      coalesce(sum(CASE WHEN payment.status = 'refunded' THEN
+        CASE
+          WHEN payment.currency = invoice.currency THEN payment.amount_cents
+          WHEN payment.base_currency = invoice.currency THEN coalesce(payment.base_amount_cents, 0)
+          ELSE 0
+        END
+      ELSE 0 END), 0)::bigint AS refunded_cents
+    FROM payments payment
+    WHERE payment.invoice_id = invoice.id
+  ) payment_totals ON true
+  WHERE invoice.invoice_type = 'invoice'
+    AND invoice.status IN ('issued', 'partially_paid', 'paid', 'overdue')
+`;
+/** A query shape outside Finance's deliberately small reporting surface. */
+export class FinanceReportingQueryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FinanceReportingQueryError";
+    }
+}
+/**
+ * Compile the public single-dataset AST to parameter-bound SQL over the
+ * Finance-owned semantic receivables relation. Only the small set implemented
+ * here is accepted; query text can never address tables or columns directly.
+ */
+export function compileFinanceReceivablesQuery(input) {
+    const { query, parameters } = input;
+    if (!Number.isInteger(input.maximumRows) || input.maximumRows < 1) {
+        throw new FinanceReportingQueryError("maximumRows must be a positive integer.");
+    }
+    if (query.dataset.id !== FINANCE_RECEIVABLES_DATASET_ID) {
+        throw new FinanceReportingQueryError(`Unsupported dataset ${JSON.stringify(query.dataset.id)}.`);
+    }
+    if (query.dataset.version !== undefined && query.dataset.version !== 1) {
+        throw new FinanceReportingQueryError(`Unsupported receivables dataset version ${query.dataset.version}.`);
+    }
+    const definitions = new Map(financeReceivablesDatasetDefinition.fields.map((field) => [field.id, field]));
+    const groups = new Map();
+    for (const group of query.groupBy) {
+        const field = requireField(definitions, group.field);
+        if (field.role !== "dimension") {
+            throw new FinanceReportingQueryError(`Cannot group by measure ${JSON.stringify(group.field)}.`);
+        }
+        if (groups.has(group.field)) {
+            throw new FinanceReportingQueryError(`Duplicate group ${JSON.stringify(group.field)}.`);
+        }
+        if (group.timeGrain && field.valueType !== "date" && field.valueType !== "datetime") {
+            throw new FinanceReportingQueryError(`Time grain is not valid for ${JSON.stringify(group.field)}.`);
+        }
+        groups.set(group.field, group);
+    }
+    const aggregateQuery = query.select.some((selection) => selection.kind === "aggregate");
+    const selections = query.select.map((selection) => {
+        if (selection.kind === "field") {
+            const field = requireField(definitions, selection.field);
+            if (aggregateQuery && !groups.has(field.id)) {
+                throw new FinanceReportingQueryError(`Selected field ${JSON.stringify(field.id)} must appear in groupBy.`);
+            }
+            const id = selection.as ?? field.id;
+            return {
+                id,
+                field,
+                expression: groupExpression(field.id, groups.get(field.id)?.timeGrain),
+                column: { id, label: field.label, valueType: field.valueType },
+            };
+        }
+        if (selection.operation !== "count" &&
+            selection.operation !== "countDistinct" &&
+            selection.operation !== "sum") {
+            throw new FinanceReportingQueryError(`Finance receivables does not support ${selection.operation}.`);
+        }
+        const field = selection.field ? requireField(definitions, selection.field) : undefined;
+        if (selection.operation === "sum" && field?.role !== "measure") {
+            throw new FinanceReportingQueryError("sum() requires a Finance measure.");
+        }
+        if (selection.operation === "countDistinct" && !field) {
+            throw new FinanceReportingQueryError("countDistinct() requires a field.");
+        }
+        if (field && !field.aggregations.includes(selection.operation)) {
+            throw new FinanceReportingQueryError(`${selection.operation} is not declared for ${JSON.stringify(field.id)}.`);
+        }
+        const expression = selection.operation === "count"
+            ? field
+                ? sql `count(${fieldExpression(field.id)})::bigint`
+                : sql `count(*)::bigint`
+            : selection.operation === "countDistinct"
+                ? sql `count(DISTINCT ${fieldExpression(field?.id ?? "")})::bigint`
+                : sql `coalesce(sum(${fieldExpression(field?.id ?? "")}), 0)::bigint`;
+        return {
+            id: selection.as,
+            field,
+            expression,
+            column: {
+                id: selection.as,
+                label: field?.label ?? "Count",
+                valueType: selection.operation === "count" || selection.operation === "countDistinct"
+                    ? "integer"
+                    : (field?.valueType ?? "number"),
+            },
+        };
+    });
+    const aliases = new Set();
+    for (const selection of selections) {
+        if (aliases.has(selection.id)) {
+            throw new FinanceReportingQueryError(`Duplicate selection alias ${JSON.stringify(selection.id)}.`);
+        }
+        aliases.add(selection.id);
+    }
+    const moneySelections = query.select.filter((selection) => selection.field !== undefined && MONEY_FIELDS.has(selection.field));
+    const currencyIsExplicit = aggregateQuery
+        ? groups.has("currency")
+        : query.select.some((selection) => selection.kind === "field" && selection.field === "currency");
+    if (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.");
+    }
+    const filters = query.filters.map((filter) => compileFilter(filter, definitions, parameters));
+    const selectSql = sql.join(selections.map(({ expression, id }) => sql `${expression} AS ${sql.identifier(id)}`), sql `, `);
+    const groupSql = [...groups.values()].map((group) => groupExpression(group.field, group.timeGrain));
+    const orderSql = query.orderBy.map((order) => {
+        if (!aliases.has(order.by)) {
+            throw new FinanceReportingQueryError(`Ordering must reference a selected output; ${JSON.stringify(order.by)} is unavailable.`);
+        }
+        return sql `${sql.identifier(order.by)} ${order.direction === "descending" ? sql `DESC` : sql `ASC`}`;
+    });
+    const rowLimit = Math.min(query.limit ?? input.maximumRows, input.maximumRows);
+    return {
+        statement: sql `
+      WITH receivable AS (${semanticReceivables})
+      SELECT ${selectSql}
+      FROM receivable
+      ${filters.length ? sql `WHERE ${sql.join(filters, sql ` AND `)}` : sql ``}
+      ${groupSql.length ? sql `GROUP BY ${sql.join(groupSql, sql `, `)}` : sql ``}
+      ${orderSql.length ? sql `ORDER BY ${sql.join(orderSql, sql `, `)}` : sql ``}
+      LIMIT ${rowLimit + 1}
+    `,
+        columns: selections.map(({ column }) => column),
+        rowLimit,
+    };
+}
+export const financeReceivablesDataset = {
+    definition: financeReceivablesDatasetDefinition,
+    async execute(context, input) {
+        if (!hasApiKeyPermission(permissionStringsToPermissions(context.grantedScopes), "finance", "read")) {
+            throw new FinanceReportingQueryError("finance:read is required to query receivables.");
+        }
+        if (context.signal?.aborted)
+            throw abortReason(context.signal);
+        const compiled = compileFinanceReceivablesQuery(input);
+        const rows = await executeBoundaryRows(context.db, compiled.statement);
+        if (context.signal?.aborted)
+            throw abortReason(context.signal);
+        const truncated = rows.length > compiled.rowLimit;
+        return {
+            columns: compiled.columns,
+            rows: rows.slice(0, compiled.rowLimit).map((row) => normalizeRow(row, compiled.columns)),
+            truncated,
+            warnings: [],
+        };
+    },
+};
+function requireField(fields, id) {
+    const field = fields.get(id);
+    if (!field || !fieldSql[id]) {
+        throw new FinanceReportingQueryError(`Unknown Finance field ${JSON.stringify(id)}.`);
+    }
+    return field;
+}
+function fieldExpression(id) {
+    const expression = fieldSql[id];
+    if (!expression)
+        throw new FinanceReportingQueryError(`Unknown Finance field ${JSON.stringify(id)}.`);
+    return expression;
+}
+function groupExpression(id, grain) {
+    const expression = fieldExpression(id);
+    if (!grain)
+        return expression;
+    switch (grain) {
+        case "day":
+            return sql `date_trunc('day', ${expression}::timestamp)::date`;
+        case "week":
+            return sql `date_trunc('week', ${expression}::timestamp)::date`;
+        case "month":
+            return sql `date_trunc('month', ${expression}::timestamp)::date`;
+        case "quarter":
+            return sql `date_trunc('quarter', ${expression}::timestamp)::date`;
+        case "year":
+            return sql `date_trunc('year', ${expression}::timestamp)::date`;
+    }
+}
+function compileFilter(filter, fields, parameters) {
+    const field = requireField(fields, filter.field);
+    if (field.role !== "dimension") {
+        throw new FinanceReportingQueryError(`Filtering measures is not supported.`);
+    }
+    const expression = fieldExpression(field.id);
+    if (filter.operator === "isNull")
+        return sql `${expression} IS NULL`;
+    if (filter.operator === "isNotNull")
+        return sql `${expression} IS NOT NULL`;
+    const value = requireFilterValue(filter, parameters);
+    switch (filter.operator) {
+        case "equal":
+            return value === null ? sql `${expression} IS NULL` : sql `${expression} = ${scalar(value)}`;
+        case "notEqual":
+            return value === null
+                ? sql `${expression} IS NOT NULL`
+                : sql `${expression} <> ${scalar(value)}`;
+        case "greaterThan":
+            return sql `${expression} > ${scalar(value)}`;
+        case "greaterThanOrEqual":
+            return sql `${expression} >= ${scalar(value)}`;
+        case "lessThan":
+            return sql `${expression} < ${scalar(value)}`;
+        case "lessThanOrEqual":
+            return sql `${expression} <= ${scalar(value)}`;
+        case "contains": {
+            if (typeof value !== "string" || field.valueType !== "string") {
+                throw new FinanceReportingQueryError("contains requires a string dimension and value.");
+            }
+            return sql `${expression} ILIKE ${`%${value}%`}`;
+        }
+        case "in":
+        case "notIn": {
+            if (!Array.isArray(value) || value.length === 0) {
+                throw new FinanceReportingQueryError(`${filter.operator} requires a non-empty array.`);
+            }
+            const values = sql.join(value.map((entry) => sql `${scalar(entry)}`), sql `, `);
+            return filter.operator === "in"
+                ? sql `${expression} IN (${values})`
+                : sql `${expression} NOT IN (${values})`;
+        }
+        case "between": {
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw new FinanceReportingQueryError("between requires exactly two values.");
+            }
+            return sql `${expression} BETWEEN ${scalar(value[0])} AND ${scalar(value[1])}`;
+        }
+        default:
+            throw new FinanceReportingQueryError(`Unsupported filter operator ${filter.operator}.`);
+    }
+}
+function requireFilterValue(filter, parameters) {
+    if (!filter.value)
+        throw new FinanceReportingQueryError(`${filter.operator} requires a value.`);
+    if (filter.value.kind === "literal")
+        return filter.value.value;
+    if (!(filter.value.name in parameters)) {
+        throw new FinanceReportingQueryError(`Missing query parameter ${JSON.stringify(filter.value.name)}.`);
+    }
+    const value = parameters[filter.value.name];
+    if (value === undefined) {
+        throw new FinanceReportingQueryError(`Missing query parameter ${JSON.stringify(filter.value.name)}.`);
+    }
+    return value;
+}
+function scalar(value) {
+    if (Array.isArray(value))
+        throw new FinanceReportingQueryError("Expected a scalar value.");
+    return value;
+}
+function hasSingleCurrencyFilter(query, parameters) {
+    return query.filters.some((filter) => {
+        if (filter.field !== "currency" || !filter.value)
+            return false;
+        const value = filter.value.kind === "literal" ? filter.value.value : parameters[filter.value.name];
+        if (filter.operator === "equal")
+            return typeof value === "string" && value.length > 0;
+        return (filter.operator === "in" &&
+            Array.isArray(value) &&
+            value.length === 1 &&
+            typeof value[0] === "string");
+    });
+}
+function normalizeRow(row, columns) {
+    return Object.fromEntries(columns.map((column) => {
+        const value = row[column.id];
+        if (column.valueType === "date" && value instanceof Date) {
+            return [column.id, value.toISOString().slice(0, 10)];
+        }
+        if ((column.valueType === "integer" ||
+            column.valueType === "number" ||
+            column.valueType === "currency") &&
+            typeof value === "string") {
+            const numeric = Number(value);
+            if (!Number.isFinite(numeric) ||
+                ((column.valueType === "integer" || column.valueType === "currency") &&
+                    !Number.isSafeInteger(numeric))) {
+                throw new FinanceReportingQueryError(`Result ${JSON.stringify(column.id)} is outside the supported numeric range.`);
+            }
+            return [column.id, numeric];
+        }
+        return [column.id, value];
+    }));
+}
+function abortReason(signal) {
+    return signal.reason ?? new Error("Finance report execution was aborted.");
+}

package/dist/voyant.js

@@ -1,8 +1,10 @@
+// agent-quality: file-size exception -- owner: finance; the package-owned deployment declarations remain centralized in one manifest.
 import { actionLedgerFinanceDriftRuntimePort } from "@voyant-travel/action-ledger/runtime-port";
 import { bookingsFinanceRuntimePort } from "@voyant-travel/bookings/runtime-port";
 import { defineExtension, defineModule, providePort, requirePort, } from "@voyant-travel/core/project";
 import { customFieldsRuntimePort } from "@voyant-travel/core/runtime-port";
 import { financeAppApiRuntimePort } from "@voyant-travel/finance-contracts/runtime-port";
+import { financeReceivablesDatasetDefinition, financeReportingTemplates, financeReportingWidgets, } from "./reporting-definitions.js";
 import { financeAccommodationsPaymentPolicyRuntimePort, financeCheckoutPaymentStartersRuntimePort, financeCruisesPaymentPolicyRuntimePort, financeDistributionPaymentPolicyRuntimePort, financeHostRuntimePort, financeInventoryPaymentPolicyRuntimePort, financeInvoiceSettlementPollerRuntimePort, financeNotificationsRuntimePort, financeOperatorSettingsRuntimePort, } from "./runtime-port.js";
 import { financeVoyantAdmin } from "./voyant-admin.js";
 import { bookingContractDocumentRequestedPayloadSchema, bookingCreatedPayloadSchema, bookingCreateRejectedPayloadSchema, bookingDualCreatedPayloadSchema, bookingPaymentSchedulePaidPayloadSchema, invoiceDocumentGeneratedPayloadSchema, invoiceIssuanceExternalPayloadSchema, invoicePaymentRecordedExternalPayloadSchema, invoiceProformaConvertedExternalPayloadSchema, invoiceRenderedPayloadSchema, invoiceSettledPayloadSchema, invoiceVoidedExternalPayloadSchema, paymentCompletedPayloadSchema, } from "./voyant-event-schemas.js";
@@ -68,6 +70,64 @@ export const financeVoyantModule = defineModule({
             source: "@voyant-travel/finance/schema",
         },
     ],
+    reporting: {
+        datasets: [
+            {
+                id: financeReceivablesDatasetDefinition.id,
+                version: financeReceivablesDatasetDefinition.version,
+                label: financeReceivablesDatasetDefinition.label,
+                description: financeReceivablesDatasetDefinition.description,
+                descriptor: financeReceivablesDatasetDefinition,
+                requiredScopes: financeReceivablesDatasetDefinition.requiredScopes,
+                runtime: {
+                    entry: "@voyant-travel/finance/reporting",
+                    export: "financeReceivablesDataset",
+                },
+            },
+        ],
+        widgets: financeReportingWidgets.map((widget) => ({
+            id: widget.id,
+            version: widget.version,
+            label: widget.label,
+            description: widget.description,
+            datasetId: widget.query.dataset.id,
+            ...(widget.query.dataset.version ? { datasetVersion: widget.query.dataset.version } : {}),
+            query: {
+                select: widget.query.select,
+                filters: widget.query.filters,
+                groupBy: widget.query.groupBy,
+                orderBy: widget.query.orderBy,
+                ...(widget.query.limit ? { limit: widget.query.limit } : {}),
+            },
+            visualization: {
+                type: widget.visualization.type,
+                options: omitUndefinedJsonOptions(widget.visualization.options),
+            },
+            defaultSize: widget.defaultSize,
+            ...(widget.minimumSize ? { minSize: widget.minimumSize } : {}),
+            ...(widget.maximumSize ? { maxSize: widget.maximumSize } : {}),
+        })),
+        templates: financeReportingTemplates.map((template) => ({
+            id: template.id,
+            version: template.version,
+            label: template.label,
+            description: template.description,
+            requirements: template.widgets.map((widget) => ({
+                kind: "widget",
+                id: widget.source.kind === "preset" ? widget.source.widgetId : widget.id,
+            })),
+            widgets: template.widgets.flatMap((widget) => widget.source.kind === "preset"
+                ? [
+                    {
+                        id: widget.id,
+                        widgetId: widget.source.widgetId,
+                        ...(widget.source.version ? { widgetVersion: widget.source.version } : {}),
+                        layout: widget.layout,
+                    },
+                ]
+                : []),
+        })),
+    },
     migrations: [
         {
             id: "@voyant-travel/finance#migrations",
@@ -566,4 +626,12 @@ export const financeBookingScheduleVoyantPlugin = defineExtension({
         ownership: "package",
     },
 });
+function omitUndefinedJsonOptions(options) {
+    const jsonOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined)
+            jsonOptions[key] = value;
+    }
+    return jsonOptions;
+}
 export default financeVoyantModule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/finance",
-  "version": "0.173.0",
+  "version": "0.175.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -44,6 +44,11 @@
       "import": "./dist/invoice-fx.js",
       "default": "./dist/invoice-fx.js"
     },
+    "./reporting": {
+      "types": "./dist/reporting.d.ts",
+      "import": "./dist/reporting.js",
+      "default": "./dist/reporting.js"
+    },
     "./order-payment-sessions": {
       "types": "./dist/order-payment-sessions.d.ts",
       "import": "./dist/order-payment-sessions.js",
@@ -151,23 +156,24 @@
     "fflate": "^0.8.2",
     "hono": "^4.12.27",
     "zod": "^4.4.3",
-    "@voyant-travel/action-ledger": "^0.111.5",
-    "@voyant-travel/bookings": "^0.173.0",
-    "@voyant-travel/core": "^0.128.0",
-    "@voyant-travel/db": "^0.114.14",
-    "@voyant-travel/types": "^0.109.4",
+    "@voyant-travel/action-ledger": "^0.111.7",
+    "@voyant-travel/bookings": "^0.175.0",
+    "@voyant-travel/core": "^0.130.0",
+    "@voyant-travel/db": "^0.115.0",
+    "@voyant-travel/types": "^0.109.6",
     "@voyant-travel/finance-contracts": "^0.107.0",
-    "@voyant-travel/hono": "^0.130.0",
-    "@voyant-travel/payments": "^0.2.4",
-    "@voyant-travel/public-document-delivery": "^0.4.4",
-    "@voyant-travel/storage": "^0.111.4",
+    "@voyant-travel/hono": "^0.131.0",
+    "@voyant-travel/payments": "^0.2.6",
+    "@voyant-travel/public-document-delivery": "^0.4.6",
+    "@voyant-travel/reporting-contracts": "^0.2.1",
+    "@voyant-travel/storage": "^0.111.6",
     "@voyant-travel/utils": "^0.108.0",
     "@voyant-travel/tools": "^0.3.0"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.10",
     "typescript": "^6.0.3",
-    "@voyant-travel/webhook-delivery": "^0.4.3",
+    "@voyant-travel/webhook-delivery": "^0.4.5",
     "@voyant-travel/voyant-typescript-config": "^0.1.0"
   },
   "files": [