@voyant-travel/reporting 0.1.0

package/dist/service.js

@@ -0,0 +1,259 @@
+import { and, desc, eq, sql } from "drizzle-orm";
+import { reportDefinitions, reportRuns, reportVersions, } from "./schema.js";
+export class ReportDefinitionRevisionConflictError extends Error {
+    constructor() {
+        super("The report draft changed since it was loaded.");
+        this.name = "ReportDefinitionRevisionConflictError";
+    }
+}
+export class ReportingRecordNotFoundError extends Error {
+    constructor(record) {
+        super(`${record} was not found.`);
+        this.name = "ReportingRecordNotFoundError";
+    }
+}
+export class ReportDefinitionRetentionConflictError extends Error {
+    constructor() {
+        super("Reports with retained execution history cannot be deleted.");
+        this.name = "ReportDefinitionRetentionConflictError";
+    }
+}
+export function createReportingService(registry) {
+    return {
+        async list(db, input) {
+            const [data, count] = await Promise.all([
+                db
+                    .select()
+                    .from(reportDefinitions)
+                    .orderBy(desc(reportDefinitions.updatedAt))
+                    .limit(input.limit)
+                    .offset(input.offset),
+                db.select({ count: sql `count(*)::int` }).from(reportDefinitions),
+            ]);
+            return { data, total: count[0]?.count ?? 0, ...input };
+        },
+        async get(db, id) {
+            const [row] = await db
+                .select()
+                .from(reportDefinitions)
+                .where(eq(reportDefinitions.id, id))
+                .limit(1);
+            return row ?? null;
+        },
+        async create(db, input, actorId) {
+            const [row] = await db
+                .insert(reportDefinitions)
+                .values({
+                ...input,
+                description: input.description ?? null,
+                sourceTemplateId: input.sourceTemplateId ?? null,
+                sourceTemplateVersion: input.sourceTemplateVersion ?? null,
+                createdByUserId: actorId,
+                updatedByUserId: actorId,
+            })
+                .returning();
+            if (!row)
+                throw new Error("Report definition insert returned no row.");
+            return row;
+        },
+        async instantiateTemplate(db, input, actorId) {
+            const template = registry.getTemplate(input.templateId, input.version);
+            if (!template)
+                throw new ReportingRecordNotFoundError("Report template");
+            return this.create(db, {
+                name: input.name,
+                description: input.description,
+                sourceTemplateId: template.id,
+                sourceTemplateVersion: template.version,
+                draft: { parameters: {}, widgets: template.widgets },
+            }, actorId);
+        },
+        async update(db, id, input, actorId) {
+            const { revision, ...patch } = input;
+            const [row] = await db
+                .update(reportDefinitions)
+                .set({ ...patch, revision: revision + 1, updatedByUserId: actorId, updatedAt: new Date() })
+                .where(and(eq(reportDefinitions.id, id), eq(reportDefinitions.revision, revision)))
+                .returning();
+            if (row)
+                return row;
+            const existing = await this.get(db, id);
+            if (!existing)
+                throw new ReportingRecordNotFoundError("Report definition");
+            throw new ReportDefinitionRevisionConflictError();
+        },
+        async remove(db, id) {
+            return db.transaction(async (transaction) => {
+                const [definition] = await transaction
+                    .select({ id: reportDefinitions.id })
+                    .from(reportDefinitions)
+                    .where(eq(reportDefinitions.id, id))
+                    .limit(1)
+                    .for("update");
+                if (!definition)
+                    return false;
+                await transaction
+                    .select({ id: reportVersions.id })
+                    .from(reportVersions)
+                    .where(eq(reportVersions.reportDefinitionId, id))
+                    .for("update");
+                const [retainedRun] = await transaction
+                    .select({ id: reportRuns.id })
+                    .from(reportRuns)
+                    .innerJoin(reportVersions, eq(reportRuns.reportVersionId, reportVersions.id))
+                    .where(eq(reportVersions.reportDefinitionId, id))
+                    .limit(1);
+                if (retainedRun)
+                    throw new ReportDefinitionRetentionConflictError();
+                await transaction.delete(reportDefinitions).where(eq(reportDefinitions.id, id));
+                return true;
+            });
+        },
+        async createVersion(db, reportDefinitionId, expectedRevision, actorId) {
+            return db.transaction(async (transaction) => {
+                const [definition] = await transaction
+                    .select()
+                    .from(reportDefinitions)
+                    .where(eq(reportDefinitions.id, reportDefinitionId))
+                    .limit(1)
+                    .for("update");
+                if (!definition)
+                    throw new ReportingRecordNotFoundError("Report definition");
+                if (definition.revision !== expectedRevision)
+                    throw new ReportDefinitionRevisionConflictError();
+                const [latest] = await transaction
+                    .select({ version: reportVersions.version })
+                    .from(reportVersions)
+                    .where(eq(reportVersions.reportDefinitionId, reportDefinitionId))
+                    .orderBy(desc(reportVersions.version))
+                    .limit(1);
+                const [version] = await transaction
+                    .insert(reportVersions)
+                    .values({
+                    reportDefinitionId,
+                    version: (latest?.version ?? 0) + 1,
+                    name: definition.name,
+                    description: definition.description,
+                    definitionRevision: definition.revision,
+                    snapshot: registry.snapshotDraft(definition.draft),
+                    createdByUserId: actorId,
+                })
+                    .returning();
+                if (!version)
+                    throw new Error("Report version insert returned no row.");
+                return version;
+            });
+        },
+        async runVersion(db, versionId, parameters, context) {
+            const execution = await db.transaction(async (transaction) => {
+                const [version] = await transaction
+                    .select()
+                    .from(reportVersions)
+                    .where(eq(reportVersions.id, versionId))
+                    .limit(1)
+                    .for("share");
+                if (!version)
+                    throw new ReportingRecordNotFoundError("Report version");
+                for (const resolved of registry.resolveDraft(version.snapshot, "edit")) {
+                    if (resolved.status === "missing" || !resolved.definition)
+                        continue;
+                    registry.validateQuery(resolved.definition.query, context.grantedScopes);
+                }
+                const [run] = await transaction
+                    .insert(reportRuns)
+                    .values({ reportVersionId: versionId, parameters, triggeredByUserId: context.actorId })
+                    .returning();
+                if (!run)
+                    throw new Error("Report run insert returned no row.");
+                return { run, version };
+            });
+            const { run, version } = execution;
+            try {
+                const executionSignal = context.signal
+                    ? AbortSignal.any([context.signal, AbortSignal.timeout(60_000)])
+                    : AbortSignal.timeout(60_000);
+                const output = await executeDraft(registry, db, version.snapshot, parameters, {
+                    ...context,
+                    signal: executionSignal,
+                });
+                const failed = output.widgets.some((widget) => widget.status === "failed");
+                const [completed] = await db
+                    .update(reportRuns)
+                    .set({
+                    status: failed ? "failed" : "succeeded",
+                    output,
+                    error: failed ? "One or more widgets failed." : null,
+                    completedAt: new Date(),
+                })
+                    .where(eq(reportRuns.id, run.id))
+                    .returning();
+                return completed ?? run;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Report execution failed.";
+                const [failed] = await db
+                    .update(reportRuns)
+                    .set({ status: "failed", error: message, completedAt: new Date() })
+                    .where(eq(reportRuns.id, run.id))
+                    .returning();
+                return failed ?? run;
+            }
+        },
+        async getRun(db, id, grantedScopes) {
+            const [run] = await db.select().from(reportRuns).where(eq(reportRuns.id, id)).limit(1);
+            if (run) {
+                const requiredScopes = [
+                    ...new Set(run.output?.widgets.flatMap((widget) => widget.requiredScopes ?? []) ?? []),
+                ];
+                registry.requireScopes(requiredScopes, grantedScopes);
+            }
+            return run ?? null;
+        },
+    };
+}
+async function executeDraft(registry, db, draft, runParameters, context) {
+    const parameters = { ...draft.parameters, ...runParameters };
+    const widgets = [];
+    for (const resolved of registry.resolveDraft(draft, "edit")) {
+        if (resolved.status === "missing" || !resolved.definition) {
+            widgets.push({
+                widgetInstanceId: resolved.instance.id,
+                status: "missing",
+                reason: resolved.missingReason ?? "Widget is unavailable.",
+            });
+            continue;
+        }
+        let provenance;
+        try {
+            const validation = registry.validateQuery(resolved.definition.query, context.grantedScopes);
+            provenance = {
+                datasetId: validation.dataset.definition.id,
+                datasetVersion: validation.dataset.definition.version,
+                requiredScopes: validation.requiredScopes,
+            };
+            const result = await registry.executeQuery({
+                db,
+                actorId: context.actorId,
+                grantedScopes: context.grantedScopes,
+                query: resolved.definition.query,
+                parameters,
+                signal: context.signal,
+            });
+            widgets.push({
+                widgetInstanceId: resolved.instance.id,
+                status: "succeeded",
+                ...provenance,
+                result,
+            });
+        }
+        catch (error) {
+            widgets.push({
+                widgetInstanceId: resolved.instance.id,
+                status: "failed",
+                ...provenance,
+                reason: error instanceof Error ? error.message : "Widget execution failed.",
+            });
+        }
+    }
+    return { widgets };
+}

