@hanzo/event 0.3.26 → 0.3.28

package/hz.js

@@ -55,7 +55,7 @@
   }
 
   var LIB = 'hz.js'
-  var VERSION = '0.3.26'
+  var VERSION = '0.3.28'
   var host = (s.getAttribute('data-host') || 'https://api.hanzo.ai').replace(/\/+$/, '')
   var product = s.getAttribute('data-product') || location.hostname
   var capture = s.getAttribute('data-capture') !== '0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "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/core.ts

@@ -28,9 +28,11 @@
 //
 //   • cookie/session app (host:'')  — same-origin credentials ride the request.
 //   • bearer app (getToken)         — Authorization: Bearer <jwt>.
-//   • publishable-key app (ingestKey: 'pk_…') — Authorization: Bearer pk_… on
-//     fetch, ?ingest_key=pk_… on a headerless page-unload beacon. Write-only and
-//     safe to ship in a bundle; the door HMAC-verifies it to an org server-side.
+//   • publishable-key app (ingestKey: 'pk-…') — ?ingest_key=pk-… on the query, on
+//     the fetch and the beacon alike, with a text/plain body. Write-only and safe
+//     to ship in a bundle; the door resolves it to an org server-side. The query
+//     is the carrier neither send needs a header for, which is what keeps both
+//     CORS-simple and therefore sendable from a customer's own origin.
 //
 // The wire is the canonical `Event` (== the cloud CaptureEvent): its `type` field
 // is what Cloud folds to event_type='error', which is how the event WAREHOUSE
@@ -115,7 +117,7 @@ function readEnv(name: string): string | undefined {
 }
 
 /** appendQuery adds a single query param to a URL string — used to carry a
- *  publishable key on a headerless sendBeacon (?ingest_key=…). */
+ *  publishable key on either send (?ingest_key=…). */
 function appendQuery(url: string, key: string, value: string): string {
   return url + (url.includes('?') ? '&' : '?') + key + '=' + encodeURIComponent(value)
 }
