@hanzo/event 0.3.42 → 0.3.44

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/dist/tags.d.ts

@@ -0,0 +1,42 @@
+import type { Analytics } from './core';
+export interface BrowserTag {
+    platform: string;
+    type: string;
+    id: string;
+    events?: Record<string, string>;
+}
+export interface TagOptions {
+    /** The site's publishable key; resolves its tag set. */
+    key?: string;
+    /** The site's host, for a site whose key is the org's. */
+    host?: string;
+    /** cloud's origin; defaults to https://api.hanzo.ai. */
+    base?: string;
+    /** Domains one visit crosses, so GA4 keeps it one session. */
+    domains?: string[];
+}
+/**
+ * Starts the tag manager: fetches the site's tag set and loads what consent
+ * allows, again on every consent change. Safe to call on every page load, and
+ * a no-op on the server. Returns a function that stops listening.
+ */
+export declare function start(o?: TagOptions): () => void;
+/** The browser tags a moment can reach right now, as the `tags` property spells it. */
+export declare function reach(): string;
+/**
+ * Sends one moment to the browser tags named in `to`, under `id`. The names each
+ * platform knows it by are the table in @hanzo/events; a platform the table
+ * gives no name, or a rule-named platform with no rule for it, is not sent it.
+ */
+export declare function mirror(name: string, params: Record<string, unknown>, id: string, to?: string): void;
+/**
+ * One moment, to every place it is counted, under one event_id: our stream
+ * always hears it (with the consent, the click and the browser ids cloud
+ * forwards on), and each browser tag that is running hears it too. A moment
+ * that arrives while gtag.js is still on its way waits for it, so GA4 sees it
+ * with a session; a page that is leaving sends what it holds as things stand.
+ */
+export declare function track(stream: Analytics | undefined, name: string, params?: Record<string, unknown>): void;
+/** What cloud needs to forward a moment a page states itself, as if the browser had sent it. */
+export declare function visit(): Record<string, unknown>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAuND;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAE,UAAe,GAAG,MAAM,IAAI,CAiCpD;AAOD,uFAAuF;AACvF,wBAAgB,KAAK,IAAI,MAAM,CAc9B;AA+CD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,SAAU,GAAG,IAAI,CAiCpG;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI,CAmB7G;AAED,gGAAgG;AAChG,wBAAgB,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG/C"}

package/dist/touch.d.ts

@@ -0,0 +1,7 @@
+import type { Choice } from './consent';
+export declare const CLICK_IDS: readonly ['gclid', 'gbraid', 'wbraid', 'fbclid', 'li_fat_id', 'twclid', 'ttclid'];
+/** Records this page's click and the browser ids. Call once per page load. */
+export declare function capture(c: Choice): void;
+/** The properties an event carries for cloud to match it on. */
+export declare function touch(c: Choice): Record<string, string | number>;
+//# sourceMappingURL=touch.d.ts.map

package/dist/touch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"touch.d.ts","sourceRoot":"","sources":["../src/touch.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAGvC,eAAO,MAAM,SAAS,YAAI,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAM1G,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAiBvC;AAED,gEAAgE;AAChE,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAmBhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.42",
+  "version": "0.3.44",
   "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/",
@@ -75,7 +75,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@hanzo/events": "0.2.2"
+    "@hanzo/events": "0.3.1"
   },
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly --declaration --outDir dist && node ../../scripts/dts.mjs",

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/consent.test.ts

