hazo_umetrics 0.1.2 → 1.3.0

package/CHANGE_LOG.md

@@ -1,5 +1,122 @@
 # hazo_umetrics — Change Log
 
+## 1.3.0 — Analytics dashboard + behavioral fixes + createUmetricsConnect
+
+**New features + bug fixes (no breaking changes):**
+
+### New: `createUmetricsConnect` — dedicated DB factory
+- `createUmetricsConnect(opts?)` builds a `HazoConnectAdapter` from `HAZO_UMETRICS_DATABASE_*`
+  env vars (type / URL / API key / SQLite path), with INI `[database]` as fallback. Returns a
+  cached adapter on no-arg calls; creates fresh when opts are passed.
+- Exported from main `hazo_umetrics` entry: `import { createUmetricsConnect } from 'hazo_umetrics'`
+- `UmetricsConnectOptions` type exported alongside the factory.
+- Enables wiring umetrics to a **separate DB** from the host app in one line:
+  `createStatHandlers({ getAdapter: createUmetricsConnect })`
+- Updated `config/hazo_umetrics_config.ini.sample` `[database]` section with dedicated env-var docs.
+
+### New: `topActions` behavior aggregation
+- `topActions` function in `src/server/behavior.ts` — ranks all `action.*` events by frequency, no `user_id` required. Answers "what is the most common action?" without needing session segmentation.
+- Exposed as `metric=top_actions` in `GET /api/hazo_umetrics/analytics/behavior`.
+- New "Top actions (all users)" panel in `AnalyticsPanel` (first panel in behavioral grid).
+
+### New: `UserIdentifier` client component (test-app)
+- Fetches `/api/hazo_auth/me` on mount and calls `identify(user_id)` automatically so logged-in users are tracked with `user_id` in all subsequent events. Required for first-session, post-relogin, and returning-user panels to populate.
+
+### Bug fix: `tabDwell` elapsed time
+- `tabDwell` was reading `row.value` (hardcoded `1`) instead of `dims.value` (the real accumulated foreground ms from the client-side visibility timer). Fixed to use `dims.value` when present. `Time per tab` panel now shows actual seconds, not event count.
+
+### Bug fix: `AnalyticsPanel` bar chart invisible bars
+- `SimpleBarChart` column divs lacked `h-full`, so `height: X%` resolved to 0px (percentage of auto-height container). Removed `items-end` from parent flex container (default `items-stretch`) and added `h-full` to each column div. Bars now render at correct proportional height.
+
+### Enhanced seed (test-app)
+- `buildEventRows()` rewritten with 4 realistic user personas (alice/bob/carol/dave) carrying `user_id` + `session_id` in all dimensions. Generates `action.*`, `ui.dwell.*`, and `ui.error.*` events spread across 14 days. Seeds `hazo_umetrics_action_def` catalog on every run so Action Catalog shows pre-classified actions with correct hierarchy and key-event flags.
+
+## 1.2.0 — Behavioral analytics + catalog UX
+
+**New features (additive, no breaking changes):**
+
+### Phase 1 — Capture foundation
+- `identify(userId)` now stores user ID in module var + `localStorage['hazo_umetrics_uid']`; `getUserId()` restores on page reload. `postEvent` attaches `user_id` to every event's dimensions automatically.
+- `HazoMetricsProvider` gains optional `userId` prop — calls `identify` when set (SSR/known-user apps).
+- Global `error` + `unhandledrejection` listeners post `ui.error.<slug>` events with `type`, `message` (truncated 200 chars), `path`.
+- Tab-dwell tracking: `ui.dwell.<path_slug>` posted on path change with `value=ms`; `pagehide`/`visibilitychange` flushes remaining dwell.
+- `trackError(err, ctx?)` exported from context for manual error capture.
+
+### Phase 2 — Catalog UX
+- New `hazo_umetrics_action_link` table (SQLite + Postgres) — undirected many-to-many related-action pairs. PK `(action_key, related_key, app_id)`; canonical order (alpha sort) prevents duplicate rows.
+- `getLinks`, `addLink`, `removeLink` in `src/server/actions.ts`. Self-link guard (`action_key === related_key` → null/400). Idempotent add.
+- `createLinkHandlers` in `hazo_umetrics/api`: `GET`, `POST`, `DELETE` for `/actions/links`. Auth-gated (`metrics.view` / `metrics.manage`).
+- `actions_panel.tsx` updated: free-text parent_key field replaced with `ActionKeyPicker` (searchable single-select with clear button); new `RelatedActionsPicker` multi-select with removable pills. Both source options from the flat action catalog.
+
+### Phase 3 — Analytics query layer
+- New `src/server/behavior.ts` — 7 behavioral aggregation functions using the established JS-aggregation pattern (windowed fetch, in-memory grouping, backend-agnostic):
+  - `firstSessionActions` — actions in each user's first session
+  - `postReloginActions` — actions in each user's second session
+  - `actionsBeforeGoal(goalKey, n)` — N actions preceding a goal event
+  - `topErrors` — `ui.error.*` frequency ranking
+  - `tabDwell` — summed dwell ms by path
+  - `frequentActionsReturning` — actions by users with >1 session
+  - `eventsOverTime` — day buckets with optional per-user breakdown
+- All functions accept `catalogMap`, `includeArchived`, `keyEventsOnly` filters — archived actions excluded by default; key events given first-class treatment.
+- `createBehaviorHandlers` in `hazo_umetrics/api`: `GET /analytics/behavior?metric=<name>` and `GET /analytics/events-over-time`.
+
+### Phase 4 — Analytics dashboard
+- New `AnalyticsPanel` component (`hazo_umetrics/ui`) — date-range filter, user multi-select, show-archived toggle, key-events-only toggle, goal-key input.
+- Events-over-time bar chart (inline `SimpleBarChart`, no extra peer dep) with per-user stacked segments when user filter active.
+- Six behavioral question cards: first-session, post-relogin, before-goal, errors, tab-dwell, frequent-returning.
+- Test-app: `/analytics` page, `Analytics` sidebar nav link, three new API routes (`/actions/links`, `/analytics/behavior`, `/analytics/events-over-time`).
+- Autotest scenarios for client capture (identify) and link API.
+
+---
+
+## 1.1.0 — Action tracking + catalog
+
+**New features (additive, no breaking changes):**
+
+### Action catalog
+- New `hazo_umetrics_action_def` table (SQLite + Postgres) — governance layer for user action tracking. Composite PK `(action_key, app_id)`, self-referencing `parent_key` for hierarchy, `is_key_event` flag, `status` (`unclassified | active | archived`).
+- `src/server/actions.ts` — catalog service: `ensureActionDef`, `listActions`, `getActionTree`, `updateActionDef`. In-process seen-set cache prevents repeated DB writes per event.
+- `ActionDef`, `ActionNode`, `ActionDefPatch` types added to `src/server/types.ts` and re-exported from the package root.
+
+### Broadened event ingestion
+- `createEventHandlers.recordEvent` now accepts `metric_key` starting with `action.*` in addition to `ui.*`. On first ingest of a new key, auto-creates an `unclassified` catalog row via `ensureActionDef`.
+- Arbitrary keys still rejected (guard unchanged for anything else).
+
+### Catalog API
+- `createActionHandlers(options)` — new handler factory in `hazo_umetrics/api`:
+  - `listActions` — `GET`, requires `metrics.view`.
+  - `getActionTree` — `GET`, requires `metrics.view`. Returns catalog nested by `parent_key`.
+  - `updateAction` — `PATCH`, requires `metrics.manage`. Patches mutable fields; emits `action.catalog.update` audit entry.
+
+### Client
+- `useMetrics()` context now includes `trackAction(key, opts?)` — thin wrapper that posts `action.<key>` via the existing `postEvent`. Optional `opts.url` and `opts.dims` forwarded as dimensions.
+
+### Admin UI
+- `ActionsPanel` component exported from `hazo_umetrics/ui` — catalog tree view with inline editing (label, description, parent reparent, URL, key-event toggle, status).
+
+### Test-app
+- New `/actions` page with demo `trackAction` buttons and live `ActionsPanel`.
+- New API routes: `GET/PATCH /api/hazo_umetrics/actions`, `GET /api/hazo_umetrics/actions/tree`.
+- 4 browser autotest scenarios in `hazo_umetrics_actions` scenario group.
+- Sidebar: Actions nav item added.
+
+### Tests
+- 22 new Jest tests in `__tests__/actions.test.ts`. Total: 83 (all green).
+
+## 1.0.0 — Breaking rename: scope_id→app_id, app_id→scope_id
+
+**Breaking changes:**
+- `scope_id` (required site-isolation key) renamed to `app_id` in all tables, TypeScript interfaces, function signatures, and API query parameters.
+- Old optional `app_id` column on `hazo_umetrics_stat` renamed to `scope_id` (now means: optional tenant subdivision within a site).
+- New optional `scope_id TEXT NOT NULL DEFAULT ''` column added to all 7 tables.
+- `StatCollectorDef.collect(scope_id)` → `collect(app_id)`.
+- `MaintenanceJob` handler ctx: `scope_id` → `app_id`.
+- `MetricsPanel` prop: `scopeId` → `appId`.
+- `Ga4Provisioner.provision(scopeId, ...)` → `provision(appId, ...)`.
+- API query params: `?scope_id=` → `?app_id=` on all stat/experiment/GA4/query endpoints.
+
+**No in-place migration provided** — this package is pre-release. Re-apply fresh schema via `db_setup_postgres.sql` or `db_setup_sqlite.sql`.
+
 ## 0.1.2 — 2026-06-14
 
 **Changed:**

