@hanzo/event 0.3.42 → 0.3.43

package/dist/storage.d.ts

@@ -21,6 +21,12 @@ export declare function anonId(): string | undefined;
  * and the recorded `last` from disagreeing.
  */
 export declare function sessionId(now?: number): string | undefined;
+/** Make `id` the current session, as if it had begun now. The session a link
+ *  carries is the one the visitor is already in, so the journey stays one session
+ *  across the hop instead of splitting at the host boundary. */
+export declare function adoptSession(id: string, now?: number): void;
+/** Make `id` the browser's anonymous id, replacing the one it held. */
+export declare function adoptAnonId(id: string): void;
 /** Read the persisted first-touch attribution. */
 export declare function getFirstTouch(): Attribution | undefined;
 /** Persist first-touch attribution ONCE — never overwrite an existing record. */

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAqBlD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;AAOD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAgB9D;AAED,kDAAkD;AAClD,wBAAgB,aAAa,IAAI,WAAW,GAAG,SAAS,CASvD;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAM7D;AAED,wCAAwC;AACxC,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAS9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAqBlD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;AAOD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAgB9D;AAED;;gEAEgE;AAChE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,IAAI,CAG/D;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,kDAAkD;AAClD,wBAAgB,aAAa,IAAI,WAAW,GAAG,SAAS,CASvD;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAM7D;AAED,wCAAwC;AACxC,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAS9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.42",
+  "version": "0.3.43",
   "description": "Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/anon.d.ts

@@ -12,3 +12,6 @@ export declare function hzUuidv7(now?: number): string
  * every existing id is adopted, and only a browser holding none is given a new one.
  */
 export declare function hzAnonId(): string
+
+/** Makes `id` this browser's anonymous id, replacing the one it held. */
+export declare function hzAnonAdopt(id: string): void

package/src/anon.js

@@ -214,6 +214,24 @@ function hzAnonId() {
   return id
 }
 
+/**
+ * hzAnonAdopt makes `id` this browser's anonymous id, replacing whatever it held.
+ *
+ * A visitor who followed a link from another Hanzo host arrives carrying the id that
+ * host minted; keeping the local one splits one journey into two strangers. The
+ * caller has already checked the shape.
+ */
+function hzAnonAdopt(id) {
+  hzAnonMemo = id
+  hzAnonWrite(HZ_ANON_KEY, id)
+  try {
+    var s = hzAnonStore()
+    if (s) s.setItem(HZ_ANON_KEY, id)
+  } catch (e) {
+    /* quota exhausted or a read-only jar — the cookie and memo still carry it */
+  }
+}
+
 /* ── END hz anon chain ─────────────────────────────────────────────────────── */
 
-export { hzAnonId, hzUuidv7 }
+export { hzAnonId, hzAnonAdopt, hzUuidv7 }

package/src/core.ts

