hazo_umetrics 1.10.0 → 1.11.0

package/CHANGE_LOG.md

@@ -1,5 +1,69 @@
 # hazo_umetrics — Change Log
 
+## 1.11.0 — M1 GA4 live (OAuth connect + Admin provisioner + Data API funnels + windowed ga4 metrics)
+
+**M1 GA4 half shipped (minor — stubs replaced with real implementations; signatures widened, not broken):**
+
+### GA4 Data API client (`src/server/ga4.ts`, rewritten)
+- `createGa4Client({ propertyId, fetchToken, fetchImpl?, apiBaseUrl?, cacheTtlMs? })` replaces the M0 stub with a real client that issues raw `fetch` calls to `analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport`. Token comes from the caller-supplied `fetchToken()` (delegated to `hazo_auth`, see D-12) — the client never persists or reads credentials itself.
+- In-memory ~5min TTL cache, keyed per client instance; stale-if-error (a failed refetch serves the last good cached value rather than throwing). `cacheTtlMs` overridable for tests. (D-11, D-14)
+- `Ga4Report` return shape unchanged from M0 — existing callers of the stub keep working.
+
+### GA4 manifest + PII guard (`src/server/ga4_manifest.ts`, new)
+- `DEFAULT_GA4_MANIFEST` — the standard set of custom dimensions/metrics/key events `hazo_umetrics` provisions per app.
+- `mergeManifest` — combines the default manifest with an app-supplied override, de-duped by name.
+- `isPII` / `assertNoPII` — blocks dimension/metric names that look like PII (email, name, phone, etc.) before they're sent to the Admin API.
+- `MAX_EVENT_SCOPED_DIMENSIONS = 50` — GA4's own event-scoped custom dimension cap, enforced client-side with a hard error rather than letting the Admin API reject it opaquely.
+- `validateManifest` — runs both guards over a full manifest in one pass.
+- Metric `step_duration_ms` display name is `Step Duration` (not `Step Duration (ms)`) — GA4 Admin `display_name` allows only `[A-Za-z0-9_ ]`; the `MILLISECONDS` `measurementUnit` already conveys the unit. Caught in live provision smoke (400 `INVALID_ARGUMENT`).
+
+### GA4 Admin API provisioner (`src/server/ga4_provision.ts`, new)
+- Idempotent **list → create-missing → patch-drifted** flow for custom dimensions, custom metrics, and key events. Re-running provision on an already-provisioned property is a no-op (aside from patching any drifted display names/scopes).
+- Runs the manifest through `validateManifest` (PII + cap) before touching the Admin API.
+- Partial failures don't abort the whole run — the result comes back `status: 'error'` with a per-item error list, and any items that did succeed still have their resolved IDs returned.
+- Returns resolved `dimension_ids` / `metric_ids` / `key_event_ids` for persistence on the connection row.
+
+### Funnel read (`src/server/funnel.ts`, new)
+- `getFunnel(client, flow, dateRange)` — one `runReport` call (`eventCount` dimensioned by `eventName`, filtered with an `inListFilter` on the flow's step event names), then JS-side: reorders rows to match the flow's declared step order, computes per-step and cumulative drop-off, and overall conversion. (D-13)
+- Output shaped to drop straight into `hazo_ui`'s `FunnelChart`.
+
+### Windowed ga4 metrics live (`src/server/metrics.ts`, `src/server/ga4_metrics.ts` new)
+- `getMetricWindows` gains an optional third arg `{ ga4Reader }` — when supplied, `source: 'ga4'` metrics are no longer forced to `pending`.
+- `createGa4MetricWindowReader(...)` (new) looks up the app's GA4 connection row, reads the Data API through `ga4.ts`, and fills `total`/`24h`/`7d`/`28d`/`90d` for each registered `ga4` metric. Falls back to `pending: true` when the app has no connection yet — unchanged behaviour for unconnected apps.
+- Wired into `createStatHandlers.getMetricWindows` in `src/api/index.ts` so the `/stats/windows` route serves live GA4 numbers once an app is connected.
+
+### Connect / provision / funnel handlers (`src/api/index.ts`)
+- `createGa4ConnectHandlers` — `connect` now actually persists `connected_user_id` + the property/measurement IDs to the connection row (`disconnect: true` clears the row instead of deleting it, keeping history). `provision` delegates the OAuth token fetch to `hazo_auth`'s `getGoogleToken`, runs `ga4_provision.ts`, persists the resolved dimension/metric/key-event IDs, and writes an audit entry. New `funnel` handler wraps `getFunnel` for the `/ga4/funnel` route. (D-12)
+
+### Canonical flow helper (`src/lib/track_flow_step.ts`, exported from `hazo_umetrics/client`)
+- `trackFlowStep(flowId, step, params)` — gtag-guarded no-op when `window.gtag` isn't present (SSR-safe, no-op in tests). This is the shape intended to replace gotimer's `src/lib/ga-events.ts` — the gotimer migration itself is a separate, later session.
+
+### UI
+- `GA4ConnectionCard` (`src/ui/ga4_connection_card.tsx`, exported from `hazo_umetrics/ui`) — connect/disconnect + provision status card.
+- Test-app: new `/ga4` tab, plus `provision`, `funnel`, and jobs-snapshot demo routes.
+
+### DB migration
+- `hazo_umetrics_ga4_connection` gains `connected_user_id`, `metric_ids`, `key_event_ids` columns — both SQLite and PostgreSQL DDL, plus seed data updated. `credential_ref` stays in the schema but reserved/unused: the OAuth token itself is never stored by `hazo_umetrics` (delegated to `hazo_auth`, D-12).
+
+### Decisions
+- **D-11** Raw `fetch` to the GA4 Data/Admin REST APIs, not the `googleapis` SDK — keeps the dependency tree shallow.
+- **D-12** GA4 token delegated to `hazo_auth`'s `getGoogleToken` — no second credential store.
+- **D-13** Funnel step ordering/drop-off/conversion computed client-side in JS from a single `eventCount`×`eventName` report, not a multi-call server-side funnel API.
+- **D-14** In-memory ~5min TTL cache, stale-if-error, per client instance — scheduled background refresh deferred.
+
+### Tests
+- New mocked-`fetch` (no real Google calls) jest suites: manifest/PII guard, client + cache behaviour, funnel computation, provisioner (idempotency + partial failure), connect/provision/funnel handlers, live windowed-metrics read, and the flow-step helper. All green.
+
+## 1.10.1 — Windowed-metrics wiring fixes (exports `default` + `MetricsTab` `apiBase`)
+
+**Fixes (patch — surfaced while wiring consumer apps; both additive/back-compatible):**
+
+### `package.json` `exports` — add a `"default"` condition to every subpath
+- Each subpath (`.`, `./client`, `./api`, `./ui`) now declares `"default"` alongside `"import"`, mirroring `hazo_connect`/`hazo_jobs`. Without it, a static `import … from "hazo_umetrics"` under tooling that doesn't resolve the `"import"` condition (e.g. `tsx` standalone scripts) failed with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Consumer backfill/snapshot scripts had to use dynamic `await import()` as a workaround; they can now import statically.
+
+### `MetricsTab` — optional `apiBase` prop
+- `MetricsTab({ appId, apiBase = '/api/hazo_umetrics' })` builds the windows fetch from `${apiBase}/stats/windows` (trailing slash tolerated) instead of hardcoding `/api/hazo_umetrics/stats/windows`. Apps mounting umetrics under a different base can now point the tab at their route. Default preserves the previous behaviour (back-compatible). Matches `JourneyPanel`'s `apiBase` pattern.
+
 ## 1.10.0 — Per-app windowed metrics (registry + Total/24h/7d/28d/90d + graph)
 
 **New features (minor — additive; existing `MetricsPanel`/`statSnapshotJob` unaffected):**

package/config/hazo_umetrics_config.ini.sample

@@ -33,9 +33,13 @@ app_id = my_app
 ; env = development
 
 [ga4]
-; GA4 property ID (format: "properties/123456789"). Leave blank until M1 GA4 connect.
+; These three keys are OPTIONAL fallbacks only. Once an app completes the
+; /ga4 connect flow, the hazo_umetrics_ga4_connection table (per app_id) is
+; the source of truth for property_id/measurement_id — these ini values are
+; not read at runtime for a connected app. Leave commented in normal use.
+; GA4 property ID — BARE numeric id (the code prefixes "properties/"). e.g. 497179388
 ; property_id =
-; GA4 Measurement ID (format: "G-XXXXXXXX"). Required for client-side event tracking.
+; GA4 Measurement ID (format: "G-XXXXXXXX"). Required for client-side event tracking. e.g. G-CBY26RF5JD
 ; measurement_id =
 ; GA4 Data API base URL (default: https://analyticsdata.googleapis.com/v1beta/)
 ; api_base_url =

package/dist/api/index.d.ts

@@ -88,10 +88,29 @@ export declare function createExperimentHandlers(options: ApiFactoryOptions): {
     stopExperiment(req: Request): Promise<Response>;
 };
 export declare function createGa4ConnectHandlers(options: ApiFactoryOptions): {
-    /** STUB (M1): Initiate GA4 OAuth connection for an app. */
+    /**
+     * POST /...?app_id=<id>
+     * Body: { property_id, measurement_id, connected_user_id } | { disconnect: true }
+     * Persists (or clears) the per-app GA4 connection row. The browser has
+     * already driven Google consent (`requestGoogleScopes`) before calling this —
+     * this handler only records the resulting property/user linkage. Requires
+     * metrics.manage. Revocation of the Google token itself is delegated to
+     * hazo_auth's DELETE /google/token (not called here).
+     */
     connect(req: Request): Promise<Response>;
-    /** STUB (M1): Provision a GA4 property for an app. */
+    /**
+     * POST /...?app_id=<id>
+     * Idempotent GA4 Admin provision — creates/patches custom dimensions,
+     * custom metrics, and key events from DEFAULT_GA4_MANIFEST, then persists
+     * the resolved IDs + provision_status. Requires metrics.manage.
+     */
     provision(req: Request): Promise<Response>;
+    /**
+     * GET /...?app_id=<id>[&flow_id=<id>]
+     * Reads a funnel via the GA4 Data API for the manifest flow matching
+     * flow_id (defaults to the first flow). Requires metrics.view.
+     */
+    funnel(req: Request): Promise<Response>;
 };
 export declare function createQueryHandlers(options: ApiFactoryOptions): {
     /** STUB (M1): Execute a GA4 or stat-store query. */

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

@@ -7,10 +7,15 @@
 import { createCrudService } from 'hazo_connect/server';
 import { recordStat as _recordStat, getLatestStat as _getLatestStat, getStatSeries as _getStatSeries, } from '../server/stats.js';
 import { getMetricWindows as _getMetricWindows } from '../server/metrics.js';
+import { createGa4MetricWindowReader } from '../server/ga4_metrics.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, 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, searchQueries as _searchQueries, } from '../server/behavior.js';
+import { createGa4Client } from '../server/ga4.js';
+import { createGa4Provisioner } from '../server/ga4_provision.js';
+import { getFunnel } from '../server/funnel.js';
+import { DEFAULT_GA4_MANIFEST } from '../server/ga4_manifest.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).
@@ -184,7 +189,13 @@ export function createStatHandlers(options) {
                 return jsonError('BAD_REQUEST', 'app_id is required', 400);
             }
             const adapter = await options.getAdapter();
-            const windows = await _getMetricWindows(adapter, { app_id, days });
+            const ga4Reader = createGa4MetricWindowReader(adapter, {
+                getToken: async (userId, o) => {
+                    const { getGoogleToken } = await import('hazo_auth/server-lib');
+                    return getGoogleToken(userId, o);
+                },
+            });
+            const windows = await _getMetricWindows(adapter, { app_id, days }, { ga4Reader });
             return jsonOk({ windows });
         },
     };
@@ -344,12 +355,39 @@ export function createExperimentHandlers(options) {
     };
 }
 // ---------------------------------------------------------------------------