package/README.md

@@ -8,7 +8,7 @@ Gives every hazo Next.js app one consistent, auth-gated way to understand user b
 - **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.
+All surfaces mount inside `hazo_admin` via the existing `kind:'metrics'` section; every read/write is `app_id`-gated.
 
 ## Status
 
@@ -41,9 +41,9 @@ HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte AES-256 key>
 | 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_dataviz LineChart — requires hazo_dataviz peer dep) |
+| `hazo_umetrics/api` | Route factories: createStatHandlers, createExperimentHandlers, createGa4ConnectHandlers, createQueryHandlers, createEventHandlers (anon ingestion), createBehaviorHandlers, createActionHandlers, createLinkHandlers, createActivityHandlers |
+| `hazo_umetrics/client` | Client: HazoMetricsProvider, useMetrics, getVariant, isEnabled, identify, trackAction, trackError, recordStat |
+| `hazo_umetrics/ui` | UI: MetricsPanel, StatCards, StatTrend, AnalyticsPanel, ActionsPanel |
 
 ## Stat store
 
@@ -51,24 +51,24 @@ HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte AES-256 key>
 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 });
+await recordStat(adapter, { app_id: 'my-app', metric_key: 'active_users', value: 42 });
 
 // Latest value
-const stat = await getLatestStat(adapter, { scope_id: 'my-app', metric_key: 'active_users' });
+const stat = await getLatestStat(adapter, { app_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 });
+const series = await getStatSeries(adapter, { app_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),
+  collect: async (app_id) => countActiveUsers(app_id),
 });
 
 // Run all collectors (call on a schedule via hazo_jobs in M1)
