@hanzo/event 0.3.8 → 0.3.10

package/src/core.test.ts

@@ -356,6 +356,40 @@ describe('Analytics capture', () => {
     expect(tx.sent[0].url).toBe('/v1/event')
   })
 
+  it('reads the ingest key from the build env when config omits it', () => {
+    // The failure this closes is silent: a surface with no key attributes nothing
+    // for a logged-out visitor, the door refuses the write, and the page shows no
+    // sign of it. The key must resolve from the env exactly as the DSN does.
+    process.env.NEXT_PUBLIC_HANZO_EVENT_KEY = 'pk-live-from-env'
+    try {
+      const a = mk() // no key in config
+      a.capture('x')
+      a.flush(true)
+      expect(tx.sent[0].ingestKey).toBe('pk-live-from-env')
+    } finally {
+      delete process.env.NEXT_PUBLIC_HANZO_EVENT_KEY
+    }
+  })
+
+  it('prefers an explicit ingest key over the build env', () => {
+    process.env.NEXT_PUBLIC_HANZO_EVENT_KEY = 'pk-live-from-env'
+    try {
+      const a = mk({ ingestKey: 'pk-live-explicit' })
+      a.capture('x')
+      a.flush(true)
+      expect(tx.sent[0].ingestKey).toBe('pk-live-explicit')
+    } finally {
+      delete process.env.NEXT_PUBLIC_HANZO_EVENT_KEY
+    }
+  })
+
+  it('stays keyless when neither config nor env names a key', () => {
+    const a = mk()
+    a.capture('x')
+    a.flush(true)
+    expect(tx.sent[0].ingestKey).toBeUndefined()
+  })
+
   it('setCohort rides subsequent events', () => {
     const a = mk()
     a.setCohort({ signupWeek: '2026-W29', channel: 'paid', refCode: 'REF9' })

package/src/core.ts

@@ -61,6 +61,7 @@ import {
   getCohort,
   mergeCohort,
 } from './storage'
+import { uuidv7 } from './uid'
 import type {
   AnalyticsConfig,
   Attribution,
@@ -111,12 +112,6 @@ function appendQuery(url: string, key: string, value: string): string {
   return url + (url.includes('?') ? '&' : '?') + key + '=' + encodeURIComponent(value)
 }
 
-function uid(): string {
-  const c = typeof crypto !== 'undefined' ? crypto : undefined
-  if (c && 'randomUUID' in c) return c.randomUUID()
-  return 'm-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
-}
-
 /** Normalize anything thrown (Error | string | unknown) into an Exception. */
 /** normalizeError adapts the shared, hostile-input-safe normalizer (sentry.ts) to
  *  the event stream's Exception shape. ONE normalizer serves both planes: a thrown
@@ -236,6 +231,15 @@ export class Analytics {
       enabled: true,
       captureErrors: true,
       ...config,
+      // The publishable key resolves the SAME way the DSN below does: an explicit
+      // config wins, else the inlined build-time env. Without this the key was the
+      // one piece of wiring a surface could not declare the way it declares every
+      // other piece, so every surface that shipped without passing it in code sent
+      // its beacons unattributed — and an unattributed write is refused (401
+      // ingest_key_required), which is silent in the page and invisible until you
+      // read the warehouse and find the host missing entirely.
+      ingestKey:
+        config.ingestKey ?? readEnv('NEXT_PUBLIC_HANZO_EVENT_KEY') ?? readEnv('HANZO_EVENT_KEY'),
     }
     this.transport = config.transport ?? new DefaultTransport()
     // Error plane, most specific source first: an explicit DSN wins, then the
@@ -472,7 +476,7 @@ export class Analytics {
   private build(kind: EventKind, event: string | undefined, extra: Partial<WireEvent>): WireEvent {
     const anon = anonId()
     const wire: WireEvent = {
-      messageId: uid(),
+      messageId: uuidv7(),
       type: kind,
       event,
       timestamp: new Date().toISOString(),

package/src/hz.test.ts

@@ -0,0 +1,96 @@
+// hz.js is the no-build distribution — 300 lines of shipped client that no test
+// had ever executed. It restates, by hand, what the bundled client imports, so the
+// two can drift; this runs the real file against a minimal browser stub and reads
+// the batch it actually posts.
+
+import { describe, expect, it, beforeEach } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const SRC = readFileSync(fileURLToPath(new URL('../hz.js', import.meta.url)), 'utf8')
+
+/** The event plane's session-rollup admission gate, transcribed from its own SQL. */
+const versionNibble = (id: string): bigint => (BigInt('0x' + id.replace(/-/g, '')) >> 76n) & 15n
+const embeddedMs = (id: string): bigint => BigInt('0x' + id.replace(/-/g, '')) >> 80n
+
+interface WireEvent {
+  messageId: string
+  sessionId: string
+  anonymousId: string
+  type: string
+  event?: string
+  library: string
+  libraryVersion: string
+}
+
+/** Runs hz.js against a stub browser and returns everything it posted. */
+function runSnippet(): { sent: WireEvent[]; api: { track(n: string): void; flush(): void } } {
+  const sent: WireEvent[] = []
+  const store = () => {
+    const m = new Map<string, string>()
+    return { getItem: (k: string) => m.get(k) ?? null, setItem: (k: string, v: string) => void m.set(k, v) }
+  }
+  const g = globalThis as Record<string, unknown>
+  g.location = { href: 'https://x.test/p?a=1', pathname: '/p', search: '?a=1', hostname: 'x.test', host: 'x.test' }
+  g.document = {
+    currentScript: { getAttribute: (a: string) => (a === 'data-product' ? 'test' : null) },
+    referrer: '',
+    addEventListener: () => {},
+    documentElement: { scrollHeight: 1000 },
+    visibilityState: 'visible',
+    createElement: () => ({}),
+    head: { appendChild: () => {} },
+  }
+  g.navigator = { doNotTrack: '0' }
+  g.localStorage = store()
+  g.sessionStorage = store()
+  g.history = { pushState: () => {}, replaceState: () => {} }
+  g.addEventListener = () => {}
+  g.PerformanceObserver = undefined
+  g.fetch = (_u: string, init: { body: string }) => {
+    sent.push(...(JSON.parse(init.body).batch as WireEvent[]))
+    return Promise.resolve()
+  }
+  g.window = g
+  new Function(SRC)()
+  return { sent, api: (g.window as { hanzo: { track(n: string): void; flush(): void } }).hanzo }
+}
+
+describe('hz.js', () => {
+  let run: ReturnType<typeof runSnippet>
+  beforeEach(() => {
+    run = runSnippet()
+  })
+
+  it('mints session ids the plane admits', () => {
+    run.api.track('checkout_started')
+    run.api.flush()
+    expect(run.sent.length).toBeGreaterThan(0)
+    const before = Date.now()
+    for (const ev of run.sent) {
+      expect(versionNibble(ev.sessionId)).toBe(7n)
+      expect(versionNibble(ev.messageId)).toBe(7n)
+      expect(versionNibble(ev.anonymousId)).toBe(7n)
+      // The embedded instant is the real mint time, not a constant.
+      expect(Number(embeddedMs(ev.sessionId))).toBeGreaterThan(before - 60_000)
+      expect(Number(embeddedMs(ev.sessionId))).toBeLessThanOrEqual(Date.now())
+    }
+  })
+
+  it('holds one session id across every event it emits', () => {
+    run.api.track('a')
+    run.api.track('b')
+    run.api.flush()
+    const ids = new Set(run.sent.map((e) => e.sessionId))
+    expect(ids.size).toBe(1)
+    expect(new Set(run.sent.map((e) => e.messageId)).size).toBe(run.sent.length)
+  })
+
+  it('emits the auto pageview on load and stamps the library', () => {
+    run.api.flush()
+    const pv = run.sent.find((e) => e.type === 'pageview')
+    expect(pv).toBeDefined()
+    expect(pv!.library).toBe('hz.js')
+    expect(pv!.libraryVersion).toMatch(/^\d+\.\d+\.\d+$/)
+  })
+})

package/src/index.ts

@@ -9,6 +9,7 @@
 
 export { Analytics, createAnalytics, VERSION, getCohort, getFirstTouch } from './core'
 export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
+export { uuidv7, uuidv7Time } from './uid'
 export { PRODUCT_DSN, dsnForProduct } from './dsn'
 export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'

package/src/sentry.ts

@@ -8,6 +8,7 @@
 // normalizeEvent, computeFingerprint). No upstream (FSL) code is used.
 
 import { scrubText } from './scrub'
+import { uuidv7 } from './uid'
 import { VERSION } from './version'
 import type {
   CaptureErrorOptions,
@@ -28,13 +29,10 @@ 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. */
+/** eventId mints a 32-hex-char id (no dashes) — the Sentry event_id shape. Same
+ *  minter as everything else, just formatted for Sentry's wire. */
 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
+  return uuidv7().replace(/-/g, '')
 }
 
 /** byteLen returns the UTF-8 byte length used for envelope item framing. */

package/src/storage.ts

@@ -3,6 +3,7 @@
 // client imports cleanly in a Next.js server component.
 
 import type { Attribution, Cohort } from './types'
+import { uuidv7 } from './uid'
 
 const KEY = {
   anon: 'hz_anon_id',
@@ -23,19 +24,13 @@ function ls(): Storage | undefined {
   }
 }
 
-function uid(): string {
-  const c = typeof crypto !== 'undefined' ? crypto : undefined
-  if (c && 'randomUUID' in c) return c.randomUUID()
-  return 'a-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
-}
-
 /** Stable anonymous id, minted once per browser and reused across sessions. */
 export function anonId(): string | undefined {
   const s = ls()
   if (!s) return undefined
   let v = s.getItem(KEY.anon)
   if (!v) {
-    v = uid()
+    v = uuidv7()
     s.setItem(KEY.anon, v)
   }
   return v
@@ -46,7 +41,14 @@ interface SessionState {
   last: number
 }
 
-/** Current session id, rotated after SESSION_TTL_MS of inactivity. */
+/**
+ * Current session id, rotated after SESSION_TTL_MS of inactivity.
+ *
+ * Minted at `now`, so the v7 timestamp the id carries IS the session's start
+ * instant — which is what the session rollups partition and order on. Passing the
+ * caller's clock rather than reading Date.now() again keeps the id's embedded time
+ * and the recorded `last` from disagreeing.
+ */
 export function sessionId(now = Date.now()): string | undefined {
   const s = ls()
   if (!s) return undefined
@@ -57,7 +59,7 @@ export function sessionId(now = Date.now()): string | undefined {
     state = null
   }
   if (!state || now - state.last > SESSION_TTL_MS) {
-    state = { id: uid(), last: now }
+    state = { id: uuidv7(now), last: now }
   } else {
     state.last = now
   }

package/src/types.ts

@@ -112,14 +112,26 @@ export interface AnalyticsConfig {
   /** Bearer token provider for token-auth apps. Omit for cookie/session apps
    *  (the client then relies on same-origin credentials). */
   getToken?: () => string | undefined | null
-  /** Publishable ingest key (pk_…). When set, the client authenticates to the ONE
-   *  front door `/v1/event` with this key instead of a bearer/cookie: it rides
-   *  Authorization: Bearer pk_… on fetch and ?ingest_key=pk_… on a headerless
-   *  page-unload beacon, so anonymous traffic is accepted and unload beacons work
-   *  without a bearer. The key is write-only (cannot read) and safe to ship in a
-   *  bundle; mint one per org via POST /v1/ingest/keys. This authenticates the
-   *  EVENT STREAM only — the error plane authenticates independently with `dsn`,
-   *  and one does not stand in for the other. */
+  /** Publishable ingest key (pk-…). When set, the client attributes writes to the
+   *  ONE front door `/v1/event` with this key instead of a bearer/cookie: it rides
+   *  Authorization: Bearer pk-… on fetch and ?ingest_key=pk-… on a headerless
+   *  page-unload beacon, so ANONYMOUS traffic is attributed and unload beacons work
+   *  without a bearer. The key is write-only — it attributes a write and never mints
+   *  a reading principal — so it is safe to ship in a bundle. Mint one per org with
+   *  POST /v1/keys {"type":"publishable"}.
+   *
+   *  Omit it and the client reads NEXT_PUBLIC_HANZO_EVENT_KEY, then HANZO_EVENT_KEY,
+   *  from the inlined build env — the same resolution `dsn` uses, so a surface
+   *  declares BOTH planes the same way and neither needs code to switch on.
+   *
+   *  A surface with no key at all still reports for whoever is SIGNED IN (the
+   *  session credential attributes them), and drops every logged-out visitor: the
+   *  door refuses an unattributable write rather than filing it where its owner
+   *  cannot read it. That failure is invisible from the page, which is why the key
+   *  belongs in the env next to the DSN and not in a checklist.
+   *
+   *  This attributes the EVENT STREAM only — the error plane authenticates
+   *  independently with `dsn`, and one does not stand in for the other. */
   ingestKey?: string
   /** Max events buffered before an automatic flush. */
   batchSize?: number

package/src/uid.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, afterEach } from 'vitest'
+import { uuidv7, uuidv7Time } from './uid'
+import { eventId } from './sentry'
+
+/** The event plane's admission gate, transcribed from the session rollup's own SQL:
+ *  `bitAnd(bitShiftRight(toUInt128(accurateCastOrNull(id,'UUID')), 76), 15) = 7`.
+ *  An id that fails this is dropped by the materialized view without an error. */
+const versionNibble = (id: string): bigint => (BigInt('0x' + id.replace(/-/g, '')) >> 76n) & 15n
+
+/** The session start the rollup partitions and orders on:
+ *  `fromUnixTimestamp(intDiv(toUInt64(bitShiftRight(session_id_v7, 80)), 1000))`. */
+const embeddedMs = (id: string): bigint => BigInt('0x' + id.replace(/-/g, '')) >> 80n
+
+/** RFC 9562 variant: the two high bits of octet 8 are 0b10. */
+const variantBits = (id: string): bigint => (BigInt('0x' + id.replace(/-/g, '')) >> 62n) & 3n
+
+const SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+describe('uuidv7', () => {
+  const realCrypto = globalThis.crypto
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'crypto', { value: realCrypto, configurable: true })
+  })
+
+  it('passes the plane admission gate that v4 fails', () => {
+    for (let i = 0; i < 200; i++) expect(versionNibble(uuidv7())).toBe(7n)
+    // The gate is real: crypto.randomUUID (v4) is what the SDK used to mint.
+    expect(versionNibble(crypto.randomUUID())).toBe(4n)
+  })
+
+  it('carries the mint instant the rollup keys on', () => {
+    for (const ms of [0, 1, 1_000, Date.now(), 253_402_300_799_000]) {
+      const id = uuidv7(ms)
+      expect(embeddedMs(id)).toBe(BigInt(ms))
+      expect(uuidv7Time(id)).toBe(ms)
+    }
+  })
+
+  it('sets the RFC 9562 variant', () => {
+    for (let i = 0; i < 50; i++) expect(variantBits(uuidv7())).toBe(2n)
+  })
+
+  it('sorts lexically by time', () => {
+    const t = Date.now()
+    const ids = [t + 3000, t, t + 1000, t + 2000].map((ms) => uuidv7(ms))
+    expect([...ids].sort()).toEqual([ids[1], ids[2], ids[3], ids[0]])
+  })
+
+  it('is unique within a single millisecond', () => {
+    const ms = Date.now()
+    const seen = new Set(Array.from({ length: 5000 }, () => uuidv7(ms)))
+    expect(seen.size).toBe(5000)
+  })
+
+  it('keeps a valid v7 shape with no crypto at all', () => {
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    const id = uuidv7(1_700_000_000_000)
+    // The old fallback emitted 'a-<base36>', which the plane casts to NULL and drops
+    // by the same gate v4 fails. Only entropy may degrade — never the shape.
+    expect(id).toMatch(SHAPE)
+    expect(versionNibble(id)).toBe(7n)
+    expect(embeddedMs(id)).toBe(1_700_000_000_000n)
+  })
+})
+
+describe('eventId', () => {
+  it('is the one minter formatted for the Sentry wire', () => {
+    const id = eventId()
+    expect(id).toMatch(/^[0-9a-f]{32}$/)
+    const dashed = `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`
+    expect(versionNibble(dashed)).toBe(7n)
+  })
+})

package/src/uid.ts

@@ -0,0 +1,70 @@
+// The ONE id minter for this client — UUIDv7 (RFC 9562 §5.7).
+//
+// WHY NOT crypto.randomUUID(): it mints v4, whose 122 bits are pure entropy and
+// carry no time. The session rollups on the event plane derive a session's start
+// instant FROM THE ID — their PARTITION BY and ORDER BY are
+// `fromUnixTimestamp(intDiv(toUInt64(bitShiftRight(session_id_v7, 80)), 1000))` —
+// so they admit only ids whose version nibble is 7
+// (`bitAnd(bitShiftRight(toUInt128(session_id), 76), 15) = 7`). A v4 session id is
+// not merely unordered there: it is DISCARDED at the door, silently, and the
+// rollup stays empty forever. Minting v7 is the whole reason those rollups can
+// exist; it also clusters index writes by time instead of scattering them across
+// the keyspace.
+//
+// Layout, 16 bytes big-endian:
+//   0..5   unix_ts_ms — 48-bit millisecond timestamp
+//   6      0111 (version 7) in the high nibble | rand_a
+//   7      rand_a
+//   8      10 (variant) in the high 2 bits | rand_b
+//   9..15  rand_b
+//
+// Never returns a non-UUID shape. The old minters fell back to `'a-' + base36`
+// when crypto was absent, and the plane casts a session id with
+// accurateCastOrNull(…, 'UUID') — a shape that does not parse becomes NULL and is
+// dropped by the same gate, so the fallback failed exactly like v4 did. Here only
+// the ENTROPY degrades without crypto; the shape is always a valid v7 UUID.
+
+/** 00..ff, so formatting is a lookup rather than 16 padStart calls. */
+const HEX: string[] = Array.from({ length: 256 }, (_, i) => (i + 0x100).toString(16).slice(1))
+
+/** Cryptographic randomness when the host has it, Math.random when it does not. */
+function fill(b: Uint8Array): Uint8Array {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(b)
+    return b
+  }
+  for (let i = 0; i < b.length; i++) b[i] = (Math.random() * 256) | 0
+  return b
+}
+
+/**
+ * uuidv7 mints a time-ordered UUIDv7 for `now` (epoch milliseconds).
+ *
+ * Two ids minted in the same millisecond sort arbitrarily between themselves; ids
+ * from different milliseconds sort by time, lexically and numerically alike.
+ */
+export function uuidv7(now: number = Date.now()): string {
+  const b = fill(new Uint8Array(16))
+  // 48-bit big-endian timestamp. Milliseconds stay exact well past year 10000, so
+  // the arithmetic never leaves the safe-integer range.
+  let t = Math.floor(now)
+  for (let i = 5; i >= 0; i--) {
+    b[i] = t % 256
+    t = Math.floor(t / 256)
+  }
+  b[6] = 0x70 | (b[6] & 0x0f) // version 7
+  b[8] = 0x80 | (b[8] & 0x3f) // variant 0b10
+  return (
+    HEX[b[0]] + HEX[b[1]] + HEX[b[2]] + HEX[b[3]] + '-' +
+    HEX[b[4]] + HEX[b[5]] + '-' +
+    HEX[b[6]] + HEX[b[7]] + '-' +
+    HEX[b[8]] + HEX[b[9]] + '-' +
+    HEX[b[10]] + HEX[b[11]] + HEX[b[12]] + HEX[b[13]] + HEX[b[14]] + HEX[b[15]]
+  )
+}
+
+/** The millisecond timestamp a v7 id was minted at — the inverse of uuidv7. */
+export function uuidv7Time(id: string): number {
+  return parseInt(id.slice(0, 8) + id.slice(9, 13), 16)
+}

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.8'
+export const VERSION = '0.3.9'