package/dist/voyant-admin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Static admin contribution metadata used by the Reporting deployment manifest.
+ * The selected factory contributes the operator navigation group and both
+ * routes; the per-route runtime carries the neutral factory the host binds.
+ */
+export declare const reportingVoyantAdmin: {
+    readonly compositionOrder: 60;
+    readonly runtime: {
+        readonly entry: "@voyant-travel/reporting-react/admin";
+        readonly export: "createSelectedReportingAdminExtension";
+    };
+    readonly routes: readonly [{
+        readonly id: "@voyant-travel/reporting#admin.route.index";
+        readonly path: "/reporting";
+        readonly requiredScopes: readonly ["reports:read"];
+        readonly runtime: {
+            readonly entry: "@voyant-travel/reporting-react/admin";
+            readonly export: "createReportingAdminExtension";
+        };
+    }, {
+        readonly id: "@voyant-travel/reporting#admin.route.detail";
+        readonly path: "/reporting/$id";
+        readonly requiredScopes: readonly ["reports:read"];
+        readonly runtime: {
+            readonly entry: "@voyant-travel/reporting-react/admin";
+            readonly export: "createReportingAdminExtension";
+        };
+    }];
+};

package/dist/voyant-admin.js

@@ -0,0 +1,30 @@
+const reportingAdminRuntime = {
+    entry: "@voyant-travel/reporting-react/admin",
+    export: "createReportingAdminExtension",
+};
+/**
+ * Static admin contribution metadata used by the Reporting deployment manifest.
+ * The selected factory contributes the operator navigation group and both
+ * routes; the per-route runtime carries the neutral factory the host binds.
+ */
+export const reportingVoyantAdmin = {
+    compositionOrder: 60,
+    runtime: {
+        entry: "@voyant-travel/reporting-react/admin",
+        export: "createSelectedReportingAdminExtension",
+    },
+    routes: [
+        {
+            id: "@voyant-travel/reporting#admin.route.index",
+            path: "/reporting",
+            requiredScopes: ["reports:read"],
+            runtime: reportingAdminRuntime,
+        },
+        {
+            id: "@voyant-travel/reporting#admin.route.detail",
+            path: "/reporting/$id",
+            requiredScopes: ["reports:read"],
+            runtime: reportingAdminRuntime,
+        },
+    ],
+};