-// createGa4ConnectHandlers — STUB (M1)
+// createGa4ConnectHandlers — GA4 OAuth connection, Admin provisioning, and
+// funnel reads (M1 step 5, plan_m1_ga4.md).
+//
+// D-12/D-9: the Google OAuth token itself is never stored here — it's
+// delegated to hazo_auth's `getGoogleToken(userId, opts)`, lazily imported
+// inside each handler (mirrors `defaultGetAuth` above) so the `server-only`
+// guard in `hazo_auth/server-lib` never fires at module-evaluation time.
 // ---------------------------------------------------------------------------
+/** Google OAuth scopes needed to read + manage a GA4 property. */
+const ANALYTICS_SCOPES = [
+    'https://www.googleapis.com/auth/analytics.readonly',
+    'https://www.googleapis.com/auth/analytics.edit',
+];
+/** Read-only subset — sufficient for Data API funnel reads. */
+const ANALYTICS_READONLY_SCOPES = [ANALYTICS_SCOPES[0]];
 export function createGa4ConnectHandlers(options) {
     const getAuth = options.getAuth ?? defaultGetAuth;
+    function getConnectionCrud(adapter) {
+        return createCrudService(adapter, 'hazo_umetrics_ga4_connection', {
+            primaryKeys: ['app_id'],
+            autoId: false,
+        });
+    }
     return {
-        /** STUB (M1): Initiate GA4 OAuth connection for an app. */
+        /**
+         * POST /...?app_id=<id>
+         * Body: { property_id, measurement_id, connected_user_id } | { disconnect: true }
+         * Persists (or clears) the per-app GA4 connection row. The browser has
+         * already driven Google consent (`requestGoogleScopes`) before calling this —
+         * this handler only records the resulting property/user linkage. Requires
+         * metrics.manage. Revocation of the Google token itself is delegated to
+         * hazo_auth's DELETE /google/token (not called here).
+         */
         async connect(req) {
             const url = new URL(req.url);
             const app_id = url.searchParams.get('app_id') ?? '';
@@ -360,10 +398,70 @@ export function createGa4ConnectHandlers(options) {
             });
             if (!gate.ok)
                 return gate.response;
-            // STUB (M1)
-            return jsonOk({ status: 'stub' });
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { app_id: bodyAppId, property_id, measurement_id, connected_user_id, disconnect, } = body;
+            const resolvedAppId = (bodyAppId ?? app_id);
+            if (!resolvedAppId) {
+                return jsonError('BAD_REQUEST', 'app_id is required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const crud = getConnectionCrud(adapter);
+            if (disconnect) {
+                await crud.deleteWhere({ app_id: resolvedAppId });
+                await options.onAudit?.({
+                    action: 'ga4.disconnect',
+                    actor_id: gate.userId,
+                    app_id: resolvedAppId,
+                });
+                return jsonOk({ status: 'disconnected', app_id: resolvedAppId });
+            }
+            if (!property_id) {
+                return jsonError('BAD_REQUEST', 'property_id is required', 400);
+            }
+            const existing = await crud.findOneBy({ app_id: resolvedAppId });
+            const now = new Date().toISOString();
+            const merged = {
+                app_id: resolvedAppId,
+                scope_id: existing?.scope_id ?? '',
+                property_id,
+                measurement_id: measurement_id ?? existing?.measurement_id ?? null,
+                credential_ref: existing?.credential_ref ?? null,
+                provision_status: existing?.provision_status ?? 'unprovisioned',
+                last_provisioned_at: existing?.last_provisioned_at ?? null,
+                dimension_ids: existing?.dimension_ids ?? '[]',
+                connected_user_id: connected_user_id ?? existing?.connected_user_id ?? null,
+                metric_ids: existing?.metric_ids ?? '[]',
+                key_event_ids: existing?.key_event_ids ?? '[]',
+                created_at: existing?.created_at ?? now,
+                updated_at: now,
+            };
+            await crud.upsert(merged, ['app_id']);
+            await options.onAudit?.({
+                action: 'ga4.connect',
+                actor_id: gate.userId,
+                app_id: resolvedAppId,
+                details: { property_id },
+            });
+            return jsonOk({
+                status: 'connected',
+                app_id: resolvedAppId,
+                property_id: merged.property_id,
+                measurement_id: merged.measurement_id,
+                connected_user_id: merged.connected_user_id,
+            });
         },
-        /** STUB (M1): Provision a GA4 property for an app. */
+        /**
+         * POST /...?app_id=<id>
+         * Idempotent GA4 Admin provision — creates/patches custom dimensions,
+         * custom metrics, and key events from DEFAULT_GA4_MANIFEST, then persists
+         * the resolved IDs + provision_status. Requires metrics.manage.
+         */
         async provision(req) {
             const url = new URL(req.url);
             const app_id = url.searchParams.get('app_id') ?? '';
@@ -374,8 +472,126 @@ export function createGa4ConnectHandlers(options) {
             });
             if (!gate.ok)
                 return gate.response;
-            // STUB (M1)
-            return jsonOk({ status: 'stub' });
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const bodyAppId = body.app_id;
+            const resolvedAppId = (bodyAppId ?? app_id);
+            if (!resolvedAppId) {
+                return jsonError('BAD_REQUEST', 'app_id is required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const crud = getConnectionCrud(adapter);
+            const row = await crud.findOneBy({ app_id: resolvedAppId });
+            if (!row) {
+                return jsonOk({ status: 'error', error: 'not_connected' });
+            }
+            const { getGoogleToken } = await import('hazo_auth/server-lib');
+            let result;
+            try {
+                const provisioner = createGa4Provisioner({
+                    propertyId: row.property_id,
+                    fetchToken: async () => {
+                        const t = await getGoogleToken(row.connected_user_id, {
+                            scopes: ANALYTICS_SCOPES,
+                        });
+                        if (!t.ok)
+                            throw new Error('ga4_token_' + t.error);
+                        return t.access_token;
+                    },
+                });
+                result = await provisioner.provision();
+            }
+            catch (err) {
+                return jsonOk({
+                    status: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            const now = new Date().toISOString();
+            const updatedRow = {
+                ...row,
+                dimension_ids: JSON.stringify(result.dimension_ids),
+                metric_ids: JSON.stringify(result.metric_ids),
+                key_event_ids: JSON.stringify(result.key_event_ids),
+                provision_status: result.status,
+                last_provisioned_at: now,
+                updated_at: now,
+            };
+            await crud.upsert(updatedRow, ['app_id']);
+            await options.onAudit?.({
+                action: 'ga4.provision',
+                actor_id: gate.userId,
+                app_id: resolvedAppId,
+                details: { created: result.created, patched: result.patched, status: result.status, errors: result.errors },
+            });
+            return jsonOk({
+                status: result.status,
+                property_id: row.property_id,
+                provision: { created: result.created, patched: result.patched, skipped: result.skipped },
+                dimension_ids: result.dimension_ids,
+                metric_ids: result.metric_ids,
+                key_event_ids: result.key_event_ids,
+                errors: result.errors,
+            });
+        },
+        /**
+         * GET /...?app_id=<id>[&flow_id=<id>]
+         * Reads a funnel via the GA4 Data API for the manifest flow matching
+         * flow_id (defaults to the first flow). Requires metrics.view.
+         */
+        async funnel(req) {
+            const url = new URL(req.url);
+            const app_id = url.searchParams.get('app_id') ?? '';
+            const flow_id = url.searchParams.get('flow_id') ?? 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 crud = getConnectionCrud(adapter);
+            const row = await crud.findOneBy({ app_id });
+            if (!row) {
+                return jsonOk({ status: 'error', error: 'not_connected' });
+            }
+            const flow = flow_id
+                ? DEFAULT_GA4_MANIFEST.flows.find((f) => f.flowId === flow_id)
+                : DEFAULT_GA4_MANIFEST.flows[0];
+            if (!flow) {
+                return jsonOk({ status: 'error', error: 'unknown_flow' });
+            }
+            try {
+                const { getGoogleToken } = await import('hazo_auth/server-lib');
+                const client = createGa4Client({
+                    propertyId: row.property_id,
+                    fetchToken: async () => {
+                        const t = await getGoogleToken(row.connected_user_id, {
+                            scopes: ANALYTICS_READONLY_SCOPES,
+                        });
+                        if (!t.ok)
+                            throw new Error('ga4_token_' + t.error);
+                        return t.access_token;
+                    },
+                });
+                const result = await getFunnel(client, flow, { startDate: '28daysAgo', endDate: 'today' });
+                return jsonOk({ status: 'ok', funnel: result, as_of: new Date().toISOString() });
+            }
+            catch (err) {
+                return jsonOk({
+                    status: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
         },
     };
 }

package/dist/index.client.d.ts

@@ -1,4 +1,6 @@
 import React from 'react';
+export { trackFlowStep } from './lib/track_flow_step.js';
+export type { TrackFlowStepParams } from './lib/track_flow_step.js';
 interface MetricsContextValue {
     appId: string | null | undefined;
     track: (metricKey: string, dimensions?: Record<string, string | number>) => void;
@@ -25,5 +27,4 @@ export declare function getIdentity(): {
 export declare function recordStat(_key: string, _value: number, _opts?: {
     unit?: string;
 }): void;
-export {};
 //# sourceMappingURL=index.client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,OAAO,CAAC;AAoD1B,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACjF,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1G,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;CAClE;AASD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,wBAAwB,4EAsJxF;AAMD,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD;AAMD,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAK7C;AAED,wBAAgB,WAAW,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAE5E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAExF"}
+{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAmDpE,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACjF,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1G,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;CAClE;AASD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,wBAAwB,4EAsJxF;AAMD,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD;AAMD,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAK7C;AAED,wBAAgB,WAAW,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAE5E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAExF"}

package/dist/index.client.js

@@ -3,6 +3,7 @@
 'use client';
 import React from 'react';
 import { usePathname } from 'next/navigation';
+export { trackFlowStep } from './lib/track_flow_step.js';
 // ---------------------------------------------------------------------------
 // Anonymous session identity (localStorage, SSR-guarded)
 // ---------------------------------------------------------------------------

package/dist/lib/index.d.ts

@@ -5,6 +5,10 @@ export * from '../server/actions.js';
 export * from '../server/flags.js';
 export * from '../server/cookie.js';
 export * from '../server/ga4.js';
+export * from '../server/ga4_manifest.js';
+export * from '../server/ga4_provision.js';
+export * from '../server/funnel.js';
+export * from '../server/ga4_metrics.js';
 export * from '../server/experiments.js';
 export * from '../server/activity.js';
 export * from '../server/behavior.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}

package/dist/lib/index.js

@@ -6,6 +6,10 @@ export * from '../server/actions.js';
 export * from '../server/flags.js';
 export * from '../server/cookie.js';
 export * from '../server/ga4.js';
+export * from '../server/ga4_manifest.js';
+export * from '../server/ga4_provision.js';
+export * from '../server/funnel.js';
+export * from '../server/ga4_metrics.js';
 export * from '../server/experiments.js';
 export * from '../server/activity.js';
 export * from '../server/behavior.js';

package/dist/lib/track_flow_step.d.ts

@@ -0,0 +1,21 @@
+export interface TrackFlowStepParams {
+    variant?: string;
+    featureFlag?: string;
+    appSection?: string;
+    stepDurationMs?: number;
+    [extra: string]: string | number | undefined;
+}
+declare global {
+    interface Window {
+        gtag?: (...args: unknown[]) => void;
+    }
+}
+/**
+ * Emits a GA4 event named `step`, with manifest dimension params:
+ * `flow_id`, `flow_step`, `variant`, `feature_flag`, `app_section`, `step_duration_ms`,
+ * plus any extra keys passed through as-is. Undefined params are omitted.
+ *
+ * Safe no-op when `window.gtag` isn't present (SSR, no GA loaded).
+ */
+export declare function trackFlowStep(flowId: string, step: string, params?: TrackFlowStepParams): void;
+//# sourceMappingURL=track_flow_step.d.ts.map

package/dist/lib/track_flow_step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track_flow_step.d.ts","sourceRoot":"","sources":["../../src/lib/track_flow_step.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;KACrC;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAoB9F"}

package/dist/lib/track_flow_step.js

@@ -0,0 +1,33 @@
+// hazo_umetrics/src/lib/track_flow_step.ts — canonical client-safe flow-event helper.
+// Emits a GA4 event via window.gtag using the manifest's dimension params. Mirrors the
+// shape of gotimer's src/lib/ga-events.ts (which this replaces — that repo is untouched here).
+// Must stay client-safe: no Node.js builtins, no server-only imports.
+/**
+ * Emits a GA4 event named `step`, with manifest dimension params:
+ * `flow_id`, `flow_step`, `variant`, `feature_flag`, `app_section`, `step_duration_ms`,
+ * plus any extra keys passed through as-is. Undefined params are omitted.
+ *
+ * Safe no-op when `window.gtag` isn't present (SSR, no GA loaded).
+ */
+export function trackFlowStep(flowId, step, params) {
+    if (typeof window === 'undefined' || typeof window.gtag !== 'function')
+        return;
+    const { variant, featureFlag, appSection, stepDurationMs, ...extra } = params ?? {};
+    const eventParams = {
+        flow_id: flowId,
+        flow_step: step,
+    };
+    if (variant !== undefined)
+        eventParams.variant = variant;
+    if (featureFlag !== undefined)
+        eventParams.feature_flag = featureFlag;
+    if (appSection !== undefined)
+        eventParams.app_section = appSection;
+    if (stepDurationMs !== undefined)
+        eventParams.step_duration_ms = stepDurationMs;
+    for (const [key, value] of Object.entries(extra)) {
+        if (value !== undefined)
+            eventParams[key] = value;
+    }
+    window.gtag('event', step, eventParams);
+}

package/dist/server/funnel.d.ts

@@ -0,0 +1,38 @@
+import type { Ga4Flow } from './ga4_manifest.js';
+export interface Ga4RunReportClient {
+    runReport(params: {
+        metrics: string[];
+        dimensions: string[];
+        dateRanges: Array<{
+            startDate: string;
+            endDate: string;
+        }>;
+        dimensionFilter?: unknown;
+        metricAggregations?: string[];
+    }): Promise<{
+        rows: Array<{
+            dimensions: string[];
+            metrics: string[];
+        }>;
+        rowCount: number;
+    }>;
+}
+export interface FunnelStep {
+    step: string;
+    label: string;
+    count: number;
+    dropOff: number;
+    dropOffPct: number;
+    conversionFromStart: number;
+}
+export interface FunnelResult {
+    flowId: string;
+    steps: FunnelStep[];
+    totalEntered: number;
+    overallConversion: number;
+}
+export declare function getFunnel(client: Ga4RunReportClient, flow: Ga4Flow, dateRange: {
+    startDate: string;
+    endDate: string;
+}): Promise<FunnelResult>;
+//# sourceMappingURL=funnel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"funnel.d.ts","sourceRoot":"","sources":["../../src/server/funnel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,MAAM,EAAE;QAChB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,EAAE,KAAK,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC/B,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7F;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAWD,wBAAsB,SAAS,CAC7B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,OAAO,EACb,SAAS,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAAC,YAAY,CAAC,CAoDvB"}

package/dist/server/funnel.js

@@ -0,0 +1,60 @@
+// hazo_umetrics/src/server/funnel.ts — GA4-backed funnel read.
+//
+// D-13: funnels computed client-side from `eventCount x eventName` (Data API v1beta
+// has no native funnelReport). G-6/G-13: a single runReport grouped by eventName,
+// filtered to the flow's step events via an inListFilter — ordering + drop-off math
+// happen here in JS, not in GA4.
+/** Title-cases an event/step name: `timer_start` -> `Timer Start`. */
+function titleCase(step) {
+    return step
+        .split('_')
+        .filter((word) => word.length > 0)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+export async function getFunnel(client, flow, dateRange) {
+    const report = await client.runReport({
+        metrics: ['eventCount'],
+        dimensions: ['eventName'],
+        dateRanges: [dateRange],
+        dimensionFilter: {
+            filter: {
+                fieldName: 'eventName',
+                inListFilter: { values: flow.steps },
+            },
+        },
+    });
+    const countsByEvent = new Map();
+    for (const row of report.rows) {
+        const eventName = row.dimensions[0];
+        const count = parseInt(row.metrics[0], 10);
+        countsByEvent.set(eventName, Number.isNaN(count) ? 0 : count);
+    }
+    const firstCount = countsByEvent.get(flow.steps[0]) ?? 0;
+    const steps = [];
+    let prevCount = 0;
+    flow.steps.forEach((step, index) => {
+        const count = countsByEvent.get(step) ?? 0;
+        const isFirst = index === 0;
+        const dropOff = isFirst ? 0 : Math.max(prevCount - count, 0);
+        const dropOffPct = isFirst ? 0 : prevCount > 0 ? Math.round(((prevCount - count) / prevCount) * 1000) / 10 : 0;
+        const conversionFromStart = firstCount > 0 ? count / firstCount : isFirst ? 0 : 0;
+        steps.push({
+            step,
+            label: titleCase(step),
+            count,
+            dropOff,
+            dropOffPct,
+            conversionFromStart: isFirst ? (firstCount > 0 ? 1 : 0) : conversionFromStart,
+        });
+        prevCount = count;
+    });
+    const lastCount = steps.length > 0 ? steps[steps.length - 1].count : 0;
+    const overallConversion = firstCount > 0 ? lastCount / firstCount : 0;
+    return {
+        flowId: flow.flowId,
+        steps,
+        totalEntered: firstCount,
+        overallConversion,
+    };
+}