@metricinsights/ca-analytics 0.1.0 → 0.3.0

package/README.md

@@ -33,19 +33,22 @@ npm i @metricinsights/ca-analytics
 
 ## Usage
 
-```ts
+```tsx
 import { init, useAnalytics } from '@metricinsights/ca-analytics';
 
 // app entry, once
-init({ app: 'my-portal-page' });
+init();
+
+// in any component
+function RevenueTile() {
+  const { track } = useAnalytics();
 
-// anywhere in the app
-const { track } = useAnalytics();
-track('tile_clicked', { tile: 'revenue' });
+  return <button onClick={() => track('tile_clicked', { tile: 'revenue' })}>Revenue</button>;
+}
 ```
 
 `useAnalytics()` is a thin wrapper over the module singleton — no provider, no context, callable
-from any component.
+from any component. Outside React, import `track`, `trackElement` and `trackPageView` directly.
 
 ## API
 
@@ -64,11 +67,15 @@ later `init()` inside the 30-minute idle window resumes the *same* `session_id`.
 
 | Export | Signature | Notes |
 | --- | --- | --- |
-| `track` | `(event: string, props?: Record<string, unknown>) => void` | Empty and [reserved](#events) names are ignored. |
-| `trackElement` | `(props: { element_id: number; segment_id?: number; [key: string]: unknown }) => void` | Emits `element_click`. |
+| `track` | `(event: string, props?: object) => void` | Empty and [reserved](#events) names are ignored. |
+| `trackElement` | `<T extends { element_id: number; segment_id?: number }>(props: T) => void` | Emits `element_click`. |
 | `trackPageView` | `(path?: string) => void` | For routers the `history` patch cannot observe. Skips dedupe — always emits. |
 | `useAnalytics` | `() => { track, trackElement, trackPageView }` | React hook; no provider needed. |
 
+Props can be any object, including interface-typed ones, with values of any type. They are
+serialized with `JSON.stringify` semantics: a `Date` becomes its ISO string, and `undefined` and
+functions are dropped.
+
 ### Constants
 
 | Export | Value | Notes |
@@ -82,14 +89,8 @@ Every option is optional. Each falls back to a portal-page variable, then to a d
 
 | Option | Variable | Default | Effect |
 | --- | --- | --- | --- |
-| `app` | — | derived from the URL | Portal page internal name. |
 | `enabled` | `CUSTOM_APP_ANALYTICS_ENABLED` | `true` | `false` disables all tracking. |
 
-`app` is derived from `location.pathname` against `/^\/(p[tl]?)\/([^/]+)(.*)$/`. **If it cannot
-be derived and isn't passed, `init()` stays silent** rather than writing rows with a blank `app`
-that nothing could attribute. This is why a bare `init()` does nothing on a local dev server,
-where the path is `/`.
-
 Portal-page variables are read from `window.PP_VARIABLES` and always arrive as **strings**.
 `'0'`, `'false'`, `'n'`, `'no'` (case-insensitive, trimmed) mean disabled; any other non-empty
 string means enabled. Unset, empty, or left unsubstituted by MI (a literal `[Custom App
@@ -99,9 +100,9 @@ Analytics Enabled]`) counts as *not set* and falls through to the option or defa
 
 | Event | Fires when | `meta` |
 | --- | --- | --- |
-| `page_view` | Once on `init()`, then on every `pushState` / `replaceState` / `popstate`, or on demand via `trackPageView()`. | `referrer`, `query` — always both, always strings |
+| `page_view` | Once on `init()`, then on every `pushState` / `replaceState` / `popstate` / `hashchange`, or on demand via `trackPageView()`. | `referrer`, `query` — always both, always strings |
 | `heartbeat` | Tab visible: every 60s for 5 beats, then every 300s. | `{}` |
-| `component_render` | The `mi-render` `CustomEvent` MI dispatches on `document`. | `component`, `element_id`, `segment_id` |
+| `component_render` | The `mi-render` `CustomEvent` MI dispatches on `document`. | `component`, `element_id`, `segment_id`, plus each prop as `prop.<path>` |
 | `element_click` | `trackElement()`. | `element_id`, `segment_id`, plus your own keys |
 | *(custom)* | `track(name, props)`. | your `props` verbatim |
 
@@ -113,23 +114,44 @@ name that does not match is still tracked verbatim but logs one console warning,
 dataset is append-only with no rename — `'Tile Click'`, `'tile_click '` and `'tileClick'` would
 become three permanent, unmergeable series. Reserved-name matching is case-insensitive.
 
-Two meta keys are reserved: `_truncated` is stamped only when meta actually exceeds 2000
-characters, and the dashboard hides both `_truncated` and `capped` from its property view, so do
+Two meta keys are reserved: `_truncated` is stamped only when meta exceeds 2000 characters or
+cannot be serialized as a whole (for example a `BigInt` or a circular value), and the dashboard hides both `_truncated` and `capped` from its property view, so do
 not use either as your own prop name.
 
-**`page_view`** dedupes on path + search, so a router calling `replaceState` for scroll or filter
-sync does not emit. `meta.referrer` follows GA4 semantics: the first view of the document uses
-`document.referrer` normalized to origin + pathname; every later view uses the `page_path` of the
-previous view. `meta.query` is `location.search` without the leading `?`. Both are capped at 300
-characters; either can be `''`.
+**`page_view`** dedupes on path + search (+ hash route, see below), so a router calling
+`replaceState` for scroll or filter sync does not emit. `meta.referrer` follows GA4 semantics: the
+first view of the document uses `document.referrer` normalized to origin + pathname; every later
+view uses the `page_path` of the previous view. `meta.query` is `location.search` without the
+leading `?`. Both are capped at 300 characters; either can be `''`.
+
+**Hash routing.** Hash-routed apps (for example React Router's `HashRouter`) are tracked without
+extra setup. When `location.hash` starts with `#/`, the fragment is the route: `#/reports/42?tab=1`
+records `page_path` `/reports/42` (it replaces any path below the portal page), and the fragment's
+own query is appended to `meta.query` with `&` (`?embed=1#/reports?tab=1` → `embed=1&tab=1`). A
+change of the hash route is a new view. A plain in-page anchor (`#section`, anything not starting
+with `#/`) is not a route: it never changes `page_path` and never emits a `page_view`.
+
+**`component_render`** reads `detail.component` plus `detail.props`. `MiNamespace.render()` is a
+pure event emitter, so `document` sees every shared component render — no patching.
+
+Identity comes only from `element`/`element_id` and `segment`/`segment_id`/`segment_value_id` —
+the spellings MI's own components use. No other key feeds `element_id`, which joins to
+`/api/element_info`, where a foreign numeric id would join wrong.
 
