@hanzo/event 0.3.24 → 0.3.26

package/hz.js

@@ -55,7 +55,7 @@
   }
 
   var LIB = 'hz.js'
-  var VERSION = '0.3.24'
+  var VERSION = '0.3.26'
   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'
@@ -284,32 +284,31 @@ function hzAnonId() {
     if (!queue.length) return
     var body = JSON.stringify({ batch: queue.splice(0, queue.length) })
     var url = host + '/v1/event'
-    // The key rides the two channels each transport can actually carry — the
-    // same pair core.ts uses, so the door cannot tell the distributions apart:
-    // a headerless sendBeacon puts it in the query, a fetch puts it in the
-    // Authorization header.
+    // BOTH transports send a SIMPLE request, and for the same reason. The key is
+    // publishable (data-publishable-key, write-only and safe in page source), so
+    // it rides the query — the one carrier neither transport needs a header for —
+    // and the body is text/plain, the CORS-safelisted type. A simple request is
+    // sent whatever origin it is on, because the browser asks permission to READ
+    // a cross-origin response, never to send one, and nothing here reads it.
     //
-    // The beacon body is text/plain because that type is CORS-safelisted, which
-    // makes the POST a SIMPLE request: no preflight, and an unloading document
-    // gets no second round trip. The door reads the raw body and dispatches on
-    // its first non-space byte, so the type names the CORS class and nothing else.
+    // That property is what lets this file run on a customer's own page at all.
+    // Every send from there is cross-origin; an Authorization header or a JSON
+    // content type makes the POST preflighted instead, and an origin that does not
+    // pass the preflight loses the batch, which splice has already emptied.
+    //
+    // The door reads the raw body and dispatches on its first non-space byte, so
+    // the type names the CORS class and nothing else.
+    var wire = key ? url + '?ingest_key=' + encodeURIComponent(key) : url
     try {
-      if (
-        navigator.sendBeacon &&
-        navigator.sendBeacon(
-          key ? url + '?ingest_key=' + encodeURIComponent(key) : url,
-          new Blob([body], { type: 'text/plain' }),
-        )
-      )
+      if (navigator.sendBeacon && navigator.sendBeacon(wire, new Blob([body], { type: 'text/plain' })))
         return
     } catch (e) {}
-    var headers = { 'content-type': 'application/json' }
-    if (key) headers.authorization = 'Bearer ' + key
-    fetch(url, {
+    fetch(wire, {
       method: 'POST',
       body: body,
       keepalive: true,
-      headers: headers,
+      credentials: 'omit',
+      headers: { 'content-type': 'text/plain' },
     }).catch(function () {})
   }
   // ── location redaction ────────────────────────────────────────────────────
@@ -471,11 +470,25 @@ function hzAnonId() {
       })
     }).observe({ type: 'layout-shift', buffered: true })
   } catch (e) {}
