hazo_umetrics 0.1.1

package/CHANGE_LOG.md

@@ -0,0 +1,28 @@
+# hazo_umetrics — Change Log
+
+## 0.1.1 — 2026-06-12
+
+**Fixed:**
+- `StatTrend` now uses `hazo_ui`'s `LineChart` instead of a minimal SVG sparkline — renders X-axis date labels, Y-axis gridlines with min/mid/max, and a hover cursor + value tooltip. Requires `hazo_ui` peer dep (already declared).
+- Test-app Admin Mount: `/api/hazo_auth/me` response parsed correctly (`{ authenticated, user, permissions }` flat shape); was checking for non-existent `{ ok, data }` wrapper — Admin Mount now renders for `metrics.view` users.
+- Test-app Event Log eval form: field names corrected to `experimentKey`/`subjectId` (camelCase) matching the `evalVariant` handler; was sending `key`/`subject_id` → `400 BAD_REQUEST`.
+- Test-app `globals.css`: import `hazo_ui/dist/styles.css` + `@theme inline` color-utility mapping fixes transparent `HazoUiDialog` panel on pure Tailwind v4 apps.
+
+## 0.1.0 — 2026-06-12
+
+M0 Core: headless spine + jest-verified logic. Interactive test-app is M0 Interactive (next session).
+
+**Added:**
+- Package scaffold: 4 entry points (server / client / api / ui), version 0.1.0, peer deps at canonical versions.
+- 7-table DB schema (SQLite + PostgreSQL): `hazo_umetrics_stat`, `_stat_def`, `_experiment`, `_assignment`, `_exposure`, `_ga4_connection`, `_dashboard`. All tables carry `scope_id`.
+- Stat store: `recordStat` (append-only), `getLatestStat`, `getStatSeries`, `registerStatCollector`, `runStatSnapshot`, `statSnapshotJob` (MaintenanceJob shape for M1 hazo_jobs wiring).
+- Flag engine: `cyrb53` pure-JS hash, `weightedBucket` (D-5 general named-variant), `resolveVariant` with 3 consent paths (logged-in sticky / anon+consent cookie / anon no-consent ephemeral), `getVariant`, `isEnabled`.
+- Cookie: `signSubjectCookie` / `readSubjectCookie` via `hazo_secure/crypto` AES-GCM (D-7).
+- GA4 stubs: `createGa4Client`, `createGa4Provisioner` (STUB M1).
+- Experiment significance stubs: `computeSignificance`, `estimateSampleSize` (STUB M2).
+- API route factories: `createStatHandlers`, `createExperimentHandlers`, `createGa4ConnectHandlers`, `createQueryHandlers`; injectable `getAuth` + `onAudit`; manage routes gate on `metrics.manage`.
+- Client entry: `HazoMetricsProvider`, `useMetrics`, `getVariant`, `isEnabled`, `identify`, `recordStat` (client shells, M1 wiring deferred).
+- UI entry: `MetricsPanel`, `StatCards`, `StatTrend` (minimal shells, M1 wiring deferred).
+- 49 jest tests: stat suite (8), flags suite (18), API suite (23).
+- `metrics.manage: 'metrics.manage'` added to `hazo_admin` `HAZO_ADMIN_PERMISSIONS` (hazo_admin v0.3.1).
+- Config sample: `[env]`, `[ga4]`, `[stats]`, `[ab_cookie]`, `[retention]` sections.

package/README.md

