@happyvertical/smrt-reports 0.40.14 → 0.40.15

package/README.md

@@ -0,0 +1,110 @@
+# @happyvertical/smrt-reports
+
+Materialized aggregate reports for s-m-r-t. Define a report as a decorated class,
+compile it to a portable aggregate query, and refresh its normal s-m-r-t table
+manually, on a schedule, after source changes, or when a TTL expires.
+
+Runtime refresh verifies schema but does not create report or system tables.
+Include report models in normal manifest-driven migrations before refreshing.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-reports
+```
+
+## Define a report
+
+```ts
+import { SmrtObject, smrt } from '@happyvertical/smrt-core';
+import {
+  groupBy,
+  month,
+  report,
+  SmrtReport,
+  SmrtReportCollection,
+  sum,
+} from '@happyvertical/smrt-reports';
+
+@smrt()
+class Invoice extends SmrtObject {
+  customerId = '';
+  issuedAt = new Date();
+  totalAmount = 0.0;
+  status = '';
+}
+
+@report({
+  source: Invoice,
+  where: { status: 'paid' },
+  refresh: { manual: true },
+})
+@smrt()
+class MonthlyRevenue extends SmrtReport {
+  @groupBy('customerId') customerId = '';
+  @month('issuedAt') issuedMonth = new Date();
+  @sum('totalAmount') revenue = 0.0;
+}
+
+class MonthlyRevenueCollection extends SmrtReportCollection<MonthlyRevenue> {
+  static readonly _itemClass = MonthlyRevenue;
+}
+
+const reports = await MonthlyRevenueCollection.create({ db: 'app.db' });
+await reports.refresh();
+const rows = await reports.list({ orderBy: 'issued_month DESC' });
+```
+
+## Decorators
+
+| Decorator | Meaning |
+| --- | --- |
+| `@report({ source, ... })` | Declare the source and refresh policy |
+| `@groupBy(column?)` | Group by a source column |
+| `@minute()` through `@year()` | Bucket a source timestamp |
+| `@sum()`, `@avg()`, `@min()`, `@max()` | Aggregate a source column |
+| `@count()` | Count rows or distinct values |
+| `@aggregate()` | Define a custom supported aggregate shape |
+
+Every non-system report field must be a grouping key, time bucket, or aggregate.
+Metadata is stored under the field's `_meta.__report` contract so scanner and
+runtime compilation stay aligned.
+
+## Refresh modes
+
+- `rebuild` replaces the materialized result.
+- `incremental` recomputes groups affected after a source watermark and removes
+  groups that become empty.
+- TTL-backed collections refresh before reads when the report is stale.
+- `ReportScheduleRunner` and `registerReportRefreshInterceptor()` enqueue
+  durable refresh jobs through [`smrt-jobs`](../jobs/README.md).
+
+Incremental sources need watermark and soft-delete columns, normally
+`updatedAt` and `deletedAt`. Tenant-scoped aggregate SQL explicitly filters
+`tenant_id`; normal collection interceptors cannot secure a raw aggregate.
+
+## Public entry points
+
+The package exposes focused subpaths for consumers that want only the compiler,
+decorators, refresh engine, scheduler, state models, or aggregate compatibility
+helpers:
+
+```text
+@happyvertical/smrt-reports
+@happyvertical/smrt-reports/compiler
+@happyvertical/smrt-reports/decorators
+@happyvertical/smrt-reports/refresh
+@happyvertical/smrt-reports/scheduler
+@happyvertical/smrt-reports/state
+@happyvertical/smrt-reports/aggregate
+```
+
+## Development
+
+```bash
+pnpm --filter @happyvertical/smrt-reports test
+pnpm --filter @happyvertical/smrt-reports typecheck
+pnpm --filter @happyvertical/smrt-reports build
+```
+
+See [`AGENTS.md`](./AGENTS.md) for refresh, schema, and tenancy invariants.

package/dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "version": "1.0.0",
-  "timestamp": 1784377940326,
+  "timestamp": 1784492242116,
   "packageName": "@happyvertical/smrt-reports",
-  "packageVersion": "0.40.14",
+  "packageVersion": "0.40.15",
   "objects": {
     "@happyvertical/smrt-reports:SmrtReport": {
       "name": "smrtreport",

package/dist/smrt-knowledge.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-18T12:32:29.039Z",
+  "generatedAt": "2026-07-19T20:17:31.040Z",
   "packageName": "@happyvertical/smrt-reports",
-  "packageVersion": "0.40.14",
+  "packageVersion": "0.40.15",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "c81c4fd4fff63c5b7f8cdb49c493b87605d1391a947b74a6838e2bebb8b3462e",
-    "packageJson": "f8aabe8d4360601901d4fe5add2ff8539a85c39066d6245ba68ac675d4cdb80c",
+    "manifest": "e11e5d6b5cee5a404d31f2cb2385a04ce86b9485bdc38f899bed958efffcb204",
+    "packageJson": "8d5de5bb1d6294c678f520f07a47a73cdca2b59fe3c5b75be44098e6da922ab6",
     "agents": "bf851be60baab2fd98149165885f70c4f4979123ff72bf8f4b43edfae4478e87"
   },
   "exports": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-reports",
-  "version": "0.40.14",
+  "version": "0.40.15",
   "description": "Materialized aggregate report models for SMRT",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,16 +44,16 @@
   },
   "dependencies": {
     "@happyvertical/sql": "^0.80.2",
-    "@happyvertical/smrt-jobs": "0.40.14",
-    "@happyvertical/smrt-core": "0.40.14",
-    "@happyvertical/smrt-tenancy": "0.40.14"
+    "@happyvertical/smrt-core": "0.40.15",
+    "@happyvertical/smrt-jobs": "0.40.15",
+    "@happyvertical/smrt-tenancy": "0.40.15"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-vitest": "0.40.14"
+    "@happyvertical/smrt-vitest": "0.40.15"
   },
   "keywords": [
     "ai",