@@ -170,14 +172,19 @@ function serializeBatch(batch: WireEvent[]): string | null {
 }
 
 /** DefaultTransport: fetch(keepalive) for authenticated/normal sends;
- *  navigator.sendBeacon for headerless page-unload beacons. A bearer (a JWT or a
- *  publishable pk_ key) rides Authorization on fetch; on a beacon — which cannot
- *  set headers — a publishable key rides the ?ingest_key query instead.
+ *  navigator.sendBeacon for page-unload beacons.
+ *
+ *  A publishable key rides the ?ingest_key query on BOTH, which is what keeps
+ *  both CORS-simple: the query is the one carrier neither send needs a header
+ *  for, and a simple request leaves the browser from any origin — permission is
+ *  asked to READ a cross-origin response, never to send one. That is what lets a
+ *  bundled client run on a customer's own page. A JWT is first-party by
+ *  construction, so it keeps Authorization and the session it travels with.
  *
  *  `contentType` names the FETCH request's Content-Type (the error plane sets the
- *  envelope type there). The beacon body is always BEACON_CONTENT_TYPE: its type
- *  is a CORS class, not a payload description, and a beacon that is not a simple
- *  request is a beacon that is never sent. */
+ *  envelope type there, and keeps the header carrier with it). The beacon body is
+ *  always BEACON_CONTENT_TYPE: its type is a CORS class, not a payload
+ *  description, and a beacon that is not a simple request is never sent. */
 class DefaultTransport implements Transport {
   send(
     url: string,
@@ -254,6 +261,8 @@ export class Analytics {
   private attribution: Attribution = { utm: {} }
   private cohort: Cohort = {}
   private started = false
+  /** The view pageview() last counted — path + location. */
+  private counted?: string
   /** Parsed error-plane DSN, or null when the plane is inert. */
   private dsn: Dsn | null
   /** Guards against an error thrown *inside* the error path re-entering it. */
@@ -292,6 +301,21 @@ export class Analytics {
     )
   }
 
+  /** adopt gives this client a credential it does not have. The key belongs to
+   *  the stream, not to whichever caller happened to ask for the handle first,
+   *  so a later caller carrying one hands it over. The error plane derives from
+   *  the key, so it comes up here too when it was inert for want of one.
+   *  Present fields are never overwritten: the first caller's key stays. */
+  adopt(config: AnalyticsConfig): void {
+    if (config.ingestKey && !this.cfg.ingestKey) this.cfg.ingestKey = config.ingestKey
+    if (config.getToken && !this.cfg.getToken) this.cfg.getToken = config.getToken
+    if (!this.dsn) {
+      this.dsn = parseDsn(
+        config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product, this.cfg.ingestKey),
+      )
+    }
+  }
+
   /** errorPlaneEnabled reports whether captured exceptions can actually reach the
    *  error host. False means a DSN was never configured — the documented
    *  fail-safe. Exposed so an app (or a test) can assert its wiring instead of
@@ -356,13 +380,22 @@ export class Analytics {
     this.enqueue('group', undefined, { groupId, properties: traits })
   }
 
-  /** pageview records a $pageview for the current (or given) location. */
+  /** pageview records a $pageview for the current (or given) location, once per
+   *  view. A view is the path plus the full location, so a query or hash change
+   *  is a new one and a repeat call for the same place is not. */
   pageview(path?: string, properties?: Record<string, unknown>): void {
     // No `url` here: build() reads window.location.href for every event, in the
     // same tick, so this recomputed it to the identical value. Only `path` is
     // passed, because a route change fires before window.location has caught up
     // and the caller's value has to win.
     const p = path ?? (isBrowser() ? window.location.pathname : undefined)
+    // Counting a page once is the client's rule, not each caller's. A page holds
+    // several emitters that each correctly believe they count the first view —
+    // the provider's autoPageview, a router hook, a nav autocapture — and per
+    // emitter state cannot see the others. On the stream they are one page.
+    const view = (p ?? '') + '\0' + (isBrowser() ? window.location.href : '')
+    if (view === this.counted) return
+    this.counted = view
     this.enqueue('pageview', PAGEVIEW, { path: p, properties })
   }
 
@@ -463,8 +496,8 @@ export class Analytics {
    *  front door POST /v1/event, body { batch: [Event…] }. beacon=true selects the
    *  unload-safe transport. Auth is orthogonal to the wire:
    *
-   *    • publishable key set → rides Authorization: Bearer pk_… (fetch) or
-   *      ?ingest_key=pk_… (beacon), so unload beacons work anonymously.
+   *    • publishable key set → rides ?ingest_key=pk-… on both sends, keeping each
+   *      a CORS-simple request that any origin may send.
    *    • else a bearer JWT rides Authorization (fetch only — sendBeacon cannot
    *      carry a header, so token apps fall back to keepalive fetch on unload).
    *    • else a cookie app rides same-origin credentials (beacon carries the
@@ -490,8 +523,8 @@ export class Analytics {
     // leak introduced by an env var.
     const token = this.cfg.getToken?.() ?? undefined
     const key = token ? undefined : this.cfg.ingestKey?.trim() || undefined
-    // Only a headerful bearer JWT blocks the beacon: sendBeacon cannot set an
-    // Authorization header. A pk_ rides ?ingest_key; a cookie rides credentials.
+    // Only a bearer JWT blocks the beacon: sendBeacon cannot set an Authorization
+    // header. A pk- rides ?ingest_key; a cookie rides credentials.
     const useBeacon = beacon && !token
     const body = serializeBatch(batch)
     if (body === null) {
@@ -631,9 +664,59 @@ export class Analytics {
   }
 }
 
-/** createAnalytics builds a client instance. Most apps use one shared instance. */
+// ── one stream, one client ──────────────────────────────────────────────────
+//
+// A page has ONE event stream per (host, product): one queue, one anon id, one
+// credential. Two clients on it split the batch and double the pageview, and
+// the half built by the caller that had no key is refused at the door — so the
+// same page is both over- and under-counted, and neither number says so.
+//
+// Two callers ask for that stream on any real page and both are right to: the
+// app mounts a provider, and the component library mounts its own telemetry.
+// Neither can see the other, so the fix cannot live in either. It lives here,
+// where the stream is: asking twice returns the same client.
+//
+// The registry is on the PAGE, under a `Symbol.for` slot, not in module scope.
+// `@hanzo/event` and `@hanzo/event/react` are separate bundles that each carry
+// a copy of this module, so a module-scope map is per-copy and the two copies
+// never see each other's — which is exactly how the duplicate arises. A
+// well-known symbol is the one slot every copy resolves to the same value.
+//
+// Browser only. A server process serves many visitors, and one client shared
+// across requests would carry one visitor's personId into the next.
+const CLIENTS = Symbol.for('hanzo.event.clients')
+
+function registry(): Map<string, Analytics> {
+  const g = globalThis as unknown as Record<symbol, Map<string, Analytics> | undefined>
+  const existing = g[CLIENTS]
+  if (existing) return existing
+  const fresh = new Map<string, Analytics>()
+  g[CLIENTS] = fresh
+  return fresh
+}
+
+/** createAnalytics returns the client for a stream, building it on first ask.
+ *  This is the ONE way to get a client: `new Analytics` bypasses the registry
+ *  and is for tests and for a deliberately separate instance. */
 export function createAnalytics(config: AnalyticsConfig): Analytics {
-  return new Analytics(config)
+  // A disabled client emits nothing, so it can double nothing and does not take
+  // the stream. Callers reach their answer at different moments — a provider
+  // whose ownership resolves in an effect renders once saying `false` before it
+  // has decided anything — and the client built in that moment must not become
+  // the one the page keeps. Registering it would silence the page, and adopting
+  // `enabled` from a later caller would let one surface overrule another's
+  // reading of consent. Neither: it is simply not the stream's client.
+  if (!isBrowser() || config.enabled === false) return new Analytics(config)
+  const key = (config.host ?? DEFAULT_HOST) + '\0' + config.product
+  const clients = registry()
+  const existing = clients.get(key)
+  if (existing) {
+    existing.adopt(config)
+    return existing
+  }
+  const fresh = new Analytics(config)
+  clients.set(key, fresh)
+  return fresh
 }
 
 // Re-export the hydrate helpers so consumers can read persisted cohort/attribution

package/src/react.tsx

@@ -15,7 +15,6 @@ import {
   createElement,
   useContext,
   useEffect,
-  useMemo,
   useRef,
   type ErrorInfo,
   type ReactNode,
@@ -36,12 +35,13 @@ export interface AnalyticsProviderProps {
 
 export function AnalyticsProvider(props: AnalyticsProviderProps) {
   const { client, config, autoPageview = true, children } = props
-  const instance = useMemo<Analytics>(() => {
-    if (client) return client
-    if (config) return createAnalytics(config)
-    throw new Error('AnalyticsProvider requires `client` or `config`')
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [client])
+  // No memo. createAnalytics returns the client for a stream, so asking on every
+  // render hands back the same object — the identity a memo used to be here to
+  // preserve. Memoizing construction is what made a config change unreachable
+  // (deps held `client` alone) while adding `config` would have built a client
+  // per render, since call sites pass an object literal.
+  if (!client && !config) throw new Error('AnalyticsProvider requires `client` or `config`')
+  const instance = client ?? createAnalytics(config as AnalyticsConfig)
 
   useEffect(() => {
     instance.init()

package/src/stream.test.ts

@@ -0,0 +1,195 @@
+// @vitest-environment jsdom
+//
+// One page, one stream. The shape under test is the one hanzo.ai serves: the
+// component library mounts its telemetry, the app mounts its own provider, and
+// each asks for a client for the same (host, product). Measured on production,
+// that page put two batches on api.hanzo.ai/v1/event in the same frame — one
+// carrying the publishable key (200, accepted 2) and one carrying no
+// Authorization at all (401, ingest_key_required) — because the library asked
+// first and had no key. Both batches held a $pageview for the same page.
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Analytics, createAnalytics } from './core'
+import { PAGEVIEW } from './events'
+import type { Transport, WireEvent } from './types'
+
+const HOST = 'https://api.hanzo.ai'
+const KEY = 'pk-CmfLA2K6kvsP'
+
+interface Sent {
+  token?: string
+  ingestKey?: string
+  batch: WireEvent[]
+}
+
+class FakeTransport implements Transport {
+  sent: Sent[] = []
+  send(_url: string, body: string, opts: { token?: string; ingestKey?: string }) {
+    this.sent.push({
+      token: opts.token,
+      ingestKey: opts.ingestKey,
+      batch: (JSON.parse(body) as { batch: WireEvent[] }).batch ?? [],
+    })
+  }
+  get all(): WireEvent[] {
+    return this.sent.flatMap((s) => s.batch)
+  }
+  get pageviews(): WireEvent[] {
+    return this.all.filter((e) => e.event === PAGEVIEW)
+  }
+}
+
+let tx: FakeTransport
+
+/** The library's ask: product from the hostname, no key — the env that carries
+ *  one is not set on this build. It asks FIRST, as it does in the tree. */
+const library = () =>
+  createAnalytics({ product: 'site', host: HOST, transport: tx, flushIntervalMs: 999999 })
+
+/** The app's ask: the same stream, with the credential. */
+const app = () =>
+  createAnalytics({
+    product: 'site',
+    host: HOST,
+    getToken: () => KEY,
+    transport: new FakeTransport(),
+    flushIntervalMs: 999999,
+  })
+
+beforeEach(() => {
+  tx = new FakeTransport()
+  delete (globalThis as unknown as Record<symbol, unknown>)[Symbol.for('hanzo.event.clients')]
+  window.history.replaceState(null, '', '/pricing')
+})
+
+describe('one stream, one client', () => {
+  it('hands both callers the same client', () => {
+    expect(app()).toBe(library())
+  })
+
+  it('sends one batch, not two', () => {
+    library().pageview('/pricing')
+    app().capture('pricing_viewed')
+    app().flush()
+    expect(tx.sent).toHaveLength(1)
+    expect(tx.all).toHaveLength(2)
+  })
+
+  it('carries the credential even though the caller without one asked first', () => {
+    library().pageview('/pricing')
+    app().flush()
+    expect(tx.sent).toHaveLength(1)
+    expect(tx.sent[0].token).toBe(KEY)
+  })
+
+  it('brings up the error plane on the key it adopts', () => {
+    const a = createAnalytics({ product: 'console', host: HOST, transport: tx })
+    expect(a.errorPlaneEnabled).toBe(false)
+    createAnalytics({ product: 'console', host: HOST, ingestKey: KEY })
+    expect(a.errorPlaneEnabled).toBe(true)
+  })
+
+  it('keeps the first credential rather than overwriting it', () => {
+    createAnalytics({ product: 'site', host: HOST, ingestKey: KEY, transport: tx })
+    createAnalytics({ product: 'site', host: HOST, ingestKey: 'pk-second' }).capture('x')
+    createAnalytics({ product: 'site', host: HOST }).flush()
+    expect(tx.sent[0].ingestKey).toBe(KEY)
+  })
+
+  // A provider whose ownership resolves in an effect renders once saying
+  // `enabled: false` and then again saying true. Measured on hanzo.ai: the
+  // library's first render built a disabled client, and a registry that kept it
+  // handed that one to the app too — the page went silent, which is worse than
+  // the double it replaced.
+  it('does not let a disabled client take the stream', () => {
+    const off = createAnalytics({ product: 'site', host: HOST, enabled: false })
+    const on = createAnalytics({ product: 'site', host: HOST, transport: tx, flushIntervalMs: 999999 })
+    expect(on).not.toBe(off)
+    on.pageview('/pricing')
+    on.flush()
+    expect(tx.pageviews).toHaveLength(1)
+    expect(createAnalytics({ product: 'site', host: HOST, getToken: () => KEY })).toBe(on)
+  })
+
+  it('gives every disabled caller its own inert client', () => {
+    const a = createAnalytics({ product: 'site', host: HOST, enabled: false, transport: tx })
+    const b = createAnalytics({ product: 'site', host: HOST, enabled: false, transport: tx })
+    expect(a).not.toBe(b)
+    a.pageview('/pricing')
+    b.pageview('/pricing')
+    a.flush()
+    b.flush()
+    expect(tx.sent).toHaveLength(0)
+  })
+
+  it('keeps separate streams separate', () => {
+    expect(createAnalytics({ product: 'chat', host: HOST })).not.toBe(
+      createAnalytics({ product: 'site', host: HOST }),
+    )
+    expect(createAnalytics({ product: 'site', host: '' })).not.toBe(
+      createAnalytics({ product: 'site', host: HOST }),
+    )
+  })
+
+  it('leaves new Analytics outside the registry', () => {
+    const own = new Analytics({ product: 'site', host: HOST })
+    expect(createAnalytics({ product: 'site', host: HOST })).not.toBe(own)
+  })
+
+  // The package publishes two entries and the react one carries its own copy of
+  // this module, so on a page that imports both there are two module scopes. A
+  // registry held in module scope is per-copy and would not dedupe the only case
+  // that matters. Two distinct instances of this module, one client.
+  it('holds one registry across separate copies of this module', async () => {
+    const one = (await import('./core?copy=1')) as typeof import('./core')
+    const two = (await import('./core?copy=2')) as typeof import('./core')
+    expect(one).not.toBe(two)
+    expect(one.createAnalytics({ product: 'site', host: HOST })).toBe(
+      two.createAnalytics({ product: 'site', host: HOST, ingestKey: KEY }),
+    )
+  })
+})
+
+describe('one pageview per view', () => {
+  it('counts a page once when two emitters both count the first view', () => {
+    library().pageview('/pricing') // the library's route hook, on mount
+    app().pageview() // the app provider's autoPageview, same frame
+    app().flush()
+    expect(tx.pageviews).toHaveLength(1)
+  })
+
+  it('counts a page once even through one client', () => {
+    const a = library()
+    a.pageview('/pricing')
+    a.pageview('/pricing')
+    a.flush()
+    expect(tx.pageviews).toHaveLength(1)
+  })
+
+  it('counts a route change', () => {
+    const a = library()
+    a.pageview('/pricing')
+    window.history.pushState(null, '', '/docs')
+    a.pageview('/docs')
+    a.flush()
+    expect(tx.pageviews.map((e) => e.path)).toEqual(['/pricing', '/docs'])
+  })
+
+  it('counts a return to a page already seen', () => {
+    const a = library()
+    a.pageview('/pricing')
+    a.pageview('/docs')
+    a.pageview('/pricing')
+    a.flush()
+    expect(tx.pageviews).toHaveLength(3)
+  })
+
+  it('counts a query change on one path', () => {
+    const a = library()
+    window.history.replaceState(null, '', '/search?q=a')
+    a.pageview('/search')
+    window.history.replaceState(null, '', '/search?q=b')
+    a.pageview('/search')
+    a.flush()
+    expect(tx.pageviews).toHaveLength(2)
+  })
+})

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.26'
+export const VERSION = '0.3.28'