@hanzo/event 0.3.19 → 0.3.20

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.19",
-  "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/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}$/)
+  })
+})

package/src/exception.ts

@@ -0,0 +1,200 @@
+// The `$exception` product-event shape — pure builders, no I/O.
+//
+// An exception reaches TWO destinations, and they read different shapes:
+//
+//   1. The ERROR PLANE — a Sentry envelope to the DSN host (sentry.ts). Untouched
+//      by this module.
+//   2. ERROR TRACKING in Hanzo Insights — reads the PRODUCT-EVENT plane
+//      (`insights.events WHERE event = '$exception'`) and expects the PostHog
+//      exception vocabulary: `$exception_list` plus the denormalized `$exception_*`
+//      properties. This module builds that.
+//
+// WHY THE FULLY-DERIVED SHAPE. Upstream, a server stage (Cymbal) symbolicates
+// frames and computes `$exception_fingerprint`, `$exception_types`, `_values`,
+// `_sources`, `_functions`, then REPLACES the property bag. That stage is not in
+// Hanzo's path: the door writes `event.fact` and a materialized view projects it
+// into `insights.events`, so nothing between the client and the warehouse derives
+// anything. Whatever the product reads, the client has to have sent. Two
+// consequences are load-bearing rather than cosmetic:
+//
+//   • The issue query drops any event whose `$exception_fingerprint` is null, so an
+//     event without one is invisible no matter how well-formed the rest is.
+//   • `stacktrace.type` must be the literal 'resolved'; on any other value the
+//     renderer falls through both match arms and draws nothing under the header.
+//
+// If that server stage is ever put in front of this plane it replaces these
+// properties wholesale, so sending them stays correct either way.
+//
+// FRAME ORDER is bottom-up: frames[0] is the entry point and the LAST frame is the
+// throw site. framesFromStack (sentry.ts) already returns that order, which is why
+// this module reuses it rather than re-parsing.
+
+import { framesFromStack, normalizeError } from './sentry'
+import type {
+  ExceptionEntry,
+  ExceptionFrame,
+  ExceptionProperties,
+  SentryFrame,
+  SentryLevel,
+} from './types'
+
+/** Cap on the frames carried per exception, matching the Sentry path's budget. */
+const MAX_FRAMES = 50
+/** Cap on `value`, so one enormous message cannot dominate a batch. The product
+ *  truncates for display anyway; this bounds the wire. */
+const MAX_VALUE = 4096
+
+/**
+ * digest is a stable 32-hex-char (128-bit) content hash, computed synchronously.
+ *
+ * Grouping keys are needed on the capture path, which is synchronous and may be
+ * running inside an unload handler — SubtleCrypto is async and unavailable on
+ * insecure origins, so it cannot be used here. This is FNV-1a run over four seeds
+ * and concatenated. It is a GROUPING key, never a security boundary: it is not
+ * collision-resistant against a chosen-input adversary, and nothing authorizes or
+ * authenticates on it. The product treats the value as opaque.
+ */
+export function digest(s: string): string {
+  let out = ''
+  for (const seed of [0x811c9dc5, 0x01000193, 0x9e3779b9, 0x85ebca6b]) {
+    let h = seed >>> 0
+    for (let i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i)
+      // FNV prime 16777619, via shifts to stay in 32-bit integer math.
+      h = (h + (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0
+    }
+    out += h.toString(16).padStart(8, '0')
+  }
+  return out
+}
+
+/**
+ * frameOf converts one parsed stack frame into the shape the product renders.
+ *
+ * The product's frame vocabulary is the POST-symbolication one (`mangled_name`,
+ * `source`, `line`, `column`), so that is what is emitted. `resolved` is false and
+ * honest: a browser bundle is minified and no symbol set has been uploaded, so the
+ * original name and line are genuinely unknown. Claiming `resolved: true` would
+ * trade an accurate "upload your symbol sets" hint for a misleading "source code is
+ * not available" error.
+ */
+function frameOf(f: SentryFrame): ExceptionFrame {
+  const source = f.filename ?? ''
+  const name = f.function ?? '<anonymous>'
+  const line = f.lineno ?? 0
+  const column = f.colno ?? 0
+  return {
+    // Stable per code location, so the same frame groups and re-renders under one
+    // key. The '/part' suffix is the product's format for one raw frame expanding
+    // into several resolved ones; a browser frame is always part 0.
+    raw_id: `${digest(`${source}|${name}|${line}|${column}`)}/0`,
+    mangled_name: name,
+    source,
+    line,
+    column,
+    in_app: f.in_app ?? false,
+    lang: 'javascript',
+    resolved: false,
+    resolve_failure: 'no symbol set uploaded for this release',
+    resolved_name: null,
+    module: null,
+  }
+}
+
+/** truncate bounds a free-text field without splitting a surrogate pair. */
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s
+  let end = max
+  const c = s.charCodeAt(end - 1)
+  // A high surrogate at the cut point would leave a lone half.
+  if (c >= 0xd800 && c <= 0xdbff) end--
+  return s.slice(0, end)
+}
+
+/**
+ * exceptionEntry builds the single `$exception_list` entry for a throwable.
+ *
+ * One entry, not a chain: `Error.cause` chaining is a distinct fact with its own
+ * ordering rules, and emitting it wrongly is worse than not emitting it.
+ */
+export function exceptionEntry(
+  err: unknown,
+  opts: { handled: boolean; id: string },
+): ExceptionEntry {
+  const n = normalizeError(err)
+  const frames = framesFromStack(n.stack).slice(-MAX_FRAMES)
+  const entry: ExceptionEntry = {
+    id: opts.id,
+    type: n.name,
+    value: truncate(n.message, MAX_VALUE),
+    mechanism: {
+      type: 'generic',
+      handled: opts.handled,
+      // An exception the app reported by hand was constructed, not thrown by the
+      // runtime at a real call site.
+      synthetic: !(err instanceof Error),
+    },
+  }
+  if (frames.length > 0) {
+    // 'resolved' names the SHAPE of the frame list, not the symbolication state of
+    // any frame — the renderer only walks frames on this exact value.
+    entry.stacktrace = { type: 'resolved', frames: frames.map(frameOf) }
+  }
+  return entry
+}
+
+/**
+ * fingerprint is the issue grouping key.
+ *
+ * Keyed on exception type plus each in-app frame's function and source — the same
+ * pieces the server-side grouper records ("Exception Type", "Resolved function
+ * name", "Source file name"). Deliberately NOT the message: `Loading chunk 3324
+ * failed` and `Loading chunk 998 failed` are one bug, and grouping on message is
+ * precisely the mistake that made every distinct error string its own event name.
+ *
+ * Falls back to the type alone when no in-app frame survived, which keeps
+ * stackless errors (`Script error.`, cross-origin) in one issue instead of
+ * scattering them.
+ */
+export function fingerprint(entry: ExceptionEntry): string {
+  const frames = entry.stacktrace?.frames ?? []
+  const pieces = frames
+    .filter((f) => f.in_app)
+    .map((f) => `${f.mangled_name}@${f.source}`)
+  return digest([entry.type, ...pieces].join('\n'))
+}
+
+/**
+ * exceptionProperties builds the full `$exception_*` property bag for one captured
+ * throwable — everything Error Tracking reads off the event.
+ *
+ * The denormalized arrays are ordered like `frames`: last element is the throw
+ * site, which is the element the issue list indexes at -1 for its source/function
+ * columns.
+ */
+export function exceptionProperties(
+  err: unknown,
+  opts: { handled: boolean; id: string; level?: SentryLevel },
+): ExceptionProperties {
+  const entry = exceptionEntry(err, opts)
+  const frames = entry.stacktrace?.frames ?? []
+  const fp = fingerprint(entry)
+  return {
+    $exception_list: [entry],
+    $exception_fingerprint: fp,
+    // Records WHY this fingerprint holds. 'manual' is the honest value: the client
+    // supplied the key rather than a server grouper deriving one.
+    $exception_fingerprint_record: [{ type: 'manual' }],
+    $exception_type: entry.type,
+    $exception_message: entry.value,
+    $exception_level: opts.level ?? 'error',
+    $exception_handled: opts.handled,
+    $exception_synthetic: entry.mechanism?.synthetic ?? false,
+    $exception_types: [entry.type],
+    $exception_values: [entry.value],
+    $exception_sources: frames.map((f) => f.source).filter((s): s is string => !!s),
+    $exception_functions: frames
+      .map((f) => f.resolved_name ?? f.mangled_name)
+      .filter((s): s is string => !!s),
+  }
+}

