@hanzo/event 0.3.13 → 0.3.14

package/src/storage.test.ts

@@ -0,0 +1,257 @@
+// 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('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,6 +1,9 @@
 // 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, so it lives in a
+// cookie on the registrable domain; everything else here stays origin-local.
 
 import type { Attribution, Cohort } from './types'
 import { uuidv7 } from './uid'
@@ -15,6 +18,14 @@ 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
@@ -24,16 +35,98 @@ function ls(): Storage | undefined {
   }
 }
 
-/** Stable anonymous id, minted once per browser and reused across sessions. */
+/** 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.
+ *
+ * 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.
+ */
 export function anonId(): string | undefined {
+  if (typeof window === 'undefined') return undefined // SSR / prerender
   const s = ls()
-  if (!s) return undefined
-  let v = s.getItem(KEY.anon)
-  if (!v) {
-    v = uuidv7()
-    s.setItem(KEY.anon, v)
+  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 v
+  return id
 }
 
 interface SessionState {

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.14'