@wtfalch/reporting 0.1.2 → 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
@@ -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,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. */
@@ -80,6 +88,34 @@ export interface Stats {
     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;
@@ -99,6 +135,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.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",