package/src/index.ts

@@ -13,7 +13,8 @@ export { uuidv7, uuidv7Time } from './uid'
 export { PRODUCT_PROJECT, dsnForProduct } from './dsn'
 export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'
-export { EVENTS, PAGEVIEW } from './events'
+export { EVENTS, EXCEPTION, PAGEVIEW } from './events'
+export { exceptionEntry, exceptionProperties, fingerprint, digest } from './exception'
 export type { EventName } from './events'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
@@ -34,6 +35,9 @@ export type {
   Dsn,
   EventKind,
   Exception,
+  ExceptionEntry,
+  ExceptionFrame,
+  ExceptionProperties,
   SentryEvent,
   SentryFrame,
   SentryLevel,

package/src/types.ts

@@ -22,6 +22,59 @@ export interface Exception {
   handled?: boolean
 }
 
+/** One stack frame as Error Tracking renders it. The key names are the product's
+ *  POST-symbolication vocabulary (`mangled_name`/`source`/`line`/`column`), which
+ *  is what the issue view reads straight off `$exception_list`. */
+export interface ExceptionFrame {
+  /** "<hash>/<part>" — stable per code location; the frame's identity. */
+  raw_id: string
+  /** The function name as it appears in the shipped bundle. */
+  mangled_name: string
+  /** File/URL the frame is in. */
+  source: string
+  line: number
+  column: number
+  /** First-party code. Frames without this are hidden by default in the product. */
+  in_app: boolean
+  lang: string
+  /** Whether a symbol set mapped this frame back to original source. */
+  resolved: boolean
+  resolve_failure?: string
+  resolved_name?: string | null
+  module?: string | null
+}
+
+/** One exception in `$exception_list`. */
+export interface ExceptionEntry {
+  id: string
+  type: string
+  value: string
+  mechanism?: {
+    type: 'generic'
+    handled: boolean
+    synthetic?: boolean
+  }
+  /** `type` MUST be 'resolved' — the renderer draws frames on no other value. */
+  stacktrace?: { type: 'resolved'; frames: ExceptionFrame[] }
+}
+
+/** The `$exception_*` property bag Error Tracking reads off a `$exception` event. */
+export interface ExceptionProperties {
+  $exception_list: ExceptionEntry[]
+  /** Issue grouping key. An event without one is dropped by the issue query. */
+  $exception_fingerprint: string
+  $exception_fingerprint_record: { type: 'manual' }[]
+  $exception_type: string
+  $exception_message: string
+  $exception_level: SentryLevel
+  $exception_handled: boolean
+  $exception_synthetic: boolean
+  $exception_types: string[]
+  $exception_values: string[]
+  $exception_sources: string[]
+  $exception_functions: string[]
+}
+
 /** First-touch marketing attribution, parsed once and persisted. */
 export interface Attribution {
   utm: {

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.19'
+export const VERSION = '0.3.20'