@hanzo/event 0.3.2 → 0.3.4

package/src/dsn.ts

@@ -0,0 +1,45 @@
+/**
+ * The product → Sentry DSN registry.
+ *
+ * An app declares WHAT it is (`product: 'console'`); this module knows WHERE its
+ * errors go. That split is the whole point: no surface has to learn a DSN, carry
+ * a build argument, or grow a config file to report errors — declaring the
+ * product it already declares is enough.
+ *
+ * A Sentry DSN is PUBLIC by construction. It ships inside the client bundle and
+ * is readable in devtools on any deployed page, and it grants exactly one
+ * capability: submitting new events. It cannot read issues, projects, or any
+ * other data. So committing it is not leaking a secret — it is recording a public
+ * identifier next to the code that needs it. (Contrast the server-side collector
+ * DSN in the `team-analytics-sentry` Secret, which is HMAC-derived and revocable
+ * precisely because a server-side credential is NOT public.)
+ *
+ * Why a literal map instead of deriving `hanzo-${product}`: the projects predate
+ * this registry and do not derive cleanly — `site` lives in `hanzo-ai`, not
+ * `hanzo-site`. An explicit map is honest about that; a derivation rule plus an
+ * exception table is the same data with a trap in it.
+ *
+ * Projects are org-scoped and named `<org>-<app>`. To add one: create the project
+ * (POST /v1/sentry/projects with X-Org-Id), then add its `dsn` here keyed by the
+ * 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',
+})
+
+/** 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. */
+export function dsnForProduct(product: string | undefined): string | undefined {
+  if (!product) return undefined
+  return PRODUCT_DSN[product]
+}

package/src/events.ts

@@ -2,6 +2,14 @@
 // names so funnels, goals, and cohorts line up across console/chat/app/site/admin.
 // Pageviews use the reserved "$pageview" name (emitted by analytics.pageview()),
 // matching the server read lens.
