@happyvertical/smrt-reports 0.42.6 → 0.42.7

package/dist/index.d.ts

@@ -6,6 +6,11 @@ import { AggregateTimeBucketUnit } from '@happyvertical/sql';
 import { bucketExpr } from '@happyvertical/sql';
 import { buildAggregate } from '@happyvertical/sql';
 import { DatabaseInterface } from '@happyvertical/sql';
+import { DataQueryFieldDescriptor } from '@happyvertical/smrt-types';
+import { DataQueryFilter } from '@happyvertical/smrt-types';
+import { DataQueryRequest } from '@happyvertical/smrt-types';
+import { DataQueryResult } from '@happyvertical/smrt-types';
+import { DataQuerySchema } from '@happyvertical/smrt-types';
 import { EventEmitter } from 'node:events';
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { SmrtJob } from '@happyvertical/smrt-jobs';
@@ -28,6 +33,22 @@ export { AggregateSelectExpr }
 
 export { AggregateSpec }
 
+export declare interface AppliedReportRefresh {
+    phase: 'apply';
+    job: ReportRefreshJobHandle;
+}
+
+/** Queue a manual refresh only after the action host authorizes and audits it. */
+export declare function applyReportRefresh(reportCtor: ReportCtor, options: ApplyReportRefreshOptions): Promise<AppliedReportRefresh>;
+
+export declare interface ApplyReportRefreshOptions extends PreviewReportRefreshOptions {
+    queue?: string;
+    priority?: number;
+    timeout?: number;
+    maxAttempts?: number;
+    tenantJobCap?: number;
+}
+
 export declare function assertReportTablesReady(db: DatabaseInterface, tables?: readonly string[]): Promise<void>;
 
 export declare const avg: (column?: string, options?: {
@@ -38,8 +59,18 @@ export { bucketExpr }
 
 export { buildAggregate }
 
+export declare function buildReportAdapterDescriptor(reportCtor: new (...args: any[]) => SmrtObject, options?: ReportAdapterOptions): Promise<ReportAdapterDescriptor>;
+
 export declare function buildReportDefinition(reportCtor: new (...args: any[]) => SmrtObject): Promise<ReportDefinition>;
 
+/**
+ * Bind a materialized report row to its declared source dimensions. This is a
+ * query handoff, not an executor: an authenticated source adapter must apply
+ * the inherited principal, tenant, definition, and field policy before it
+ * reads source records.
+ */
+export declare function buildReportDrilldownQuery(reportCtor: new (...args: any[]) => SmrtObject, row: Readonly<Record<string, unknown>>, options?: ReportAdapterOptions): Promise<ReportDrilldownQuery>;
+
 export declare function compileReportDefinition(definition: ReportDefinition): AggregateSpec;
 
 export declare function compileReportSpec(reportCtor: new (...args: any[]) => SmrtObject): Promise<AggregateSpec>;
@@ -59,7 +90,7 @@ export declare const day: (sourceColumn: string) => PropertyDecorator;
 export declare function enqueueReportRefresh(options: EnqueueReportRefreshOptions): Promise<SmrtJob>;
 
 export declare interface EnqueueReportRefreshOptions extends ReportRefreshJobArgs {
-    report?: ReportCtor_2;
+    report?: ReportCtor_3;
     reportClass: string;
     db: DatabaseInterface;
     queue?: string;
@@ -73,7 +104,7 @@ export declare function ensureReportRefreshSchedules(options: EnsureReportSchedu
 
 export declare interface EnsureReportSchedulesOptions {
     db: DatabaseInterface;
-    reports: ReportCtor_2[];
+    reports: ReportCtor_3[];
     tenantIds?: string[];
     queue?: string;
     priority?: number;
@@ -82,6 +113,13 @@ export declare interface EnsureReportSchedulesOptions {
 
 export declare function getReportGroupingColumns(definition: Pick<ReportDefinition, 'fields'>): string[];
 
+/**
+ * Read only the ambient tenant's report state. The caller cannot supply a
+ * tenant selector, which prevents lifecycle lookup from becoming a tenant
+ * enumeration surface.
+ */
+export declare function getReportLifecycle(reportCtor: ReportCtor, options: ReportLifecycleOptions): Promise<ReportLifecycleSnapshot>;
+
 export declare function getRuntimeReportOptions(ctor: Function): ReportOptions | undefined;
 
 export declare function groupBy(sourceColumn?: string): PropertyDecorator;
@@ -100,9 +138,32 @@ export declare const minute: (sourceColumn: string) => PropertyDecorator;
 
 export declare const month: (sourceColumn: string) => PropertyDecorator;
 
+/** Preview only declares a separately authorized and audited refresh request. */
+export declare function previewReportRefresh(reportCtor: ReportCtor, options: PreviewReportRefreshOptions): Promise<ReportRefreshPreview>;
+
+export declare interface PreviewReportRefreshOptions extends ReportLifecycleOptions {
+    host: ReportRefreshActionHost;
+    mode?: ReportRefreshMode;
+    /**
+     * Pass `descriptor.refresh.action` when the adapter declares a custom
+     * refresh permission, so the displayed and enforced action stay aligned.
+     */
+    refreshAction?: Pick<ReportRefreshActionDescriptor, 'requiredPermission'>;
+}
+
 export declare const quarter: (sourceColumn: string) => PropertyDecorator;
 
-export declare function refreshReport(reportCtor: ReportCtor, options?: ReportRefreshOptions): Promise<ReportRefreshResult>;
+/**
+ * Execute bounded materialized report reads through the canonical query
+ * envelope. Every predicate is an adapter-declared field/operator pair; the
+ * collection converts it to parameterized SQL and applies tenant interceptors
+ * to list, count, and facet reads alike.
+ */
+export declare function queryReportMaterializedRows(reportCtor: new (...args: any[]) => SmrtObject, input: unknown, options: ReportBackgroundQueryOptions): Promise<ReportBackgroundQueryResult>;
+
+export declare function queryReportMaterializedRows(reportCtor: new (...args: any[]) => SmrtObject, input: unknown, options?: ReportQueryOptions): Promise<ReportDataQueryResult>;
+
+export declare function refreshReport(reportCtor: ReportCtor_2, options?: ReportRefreshOptions): Promise<ReportRefreshResult>;
 
 export declare function registerReportRefreshInterceptor(options: ReportRefreshInterceptorOptions): () => boolean;
 
@@ -122,6 +183,36 @@ export declare const REPORT_SCHEDULES_TABLE = "_smrt_report_schedules";
 
 export declare const REPORT_WATERMARKS_TABLE = "_smrt_report_watermarks";
 
+/**
+ * The report-owned, transport-neutral descriptor. Consumers can map `schema`
+ * to the canonical data-query runtime and `columns` to their presentation
+ * contract without importing smrt-ui or a report domain class.
+ */
+export declare interface ReportAdapterDescriptor {
+    version: 1;
+    resourceId: string;
+    reportClassName: string;
+    sourceClassName: string;
+    tenantScoped: boolean;
+    tenantField?: string;
+    identityField: 'id';
+    columns: ReportColumnDescriptor[];
+    schema: DataQuerySchema;
+    queryExecution: ReportQueryExecutionDescriptor;
+    dataTable: ReportDataTableDescriptor;
+    drilldown: ReportDrilldownDescriptor;
+    refresh: ReportRefreshDescriptor;
+}
+
+export declare interface ReportAdapterOptions {
+    /** Scope used only to make a stable resource id; it is not authority. */
+    tenantScope?: 'current' | 'global' | 'tenant';
+    /** Permission that a lifecycle action host must require before refresh. */
+    refreshPermission?: string;
+    /** Consumer-owned presentational preferences; they never affect query rows. */
+    dataTable?: ReportDataTablePresentationOptions;
+}
+
 export declare interface ReportAggregateFieldMetadata {
     kind: 'aggregate';
     fn: ReportAggregateFn;
@@ -131,16 +222,170 @@ export declare interface ReportAggregateFieldMetadata {
 
 export declare type ReportAggregateFn = AggregateFunction;
 
+/** Background execution is possible only through an application-owned queue host. */
+export declare interface ReportBackgroundQueryOptions extends ReportQueryCommonOptions {
+    execution: 'background';
+    enqueueBackgroundQuery(task: ReportBackgroundQueryTask): Promise<{
+        taskId: string;
+    }>;
+}
+
+/** Queuing a background query returns a handle, never rows from another scope. */
+export declare interface ReportBackgroundQueryResult {
+    version: 1;
+    execution: 'background';
+    status: 'queued';
+    taskId: string;
+    queryFingerprint: string;
+}
+
+/**
+ * The exact bounded request a background host may persist. Tenant, principal,
+ * collection, database, and display state deliberately remain with that host.
+ */
+export declare interface ReportBackgroundQueryTask {
+    version: 1;
+    execution: 'background';
+    resourceId: string;
+    reportClassName: string;
+    request: DataQueryRequest;
+    inherits: Array<'principal' | 'tenant' | 'report-definition' | 'field-policy'>;
+}
+
 export declare interface ReportBucketFieldMetadata {
     kind: 'bucket';
     unit: ReportTimeBucketUnit;
     sourceColumn: string;
 }
 
+export declare type ReportColumnCapability = 'read' | 'project' | 'filter' | 'sort' | 'facet' | 'group' | 'aggregate';
+
+export declare interface ReportColumnDescriptor extends DataQueryFieldDescriptor {
+    /** Stable output column id (never a property path). */
+    id: string;
+    fieldName: string;
+    label: string;
+    kind: ReportColumnKind;
+    filterScope: ReportFilterScope;
+    /** Capabilities available from this adapter revision. */
+    capabilities: ReportColumnCapability[];
+    format?: string;
+    sensitivity?: ReportColumnSensitivity;
+    sourceColumn?: string;
+    bucket?: ReportTimeBucketUnit;
+    aggregate?: ReportAggregateFn;
+    distinct?: boolean;
+}
+
+export declare type ReportColumnKind = 'identity' | 'group' | 'bucket' | 'aggregate';
+
+/** Presentation and policy metadata understood by the report adapter. */
+export declare type ReportColumnSensitivity = 'public' | 'personal' | 'sensitive' | 'secret';
+
 declare type ReportCtor = new (...args: any[]) => SmrtObject;
 
 declare type ReportCtor_2 = new (...args: any[]) => SmrtObject;
 
+declare type ReportCtor_3 = new (...args: any[]) => SmrtObject;
+
+export declare interface ReportDataQueryResult extends DataQueryResult {
+    /** Delivery intent only; the adapter never mutates a visible surface. */
+    execution: 'visible' | 'silent';
+    reportLifecycle?: ReportMaterializedReadLifecycle;
+}
+
+export declare interface ReportDataTableColumn {
+    id: string;
+    label: string;
+    accessor: string;
+    sortable: boolean;
+    searchable: false;
+    filterable: boolean;
+    /** Group ancestry for consumers with multi-level table headers. */
+    headerPath: ReportDataTableHeaderPathSegment[];
+    /** Consumer-side display instruction; materialized rows remain raw. */
+    valueFormat: ReportDataTableValueFormat;
+    /** The default alignment for the formatted display value. */
+    align: 'left' | 'right';
+    /** Generic semantic role for status/action columns introduced by later slices. */
+    role: ReportDataTableColumnRole;
+    responsive: ReportDataTableColumnResponsive;
+}
+
+/** Per-column presentation overrides owned by the consuming report surface. */
+export declare interface ReportDataTableColumnOverride {
+    label?: string;
+    headerPath?: readonly ReportDataTableHeaderPathSegment[];
+    valueFormat?: ReportDataTableValueFormat;
+    align?: 'left' | 'right';
+    role?: ReportDataTableColumnRole;
+    responsive?: ReportDataTableColumnResponsive;
+}
+
+/** Responsive metadata that maps directly to a consumer's table contract. */
+export declare interface ReportDataTableColumnResponsive {
+    /** Higher values make a column more important during responsive collapse. */
+    priority?: number;
+    /** Keep key dimensions reachable during responsive collapse. */
+    keepVisible?: boolean;
+}
+
+export declare type ReportDataTableColumnRole = 'data' | 'status' | 'action';
+
+export declare interface ReportDataTableDescriptor {
+    rowKey: 'id';
+    manualPagination: true;
+    manualSorting: true;
+    enableFiltering: true;
+    enableSearch: false;
+    columns: ReportDataTableColumn[];
+    structuralRows: ReportDataTableStructuralRow[];
+}
+
+/** Structural DataTable view hints; deliberately not a smrt-ui dependency. */
+export declare interface ReportDataTableHeaderPathSegment {
+    /** Stable group identity within a header level. */
+    id: string;
+    /** Human-readable grouped-header label. */
+    label: string;
+}
+
+export declare interface ReportDataTablePresentationOptions {
+    /** Overrides are keyed by stable adapter column id, not display labels. */
+    columns?: Readonly<Record<string, ReportDataTableColumnOverride>>;
+    /** Summary/subtotal rows remain structural rather than materialized data rows. */
+    structuralRows?: readonly ReportDataTableStructuralRowInput[];
+}
+
+/**
+ * Structural rows are intentionally separate from materialized data rows.
+ * Consumers pass them to their DataTable's structural-row slot/prop, never its
+ * selectable data collection.
+ */
+export declare interface ReportDataTableStructuralRow extends ReportDataTableStructuralRowInput {
+    selection: 'excluded';
+    actions: 'excluded';
+}
+
+/** Input supplied by a report consumer that computes a summary or subtotal. */
+export declare interface ReportDataTableStructuralRowInput {
+    id: string;
+    kind: ReportDataTableStructuralRowKind;
+    label: string;
+    /** Raw values keyed by the adapter's stable column id. */
+    values?: Readonly<Record<string, unknown>>;
+    /** Column that renders this row's accessible row header. */
+    labelColumnId?: string;
+}
+
+export declare type ReportDataTableStructuralRowKind = 'summary' | 'subtotal' | 'aggregate' | 'footer';
+
+/**
+ * A rendering instruction for a raw materialized value. Formatting is never
+ * applied to a query row, so sorting, export, and agent consumers retain it.
+ */
+export declare type ReportDataTableValueFormat = 'text' | 'date' | 'datetime' | 'percentage' | 'count' | 'money' | 'number';
+
 export declare interface ReportDefinition {
     reportClassName: string;
     sourceClassName: string;
@@ -151,6 +396,46 @@ export declare interface ReportDefinition {
     refresh?: ReportRefreshConfig;
 }
 
+export declare interface ReportDrilldownConstraint {
+    id: string;
+    sourceColumn: string;
+    kind: 'group' | 'bucket';
+    value: unknown;
+    bucket?: ReportTimeBucketUnit;
+}
+
+/**
+ * Declarative source-query handoff for a report row. No client can supply a
+ * principal, tenant, report definition, or arbitrary source field here.
+ */
+export declare interface ReportDrilldownDescriptor {
+    id: 'drilldown';
+    sourceClassName: string;
+    fields: ReportDrilldownFieldDescriptor[];
+    inherits: Array<'principal' | 'tenant' | 'report-definition' | 'field-policy'>;
+}
+
+/** One row value that can safely constrain a source-record drilldown. */
+export declare interface ReportDrilldownFieldDescriptor {
+    /** Stable report column id; never a display label. */
+    id: string;
+    /** Declared source field/column chosen by report metadata, not caller input. */
+    sourceColumn: string;
+    kind: 'group' | 'bucket';
+    /** A bucket stays declarative so the source adapter preserves report timezone semantics. */
+    bucket?: ReportTimeBucketUnit;
+}
+
+/** A server adapter uses this authority-free handoff to execute a source drilldown. */
+export declare interface ReportDrilldownQuery {
+    version: 1;
+    resourceId: string;
+    reportClassName: string;
+    sourceClassName: string;
+    constraints: ReportDrilldownConstraint[];
+    inherits: Array<'principal' | 'tenant' | 'report-definition' | 'field-policy'>;
+}
+
 export declare interface ReportFieldDefinition {
     fieldName: string;
     columnName?: string;
@@ -160,11 +445,74 @@ export declare interface ReportFieldDefinition {
 
 export declare type ReportFieldMetadata = ReportGroupFieldMetadata | ReportBucketFieldMetadata | ReportAggregateFieldMetadata;
 
+/**
+ * Source-query clause a field belongs to. The materialized read executor
+ * applies both kinds through its tenant-scoped collection, but consumers use
+ * this declaration to keep dimensions/periods (WHERE) distinct from measures
+ * (HAVING) when constructing drilldowns, saved views, or a live query.
+ */
+export declare type ReportFilterScope = 'where' | 'having';
+
 export declare interface ReportGroupFieldMetadata {
     kind: 'group';
     sourceColumn?: string;
 }
 
+export declare interface ReportLifecycleOptions {
+    db: DatabaseInterface;
+    /** Test seam; production callers use the current clock. */
+    now?: Date;
+}
+
+export declare interface ReportLifecycleRun {
+    id: string;
+    status: 'running' | 'success' | 'failed' | 'skipped';
+    mode: ReportRefreshMode;
+    trigger: ReportRefreshTrigger;
+    startedAt?: string;
+    completedAt?: string;
+    rowCount: number;
+    changedGroupCount: number;
+    /** A failed run is safe to retry through the separately permissioned action. */
+    mayRetry: boolean;
+}
+
+/**
+ * Transport-neutral report lifecycle state. It deliberately never includes a
+ * lock owner, a raw failure message, or tenant fanout identifiers.
+ */
+export declare interface ReportLifecycleSnapshot {
+    version: 1;
+    state: ReportLifecycleState;
+    asOf?: string;
+    refreshedAt?: string;
+    /** Whether existing materialized rows can remain visible while work changes state. */
+    hasUsableRows: boolean;
+    mode: ReportRefreshMode;
+    run?: ReportLifecycleRun;
+    /** A stable, redacted failure signal; raw executor errors stay server-side. */
+    failure?: {
+        code: 'refresh_failed';
+        retryable: true;
+    };
+    lock: {
+        held: boolean;
+        expiresAt?: string;
+    };
+}
+
+export declare type ReportLifecycleState = 'current' | 'stale' | 'refreshing' | 'lock-skipped' | 'failed';
+
+/** Lifecycle context attached only when a caller explicitly opts in. */
+export declare interface ReportMaterializedReadLifecycle {
+    snapshot: ReportLifecycleSnapshot;
+    /** Whether this collection read appears to have completed a TTL refresh. */
+    read: 'current' | 'stale' | 'refresh-triggered';
+}
+
+/** Read the already-materialized primary key; never use a display/page index. */
+export declare function reportMaterializedRowKey(row: Record<string, unknown>): string;
+
 export declare interface ReportOptions {
     source: ReportSource;
     where?: WhereClause;
@@ -172,6 +520,82 @@ export declare interface ReportOptions {
     refresh?: ReportRefreshConfig;
 }
 
+declare interface ReportQueryCommonOptions {
+    /** Injected collection seam for tests and application-owned adapters. */
+    collection?: {
+        list(options: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+        count(options?: Record<string, unknown>): Promise<number>;
+        facets?(options: Record<string, unknown>): Promise<Array<{
+            field: string;
+            values: Array<{
+                value: string | number | boolean | null;
+                count: number;
+            }>;
+        }>>;
+    };
+    db?: DatabaseInterface;
+    /**
+     * Opt in to a tenant-safe lifecycle snapshot alongside this materialized
+     * read. It never makes a generic read mutate.
+     */
+    lifecycle?: Omit<ReportLifecycleOptions, 'db'>;
+}
+
+export declare interface ReportQueryExecutionDescriptor {
+    modes: ReportQueryExecutionMode[];
+    /** The caller may apply the returned rows to an already-authorized surface. */
+    visible: {
+        delivery: 'result';
+    };
+    /** A host queues the authority-free task and returns no materialized rows yet. */
+    background: {
+        delivery: 'queued';
+        requiresHost: true;
+    };
+    /** The caller receives rows but the adapter makes no visible-surface change. */
+    silent: {
+        delivery: 'result';
+        mutatesVisibleSurface: false;
+    };
+}
+
+/**
+ * Delivery choices for the same bounded report query. They never add
+ * authority: a host owns visible state and background-job execution.
+ */
+export declare type ReportQueryExecutionMode = 'visible' | 'background' | 'silent';
+
+/** Visible is the default; silent has identical data authority but no UI intent. */
+export declare interface ReportQueryOptions extends ReportQueryCommonOptions {
+    execution?: 'visible' | 'silent';
+}
+
+export declare interface ReportRefreshActionContext {
+    phase: 'preview' | 'apply';
+    reportClassName: string;
+    /** The action always applies to the caller's already-bound tenant scope. */
+    tenantScope: 'ambient';
+    mode: ReportRefreshMode;
+    requiredPermission: string;
+}
+
+/** A report-wide lifecycle action, never a mutation performed by this adapter. */
+export declare interface ReportRefreshActionDescriptor {
+    id: 'refresh';
+    label: 'Refresh report';
+    scope: 'surface';
+    phases: Array<'preview' | 'apply'>;
+    requiresPermission: true;
+    requiredPermission: string;
+    auditRequired: true;
+}
+
+/** Authority and audit stay with the application action host, not reports. */
+export declare interface ReportRefreshActionHost {
+    authorize(context: ReportRefreshActionContext): Promise<void> | void;
+    audit(context: ReportRefreshActionContext): Promise<void> | void;
+}
+
 export declare interface ReportRefreshConfig {
     mode?: ReportRefreshMode;
     schedule?: string;
@@ -190,9 +614,23 @@ export declare interface ReportRefreshConfig {
     tenantFanout?: boolean;
 }
 
+export declare interface ReportRefreshDescriptor {
+    mode: 'rebuild' | 'incremental';
+    /**
+     * Whether the report configuration lets a registered SmrtReportCollection
+     * synchronously refresh a stale read. Generic collection reads stay
+     * read-only and report unknown freshness until the lifecycle adapter runs.
+     */
+    mayRefreshOnRead: boolean;
+    ttlMs?: number;
+    triggers: Array<'manual' | 'schedule' | 'change' | 'ttl' | 'job'>;
+    /** Declared only; the lifecycle adapter owns authorization, audit, and run state. */
+    action: ReportRefreshActionDescriptor;
+}
+
 export declare interface ReportRefreshInterceptorOptions {
     db: DatabaseInterface;
-    reports: ReportCtor_2[];
+    reports: ReportCtor_3[];
     enqueue?: boolean;
     queue?: string;
     priority?: number;
@@ -213,6 +651,15 @@ export declare interface ReportRefreshJobArgs {
     _scheduleId?: string;
 }
 
+export declare interface ReportRefreshJobHandle {
+    jobId: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    attempts: number;
+    maxAttempts: number;
+    /** Bounded polling guidance; this API does not create a second queue. */
+    pollAfterMs: number;
+}
+
 export declare type ReportRefreshMode = 'rebuild' | 'incremental';
 
 export declare interface ReportRefreshOptions {
@@ -229,6 +676,27 @@ export declare interface ReportRefreshOptions {
     changedRows?: Record<string, unknown>[];
 }
 
+export declare interface ReportRefreshOutcome {
+    state: 'current' | 'lock-skipped' | 'partial';
+    rowCount: number;
+    changedGroupCount: number;
+    completedScopes: number;
+    lockSkippedScopes: number;
+    mode: ReportRefreshMode;
+    refreshedAt: string;
+    runId?: string;
+}
+
+/** Normalize executor results without exposing the tenant identifiers in a fanout. */
+export declare function reportRefreshOutcome(result: ReportRefreshResult): ReportRefreshOutcome;
+
+export declare interface ReportRefreshPreview {
+    phase: 'preview';
+    lifecycle: ReportLifecycleSnapshot;
+    action: ReportRefreshActionContext;
+    execution: 'background';
+}
+
 export declare interface ReportRefreshResult {
     rowCount: number;
     refreshedAt: Date;
@@ -396,6 +864,17 @@ export declare class SmrtReportWatermarkCollection extends SmrtCollection<SmrtRe
     static readonly _itemClass: typeof SmrtReportWatermark;
 }
 
+/**
+ * Split the declared filter language by report semantics for consumers that
+ * construct a live source query. Mixed AND expressions are represented as two
+ * independent clauses; mixed OR/NOT expressions are rejected because moving
+ * either half across WHERE/HAVING would change their meaning.
+ */
+export declare function splitReportFilterScopes(descriptor: ReportAdapterDescriptor, filter: DataQueryFilter | undefined): {
+    where?: DataQueryFilter;
+    having?: DataQueryFilter;
+};
+
 export declare const sum: (column?: string, options?: {
     distinct?: boolean;
 }) => PropertyDecorator;