@hanzo/event 0.3.31 → 0.3.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "description": "Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -17,7 +17,6 @@
   "files": [
     "dist",
     "src",
-    "hz.js",
     "README.md",
     "TAXONOMY.md"
   ],

package/src/anon.d.ts

@@ -1,5 +1,5 @@
 // Types for anon.js, which is hand-written ES5 rather than TypeScript because
-// hz.js and the door's hosted tag inline it VERBATIM and neither has a compiler.
+// The door's hosted tag inlines it VERBATIM and has no compiler.
 // The declarations are here so the bundled client still imports it typed.
 
 /** Mints a time-ordered UUIDv7 (RFC 9562 §5.7) for `now` in epoch milliseconds. */

package/src/anon.js

@@ -1,34 +1,34 @@
-/*! anon.js — THE anonymous-identity chain. ONE implementation, three distributions.
+/*! anon.js — THE anonymous-identity chain. ONE implementation, two distributions.
  *
  * One browser is ONE person on every Hanzo surface, whichever client a page
- * happens to have loaded. There were three implementations writing TWO keys —
- * `hz_anon_id` (the npm client, the hosted tag) and `hz_id` (hz.js) — so the same
- * visitor was several people depending on which snippet the surface shipped.
+ * happens to have loaded. There were once three implementations writing TWO keys —
+ * `hz_anon_id` and `hz_id` — so the same visitor was several people depending on
+ * which snippet the surface shipped.
  *
- * The three call sites:
+ * The two call sites:
  *   1. src/storage.ts        — the bundled npm client; IMPORTS this file.
- *   2. hz.js                 — the no-build script tag; INLINES the marked region.
- *   3. hanzoai/cloud apps/analytics/tag.js — the tag the door hosts at
+ *   2. hanzoai/cloud apps/analytics/tag.js — the tag the door hosts at
  *      /v1/event.js; vendors this file and its tag.go serves the marked region
  *      with the tag as one asset, so the door holds no second copy either.
  *
- * (2) and (3) have no bundler and cannot import anything, which is why the chain
- * lives in a file that is plain ES5 rather than in a .ts: the region between the
- * BEGIN and END markers is COPIED VERBATIM, and src/anon.test.ts fails if hz.js's
- * copy is so much as a byte different. Keep the region ES5, dependency-free,
- * `hz`-prefixed (it is spliced into other people's scopes) and unformatted — a
- * reformat of one copy is a diff against the other.
+ * (2) has no bundler and cannot import anything, which is why the chain lives in a
+ * file that is plain ES5 rather than in a .ts: the region between the BEGIN and END
+ * markers is COPIED VERBATIM. Keep it ES5, dependency-free, `hz`-prefixed (it is
+ * spliced into other people's scopes) and unformatted — a reformat here is a diff
+ * against the vendored copy. After editing, resync the door:
+ *
+ *   curl -fsSL https://unpkg.com/@hanzo/event/src/anon.js -o apps/analytics/anon.js
  */
 
-/* ── BEGIN hz anon chain — copied VERBATIM into hz.js and hanzoai/cloud ────── */
+/* ── BEGIN hz anon chain — copied VERBATIM into hanzoai/cloud ──────────────── */
 
 /** The ONE anonymous-id key, on every surface and in every distribution. */
 var HZ_ANON_KEY = 'hz_anon_id'
 
