@hanzo/event 0.3.14 → 0.3.16

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

@@ -113,6 +113,34 @@ describe('anonId', () => {
     }
   })
 
+  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.

package/src/storage.ts

@@ -2,14 +2,15 @@
 // 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, so it lives in a
-// cookie on the registrable domain; everything else here stays origin-local.
+// 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',
@@ -18,14 +19,6 @@ const KEY = {
 /** 30-minute inactivity window defines a session (PostHog/GA convention). */
 const SESSION_TTL_MS = 30 * 60 * 1000
 
-/** The registrable domain the anon cookie is scoped to, so docs, cloud, console,
- *  studio, pay, id and www all read the ONE id. */
-const ANON_DOMAIN = 'hanzo.ai'
-
-/** Two years, refreshed on every read — the cookie rolls forward with the visitor
- *  instead of expiring a fixed two years after first touch. */
-const ANON_MAX_AGE_S = 2 * 365 * 24 * 60 * 60
-
 function ls(): Storage | undefined {
   try {
     if (typeof window === 'undefined' || !window.localStorage) return undefined
@@ -35,98 +28,20 @@ function ls(): Storage | undefined {
   }
 }
 
-/** The cookie jar, or undefined wherever there is no document to read one from. */
-function jar(): Document | undefined {
-  try {
-    if (typeof document === 'undefined' || typeof document.cookie !== 'string') return undefined
-    return document
-  } catch {
-    return undefined // sandboxed frame with an opaque origin
-  }
-}
-
-function getCookie(name: string): string | undefined {
-  const d = jar()
-  if (!d) return undefined
-  for (const part of d.cookie.split(';')) {
-    const eq = part.indexOf('=')
-    if (eq < 0 || part.slice(0, eq).trim() !== name) continue
-    const v = part.slice(eq + 1).trim()
-    if (!v) continue
-    try {
-      return decodeURIComponent(v)
-    } catch {
-      return v // not percent-encoded — take it as written
-    }
-  }
-  return undefined
-}
-
-function setCookie(name: string, value: string): void {
-  const d = jar()
-  if (!d) return
-  let host = ''
-  let secure = false
-  try {
-    if (typeof window !== 'undefined' && window.location) {
-      host = window.location.hostname || ''
-      // A Secure cookie is refused outright by a non-secure origin, which would
-      // strand http://localhost dev on the localStorage path.
-      secure = window.location.protocol === 'https:'
-    }
-  } catch {
-    /* location unreachable — write a host-only, non-secure cookie */
-  }
-  const attrs = [
-    // encodeURIComponent leaves a UUID byte-identical while making any value that
-    // is not one unable to forge a `;` and inject an attribute.
-    `${name}=${encodeURIComponent(value)}`,
-    'Path=/',
-    `Max-Age=${ANON_MAX_AGE_S}`,
-    'SameSite=Lax',
-  ]
-  // Off hanzo.ai (localhost, previews, other registrable domains) the attribute
-  // would be rejected and the cookie dropped, so the cookie stays host-only there.
-  if (host === ANON_DOMAIN || host.endsWith(`.${ANON_DOMAIN}`)) attrs.push(`Domain=${ANON_DOMAIN}`)
-  if (secure) attrs.push('Secure')
-  try {
-    d.cookie = attrs.join('; ')
-  } catch {
-    /* cookies refused — localStorage still carries the id */
-  }
-}
-
-/** Last resort for a browser that refuses cookies AND localStorage: without it
- *  every event in a page load would mint its own id. */
-let memAnon: string | undefined
-
 /**
- * Stable anonymous id, shared by every *.hanzo.ai surface.
- *
- * 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.
+ * 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.
  *
- * Resolution is strictly ADDITIVE: cookie, else the localStorage id this package
- * has always written (ADOPTED into the cookie, never minted over — minting there
- * would reset every returning visitor and detach their history), else mint.
- * localStorage keeps being written, so a rollback finds everyone where it left
- * them.
+ * 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 {
-  if (typeof window === 'undefined') return undefined // SSR / prerender
-  const s = ls()
-  const id = getCookie(KEY.anon) || s?.getItem(KEY.anon) || memAnon || uuidv7()
-  memAnon = id
-  setCookie(KEY.anon, id)
-  try {
-    if (s && s.getItem(KEY.anon) !== id) s.setItem(KEY.anon, id)
-  } catch {
-    /* quota exhausted, or a private-mode jar that reads but refuses writes */
-  }
-  return id
+  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.14'
+export const VERSION = '0.3.16'