@@ -0,0 +1,140 @@
+// Consent: opt-in outside the US, opt-out inside it, GPC always wins.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { CONSENT_COOKIE, acceptAll, asks, read, region, rejectAll, save } from './consent'
+import { touch, capture } from './touch'
+
+const g = globalThis as Record<string, unknown>
+const original = {
+  navigator: Object.getOwnPropertyDescriptor(globalThis, 'navigator'),
+  Intl: Object.getOwnPropertyDescriptor(globalThis, 'Intl'),
+}
+const put = (k: string, value: unknown) => Object.defineProperty(globalThis, k, { value, configurable: true, writable: true })
+
+function browser(zone: string, opts: { gpc?: boolean; cookie?: string; href?: string } = {}) {
+  const jar = new Map<string, string>()
+  if (opts.cookie !== undefined) jar.set(CONSENT_COOKIE, opts.cookie)
+  const fired: string[] = []
+  const url = new URL(opts.href ?? 'https://hanzo.ai/')
+  g.window = {
+    location: { hostname: url.hostname, protocol: url.protocol, search: url.search, href: url.href },
+    dispatchEvent: (e: { type: string }) => void fired.push(e.type),
+  }
+  g.Event = class {
+    constructor(public type: string) {}
+  }
+  put('navigator', { globalPrivacyControl: opts.gpc === true })
+  put('Intl', { DateTimeFormat: () => ({ resolvedOptions: () => ({ timeZone: zone }) }) })
+  g.document = {
+    get cookie() {
+      return [...jar].map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('; ')
+    },
+    set cookie(line: string) {
+      const [pair] = line.split(';')
+      const i = pair.indexOf('=')
+      const name = pair.slice(0, i)
+      const value = decodeURIComponent(pair.slice(i + 1))
+      if (/Max-Age=0/.test(line)) jar.delete(name)
+      else jar.set(name, value)
+    },
+  }
+  return { jar, fired }
+}
+
+afterEach(() => {
+  for (const k of ['window', 'document', 'Event']) delete g[k]
+  for (const [k, d] of Object.entries(original)) if (d) Object.defineProperty(globalThis, k, d)
+  vi.restoreAllMocks()
+})
+
+describe('region', () => {
+  it.each([
+    ['Europe/Berlin', 'opt-in'],
+    ['Europe/London', 'opt-in'],
+    ['Europe/Zurich', 'opt-in'],
+    ['Asia/Tokyo', 'opt-in'],
+    ['America/New_York', 'opt-out'],
+    ['America/Los_Angeles', 'opt-out'],
+    ['America/Indiana/Indianapolis', 'opt-out'],
+    ['Pacific/Honolulu', 'opt-out'],
+    ['', 'opt-in'],
+  ])('%s is %s', (zone, want) => {
+    browser(zone)
+    expect(region()).toBe(want)
+  })
+})
+
+describe('the default before a choice', () => {
+  it('allows nothing in the EU and asks', () => {
+    browser('Europe/Paris')
+    expect(read()).toEqual({ analytics: false, marketing: false, ads: false })
+    expect(asks()).toBe(true)
+  })
+
+  it('allows everything in the US and does not ask', () => {
+    browser('America/Chicago')
+    expect(read()).toEqual({ analytics: true, marketing: true, ads: true })
+    expect(asks()).toBe(false)
+  })
+
+  it('Global Privacy Control turns marketing off in the US', () => {
+    browser('America/Denver', { gpc: true })
+    expect(read()).toEqual({ analytics: false, marketing: false, ads: false })
+  })
+
+  it('GPC wins over a stored yes', () => {
+    browser('America/Denver', { gpc: true, cookie: 'analytics,marketing,ads' })
+    expect(read()).toEqual({ analytics: true, marketing: false, ads: false })
+  })
+})
+
+describe('a stored choice', () => {
+  it('is what is read, and stops the asking', () => {
+    browser('Europe/Paris', { cookie: 'analytics' })
+    expect(read()).toEqual({ analytics: true, marketing: false, ads: false })
+    expect(asks()).toBe(false)
+  })
+
+  it('accepting stores all three and tells the page', () => {
+    const b = browser('Europe/Paris')
+    acceptAll()
+    expect(b.jar.get(CONSENT_COOKIE)).toBe('analytics,marketing,ads')
+    expect(b.fired).toEqual(['hzconsent'])
+    expect(read()).toEqual({ analytics: true, marketing: true, ads: true })
+  })
+
+  it('rejecting stores an empty choice, which is a choice', () => {
+    const b = browser('America/New_York')
+    rejectAll()
+    expect(b.jar.get(CONSENT_COOKIE)).toBe('')
+    expect(read()).toEqual({ analytics: false, marketing: false, ads: false })
+  })
+
+  it('saving marketing under GPC stores none', () => {
+    const b = browser('Europe/Paris', { gpc: true })
+    save({ analytics: true, marketing: true, ads: true })
+    expect(b.jar.get(CONSENT_COOKIE)).toBe('analytics')
+  })
+})
+
+describe('click ids', () => {
+  const href = (q: string) => `https://hanzo.ai/?${q}`
+
+  it('keeps every platform click id and builds _fbc from fbclid', () => {
+    const b = browser('America/New_York', {
+      href: href('gclid=G1&gbraid=GB&wbraid=WB&fbclid=F1&li_fat_id=L1&twclid=T1&ttclid=K1'),
+    })
+    capture({ analytics: true, marketing: true, ads: true })
+    const t = touch({ analytics: true, marketing: true, ads: true })
+    expect(t).toMatchObject({ gclid: 'G1', gbraid: 'GB', wbraid: 'WB', fbclid: 'F1', li_fat_id: 'L1', twclid: 'T1', ttclid: 'K1' })
+    expect(String(t.fbc)).toMatch(/^fb\.1\.\d+\.F1$/)
+    expect(b.jar.get('hz_touch')).toContain('ttclid')
+  })
+
+  it('stores no click without marketing consent', () => {
+    const b = browser('Europe/Paris', { href: href('gclid=G1') })
+    capture({ analytics: true, marketing: false, ads: false })
+    expect(b.jar.has('hz_touch')).toBe(false)
+    expect(touch({ analytics: true, marketing: false, ads: false })).not.toHaveProperty('gclid')
+  })
+})