-/** hz.js used to write `hz_id` — a SECOND identity space, so the one-paste tag
- *  and the npm client were two different people on one page. It is READ and never
- *  written: an id already in the wild is ADOPTED into the shared identity, because
- *  minting over one detaches a returning visitor from their own history. */
+/** `hz_id` is a SECOND identity space a no-build tag once wrote, so one page could
+ *  hold two people. It is READ and never written: an id already in the wild is
+ *  ADOPTED into the shared identity, because minting over one detaches a returning
+ *  visitor from their own history. */
 var HZ_ANON_LEGACY_KEY = 'hz_id'
 
 /** The registrable domain the cookie is scoped to, so docs, cloud, console,

package/src/anon.test.ts

@@ -1,15 +1,13 @@
-// The anonymous-identity chain is ONE implementation with three call sites, and
-// two of them cannot import it: hz.js and the tag hanzoai/cloud hosts at
-// /v1/event.js have no bundler, so they carry the marked region of anon.js
-// VERBATIM. That is the drift risk this file exists to remove — three snippets
-// that agree the day they are written and disagree a quarter later, which is
-// exactly how the same browser came to hold two different anonymous ids under two
-// different key names.
+// The anonymous-identity chain is ONE implementation with two call sites, and one
+// of them cannot import it: the tag hanzoai/cloud hosts at /v1/event.js has no
+// bundler, so it carries the marked region of anon.js VERBATIM. That is the drift
+// risk this file exists to remove — snippets that agree the day they are written
+// and disagree a quarter later, which is exactly how the same browser came to hold
+// two different anonymous ids under two different key names.
 //
-// The behavioural contract is proven where each distribution runs it:
-// storage.test.ts (the npm client) and hz.test.ts (the script tag). This file
-// proves the copies are the SAME TEXT, which is the only thing that keeps those
-// two suites testing one implementation instead of two.
+// The behavioural contract is proven where the chain runs: storage.test.ts. This
+// file proves the region is SPLICEABLE and that it ships, which is what lets the
+// door vendor it instead of writing a second one.
 
 import { describe, expect, it } from 'vitest'
 import { readFileSync } from 'node:fs'
@@ -32,37 +30,19 @@ function span(src: string, what: string): [number, number] {
 /** The shared region, markers included. */
 const region = (src: string, what: string): string => src.slice(...span(src, what))
 
-/** Everything that is NOT the shared region. */
-function outside(src: string, what: string): string {
-  const [b, e] = span(src, what)
-  return src.slice(0, b) + src.slice(e)
-}
-
 const ANON = read('./anon.js')
