@voyant-travel/reporting 0.2.3 → 0.3.0

package/dist/export.d.ts

@@ -0,0 +1,8 @@
+import type { ReportExport } from "./service.js";
+export type ReportExportFormat = "csv" | "xlsx" | "pdf";
+export declare const REPORT_EXPORT_CONTENT_TYPES: Record<ReportExportFormat, string>;
+/** A filesystem-safe base name for the downloaded file (no extension). */
+export declare function reportExportFileBase(report: ReportExport): string;
+export declare function reportToCsv(report: ReportExport): string;
+export declare function reportToXlsx(report: ReportExport): Promise<Uint8Array>;
+export declare function reportToPdf(report: ReportExport): Promise<Uint8Array>;

package/dist/export.js

@@ -0,0 +1,242 @@
+import ExcelJS from "exceljs";
+import { PDFDocument, rgb, StandardFonts } from "pdf-lib";
+export const REPORT_EXPORT_CONTENT_TYPES = {
+    csv: "text/csv; charset=utf-8",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    pdf: "application/pdf",
+};
+/** A filesystem-safe base name for the downloaded file (no extension). */
+export function reportExportFileBase(report) {
+    const slug = report.name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : "report";
+}
+function cellText(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+function toMajorUnits(value, format) {
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(numeric))
+        return null;
+    return format?.minorUnit ? numeric / 100 : numeric;
+}
+/**
+ * Spreadsheet cell: currency amounts become major-unit NUMBERS (so Excel can sum
+ * them), everything else stays raw. The currency code lives in its own column, so
+ * no symbol is embedded here.
+ */
+function numericCell(value, column, format) {
+    if (column.valueType === "currency") {
+        const major = toMajorUnits(value, format);
+        return major ?? cellText(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    return cellText(value);
+}
+/** Presentation cell (PDF): currency formatted with the row's own currency symbol. */
+function displayCell(value, column, format, row) {
+    if (value === null || value === undefined)
+        return "";
+    if (column.valueType === "currency") {
+        const major = toMajorUnits(value, format);
+        if (major === null)
+            return cellText(value);
+        const perRow = format?.currencyField ? row[format.currencyField] : undefined;
+        const currency = (typeof perRow === "string" && perRow) || format?.currency || "USD";
+        try {
+            return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(major);
+        }
+        catch {
+            return major.toLocaleString("en-US");
+        }
+    }
+    return cellText(value);
+}
+// ── CSV ─────────────────────────────────────────────────────────────────────
+function csvField(value) {
+    const text = cellText(value);
+    return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+export function reportToCsv(report) {
+    const lines = [];
+    report.sections.forEach((section, index) => {
+        if (index > 0)
+            lines.push("");
+        lines.push(csvField(section.title));
+        if (section.error) {
+            lines.push(csvField(`No data — ${section.error}`));
+            return;
+        }
+        lines.push(section.columns.map((column) => csvField(column.label)).join(","));
+        for (const row of section.rows) {
+            lines.push(section.columns
+                .map((column) => csvField(numericCell(row[column.id], column, section.format)))
+                .join(","));
+        }
+    });
+    // Excel opens UTF-8 CSV correctly only with a BOM.
+    return `${lines.join("\r\n")}\r\n`;
+}
+// ── XLSX ────────────────────────────────────────────────────────────────────
+function worksheetName(title, index) {
+    // Excel sheet names: ≤31 chars, none of : \ / ? * [ ].
+    const cleaned = title.replace(/[:\\/?*[\]]/g, " ").trim() || `Sheet ${index + 1}`;
+    return cleaned.slice(0, 31);
+}
+export async function reportToXlsx(report) {
+    const workbook = new ExcelJS.Workbook();
+    workbook.creator = "Voyant Reporting";
+    const usedNames = new Set();
+    report.sections.forEach((section, index) => {
+        let name = worksheetName(section.title, index);
+        while (usedNames.has(name))
+            name = worksheetName(`${section.title} ${index + 1}`, index);
+        usedNames.add(name);
+        const sheet = workbook.addWorksheet(name);
+        if (section.error) {
+            sheet.addRow([`No data — ${section.error}`]);
+            return;
+        }
+        const header = sheet.addRow(section.columns.map((column) => column.label));
+        header.font = { bold: true };
+        for (const row of section.rows) {
+            sheet.addRow(section.columns.map((column) => numericCell(row[column.id], column, section.format)));
+        }
+        sheet.columns.forEach((column) => {
+            column.width = 22;
+        });
+    });
+    if (report.sections.length === 0)
+        workbook.addWorksheet("Report");
+    const buffer = await workbook.xlsx.writeBuffer();
+    return new Uint8Array(buffer);
+}
+// ── PDF ─────────────────────────────────────────────────────────────────────
+const PDF_MARGIN = 48;
+const PDF_ROW_HEIGHT = 18;
+const PDF_FONT_SIZE = 9;
+export async function reportToPdf(report) {
+    const doc = await PDFDocument.create();
+    const font = await doc.embedFont(StandardFonts.Helvetica);
+    const bold = await doc.embedFont(StandardFonts.HelveticaBold);
+    const muted = rgb(0.42, 0.42, 0.45);
+    const ink = rgb(0.1, 0.1, 0.12);
+    let page = doc.addPage();
+    let { width, height } = page.getSize();
+    let cursorY = height - PDF_MARGIN;
+    const ensureSpace = (needed) => {
+        if (cursorY - needed < PDF_MARGIN) {
+            page = doc.addPage();
+            ({ width, height } = page.getSize());
+            cursorY = height - PDF_MARGIN;
+        }
+    };
+    const truncate = (text, cellFont, size, maxWidth) => {
+        if (cellFont.widthOfTextAtSize(text, size) <= maxWidth)
+            return text;
+        let out = text;
+        while (out.length > 1 && cellFont.widthOfTextAtSize(`${out}…`, size) > maxWidth) {
+            out = out.slice(0, -1);
+        }
+        return `${out}…`;
+    };
+    page.drawText(truncate(report.name, bold, 18, width - PDF_MARGIN * 2), {
+        x: PDF_MARGIN,
+        y: cursorY,
+        size: 18,
+        font: bold,
+        color: ink,
+    });
+    cursorY -= 26;
+    if (report.description) {
+        page.drawText(truncate(report.description, font, 10, width - PDF_MARGIN * 2), {
+            x: PDF_MARGIN,
+            y: cursorY,
+            size: 10,
+            font,
+            color: muted,
+        });
+        cursorY -= 20;
+    }
+    for (const section of report.sections) {
+        ensureSpace(PDF_ROW_HEIGHT * 2);
+        cursorY -= 12;
+        page.drawText(truncate(section.title, bold, 12, width - PDF_MARGIN * 2), {
+            x: PDF_MARGIN,
+            y: cursorY,
+            size: 12,
+            font: bold,
+            color: ink,
+        });
+        cursorY -= PDF_ROW_HEIGHT;
+        drawSectionTable(section, {
+            page,
+            addPage: () => {
+                page = doc.addPage();
+                ({ width, height } = page.getSize());
+                cursorY = height - PDF_MARGIN;
+                return page;
+            },
+            font,
+            bold,
+            muted,
+            ink,
+            widthOf: () => width,
+            getY: () => cursorY,
+            setY: (y) => {
+                cursorY = y;
+            },
+            truncate,
+        });
+    }
+    return doc.save();
+}
+function drawSectionTable(section, ctx) {
+    let page = ctx.page;
+    const width = ctx.widthOf();
+    const usableWidth = width - PDF_MARGIN * 2;
+    if (section.error) {
+        ctx.page.drawText(ctx.truncate(`No data — ${section.error}`, ctx.font, 9, usableWidth), {
+            x: PDF_MARGIN,
+            y: ctx.getY(),
+            size: 9,
+            font: ctx.font,
+            color: ctx.muted,
+        });
+        ctx.setY(ctx.getY() - PDF_ROW_HEIGHT);
+        return;
+    }
+    if (section.columns.length === 0)
+        return;
+    const colWidth = usableWidth / section.columns.length;
+    const drawRow = (values, rowFont, color) => {
+        if (ctx.getY() - PDF_ROW_HEIGHT < PDF_MARGIN) {
+            page = ctx.addPage();
+        }
+        const y = ctx.getY();
+        values.forEach((value, index) => {
+            page.drawText(ctx.truncate(value, rowFont, PDF_FONT_SIZE, colWidth - 6), {
+                x: PDF_MARGIN + index * colWidth,
+                y,
+                size: PDF_FONT_SIZE,
+                font: rowFont,
+                color,
+            });
+        });
+        ctx.setY(y - PDF_ROW_HEIGHT);
+    };
+    drawRow(section.columns.map((column) => column.label), ctx.bold, ctx.ink);
+    for (const row of section.rows) {
+        drawRow(section.columns.map((column) => displayCell(row[column.id], column, section.format, row)), ctx.font, ctx.ink);
+    }
+    if (section.rows.length === 0) {
+        drawRow(["No rows for the selected period."], ctx.font, ctx.muted);
+    }
+}

package/dist/registry.d.ts

@@ -43,6 +43,7 @@ export declare class ReportingRegistry {
         defaultLimit: number;
         maximumLimit: number;
         description?: string | undefined;
+        defaultDateField?: string | undefined;
     }[];
     listWidgets(): readonly ReportWidgetDefinition[];
     listTemplates(): readonly ReportTemplateDefinition[];

package/dist/registry.js

@@ -14,6 +14,33 @@ export class ReportingAuthorizationError extends ReportingRegistryError {
         this.missingScopes = missingScopes;
     }
 }
+/** The reserved report parameters a page-level date range writes into. */
+const PAGE_DATE_FROM_PARAM = "dateFrom";
+const PAGE_DATE_TO_PARAM = "dateTo";
+/**
+ * Apply a page-level date range to a query. When the dataset declares a
+ * {@link ReportDatasetContribution.definition.defaultDateField} and the caller
+ * supplies the reserved `dateFrom`/`dateTo` parameters, an inclusive window is
+ * appended as extra filters — so a single header control filters every widget
+ * (preset and custom) without touching individual queries. Absent parameters
+ * mean "all time"; the query is returned unchanged.
+ */
+function applyPageDateWindow(query, dataset, parameters) {
+    const field = dataset.definition.defaultDateField;
+    if (!field)
+        return query;
+    const params = parameters ?? {};
+    const from = params[PAGE_DATE_FROM_PARAM];
+    const to = params[PAGE_DATE_TO_PARAM];
+    const extra = [];
+    if (typeof from === "string" && from.length > 0) {
+        extra.push({ field, operator: "greaterThanOrEqual", value: { kind: "literal", value: from } });
+    }
+    if (typeof to === "string" && to.length > 0) {
+        extra.push({ field, operator: "lessThanOrEqual", value: { kind: "literal", value: to } });
+    }
+    return extra.length === 0 ? query : { ...query, filters: [...query.filters, ...extra] };
+}
 /** Immutable registry assembled from graph-selected module contributions. */
 export class ReportingRegistry {
     #datasets = new Map();
@@ -167,7 +194,8 @@ export class ReportingRegistry {
     }
     async executeQuery(input) {
         const { query, dataset, maximumRows } = this.validateQuery(input.query, input.grantedScopes);
-        for (const filter of query.filters) {
+        const executable = applyPageDateWindow(query, dataset, input.parameters);
+        for (const filter of executable.filters) {
             if (filter.value?.kind === "parameter" && !(filter.value.name in (input.parameters ?? {}))) {
                 throw new ReportingRegistryError(`Missing query parameter ${JSON.stringify(filter.value.name)}.`);
             }
@@ -177,7 +205,7 @@ export class ReportingRegistry {
             actorId: input.actorId,
             grantedScopes: input.grantedScopes,
             signal: input.signal,
-        }, { query, parameters: input.parameters ?? {}, maximumRows }));
+        }, { query: executable, parameters: input.parameters ?? {}, maximumRows }));
         if (result.rows.length <= maximumRows)
             return result;
         return { ...result, rows: result.rows.slice(0, maximumRows), truncated: true };

package/dist/routes.js

@@ -1,9 +1,10 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { ForbiddenApiError, openApiValidationHook, parseJsonBody, parseQuery, RequestValidationError, } from "@voyant-travel/hono";
-import { createReportDefinitionSchema, createReportVersionSchema, executeReportVersionSchema, instantiateReportTemplateSchema, listReportDefinitionsQuerySchema, parseReportQuery, parseReportQuerySourceSchema, previewReportQuerySchema, ReportQuerySyntaxError, updateReportDefinitionSchema, } from "@voyant-travel/reporting-contracts";
+import { ForbiddenApiError, openApiValidationHook, parseJsonBody, parseQuery, } from "@voyant-travel/hono";
+import { createReportDefinitionSchema, instantiateReportTemplateSchema, listReportDefinitionsQuerySchema, parseReportQuery, parseReportQuerySourceSchema, previewReportQuerySchema, ReportDatasetQueryError, ReportQuerySyntaxError, updateReportDefinitionSchema, } from "@voyant-travel/reporting-contracts";
 import { hasApiKeyPermission, permissionStringsToPermissions } from "@voyant-travel/types/api-keys";
+import { REPORT_EXPORT_CONTENT_TYPES, reportExportFileBase, reportToCsv, reportToPdf, reportToXlsx, } from "./export.js";
 import { ReportingAuthorizationError, ReportingRegistryError, } from "./registry.js";
-import { createReportingService, ReportDefinitionRetentionConflictError, ReportDefinitionRevisionConflictError, ReportingRecordNotFoundError, } from "./service.js";
+import { createReportingService, ReportDefinitionRevisionConflictError, ReportingRecordNotFoundError, } from "./service.js";
 export function createReportingRoutes(registry) {
     const routes = new OpenAPIHono({ defaultHook: openApiValidationHook });
     const service = createReportingService(registry);
@@ -15,12 +16,21 @@ export function createReportingRoutes(registry) {
         requireReportsPermission(c.get("scopes"), "read");
         const input = await parseJsonBody(c, parseReportQuerySourceSchema);
         try {
-            return c.json({ data: parseReportQuery(input.source) });
+            const query = parseReportQuery(input.source);
+            // Validate against the live registry so unknown datasets/fields, unsupported
+            // aggregations, and grouping mistakes fail here — where the author clicked
+            // "Parse" to check their query — instead of only when the preview executes.
+            registry.validateQuery(query, c.get("scopes") ?? []);
+            return c.json({ data: query });
         }
         catch (error) {
-            if (error instanceof ReportQuerySyntaxError)
-                throw new RequestValidationError(error.message);
-            throw error;
+            // Both syntax errors and registry validation failures (unknown dataset/field,
+            // bad grouping, out-of-range limit) are author mistakes → 400 with a message,
+            // never a 500.
+            if (error instanceof ReportQuerySyntaxError) {
+                return c.json({ error: "invalid_report_query", message: error.message }, 400);
+            }
+            return reportingErrorResponse(c, error);
         }
     });
     routes.post("/queries/preview", async (c) => {
@@ -89,39 +99,31 @@ export function createReportingRoutes(registry) {
             return reportingErrorResponse(c, error);
         }
     });
-    routes.post("/reports/:id/versions", async (c) => {
-        requireReportsPermission(c.get("scopes"), "write");
-        const input = await parseJsonBody(c, createReportVersionSchema);
-        try {
-            const version = await service.createVersion(c.get("db"), c.req.param("id"), input.expectedRevision, c.get("userId"));
-            return c.json({ data: version }, 201);
-        }
-        catch (error) {
-            return reportingErrorResponse(c, error);
-        }
-    });
-    routes.post("/versions/:id/runs", async (c) => {
+    routes.get("/reports/:id/export", async (c) => {
         requireReportsPermission(c.get("scopes"), "export");
-        const input = await parseJsonBody(c, executeReportVersionSchema);
+        const format = (c.req.query("format") ?? "csv").toLowerCase();
+        if (format !== "csv" && format !== "xlsx" && format !== "pdf") {
+            return c.json({ error: "invalid_format", message: "format must be csv, xlsx, or pdf." }, 400);
+        }
         try {
-            const run = await service.runVersion(c.get("db"), c.req.param("id"), input.parameters, {
+            const report = await service.exportReport(c.get("db"), c.req.param("id"), {}, {
                 actorId: c.get("userId"),
                 grantedScopes: c.get("scopes") ?? [],
                 signal: c.req.raw.signal,
             });
-            return c.json({ data: run }, 201);
-        }
-        catch (error) {
-            return reportingErrorResponse(c, error);
-        }
-    });
-    routes.get("/runs/:id", async (c) => {
-        requireReportsPermission(c.get("scopes"), "export");
-        try {
-            const run = await service.getRun(c.get("db"), c.req.param("id"), c.get("scopes") ?? []);
-            if (!run)
-                return c.json({ error: "report_run_not_found" }, 404);
-            return c.json({ data: run });
+            if (!report)
+                return c.json({ error: "report_not_found" }, 404);
+            const typed = format;
+            c.header("Content-Type", REPORT_EXPORT_CONTENT_TYPES[typed]);
+            c.header("Content-Disposition", `attachment; filename="${reportExportFileBase(report)}.${typed}"`);
+            if (typed === "csv") {
+                return c.body(reportToCsv(report));
+            }
+            // xlsx/pdf return raw bytes; hand Hono a standalone ArrayBuffer (a
+            // Uint8Array is not part of its accepted body `Data` union, and the view
+            // may be backed by a larger buffer).
+            const bytes = typed === "xlsx" ? await reportToXlsx(report) : await reportToPdf(report);
+            return c.body(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
         }
         catch (error) {
             return reportingErrorResponse(c, error);
@@ -140,13 +142,10 @@ function reportingErrorResponse(c, error) {
     if (error instanceof ReportDefinitionRevisionConflictError) {
         return c.json({ error: "revision_conflict" }, 409);
     }
-    if (error instanceof ReportDefinitionRetentionConflictError) {
-        return c.json({ error: "report_has_retained_runs" }, 409);
-    }
     if (error instanceof ReportingAuthorizationError) {
         return c.json({ error: "forbidden", missingScopes: error.missingScopes }, 403);
     }
-    if (error instanceof ReportingRegistryError) {
+    if (error instanceof ReportingRegistryError || error instanceof ReportDatasetQueryError) {
         return c.json({ error: "invalid_report_query", message: error.message }, 400);
     }
     throw error;