@hanzo/event 0.3.1 → 0.3.3

package/src/sentry.test.ts

@@ -0,0 +1,312 @@
+import { describe, it, expect } from 'vitest'
+import { createHash } from 'node:crypto'
+import {
+  parseDsn,
+  framesFromStack,
+  buildSentryEvent,
+  buildEnvelope,
+  eventId,
+  normalizeError,
+} from './sentry'
+import type { SentryEvent, SentryFrame } from './types'
+import { VERSION } from './version'
+
+const DSN = 'https://1:deadbeefcafe@api.hanzo.ai/v1/sentry/00000000-0000-0000-0000-000000000000'
+
+describe('parseDsn', () => {
+  it('keeps the version:hmac key intact (does NOT split on the colon) and derives the ingest url', () => {
+    const dsn = parseDsn(DSN)!
+    expect(dsn.publicKey).toBe('1:deadbeefcafe')
+    expect(dsn.origin).toBe('https://api.hanzo.ai')
+    expect(dsn.projectId).toBe('00000000-0000-0000-0000-000000000000')
+    expect(dsn.ingestUrl).toBe(
+      'https://api.hanzo.ai/v1/sentry/00000000-0000-0000-0000-000000000000/envelope/?sentry_key=1%3Adeadbeefcafe',
+    )
+  })
+  it('returns null for malformed input (fail-safe)', () => {
+    expect(parseDsn(undefined)).toBeNull()
+    expect(parseDsn('')).toBeNull()
+    expect(parseDsn('not-a-dsn')).toBeNull()
+    expect(parseDsn('https://api.hanzo.ai/v1/sentry/x')).toBeNull() // no key
+    expect(parseDsn('https://1:k@api.hanzo.ai')).toBeNull() // no project
+  })
+})
+
+describe('framesFromStack', () => {
+  it('parses a V8 stack oldest-first with in_app marking', () => {
+    const stack = [
+      'TypeError: x is not a function',
+      '    at inner (https://app.hanzo.ai/app.js:10:5)',
+      '    at outer (https://app.hanzo.ai/app.js:20:1)',
+      '    at eval (webpack-internal:///./node_modules/lib/index.js:3:2)',
+    ].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(3)
+    // oldest-first: the node_modules frame is the outermost caller (first),
+    // the crash site (inner) is last.
+    expect(frames[frames.length - 1].function).toBe('inner')
+    expect(frames[frames.length - 1].lineno).toBe(10)
+    expect(frames[frames.length - 1].in_app).toBe(true)
+    expect(frames[0].function).toBe('eval')
+    expect(frames[0].in_app).toBe(false) // node_modules
+  })
+  it('parses a Firefox/Safari stack (fn@file:li:co and bare @file)', () => {
+    const stack = ['boom@https://app.hanzo.ai/a.js:1:2', '@https://app.hanzo.ai/b.js:3:4'].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(2)
+    expect(frames[frames.length - 1].function).toBe('boom')
+    expect(frames[frames.length - 1].filename).toBe('https://app.hanzo.ai/a.js')
+  })
+  it('skips the header line and tolerates junk', () => {
+    expect(framesFromStack('Error: nope\n   total garbage line')).toHaveLength(0)
+    expect(framesFromStack(undefined)).toHaveLength(0)
+  })
+})
+
+describe('normalizeError', () => {
+  it('coerces Error, string, and objects', () => {
+    expect(normalizeError(new RangeError('r')).name).toBe('RangeError')
+    expect(normalizeError('boom')).toEqual({ name: 'Error', message: 'boom' })
+    expect(normalizeError({ a: 1 }).message).toBe('{"a":1}')
+  })
+})
+
+describe('eventId', () => {
+  it('is 32 lowercase hex chars (the Sentry event_id shape)', () => {
+    expect(eventId()).toMatch(/^[0-9a-f]{32}$/)
+    expect(eventId()).not.toBe(eventId())
+  })
+})
+
+describe('buildSentryEvent', () => {
+  it('sets subject-only user, default error level, scrubbed message, product tags', () => {
+    const ev = buildSentryEvent({
+      error: new Error('boom for bob@corp.com'),
+      identity: { userId: 'sub-9', sessionId: 'sess-1', product: 'app', release: 'v1', environment: 'production' },
+    })
+    expect(ev.platform).toBe('javascript')
+    expect(ev.level).toBe('error')
+    expect(ev.user).toEqual({ id: 'sub-9' })
+    expect(ev.exception!.values[0].value).toBe('boom for [email]')
+    expect(ev.tags!.product).toBe('app')
+    expect(ev.tags!.session).toBe('sess-1')
+    expect(ev.tags!.handled).toBe('true')
+    expect(ev.release).toBe('v1')
+    expect(ev.environment).toBe('production')
+    expect(ev.sdk).toEqual({ name: '@hanzo/event', version: VERSION })
+  })
+  it('uncaught errors default to fatal level and handled=false', () => {
+    const ev = buildSentryEvent({ error: new Error('x'), options: { handled: false }, identity: {} })
+    expect(ev.level).toBe('fatal')
+    expect(ev.tags!.handled).toBe('false')
+  })
+  it('omits user entirely when there is no subject', () => {
+    const ev = buildSentryEvent({ error: new Error('x'), identity: {} })
+    expect(ev.user).toBeUndefined()
+  })
+})
+
+// ── round-trip proof: a byte-faithful TS port of the SERVER parser recovers the
+//    exact event from our envelope. Port of o11y
+//    pkg/modules/errortracking/implerrortracking/envelope.go parseEnvelope. ───────
+
+function parseEnvelopeOracle(body: Uint8Array): SentryEvent[] {
+  let pos = 0
+  const dec = new TextDecoder()
+  const readLine = (): Uint8Array | null => {
+    if (pos >= body.length) return null
+    const nl = body.indexOf(0x0a, pos)
+    if (nl >= 0) {
+      const line = body.subarray(pos, nl)
+      pos = nl + 1
+      return line
+    }
+    const line = body.subarray(pos)
+    pos = body.length
+    return line
+  }
+  if (readLine() === null) throw new Error('empty envelope') // required header
+  const events: SentryEvent[] = []
+  while (pos < body.length) {
+    if (events.length >= 1000) break
+    const hdrLine = readLine()
+    if (hdrLine === null) break
+    const hdrStr = dec.decode(hdrLine).trim()
+    if (hdrStr.length === 0) continue
+    let ih: { type?: string; length?: number | null }
+    try {
+      ih = JSON.parse(hdrStr)
+    } catch {
+      break
+    }
+    let payload: Uint8Array | null
+    if (ih.length != null && ih.length >= 0 && ih.length <= body.length - pos) {
+      const end = pos + ih.length
+      payload = body.subarray(pos, end)
+      pos = end
+      if (pos < body.length && body[pos] === 0x0a) pos++
+    } else {
+      payload = readLine()
+      if (payload === null) break
+    }
+    if (ih.type === 'event') {
+      try {
+        events.push(JSON.parse(dec.decode(payload)) as SentryEvent)
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return events
+}
+
+describe('buildEnvelope round-trip (server parser recovers our event)', () => {
+  it('recovers exactly one event with matching id + exception', () => {
+    const dsn = parseDsn(DSN)!
+    const event = buildSentryEvent({
+      error: new TypeError('cannot read properties of undefined'),
+      identity: { userId: 'sub-1', sessionId: 'sess-1', product: 'app' },
+    })
+    const envelope = buildEnvelope(event, dsn)
+    const recovered = parseEnvelopeOracle(new TextEncoder().encode(envelope))
+    expect(recovered).toHaveLength(1)
+    expect(recovered[0].event_id).toBe(event.event_id)
+    expect(recovered[0].exception!.values[0].type).toBe('TypeError')
+    expect(recovered[0].platform).toBe('javascript')
+  })
+
+  it('byte-length framing is correct with multi-byte characters', () => {
+    const dsn = parseDsn(DSN)!
+    const event = buildSentryEvent({
+      error: new Error('naïve café €500 — 日本語 fails'),
+      identity: { userId: 'sub-1' },
+    })
+    const envelope = buildEnvelope(event, dsn)
+    const recovered = parseEnvelopeOracle(new TextEncoder().encode(envelope))
+    expect(recovered).toHaveLength(1)
+    expect(recovered[0].exception!.values[0].value).toContain('日本語')
+  })
+})
+
+// ── grouping proof: a compact port of the server fingerprint (fingerprint.go).
+//    Two errors with the same crash frame group together; a different type does not.
+
+function normalizeFunction(fn: string): string {
+  return fn.replace(/0x[0-9a-fA-F]+/g, '').trim()
+}
+function normalizeFilename(name: string): string {
+  name = name.trim().replace(/\\/g, '/')
+  const i = name.search(/[?#]/)
+  if (i >= 0) name = name.slice(0, i)
+  let segs = name.replace(/^\/+|\/+$/g, '').split('/')
+  if (segs.length > 2) segs = segs.slice(segs.length - 2)
+  return segs.map((s) => s.replace(/\b[0-9a-fA-F]{8,}\b/g, '*').replace(/\b\d[\d.,_]*\b/g, '*')).join('/')
+}
+function normalizeFrame(f: SentryFrame): string {
+  const fn = normalizeFunction(f.function ?? '')
+  const loc = f.module || normalizeFilename(f.filename ?? '') || normalizeFilename(f.abs_path ?? '')
+  if (fn && loc) return `${fn}@${loc}`
+  return fn || loc
+}
+function pickCrashFrame(frames: SentryFrame[]): SentryFrame | null {
+  if (frames.length === 0) return null
+  for (let i = frames.length - 1; i >= 0; i--) if (frames[i].in_app) return frames[i]
+  return frames[frames.length - 1]
+}
+function fingerprintOf(ev: SentryEvent): string {
+  const val = ev.exception!.values[0]
+  const parts: string[] = []
+  if (val.type) parts.push('type:' + val.type)
+  const frame = pickCrashFrame(val.stacktrace?.frames ?? [])
+  if (frame) {
+    const sig = normalizeFrame(frame)
+    if (sig) parts.push('frame:' + sig)
+  }
+  const h = createHash('sha256')
+  parts.forEach((p, i) => {
+    if (i > 0) h.update(Buffer.from([0]))
+    h.update(Buffer.from(p, 'utf8'))
+  })
+  return h.digest('hex')
+}
+
+describe('fingerprint grouping (port of server model)', () => {
+  const stack = [
+    'TypeError: user missing',
+    '    at loadUser (https://app.hanzo.ai/app.9f3a2b1c.js:42:11)',
+    '    at render (https://app.hanzo.ai/app.9f3a2b1c.js:88:3)',
+  ].join('\n')
+
+  it('groups two errors with the same crash frame despite different ids in the message', () => {
+    const e1 = new Error('user 111 missing')
+    e1.stack = stack.replace('user missing', 'user 111 missing')
+    const e2 = new Error('user 222 missing')
+    e2.stack = stack.replace('user missing', 'user 222 missing')
+    const f1 = fingerprintOf(buildSentryEvent({ error: e1, identity: {} }))
+    const f2 = fingerprintOf(buildSentryEvent({ error: e2, identity: {} }))
+    expect(f1).toMatch(/^[0-9a-f]{64}$/)
+    expect(f1).toBe(f2)
+  })
+
+  it('does NOT group different exception types', () => {
+    const e1 = new TypeError('boom')
+    e1.stack = stack
+    const e2 = new RangeError('boom')
+    e2.stack = stack.replace('TypeError', 'RangeError')
+    const f1 = fingerprintOf(buildSentryEvent({ error: e1, identity: {} }))
+    const f2 = fingerprintOf(buildSentryEvent({ error: e2, identity: {} }))
+    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

@@ -0,0 +1,309 @@
+// Pure builders for the error path: parse a Hanzo-minted DSN, turn a JS Error into
+// a Sentry `event`, and frame it into a Sentry envelope. No I/O, no globals — the
+// Analytics client (core.ts) wires these to identity + transport.
+//
+// The wire shapes are a from-scratch model of the PUBLIC, documented Sentry ingest
+// protocol (develop.sentry.dev), verified against the Hanzo /v1/sentry ingest
+// (o11y pkg/modules/errortracking/implerrortracking: parseEnvelope, SentryEvent,
+// normalizeEvent, computeFingerprint). No upstream (FSL) code is used.
+
+import { scrubText } from './scrub'
+import { VERSION } from './version'
+import type {
+  CaptureErrorOptions,
+  Dsn,
+  SentryEvent,
+  SentryFrame,
+  SentryLevel,
+} from './types'
+
+/** Max stack frames kept — well under the server's 250 cap, plenty for grouping. */
+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
+/** Max tag string length, so one huge property can't bloat the envelope. */
+const MAX_TAG_LEN = 1024
+/** Max tags copied from properties. */
+const MAX_TAGS = 50
+
+/** eventId mints a 32-hex-char id (no dashes) — the Sentry event_id shape. */
+export function eventId(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && 'randomUUID' in c) return c.randomUUID().replace(/-/g, '')
+  let s = ''
+  for (let i = 0; i < 32; i++) s += Math.floor(Math.random() * 16).toString(16)
+  return s
+}
+
+/** byteLen returns the UTF-8 byte length used for envelope item framing. */
+function byteLen(s: string): number {
+  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(s).length
+  // Node fallback.
+  if (typeof Buffer !== 'undefined') return Buffer.byteLength(s, 'utf8')
+  return s.length
+}
+
+/**
+ * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
+ * public key + the derived envelope ingest URL. The key (which itself contains a
+ * ':') is taken verbatim as the userinfo — we do NOT split it as user:pass. The
+ * key rides ?sentry_key= (not the DSN in the body) because that is the credential
+ * channel the server trusts AND the only one sendBeacon can carry on unload.
+ * Returns null for anything malformed (fail-safe: the caller then stays inert).
+ */
+export function parseDsn(dsn: string | undefined | null): Dsn | null {
+  if (!dsn) return null
+  const m = /^(https?):\/\/([^@]+)@([^/]+)(\/.*)?$/.exec(dsn.trim())
+  if (!m) return null
+  const scheme = m[1]
+  const publicKey = m[2]
+  const host = m[3]
+  const path = m[4] ?? ''
+  if (!publicKey || !host) return null
+  const segs = path.split('/').filter(Boolean)
+  const projectId = segs.length > 0 ? segs[segs.length - 1] : ''
+  if (!projectId) return null
+  const origin = `${scheme}://${host}`
+  const ingestUrl =
+    `${origin}/v1/sentry/${encodeURIComponent(projectId)}/envelope/` +
+    `?sentry_key=${encodeURIComponent(publicKey)}`
+  return { publicKey, origin, projectId, ingestUrl }
+}
+
+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) for grouping. */
+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 Sentry frames, OLDEST-FIRST
+ * (Sentry orders caller->callee; the crash site is last — matching the server's
+ * pickCrashFrame). 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): SentryFrame[] {
+  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: SentryFrame[] = []
+  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
+}
+
+/** normalizeError coerces an unknown throwable into {name, message, stack}. */
+export function normalizeError(err: unknown): { name: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    // `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) ?? 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 '[unstringifiable]'
+  }
+}
+
+/** Identity carried onto every error event — the SAME ids analytics uses. */
+export interface ErrorIdentity {
+  /** OIDC sub (post-identify) or anon id. NEVER email/PII. */
+  userId?: string
+  sessionId?: string
+  product?: string
+  release?: string
+  environment?: string
+}
+
+export interface BuildEventInput {
+  error: unknown
+  options?: CaptureErrorOptions
+  identity: ErrorIdentity
+  capturePII?: boolean
+  /** Injectable for deterministic tests. */
+  now?: number
+  id?: string
+}
+
+function coerceTag(v: unknown): string {
+  const s = typeof v === 'string' ? v : (() => {
+    try {
+      return JSON.stringify(v) ?? String(v)
+    } catch {
+      try {
+        return String(v) // circular — fall back to the primitive coercion
+      } catch {
+        return '[unstringifiable]' // ...which a throwing toString can also refuse
+      }
+    }
+  })()
+  return s.length > MAX_TAG_LEN ? s.slice(0, MAX_TAG_LEN) : s
+}
+
+/**
+ * buildSentryEvent turns a throwable + identity into a Sentry `event`. The message
+ * (the leak surface) is scrubbed client-side; the user is ONLY the stable subject
+ * id — never email/username/ip. Level defaults to error, or fatal for uncaught.
+ */
+export function buildSentryEvent(input: BuildEventInput): SentryEvent {
+  const { error, options = {}, identity, capturePII = false } = input
+  const norm = normalizeError(error)
+  const handled = options.handled !== false
+  const level: SentryLevel = options.level ?? (handled ? 'error' : 'fatal')
+
+  const tags: Record<string, string> = { handled: String(handled) }
+  if (identity.product) tags.product = identity.product
+  if (identity.sessionId) tags.session = identity.sessionId
+  // Tags come from arbitrary caller `properties`. Read each key in isolation:
+  // Object.entries() invokes every getter at once, so one throwing getter would
+  // cost us the entire envelope — losing the stack trace to save a tag. Keys are
+  // optional; the exception is not.
+  try {
+    const props = (options.properties ?? {}) as Record<string, unknown>
+    let n = 0
+    for (const k of Object.keys(props)) {
+      if (n >= MAX_TAGS) break
+      try {
+        const val = props[k]
+        if (val === undefined || val === null) continue
+        tags[k] = scrubText(coerceTag(val), capturePII)
+        n++
+      } catch {
+        continue // throwing getter or unstringifiable value — skip this key only
+      }
+    }
+  } catch {
+    /* unenumerable/exotic properties object — ship the exception without tags */
+  }
+
+  const event: SentryEvent = {
+    event_id: input.id ?? eventId(),
+    timestamp: (input.now ?? Date.now()) / 1000,
+    platform: 'javascript',
+    level,
+    logger: identity.product,
+    environment: identity.environment,
+    release: identity.release,
+    exception: {
+      values: [
+        {
+          type: norm.name,
+          value: scrubText(norm.message, capturePII),
+          stacktrace: { frames: framesFromStack(norm.stack) },
+        },
+      ],
+    },
+    tags,
+    sdk: { name: '@hanzo/event', version: VERSION },
+  }
+  if (identity.userId) event.user = { id: identity.userId }
+  return event
+}
+
+/**
+ * buildEnvelope frames a Sentry event into a newline-delimited envelope:
+ *
+ *   {"event_id","dsn","sent_at"}\n
+ *   {"type":"event","content_type":"application/json","length":N}\n
+ *   <event json>\n
+ *
+ * The item is length-delimited (N = UTF-8 byte length) — the framing the server's
+ * parseEnvelope reads first (falling back to newline-delimited otherwise).
+ */
+export function buildEnvelope(event: SentryEvent, dsn: Dsn, sentAt?: string): string {
+  const payload = JSON.stringify(event)
+  const header = JSON.stringify({
+    event_id: event.event_id,
+    dsn: `${dsn.origin}/v1/sentry/${dsn.projectId}`,
+    sent_at: sentAt ?? new Date().toISOString(),
+  })
+  const itemHeader = JSON.stringify({
+    type: 'event',
+    content_type: 'application/json',
+    length: byteLen(payload),
+  })
+  return `${header}\n${itemHeader}\n${payload}\n`
+}