-const HZ = read('../hz.js')
 
 describe('the shared anon chain', () => {
-  it('is in hz.js as the same text, byte for byte', () => {
-    // Not "equivalent" — IDENTICAL. Anything weaker (normalising whitespace,
-    // comparing behaviour) permits the copies to say different things about which
-    // key they read, which is the bug. To change the chain, edit src/anon.js and
-    // re-splice; never patch a copy.
-    expect(region(HZ, 'hz.js')).toBe(region(ANON, 'anon.js'))
-  })
-
-  it('names one key, and hz.js holds no identity code of its own', () => {
-    // hz.js used to mint into hz_id — a second identity space, so the one-paste
-    // tag and the npm client were two people on one page. Neither key may be
-    // NAMED outside the shared region: a snippet that spells a key is a snippet
-    // that has an opinion about identity, and there is one opinion now.
-    const rest = outside(HZ, 'hz.js')
-    expect(rest).not.toContain("'hz_anon_id'")
-    expect(rest).not.toContain("'hz_id'")
+  it('is marked, so the door can splice exactly it', () => {
+    // cloud's tag.go slices between these markers and PANICS if it cannot find
+    // them, so losing a marker ships a tag whose every event carries an undefined
+    // identity. To change the chain, edit this file; never patch a copy.
+    expect(region(ANON, 'anon.js')).toContain(BEGIN)
   })
 
   it('is inlineable: the region imports nothing and declares no ES6', () => {
-    // It is spliced into two files that have no bundler and into pages the client
-    // does not control, so it must be ES5, self-contained and hz-prefixed.
+    // It is spliced into a file that has no bundler and into pages the client does
+    // not control, so it must be ES5, self-contained and hz-prefixed.
     const r = region(ANON, 'anon.js')
     expect(r).not.toMatch(/\b(?:import|export|const|let|class|=>)\b|=>/)
     for (const [, name] of r.matchAll(/^(?:function|var) ([A-Za-z_$][\w$]*)/gm)) {
@@ -72,9 +52,8 @@ describe('the shared anon chain', () => {
 
   it('ships in the published package, for the door to vendor', () => {
     // hanzoai/cloud vendors this file whole and its tag.go serves the region with
-    // the tag as one asset, so the third call site holds no second copy either.
+    // the tag as one asset, so the second call site holds no copy of its own.
     const pkg = JSON.parse(read('../package.json')) as { files: string[] }
     expect(pkg.files).toContain('src')
-    expect(pkg.files).toContain('hz.js')
   })
 })

package/src/stack.ts

@@ -0,0 +1,144 @@
+// Pure error parsing: coerce an unknown throwable into {name, message, stack},
+// and parse a browser stack string into structured frames. No I/O, no globals —
+// core.ts wires these to identity and transport.
+//
+// These frames ride the error Event to POST /v1/event so the warehouse stores
+// WHERE a crash happened, not just that one did. Nothing here talks to Sentry:
+// the client has one door and one credential. The frame shape is deliberately the
+// conventional one (function/filename/abs_path/lineno/colno/in_app) because it is
+// what every stack tool already speaks — including a future grouper built over
+// the warehouse.
+
+/** Max frames kept — well under the server's cap, plenty to identify a crash. */
+const MAX_FRAMES = 50
+/** Max stack lines examined, and max length of a line worth examining. Guards the
+ *  frame regexes against a hostile `stack` string (see framesFromStack). */
+const MAX_LINES = 500
+const MAX_LINE_LEN = 2048
+
+/** One parsed stack frame. */
+export interface Frame {
+  filename?: string
+  function?: string
+  abs_path?: string
+  lineno?: number
+  colno?: number
+  /** The app's own code, as opposed to vendor/runtime — the useful default filter. */
+  in_app?: boolean
+}
+
+const V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+)|([^)]+))\)?\s*$/
+const MOZ_FRAME = /^\s*(?:(.*?)@)?(.+?):(\d+):(\d+)\s*$/
+
+/** inApp marks a frame as the app's own code (vs vendor/runtime). */
+function inApp(file: string): boolean {
+  if (!file) return false
+  return !(
+    file.includes('node_modules') ||
+    file.startsWith('webpack-internal') ||
+    file.startsWith('webpack://') ||
+    file.startsWith('chrome-extension://') ||
+    file.startsWith('moz-extension://')
+  )
+}
+
+/**
+ * framesFromStack parses a browser Error.stack into frames, OLDEST-FIRST (caller
+ * → callee, so the crash site is LAST). Handles both V8 ("at fn (file:li:co)")
+ * and Firefox/Safari ("fn@file:li:co"). Unparseable lines are skipped.
+ */
+export function framesFromStack(stack: string | undefined): Frame[] {
+  if (!stack) return []
+  // Both frame regexes use lazy nested quantifiers, which backtrack badly on a
+  // long line that never matches. A stack is attacker-influenced (a thrown value
+  // can carry any `stack` string), so bound the work: skip absurd lines and stop
+  // after MAX_LINES. Only the innermost MAX_FRAMES are kept anyway.
+  const lines = stack.split('\n', MAX_LINES)
+  const frames: Frame[] = []
+  for (const raw of lines) {
+    if (raw.length > MAX_LINE_LEN) continue
+    const line = raw.trimEnd()
+    if (!line) continue
+    // Header lines like "TypeError: x is not a function" match neither frame
+    // regex (no "at " prefix, no trailing :line:col) and are skipped naturally.
+    let fn: string | undefined
+    let file = ''
+    let lineno = 0
+    let colno = 0
+    const v = V8_FRAME.exec(line)
+    if (v) {
+      fn = v[1]
+      if (v[2]) {
+        file = v[2]
+        lineno = Number(v[3]) || 0
+        colno = Number(v[4]) || 0
+      } else {
+        file = (v[5] || '').trim()
+      }
+    } else {
+      const f = MOZ_FRAME.exec(line)
+      if (!f) continue
+      fn = f[1]
+      file = f[2]
+      lineno = Number(f[3]) || 0
+      colno = Number(f[4]) || 0
+    }
+    if (!file && !fn) continue
+    frames.push({
+      function: fn || '<anonymous>',
+      filename: file,
+      abs_path: file,
+      lineno,
+      colno,
+      in_app: inApp(file),
+    })
+  }
+  // Reverse to oldest-first and cap to the innermost MAX_FRAMES.
+  frames.reverse()
+  if (frames.length > MAX_FRAMES) return frames.slice(frames.length - MAX_FRAMES)
+  return frames
+}
+
+/** read pulls a property off a value that may be hostile — `name`, `message` and
+ *  `stack` are ordinary getters that a thrown object is free to define as
+ *  throwing. The thrown value is the least trustworthy input this library
+ *  handles; losing the whole report to one of them is not acceptable. */
+function read(o: unknown, k: string): unknown {
+  try {
+    return (o as Record<string, unknown>)[k]
+  } catch {
+    return undefined
+  }
+}
+
+/** str coerces to a string without letting a throwing toString/Symbol.toPrimitive
+ *  escape. */
+function str(v: unknown): string {
+  try {
+    return String(v)
+  } catch {
+    return '[unstringifiable]'
+  }
+}
+
+/** normalizeError coerces an unknown throwable into {name, message, stack}.
+ *  TOTAL: it returns a usable record for ANY input, including an object
+ *  engineered to throw on property access. */
+export function normalizeError(err: unknown): { name: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    const name = read(err, 'name')
+    const message = read(err, 'message')
+    const stack = read(err, 'stack')
+    return {
+      name: typeof name === 'string' && name ? name : 'Error',
+      message: typeof message === 'string' && message ? message : str(err),
+      stack: typeof stack === 'string' ? stack : undefined,
+    }
+  }
+  if (typeof err === 'string') return { name: 'Error', message: err }
+  try {
+    return { name: 'Error', message: JSON.stringify(err) ?? str(err) }
+  } catch {
+    return { name: 'Error', message: str(err) }
+  }
+}

package/src/storage.test.ts

@@ -113,8 +113,8 @@ describe('anonId', () => {
     }
   })
 
-  it("adopts hz.js's `hz_id` when there is no canonical id to find", async () => {
-    // The no-build tag minted into a key of its own, so a browser that met hz.js
+  it("adopts a legacy `hz_id` when there is no canonical id to find", async () => {
+    // A no-build tag once minted into a key of its own, so a browser that met it
     // first already carries an identity — under a different name. Minting here
     // would make that visitor a stranger the moment they reach a bundled surface,
     // which is precisely the split this migration closes.

package/src/storage.ts

@@ -30,7 +30,7 @@ function ls(): Storage | undefined {
 
 /**
  * Stable anonymous id, shared by every *.hanzo.ai surface AND by every Hanzo
- * client on the page — the npm client, hz.js and the hosted tag all run the one
+ * client on the page — the npm client and the hosted tag both run the one
  * chain in ./anon.js, so which snippet a surface loaded no longer decides who the
  * visitor is.
  *

package/src/uid.ts

@@ -2,7 +2,7 @@
 //
 // The implementation is `hzUuidv7` in ./anon.js and this file only re-exports it.
 // It lives there because the anonymous-id chain has to mint too, and that chain is
-// inlined verbatim by two distributions that have no bundler (hz.js, and the tag
+// inlined verbatim by the distribution that has no bundler (the tag
 // the door hosts) — a minter here as well would be a second implementation, and
 // the version nibble it produces is exactly the thing that must never diverge.
 //

package/src/version.ts

@@ -1,4 +1,4 @@
 // The library version, stamped on every event (`libraryVersion`) and on the
 // Sentry `sdk` block. It lives alone so `sentry.ts` can read it without importing
 // `core.ts` — core imports sentry, so the reverse would be an import cycle.
-export const VERSION = '0.3.31'
+export const VERSION = '0.3.33'