@@ -58,6 +58,8 @@ import {
   type ErrorIdentity,
 } from './sentry'
 import {
+  adoptAnonId,
+  adoptSession,
   anonId,
   sessionId,
   getFirstTouch,
@@ -66,6 +68,7 @@ import {
   mergeCohort,
 } from './storage'
 import { uuidv7 } from './uid'
+import { linkUrl, readLink, stripLink } from './link'
 import type {
   AnalyticsConfig,
   Attribution,
@@ -349,10 +352,26 @@ export class Analytics {
     this.started = true
     if (!isBrowser()) return
 
+    // A link from another Hanzo host carries the visitor with it. Adopt it FIRST, so
+    // the first pageview is already the same person, session and first touch.
+    const linked = readLink(window.location.search)
+    if (linked.anonId) adoptAnonId(linked.anonId)
+    if (linked.sessionId) adoptSession(linked.sessionId)
+    const clean = stripLink(window.location.href)
+    if (clean !== undefined) {
+      try {
+        window.history.replaceState(window.history.state, '', clean)
+      } catch {
+        /* a sandboxed frame may refuse; the params are then simply visible */
+      }
+    }
+
     const parsed = parseAttribution(window.location.search, document.referrer)
-    this.attribution = hasAttribution(parsed)
-      ? setFirstTouchOnce(parsed)
-      : getFirstTouch() ?? parsed
+    // The first touch the link carries is the visit's real origin. Without it this
+    // host's own "first touch" would be the referring Hanzo page, which says nothing.
+    const first = linked.firstTouch && !getFirstTouch() ? setFirstTouchOnce(linked.firstTouch) : undefined
+    this.attribution =
+      first ?? (hasAttribution(parsed) ? setFirstTouchOnce(parsed) : getFirstTouch() ?? parsed)
     this.cohort = mergeCohort({
       channel: this.attribution.channel ?? deriveChannel(this.attribution),
       refCode: this.attribution.refCode,
@@ -378,6 +397,29 @@ export class Analytics {
     }
   }
 
+  /** link returns `url` carrying this visitor's anonymous id, session and first
+   *  touch when the destination is a Hanzo-owned host, so the journey continues
+   *  across the hop. Any other URL comes back unchanged. */
+  link(url: string): string {
+    if (!isBrowser()) return url
+    if (!this.started) this.init()
+    return linkUrl(
+      url,
+      { anonId: anonId(), sessionId: sessionId(), firstTouch: this.attribution },
+      window.location.hostname,
+      window.location.href,
+    )
+  }
+
+  /** authorize decorates an OAuth authorize URL for the redirect to IAM and flushes
+   *  what is queued, because the page is about to unload. Assign the result to
+   *  `location`. */
+  authorize(url: string): string {
+    const out = this.link(url)
+    this.flush(true)
+    return out
+  }
+
   /** identify binds the current visitor to a stable person id (post-login). */
   identify(personId: string, traits?: Record<string, unknown>): void {
     this.personId = personId

package/src/index.ts

@@ -17,6 +17,8 @@ export {
 } from './core'
 export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
 export { uuidv7, uuidv7Time } from './uid'
+export { linkUrl, readLink, stripLink, LINK_PARAMS } from './link'
+export type { LinkState } from './link'
 export { PRODUCT_PROJECT, dsnForProduct } from './dsn'
 export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'

package/src/link.test.ts

@@ -0,0 +1,222 @@
+// Cross-domain continuity: a link between Hanzo hosts carries the visitor, the
+// destination adopts it before its first pageview and cleans the address bar.
+
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { linkUrl, readLink, stripLink, encodeFirstTouch } from './link'
+import { keyFor, keyForPage } from './org'
+import type { Attribution, Transport, WireEvent } from './types'
+
+const AID = '01920000-0000-7000-8000-0000000000aa'
+const SID = '01920000-0000-7000-8000-0000000000bb'
+const LOCAL = '01920000-0000-7000-8000-0000000000cc'
+const FT: Attribution = {
+  utm: { source: 'x', medium: 'cpc', campaign: 'launch' },
+  refCode: 'r1',
+  referrer: 'https://t.co/abc',
+  channel: 'paid',
+}
+
+const g = globalThis as Record<string, unknown>
+
+function browser(href: string, storage: Record<string, string> = {}) {
+  const url = new URL(href)
+  const store = new Map(Object.entries(storage))
+  const jar = new Map<string, string>()
+  const replaced: string[] = []
+  const location = {
+    href: url.href,
+    hostname: url.hostname,
+    protocol: url.protocol,
+    pathname: url.pathname,
+    search: url.search,
+  }
+  g.window = {
+    location,
+    history: {
+      state: null,
+      replaceState: (_s: unknown, _t: string, next: string) => {
+        replaced.push(next)
+        const u = new URL(next, url)
+        location.href = u.href
+        location.search = u.search
+      },
+    },
+    localStorage: {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => void store.set(k, v),
+    },
+    addEventListener: () => {},
+  }
+  g.document = {
+    get cookie() {
+      return [...jar].map(([k, v]) => `${k}=${v}`).join('; ')
+    },
+    set cookie(raw: string) {
+      const kv = raw.split(';')[0]
+      const eq = kv.indexOf('=')
+      jar.set(kv.slice(0, eq).trim(), kv.slice(eq + 1))
+    },
+    referrer: 'https://hanzo.ai/',
+    visibilityState: 'visible',
+  }
+  return { store, jar, replaced, location }
+}
+
+class Tx implements Transport {
+  all: WireEvent[] = []
+  send(_u: string, body: string) {
+    try {
+      this.all.push(...(JSON.parse(body) as { batch: WireEvent[] }).batch)
+    } catch {
+      /* not JSON */
+    }
+  }
+}
+
+const load = async () => {
+  vi.resetModules()
+  return await import('./core')
+}
+
+afterEach(() => {
+  delete g.window
+  delete g.document
+})
+
+describe('linkUrl', () => {
+  const state = { anonId: AID, sessionId: SID, firstTouch: FT }
+
+  it('appends id, session and first touch for Hanzo-owned hosts', () => {
+    for (const host of ['hanzo.id', 'hanzo.app', 'hanzo.team', 'hanzo.bot', 'id.lux.network', 'zoo.ngo']) {
+      const u = new URL(linkUrl(`https://${host}/login`, state, 'hanzo.ai'))
+      expect(u.searchParams.get('hz_aid')).toBe(AID)
+      expect(u.searchParams.get('hz_sid')).toBe(SID)
+      expect(readLink(u.search).firstTouch).toEqual(FT)
+    }
+  })
+
+  it('leaves foreign hosts and same-host links alone', () => {
+    expect(linkUrl('https://example.com/x', state, 'hanzo.ai')).toBe('https://example.com/x')
+    expect(linkUrl('https://hanzo.ai/x', state, 'hanzo.ai')).toBe('https://hanzo.ai/x')
+    expect(linkUrl('mailto:z@hanzo.ai', state, 'hanzo.ai')).toBe('mailto:z@hanzo.ai')
+    expect(linkUrl('https://evilhanzo.id/x', state, 'hanzo.ai')).toBe('https://evilhanzo.id/x')
+  })
+
+  it('keeps existing query and hash, and refuses a non-UUID id', () => {
+    const out = linkUrl('https://hanzo.id/login/oauth/authorize?client_id=a&x=1#h', { anonId: 'nope' }, 'hanzo.ai')
+    expect(out).toBe('https://hanzo.id/login/oauth/authorize?client_id=a&x=1#h')
+    const ok = new URL(linkUrl('https://hanzo.id/a?client_id=a#h', state, 'hanzo.ai'))
+    expect(ok.searchParams.get('client_id')).toBe('a')
+    expect(ok.hash).toBe('#h')
+  })
+
+  it('round-trips first touch and rejects garbage', () => {
+    expect(readLink('?hz_ft=' + encodeURIComponent(encodeFirstTouch(FT))).firstTouch).toEqual(FT)
+    expect(readLink('?hz_ft=%5B1%5D&hz_aid=zzz').firstTouch).toBeUndefined()
+    expect(readLink('?hz_aid=zzz').anonId).toBeUndefined()
+  })
+
+  it('stripLink removes only its own params', () => {
+    expect(stripLink(`https://hanzo.id/a?hz_aid=${AID}&keep=1&hz_sid=${SID}#f`)).toBe('/a?keep=1#f')
+    expect(stripLink('https://hanzo.id/a?keep=1')).toBeUndefined()
+  })
+})
+
+describe('Analytics adopts a link on init', () => {
+  const href = `https://hanzo.id/login?client_id=c&hz_aid=${AID}&hz_sid=${SID}&hz_ft=${encodeURIComponent(encodeFirstTouch(FT))}`
+
+  it('first pageview carries the linked ids, first touch and a clean address bar', async () => {
+    const b = browser(href, { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.pageview()
+    a.flush()
+    const e = tx.all[0]
+    expect(e.anonymousId).toBe(AID)
+    expect(e.sessionId).toBe(SID)
+    expect(e.channel).toBe('paid')
+    expect(e.utm?.campaign).toBe('launch')
+    expect(e.url).not.toContain('hz_aid')
+    expect(b.replaced).toEqual(['/login?client_id=c'])
+    expect(b.location.search).toBe('?client_id=c')
+    expect(b.jar.get('iam-anon-id')).toBe(AID)
+    expect(b.store.get('iam-anon-id')).toBe(AID)
+  })
+
+  it('an existing first touch is not overwritten by a link', async () => {
+    browser(href, { hz_first_touch: JSON.stringify({ utm: { source: 'old' }, channel: 'organic' }) })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.pageview()
+    a.flush()
+    expect(tx.all[0].utm?.source).toBe('old')
+    expect(tx.all[0].anonymousId).toBe(AID)
+  })
+
+  it('a link with a bad id changes nothing but is still stripped', async () => {
+    const b = browser('https://hanzo.id/x?hz_aid=evil', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    new Analytics({ product: 't', host: '', transport: tx }).pageview()
+    expect(b.replaced).toEqual(['/x'])
+    expect(b.store.get('iam-anon-id')).toBe(LOCAL)
+  })
+})
+
+describe('Analytics.link / authorize / identify', () => {
+  it('link decorates an IAM authorize URL with the current visitor', async () => {
+    browser('https://hanzo.ai/chat?utm_source=news', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const a = new Analytics({ product: 't', host: '', transport: new Tx() })
+    const u = new URL(a.link('https://hanzo.id/login/oauth/authorize?client_id=c&state=s'))
+    expect(u.searchParams.get('client_id')).toBe('c')
+    expect(u.searchParams.get('hz_aid')).toBe(LOCAL)
+    expect(u.searchParams.get('hz_sid')).toMatch(/^[0-9a-f-]{36}$/)
+    expect(readLink(u.search).firstTouch?.utm.source).toBe('news')
+    expect(a.link('https://example.com/x')).toBe('https://example.com/x')
+  })
+
+  it('authorize decorates and flushes what is queued before unload', async () => {
+    browser('https://hanzo.ai/chat', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx, flushIntervalMs: 999999 })
+    a.capture('chat_started')
+    const out = a.authorize('https://hanzo.id/login/oauth/authorize?client_id=c')
+    expect(out).toContain('hz_aid=' + LOCAL)
+    expect(tx.all.map((e) => e.event)).toEqual(['chat_started'])
+  })
+
+  it('identify emits the anonymous id and the person id together', async () => {
+    browser('https://hanzo.ai/', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.identify('person-1')
+    a.flush()
+    const e = tx.all[0]
+    expect(e.type).toBe('identify')
+    expect(e.anonymousId).toBe(LOCAL)
+    expect(e.personId).toBe('person-1')
+    expect(e.distinctId).toBe('person-1')
+  })
+})
+
+describe('one ingest key across the journey', () => {
+  it('hanzo.ai, hanzo.id, hanzo.app resolve to the same org key', () => {
+    const k = keyFor('hanzo.ai')
+    expect(k).toBeTruthy()
+    for (const h of ['www.hanzo.ai', 'hanzo.id', 'hanzo.app', 'hanzo.team', 'hanzo.bot']) expect(keyFor(h)).toBe(k)
+    const ring = { hanzo: 'pk-runtime' }
+    expect(keyFor('hanzo.id', ring)).toBe(keyFor('hanzo.ai', ring))
+  })
+
+  it('keyForPage on either host names the same project', () => {
+    browser('https://hanzo.id/login')
+    const id = keyForPage()
+    browser('https://hanzo.ai/')
+    expect(keyForPage()).toBe(id)
+  })
+})

package/src/link.ts

@@ -0,0 +1,103 @@
+// Cross-domain visitor continuity.
+//
+// Cookies and localStorage stop at the registrable domain, so a visitor who goes
+// hanzo.ai -> hanzo.id (sign-in) -> back arrived as separate people on each host, and
+// the journey across the sign-in redirect could not be read. A link between two
+// Hanzo hosts therefore carries the visitor's identity in three short query
+// parameters, and the destination adopts them before its first pageview and
+// removes them from the address bar.
+//
+//   hz_aid  anonymous id      hz_sid  session id      hz_ft  first-touch attribution
+//
+// They are appended ONLY when the destination host belongs to a brand in ORG_DOMAIN:
+// an id handed to a host outside the table would be handed to a stranger.
+
+import { orgOf } from './org'
+import type { Attribution } from './types'
+
+export const LINK_PARAMS = { anon: 'hz_aid', session: 'hz_sid', firstTouch: 'hz_ft' } as const
+
+/** Ids are v7 UUIDs; anything else in a URL is someone else's input and is refused. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export const isId = (v: string | null | undefined): v is string => !!v && UUID.test(v)
+
+/** What a link carries. Any field may be absent. */
+export interface LinkState {
+  anonId?: string
+  sessionId?: string
+  firstTouch?: Attribution
+}
+
+/** First touch as a compact tuple: utm source, medium, campaign, term, content, refCode,
+ *  referrer, channel. Short because it rides a URL; a tuple because keys cost bytes. */
+export function encodeFirstTouch(a: Attribution): string {
+  return JSON.stringify([
+    a.utm.source, a.utm.medium, a.utm.campaign, a.utm.term, a.utm.content,
+    a.refCode, a.referrer, a.channel,
+  ].map((v) => v ?? ''))
+}
+
+export function decodeFirstTouch(raw: string | null | undefined): Attribution | undefined {
+  if (!raw || raw.length > 1024) return undefined
+  try {
+    const t: unknown = JSON.parse(raw)
+    if (!Array.isArray(t) || t.length !== 8 || t.some((v) => typeof v !== 'string')) return undefined
+    const [source, medium, campaign, term, content, refCode, referrer, channel] = t as string[]
+    const u = (v: string) => v || undefined
+    return {
+      utm: { source: u(source), medium: u(medium), campaign: u(campaign), term: u(term), content: u(content) },
+      refCode: u(refCode),
+      referrer: u(referrer),
+      channel: u(channel),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** linkUrl returns `url` with the visitor's identity appended when its host is
+ *  Hanzo-owned and is not `fromHost`; otherwise `url` unchanged. Relative URLs
+ *  resolve against `base`. Never throws. */
+export function linkUrl(url: string, state: LinkState, fromHost: string, base?: string): string {
+  let u: URL
+  try {
+    u = new URL(url, base)
+  } catch {
+    return url
+  }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return url
+  if (!orgOf(u.hostname) || u.hostname === fromHost) return url
+  const set = (k: string, v: string | undefined) => v && u.searchParams.set(k, v)
+  if (isId(state.anonId)) set(LINK_PARAMS.anon, state.anonId)
+  if (isId(state.sessionId)) set(LINK_PARAMS.session, state.sessionId)
+  if (state.firstTouch) set(LINK_PARAMS.firstTouch, encodeFirstTouch(state.firstTouch))
+  return u.toString()
+}
+
+/** readLink parses what a link carried out of a location.search value. Invalid
+ *  values are dropped, not repaired. */
+export function readLink(search: string): LinkState {
+  const q = new URLSearchParams(search || '')
+  const a = q.get(LINK_PARAMS.anon)
+  const s = q.get(LINK_PARAMS.session)
+  return {
+    anonId: isId(a) ? a : undefined,
+    sessionId: isId(s) ? s : undefined,
+    firstTouch: decodeFirstTouch(q.get(LINK_PARAMS.firstTouch)),
+  }
+}
+
+/** stripLink returns the path, query and hash of `href` without the link parameters, or
+ *  undefined when there were none. */
+export function stripLink(href: string): string | undefined {
+  const u = new URL(href)
+  let hit = false
+  for (const k of Object.values(LINK_PARAMS)) {
+    if (u.searchParams.has(k)) {
+      u.searchParams.delete(k)
+      hit = true
+    }
+  }
+  return hit ? u.pathname + u.search + u.hash : undefined
+}

package/src/storage.ts

@@ -6,7 +6,7 @@
 // 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 { hzAnonAdopt, hzAnonId } from './anon.js'
 import type { Attribution, Cohort } from './types'
 import { uuidv7 } from './uid'
 
@@ -75,6 +75,19 @@ export function sessionId(now = Date.now()): string | undefined {
   return state.id
 }
 
+/** Make `id` the current session, as if it had begun now. The session a link
+ *  carries is the one the visitor is already in, so the journey stays one session
+ *  across the hop instead of splitting at the host boundary. */
+export function adoptSession(id: string, now = Date.now()): void {
+  const s = ls()
+  if (s) s.setItem(KEY.session, JSON.stringify({ id, last: now }))
+}
+
+/** Make `id` the browser's anonymous id, replacing the one it held. */
+export function adoptAnonId(id: string): void {
+  hzAnonAdopt(id)
+}
+
 /** Read the persisted first-touch attribution. */
 export function getFirstTouch(): Attribution | undefined {
   const s = ls()