@wtfalch/reporting 0.1.2 → 0.3.0

package/dist/tables.js

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { bigint, index, jsonb, pgTable, smallint, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
+import { bigint, date, index, integer, jsonb, pgTable, primaryKey, 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
@@ -48,6 +48,8 @@ export const reportingTasks = pgTable('reporting_tasks', {
     claimToken: uuid('claim_token'),
     lastOutcome: text('last_outcome'),
     lastError: text('last_error'),
+    /** The rollups' completed-history watermark (0002), one value per task. */
+    watermark: text('watermark'),
 });
 export const reportingSettings = pgTable('reporting_settings', {
     key: text('key').primaryKey(),
@@ -55,8 +57,116 @@ export const reportingSettings = pgTable('reporting_settings', {
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().default(sql `now()`),
     updatedBy: text('updated_by'),
 });
+/** Raw analytics rows, a window's worth; mirrored from migrations/0002_analytics.sql. */
+export const reportingAnalytics = pgTable('reporting_analytics', {
+    id: bigint('id', { mode: 'number' }).generatedAlwaysAsIdentity().primaryKey(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull(),
+    receivedAt: timestamp('received_at', { withTimezone: true }).notNull().default(sql `now()`),
+    site: text('site').notNull(),
+    tenantId: uuid('tenant_id'),
+    visitorId: text('visitor_id'),
+    sessionId: text('session_id'),
+    userId: text('user_id'),
+    name: text('name').notNull(),
+    path: text('path').notNull(),
+    referrerHost: text('referrer_host'),
+    device: text('device').notNull(),
+    country: text('country'),
+    props: jsonb('props')
+        .$type()
+        .notNull()
+        .default(sql `'{}'::jsonb`),
+    schemaVersion: smallint('schema_version').notNull().default(1),
+}, (t) => [
+    index('reporting_analytics_site_time_idx').on(t.site, t.occurredAt.desc(), t.id.desc()),
+    index('reporting_analytics_tenant_time_idx')
+        .on(t.tenantId, t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.tenantId} is not null`),
+    index('reporting_analytics_user_idx').on(t.userId).where(sql `${t.userId} is not null`),
+    index('reporting_analytics_site_name_time_idx').on(t.site, t.name, t.occurredAt.desc()),
+]);
+/** One row per day, site, grain and dimension value; written only by reporting_rollup_day. */
+export const reportingAnalyticsDaily = pgTable('reporting_analytics_daily', {
+    day: date('day').notNull(),
+    site: text('site').notNull(),
+    grain: text('grain').notNull(),
+    tenantId: uuid('tenant_id'),
+    name: text('name'),
+    path: text('path'),
+    device: text('device'),
+    country: text('country'),
+    referrerHost: text('referrer_host'),
+    views: integer('views').notNull(),
+    visitors: integer('visitors').notNull(),
+    people: integer('people').notNull(),
+    tenantKey: text('tenant_key').generatedAlwaysAs(sql `coalesce(tenant_id::text, '')`),
+    nameKey: text('name_key').generatedAlwaysAs(sql `coalesce(name, '')`),
+    pathKey: text('path_key').generatedAlwaysAs(sql `coalesce(path, '')`),
+    deviceKey: text('device_key').generatedAlwaysAs(sql `coalesce(device, '')`),
+    countryKey: text('country_key').generatedAlwaysAs(sql `coalesce(country, '')`),
+    referrerKey: text('referrer_key').generatedAlwaysAs(sql `coalesce(referrer_host, '')`),
+}, (t) => [
+    primaryKey({
+        name: 'reporting_analytics_daily_pkey',
+        columns: [
+            t.day,
+            t.site,
+            t.grain,
+            t.tenantKey,
+            t.nameKey,
+            t.pathKey,
+            t.deviceKey,
+            t.countryKey,
+            t.referrerKey,
+        ],
+    }),
+    index('reporting_analytics_daily_site_grain_idx').on(t.site, t.grain, t.day.desc()),
+]);
+/** Visitors and people per ISO week and how many returned; written only by reporting_rollup_week. */
+export const reportingAnalyticsWeekly = pgTable('reporting_analytics_weekly', {
+    week: date('week').notNull(),
+    site: text('site').notNull(),
+    tenantId: uuid('tenant_id'),
+    visitors: integer('visitors').notNull(),
+    returningVisitors: integer('returning_visitors').notNull(),
+    people: integer('people').notNull(),
+    returningPeople: integer('returning_people').notNull(),
+    tenantKey: text('tenant_key').generatedAlwaysAs(sql `coalesce(tenant_id::text, '')`),
+}, (t) => [
+    primaryKey({
+        name: 'reporting_analytics_weekly_pkey',
+        columns: [t.week, t.site, t.tenantKey],
+    }),
+]);
+/** One row per fingerprint; mirrored from migrations/0003_errors.sql. */
+export const reportingErrors = pgTable('reporting_errors', {
+    fingerprint: text('fingerprint').primaryKey(),
+    site: text('site').notNull(),
+    kind: text('kind').notNull(),
+    message: text('message').notNull(),
+    stack: text('stack'),
+    runtime: text('runtime').notNull(),
+    release: text('release'),
+    firstSeenAt: timestamp('first_seen_at', { withTimezone: true }).notNull(),
+    lastSeenAt: timestamp('last_seen_at', { withTimezone: true }).notNull(),
+    occurrences: bigint('occurrences', { mode: 'number' }).notNull().default(1),
+    state: text('state').notNull().default('open'),
+    resolvedAt: timestamp('resolved_at', { withTimezone: true }),
+    resolvedBy: text('resolved_by'),
+    tenantId: uuid('tenant_id'),
+    requestId: text('request_id'),
+}, (t) => [
+    index('reporting_errors_site_open_idx')
+        .on(t.site, t.lastSeenAt.desc())
+        .where(sql `${t.state} = 'open'`),
+    index('reporting_errors_state_idx').on(t.state, t.lastSeenAt.desc()),
+]);
 export const tables = {
     events: reportingEvents,
     tasks: reportingTasks,
     settings: reportingSettings,
+    analytics: reportingAnalytics,
+    analyticsDaily: reportingAnalyticsDaily,
+    analyticsWeekly: reportingAnalyticsWeekly,
+    errors: reportingErrors,
 };

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 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';
+import type { RecentEvent, RecentOptions, SeriesOptions, SeriesPoint, WeeklyPoint } from './analytics/reader.js';
+import type { Device } from './analytics/schema.js';
+import type { Actor, ErrorRuntime, ErrorState, EventInput, FlatData, Level } from './schema.js';
+import type { ReportingErrorRow, 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
@@ -27,8 +29,12 @@ export interface SettingsChange {
     readonly by: Actor;
     readonly changed: readonly string[];
 }
+export type ConsentMode = 'none' | 'consented' | 'always';
 export interface Settings {
     readonly 'events.retention_days': number;
+    readonly 'analytics.retention_days': number;
+    readonly 'analytics.consent': ConsentMode;
+    readonly 'analytics.identify_signed_in': boolean;
 }
 export interface ReportingOptions {
     db: Db;
@@ -48,6 +54,8 @@ export interface ReportingOptions {
     onAlert?: (finding: AlertFinding) => void;
     /** Bound by the host to its audit ledger; called after a settings change commits. */
     audit?: (change: SettingsChange) => Promise<void>;
+    /** The host's route normalisation for analytics paths (addendum A7); the package's default otherwise. */
+    normalisePath?: (pathname: string) => string;
     /** Queue bound; past it rows go to the logger only. Default 1,000. */
     queueLimit?: number;
     /** Rows per insert. Default 500. */
@@ -74,17 +82,76 @@ export interface EventsPage {
         readonly id: number;
     } | null;
 }
+export interface ErrorsPageOptions {
+    readonly limit?: number;
+    readonly after?: {
+        readonly lastSeenAt: Date;
+        readonly fingerprint: string;
+    };
+    readonly site?: string;
+    readonly state?: ErrorState;
+    readonly runtime?: ErrorRuntime;
+}
+export interface ErrorsPage {
+    readonly items: readonly ReportingErrorRow[];
+    readonly next: {
+        readonly lastSeenAt: Date;
+        readonly fingerprint: string;
+    } | null;
+}
+/**
+ * What `captureError` knows about an exception's surroundings; every field
+ * is optional because a boot-time crash has none of them.
+ */
+export interface CaptureContext {
+    readonly runtime?: ErrorRuntime;
+    readonly tenantId?: string | null;
+    readonly requestId?: string | null;
+    readonly release?: string | null;
+    /** Overrides `errorKind(error)` when the caller already knows the class name better than the thrown value can say — a JSON-serialised browser report, say. */
+    readonly kind?: string;
+}
 export interface Stats {
     readonly queued: number;
     readonly dropped: number;
     readonly invalid: number;
     readonly flushed: number;
 }
+/** A server-side analytics event: the server's truth about something a person did, with identity from the `Access`, never a claim. */
+export interface TrackInput {
+    readonly name: string;
+    readonly props?: Record<string, string | number | boolean | null>;
+    readonly tenantId?: string | null;
+    /** The signed-in person's id, from the host's resolved principal. */
+    readonly userId?: string | null;
+    /** The pathname the event belongs to; normalised before storage. Default `/`. */
+    readonly path?: string;
+    readonly device?: Device;
+    readonly country?: string | null;
+    /** The consent cookie's value, when the host passes it through. */
+    readonly visitorId?: string | null;
+    readonly sessionId?: string | null;
+    readonly occurredAt?: Date;
+}
+export interface Analytics {
+    /** Never throws in production: a failed insert is a log line. */
+    track(input: TrackInput): Promise<void>;
+    series(opts: SeriesOptions): Promise<readonly SeriesPoint[]>;
+    weekly(opts: {
+        site: string;
+        tenantId?: string;
+        from: string;
+        to: string;
+    }): Promise<readonly WeeklyPoint[]>;
+    recent(opts: RecentOptions): Promise<readonly RecentEvent[]>;
+}
 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;
+    /** An uncaught exception, redacted and fingerprinted (./errors/capture.js). Never throws. */
+    captureError(error: unknown, context?: CaptureContext): void;
     /** Drain the queue now. Bounded by `deadlineMs` (default 5,000). Never throws. */
     flush(opts?: {
         deadlineMs?: number;
@@ -99,6 +166,7 @@ export interface Reporting {
     readonly tables: typeof tables;
     readonly site: string;
     readonly log: Logger;
+    readonly analytics: Analytics;
     stats(): Stats;
 }
 export type { Actor, EventInput, FlatData, Level };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/reporting",
-  "version": "0.1.2",
+  "version": "0.3.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",
@@ -30,6 +30,22 @@
       "types": "./dist/fake/index.d.ts",
       "default": "./dist/fake/index.js"
     },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./react/charts": {
+      "types": "./dist/react/charts.d.ts",
+      "default": "./dist/react/charts.js"
+    },
+    "./react/errors": {
+      "types": "./dist/react/errors.d.ts",
+      "default": "./dist/react/errors.js"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
@@ -49,6 +65,7 @@
   "peerDependencies": {
     "drizzle-orm": ">=0.39.0",
     "next": ">=16.0.0",
+    "react": ">=19.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -59,6 +76,7 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@types/react": "^19",
     "drizzle-orm": "^0.39.3",
     "next": "^16.2.4",
     "postgres": "^3.4.5",