package/dist/voyant.d.ts

@@ -0,0 +1,2 @@
+export declare const reportingVoyantModule: import("@voyant-travel/core").VoyantGraphUnitManifest;
+export default reportingVoyantModule;

package/dist/voyant.js

@@ -0,0 +1,116 @@
+import { defineModule, requirePort } from "@voyant-travel/core/project";
+import { reportingContributionRuntimePort } from "@voyant-travel/reporting-contracts/runtime-port";
+import { reportingVoyantAdmin } from "./voyant-admin.js";
+export const reportingVoyantModule = defineModule({
+    id: "@voyant-travel/reporting",
+    packageName: "@voyant-travel/reporting",
+    localId: "reporting",
+    runtimePorts: [
+        requirePort(reportingContributionRuntimePort, { optional: true, cardinality: "many" }),
+    ],
+    reporting: {
+        templates: [
+            {
+                id: "reporting.template.operator-overview",
+                version: 1,
+                label: "Operator overview",
+                description: "A cross-module overview of booking activity and final-invoice receivables.",
+                requirements: [
+                    { kind: "widget", id: "bookings.widget.total" },
+                    { kind: "widget", id: "bookings.widget.monthly-trend" },
+                    { kind: "widget", id: "finance.outstanding-by-currency" },
+                    { kind: "widget", id: "finance.net-issued-trend" },
+                    { kind: "widget", id: "finance.invoice-status-breakdown" },
+                ],
+                widgets: [
+                    {
+                        id: "total-bookings",
+                        widgetId: "bookings.widget.total",
+                        widgetVersion: 1,
+                        layout: { x: 0, y: 0, width: 3, height: 2 },
+                    },
+                    {
+                        id: "outstanding-receivables",
+                        widgetId: "finance.outstanding-by-currency",
+                        widgetVersion: 1,
+                        layout: { x: 3, y: 0, width: 4, height: 3 },
+                    },
+                    {
+                        id: "invoice-status",
+                        widgetId: "finance.invoice-status-breakdown",
+                        widgetVersion: 1,
+                        layout: { x: 7, y: 0, width: 5, height: 3 },
+                    },
+                    {
+                        id: "monthly-bookings",
+                        widgetId: "bookings.widget.monthly-trend",
+                        widgetVersion: 1,
+                        layout: { x: 0, y: 3, width: 6, height: 4 },
+                    },
+                    {
+                        id: "net-issued",
+                        widgetId: "finance.net-issued-trend",
+                        widgetVersion: 1,
+                        layout: { x: 6, y: 3, width: 6, height: 4 },
+                    },
+                ],
+            },
+        ],
+    },
+    api: [
+        {
+            id: "@voyant-travel/reporting#api.admin",
+            surface: "admin",
+            mount: "reporting",
+            resource: "reports",
+            authorization: "route",
+            openapi: { document: "reporting" },
+            runtime: {
+                entry: "@voyant-travel/reporting/api-runtime",
+                export: "createReportingApiModule",
+            },
+        },
+    ],
+    schema: [{ id: "@voyant-travel/reporting#schema", source: "@voyant-travel/reporting/schema" }],
+    migrations: [{ id: "@voyant-travel/reporting#migrations", source: "./migrations" }],
+    resources: [
+        {
+            id: "@voyant-travel/reporting#resource.database",
+            kind: "database",
+            required: true,
+            config: { engine: "postgres" },
+        },
+    ],
+    access: {
+        resources: [
+            {
+                id: "@voyant-travel/reporting#access.reports",
+                resource: "reports",
+                label: "Reports",
+                description: "Build, view, publish, and export reports.",
+                actions: [
+                    {
+                        action: "read",
+                        label: "View reports",
+                        description: "View reports and preview queries.",
+                    },
+                    {
+                        action: "write",
+                        label: "Manage reports",
+                        description: "Create, edit, remove, and publish reports.",
+                    },
+                    {
+                        action: "export",
+                        label: "Run and export reports",
+                        description: "Execute immutable report versions and access their output.",
+                        sensitive: true,
+                    },
+                ],
+            },
+        ],
+    },
+    admin: reportingVoyantAdmin,
+    lifecycle: { uninstall: { default: "retain-data", purge: "not-supported" } },
+    meta: { ownership: "package" },
+});
+export default reportingVoyantModule;

