@wtfalch/reporting 0.1.0

package/dist/tables.js

@@ -0,0 +1,55 @@
+import { sql } from 'drizzle-orm';
+import { bigint, index, jsonb, pgTable, smallint, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
+/**
+ * The three tables, mirrored from `migrations/0001_reporting.sql`, which is
+ * the source of truth: the SQL carries the CHECKs, the partial indexes, the
+ * generated column and the prune function that drizzle-kit does not
+ * generate. A host re-exports these from its own schema module so its
+ * drizzle instance and its types know them.
+ */
+export const reportingEvents = pgTable('reporting_events', {
+    id: bigint('id', { mode: 'number' }).generatedAlwaysAsIdentity().primaryKey(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().default(sql `now()`),
+    level: text('level').notNull(),
+    kind: text('kind').notNull(),
+    kindNs: text('kind_ns').generatedAlwaysAs(sql `split_part(kind, '.', 1)`),
+    site: text('site').notNull(),
+    tenantId: uuid('tenant_id'),
+    actorClass: text('actor_class'),
+    actorId: text('actor_id'),
+    requestId: text('request_id'),
+    targetType: text('target_type'),
+    targetId: text('target_id'),
+    message: text('message').notNull(),
+    data: jsonb('data').$type().notNull(),
+    schemaVersion: smallint('schema_version').notNull().default(1),
+}, (t) => [
+    index('reporting_events_time_idx').on(t.occurredAt.desc(), t.id.desc()),
+    // The partial predicates live in the SQL; these declare the columns.
+    index('reporting_events_tenant_time_idx').on(t.tenantId, t.occurredAt.desc(), t.id.desc()),
+    index('reporting_events_ns_time_idx').on(t.kindNs, t.occurredAt.desc(), t.id.desc()),
+    index('reporting_events_problem_time_idx').on(t.occurredAt.desc(), t.id.desc()),
+    index('reporting_events_request_idx').on(t.requestId, t.occurredAt.desc()),
+]);
+export const reportingTasks = pgTable('reporting_tasks', {
+    task: text('task').primaryKey(),
+    nextDueAt: timestamp('next_due_at', { withTimezone: true }).notNull().default(sql `now()`),
+    lastStartedAt: timestamp('last_started_at', { withTimezone: true }),
+    lastFinishedAt: timestamp('last_finished_at', { withTimezone: true }),
+    leaseExpiresAt: timestamp('lease_expires_at', { withTimezone: true }),
+    claimToken: uuid('claim_token'),
+    lastOutcome: text('last_outcome'),
+    lastError: text('last_error'),
+    watermark: text('watermark'),
+});
+export const reportingSettings = pgTable('reporting_settings', {
+    key: text('key').primaryKey(),
+    value: jsonb('value').notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().default(sql `now()`),
+    updatedBy: text('updated_by'),
+});
+export const tables = {
+    events: reportingEvents,
+    tasks: reportingTasks,
+    settings: reportingSettings,
+};

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { Actor, EventInput, FlatData, Level } from './schema.js';
+import type { ReportingEventRow, tables } from './tables.js';
+/**
+ * The host's drizzle handle, whatever driver it runs on. postgres-js in the
+ * apps, PGlite in this package's own tests; the queries here use nothing
+ * driver-specific.
+ */
+export type Db = PgDatabase<PgQueryResultHKT, any, any>;
+/** pino-shaped, so a host passes its logger and this package depends on none. */
+export interface Logger {
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+    error(obj: object, msg?: string): void;
+}
+export type Mode = 'production' | 'development' | 'test';
+/** What `alert()` takes: the shape the template's `alerts.ts` already produces. */
+export interface AlertFinding {
+    readonly check: string;
+    readonly message: string;
+    readonly detail?: unknown;
+}
+/** A settings change handed to the host's audit writer, when it bound one. */
+export interface SettingsChange {
+    readonly before: Settings;
+    readonly after: Settings;
+    readonly by: Actor;
+    readonly changed: readonly string[];
+}
+export interface Settings {
+    readonly 'events.retention_days': number;
+}
+export interface ReportingOptions {
+    db: Db;
+    log: Logger;
+    /** This host's id, stamped on every row: `^[a-z][a-z0-9-]{0,63}$`. */
+    site: string;
+    /**
+     * Runs a flush after the current unit of work. The `./next` entry passes
+     * `after()`; the default is `setTimeout(0)`, which a script keeps until it
+     * exits. Errors thrown by `fn` are the flush's own and never reach here.
+     */
+    defer?: (fn: () => Promise<void>) => void;
+    now?: () => Date;
+    /** Defaults from NODE_ENV: anything but `development` or `test` is production. */
+    mode?: Mode;
+    /** The host's second sink (Sentry, say). Called after the row is queued; a throw is swallowed. */
+    onAlert?: (finding: AlertFinding) => void;
+    /** Bound by the host to its audit ledger; called after a settings change commits. */
+    audit?: (change: SettingsChange) => Promise<void>;
+    /** Queue bound; past it rows go to the logger only. Default 1,000. */
+    queueLimit?: number;
+    /** Rows per insert. Default 500. */
+    batchSize?: number;
+    /** Timer flush interval, ms. Default 1,000. */
+    flushEveryMs?: number;
+}
+export interface EventsPageOptions {
+    readonly limit?: number;
+    readonly after?: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    };
+    readonly level?: Level;
+    readonly kindNs?: string;
+    readonly tenantId?: string;
+    readonly site?: string;
+    readonly requestId?: string;
+}
+export interface EventsPage {
+    readonly items: readonly ReportingEventRow[];
+    readonly next: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    } | null;
+}
+export interface Stats {
+    readonly queued: number;
+    readonly dropped: number;
+    readonly invalid: number;
+    readonly flushed: number;
+    readonly failedFlushes: number;
+}
+export interface Reporting {
+    /** Never throws in production; see writer.ts. */
+    event(input: EventInput): void;
+    /** An `alert.<check>` row at level `alert`, then the host's `onAlert`. */
+    alert(finding: AlertFinding): void;
+    /** Drain the queue now. Bounded by `deadlineMs` (default 5,000). Never throws. */
+    flush(opts?: {
+        deadlineMs?: number;
+    }): Promise<void>;
+    readonly events: {
+        page(opts?: EventsPageOptions): Promise<EventsPage>;
+    };
+    readonly settings: {
+        get(): Promise<Settings>;
+        set(patch: Partial<Settings>, by: Actor): Promise<SettingsChange>;
+    };
+    readonly tables: typeof tables;
+    readonly site: string;
+    readonly db: Db;
+    readonly log: Logger;
+    stats(): Stats;
+}
+export type { Actor, EventInput, FlatData, Level };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/writer.d.ts