+//
+// Naming is a closed convention, not a style preference (see TAXONOMY.md):
+//   • snake_case, `<object>_<verb-in-past-tense>` — signup_completed, plan_clicked.
+//   • Names are CONSTANTS, never interpolated. A dimension (framework, model,
+//     plan, source) is a PROPERTY, never part of the name. `deploy_succeeded`
+//     with {framework:'static'} — never `deploy_static_succeeded`.
+//   • One name per user-visible moment, shared by every surface. The surface is
+//     already on the wire as `product`, so a name is never product-prefixed.
 
 export const EVENTS = {
   // Signup funnel: view -> submit -> verify -> completed -> first action.
@@ -9,6 +17,12 @@ export const EVENTS = {
   SIGNUP_SUBMITTED: 'signup_submitted',
   SIGNUP_VERIFIED: 'signup_verified',
   SIGNUP_COMPLETED: 'signup_completed',
+  /** A RETURNING user authenticated — the non-signup half of the IAM callback.
+   *  Keeping it distinct is what stops returning logins from inflating signups. */
+  LOGIN_COMPLETED: 'login_completed',
+  /** Activation: the first moment of real value. ONE event for every product —
+   *  the product-specific moment is the `action` property (api_call, app_live,
+   *  chat_reply), never a new event name. */
   FIRST_ACTION: 'first_action',
 
   // Waitlist + referral.
@@ -27,13 +41,28 @@ export const EVENTS = {
   FEATURE_USED: 'feature_used',
   API_KEY_CREATED: 'api_key_created',
   APP_CREATED: 'app_created',
-  DEPLOY_STARTED: 'deploy_started',
   PROJECT_CREATED: 'project_created',
   AGENT_CREATED: 'agent_created',
   CHAT_STARTED: 'chat_started',
   CHAT_MESSAGE_SENT: 'chat_message_sent',
+  /** The user switched model/endpoint — the single strongest quality signal a
+   *  chat surface emits (a switch usually follows a bad answer). */
+  MODEL_SWITCHED: 'model_switched',
   TASK_STARTED: 'task_started',
   TASK_COMPLETED: 'task_completed',
+
+  // Build → ship. `build_*` is a MODEL producing an artifact; `deploy_*` is that
+  // artifact going live. Intent (build_started) is never the same event as the
+  // artifact existing (app_created) — conflating them makes the funnel lie.
+  BUILD_STARTED: 'build_started',
+  /** A model finished producing an artifact (an app build, a chat reply, an agent
+   *  run). Carries `durationMs` — the outcome event owns its own duration, so no
+   *  paired start event is needed. */
+  GENERATION_COMPLETED: 'generation_completed',
+  GENERATION_FAILED: 'generation_failed',
+  DEPLOY_STARTED: 'deploy_started',
+  DEPLOY_SUCCEEDED: 'deploy_succeeded',
+  DEPLOY_FAILED: 'deploy_failed',
 } as const
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS]

package/src/funnels.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest'
+import { EVENTS, PAGEVIEW } from './events'
+import { FUNNELS, PRODUCTS, eventsOf, type FunnelId } from './funnels'
+import { GOALS } from './goals'
+
+const NAMES = new Set<string>([...Object.values(EVENTS), PAGEVIEW])
+const ids = Object.keys(FUNNELS) as FunnelId[]
+
+describe('event vocabulary', () => {
+  it('is snake_case with no product prefix or interpolation', () => {
+    for (const name of Object.values(EVENTS)) {
+      expect(name, name).toMatch(/^[a-z][a-z0-9]*(_[a-z0-9]+)+$/)
+    }
+  })
+
+  it('has no duplicate values (two constants must never share a name)', () => {
+    const values = Object.values(EVENTS)
+    expect(new Set(values).size).toBe(values.length)
+  })
+
+  it('reserves the $ prefix for the client (only $pageview)', () => {
+    expect(Object.values(EVENTS).some((n) => n.startsWith('$'))).toBe(false)
+    expect(PAGEVIEW).toBe('$pageview')
+  })
+})
+
+describe('funnels', () => {
+  it('only reference events that exist — the anti-drift guard', () => {
+    for (const id of ids) {
+      for (const step of FUNNELS[id].steps) {
+        expect(NAMES.has(step.event), `${id}: unknown event "${step.event}"`).toBe(true)
+      }
+    }
+  })
+
+  it('name only known products', () => {
+    for (const id of ids) {
+      for (const p of FUNNELS[id].products) {
+        expect(PRODUCTS, `${id}: unknown product "${p}"`).toContain(p)
+      }
+    }
+  })
+
+  it('are ordered lists of at least two steps', () => {
+    for (const id of ids) expect(FUNNELS[id].steps.length, id).toBeGreaterThanOrEqual(2)
+  })
+
+  it('mark a cross-origin funnel as aggregate (no shared anonymousId)', () => {
+    // Two surfaces + a logged-out visitor = two anonymousIds. Anything spanning
+    // origins must say so, or the read lens silently reports a false conversion.
+    for (const id of ids) {
+      if (FUNNELS[id].products.length > 1 && FUNNELS[id].join === 'person') {
+        // person-joined multi-product funnels are only legitimate post-login
+        // (site+cloud share the OIDC subject) — flag anything anonymous.
+        expect(FUNNELS[id].steps[0].event, id).not.toBe(PAGEVIEW)
+      }
+    }
+    expect(FUNNELS.siteToChat.join).toBe('aggregate')
+  })
+
+  it('the three product journeys are covered', () => {
+    expect(FUNNELS.signup.products).toContain('site')
+    expect(FUNNELS.appShip.products).toContain('app')
+    expect(FUNNELS.chatEngage.products).toContain('chat')
+  })
+
+  it('appShip ends at a live URL, not at a click', () => {
+    const last = FUNNELS.appShip.steps[FUNNELS.appShip.steps.length - 1]
+    expect(last.event).toBe(EVENTS.DEPLOY_SUCCEEDED)
+  })
+})
+
+describe('goals', () => {
+  it('derive their funnel from the registry — one definition, never restated', () => {
+    for (const goal of Object.values(GOALS)) {
+      if (!goal.funnelId) continue
+      expect(goal.funnel).toEqual(eventsOf(goal.funnelId))
+    }
+  })
+
+  it('convert on an event the funnel actually contains (or its head)', () => {
+    expect(GOALS.signup.funnel).toContain(EVENTS.SIGNUP_COMPLETED)
+    expect(GOALS.sale.funnel).toContain(EVENTS.ORDER_COMPLETED)
+    expect(GOALS.activation.funnel).toContain(EVENTS.FIRST_ACTION)
+  })
+
+  it('no longer gates signup on an event nothing emits', () => {
+    // signup_verified is IAM-internal: no surface emits it, so its presence in
+    // the signup funnel pinned the conversion rate at 0.
+    expect(GOALS.signup.funnel).not.toContain(EVENTS.SIGNUP_VERIFIED)
+  })
+})

package/src/funnels.ts

@@ -0,0 +1,154 @@
+// The ONE funnel registry. A funnel is DATA — an ordered list of event names —
+// so the products, the Insights UI, and the docs can never drift: every step is
+// a name from EVENTS (funnels.test.ts fails the build otherwise), and a GOAL that
+// has a funnel points AT one of these rather than restating the steps.
+//
+// Why here and not in Insights: the taxonomy is code that all three surfaces
+// already import (`@hanzo/event`). A funnel defined in the read lens could name
+// an event no surface emits; a funnel defined next to EVENTS cannot.
+
+import { EVENTS, PAGEVIEW } from './events'
+
+/** The emitting surfaces — the closed set of `AnalyticsConfig.product` values.
+ *  `product` is on every event, so a funnel scopes by product instead of every
+ *  surface prefixing its event names. */
+export const PRODUCTS = ['site', 'app', 'chat', 'console', 'admin', 'cloud'] as const
+export type ProductId = (typeof PRODUCTS)[number]
+
+export interface FunnelStep {
+  /** An EVENTS value (or PAGEVIEW). */
+  event: string
+  /** Human label for the Insights step. */
+  label: string
+  /** Property equality that qualifies the step, e.g. first_action{action:'api_call'}. */
+  where?: { property: string; equals: string }
+}
+
+export interface FunnelDef {
+  label: string
+  /** Surface(s) the steps are emitted from — matched against the `product` field. */
+  products: ProductId[]
+  /**
+   * How steps are joined:
+   *  • 'person'    — steps join on distinctId (one browser, or one logged-in
+   *                  person across surfaces). The normal case.
+   *  • 'aggregate' — steps are emitted on DIFFERENT origins by a LOGGED-OUT
+   *                  visitor, so there is no shared id: hanzo.ai, hanzo.app and
+   *                  hanzo.chat each mint their own anonymousId in their own
+   *                  storage. Read these as step-over-step COUNTS, never as a
+   *                  per-person conversion. Honest by construction.
+   */
+  join: 'person' | 'aggregate'
+  steps: FunnelStep[]
+}
+
+const s = (event: string, label: string, where?: FunnelStep['where']): FunnelStep => ({
+  event,
+  label,
+  ...(where ? { where } : {}),
+})
+
+export const FUNNELS = {
+  /** hanzo.ai: land → sign up. IAM hosts the form, so `signup_submitted` is the
+   *  redirect INTO IAM and `signup_completed` is the return at /auth/callback. */
+  signup: {
+    label: 'Signup',
+    products: ['site'],
+    join: 'person',
+    steps: [
+      s(PAGEVIEW, 'Landed'),
+      s(EVENTS.SIGNUP_VIEWED, 'Opened signup'),
+      s(EVENTS.SIGNUP_SUBMITTED, 'Redirected to Hanzo ID'),
+      s(EVENTS.SIGNUP_COMPLETED, 'Account created'),
+      s(EVENTS.FIRST_ACTION, 'First action'),
+    ],
+  },
+
+  /** The developer activation path: an account is worth nothing until a key has
+   *  made a call. `first_action{action:'api_call'}` is emitted SERVER-SIDE by
+   *  Cloud on an org's first successful /v1 request — a browser cannot see it. */
+  apiActivation: {
+    label: 'API activation',
+    products: ['site', 'cloud'],
+    join: 'person',
+    steps: [
+      s(EVENTS.SIGNUP_COMPLETED, 'Account created'),
+      s(EVENTS.API_KEY_CREATED, 'Key minted'),
+      s(EVENTS.FIRST_ACTION, 'First successful API call', {
+        property: 'action',
+        equals: 'api_call',
+      }),
+    ],
+  },
+
+  /** Upgrade intent → revenue. `order_completed{kind:'plan'}` is the Sale goal. */
+  upgrade: {
+    label: 'Upgrade',
+    products: ['site', 'app', 'console'],
+    join: 'person',
+    steps: [
+      s(EVENTS.PRICING_VIEWED, 'Viewed pricing'),
+      s(EVENTS.PLAN_CLICKED, 'Chose a plan'),
+      s(EVENTS.CHECKOUT_STARTED, 'Started checkout'),
+      s(EVENTS.ORDER_COMPLETED, 'Paid'),
+    ],
+  },
+
+  /** hanzo.app: describe → build → deploy → live URL. The whole product thesis
+   *  in five steps; `deploy_succeeded` is the moment a live URL exists. */
+  appShip: {
+    label: 'Describe → ship',
+    products: ['app'],
+    join: 'person',
+    steps: [
+      s(PAGEVIEW, 'Landed'),
+      s(EVENTS.BUILD_STARTED, 'Described an app'),
+      s(EVENTS.GENERATION_COMPLETED, 'Got a working build'),
+      s(EVENTS.DEPLOY_STARTED, 'Hit publish'),
+      s(EVENTS.DEPLOY_SUCCEEDED, 'Live URL'),
+    ],
+  },
+
+  /** hanzo.chat: visit → first message → answer. `generation_completed` is what
+   *  separates "typed something" from "got value". */
+  chatEngage: {
+    label: 'Chat engagement',
+    products: ['chat'],
+    join: 'person',
+    steps: [
+      s(PAGEVIEW, 'Landed'),
+      s(EVENTS.CHAT_STARTED, 'Started a conversation'),
+      s(EVENTS.CHAT_MESSAGE_SENT, 'Sent a message'),
+      s(EVENTS.GENERATION_COMPLETED, 'Got an answer'),
+    ],
+  },
+
+  /** The cross-surface handoff: the hanzo.ai composer forwards its prompt to
+   *  hanzo.chat. Two origins, two anonymousIds — so this is an AGGREGATE funnel.
+   *  The join is the `referrerProduct` property hanzo.chat reads off `?hz_ref=`,
+   *  which makes the drop-off measurable without any cross-domain identity. */
+  siteToChat: {
+    label: 'Site → Chat handoff',
+    products: ['site', 'chat'],
+    join: 'aggregate',
+    steps: [
+      s(EVENTS.CHAT_STARTED, 'Submitted the hanzo.ai composer', {
+        property: 'source',
+        equals: 'composer',
+      }),
+      s(EVENTS.CHAT_STARTED, 'Landed in hanzo.chat', {
+        property: 'referrerProduct',
+        equals: 'site',
+      }),
+      s(EVENTS.GENERATION_COMPLETED, 'Got an answer'),
+    ],
+  },
+} as const satisfies Record<string, FunnelDef>
+
+export type FunnelId = keyof typeof FUNNELS
+
+/** eventsOf flattens a funnel to its ordered event names — what a goal's `funnel`
+ *  field carries, so the steps are defined exactly once (here). */
+export function eventsOf(id: FunnelId): string[] {
+  return FUNNELS[id].steps.map((step) => step.event)
+}

package/src/goals.ts

@@ -1,44 +1,58 @@
 // Insights goals + cohorts, defined once as data so the console/insights UI and
 // every product agree on what "a Signup", "a Sale", and "upgrade intent" mean.
 // This is the machine-readable spec — the shared source of truth a sync step can
-// push into Insights, and what the guide documents.
+// push into Insights, and what TAXONOMY.md documents.
+//
+// A goal answers "what counts as a conversion". A funnel answers "by what path".
+// The paths live in funnels.ts and a goal REFERENCES one by id: the steps are
+// written down exactly once.
 
 import { EVENTS } from './events'
+import { eventsOf, type FunnelId } from './funnels'
 
 export interface GoalDef {
   /** Human label shown in Insights. */
   label: string
   /** The event whose occurrence counts as the goal conversion. */
   event: string
-  /** Optional ordered funnel leading to the goal (for funnel insights). */
+  /** The funnel leading to the goal — an id into FUNNELS (see funnels.ts). */
+  funnelId?: FunnelId
+  /** The ordered event names of `funnelId`, derived — never hand-written. */
   funnel?: string[]
   /** Optional property equality filter that qualifies the conversion. */
   filter?: { property: string; equals: string }
 }
 
-export const GOALS: Record<'signup' | 'sale' | 'upgradeIntent', GoalDef> = {
-  // Signup: the conversion is signup_completed; the funnel is the four steps.
+export const GOALS: Record<'signup' | 'sale' | 'upgradeIntent' | 'activation', GoalDef> = {
+  // Signup: the conversion is signup_completed, along the site signup funnel.
   signup: {
     label: 'Signup',
     event: EVENTS.SIGNUP_COMPLETED,
-    funnel: [
-      EVENTS.SIGNUP_VIEWED,
-      EVENTS.SIGNUP_SUBMITTED,
-      EVENTS.SIGNUP_VERIFIED,
-      EVENTS.FIRST_ACTION,
-    ],
+    funnelId: 'signup',
+    funnel: eventsOf('signup'),
   },
   // Sale: a completed order qualified as a plan purchase (kind=plan).
   sale: {
     label: 'Sale',
     event: EVENTS.ORDER_COMPLETED,
+    funnelId: 'upgrade',
+    funnel: eventsOf('upgrade'),
     filter: { property: 'kind', equals: 'plan' },
   },
   // Upgrade intent: a plan click; pricing_viewed is the top of its funnel.
   upgradeIntent: {
     label: 'Upgrade Intent',
     event: EVENTS.PLAN_CLICKED,
-    funnel: [EVENTS.PRICING_VIEWED, EVENTS.PLAN_CLICKED, EVENTS.CHECKOUT_STARTED],
+    funnelId: 'upgrade',
+    funnel: eventsOf('upgrade'),
+  },
+  // Activation: the ONE north-star conversion — an account that did the first
+  // valuable thing (a successful API call, a live app, a chat answer).
+  activation: {
+    label: 'Activation',
+    event: EVENTS.FIRST_ACTION,
+    funnelId: 'apiActivation',
+    funnel: eventsOf('apiActivation'),
   },
 }
 

package/src/index.ts

@@ -9,12 +9,15 @@
 
 export { Analytics, createAnalytics, VERSION, getCohort, getFirstTouch } from './core'
 export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
+export { PRODUCT_DSN, dsnForProduct } from './dsn'
 export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'
 export { EVENTS, PAGEVIEW } from './events'
 export type { EventName } from './events'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
+export { FUNNELS, PRODUCTS, eventsOf } from './funnels'
+export type { FunnelDef, FunnelStep, FunnelId, ProductId } from './funnels'
 export {
   parseAttribution,
   deriveChannel,

package/src/scrub.ts

@@ -70,7 +70,12 @@ function redactPAN(s: string): string {
   })
 }
 
-const RE_EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g
+// Bounded to the RFC 5321 maxima (local-part 64, domain 255) for the same reason
+// as the creds-in-URL rule: the unbounded form backtracks quadratically across a
+// long run of local-part-legal characters that never reaches an '@' — measured at
+// 20ms on an 8KB worst case, on the main thread, per captured error. No real
+// address is excluded by these caps.
+const RE_EMAIL = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}/g
 const RE_IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g
 const RE_IPV6 = /\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{1,4}\b/g
 