-**`component_render`** reads `detail.component` plus `detail.props`, accepting either
-`{element, segment}` or `{element_id, segment_value_id}`. Capped at 50 emits per distinct
-component + element + segment per page load; the emit that hits the cap carries `capped: 1`.
-`MiNamespace.render()` is a pure event emitter, so listening on `document` observes every shared
-component render without patching or wrapping anything.
+Every other prop flattens to `prop.<dotted.path>` — flat, because the dashboard summarizes per
+key and a nested object collapses to one opaque string. Scalars verbatim, strings capped at 40,
+arrays as `arr:<length>`, 4 levels deep, 40 keys. When the depth or key cap drops a prop, the row
+carries `props_dropped: 1`.
 
-**`trackElement`** needs `element_id` to be finite and non-zero — anything else drops the event
+Props are stored verbatim and readable by anyone with dashboard access. Keep record-specific text
+out of props you render with.
+
+Capped at 50 emits per distinct component + element + segment + props; the capping emit carries
+`capped: 1`. Past 200 distinct buckets per `init()`, a render that would open a new bucket goes into
+one shared overflow bucket per component instead, which has the same cap of 50.
+
+**`trackElement`** needs `element_id` to be a non-zero number within the `int` column's range
+(−2³¹ … 2³¹−1; a fraction is truncated) — anything else drops the event
 (one `console.warn` per runtime). `segment_id` is optional and defaults to `0` when omitted, with
 no warning; a supplied non-finite value also records `0` but logs one `console.warn` per runtime.
 Extra props pass through to `meta` untouched, and
