@wtfalch/reporting 0.1.1 → 0.2.1

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
@@ -21,15 +21,23 @@ export const reportingEvents = pgTable('reporting_events', {
     targetType: text('target_type'),
     targetId: text('target_id'),
     message: text('message').notNull(),
-    data: jsonb('data').$type().notNull(),
+    data: jsonb('data')
+        .$type()
+        .notNull()
+        .default(sql `'{}'::jsonb`),
     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_tenant_time_idx')
+        .on(t.tenantId, t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.tenantId} is not null`),
     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()),
+    index('reporting_events_problem_time_idx')
+        .on(t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.level} in ('error', 'alert')`),
+    index('reporting_events_request_idx')
+        .on(t.requestId, t.occurredAt.desc())
+        .where(sql `${t.requestId} is not null`),
 ]);
 export const reportingTasks = pgTable('reporting_tasks', {
     task: text('task').primaryKey(),
@@ -40,6 +48,7 @@ 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', {
@@ -48,8 +57,92 @@ 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],
+    }),
+]);
 export const tables = {
     events: reportingEvents,
     tasks: reportingTasks,
     settings: reportingSettings,
+    analytics: reportingAnalytics,
+    analyticsDaily: reportingAnalyticsDaily,
+    analyticsWeekly: reportingAnalyticsWeekly,
 };

package/dist/types.d.ts

@@ -1,4 +1,6 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { RecentEvent, RecentOptions, SeriesOptions, SeriesPoint, WeeklyPoint } from './analytics/reader.js';
+import type { Device } from './analytics/schema.js';
 import type { Actor, EventInput, FlatData, Level } from './schema.js';
 import type { ReportingEventRow, tables } from './tables.js';
 /**
@@ -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. */
@@ -79,7 +87,34 @@ export interface Stats {
     readonly dropped: number;
     readonly invalid: number;
     readonly flushed: number;
-    readonly failedFlushes: 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. */
@@ -99,8 +134,8 @@ export interface Reporting {
     };
     readonly tables: typeof tables;
     readonly site: string;
-    readonly db: Db;
     readonly log: Logger;
+    readonly analytics: Analytics;
     stats(): Stats;
 }
 export type { Actor, EventInput, FlatData, Level };

package/dist/writer.d.ts

@@ -20,7 +20,6 @@ export declare class Writer {
     private droppedSinceReport;
     private invalid;
     private flushed;
-    private failedFlushes;
     constructor(o: WriterOptions);
     event(input: EventInput): void;
     private toRow;

package/dist/writer.js

@@ -10,7 +10,6 @@ export class Writer {
     droppedSinceReport = 0;
     invalid = 0;
     flushed = 0;
-    failedFlushes = 0;
     constructor(o) {
         this.o = o;
     }
@@ -119,8 +118,7 @@ export class Writer {
                 ok = await attempt;
             }
             finally {
-                if (this.inFlight === attempt)
-                    this.inFlight = null;
+                this.inFlight = null;
             }
             // A failed insert leaves its rows queued; do not spin on the database
             // inside one call. The timer and the next defer try again.
@@ -152,7 +150,6 @@ export class Writer {
             return true;
         }
         catch (error) {
-            this.failedFlushes += 1;
             // 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);
@@ -170,7 +167,6 @@ export class Writer {
             dropped: this.dropped,
             invalid: this.invalid,
             flushed: this.flushed,
-            failedFlushes: this.failedFlushes,
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/reporting",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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,18 @@
       "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"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
@@ -49,6 +61,7 @@
   "peerDependencies": {
     "drizzle-orm": ">=0.39.0",
     "next": ">=16.0.0",
+    "react": ">=19.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -59,6 +72,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",