@hanzo/event 0.3.24 → 0.3.25

package/hz.js

@@ -55,7 +55,7 @@
   }
 
   var LIB = 'hz.js'
-  var VERSION = '0.3.24'
+  var VERSION = '0.3.25'
   var host = (s.getAttribute('data-host') || 'https://api.hanzo.ai').replace(/\/+$/, '')
   var product = s.getAttribute('data-product') || location.hostname
   var capture = s.getAttribute('data-capture') !== '0'
@@ -471,11 +471,25 @@ function hzAnonId() {
       })
     }).observe({ type: 'layout-shift', buffered: true })
   } catch (e) {}
-  addEventListener('visibilitychange', function () {
-    if (document.visibilityState !== 'hidden') return
-    if (vitals.lcp != null || vitals.cls != null) send('event', '$vitals', vitals)
+  // A document can be taken away on either signal, and neither one alone covers
+  // every browser: visibilitychange is what fires when a tab is backgrounded or
+  // discarded, pagehide is what fires on the navigation path where it does not.
+  // core.ts listens for both; this listens for both. flush() returns on an empty
+  // queue, so whichever arrives second finds nothing left to send.
+  var vitalsSent = false
+  function leaving() {
+    // The web vitals are one measurement of one page view. Hiding a tab twice
+    // does not make two of them.
+    if (!vitalsSent && (vitals.lcp != null || vitals.cls != null)) {
+      vitalsSent = true
+      send('event', '$vitals', vitals)
+    }
     flush()
+  }
+  addEventListener('visibilitychange', function () {
+    if (document.visibilityState === 'hidden') leaving()
   })
+  addEventListener('pagehide', leaving)
 
   // ── public API (manual funnel/identify) + GA/Meta fan-out ─────────────────
   function assign(a, b) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.24",
-  "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.",
+  "version": "0.3.25",
+  "description": "Hanzo Event \u2014 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 \u2014 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/",
     "access": "public",
@@ -37,6 +37,13 @@
     "funnel",
     "hanzo"
   ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
   "exports": {
     ".": {
       "import": {
@@ -77,12 +84,5 @@
   },
   "dependencies": {
     "@hanzo/events": "^0.2.1"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}

package/src/hz.test.ts

@@ -75,8 +75,11 @@ function runSnippet(opts: StubOptions = {}): {
   api: Api | undefined
   local: Map<string, string>
   jar: Map<string, string>
+  fire: (type: string) => void
+  hide: () => void
 } {
   const posts: Post[] = []
+  const listeners = new Map<string, (() => void)[]>()
   const local = new Map<string, string>(Object.entries(opts.storage ?? {}))
   const jar = opts.jar ?? new Map<string, string>()
   const store = (m: Map<string, string>) => ({
@@ -145,7 +148,13 @@ function runSnippet(opts: StubOptions = {}): {
   define('localStorage', store(local))
   define('sessionStorage', store(new Map()))
   define('history', { pushState: () => {}, replaceState: () => {} })
-  define('addEventListener', () => {})
+  // Listeners are kept, not discarded: the unload flush IS a listener, so a stub
+  // that drops them leaves the only path the drop-off signal travels unexecuted.
+  define('addEventListener', (type: string, fn: () => void) => {
+    const seen = listeners.get(type)
+    if (seen) seen.push(fn)
+    else listeners.set(type, [fn])
+  })
   define('PerformanceObserver', undefined)
   define('hzDNT', undefined)
   define('doNotTrack', undefined)
@@ -166,7 +175,16 @@ function runSnippet(opts: StubOptions = {}): {
   define('window', g)
 
   new Function(SRC)()
-  return { posts, api: (g.window as { hanzo?: Api }).hanzo, local, jar }
+  /** Raise an event the page would raise, so its listeners actually run. */
+  const fire = (type: string) => {
+    for (const fn of listeners.get(type) ?? []) fn()
+  }
+  /** Hide the document, as a browser does before it takes one away. */
+  const hide = () => {
+    ;(g.document as { visibilityState: string }).visibilityState = 'hidden'
+    fire('visibilitychange')
+  }
+  return { posts, api: (g.window as { hanzo?: Api }).hanzo, local, jar, fire, hide }
 }
 
 /** Every event across every transmission, in order. */
@@ -178,6 +196,29 @@ describe('hz.js', () => {
     run = runSnippet()
   })
 
+  // A visitor who leaves mid-funnel is the drop-off signal, and hz.js only gets
+  // to report it from a teardown listener. Neither signal fires in every browser
+  // on every path, so the tag listens for both.
+  it('flushes what is queued when the tab is hidden', () => {
+    run.api!.track('plan_clicked')
+    run.hide()
+    expect(sentOf(run).map((e) => e.event)).toContain('plan_clicked')
+  })
+
+  it('flushes what is queued on pagehide, which visibilitychange need not precede', () => {
+    run.api!.track('checkout_started')
+    run.fire('pagehide')
+    expect(sentOf(run).map((e) => e.event)).toContain('checkout_started')
+  })
+
+  it('sends nothing a second time when both teardown signals arrive', () => {
+    run.api!.track('plan_clicked')
+    run.hide()
+    run.fire('pagehide')
+    const clicks = sentOf(run).filter((e) => e.event === 'plan_clicked')
+    expect(clicks).toHaveLength(1)
+  })
+
   it('mints session ids the plane admits', () => {
     run.api!.track('checkout_started')
     run.api!.flush()

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/transport.test.ts

@@ -22,6 +22,9 @@ interface Fetched {
   url: string
   headers: Record<string, string>
   body: string
+  /** Whether the request may outlive the document that made it. A fetch without
+   *  it is cancelled on teardown, which is the whole failure this file guards. */
+  keepalive?: boolean
 }
 
 // The three CORS-safelisted request content types. A POST whose body carries one
@@ -70,10 +73,16 @@ function unloadFlush(queued: boolean): { beacons: Beaconed[]; fetches: Fetched[]
       }
     },
   )
-  define('fetch', (url: string, init: { headers: Record<string, string>; body: string }) => {
-    fetches.push({ url, headers: init.headers, body: init.body })
-    return Promise.resolve({ ok: true, status: 200 })
-  })
+  define(
+    'fetch',
+    (
+      url: string,
+      init: { headers: Record<string, string>; body: string; keepalive?: boolean },
+    ) => {
+      fetches.push({ url, headers: init.headers, body: init.body, keepalive: init.keepalive })
+      return Promise.resolve({ ok: true, status: 200 })
+    },
+  )
 
   try {
     // No `transport`, so the client builds the real DefaultTransport. The key is
@@ -121,5 +130,10 @@ describe('the unload beacon', () => {
     const batch = (JSON.parse(fetches[0].body) as { batch: { event?: string }[] }).batch
     expect(batch.map((e) => e.event)).toContain('checkout_started')
     expect(fetches[0].headers.Authorization).toBe('Bearer pk-abc123')
+
+    // The fallback is only a fallback if it survives the teardown that the beacon
+    // was there for. Without this the batch is cancelled mid-flight and the
+    // refusal was merely traded for a quieter loss.
+    expect(fetches[0].keepalive).toBe(true)
   })
 })

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.24'
+export const VERSION = '0.3.25'

package/LICENSE.md

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 hanzo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.