package/src/sentry.test.ts

@@ -258,3 +258,55 @@ describe('fingerprint grouping (port of server model)', () => {
     expect(f1).not.toBe(f2)
   })
 })
+
+// ── hostile thrown objects ─────────────────────────────────────────────────
+//
+// `name`, `message` and `stack` are ordinary getters. A thrown object is free to
+// define any of them to throw, and the thrown value is the least trustworthy
+// input this library handles. normalizeError must be TOTAL — buildSentryEvent
+// throwing here meant the crash report was lost on both planes.
+
+describe('normalizeError survives hostile input', () => {
+  const bomb = (prop: string) => {
+    const e = new Error('real message')
+    Object.defineProperty(e, prop, {
+      get() {
+        throw new Error(prop + ' bomb')
+      },
+      configurable: true,
+    })
+    return e
+  }
+
+  for (const prop of ['stack', 'message', 'name']) {
+    it(`a throwing ${prop} getter does not throw`, () => {
+      expect(() => normalizeError(bomb(prop))).not.toThrow()
+      const n = normalizeError(bomb(prop))
+      expect(typeof n.name).toBe('string')
+      expect(typeof n.message).toBe('string')
+    })
+  }
+
+  it('buildSentryEvent still produces a usable event from a getter bomb', () => {
+    const ev = buildSentryEvent({ error: bomb('stack'), identity: { product: 'test' } })
+    expect(ev.exception?.values[0].type).toBe('Error')
+    // The message survived because only `stack` was hostile.
+    expect(ev.exception?.values[0].value).toBe('real message')
+    expect(ev.exception?.values[0].stacktrace?.frames).toEqual([])
+  })
+
+  it('an object with a throwing toString is still reportable', () => {
+    const evil = {
+      toString() {
+        throw new Error('toString bomb')
+      },
+    }
+    expect(() => normalizeError(evil)).not.toThrow()
+    expect(() => buildSentryEvent({ error: evil, identity: {} })).not.toThrow()
+  })
+
+  it('a frozen/null-prototype throwable is still reportable', () => {
+    const weird = Object.freeze(Object.create(null)) as unknown
+    expect(() => buildSentryEvent({ error: weird, identity: {} })).not.toThrow()
+  })
+})

package/src/sentry.ts

@@ -148,13 +148,43 @@ export function framesFromStack(stack: string | undefined): SentryFrame[] {
 /** normalizeError coerces an unknown throwable into {name, message, stack}. */
 export function normalizeError(err: unknown): { name: string; message: string; stack?: string } {
   if (err instanceof Error) {
-    return { name: err.name || 'Error', message: err.message || String(err), stack: err.stack }
+    // `name`, `message` and `stack` are ordinary getters, and the thrown object is
+    // the least trustworthy input this library handles — any of them may throw.
+    // Losing the whole report to a hostile getter is not acceptable.
+    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) }
+    return { name: 'Error', message: JSON.stringify(err) ?? str(err) }
+  } catch {
+    return { name: 'Error', message: str(err) }
+  }
+}
+
+/** read pulls a property off a possibly-hostile value without letting a throwing
+ *  getter escape. */
+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 { name: 'Error', message: String(err) }
+    return '[unstringifiable]'
   }
 }
 

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.2'
+export const VERSION = '0.3.3'