@hanzo/event 0.3.43 → 0.3.48

package/dist/tags.d.ts

@@ -0,0 +1,55 @@
+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[];
+}
+/**
+ * The publishable key of each site's project, which is how cloud finds the site's
+ * tag set. A `pk-` is public by design (it ships in every page); it names a site,
+ * never a platform id. A host absent here has no tag config unless `start` is
+ * given a key.
+ */
+export declare const SITE_KEY: Readonly<Record<string, 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.
+ *
+ * A paid order is stated by the SERVER on our stream (and forwarded server-side);
+ * its browser copy is `track(stream, 'order_completed', {event_id: order, order_id:
+ * order, …}, 'tags')`: the same id, the pixels only, so nothing counts twice.
+ */
+export declare function track(stream: Analytics | undefined, name: string, params?: Record<string, unknown>, 
+/** `'tags'` fires the browser pixels only: the server states this moment on our stream itself. */
+only?: 'tags'): 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;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUpD,CAAA;AAuNF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAE,UAAe,GAAG,MAAM,IAAI,CAmCpD;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;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;AACpC,kGAAkG;AAClG,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAsBN;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.43",
+  "version": "0.3.48",
   "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/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/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

@@ -25,6 +25,16 @@ 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, SITE_KEY } from './tags'
+export type { BrowserTag, TagOptions } from './tags'
+export { commerceItem, worth } from './items'
+export type { CommerceItem, PlanLine } from './items'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
 export { FUNNELS, PRODUCTS, eventsOf } from './funnels'

package/src/items.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { commerceItem, worth } from './items'
+
+describe('commerceItem', () => {
+  it('names an individual plan by its id, term and price', () => {
+    expect(commerceItem({ id: 'dev', name: 'Dev', interval: 'month', price: 19 })).toEqual({
+      item_id: 'dev', item_name: 'Dev', item_category: 'individual', item_variant: 'monthly', price: 19, quantity: 1,
+    })
+  })
+
+  it('names a team plan by its seats, and an annual term however commerce spells it', () => {
+    for (const interval of ['year', 'yearly', 'annual', 'Year']) {
+      const i = commerceItem({ id: 'team_standard', team: true, interval, price: 24, quantity: 3 })
+      expect(i).toMatchObject({ item_category: 'team', item_variant: 'annual', quantity: 3 })
+      expect(worth(i)).toBe(72)
+    }
+  })
+
+  it('a plan with no price is free, not unknown', () => {
+    expect(commerceItem({ id: 'free', interval: 'month', price: null }).price).toBe(0)
+  })
+})

package/src/items.ts

@@ -0,0 +1,44 @@
+// A plan as every ecommerce event names it: GA4's item shape, which the tag
+// manager hands Meta, TikTok and X, and which cloud's forwarder lifts from the
+// events the server states. One function, so a plan carries the same line from
+// the pricing page to the checkout to the order.
+//
+// `item_id` is the plan's id as the catalog spells it (free, dev, max, and the
+// team plans), `item_category` says who it is for, `item_variant` the term,
+// `price` the unit price for that term in US dollars and `quantity` the seats
+// (1 for an individual plan).
+
+export interface CommerceItem {
+  item_id: string
+  item_name?: string
+  item_category: 'individual' | 'team'
+  item_variant: 'monthly' | 'annual'
+  price: number
+  quantity: number
+}
+
+export interface PlanLine {
+  id: string
+  name?: string
+  /** A team plan is sold per seat. */
+  team?: boolean
+  /** The term, as commerce (`month`, `year`) or the funnel (`monthly`, `annual`) says it. */
+  interval: string
+  price: number | null
+  quantity?: number
+}
+
+export function commerceItem(p: PlanLine): CommerceItem {
+  const annual = /^(year|yearly|annual)$/i.test(p.interval)
+  return {
+    item_id: p.id,
+    ...(p.name ? { item_name: p.name } : {}),
+    item_category: p.team ? 'team' : 'individual',
+    item_variant: annual ? 'annual' : 'monthly',
+    price: p.price ?? 0,
+    quantity: p.quantity ?? 1,
+  }
+}
+
+/** What the whole order is worth: the unit price times the seats. */
+export const worth = (i: CommerceItem): number => i.price * i.quantity

package/src/react.tsx

@@ -16,11 +16,13 @@ import {
   useContext,
   useEffect,
   useRef,
+  useSyncExternalStore,
   type ErrorInfo,
   type ReactNode,
 } from 'react'
 import { Analytics, createAnalytics } from './core'
 import type { AnalyticsConfig } from './types'
+import { CONSENT_EVENT, read, render, type Choice } from './consent'
 
 const Ctx = createContext<Analytics | null>(null)
 
@@ -120,3 +122,23 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
     return fallback ?? null
   }
 }
+
+const listen = (on: () => void) => {
+  window.addEventListener(CONSENT_EVENT, on)
+  return () => window.removeEventListener(CONSENT_EVENT, on)
+}
+
+/**
+ * The visitor's consent, live: what a region presumes until they choose, then
+ * what they chose, re-rendering the moment they do. `enabled: choice.analytics`
+ * on the provider's config is how a stream that started silent for an EU visitor
+ * starts on Accept, with no reload.
+ */
+export function useConsent(): Choice {
+  const kept = useSyncExternalStore(listen, () => render(read()), () => '')
+  return {
+    analytics: kept.includes('analytics'),
+    marketing: kept.includes('marketing'),
+    ads: kept.includes('ads'),
+  }
+}