@@ -0,0 +1,39 @@
+import type { Db, EventInput, Logger, Mode, Stats } from './types.js';
+export interface WriterOptions {
+    db: Db;
+    log: Logger;
+    site: string;
+    mode: Mode;
+    now: () => Date;
+    defer: (fn: () => Promise<void>) => void;
+    queueLimit: number;
+    batchSize: number;
+    flushEveryMs: number;
+}
+export declare class Writer {
+    private readonly o;
+    private readonly queue;
+    private inFlight;
+    private timer;
+    private deferred;
+    private dropped;
+    private droppedSinceReport;
+    private invalid;
+    private flushed;
+    private failedFlushes;
+    constructor(o: WriterOptions);
+    event(input: EventInput): void;
+    private toRow;
+    private enqueue;
+    /** Once per idle period through `defer`, and always on the timer. */
+    private schedule;
+    /** Drain until empty or the deadline. One flush in flight at a time; a second call waits on the first. */
+    flush(opts?: {
+        deadlineMs?: number;
+    }): Promise<void>;
+    private lastFailed;
+    private flushOnce;
+    stats(): Stats;
+}
+/** A string for the logger, never the error object: an error's `cause` can carry a request body. */
+export declare function describe(error: unknown): string;

package/dist/writer.js

@@ -0,0 +1,166 @@
+import { eventInputSchema } from './schema.js';
+import { reportingEvents } from './tables.js';
+export class Writer {
+    o;
+    queue = [];
+    inFlight = null;
+    timer = null;
+    deferred = false;
+    dropped = 0;
+    droppedSinceReport = 0;
+    invalid = 0;
+    flushed = 0;
+    failedFlushes = 0;
+    constructor(o) {
+        this.o = o;
+    }
+    event(input) {
+        const parsed = eventInputSchema.safeParse(input);
+        if (!parsed.success) {
+            this.invalid += 1;
+            const issue = parsed.error.issues[0];
+            const where = issue ? `${issue.path.join('.') || '(root)'}: ${issue.message}` : 'invalid';
+            if (this.o.mode !== 'production') {
+                throw new Error(`reporting.event refused: ${where}`);
+            }
+            // The offending payload is exactly what must not be written; the
+            // kind, if it is even a string, and the failing path are enough.
+            const kind = typeof input?.kind === 'string' ? input.kind.slice(0, 128) : '(not a string)';
+            this.o.log.error({ kind, issue: where }, 'reporting: event refused');
+            this.enqueue(this.toRow({
+                kind: 'reporting.invalid',
+                level: 'error',
+                message: `event refused: ${where}`.slice(0, 512),
+                data: { kind },
+                tenantId: null,
+                actor: null,
+                requestId: null,
+                target: null,
+            }));
+            return;
+        }
+        const row = this.toRow(parsed.data);
+        this.o.log[parsed.data.level === 'alert' ? 'warn' : parsed.data.level]({
+            site: row.site,
+            kind: row.kind,
+            tenantId: row.tenantId,
+            requestId: row.requestId,
+            data: row.data,
+        }, row.message);
+        this.enqueue(row);
+    }
+    toRow(v) {
+        return {
+            occurredAt: v.occurredAt ?? this.o.now(),
+            level: v.level,
+            kind: v.kind,
+            site: this.o.site,
+            tenantId: v.tenantId ?? null,
+            actorClass: v.actor?.class ?? null,
+            actorId: v.actor?.id ?? null,
+            requestId: v.requestId ?? null,
+            targetType: v.target?.type ?? null,
+            targetId: v.target?.id ?? null,
+            message: v.message,
+            data: v.data,
+        };
+    }
+    enqueue(row) {
+        if (this.queue.length >= this.o.queueLimit) {
+            this.dropped += 1;
+            this.droppedSinceReport += 1;
+            return;
+        }
+        this.queue.push(row);
+        this.schedule();
+    }
+    /** Once per idle period through `defer`, and always on the timer. */
+    schedule() {
+        if (!this.deferred) {
+            this.deferred = true;
+            try {
+                this.o.defer(() => this.flush({ deadlineMs: 5000 }));
+            }
+            catch (error) {
+                // A host's defer that throws (called outside a request scope, say)
+                // must not take the event with it; the timer still runs.
+                this.o.log.warn({ err: describe(error) }, 'reporting: defer threw; relying on the timer');
+            }
+        }
+        if (!this.timer) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                void this.flush({ deadlineMs: 5000 });
+            }, this.o.flushEveryMs);
+            this.timer.unref?.();
+        }
+    }
+    /** Drain until empty or the deadline. One flush in flight at a time; a second call waits on the first. */
+    async flush(opts = {}) {
+        const deadline = Date.now() + (opts.deadlineMs ?? 5000);
+        if (this.inFlight)
+            await this.inFlight;
+        while (this.queue.length > 0 && Date.now() < deadline) {
+            this.inFlight = this.flushOnce();
+            try {
+                await this.inFlight;
+            }
+            finally {
+                this.inFlight = null;
+            }
+            if (this.failedFlushes > 0 && this.queue.length > 0 && this.lastFailed)
+                break;
+        }
+        this.deferred = false;
+    }
+    lastFailed = false;
+    async flushOnce() {
+        const batch = this.queue.splice(0, this.o.batchSize);
+        if (this.droppedSinceReport > 0) {
+            const count = this.droppedSinceReport;
+            this.droppedSinceReport = 0;
+            batch.push(this.toRow({
+                kind: 'reporting.dropped',
+                level: 'warn',
+                message: `${count} event(s) went to the logger only: the queue was full`,
+                data: { count },
+                tenantId: null,
+                actor: null,
+                requestId: null,
+                target: null,
+            }));
+        }
+        try {
+            await this.o.db.insert(reportingEvents).values(batch);
+            this.flushed += batch.length;
+            this.lastFailed = false;
+        }
+        catch (error) {
+            this.failedFlushes += 1;
+            this.lastFailed = true;
+            // Back at the front, so order survives; the bound still applies, and
+            // whatever does not fit is counted as dropped rather than kept for ever.
+            const room = Math.max(0, this.o.queueLimit - this.queue.length);
+            const kept = batch.slice(0, room);
+            this.dropped += batch.length - kept.length;
+            this.droppedSinceReport += batch.length - kept.length;
+            this.queue.unshift(...kept);
+            this.o.log.error({ err: describe(error), rows: batch.length, queued: this.queue.length }, 'reporting: flush failed; rows stay queued');
+        }
+    }
+    stats() {
+        return {
+            queued: this.queue.length,
+            dropped: this.dropped,
+            invalid: this.invalid,
+            flushed: this.flushed,
+            failedFlushes: this.failedFlushes,
+        };
+    }
+}
+/** A string for the logger, never the error object: an error's `cause` can carry a request body. */
+export function describe(error) {
+    if (error instanceof Error)
+        return `${error.name}: ${error.message}`.slice(0, 500);
+    return String(error).slice(0, 500);
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@wtfalch/reporting",
+  "version": "0.1.0",
+  "description": "The estate's operational event log and housekeeping tick: a writer that never fails a request, a claim protocol that needs no scheduler, and the readers an operator opens. Per-app Postgres, host-supplied logger, framework-neutral core with a Next entry.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfalch/reporting",
+    "directory": "packages/reporting"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist"],
+  "bin": {
+    "reporting-migrations": "./dist/bin/migrations.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./housekeeping": {
+      "types": "./dist/housekeeping/index.d.ts",
+      "default": "./dist/housekeeping/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./fake": {
+      "types": "./dist/fake/index.d.ts",
+      "default": "./dist/fake/index.js"
+    },
+    "./migrations/*.sql": "./dist/migrations/*.sql",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/migrations && cp src/migrations/*.sql dist/migrations/",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.39.0",
+    "next": ">=16.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@types/node": "^22",
+    "drizzle-orm": "^0.39.3",
+    "next": "^16.2.4",
+    "postgres": "^3.4.5",
+    "react": "^19",
+    "react-dom": "^19",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6",
+    "zod": "^4.5.4"
+  }
+}