hazo_umetrics 1.3.0 → 1.4.0

package/CHANGE_LOG.md

@@ -1,5 +1,40 @@
 # hazo_umetrics — Change Log
 
+## 1.4.0 — Bulk catalog edits, per-action datapoints, user-journey viz, real user identity
+
+**New features (minor bump — no breaking changes):**
+
+### New: Bulk multiselect in Action Catalog
+- `updateActionDefBulk(adapter, {app_id, action_keys, patch})` — update many actions at once.
+- `applyLinksBulk(adapter, {app_id, action_keys, add_related, remove_related})` — cartesian add/remove related links.
+- `POST /actions/bulk` API: set status, key-event flag, parent, and related actions across N actions in one request. Permission: `metrics.manage`.
+- UI: checkbox column + `BulkActionBar` (status select, key-event toggles, parent picker, related add/remove) appear above the tree when ≥1 action selected.
+
+### New: Per-action datapoint schema
+- `datapoint_schema JSONB/TEXT` column on `hazo_umetrics_action_def` (migration: `ALTER TABLE hazo_umetrics_action_def ADD COLUMN datapoint_schema JSONB NOT NULL DEFAULT '[]'` for PG; `TEXT` for SQLite).
+- `DatapointField`, `DatapointSchema` types exported from `hazo_umetrics`.
+- JSON textarea in the Action Catalog edit form to declare which `dimensions` keys are meaningful.
+- `datapointStats(adapter, opts)` — aggregates dimension values (numeric histograms + categorical top lists).
+- `GET /analytics/datapoints?app_id=&action_key=` — returns `{action_key, total_events, keys[]}`.
+- `DatapointPanel` component: action picker + per-key cards (histogram bars for numeric, ranked list for categorical).
+
+### New: User-journey aggregation + graph
+- `userJourney(adapter, opts)` — groups events by session, computes per-step timing, emits `JourneyGraph` (nodes + edges with avgMs).
+- `GET /analytics/journey?app_id=[&user_id=][&session_id=]` — returns `{sessions, graph}`.
+- `JourneyPanel` component: dagre LR graph via `hazo_canvas` (optional peer dep) with edge timing labels; falls back to ordered step list when canvas unavailable.
+- `hazo_canvas` ≥1.9.1 required for timing labels on dagre edges (`direction:'LR'`).
+
+### New: Host-injected user identity
+- `resolveUserProfiles?: ResolveUserProfiles` prop on `AnalyticsPanel` and `JourneyPanel`.
+- UserFilter dropdown now shows `name / email / avatar` when resolver is wired; falls back to truncated UUID.
+- JourneyPanel session headers show resolved name/email/avatar.
+- Test-app: `POST /api/hazo_umetrics/user_profiles` route wires `hazo_auth` `get_profiles` as an example host implementation.
+
+### hazo_canvas 1.9.1
+- Dagre edge `label` field now rendered as a midpoint `kind:'text'` child (timing labels for journey viz).
+
+---
+
 ## 1.3.0 — Analytics dashboard + behavioral fixes + createUmetricsConnect
 
 **New features + bug fixes (no breaking changes):**

package/README.md

@@ -125,6 +125,128 @@ trackAction('timer.complete', { url: '/timer' });
 
 Auto-tracked on mount: page views (`ui.pageview.*`), clicks (`ui.click.*`), errors (`ui.error.*`), dwell time (`ui.dwell.*`).
 