package/migrations/20260718090000_reporting_baseline.sql

@@ -0,0 +1,54 @@
+CREATE TYPE "public"."report_run_status" AS ENUM('running', 'succeeded', 'failed');
+--> statement-breakpoint
+CREATE TABLE "report_definitions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"source_template_id" text,
+	"source_template_version" integer,
+	"draft" jsonb NOT NULL,
+	"revision" integer DEFAULT 1 NOT NULL,
+	"created_by_user_id" text,
+	"updated_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "report_versions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"report_definition_id" text NOT NULL,
+	"version" integer NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"definition_revision" integer NOT NULL,
+	"snapshot" jsonb NOT NULL,
+	"created_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "report_runs" (
+	"id" text PRIMARY KEY NOT NULL,
+	"report_version_id" text NOT NULL,
+	"status" "report_run_status" DEFAULT 'running' NOT NULL,
+	"parameters" jsonb NOT NULL,
+	"output" jsonb,
+	"error" text,
+	"triggered_by_user_id" text,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"completed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "report_versions" ADD CONSTRAINT "report_versions_report_definition_id_report_definitions_id_fk" FOREIGN KEY ("report_definition_id") REFERENCES "public"."report_definitions"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "report_runs" ADD CONSTRAINT "report_runs_report_version_id_report_versions_id_fk" FOREIGN KEY ("report_version_id") REFERENCES "public"."report_versions"("id") ON DELETE restrict ON UPDATE no action;
+--> statement-breakpoint
+CREATE INDEX "idx_report_definitions_updated" ON "report_definitions" USING btree ("updated_at");
+--> statement-breakpoint
+CREATE UNIQUE INDEX "uidx_report_versions_definition_version" ON "report_versions" USING btree ("report_definition_id","version");
+--> statement-breakpoint
+CREATE INDEX "idx_report_versions_definition_created" ON "report_versions" USING btree ("report_definition_id","created_at");
+--> statement-breakpoint
+CREATE INDEX "idx_report_runs_version_created" ON "report_runs" USING btree ("report_version_id","created_at");
+--> statement-breakpoint
+CREATE INDEX "idx_report_runs_status_started" ON "report_runs" USING btree ("status","started_at");

package/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1784365200000,
+      "tag": "20260718090000_reporting_baseline",
+      "breakpoints": true
+    }
+  ]
+}