-const results = await runStatSnapshot(adapter, { scope_id: 'my-app' });
+const results = await runStatSnapshot(adapter, { app_id: 'my-app' });
 ```
 
 ## Feature flags
@@ -79,15 +79,52 @@ 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',
+  app_id: 'my-app',
   subjectId: user.id,
   consent: true,
 });
 
 // Boolean flag shorthand
-const enabled = await isEnabled(adapter, { experimentKey: 'new_feature', scope_id, subjectId });
+const enabled = await isEnabled(adapter, { experimentKey: 'new_feature', app_id, subjectId });
 ```
 
+## Analytics dashboard
+
+```tsx
+import { AnalyticsPanel } from 'hazo_umetrics/ui';
+
+// Mount in a server or client page — fetches all behavioral data from /api/hazo_umetrics/analytics/*
+<AnalyticsPanel appId="my-app" />
+```
+
+Seven behavioral panels answer:
+- **Top actions (all users)** — most frequent `action.*` events, no user_id required
+- **First-session actions** — what new users do first (requires `user_id` in events)
+- **Post re-login actions** — what users do on their second session
+- **Before "share"** — the N actions preceding a goal event (configurable goal key)
+- **Common errors** — ranked `ui.error.*` frequency
+- **Time per tab** — real foreground dwell time per path (from `ui.dwell.*` events)
+- **Returning-user actions** — most common actions for users with >1 session
+
+For `user_id` to be captured, call `identify(userId)` after login or mount `UserIdentifier` (see test-app `src/components/user_identifier.tsx`).
+
+## Action tracking (client)
+
+```tsx
+import { HazoMetricsProvider, useMetrics } from 'hazo_umetrics/client';
+
+// Wrap your app
+<HazoMetricsProvider appId="my-app" userId={currentUser?.id}>
+  {children}
+</HazoMetricsProvider>
+
+// In any component
+const { trackAction, trackError } = useMetrics();
+trackAction('timer.complete', { url: '/timer' });
+```
+
+Auto-tracked on mount: page views (`ui.pageview.*`), clicks (`ui.click.*`), errors (`ui.error.*`), dwell time (`ui.dwell.*`).
+
 ## API route factories
 
 ```ts
@@ -102,7 +139,46 @@ const expHandlers = createExperimentHandlers({ getAdapter: () => myAdapter });
 
 ## DB setup
 
-Run `db_setup_sqlite.sql` (SQLite) or `db_setup_postgres.sql` (PostgreSQL) once. Creates 7 tables, all prefixed `hazo_umetrics_`.
+Run `db_setup_sqlite.sql` (SQLite) or `db_setup_postgres.sql` (PostgreSQL) once against your **umetrics DB**. Creates 7 tables, all prefixed `hazo_umetrics_`.
+
+> Run the migration against the **dedicated umetrics database**, not the host app's main DB.
+> If you use `createUmetricsConnect()` (recommended), the umetrics DB is the one pointed to
+> by `HAZO_UMETRICS_DATABASE_URL`.
+
+## Separate database for umetrics
+
+`hazo_umetrics` data (events, stats, flags, experiments) should live in its own database,
+**separate from the host app's main DB**. This keeps analytics writes from competing with
+product data, lets you point multiple apps at one shared analytics store, and lets you
+scale each independently.
+
+Use `createUmetricsConnect()` to build a dedicated adapter in one line:
+
+```ts
+import { createUmetricsConnect } from 'hazo_umetrics';
+
+// Reads HAZO_UMETRICS_DATABASE_URL + HAZO_UMETRICS_DATABASE_API_KEY from env.
+// Falls back to ./umetrics.sqlite when type=sqlite.
+export const getUmetricsAdapter = createUmetricsConnect;
+```
+
+Then inject it into every route factory:
+
+```ts
+const handlers = createStatHandlers({ getAdapter: createUmetricsConnect });
+```
+
+### Env vars
+
+| Variable | Required | Description |
+|---|---|---|
+| `HAZO_UMETRICS_DATABASE_URL` | PostgREST only | Base URL of the umetrics PostgREST server |
+| `HAZO_UMETRICS_DATABASE_API_KEY` | PostgREST only | Bearer token for the umetrics PostgREST server |
+| `HAZO_UMETRICS_DATABASE_TYPE` | No | `postgrest` (default) or `sqlite` |
+| `HAZO_UMETRICS_DATABASE_PATH` | SQLite only | Path to the SQLite file (default: `./umetrics.sqlite`) |
+
+These are independent of the host app's `POSTGREST_URL` / `POSTGREST_API_KEY` — the
+analytics DB can be a completely different PostgREST instance (or a local SQLite file for dev).
 
 ## Config
 

package/SETUP_CHECKLIST.md

@@ -33,7 +33,24 @@ db.close();
 
 **PostgreSQL:** Run `node_modules/hazo_umetrics/db_setup_postgres.sql` against your database.
 
-## 3. Set env vars for cookie signing
+## 3. Set env vars for the umetrics database
+
+`createUmetricsConnect()` reads these variables to connect to the dedicated umetrics DB:
+
+```bash
+# PostgREST mode (production / staging)
+HAZO_UMETRICS_DATABASE_URL=https://your-umetrics-postgrest.example.com
+HAZO_UMETRICS_DATABASE_API_KEY=<bearer-token>
+
+# SQLite mode (local dev — omit DATABASE_URL to fall back to ./umetrics.sqlite)
+# HAZO_UMETRICS_DATABASE_TYPE=sqlite
+# HAZO_UMETRICS_DATABASE_PATH=./umetrics.sqlite
+```
+
+> Run `db_setup_postgres.sql` (or `db_setup_sqlite.sql`) against this **umetrics DB**, not
+> the host app's main database.
+
+## 4. Set env vars for cookie signing
 
 ```bash
 # Generate a 32-byte key: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
