@hanzo/event 0.3.13 → 0.3.15

package/src/hz.test.ts

@@ -42,6 +42,9 @@ interface StubOptions {
   navigator?: Record<string, unknown>
   /** Seed localStorage (e.g. an explicit hz_consent choice). */
   storage?: Record<string, string>
+  /** The cookie jar. Pass one in to model a browser that already carries an id —
+   *  from another *.hanzo.ai surface, or from the npm client on this same page. */
+  jar?: Map<string, string>
   /** Let navigator.sendBeacon succeed, so the beacon path is the one measured. */
   beacon?: boolean
 }
@@ -54,16 +57,20 @@ type Api = { track(n: string, p?: unknown): void; flush(): void }
  *  descriptor is an accessor with no setter, so the plain assignment this
  *  harness used threw — and every hz.js test failed on a current runtime,
  *  leaving the shipped file with no executed coverage again. */
-function runSnippet(opts: StubOptions = {}): { posts: Post[]; api: Api | undefined } {
+function runSnippet(opts: StubOptions = {}): {
+  posts: Post[]
+  api: Api | undefined
+  local: Map<string, string>
+  jar: Map<string, string>
+} {
   const posts: Post[] = []
-  const store = (seed: Record<string, string> = {}) => {
-    const m = new Map<string, string>(Object.entries(seed))
-    return {
-      getItem: (k: string) => m.get(k) ?? null,
-      setItem: (k: string, v: string) => void m.set(k, v),
-      removeItem: (k: string) => void m.delete(k),
-    }
-  }
+  const local = new Map<string, string>(Object.entries(opts.storage ?? {}))
+  const jar = opts.jar ?? new Map<string, string>()
+  const store = (m: Map<string, string>) => ({
+    getItem: (k: string) => m.get(k) ?? null,
+    setItem: (k: string, v: string) => void m.set(k, v),
+    removeItem: (k: string) => void m.delete(k),
+  })
   const attrs: Record<string, string> = { 'data-product': 'test', ...opts.attrs }
   const g = globalThis as unknown as Record<string, unknown>
   const define = (name: string, value: unknown) =>
@@ -78,6 +85,16 @@ function runSnippet(opts: StubOptions = {}): { posts: Post[]; api: Api | undefin
   })
   define('document', {
     currentScript: { getAttribute: (a: string) => attrs[a] ?? null },
+    // A real jar: the anonymous id is a cookie now, so a stub with no `cookie`
+    // would leave the whole identity chain unexecuted by these tests.
+    get cookie(): string {
+      return [...jar].map(([k, v]) => `${k}=${v}`).join('; ')
+    },
+    set cookie(raw: string) {
+      const first = raw.split(';')[0]
+      const eq = first.indexOf('=')
+      if (eq > 0) jar.set(first.slice(0, eq).trim(), first.slice(eq + 1).trim())
+    },
     referrer: '',
     addEventListener: () => {},
     documentElement: { scrollHeight: 1000 },
@@ -104,8 +121,8 @@ function runSnippet(opts: StubOptions = {}): { posts: Post[]; api: Api | undefin
       }
     },
   )
-  define('localStorage', store(opts.storage))
-  define('sessionStorage', store())
+  define('localStorage', store(local))
+  define('sessionStorage', store(new Map()))
   define('history', { pushState: () => {}, replaceState: () => {} })
   define('addEventListener', () => {})
   define('PerformanceObserver', undefined)
@@ -122,7 +139,7 @@ function runSnippet(opts: StubOptions = {}): { posts: Post[]; api: Api | undefin
   define('window', g)
 
   new Function(SRC)()
-  return { posts, api: (g.window as { hanzo?: Api }).hanzo }
+  return { posts, api: (g.window as { hanzo?: Api }).hanzo, local, jar }
 }
 
 /** Every event across every transmission, in order. */
@@ -170,6 +187,44 @@ describe('hz.js', () => {
     expect(pv!.libraryVersion).toBe(PKG.version)
   })
 
+  // ── identity ──────────────────────────────────────────────────────────────
+  // This file used to mint into `hz_id`, a key nothing else read or wrote, so a
+  // page carrying both this tag and the npm client sent two anonymous ids for one
+  // visitor — and every surface counted them as two people. It now runs the same
+  // chain, from the same file, against the same key.
+
+  const SEEDED = '01920000-0000-7000-8000-0000000000cc'
+  const LEGACY = '01920000-0000-7000-8000-0000000000dd'
+
+  it('is the same person as every other Hanzo client on the browser', () => {
+    // The cookie the npm client (or another *.hanzo.ai surface) already wrote.
+    const r = runSnippet({ jar: new Map([['hz_anon_id', SEEDED]]) })
+    r.api!.track('checkout_started')
+    r.api!.flush()
+    const sent = sentOf(r)
+    expect(sent.length).toBeGreaterThan(0)
+    for (const ev of sent) expect(ev.anonymousId).toBe(SEEDED)
+  })
+
+  it('adopts the `hz_id` it used to mint rather than making a stranger', () => {
+    // Every browser that has ever loaded this tag holds one of these. Minting
+    // over it would detach a returning visitor from their own history.
+    const r = runSnippet({ storage: { hz_id: LEGACY } })
+    r.api!.flush()
+    for (const ev of sentOf(r)) expect(ev.anonymousId).toBe(LEGACY)
+    expect(r.jar.get('hz_anon_id')).toBe(LEGACY) // carried onto the shared key
+    expect(r.local.get('hz_anon_id')).toBe(LEGACY)
+  })
+
+  it('writes the one key, in the durable place, and no longer mints its own', () => {
+    const r = runSnippet()
+    r.api!.flush()
+    const id = sentOf(r)[0].anonymousId
+    expect(r.jar.get('hz_anon_id')).toBe(id) // the cookie outlives the ORIGIN
+    expect(r.local.get('hz_anon_id')).toBe(id)
+    expect(r.local.has('hz_id')).toBe(false)
+  })
+
   // ── the publishable key ───────────────────────────────────────────────────
   // Through 0.3.11 this file could present none at all: no header, no query. A
   // keyed static surface therefore sent UNATTRIBUTED writes, which the door

package/src/storage.test.ts

@@ -0,0 +1,285 @@
+// The anonymous id is the join key for the whole pre-signup journey, and it used
+// to live in localStorage — which is ORIGIN-scoped, so docs, cloud and console
+// each minted their own for the same person (463 anonymous identities carried 545
+// events in a week). It is now a cookie on the registrable domain. These tests
+// pin the two properties that migration turns on: that one jar yields ONE id
+// across surfaces, and that an existing localStorage id is ADOPTED rather than
+// minted over — minting there resets every returning visitor.
+
+import { describe, it, expect, vi } from 'vitest'
+
+const ANON = 'hz_anon_id'
+const LEGACY = '01920000-0000-7000-8000-0000000000aa'
+const OTHER = '01920000-0000-7000-8000-0000000000bb'
+
+const g = globalThis as Record<string, unknown>
+
+interface Browser {
+  /** Every raw `document.cookie = …` write, so attributes can be asserted. */
+  writes: string[]
+  /** name → raw cookie value, shared between surfaces to model one browser. */
+  jar: Map<string, string>
+  store: Map<string, string> | undefined
+  restore: () => void
+}
+
+/** A minimal browser. `jar` can be passed in to model two *.hanzo.ai surfaces
+ *  reading the same cookie store, which is the whole point of the change. */
+function browser(
+  opts: {
+    href?: string
+    jar?: Map<string, string>
+    storage?: Record<string, string>
+    noStorage?: boolean
+    refuseCookies?: boolean
+    noDocument?: boolean
+  } = {},
+): Browser {
+  const had = { window: 'window' in g, document: 'document' in g }
+  const prev = { window: g.window, document: g.document }
+  const jar = opts.jar ?? new Map<string, string>()
+  const writes: string[] = []
+  const store = opts.noStorage ? undefined : new Map(Object.entries(opts.storage ?? {}))
+  const url = new URL(opts.href ?? 'https://docs.hanzo.ai/guide')
+
+  g.window = {
+    location: {
+      href: url.href,
+      hostname: url.hostname,
+      protocol: url.protocol,
+      pathname: url.pathname,
+      search: url.search,
+    },
+    localStorage: store && {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => void store.set(k, v),
+    },
+    addEventListener: () => {},
+  }
+  if (opts.noDocument) {
+    delete g.document
+  } else {
+    g.document = {
+      get cookie(): string {
+        return [...jar].map(([k, v]) => `${k}=${v}`).join('; ')
+      },
+      set cookie(raw: string) {
+        writes.push(raw)
+        if (opts.refuseCookies) return // a jar that accepts the write and drops it
+        const eq = raw.split(';')[0].indexOf('=')
+        if (eq < 0) return
+        jar.set(raw.slice(0, eq).trim(), raw.split(';')[0].slice(eq + 1).trim())
+      },
+      referrer: '',
+      visibilityState: 'visible',
+    }
+  }
+
+  return {
+    writes,
+    jar,
+    store,
+    restore: () => {
+      if (had.window) g.window = prev.window
+      else delete g.window
+      if (had.document) g.document = prev.document
+      else delete g.document
+    },
+  }
+}
+
+/** A fresh module instance — the in-memory fallback is module state, and each
+ *  surface in these tests is a separately loaded copy of the client. */
+const load = async () => {
+  vi.resetModules()
+  return await import('./storage')
+}
+
+const isUuidV7 = (id: string) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id)
+
+describe('anonId', () => {
+  it('adopts an existing localStorage id into the cookie instead of minting', async () => {
+    // THE migration invariant. Minting here would hand every returning visitor a
+    // new identity and detach them from their own history.
+    const b = browser({ storage: { [ANON]: LEGACY } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(LEGACY)
+      expect(b.jar.get(ANON)).toBe(LEGACY)
+      expect(b.store!.get(ANON)).toBe(LEGACY)
+    } finally {
+      b.restore()
+    }
+  })
+
+  it("adopts hz.js's `hz_id` when there is no canonical id to find", async () => {
+    // The no-build tag minted into a key of its own, so a browser that met hz.js
+    // first already carries an identity — under a different name. Minting here
+    // would make that visitor a stranger the moment they reach a bundled surface,
+    // which is precisely the split this migration closes.
+    const b = browser({ storage: { hz_id: LEGACY } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(LEGACY)
+      expect(b.jar.get(ANON)).toBe(LEGACY)
+      expect(b.store!.get(ANON)).toBe(LEGACY) // and converged onto the one key
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('prefers the canonical id when a divergent hz_id is also present', async () => {
+    // Both clients ran on this origin before the merge and counted the visitor
+    // twice. One of the two has to win, and it is the key everything else uses.
+    const b = browser({ storage: { [ANON]: LEGACY, hz_id: OTHER } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(LEGACY)
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('lets the cookie win over a divergent origin-local id', async () => {
+    // docs already minted its own before the migration; the shared cookie is now
+    // the source of truth and localStorage converges onto it.
+    const b = browser({ jar: new Map([[ANON, OTHER]]), storage: { [ANON]: LEGACY } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(OTHER)
+      expect(b.store!.get(ANON)).toBe(OTHER)
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('mints a v7 id when neither store holds one, and writes both', async () => {
+    const b = browser()
+    try {
+      const { anonId } = await load()
+      const id = anonId()!
+      expect(isUuidV7(id)).toBe(true)
+      expect(b.jar.get(ANON)).toBe(id)
+      expect(b.store!.get(ANON)).toBe(id)
+      expect(anonId()).toBe(id) // stable across calls
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('is the SAME id on a second *.hanzo.ai surface sharing the jar', async () => {
+    // The goal: one visitor is one person from marketing through checkout.
+    const shared = new Map<string, string>()
+    const docs = browser({ href: 'https://docs.hanzo.ai/guide', jar: shared })
+    let first: string
+    try {
+      first = (await load()).anonId()!
+    } finally {
+      docs.restore()
+    }
+    // A different origin: its own empty localStorage, the same cookie jar.
+    const cloud = browser({ href: 'https://cloud.hanzo.ai/', jar: shared })
+    try {
+      expect((await load()).anonId()).toBe(first)
+    } finally {
+      cloud.restore()
+    }
+  })
+
+  it('returns undefined during SSR rather than minting a server-side id', async () => {
+    const had = { window: 'window' in g, document: 'document' in g }
+    const prev = { window: g.window, document: g.document }
+    delete g.window
+    delete g.document
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBeUndefined()
+    } finally {
+      if (had.window) g.window = prev.window
+      if (had.document) g.document = prev.document
+    }
+  })
+
+  it('scopes the cookie to the registrable domain, secure and long-lived', async () => {
+    const b = browser({ href: 'https://cloud.hanzo.ai/billing' })
+    try {
+      const { anonId } = await load()
+      anonId()
+      const w = b.writes[0]
+      expect(w).toContain('Domain=hanzo.ai')
+      expect(w).toContain('Path=/')
+      expect(w).toContain('SameSite=Lax')
+      expect(w).toContain('Secure')
+      expect(w).toContain(`Max-Age=${2 * 365 * 24 * 60 * 60}`)
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('omits Domain and Secure off hanzo.ai, where both would drop the cookie', async () => {
+    const b = browser({ href: 'http://localhost:3000/' })
+    try {
+      const { anonId } = await load()
+      const id = anonId()!
+      expect(b.writes[0]).not.toContain('Domain=')
+      expect(b.writes[0]).not.toContain('Secure')
+      expect(b.jar.get(ANON)).toBe(id) // still durable, just host-only
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('falls back to localStorage when cookies are refused', async () => {
+    const b = browser({ refuseCookies: true, storage: { [ANON]: LEGACY } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(LEGACY)
+      expect(anonId()).toBe(LEGACY)
+      expect(b.jar.size).toBe(0)
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('holds one id in memory when both cookies and localStorage are refused', async () => {
+    const b = browser({ refuseCookies: true, noStorage: true })
+    try {
+      const { anonId } = await load()
+      const id = anonId()!
+      expect(isUuidV7(id)).toBe(true)
+      expect(anonId()).toBe(id) // one identity per page load, not one per event
+    } finally {
+      b.restore()
+    }
+  })
+
+  it('survives a browser with no document at all', async () => {
+    const b = browser({ noDocument: true, storage: { [ANON]: LEGACY } })
+    try {
+      const { anonId } = await load()
+      expect(anonId()).toBe(LEGACY)
+    } finally {
+      b.restore()
+    }
+  })
+})
+
+describe('sessionId', () => {
+  // Deliberately unchanged by the anon migration: a session is origin-local and
+  // rotates on a 30-minute idle window.
+  it('stays in localStorage and rotates after the idle window', async () => {
+    const b = browser()
+    try {
+      const { sessionId } = await load()
+      const t0 = Date.now()
+      const a = sessionId(t0)
+      // The window runs from the LAST call, not from the session's start.
+      expect(sessionId(t0 + 60_000)).toBe(a)
+      expect(sessionId(t0 + 60_000 + 31 * 60_000)).not.toBe(a)
+      expect(b.jar.has('hz_session')).toBe(false)
+    } finally {
+      b.restore()
+    }
+  })
+})

package/src/storage.ts

@@ -1,12 +1,16 @@
 // SSR-safe browser storage for stable identifiers and first-touch state. Every
 // accessor no-ops (returns undefined) when there is no window/localStorage, so the
 // client imports cleanly in a Next.js server component.
+//
+// The anonymous id is the one value that must outlive an ORIGIN, and it is also
+// the one value the OTHER two distributions must agree with, so its chain lives in
+// ./anon.js and this file only calls it. Everything else here stays origin-local.
 
+import { hzAnonId } from './anon.js'
 import type { Attribution, Cohort } from './types'
 import { uuidv7 } from './uid'
 
 const KEY = {
-  anon: 'hz_anon_id',
   session: 'hz_session',
   firstTouch: 'hz_first_touch',
   cohort: 'hz_cohort',
@@ -24,16 +28,20 @@ function ls(): Storage | undefined {
   }
 }
 
-/** Stable anonymous id, minted once per browser and reused across sessions. */
+/**
+ * Stable anonymous id, shared by every *.hanzo.ai surface AND by every Hanzo
+ * client on the page — the npm client, hz.js and the hosted tag all run the one
+ * chain in ./anon.js, so which snippet a surface loaded no longer decides who the
+ * visitor is.
+ *
+ * It lives in a first-party cookie on the registrable domain because localStorage
+ * is ORIGIN-scoped: docs, cloud and console each minted their own id for the same
+ * person, so one marketing → docs → signup → checkout journey arrived as several
+ * strangers — 463 anonymous identities carried 545 events in a week, about 1.2
+ * events each.
+ */
 export function anonId(): string | undefined {
-  const s = ls()
-  if (!s) return undefined
-  let v = s.getItem(KEY.anon)
-  if (!v) {
-    v = uuidv7()
-    s.setItem(KEY.anon, v)
-  }
-  return v
+  return hzAnonId() || undefined // '' during SSR / prerender
 }
 
 interface SessionState {

package/src/uid.ts

@@ -1,5 +1,11 @@
 // The ONE id minter for this client — UUIDv7 (RFC 9562 §5.7).
 //
+// The implementation is `hzUuidv7` in ./anon.js and this file only re-exports it.
+// It lives there because the anonymous-id chain has to mint too, and that chain is
+// inlined verbatim by two distributions that have no bundler (hz.js, and the tag
+// the door hosts) — a minter here as well would be a second implementation, and
+// the version nibble it produces is exactly the thing that must never diverge.
+//
 // 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
@@ -21,22 +27,8 @@
 // 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
-}
+// dropped by the same gate, so the fallback failed exactly like v4 did. Only the
+// ENTROPY degrades without crypto; the shape is always a valid v7 UUID.
 
 /**
  * uuidv7 mints a time-ordered UUIDv7 for `now` (epoch milliseconds).
@@ -44,25 +36,7 @@ function fill(b: Uint8Array): Uint8Array {
  * 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]]
-  )
-}
+export { hzUuidv7 as uuidv7 } from './anon.js'
 
 /** The millisecond timestamp a v7 id was minted at — the inverse of uuidv7. */
 export function uuidv7Time(id: string): number {

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.13'
+export const VERSION = '0.3.15'