+## Bulk Action Catalog edits
+
+```ts
+// POST /api/hazo_umetrics/actions/bulk
+// Body: { app_id, action_keys, patch?, add_related?, remove_related? }
+// Permission: metrics.manage
+// Response: { ok: true, data: { updated: string[], missing: string[], links: { added, removed } } }
+
+// Set status on many actions at once
+await fetch('/api/hazo_umetrics/actions/bulk', {
+  method: 'POST',
+  body: JSON.stringify({
+    app_id: 'my-app',
+    action_keys: ['timer.start', 'timer.complete'],
+    patch: { status: 'active', is_key_event: true },
+  }),
+});
+
+// Add related links in bulk (cartesian: every key in action_keys ↔ every key in add_related)
+await fetch('/api/hazo_umetrics/actions/bulk', {
+  method: 'POST',
+  body: JSON.stringify({
+    app_id: 'my-app',
+    action_keys: ['timer.start'],
+    add_related: ['timer.complete', 'timer.pause'],
+  }),
+});
+```
+
+`action_keys` must be a non-empty array — an empty array returns 400. Both `patch` and `add_related`/`remove_related` can be combined in one request.
+
+## Per-action datapoint schema
+
+Declare which `dimensions` keys are analytically meaningful for a given action:
+
+```ts
+// PATCH the action to set a datapoint_schema
+await fetch('/api/hazo_umetrics/actions?app_id=my-app', {
+  method: 'PATCH',
+  body: JSON.stringify({
+    app_id: 'my-app',
+    action_key: 'timer.complete',
+    patch: {
+      datapoint_schema: [
+        { key: 'duration_ms', label: 'Duration (ms)', type: 'number' },
+        { key: 'mode', label: 'Timer mode', type: 'string' },
+      ],
+    },
+  }),
+});
+```
+
+Types exported from `hazo_umetrics`: `DatapointField`, `DatapointSchema`.
+
+Once a schema is set, the `DatapointPanel` UI component shows per-key cards: histogram bars for `type:'number'` keys, ranked frequency lists for `type:'string'` keys.
+
+## Journey analytics
+
+```ts
+// GET /api/hazo_umetrics/analytics/journey?app_id=<id>[&user_id=<id>][&session_id=<id>]
+// Permission: metrics.view
+// Response: { ok: true, data: { sessions: Session[], graph: JourneyGraph } }
+```
+
+`sessions` is an ordered list of per-session step arrays with timing. `graph.nodes` and `graph.edges` provide the aggregated action-transition graph for all sessions (or filtered by user/session). Each edge carries `avgMs` (mean inter-step latency).
+
+```tsx
+import { JourneyPanel } from 'hazo_umetrics/ui';
+
+// Embedded panel — fetches journey data from /api/hazo_umetrics/analytics/journey
+<JourneyPanel
+  appId="my-app"
+  resolveUserProfiles={resolveUserProfiles}  // optional — enriches session headers
+/>
+```
+
+`JourneyPanel` renders a dagre LR graph via `hazo_canvas` when installed (`npm install hazo_canvas@^1.9.1`). Without `hazo_canvas`, it falls back to an ordered step list. Dagre edge timing labels require `hazo_canvas ≥ 1.9.1`.
+
+## Datapoint analytics
+
+```ts
+// GET /api/hazo_umetrics/analytics/datapoints?app_id=<id>&action_key=<key>
+// Permission: metrics.view
+// Response: { ok: true, data: { action_key, total_events, keys: DatapointKeyStats[] } }
+```
+
+Each entry in `keys` describes one dimension: `{ key, type, total, histogram | topValues }`. Use the `DatapointPanel` component to render these automatically.
+
+## resolveUserProfiles — wiring user identity
+
+`AnalyticsPanel` and `JourneyPanel` both accept an optional `resolveUserProfiles` prop that enriches user IDs with real names, emails, and avatars:
+
+```ts
+import type { ResolveUserProfiles } from 'hazo_umetrics/ui';
+
+const resolveUserProfiles: ResolveUserProfiles = async (ids) => {
+  const r = await fetch('/api/my-app/user_profiles', {
+    method: 'POST',
+    body: JSON.stringify({ ids }),
+    headers: { 'Content-Type': 'application/json' },
+  });
+  const j = await r.json();
+  return j.profiles ?? [];
+};
+
+// Each profile: { user_id, email?, name?, profile_picture_url? }
+```
+
+**Wiring with `hazo_auth` (gotimer / kinstripe pattern):**
+
+```ts
+// app/api/hazo_umetrics/user_profiles/route.ts
+import { authConnect } from '@/lib/db';
+import { hazo_get_user_profiles } from 'hazo_auth/server-lib';
+
+export async function POST(req: Request) {
+  const { ids } = await req.json();
+  const result = await hazo_get_user_profiles(authConnect, ids);
+  return Response.json({ profiles: result.profiles ?? [] });
+}
+```
+
 ## API route factories
 
 ```ts

package/SETUP_CHECKLIST.md

@@ -17,6 +17,30 @@ npm install hazo_core hazo_connect hazo_auth hazo_secure hazo_audit hazo_api haz
 > `hazo_dataviz` is required when you render `MetricsPanel`/`StatTrend` — its `LineChart`
 > draws the trend chart (moved out of `hazo_ui` in the 4.0.0 chart migration).
 
+## ALTER TABLE for 1.4.0 (existing deployments only)
+
+If you are upgrading an **existing** deployment from a version before 1.4.0, run these statements against your umetrics database before upgrading the package:
+
+```sql
+-- PostgreSQL:
+ALTER TABLE hazo_umetrics_action_def ADD COLUMN IF NOT EXISTS datapoint_schema JSONB NOT NULL DEFAULT '[]';
+
+-- SQLite (does not support IF NOT EXISTS on ALTER TABLE — skip if column already exists):
+ALTER TABLE hazo_umetrics_action_def ADD COLUMN datapoint_schema TEXT NOT NULL DEFAULT '[]';
+```
+
+Fresh installations (using `db_setup_sqlite.sql` / `db_setup_postgres.sql` from 1.4.0+) already include this column — no ALTER TABLE needed.
+
+**Optional — journey graph (hazo_canvas peer dep):**
+
+`JourneyPanel` renders an interactive dagre LR graph when `hazo_canvas` is installed. Without it, the panel falls back to a plain ordered step list. Install only if you use `JourneyPanel`:
+
+```bash
+npm install hazo_canvas@^1.9.1
+```
+
+---
+
 ## 2. Run DB migrations
 
 **SQLite:**

package/dist/api/index.d.ts

@@ -106,6 +106,13 @@ export declare function createActionHandlers(options: ApiFactoryOptions): {
      * Emits an audit entry 'action.catalog.update'.
      */
     updateAction(req: Request): Promise<Response>;
+    /**
+     * POST /...
+     * Body: { app_id, action_keys, patch?, add_related?, remove_related? }
+     * Bulk-updates multiple action defs and/or their links. Requires metrics.manage.
+     * Emits a single audit entry 'action.catalog.bulk_update' per call.
+     */
+    bulkUpdateActions(req: Request): Promise<Response>;
 };
 export declare function createActivityHandlers(options: ApiFactoryOptions): {
     /**
@@ -145,5 +152,15 @@ export declare function createBehaviorHandlers(options: ApiFactoryOptions): {
      * Returns events bucketed by day. Requires metrics.view.
      */
     getEventsOverTime(req: Request): Promise<Response>;
+    /**
+     * GET /...?app_id=<id>&action_key=<key>[&since=<iso>][&until=<iso>][&buckets=<n>][&top_n=<n>]
+     * Returns datapoint dimension stats for an action. Requires metrics.view.
+     */
+    getDatapoints(req: Request): Promise<Response>;
+    /**
+     * GET /...?app_id=<id>[&user_id=<id>][&session_id=<id>][&since=<iso>]
+     * Returns user journey sessions and aggregated graph. Requires metrics.view.
+     */
+    getJourney(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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}

package/dist/api/index.js

@@ -8,8 +8,8 @@ import { createCrudService } from 'hazo_connect/server';
 import { recordStat as _recordStat, getLatestStat as _getLatestStat, getStatSeries as _getStatSeries, } from '../server/stats.js';
 import { resolveVariant } from '../server/flags.js';
 import { getActivitySummary as _getActivitySummary, getActivityTrend as _getActivityTrend, } from '../server/activity.js';
-import { ensureActionDef as _ensureActionDef, listActions as _listActions, getActionTree as _getActionTree, updateActionDef as _updateActionDef, getLinks as _getLinks, addLink as _addLink, removeLink as _removeLink, } from '../server/actions.js';
-import { topActions as _topActions, firstSessionActions as _firstSessionActions, postReloginActions as _postReloginActions, actionsBeforeGoal as _actionsBeforeGoal, topErrors as _topErrors, tabDwell as _tabDwell, frequentActionsReturning as _frequentActionsReturning, eventsOverTime as _eventsOverTime, } from '../server/behavior.js';
+import { ensureActionDef as _ensureActionDef, listActions as _listActions, getActionTree as _getActionTree, updateActionDef as _updateActionDef, updateActionDefBulk as _updateActionDefBulk, applyLinksBulk as _applyLinksBulk, getLinks as _getLinks, addLink as _addLink, removeLink as _removeLink, } from '../server/actions.js';
+import { topActions as _topActions, firstSessionActions as _firstSessionActions, postReloginActions as _postReloginActions, actionsBeforeGoal as _actionsBeforeGoal, topErrors as _topErrors, tabDwell as _tabDwell, frequentActionsReturning as _frequentActionsReturning, eventsOverTime as _eventsOverTime, datapointStats as _datapointStats, userJourney as _userJourney, } from '../server/behavior.js';
 // ---------------------------------------------------------------------------
 // Default auth — dynamically imports hazo_auth/server-lib to avoid the
 // server-only guard firing at module-evaluation time (e.g. in test runners).
@@ -516,6 +516,67 @@ export function createActionHandlers(options) {
             });
             return jsonOk({ action: updated });
         },
+        /**
+         * POST /...
+         * Body: { app_id, action_keys, patch?, add_related?, remove_related? }
+         * Bulk-updates multiple action defs and/or their links. Requires metrics.manage.
+         * Emits a single audit entry 'action.catalog.bulk_update' per call.
+         */
+        async bulkUpdateActions(req) {
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { app_id, action_keys, patch, add_related, remove_related } = body;
+            if (!app_id) {
+                return jsonError('BAD_REQUEST', 'app_id is required', 400);
+            }
+            if (!Array.isArray(action_keys) || action_keys.length === 0) {
+                return jsonError('BAD_REQUEST', 'action_keys must be a non-empty array', 400);
+            }
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.manage'],
+                app_id,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            const adapter = await options.getAdapter();
+            const keys = action_keys;
+            let updated = [];
+            let missing = [];
+            let linksAdded = 0;
+            let linksRemoved = 0;
+            if (patch && Object.keys(patch).length > 0) {
+                const result = await _updateActionDefBulk(adapter, {
+                    app_id,
+                    action_keys: keys,
+                    patch: patch,
+                });
+                updated = result.updated;
+                missing = result.missing;
+            }
+            if ((add_related && add_related.length > 0) || (remove_related && remove_related.length > 0)) {
+                const result = await _applyLinksBulk(adapter, {
+                    app_id,
+                    action_keys: keys,
+                    add_related,
+                    remove_related,
+                });
+                linksAdded = result.added;
+                linksRemoved = result.removed;
+            }
+            await options.onAudit?.({
+                action: 'action.catalog.bulk_update',
+                actor_id: gate.userId,
+                app_id,
+                details: { action_keys: keys, patch, add_related, remove_related },
+            });
+            return jsonOk({ updated, missing, links: { added: linksAdded, removed: linksRemoved } });
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -744,5 +805,68 @@ export function createBehaviorHandlers(options) {
             const data = await _eventsOverTime(adapter, { app_id, since, userIds, limit: 10000, catalogMap, includeArchived, keyEventsOnly });
             return jsonOk({ data });
         },
+        /**
+         * GET /...?app_id=<id>&action_key=<key>[&since=<iso>][&until=<iso>][&buckets=<n>][&top_n=<n>]
+         * Returns datapoint dimension stats for an action. Requires metrics.view.
+         */
+        async getDatapoints(req) {
+            const url = new URL(req.url);
+            const app_id = url.searchParams.get('app_id') ?? '';
+            const action_key = url.searchParams.get('action_key') ?? '';
+            const since = url.searchParams.get('since') ?? undefined;
+            const until = url.searchParams.get('until') ?? undefined;
+            const bucketsParam = url.searchParams.get('buckets');
+            const buckets = bucketsParam != null ? parseInt(bucketsParam, 10) : undefined;
+            const topNParam = url.searchParams.get('top_n');
+            const topN = topNParam != null ? parseInt(topNParam, 10) : undefined;
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                app_id: app_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            if (!app_id || !action_key) {
+                return jsonError('BAD_REQUEST', 'app_id and action_key are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const catalog = await _listActions(adapter, { app_id });
+            const matchingAction = catalog.find((a) => a.action_key === action_key);
+            const result = await _datapointStats(adapter, {
+                app_id,
+                action_key,
+                since,
+                until,
+                buckets,
+                topN,
+                schema: matchingAction?.datapoint_schema,
+            });
+            return jsonOk(result);
+        },
+        /**
+         * GET /...?app_id=<id>[&user_id=<id>][&session_id=<id>][&since=<iso>]
+         * Returns user journey sessions and aggregated graph. Requires metrics.view.
+         */
+        async getJourney(req) {
+            const url = new URL(req.url);
+            const app_id = url.searchParams.get('app_id') ?? '';
+            const user_id = url.searchParams.get('user_id') ?? undefined;
+            const session_id = url.searchParams.get('session_id') ?? undefined;
+            const since = url.searchParams.get('since') ?? undefined;
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                app_id: app_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            if (!app_id)
+                return jsonError('BAD_REQUEST', 'app_id is required', 400);
+            const adapter = await options.getAdapter();
+            const catalog = await _listActions(adapter, { app_id });
+            const catalogMap = new Map(catalog.map((a) => [a.action_key, { label: a.label, datapoint_schema: a.datapoint_schema }]));
+            const result = await _userJourney(adapter, { app_id, user_id, session_id, since, catalogMap });
+            return jsonOk(result);
+        },
     };
 }

package/dist/server/actions.d.ts

@@ -1,5 +1,21 @@
 import type { HazoConnectAdapter } from 'hazo_connect/server';
 import type { ActionDef, ActionDefPatch, ActionNode, ActionLink } from './types.js';
+type ActionDefRow = {
+    action_key: string;
+    app_id: string;
+    scope_id: string;
+    label: string;
+    description: string;
+    parent_key: string | null;
+    url: string | null;
+    is_key_event: number | boolean;
+    status: string;
+    datapoint_schema: string;
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+};
+export declare function applyPatch(_existing: ActionDef, patch: ActionDefPatch): Partial<ActionDefRow>;
 /**
  * Insert-if-absent a draft def row. No-op after first sight (seen-set cached).
  * Called by the ingestion layer on every `action.*` event.
@@ -63,4 +79,32 @@ export declare function removeLink(adapter: HazoConnectAdapter, params: {
     action_key: string;
     related_key: string;
 }): Promise<void>;
+/**
+ * Updates mutable fields across multiple action defs in one call.
+ * Returns lists of updated keys and missing (not found) keys.
+ */
+export declare function updateActionDefBulk(adapter: HazoConnectAdapter, params: {
+    app_id: string;
+    action_keys: string[];
+    patch: ActionDefPatch;
+}): Promise<{
+    updated: string[];
+    missing: string[];
+}>;
+/**
+ * Applies link additions and removals across multiple action keys (Cartesian product).
+ * For each action_key × each add_related key: calls addLink (idempotent, self-link guarded).
+ * For each action_key × each remove_related key: calls removeLink.
+ * Returns counts of added (non-null addLink results) and removed (all removeLink calls).
+ */
+export declare function applyLinksBulk(adapter: HazoConnectAdapter, params: {
+    app_id: string;
+    action_keys: string[];
+    add_related?: string[];
+    remove_related?: string[];
+}): Promise<{
+    added: number;
+    removed: number;
+}>;
+export {};
 //# sourceMappingURL=actions.d.ts.map

package/dist/server/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/server/actions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoEpF;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IACN,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,GACA,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,SAAS,EAAE,CAAC,CAUtB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,UAAU,EAAE,CAAC,CAwBvB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IACN,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;CACvB,GACA,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAwB3B;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAsBD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,UAAU,EAAE,CAAC,CAoBvB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrF,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAsC5B;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CAAC,IAAI,CAAC,CAiBf"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/server/actions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAMrG,KAAK,YAAY,GAAG;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAwCF,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAU7F;AA6BD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IACN,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,GACA,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,SAAS,EAAE,CAAC,CAUtB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,UAAU,EAAE,CAAC,CAwBvB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IACN,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;CACvB,GACA,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAkB3B;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAsBD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,UAAU,EAAE,CAAC,CAoBvB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrF,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAsC5B;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CAAC,IAAI,CAAC,CAiBf;AAMD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACvE,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAgCnD;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE;IACN,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB7C"}

package/dist/server/actions.js

@@ -5,6 +5,21 @@ import { createCrudService } from 'hazo_connect/server';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+function parseSchema(raw) {
+    try {
+        const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (!Array.isArray(parsed))
+            return [];
+        const valid = parsed.every((el) => el != null &&
+            typeof el.key === 'string' &&
+            typeof el.label === 'string' &&
+            typeof el.type === 'string');
+        return valid ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
 function rowToDef(row) {
     return {
         action_key: row.action_key,
@@ -16,10 +31,29 @@ function rowToDef(row) {
         url: row.url ?? null,
         is_key_event: Boolean(row.is_key_event),
         status: row.status,
+        datapoint_schema: parseSchema(row.datapoint_schema),
         created_at: row.created_at,
         updated_at: row.updated_at,
     };
 }
+export function applyPatch(_existing, patch) {
+    const changes = {};
+    if (patch.label != null)
+        changes.label = patch.label;
+    if (patch.description != null)
+        changes.description = patch.description;
+    if ('parent_key' in patch)
+        changes.parent_key = patch.parent_key ?? null;
+    if ('url' in patch)
+        changes.url = patch.url ?? null;
+    if (patch.is_key_event != null)
+        changes.is_key_event = patch.is_key_event ? 1 : 0;
+    if (patch.status != null)
+        changes.status = patch.status;
+    if ('datapoint_schema' in patch)
+        changes.datapoint_schema = JSON.stringify(patch.datapoint_schema ?? []);
+    return changes;
+}
 function getCrud(adapter) {
     return createCrudService(adapter, 'hazo_umetrics_action_def', {
         primaryKeys: ['action_key', 'app_id'],
@@ -66,6 +100,7 @@ export async function ensureActionDef(adapter, params) {
             url: params.url ?? null,
             is_key_event: 0,
             status: 'unclassified',
+            datapoint_schema: '[]',
             created_at: new Date().toISOString(),
             updated_at: new Date().toISOString(),
         });
@@ -125,23 +160,12 @@ export async function updateActionDef(adapter, params) {
     });
     if (!existing)
         return null;
+    const changes = applyPatch(rowToDef(existing), params.patch);
     const merged = {
         ...existing,
+        ...changes,
         updated_at: new Date().toISOString(),
     };
-    if (params.patch.label != null)
-        merged.label = params.patch.label;
-    if (params.patch.description != null)
-        merged.description = params.patch.description;
-    if ('parent_key' in params.patch)
-        merged.parent_key = params.patch.parent_key ?? null;
-    if ('url' in params.patch)
-        merged.url = params.patch.url ?? null;
-    if (params.patch.is_key_event != null) {
-        merged.is_key_event = params.patch.is_key_event ? 1 : 0;
-    }
-    if (params.patch.status != null)
-        merged.status = params.patch.status;
     await crud.upsert(merged, ['action_key', 'app_id']);
     return rowToDef(merged);
 }
@@ -232,3 +256,61 @@ export async function removeLink(adapter, params) {
         await crud.deleteWhere({ action_key: a, related_key: b, app_id: params.app_id });
     }
 }
+// ---------------------------------------------------------------------------
+// Bulk operations
+// ---------------------------------------------------------------------------
+/**
+ * Updates mutable fields across multiple action defs in one call.
+ * Returns lists of updated keys and missing (not found) keys.
+ */
+export async function updateActionDefBulk(adapter, params) {
+    if (params.action_keys.length === 0) {
+        return { updated: [], missing: [] };
+    }
+    const crud = getCrud(adapter);
+    const updated = [];
+    const missing = [];
+    for (const action_key of params.action_keys) {
+        const existing = await crud.findOneBy({
+            action_key,
+            app_id: params.app_id,
+        });
+        if (!existing) {
+            missing.push(action_key);
+            continue;
+        }
+        const changes = applyPatch(rowToDef(existing), params.patch);
+        const merged = {
+            ...existing,
+            ...changes,
+            updated_at: new Date().toISOString(),
+        };
+        await crud.upsert(merged, ['action_key', 'app_id']);
+        updated.push(action_key);
+    }
+    return { updated, missing };
+}
+/**
+ * Applies link additions and removals across multiple action keys (Cartesian product).
+ * For each action_key × each add_related key: calls addLink (idempotent, self-link guarded).
+ * For each action_key × each remove_related key: calls removeLink.
+ * Returns counts of added (non-null addLink results) and removed (all removeLink calls).
+ */
+export async function applyLinksBulk(adapter, params) {
+    let added = 0;
+    let removed = 0;
+    const addRelated = params.add_related ?? [];
+    const removeRelated = params.remove_related ?? [];
+    for (const action_key of params.action_keys) {
+        for (const related_key of addRelated) {
+            const result = await addLink(adapter, { app_id: params.app_id, action_key, related_key });
+            if (result !== null)
+                added++;
+        }
+        for (const related_key of removeRelated) {
+            await removeLink(adapter, { app_id: params.app_id, action_key, related_key });
+            removed++;
+        }
+    }
+    return { added, removed };
+}