@@ -41,11 +58,11 @@ HAZO_UMETRICS_COOKIE_KEY_CURRENT=v1
 HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte key>
 ```
 
-## 4. Add config file (optional)
+## 5. 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)
+## 6. Mount API routes (Next.js)
 
 ```ts
 // app/api/hazo_umetrics/stats/route.ts
@@ -58,7 +75,7 @@ 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)
+## 7. Wrap your app in HazoMetricsProvider (client)
 
 ```tsx
 // app/layout.tsx
@@ -66,14 +83,14 @@ import { HazoMetricsProvider } from 'hazo_umetrics/client';
 
 export default function RootLayout({ children }) {
   return (
-    <HazoMetricsProvider scopeId={process.env.NEXT_PUBLIC_SCOPE_ID}>
+    <HazoMetricsProvider appId={process.env.NEXT_PUBLIC_APP_ID}>
       {children}
     </HazoMetricsProvider>
   );
 }
 ```
 
-## 7. Configure Tailwind (if you use hazo_umetrics UI components)
+## 8. 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`:
 
@@ -112,11 +129,11 @@ export default function RootLayout({ children }) {
 
 (Adjust `@import` and `@source` depth to match your project's distance from `node_modules`.)
 
-## 8. Smoke test
+## 9. 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' });
+await recordStat(adapter, { app_id: 'my-app', metric_key: 'setup_test', value: 1 });
+const stat = await getLatestStat(adapter, { app_id: 'my-app', metric_key: 'setup_test' });
 console.assert(stat?.value === 1, 'hazo_umetrics setup OK');
 ```

package/config/hazo_umetrics_config.ini.sample

@@ -2,6 +2,32 @@
 ; Copy to hazo_umetrics_config.ini and fill in values for your environment.
 ; Env-var overrides: HAZO_UMETRICS_<SECTION>_<KEY> (uppercase, underscores).
 
+[umetrics]
+; The site identifier for this application instance. Used as the primary
+; isolation key (app_id) on all hazo_umetrics tables.
+app_id = my_app
+
+[database]
+; Dedicated hazo_umetrics database — separate from the host app's main DB.
+; Use createUmetricsConnect() from hazo_umetrics to wire this adapter.
+;
+; type: postgrest (default) | sqlite
+; Env-var override: HAZO_UMETRICS_DATABASE_TYPE
+; type = postgrest
+;
+; PostgREST mode (recommended for production):
+;   base_url — the PostgREST server base URL
+;   Env-var override: HAZO_UMETRICS_DATABASE_URL
+; base_url = http://your-postgrest-host:4444
+;   api_key — bearer token (env only, never store in INI)
+;   Set: HAZO_UMETRICS_DATABASE_API_KEY=<your-token>
+;
+; SQLite mode (local development without a Postgres instance):
+;   database_path — path to the SQLite file (default: ./umetrics.sqlite)
+;   Env-var override: HAZO_UMETRICS_DATABASE_PATH
+; type = sqlite
+; database_path = ./umetrics.sqlite
+
 [env]
 ; Uncomment to hard-code the environment name (overrides HAZO_ENV / NODE_ENV).
 ; env = development

package/dist/api/index.d.ts

@@ -18,61 +18,132 @@ export interface ApiFactoryOptions {
     onAudit?: (entry: {
         action: string;
         actor_id: string;
-        scope_id: string;
+        app_id: string;
         details?: unknown;
     }) => Promise<void>;
 }
 export declare function createStatHandlers(options: ApiFactoryOptions): {
     /**
-     * GET /...?scope_id=<id>&metric_key=<key>
+     * GET /...?app_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>]
+     * GET /...?app_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? }
+     * Body: { app_id, metric_key, value, scope_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.
+     * GET /...?app_id=<id>
+     * Lists all experiments for an app.
      */
     listExperiments(req: Request): Promise<Response>;
     /**
      * POST /...
-     * Body: { experimentKey, scope_id, subjectId?, consent? }
+     * Body: { experimentKey, app_id, subjectId?, consent? }
      * Resolves the variant for a subject.
      */
     evalVariant(req: Request): Promise<Response>;
     /**
      * POST /...
-     * Body: { key, scope_id }
+     * Body: { key, app_id }
      * Transitions an experiment to 'running'. Requires metrics.manage.
      */
     startExperiment(req: Request): Promise<Response>;
     /**
      * POST /...
-     * Body: { key, scope_id }
+     * Body: { key, app_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. */
+    /** STUB (M1): Initiate GA4 OAuth connection for an app. */
     connect(req: Request): Promise<Response>;
-    /** STUB (M1): Provision a GA4 property for a scope. */
+    /** STUB (M1): Provision a GA4 property for an app. */
     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>;
 };
+export declare function createEventHandlers(options: Pick<ApiFactoryOptions, 'getAdapter'>): {
+    /**
+     * POST /...
+     * Body: { app_id, metric_key, value?, dimensions? }
+     * Records a UI or action event stat without auth. metric_key must start with
+     * 'ui.' or 'action.'. Intentional auth carve-out: instrumentation must work
+     * without login.
+     *
+     * For action.* keys: auto-creates an 'unclassified' catalog row on first sight
+     * (seen-set cached in-process). Accepts optional `url` dimension.
+     */
+    recordEvent(req: Request): Promise<Response>;
+};
+export declare function createActionHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?app_id=<id>
+     * Returns all action defs as a flat list. Requires metrics.view.
+     */
+    listActions(req: Request): Promise<Response>;
+    /**
+     * GET /...?app_id=<id>
+     * Returns action defs nested by parent_key. Requires metrics.view.
+     */
+    getActionTree(req: Request): Promise<Response>;
+    /**
+     * PATCH /...
+     * Body: { app_id, action_key, patch: { label?, description?, parent_key?, url?, is_key_event?, status? } }
+     * Updates mutable fields of an action def. Requires metrics.manage.
+     * Emits an audit entry 'action.catalog.update'.
+     */
+    updateAction(req: Request): Promise<Response>;
+};
+export declare function createActivityHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?app_id=<id>[&since=<iso>]
+     * Returns { summary, trend } aggregated from ui.* events in the stat store.
+     */
+    getActivity(req: Request): Promise<Response>;
+};
+export declare function createLinkHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?app_id=<id>[&action_key=<key>]
+     * Returns related-action links. Requires metrics.view.
+     */
+    getLinks(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { app_id, action_key, related_key }
+     * Adds a link (idempotent). Requires metrics.manage.
+     */
+    addLink(req: Request): Promise<Response>;
+    /**
+     * DELETE /...
+     * Body: { app_id, action_key, related_key }
+     * Removes a link. Requires metrics.manage.
+     */
+    removeLink(req: Request): Promise<Response>;
+};
+export declare function createBehaviorHandlers(options: ApiFactoryOptions): {
+    /**
+     * GET /...?app_id=<id>&metric=<name>[&since=<iso>][&goal=<key>][&n=<int>][&include_archived=1][&key_events_only=1][&user_ids=u1,u2]
+     * Dispatches to behavioral aggregation functions. Requires metrics.view.
+     * metric: first_session | post_relogin | before_goal | errors | tab_dwell | frequent_returning
+     */
+    getBehavior(req: Request): Promise<Response>;
+    /**
+     * GET /...?app_id=<id>[&since=<iso>][&user_ids=u1,u2][&key_events_only=1][&include_archived=1]
+     * Returns events bucketed by day. Requires metrics.view.
+     */
+    getEventsOverTime(req: Request): Promise<Response>;
+};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}