@@ -148,25 +170,30 @@ stamps itself — the client never sends it.
 | --- | --- | --- |
 | `id` | text | Client UUID. Reused across a retry so readers dedupe with `COUNT(DISTINCT id)`. |
 | `ts` | datetime | `YYYY-MM-DD HH:MM:SS`, UTC. **Never ISO** — see [One-way doors](#one-way-doors). |
-| `app` | text | Portal page internal name, capped at 100. |
+| `app` | text | Portal page internal name, read from `location.pathname` against `/^\/(p[tl]?)\/([^/]+)(.*)$/`. Capped at 100. |
 | `event` | text | Capped at 100. |
 | `session_id` | text | New session after 30 minutes idle. Survives reloads via `localStorage`. |
-| `page_path` | text | Route below the portal page, `/` at the root. Capped at 400. |
+| `page_path` | text | Route below the portal page, `/` at the root; a `#/` hash route when present (see [Hash routing](#events)). Capped at 400. |
 | `element_id` | int | `0` when not applicable. Integers only. |
 | `version` | text | This package's version, capped at 20. |
 | `meta` | text | JSON string, capped at 2000. |
 
+`pp-dev` serves that same path locally. **Off that path shape, `init()` stays silent** rather
+than writing rows with a blank `app` that nothing could attribute.
+
 Text columns are wide (10500) and the caps above are client-side payload budget, keeping a batch
 inside `sendBeacon`'s 64 KiB quota — they are not schema limits.
 
 `meta` over 2000 characters drops whole keys rather than slicing, so the stored value always
-parses, and stamps `_truncated: 1`.
+parses, and stamps `_truncated: 1`. Meta that `JSON.stringify` cannot serialize as a whole takes the
+same path: keys that fail on their own are dropped, and `_truncated: 1` is stamped.
 
 ## Delivery
 
 Rows buffer and flush on whichever comes first: 15 seconds, 50 rows, or 30 KB encoded. On
 `pagehide`, and on `visibilitychange` to hidden (which is what actually fires on iOS), the buffer
-goes out via `sendBeacon`, falling back to `fetch(…, { keepalive: true })`.
+goes out via `sendBeacon`, falling back to `fetch(…, { keepalive: true })`, in chunks of at most
+30 KB each.
 
 A failed batch retries once after 2 seconds — network errors, 429 and 5xx are retryable; a `200`
 carrying a non-zero `resultCode` is a rejected insert and is not. A failed batch is dropped, not
@@ -196,6 +223,15 @@ wrapped.
 >   (`int → float → text`). One float or string converts the column permanently.
 > - **Never send `owner_user_id`.** The server stamps it and creates the column itself.
 
+## Releases
+
+Releases use the shared workflows from [mi-examples-workflows](https://github.com/mi-examples/mi-examples-workflows) ([release flow](https://github.com/mi-examples/mi-examples-workflows/blob/main/docs/workflows.md#release-workflows)). This repository has no `develop` branch, so there are no betas:
+
+1. Run **Actions → Release → Run workflow**. It opens a release pull request `release/vX.Y.Z → main` with the version bump and the new `CHANGELOG.md` entry.
+2. Review and edit the entry in the pull request, then merge it.
+3. Merging publishes to npm under `latest` and creates the tag and the GitHub release.
+
+Versions come from [Conventional Commits](https://www.conventionalcommits.org/) (`feat` → minor; `fix`, `perf`, `revert` → patch; `!` or `BREAKING CHANGE:` → major). Publishing uses npm Trusted Publishing (OIDC) from `.github/workflows/release.yml`, so don't rename that file.
 ## License
 
 MIT © 2026 Metric Insights

package/dist/index.cjs

@@ -34,7 +34,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/core/constants.ts
 var ENTITY_NAME = "analytics_events";
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 var MI_PAGE_PATH_RE = /^\/(p[tl]?)\/([^/]+)(.*)$/;
 var WIDTHS = {
   app: 100,
@@ -66,25 +66,44 @@ function matchPage() {
   if (typeof window === "undefined" || !window.location) return null;
   return MI_PAGE_PATH_RE.exec(window.location.pathname);
 }
+function isHashRoute(hash2) {
+  return hash2.startsWith("#/");
+}
+function hashRoute() {
+  const hash2 = window.location.hash;
+  if (!isHashRoute(hash2)) return null;
+  const route = hash2.slice(1);
+  const pathEnd = route.search(/[?#]/);
+  const path = pathEnd === -1 ? route : route.slice(0, pathEnd);
+  const queryMatch = /\?([^#]*)/.exec(route);
+  return { path, query: queryMatch ? queryMatch[1] : "" };
+}
 function currentPagePath() {
   const match = matchPage();
   if (!match) return "/";
-  const rest = match[3];
+  const rest = hashRoute()?.path ?? match[3];
   return (rest && rest !== "" && rest !== "/" ? rest : "/").slice(0, WIDTHS.page_path);
 }
+function currentQuery() {
+  const outer = window.location.search.replace(/^\?/, "");
+  const inner = hashRoute()?.query ?? "";
+  return outer && inner ? `${outer}&${inner}` : outer || inner;
+}
 function resolveConfig(options = {}) {
   const enabled = options.enabled ?? readFlag("CUSTOM_APP_ANALYTICS_ENABLED") ?? true;
   if (!enabled) return null;
-  const app = (options.app ?? matchPage()?.[2] ?? "").slice(0, WIDTHS.app);
+  const app = (matchPage()?.[2] ?? "").slice(0, WIDTHS.app);
   if (!app) return null;
   return { app, endpoint: `/data/page/${encodeURIComponent(app)}/${ENTITY_NAME}` };
 }
 
 // src/core/event.ts
 var pad2 = (n) => String(n).padStart(2, "0");
+var INT32_MIN = -(2 ** 31);
+var INT32_MAX = 2 ** 31 - 1;
 function toId(value) {
-  const n = Number(value);
-  return Number.isFinite(n) ? Math.trunc(n) : 0;
+  const n = Math.trunc(Number(value));
+  return Number.isSafeInteger(n) && n >= INT32_MIN && n <= INT32_MAX ? n : 0;
 }
 function formatTs(date) {
   return `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())} ${pad2(date.getUTCHours())}:${pad2(date.getUTCMinutes())}:${pad2(date.getUTCSeconds())}`;
@@ -179,12 +198,13 @@ function sendOnUnload(endpoint, rows) {
   } catch {
   }
   try {
-    void fetch(endpoint, {
+    fetch(endpoint, {
       method: "POST",
       credentials: "same-origin",
       headers: { "Content-Type": "application/json" },
       body,
       keepalive: true
+    }).catch(() => {
     });
   } catch {
   }
@@ -196,6 +216,22 @@ var MAX_FLUSH_ROWS = 50;
 var MAX_FLUSH_BYTES = 3e4;
 var MAX_CONSECUTIVE_FAILURES = 3;
 var textEncoder = new TextEncoder();
+function chunkBySize(rows, maxBytes) {
+  const chunks = [];
+  let current = [];
+  let size = 2;
+  for (const row of rows) {
+    if (current.length > 0 && size + 1 + row.size > maxBytes) {
+      chunks.push(current);
+      current = [];
+      size = 2;
+    }
+    size += (current.length > 0 ? 1 : 0) + row.size;
+    current.push(row);
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
 function createQueue(endpoint, onKilled) {
   let buffer = [];
   let bytes = 0;
@@ -218,8 +254,8 @@ function createQueue(endpoint, onKilled) {
     buffer = [];
     bytes = 0;
     inFlight = true;
+    let outcome = "failed";
     try {
-      let outcome;
       try {
         outcome = await send(
           endpoint,
@@ -228,6 +264,7 @@ function createQueue(endpoint, onKilled) {
       } catch {
         outcome = "failed";
       }
+      if (stopped) return;
       if (outcome === "ok") {
         failures = 0;
         return;
@@ -243,6 +280,7 @@ function createQueue(endpoint, onKilled) {
       }
     } finally {
       inFlight = false;
+      if (!stopped && outcome === "ok" && (buffer.length >= MAX_FLUSH_ROWS || bytes >= MAX_FLUSH_BYTES)) void flush();
     }
   }
   return {
@@ -267,10 +305,12 @@ function createQueue(endpoint, onKilled) {
       const batch = buffer;
       buffer = [];
       bytes = 0;
-      sendOnUnload(
-        endpoint,
-        batch.map((b) => b.json)
-      );
+      for (const chunk of chunkBySize(batch, MAX_FLUSH_BYTES)) {
+        sendOnUnload(
+          endpoint,
+          chunk.map((b) => b.json)
+        );
+      }
     },
     stop
   };
@@ -380,6 +420,53 @@ function startHeartbeat(emit) {
 
 // src/core/signals/miRender.ts
 var RENDER_CAP = 50;
+var MAX_KEYS = 200;
+var PROP_DEPTH = 4;
+var PROP_KEYS = 40;
+var PROP_STRING = 40;
+var IDENTITY_KEYS = /* @__PURE__ */ new Set(["element", "element_id", "segment", "segment_id", "segment_value_id"]);
+var SKIP = /* @__PURE__ */ Symbol("skip");
+function leafValue(value) {
+  if (value === null) return null;
+  switch (typeof value) {
+    case "boolean":
+      return value;
+    case "number":
+      return Number.isFinite(value) ? value : SKIP;
+    case "string":
+      return value.slice(0, PROP_STRING);
+    default:
+      return SKIP;
+  }
+}
+function flattenProps(source, out, prefix, depth) {
+  let dropped = false;
+  for (const [key, value] of Object.entries(source)) {
+    if (Object.keys(out).length >= PROP_KEYS) return true;
+    if (depth === 0 && IDENTITY_KEYS.has(key)) continue;
+    const path = prefix === "" ? key : `${prefix}.${key}`;
+    if (Array.isArray(value)) {
+      out[`prop.${path}`] = `arr:${value.length}`;
+      continue;
+    }
+    if (value !== null && typeof value === "object") {
+      if (depth + 1 < PROP_DEPTH) dropped = flattenProps(value, out, path, depth + 1) || dropped;
+      else dropped = true;
+      continue;
+    }
+    const leaf = leafValue(value);
+    if (leaf !== SKIP) out[`prop.${path}`] = leaf;
+  }
+  return dropped;
+}
+function hash(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i += 1) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(36);
+}
 function startMiRender(emit) {
   let stopped = false;
   const counts = /* @__PURE__ */ new Map();
@@ -392,16 +479,21 @@ function startMiRender(emit) {
       if (!component) return;
       const props = detail.props && typeof detail.props === "object" ? detail.props : {};
       const elementId = toId(props.element ?? props.element_id ?? 0);
-      const segmentId = toId(props.segment ?? props.segment_value_id ?? 0);
-      const key = `${component}|${elementId}|${segmentId}`;
+      const segmentId = toId(props.segment ?? props.segment_id ?? props.segment_value_id ?? 0);
+      const flat = {};
+      const propsDropped = flattenProps(props, flat, "", 0);
+      const bucket = `${component}|${elementId}|${segmentId}|${hash(JSON.stringify(flat))}`;
+      const key = counts.has(bucket) || counts.size < MAX_KEYS ? bucket : `${component}|*`;
       const seq = (counts.get(key) ?? 0) + 1;
       if (seq > RENDER_CAP) return;
       counts.set(key, seq);
       const meta = {
         component,
         element_id: elementId,
-        segment_id: segmentId
+        segment_id: segmentId,
+        ...flat
       };
+      if (propsDropped) meta.props_dropped = 1;
       if (seq === RENDER_CAP) meta.capped = 1;
       emit({ elementId, meta });
     } catch {
@@ -434,7 +526,8 @@ function startPageView(emit, currentPath) {
   let lastLocation = null;
   const locationKey = (path) => {
     try {
-      return `${path}${window.location.search}`;
+      const { search, hash: hash2 } = window.location;
+      return `${path}${search}${isHashRoute(hash2) ? hash2 : ""}`;
     } catch {
       return path;
     }
@@ -465,6 +558,7 @@ function startPageView(emit, currentPath) {
   window.history.replaceState = patchedReplace;
   const onPopState = () => safeEmit(currentPath, true);
   window.addEventListener("popstate", onPopState);
+  window.addEventListener("hashchange", onPopState);
   safeEmit(currentPath, true);
   return {
     stop() {
@@ -478,6 +572,7 @@ function startPageView(emit, currentPath) {
         window.history.replaceState = originalReplace;
       }
       window.removeEventListener("popstate", onPopState);
+      window.removeEventListener("hashchange", onPopState);
     },
     emitNow(path) {
       safeEmit(() => path ?? currentPath(), false);
@@ -500,7 +595,7 @@ function warnOnce(key, message) {
   console.warn(`[ca-analytics] ${message}`);
 }
 function pageViewMeta(referrer) {
-  const query = window.location.search.replace(/^\?/, "");
+  const query = currentQuery();
   return { referrer: referrer.slice(0, LIMITS.referrer), query: query.slice(0, LIMITS.query) };
 }
 function stopStarted(parts, flushFirst) {
@@ -524,7 +619,9 @@ function init(options = {}) {
     if (runtime) return;
     const config = resolveConfig(options);
     if (!config) return;
-    const queue = createQueue(config.endpoint, () => shutdown());
+    const queue = createQueue(config.endpoint, () => {
+      if (runtime?.queue === queue) shutdown();
+    });
     const emit = (event, extra = {}) => {
       queue.push(
         createRow({
@@ -587,7 +684,7 @@ function trackElement(props) {
     const { element_id, segment_id, ...extra } = props ?? {};
     const id = toId(element_id);
     if (!id) {
-      warnOnce("element", `trackElement() ignored a non-finite or zero element_id (${element_id})`);
+      warnOnce("element", `trackElement() ignored a zero, non-finite or out-of-range element_id (${element_id})`);
       return;
     }
     const segmentRaw = Number(segment_id);