-  addEventListener('visibilitychange', function () {
-    if (document.visibilityState !== 'hidden') return
-    if (vitals.lcp != null || vitals.cls != null) send('event', '$vitals', vitals)
+  // A document can be taken away on either signal, and neither one alone covers
+  // every browser: visibilitychange is what fires when a tab is backgrounded or
+  // discarded, pagehide is what fires on the navigation path where it does not.
+  // core.ts listens for both; this listens for both. flush() returns on an empty
+  // queue, so whichever arrives second finds nothing left to send.
+  var vitalsSent = false
+  function leaving() {
+    // The web vitals are one measurement of one page view. Hiding a tab twice
+    // does not make two of them.
+    if (!vitalsSent && (vitals.lcp != null || vitals.cls != null)) {
+      vitalsSent = true
+      send('event', '$vitals', vitals)
+    }
     flush()
+  }
+  addEventListener('visibilitychange', function () {
+    if (document.visibilityState === 'hidden') leaving()
   })
+  addEventListener('pagehide', leaving)
 
   // ── public API (manual funnel/identify) + GA/Meta fan-out ─────────────────
   function assign(a, b) {

package/package.json

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

@@ -207,17 +207,25 @@ class DefaultTransport implements Transport {
       }
     }
     if (typeof fetch !== 'function') return
+    // A publishable key makes the send a CORS SIMPLE request: the key rides the
+    // query, the body is text/plain, and nothing asks for credentials. That is what
+    // lets a bundled client run on a customer's own page — every send from there is
+    // cross-origin, and an Authorization header or a JSON type preflights the POST
+    // for an origin that cannot pass one. A JWT is first-party by construction, so
+    // it keeps the header and the session it travels with, and so does the error
+    // plane, which names its own envelope type.
+    const simple = opts.ingestKey !== undefined && opts.contentType === undefined
     const headers: Record<string, string> = {
-      'Content-Type': opts.contentType ?? 'application/json',
+      'Content-Type': simple ? BEACON_CONTENT_TYPE : (opts.contentType ?? 'application/json'),
     }
-    const bearer = opts.ingestKey ?? opts.token
+    const bearer = simple ? undefined : (opts.ingestKey ?? opts.token)
     if (bearer) headers.Authorization = `Bearer ${bearer}`
-    void fetch(url, {
+    void fetch(simple ? appendQuery(url, 'ingest_key', opts.ingestKey!) : url, {
       method: 'POST',
       headers,
       body,
       keepalive: true,
-      credentials: 'include',
+      credentials: simple ? 'omit' : 'include',
     })
       .then((res) => {
         // Telemetry loss never throws into the app — but silence is how this

package/src/hz.test.ts

@@ -75,8 +75,11 @@ function runSnippet(opts: StubOptions = {}): {
   api: Api | undefined
   local: Map<string, string>
   jar: Map<string, string>
+  fire: (type: string) => void
+  hide: () => void
 } {
   const posts: Post[] = []
+  const listeners = new Map<string, (() => void)[]>()
   const local = new Map<string, string>(Object.entries(opts.storage ?? {}))
   const jar = opts.jar ?? new Map<string, string>()
   const store = (m: Map<string, string>) => ({
@@ -145,7 +148,13 @@ function runSnippet(opts: StubOptions = {}): {
   define('localStorage', store(local))
   define('sessionStorage', store(new Map()))
   define('history', { pushState: () => {}, replaceState: () => {} })
-  define('addEventListener', () => {})
+  // Listeners are kept, not discarded: the unload flush IS a listener, so a stub
+  // that drops them leaves the only path the drop-off signal travels unexecuted.
+  define('addEventListener', (type: string, fn: () => void) => {
+    const seen = listeners.get(type)
+    if (seen) seen.push(fn)
+    else listeners.set(type, [fn])
+  })
   define('PerformanceObserver', undefined)
   define('hzDNT', undefined)
   define('doNotTrack', undefined)
@@ -166,7 +175,16 @@ function runSnippet(opts: StubOptions = {}): {
   define('window', g)
 
   new Function(SRC)()
-  return { posts, api: (g.window as { hanzo?: Api }).hanzo, local, jar }
+  /** Raise an event the page would raise, so its listeners actually run. */
+  const fire = (type: string) => {
+    for (const fn of listeners.get(type) ?? []) fn()
+  }
+  /** Hide the document, as a browser does before it takes one away. */
+  const hide = () => {
+    ;(g.document as { visibilityState: string }).visibilityState = 'hidden'
+    fire('visibilitychange')
+  }
+  return { posts, api: (g.window as { hanzo?: Api }).hanzo, local, jar, fire, hide }
 }
 
 /** Every event across every transmission, in order. */
@@ -178,6 +196,29 @@ describe('hz.js', () => {
     run = runSnippet()
   })
 
+  // A visitor who leaves mid-funnel is the drop-off signal, and hz.js only gets
+  // to report it from a teardown listener. Neither signal fires in every browser
+  // on every path, so the tag listens for both.
+  it('flushes what is queued when the tab is hidden', () => {
+    run.api!.track('plan_clicked')
+    run.hide()
+    expect(sentOf(run).map((e) => e.event)).toContain('plan_clicked')
+  })
+
+  it('flushes what is queued on pagehide, which visibilitychange need not precede', () => {
+    run.api!.track('checkout_started')
+    run.fire('pagehide')
+    expect(sentOf(run).map((e) => e.event)).toContain('checkout_started')
+  })
+
+  it('sends nothing a second time when both teardown signals arrive', () => {
+    run.api!.track('plan_clicked')
+    run.hide()
+    run.fire('pagehide')
+    const clicks = sentOf(run).filter((e) => e.event === 'plan_clicked')
+    expect(clicks).toHaveLength(1)
+  })
+
   it('mints session ids the plane admits', () => {
     run.api!.track('checkout_started')
     run.api!.flush()
@@ -257,13 +298,24 @@ describe('hz.js', () => {
   // keyed static surface therefore sent UNATTRIBUTED writes, which the door
   // refuses — silently, because nothing here reads the response.
 
-  it('presents the publishable key as a bearer on fetch', () => {
+  // The fetch presents it on the SAME carrier the beacon does, and stays a CORS
+  // simple request doing so. This file's whole job is to run on a customer's own
+  // page, where every send is cross-origin: an Authorization header or a JSON
+  // content type would preflight the POST, and an origin that does not pass the
+  // preflight loses the batch that splice has already emptied. A simple request is
+  // sent from any origin — the browser asks permission to READ a cross-origin
+  // response, never to send one, and nothing here reads it.
+  it('presents the publishable key on the query, as a simple request', () => {
     const r = runSnippet({ attrs: { 'data-publishable-key': 'pk-abc123' } })
     r.api!.flush()
     const post = r.posts.at(-1)!
     expect(post.via).toBe('fetch')
-    expect(post.headers.authorization).toBe('Bearer pk-abc123')
-    expect(post.url).toBe('https://api.hanzo.ai/v1/event')
+    expect(post.url).toBe('https://api.hanzo.ai/v1/event?ingest_key=pk-abc123')
+    expect(post.headers.authorization).toBeUndefined()
+    expect(post.headers['content-type']).toBe('text/plain')
+    // Content-Type is safelisted only for three values; every other header is
+    // outside the safelist by construction, so the count is the check.
+    expect(Object.keys(post.headers)).toEqual(['content-type'])
   })
 
   it('still reads the retiring data-ingest-key, on a headerless beacon', () => {

package/src/transport.test.ts

@@ -22,6 +22,9 @@ interface Fetched {
   url: string
   headers: Record<string, string>
   body: string
+  /** Whether the request may outlive the document that made it. A fetch without
+   *  it is cancelled on teardown, which is the whole failure this file guards. */
+  keepalive?: boolean
 }
 
 // The three CORS-safelisted request content types. A POST whose body carries one
@@ -70,10 +73,16 @@ function unloadFlush(queued: boolean): { beacons: Beaconed[]; fetches: Fetched[]
       }
     },
   )
-  define('fetch', (url: string, init: { headers: Record<string, string>; body: string }) => {
-    fetches.push({ url, headers: init.headers, body: init.body })
-    return Promise.resolve({ ok: true, status: 200 })
-  })
+  define(
+    'fetch',
+    (
+      url: string,
+      init: { headers: Record<string, string>; body: string; keepalive?: boolean },
+    ) => {
+      fetches.push({ url, headers: init.headers, body: init.body, keepalive: init.keepalive })
+      return Promise.resolve({ ok: true, status: 200 })
+    },
+  )
 
   try {
     // No `transport`, so the client builds the real DefaultTransport. The key is
@@ -120,6 +129,17 @@ describe('the unload beacon', () => {
     expect(fetches).toHaveLength(1)
     const batch = (JSON.parse(fetches[0].body) as { batch: { event?: string }[] }).batch
     expect(batch.map((e) => e.event)).toContain('checkout_started')
-    expect(fetches[0].headers.Authorization).toBe('Bearer pk-abc123')
+
+    // The fallback carries the key the SAME way the beacon it replaces did, and
+    // stays a simple request doing so — a fallback that preflights is no fallback
+    // on the customer origin this client is meant to run on.
+    expect(fetches[0].url).toBe('https://api.hanzo.ai/v1/event?ingest_key=pk-abc123')
+    expect(fetches[0].headers.Authorization).toBeUndefined()
+    expect(fetches[0].headers['Content-Type']).toBe('text/plain')
+
+    // The fallback is only a fallback if it survives the teardown that the beacon
+    // was there for. Without this the batch is cancelled mid-flight and the
+    // refusal was merely traded for a quieter loss.
+    expect(fetches[0].keepalive).toBe(true)
   })
 })

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.24'
+export const VERSION = '0.3.26'