@@ -0,0 +1,129 @@
+# hazo_umetrics
+
+Product analytics for hazo apps — GA4 hybrid + first-party stat store + feature flags.
+
+Gives every hazo Next.js app one consistent, auth-gated way to understand user behaviour:
+- **GA4 hybrid** — traffic, SEO, and conversion funnels read via the GA4 Data API; auto-provisioned via GA4 Admin API (M1).
+- **Stat store** — first-party numeric metrics over time, collector pattern, sparkline history.
+- **Feature flags** — deterministic weighted-variant bucketing, signed consent cookie, sticky assignment.
+- **A/B experiments** — same engine as flags + significance (deferred until traffic justifies it).
+
+All surfaces mount inside `hazo_admin` via the existing `kind:'metrics'` section; every read/write is `scope_id`-gated.
+
+## Status
+
+M0 Core shipped. M0 Interactive test-app is live (Admin Mount, Event Log, Metrics, Autotest). See `design/master_plan.md`.
+
+## Installation
+
+```bash
+npm install hazo_umetrics
+```
+
+**Peer dependencies (install the ones you use):**
+
+```bash
+npm install hazo_core hazo_connect hazo_auth hazo_secure hazo_audit hazo_api hazo_ui
+```
+
+Required env vars for cookie signing (A/B assignment):
+```
+HAZO_UMETRICS_COOKIE_KEY_CURRENT=v1
+HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte AES-256 key>
+```
+
+## Entry points
+
+| Import path | Contents |
+|---|---|
+| `hazo_umetrics` | Server: recordStat, getLatestStat, getStatSeries, resolveVariant, weightedBucket, GA4/experiment stubs |
+| `hazo_umetrics/api` | Route factories: createStatHandlers, createExperimentHandlers, createGa4ConnectHandlers, createQueryHandlers |
+| `hazo_umetrics/client` | Client: HazoMetricsProvider, useMetrics, getVariant, isEnabled, identify, recordStat |
+| `hazo_umetrics/ui` | UI: MetricsPanel, StatCards, StatTrend (uses hazo_ui LineChart — requires hazo_ui peer dep) |
+
+## Stat store
+
+```ts
+import { recordStat, getLatestStat, getStatSeries, registerStatCollector, runStatSnapshot } from 'hazo_umetrics';
+
+// Append a reading (always inserts, never upserts)
+await recordStat(adapter, { scope_id: 'my-app', metric_key: 'active_users', value: 42 });
+
+// Latest value
+const stat = await getLatestStat(adapter, { scope_id: 'my-app', metric_key: 'active_users' });
+
+// Series (ascending by captured_at)
+const series = await getStatSeries(adapter, { scope_id: 'my-app', metric_key: 'active_users', limit: 30 });
+
+// Register a collector (runs in runStatSnapshot)
+registerStatCollector({
+  key: 'active_users',
+  label: 'Active users',
+  format: 'count',
+  collect: async (scope_id) => countActiveUsers(scope_id),
+});
+
+// Run all collectors (call on a schedule via hazo_jobs in M1)
+const results = await runStatSnapshot(adapter, { scope_id: 'my-app' });
+```
+
+## Feature flags
+
+```ts
+import { resolveVariant, getVariant, isEnabled } from 'hazo_umetrics';
+
+// Evaluate a flag with logged-in user (sticky assignment)
+const { variant } = await resolveVariant(adapter, {
+  experimentKey: 'new_dashboard',
+  scope_id: 'my-app',
+  subjectId: user.id,
+  consent: true,
+});
+
+// Boolean flag shorthand
+const enabled = await isEnabled(adapter, { experimentKey: 'new_feature', scope_id, subjectId });
+```
+
+## API route factories
+
+```ts
+import { createStatHandlers, createExperimentHandlers } from 'hazo_umetrics/api';
+
+const statHandlers = createStatHandlers({ getAdapter: () => myAdapter });
+// → statHandlers.getStat, statHandlers.getStatSeries, statHandlers.recordStat
+
+const expHandlers = createExperimentHandlers({ getAdapter: () => myAdapter });
+// → expHandlers.listExperiments (metrics.view), expHandlers.startExperiment (metrics.manage)
+```
+
+## DB setup
+
+Run `db_setup_sqlite.sql` (SQLite) or `db_setup_postgres.sql` (PostgreSQL) once. Creates 7 tables, all prefixed `hazo_umetrics_`.
+
+## Config
+
+Copy `config/hazo_umetrics_config.ini.sample` to `hazo_umetrics_config.ini` and fill in values. Sections: `[env]`, `[ga4]`, `[stats]`, `[ab_cookie]`, `[retention]`.
+
+## Tailwind / shadcn setup for UI components
+
+`MetricsPanel` renders inside `HazoUiDialog` and uses shadcn token classes (`bg-background`, `text-muted-foreground`, etc.). If those tokens aren't defined, the dialog panel will appear transparent. In your `globals.css`:
+
+```css
+@import "tailwindcss";
+/* shadcn tokens — required for bg-background, border, muted colors etc. */
+@import "../node_modules/hazo_ui/dist/styles.css";
+
+@source "../node_modules/hazo_umetrics/dist";
+@source "../node_modules/hazo_ui/dist";
+
+/* Tailwind v4 — map tokens to utilities */
+@theme inline {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-border: hsl(var(--border));
+  /* add remaining tokens as needed — see hazo_ui/dist/styles.css for the full list */
+}
+```
+
+(Adjust `@import` and `@source` depth to match your project's distance from `node_modules`.)

package/SETUP_CHECKLIST.md

@@ -0,0 +1,118 @@
+# hazo_umetrics — Setup Checklist
+
+Follow these steps when adding hazo_umetrics to a consuming application.
+
+## 1. Install the package
+
+```bash
+npm install hazo_umetrics
+```
+
+Install peer dependencies you need:
+
+```bash
+npm install hazo_core hazo_connect hazo_auth hazo_secure hazo_audit hazo_api hazo_ui
+```
+
+## 2. Run DB migrations
+
+**SQLite:**
+```bash
+# Run db_setup_sqlite.sql against your SQLite database
+node -e "
+const Database = require('better-sqlite3');
+const fs = require('fs');
+const db = new Database(process.env.DATABASE_PATH);
+db.exec(fs.readFileSync(require.resolve('hazo_umetrics/db_setup_sqlite.sql'), 'utf-8'));
+db.close();
+"
+```
+
+**PostgreSQL:** Run `node_modules/hazo_umetrics/db_setup_postgres.sql` against your database.
+
+## 3. Set env vars for cookie signing
+
+```bash
+# Generate a 32-byte key: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+HAZO_UMETRICS_COOKIE_KEY_CURRENT=v1
+HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte key>
+```
+
+## 4. Add config file (optional)
+
+Copy `node_modules/hazo_umetrics/config/hazo_umetrics_config.ini.sample` to your app's config directory as `hazo_umetrics_config.ini` and fill in `[ga4]` when ready for M1.
+
+## 5. Mount API routes (Next.js)
+
+```ts
+// app/api/hazo_umetrics/stats/route.ts
+import { createStatHandlers } from 'hazo_umetrics/api';
+import { getHazoConnect } from '@/lib/db';
+
+const handlers = createStatHandlers({ getAdapter: getHazoConnect });
+
+export async function GET(req: Request) { return handlers.getStat(req); }
+export async function POST(req: Request) { return handlers.recordStat(req); }
+```
+
+## 6. Wrap your app in HazoMetricsProvider (client)
+
+```tsx
+// app/layout.tsx
+import { HazoMetricsProvider } from 'hazo_umetrics/client';
+
+export default function RootLayout({ children }) {
+  return (
+    <HazoMetricsProvider scopeId={process.env.NEXT_PUBLIC_SCOPE_ID}>
+      {children}
+    </HazoMetricsProvider>
+  );
+}
+```
+
+## 7. Configure Tailwind (if you use hazo_umetrics UI components)
+
+`MetricsPanel` uses shadcn token utilities (`bg-background`, `text-muted-foreground`, `border`, etc.) from `hazo_ui`. Without the token definitions the dialog panel will render transparent. In your `globals.css`:
+
+```css
+@import "tailwindcss";
+/* shadcn tokens — required so bg-background, border, muted etc. resolve */
+@import "../node_modules/hazo_ui/dist/styles.css";
+
+@source "../node_modules/hazo_umetrics/dist";
+@source "../node_modules/hazo_ui/dist";
+
+/* Tailwind v4 — map HSL tokens to color utilities */
+@theme inline {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+}
+```
+
+(Adjust `@import` and `@source` depth to match your project's distance from `node_modules`.)
+
+## 8. Smoke test
+
+```ts
+import { recordStat, getLatestStat } from 'hazo_umetrics';
+await recordStat(adapter, { scope_id: 'my-app', metric_key: 'setup_test', value: 1 });
+const stat = await getLatestStat(adapter, { scope_id: 'my-app', metric_key: 'setup_test' });
+console.assert(stat?.value === 1, 'hazo_umetrics setup OK');
+```

package/config/hazo_umetrics_config.ini.sample

@@ -0,0 +1,35 @@
+; hazo_umetrics configuration
+; Copy to hazo_umetrics_config.ini and fill in values for your environment.
+; Env-var overrides: HAZO_UMETRICS_<SECTION>_<KEY> (uppercase, underscores).
+
+[env]
+; Uncomment to hard-code the environment name (overrides HAZO_ENV / NODE_ENV).
+; env = development
+
+[ga4]
+; GA4 property ID (format: "properties/123456789"). Leave blank until M1 GA4 connect.
+; property_id =
+; GA4 Measurement ID (format: "G-XXXXXXXX"). Required for client-side event tracking.
+; measurement_id =
+; GA4 Data API base URL (default: https://analyticsdata.googleapis.com/v1beta/)
+; api_base_url =
+
+[stats]
+; Default snapshot cadence for collectors that don't specify their own.
+; default_cadence = hourly
+; How many stat rows to return in getStatSeries when no limit is passed.
+; default_series_limit = 100
+
+[ab_cookie]
+; Cookie name set for anonymous variant assignments.
+; name = hazo_umetrics_ab
+; TTL in seconds (default: 90 days).
+; ttl_seconds = 7776000
+; Env var prefix for the AES-256-GCM signing key.
+; Set HAZO_UMETRICS_COOKIE_KEY_CURRENT=v1 and HAZO_UMETRICS_COOKIE_KEY_v1=<base64 32 bytes>.
+; key_env_prefix = HAZO_UMETRICS_COOKIE_KEY
+
+[retention]
+; How many days of own-capture data (stats, exposures, assignments) to keep.
+; Retention jobs are M3 (hazo_jobs wiring); this value documents the intent.
+; days = 90

package/dist/api/index.d.ts

@@ -0,0 +1,78 @@
+import type { HazoConnectAdapter } from 'hazo_connect/server';
+export type GetAuthFn = (req: Request, opts: {
+    required_permissions?: string[];
+    scope_id?: string;
+    strict?: boolean;
+}) => Promise<{
+    authenticated: boolean;
+    user: {
+        id: string;
+    } | null;
+    permissions: string[];
+    permission_ok: boolean;
+    scope_ok?: boolean;
+}>;
+export interface ApiFactoryOptions {
+    getAdapter: () => Promise<HazoConnectAdapter> | HazoConnectAdapter;
+    getAuth?: GetAuthFn;
+    onAudit?: (entry: {
+        action: string;
+        actor_id: string;
+        scope_id: string;
+        details?: unknown;
+    }) => Promise<void>;
+}
+export declare function createStatHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?scope_id=<id>&metric_key=<key>
+     * Returns the latest reading for the metric, or null if none.
+     */
+    getStat(req: Request): Promise<Response>;
+    /**
+     * GET /...?scope_id=<id>&metric_key=<key>[&since=<iso>][&limit=<n>]
+     * Returns time-series readings.
+     */
+    getStatSeries(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { scope_id, metric_key, value, app_id?, unit?, dimensions? }
+     * Appends a new stat reading.
+     */
+    recordStat(req: Request): Promise<Response>;
+};
+export declare function createExperimentHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?scope_id=<id>
+     * Lists all experiments for a scope.
+     */
+    listExperiments(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { experimentKey, scope_id, subjectId?, consent? }
+     * Resolves the variant for a subject.
+     */
+    evalVariant(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { key, scope_id }
+     * Transitions an experiment to 'running'. Requires metrics.manage.
+     */
+    startExperiment(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { key, scope_id }
+     * Transitions an experiment to 'stopped'. Requires metrics.manage.
+     */
+    stopExperiment(req: Request): Promise<Response>;
+};
+export declare function createGa4ConnectHandlers(options: ApiFactoryOptions): {
+    /** STUB (M1): Initiate GA4 OAuth connection for a scope. */
+    connect(req: Request): Promise<Response>;
+    /** STUB (M1): Provision a GA4 property for a scope. */
+    provision(req: Request): Promise<Response>;
+};
+export declare function createQueryHandlers(options: ApiFactoryOptions): {
+    /** STUB (M1): Execute a GA4 or stat-store query. */
+    query(req: Request): Promise<Response>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAY9D,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,KAC3E,OAAO,CAAC;IACX,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACnE,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAiGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB;IAIzD;;;OAGG;iBACgB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqB9C;;;OAGG;uBACsB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwBpD;;;;OAIG;oBACmB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EA4CpD;AAoBD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB;IAW/D;;;OAGG;yBACwB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqBtD;;;;OAIG;qBACoB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiDlD;;;;OAIG;yBACwB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IA8CtD;;;;OAIG;wBACuB,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EA8CxD;AAMD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB;IAI/D,4DAA4D;iBACzC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAe9C,uDAAuD;mBAClC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EAenD;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB;IAI1D,oDAAoD;eACnC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EAe/C"}