package/src/consent.ts

@@ -0,0 +1,116 @@
+// Cookie consent: what a visitor lets a site measure and share, and the rule for
+// what a visitor who has not chosen is presumed to allow.
+//
+// Three categories. Analytics is our own stream and GA4. Marketing is the ad
+// platforms measuring the conversions they bought (Google Ads, Meta, LinkedIn,
+// X, TikTok) and every server-side send. Ads is those platforms using the visit
+// for audiences; off, Google's ad_personalization is denied and Meta runs under
+// Limited Data Use.
+//
+// THE DEFAULT depends on where the visitor is. In the EU, UK and Switzerland,
+// and anywhere else that is not a US state, nothing is allowed until they say
+// so: a visitor with no stored choice has allowed nothing. In the US the default
+// is on and the choice is an opt-out ("Do not sell or share my personal
+// information"). Global Privacy Control, and Do Not Track, turn marketing and
+// ads off in every region whatever is stored: California reads GPC as the opt-out
+// of sale and sharing.
+//
+// There is no geo lookup. The page cannot ask a server where the visitor is, so
+// the zone is the browser's own time zone, and a zone that is not a US zone is
+// treated as opt-in. Wrong in the safe direction: a US visitor on a foreign
+// clock is asked, and a European is never presumed to have agreed.
+//
+// The choice is a first-party cookie, `hz_consent`, on the registrable domain
+// for 13 months: the granted categories, comma separated. cloud reads the same
+// string off each event's `consent` property.
+
+import { get, set } from './cookie'
+
+export const CONSENT_COOKIE = 'hz_consent'
+
+/** Fired on `window` whenever a choice is stored. */
+export const CONSENT_EVENT = 'hzconsent'
+
+export interface Choice {
+  analytics: boolean
+  marketing: boolean
+  ads: boolean
+}
+
+export type Region = 'opt-in' | 'opt-out'
+
+type Nav = { doNotTrack?: string; msDoNotTrack?: string; globalPrivacyControl?: boolean }
+
+const US =
+  /^(America\/(New_York|Chicago|Denver|Los_Angeles|Phoenix|Anchorage|Adak|Boise|Detroit|Juneau|Sitka|Nome|Yakutat|Menominee|Metlakatla|Indiana\/.*|Kentucky\/.*|North_Dakota\/.*)|Pacific\/Honolulu|US\/.*)$/
+
+/** Whether the browser sends Global Privacy Control. */
+export function gpc(): boolean {
+  if (typeof navigator === 'undefined') return false
+  return (navigator as unknown as Nav).globalPrivacyControl === true
+}
+
+/** Whether the browser sends Global Privacy Control or Do Not Track. */
+export function refused(): boolean {
+  if (typeof window === 'undefined') return false
+  const n = navigator as unknown as Nav
+  const dnt = n.doNotTrack ?? (window as unknown as Nav).doNotTrack ?? n.msDoNotTrack
+  return gpc() || dnt === '1' || dnt === 'yes'
+}
+
+/** Which rule applies to this visitor. */
+export function region(): Region {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone ?? ''
+    return US.test(zone) ? 'opt-out' : 'opt-in'
+  } catch {
+    return 'opt-in'
+  }
+}
+
+/** Whether the visitor has stored a choice. */
+export function stored(): boolean {
+  return get(CONSENT_COOKIE) !== undefined
+}
+
+/** The visitor's choice: the stored one, else the regional default, with GPC applied. */
+export function read(): Choice {
+  const kept = get(CONSENT_COOKIE)
+  const on =
+    kept !== undefined
+      ? kept.split(',')
+      : region() === 'opt-in' || refused()
+        ? []
+        : ['analytics', 'marketing', 'ads']
+  const has = (k: string) => on.includes(k)
+  return { analytics: has('analytics'), marketing: has('marketing') && !gpc(), ads: has('ads') && !gpc() }
+}
+
+/** Whether the consent banner must be shown: an opt-in visitor who has not chosen. */
+export function asks(): boolean {
+  return typeof document !== 'undefined' && region() === 'opt-in' && !stored()
+}
+
+/** The choice as the `consent` property and the cookie spell it. */
+export function render(c: Choice): string {
+  return (['analytics', 'marketing', 'ads'] as const).filter((k) => c[k]).join(',')
+}
+
+/**
+ * Stores a choice and tells the page. The tags react without a reload: a
+ * category just allowed loads its libraries, and Google's consent state is
+ * updated. An ad library already running cannot be unloaded, so a choice that
+ * withdraws marketing takes effect for what has not loaded yet and for every
+ * later page.
+ */
+export function save(c: Choice): void {
+  const out: Choice = { analytics: c.analytics, marketing: c.marketing && !gpc(), ads: c.ads && !gpc() }
+  set(CONSENT_COOKIE, render(out), 395)
+  if (typeof window !== 'undefined') window.dispatchEvent(new Event(CONSENT_EVENT))
+}
+
+/** Accept every category. */
+export const acceptAll = (): void => save({ analytics: true, marketing: true, ads: true })
+
+/** Refuse every optional category. */
+export const rejectAll = (): void => save({ analytics: false, marketing: false, ads: false })

