@hanzo/event 0.3.18 → 0.3.20

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.18",
-  "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.20",
+  "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": {
@@ -74,12 +81,5 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}

package/src/core.test.ts

@@ -483,45 +483,78 @@ describe('Analytics capture', () => {
 })
 
 describe('Event error capture', () => {
-  it('captureError emits a type:error event carrying a TOP-LEVEL exception, flushed at once', () => {
+  it('emits under the RESERVED $exception name, never under the message', () => {
     const a = mk()
     a.captureError(new TypeError('boom'))
     // captureError flushes promptly — no explicit flush() needed.
     expect(tx.sent).toHaveLength(1)
     const e = tx.all[0]
-    // type:'error' is the field Cloud folds to event_type='error' for the warehouse.
-    expect(e.type).toBe('error')
-    expect(e.event).toBe('boom')
-    // The exception rides the TOP-LEVEL `error` field (what cloud foldException
-    // reads), NOT properties — a properties-only exception would not be folded.
+    // THE NAME. Until 0.3.20 this was `ex.message`, which made every distinct
+    // error string a permanent entry in the event taxonomy and left Error
+    // Tracking — which reads this exact name — at zero rows.
+    expect(e.event).toBe('$exception')
+    // THE TYPE. `type` alone picks the storage plane: 'error' routes to the error
+    // plane, which the product-event projection does not read, so an exception
+    // filed there cannot reach Error Tracking. The full error record still goes to
+    // the error plane as a Sentry envelope.
+    expect(e.type).toBe('event')
+    // The exception STILL rides the TOP-LEVEL `error` field, which is what cloud's
+    // foldException reads to stamp properties.$exception (scrubbing on the way).
     expect(e.error?.type).toBe('TypeError')
     expect(e.error?.message).toBe('boom')
     expect(e.error?.stack).toBeTruthy()
     expect(e.error?.handled).toBe(true) // a caught, manually-reported error
-    expect((e.properties ?? {})).not.toHaveProperty('$exception')
+    // The client does not stamp $exception itself — the server fold owns that key.
+    expect(e.properties ?? {}).not.toHaveProperty('$exception')
+  })
+
+  it('carries the $exception_* bag Error Tracking reads', () => {
+    const a = mk()
+    a.captureError(new TypeError('boom'))
+    const p = tx.all[0].properties as Record<string, unknown>
+    expect(Array.isArray(p.$exception_list)).toBe(true)
+    // Without a fingerprint the issue query drops the event outright.
+    expect(p.$exception_fingerprint).toMatch(/^[0-9a-f]{32}$/)
+    expect(p.$exception_type).toBe('TypeError')
+    expect(p.$exception_handled).toBe(true)
   })
 
   it('normalizes a thrown string into an exception', () => {
     const a = mk()
     a.captureError('plain failure')
     const e = tx.all[0]
-    expect(e.type).toBe('error')
+    expect(e.event).toBe('$exception')
+    expect(e.type).toBe('event')
     expect(e.error?.message).toBe('plain failure')
   })
 
-  it('marks handled=false for unhandled/global errors and carries properties', () => {
+  it('marks handled=false for unhandled/global errors and carries caller properties', () => {
     const a = mk()
     a.captureError(new Error('unhandled'), { handled: false, properties: { source: 'onerror' } })
     const e = tx.all[0]
     expect(e.error?.handled).toBe(false)
-    expect(e.properties).toEqual({ source: 'onerror' })
+    const p = e.properties as Record<string, unknown>
+    // The caller's own properties survive alongside the exception bag.
+    expect(p.source).toBe('onerror')
+    expect(p.$exception_handled).toBe(false)
+  })
+
+  it("a caller property cannot overwrite the exception bag it shares a name with", () => {
+    const a = mk()
+    a.captureError(new Error('x'), {
+      handled: false,
+      properties: { $exception_fingerprint: 'forged' },
+    })
+    const p = tx.all[0].properties as Record<string, unknown>
+    expect(p.$exception_fingerprint).not.toBe('forged')
   })
 
   it('captureException is an alias of captureError', () => {
     const a = mk()
     a.captureException(new Error('via alias'))
     const e = tx.all[0]
-    expect(e.type).toBe('error')
+    expect(e.event).toBe('$exception')
+    expect(e.type).toBe('event')
     expect(e.error?.message).toBe('via alias')
   })
 
@@ -563,7 +596,7 @@ describe('error plane', () => {
     expect(tx.envelopes).toHaveLength(0)
     // fail-safe: the event stream still carries the error, analytics untouched.
     expect(tx.streams).toHaveLength(1)
-    expect(tx.all[0].type).toBe('error')
+    expect(tx.all[0].event).toBe('$exception')
   })
 
   it('with a DSN, an error POSTs a Sentry envelope to the DERIVED ingest URL', () => {

package/src/core.ts

@@ -44,7 +44,8 @@ import {
   deriveChannel,
 } from './attribution'
 import { dsnForProduct, defaultPublishableKey } from './dsn'
-import { PAGEVIEW } from './events'
+import { EXCEPTION, PAGEVIEW } from './events'
+import { exceptionProperties } from './exception'
 import { scrubText } from './scrub'
 import {
   buildEnvelope,
@@ -389,9 +390,35 @@ export class Analytics {
       }
 
       try {
+        const handled = context?.handled ?? true
         const ex = normalizeError(err)
-        ex.handled = context?.handled ?? true
-        this.enqueue('error', ex.message, { error: ex, properties: context?.properties })
+        ex.handled = handled
+        // NAME: the reserved '$exception', never the message. The message was the
+        // name until 0.3.20, which put every distinct error string — one per failed
+        // chunk id, per ResizeObserver notification — permanently into the event
+        // taxonomy, and left Error Tracking (which reads this exact name) at zero.
+        //
+        // TYPE 'event', not 'error'. `type` alone picks the storage plane: 'error'
+        // routes to the error plane, which the product-event projection does not
+        // read, so an exception filed there is invisible to Error Tracking however
+        // well-formed it is. The full error record still reaches the error plane as
+        // a Sentry envelope above — this row is the product-analytics breadcrumb,
+        // which is what keeps a crash correlated with the session's pageviews.
+        //
+        // `error` is still carried: the server folds it into properties.$exception
+        // (scrubbing message and stack on the way), which is the shape existing
+        // readers bind to.
+        this.enqueue('event', EXCEPTION, {
+          error: ex,
+          properties: {
+            ...context?.properties,
+            ...exceptionProperties(err, {
+              handled,
+              id: uuidv7(),
+              level: context?.level,
+            }),
+          },
+        })
         this.flush()
       } catch {
         /* nor the reverse */

package/src/dsn.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, afterEach } from 'vitest'
 
 import { createAnalytics } from './core'
-import { PRODUCT_DSN, dsnForProduct } from './dsn'
+import { PRODUCT_PROJECT, dsnForProduct, HANZO_PUBLISHABLE_KEY } from './dsn'
 import { parseDsn } from './sentry'
 
 const ENV = 'NEXT_PUBLIC_HANZO_EVENT_DSN'
@@ -13,10 +13,13 @@ afterEach(() => {
 })
 
 describe('the product registry', () => {
-  it('resolves a registered product to its DSN', () => {
-    expect(dsnForProduct('console')).toBe(PRODUCT_DSN.console)
-    expect(dsnForProduct('app')).toBe(PRODUCT_DSN.app)
-    expect(dsnForProduct('site')).toBe(PRODUCT_DSN.site)
+  it('builds a product DSN — the org publishable key at its project envelope', () => {
+    expect(dsnForProduct('console')).toBe(
+      `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.console}`
+    )
+    expect(dsnForProduct('site')).toBe(
+      `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.site}`
+    )
   })
 
   it('returns undefined for an unregistered or missing product, rather than guessing', () => {
@@ -25,12 +28,12 @@ describe('the product registry', () => {
     expect(dsnForProduct('')).toBeUndefined()
   })
 
-  it('registers only DSNs that actually parse — a typo here would silently disable a surface', () => {
-    for (const [product, dsn] of Object.entries(PRODUCT_DSN)) {
-      const parsed = parseDsn(dsn)
+  it('every product DSN parses to the org key + its own project id', () => {
+    for (const [product, projectId] of Object.entries(PRODUCT_PROJECT)) {
+      const parsed = parseDsn(dsnForProduct(product))
       expect(parsed, `${product} DSN must parse`).not.toBeNull()
-      expect(parsed!.projectId, `${product} needs a project id`).toBeTruthy()
-      expect(parsed!.publicKey, `${product} needs a public key`).toBeTruthy()
+      expect(parsed!.projectId, `${product} project id`).toBe(projectId)
+      expect(parsed!.publicKey, `${product} carries the org key`).toBe(HANZO_PUBLISHABLE_KEY)
     }
   })
 })
@@ -39,7 +42,7 @@ describe('DSN precedence — most specific source wins', () => {
   it('lights up the error plane from `product` alone, with no dsn and no env', () => {
     const a = createAnalytics({ product: 'console', enabled: false })
     expect(a.errorPlaneEnabled).toBe(true)
-    expect(a.errorIngestUrl).toContain(parseDsn(PRODUCT_DSN.console)!.projectId)
+    expect(a.errorIngestUrl).toContain(PRODUCT_PROJECT.console)
   })
 
   it('prefers an explicit dsn over both the env and the registry', () => {

package/src/dsn.ts

@@ -24,24 +24,29 @@
  * product name the app passes to `createAnalytics`.
  */
 
-/** PRODUCT_DSN maps a `product` to the DSN its errors are submitted to. */
-export const PRODUCT_DSN: Readonly<Record<string, string>> = Object.freeze({
-  // hanzo-console — console.hanzo.ai (also served embedded by the cloud binary)
-  console:
-    'https://1:0c8054dbde157f4f420c56b58660052b2ad782293c4de1d606ef8fbc46a0bf34@api.hanzo.ai/v1/sentry/019fa40b-94ae-7f1d-8f7b-e92f123fad42',
-  // hanzo-app — hanzo.app
-  app: 'https://1:b3e1173125568c80f91ef4b1fabbbd2d7e22341de02b33ce7e22ef4fc16a196e@api.hanzo.ai/v1/sentry/019f9b1e-57eb-7171-9d92-72c0b85e4b4b',
-  // hanzo-ai — hanzo.ai (the marketing site; `site` is the product name it declares)
-  site: 'https://1:d9cbfb844958bd7ef2a455600f00fbf237fbd71b75c1504f137773096d6aa53f@api.hanzo.ai/v1/sentry/019f9b1e-5785-7359-ad0b-f75db8e58c99',
+/** PRODUCT_PROJECT maps a `product` to its Sentry project id. The DSN's KEY is no
+ *  longer a per-project secret — it is the ONE org publishable key (below), so a
+ *  surface's errors ride the SAME key its events do. The id only names WHICH
+ *  project the errors group under, and cloud auto-provisions that project on first
+ *  keyed ingest, so a new id needs nothing minted. `site` lives in the `hanzo-ai`
+ *  project — an explicit map, because the projects predate this and do not derive
+ *  cleanly from the product name. */
+export const PRODUCT_PROJECT: Readonly<Record<string, string>> = Object.freeze({
+  console: '019fa40b-94ae-7f1d-8f7b-e92f123fad42', // console.hanzo.ai
+  app: '019f9b1e-57eb-7171-9d92-72c0b85e4b4b', // hanzo.app
+  site: '019f9b1e-5785-7359-ad0b-f75db8e58c99', // hanzo.ai (marketing; product `site`)
 })
 
-/** dsnForProduct resolves the registered DSN for a product, or undefined when the
- *  product has no project yet — which leaves the error plane inert rather than
- *  guessing a destination and silently posting a surface's errors into the wrong
- *  project. */
+/** dsnForProduct builds the product's Sentry DSN — the ONE org publishable key at
+ *  its project's envelope endpoint — or undefined when the product has no project
+ *  yet, which leaves the error plane inert rather than posting into the wrong one.
+ *  Same key as the event stream: cloud resolves it to the org and attributes the
+ *  errors there. */
 export function dsnForProduct(product: string | undefined): string | undefined {
   if (!product) return undefined
-  return PRODUCT_DSN[product]
+  const projectId = PRODUCT_PROJECT[product]
+  if (!projectId) return undefined
+  return `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${projectId}`
 }
 
 /** The hanzo org's publishable ingest key. Like the DSNs above it is PUBLIC by

package/src/events.ts

@@ -69,3 +69,8 @@ export type EventName = (typeof EVENTS)[keyof typeof EVENTS]
 
 /** The reserved event name a pageview is stored under (server + read lens). */
 export const PAGEVIEW = '$pageview'
+
+/** The reserved name every captured exception is emitted under. Error Tracking
+ *  reads exactly this name; an exception emitted under its own message instead
+ *  makes every distinct message a permanent entry in the event taxonomy. */
+export const EXCEPTION = '$exception'

package/src/exception.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest'
+import { digest, exceptionEntry, exceptionProperties, fingerprint } from './exception'
+
+/** A throwable with a realistic V8 stack, innermost call first (as V8 emits). */
+function boom(msg = 'Cannot read properties of undefined'): Error {
+  const e = new TypeError(msg)
+  e.stack = [
+    `TypeError: ${msg}`,
+    '    at loadIssue (https://hanzo.ai/_next/static/chunks/app.js:42:9)',
+    '    at render (https://hanzo.ai/_next/static/chunks/app.js:17:3)',
+    '    at vendorLoad (https://hanzo.ai/node_modules/react-dom/index.js:12:3)',
+  ].join('\n')
+  return e
+}
+
+describe('frame ordering — the product reads frames bottom-up', () => {
+  it('puts the entry point first and the throw site last', () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    const frames = e.stacktrace!.frames
+    // V8 emits innermost-first; the product wants the reverse.
+    expect(frames[0].mangled_name).toBe('vendorLoad')
+    expect(frames[frames.length - 1].mangled_name).toBe('loadIssue')
+  })
+
+  it('indexes the throw site at -1, which is where the issue list reads it', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_functions.at(-1)).toBe('loadIssue')
+    expect(p.$exception_sources.at(-1)).toBe('https://hanzo.ai/_next/static/chunks/app.js')
+  })
+})
+
+describe('stacktrace.type — the renderer draws nothing on any other value', () => {
+  it("is the literal 'resolved'", () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    expect(e.stacktrace!.type).toBe('resolved')
+  })
+
+  it('is omitted entirely when there is no stack, rather than sent empty', () => {
+    const e = exceptionEntry('Script error.', { handled: false, id: 'x' })
+    expect(e.stacktrace).toBeUndefined()
+    expect(e.type).toBe('Error')
+    expect(e.value).toBe('Script error.')
+  })
+})
+
+describe('in_app — frames without it are hidden by default', () => {
+  it('marks first-party code in_app and vendor code not', () => {
+    const frames = exceptionEntry(boom(), { handled: false, id: 'x' }).stacktrace!.frames
+    const byName = Object.fromEntries(frames.map((f) => [f.mangled_name, f.in_app]))
+    expect(byName.loadIssue).toBe(true)
+    expect(byName.render).toBe(true)
+    expect(byName.vendorLoad).toBe(false)
+  })
+
+  it('keeps only in_app frames out of the fingerprint', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    // vendorLoad is the only non-in_app frame; it must not move the group key.
+    const e = exceptionEntry(boom(), { handled: false, id: 'y' })
+    e.stacktrace!.frames = e.stacktrace!.frames.filter((f) => f.in_app)
+    expect(fingerprint(e)).toBe(p.$exception_fingerprint)
+  })
+})
+
+describe('fingerprint — the issue grouping key', () => {
+  it('is present, since the issue query drops events without one', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_fingerprint).toMatch(/^[0-9a-f]{32}$/)
+  })
+
+  it('groups the SAME bug whose message varies — the whole point', () => {
+    // The real-world case: one failed-chunk bug produced a distinct event name per
+    // chunk id. These must be one issue.
+    const a = new Error('Loading chunk 3324 failed.')
+    const b = new Error('Loading chunk 998 failed.')
+    const stack = '    at load (https://hanzo.ai/app.js:1:1)'
+    a.stack = `Error: x\n${stack}`
+    b.stack = `Error: y\n${stack}`
+    const fa = exceptionProperties(a, { handled: false, id: '1' }).$exception_fingerprint
+    const fb = exceptionProperties(b, { handled: false, id: '2' }).$exception_fingerprint
+    expect(fa).toBe(fb)
+  })
+
+  it('separates genuinely different bugs', () => {
+    const other = new RangeError('nope')
+    other.stack = 'RangeError: nope\n    at somewhereElse (https://hanzo.ai/other.js:5:5)'
+    const fa = exceptionProperties(boom(), { handled: false, id: '1' }).$exception_fingerprint
+    const fb = exceptionProperties(other, { handled: false, id: '2' }).$exception_fingerprint
+    expect(fa).not.toBe(fb)
+  })
+
+  it('still groups stackless errors by type instead of scattering them', () => {
+    const f1 = exceptionProperties('Script error.', { handled: false, id: '1' })
+    const f2 = exceptionProperties('Script error.', { handled: false, id: '2' })
+    expect(f1.$exception_fingerprint).toBe(f2.$exception_fingerprint)
+  })
+})
+
+describe('raw_id — frame identity', () => {
+  it('carries the "<hash>/<part>" shape the product expects', () => {
+    const frames = exceptionEntry(boom(), { handled: false, id: 'x' }).stacktrace!.frames
+    for (const f of frames) expect(f.raw_id).toMatch(/^[0-9a-f]{32}\/0$/)
+  })
+
+  it('is stable for the same code location across captures', () => {
+    const a = exceptionEntry(boom(), { handled: false, id: '1' }).stacktrace!.frames
+    const b = exceptionEntry(boom('different message'), { handled: false, id: '2' })
+      .stacktrace!.frames
+    expect(a.map((f) => f.raw_id)).toEqual(b.map((f) => f.raw_id))
+  })
+})
+
+describe('mechanism + level', () => {
+  it('reports an uncaught error as unhandled', () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    expect(e.mechanism).toEqual({ type: 'generic', handled: false, synthetic: false })
+  })
+
+  it('marks a non-Error throwable synthetic', () => {
+    const e = exceptionEntry('just a string', { handled: true, id: 'x' })
+    expect(e.mechanism?.synthetic).toBe(true)
+  })
+
+  it('defaults level to error and honours an override', () => {
+    expect(exceptionProperties(boom(), { handled: true, id: 'x' }).$exception_level).toBe('error')
+    expect(
+      exceptionProperties(boom(), { handled: true, id: 'x', level: 'warning' }).$exception_level,
+    ).toBe('warning')
+  })
+})
+
+describe('denormalized properties (nothing derives these server-side here)', () => {
+  it('sends the search + issue-column arrays the product reads', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_types).toEqual(['TypeError'])
+    expect(p.$exception_values).toEqual(['Cannot read properties of undefined'])
+    expect(p.$exception_type).toBe('TypeError')
+    expect(p.$exception_handled).toBe(false)
+    expect(p.$exception_fingerprint_record).toEqual([{ type: 'manual' }])
+    expect(p.$exception_list).toHaveLength(1)
+  })
+})
+
+describe('hostile input never escapes', () => {
+  it('survives a throwable whose getters throw', () => {
+    const hostile = {
+      get name() {
+        throw new Error('nope')
+      },
+      get message() {
+        throw new Error('nope')
+      },
+      get stack() {
+        throw new Error('nope')
+      },
+    }
+    expect(() => exceptionProperties(hostile, { handled: true, id: 'x' })).not.toThrow()
+  })
+
+  it('bounds an enormous message', () => {
+    const e = exceptionEntry(new Error('x'.repeat(100_000)), { handled: true, id: 'x' })
+    expect(e.value.length).toBeLessThanOrEqual(4096)
+  })
+
+  it('bounds frame count', () => {
+    const many = new Error('deep')
+    many.stack =
+      'Error: deep\n' +
+      Array.from({ length: 500 }, (_, i) => `    at f${i} (https://hanzo.ai/a.js:${i}:1)`).join(
+        '\n',
+      )
+    expect(exceptionEntry(many, { handled: true, id: 'x' }).stacktrace!.frames.length).toBe(50)
+  })
+})
+
+describe('digest', () => {
+  it('is stable and 32 hex chars', () => {
+    expect(digest('abc')).toBe(digest('abc'))
+    expect(digest('abc')).toMatch(/^[0-9a-f]{32}$/)
+  })
+
+  it('separates different inputs', () => {
+    expect(digest('abc')).not.toBe(digest('abd'))
+  })
+
+  it('handles an empty string', () => {
+    expect(digest('')).toMatch(/^[0-9a-f]{32}$/)
+  })
+})