package/src/cookie.ts

@@ -0,0 +1,28 @@
+// First-party cookies for consent, the ad click and the browser ids the ad
+// platforms match on. Set on the registrable domain so every subdomain of a site
+// reads the same choice and the same click; on localhost or an address it stays
+// on the host.
+
+const DAY = 86_400
+
+/** The domain attribute for this host, or '' to keep the cookie on the host. */
+function domain(): string {
+  const h = window.location.hostname
+  if (h === 'localhost' || /^[\d.]+$/.test(h) || h.includes(':')) return ''
+  const parts = h.split('.')
+  return parts.length > 2 ? `; Domain=.${parts.slice(-2).join('.')}` : `; Domain=.${h}`
+}
+
+/** Reads one cookie, or undefined. */
+export function get(name: string): string | undefined {
+  if (typeof document === 'undefined') return undefined
+  const hit = document.cookie.split('; ').find((c) => c.startsWith(`${name}=`))
+  return hit ? decodeURIComponent(hit.slice(name.length + 1)) : undefined
+}
+
+/** Writes one cookie for `days`. */
+export function set(name: string, value: string, days: number): void {
+  if (typeof document === 'undefined') return
+  const secure = window.location.protocol === 'https:' ? '; Secure' : ''
+  document.cookie = `${name}=${encodeURIComponent(value)}; Max-Age=${days * DAY}; Path=/; SameSite=Lax${domain()}${secure}`
+}

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/events.ts

@@ -17,5 +17,5 @@
  * of the name, one name per user-visible moment shared by every surface.
  */
 
-export { EVENTS, PAGEVIEW, EXCEPTION } from '@hanzo/events'
+export { EVENTS, PAGEVIEW, EXCEPTION, PLATFORMS, namesOn } from '@hanzo/events'
 export type { EventName } from '@hanzo/events'

package/src/index.ts

@@ -17,12 +17,22 @@ 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'
 export { EVENTS, EXCEPTION, PAGEVIEW } from './events'
 export { exceptionEntry, exceptionProperties, fingerprint, digest } from './exception'
 export type { EventName } from './events'
+export {
+  CONSENT_COOKIE, CONSENT_EVENT, acceptAll, asks, gpc, read as readConsent, refused, region,
+  rejectAll, render as renderConsent, save as saveConsent, stored as storedConsent,
+} from './consent'
+export type { Choice, Region } from './consent'
+export { CLICK_IDS, capture as captureClick, touch } from './touch'
+export { start as startTags, track, mirror, reach, visit } from './tags'
+export type { BrowserTag, TagOptions } from './tags'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
 export { FUNNELS, PRODUCTS, eventsOf } from './funnels'