@hanzo/event 0.3.5 → 0.3.8

package/hz.js

@@ -0,0 +1,307 @@
+/*! hz.js — the no-build distribution of @hanzo/event.
+ *
+ * A <script> tag for surfaces that have no bundler: a CMS page, a landing page,
+ * a docs site. It speaks the SAME wire as the npm client and posts to the SAME
+ * front door — one batch of WireEvents to POST {host}/v1/event:
+ *
+ *     { batch: [ { messageId, type, event, timestamp, distinctId, anonymousId,
+ *                  sessionId, product, url, path, referrer, properties }, … ] }
+ *
+ *   <script async src="https://unpkg.com/@hanzo/event/hz.js"
+ *           data-product="hanzo.ai"          // required: which surface this is
+ *           data-host="https://api.hanzo.ai" // optional: API host override
+ *           data-ga="G-XXXX" data-fb="123"   // optional: also fan out to GA4 / Meta
+ *           data-capture="1"></script>       // optional: autocapture off with "0"
+ *
+ * It adds what a bundled app does not need and a plain page cannot get: DOM
+ * AUTOCAPTURE. Clicks on interactive elements (with a compact element locator),
+ * outbound links, scroll depth, form submits and core web vitals arrive as
+ * `$click` / `$outbound` / `$scroll` / `$form` / `$vitals` events on the one
+ * stream. Manual: window.hanzo.track(name, props) · identify(id, traits) · page().
+ * Respects DNT. No PII beyond the short element text the locator carries.
+ *
+ * It used to live in hanzoai/analytics and post a BARE JSON ARRAY of
+ * {site, ts, type, path, …} to analytics.hanzo.ai/v1/event — a second protocol
+ * behind an identical path spelling, served by a second collector with its own
+ * database. Both are deleted. There is one wire, one door and one client home,
+ * and this file is that client's script-tag form.
+ */
+;(function () {
+  var s = document.currentScript
+  if (!s) return
+  if (navigator.doNotTrack === '1' || navigator.doNotTrack === 'yes' || window.hzDNT) return
+
+  var LIB = 'hz.js'
+  var VERSION = '0.3.8'
+  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'
+
+  function uid() {
+    return crypto.randomUUID
+      ? crypto.randomUUID()
+      : Date.now().toString(36) + '.' + Math.random().toString(36).slice(2)
+  }
+  function stored(store, key) {
+    try {
+      var v = store.getItem(key)
+      if (!v) store.setItem(key, (v = uid()))
+      return v
+    } catch (e) {
+      return 'anon'
+    }
+  }
+  var anon = stored(localStorage, 'hz_id')
+  var sid = stored(sessionStorage, 'hz_sid')
+  var person = null
+  try {
+    person = localStorage.getItem('hz_uid')
+  } catch (e) {}
+
+  var queue = [],
+    timer
+  function flush() {
+    clearTimeout(timer)
+    if (!queue.length) return
+    var body = JSON.stringify({ batch: queue.splice(0, queue.length) })
+    var url = host + '/v1/event'
+    try {
+      if (
+        navigator.sendBeacon &&
+        navigator.sendBeacon(url, new Blob([body], { type: 'application/json' }))
+      )
+        return
+    } catch (e) {}
+    fetch(url, {
+      method: 'POST',
+      body: body,
+      keepalive: true,
+      headers: { 'content-type': 'application/json' },
+    }).catch(function () {})
+  }
+  // ── location redaction ────────────────────────────────────────────────────
+  // The same policy src/scrub.ts applies in the npm client, restated here because
+  // this file has no bundler and therefore cannot import it: a reset, invite or
+  // magic link carries a JWT in the query and an address in `?email=`, and the
+  // location is stamped on EVERY event — so without this, one page load ships the
+  // credential to the warehouse and every later click repeats it.
+  //
+  // Deliberately a SUBSET: the shapes that actually appear in a URL. Free-text
+  // error scrubbing (PANs, private keys, stack text) has no counterpart here
+  // because this distribution has no error plane. Keep the markers identical to
+  // scrub.ts — a warehouse row must not reveal which distribution wrote it.
+  var SECRETS = [
+    /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, // JWT
+    /\bbearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi,
+    /\b(?:sk|pk|rk)-[A-Za-z0-9]{2,}-?[A-Za-z0-9]{12,}/g,
+    /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{16,}/g,
+    /\bhk-[A-Za-z0-9]{16,}/g,
+    /\bgh[posru]_[A-Za-z0-9]{20,}/g,
+    /\bAIza[0-9A-Za-z_-]{20,}/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    // Bounded like scrub.ts's: the unbounded form backtracks quadratically on
+    // colon-rich text that never reaches an '@'.
+    /[a-zA-Z][a-zA-Z0-9+.-]{0,32}:\/\/[^\s:@/]{1,256}:[^\s@/]{1,256}@/g,
+  ]
+  var EMAIL = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}/g
+  function clean(u) {
+    if (!u) return u
+    if (u.length > 8192) u = u.slice(0, 8192) + '… [truncated]'
+    for (var i = 0; i < SECRETS.length; i++) u = u.replace(SECRETS[i], '[redacted]')
+    return u.replace(EMAIL, '[email]')
+  }
+
+  // send builds ONE WireEvent — the same shape core.ts build() produces, so the
+  // server cannot tell which distribution emitted it.
+  function send(kind, event, props) {
+    queue.push({
+      messageId: uid(),
+      type: kind,
+      event: event,
+      timestamp: new Date().toISOString(),
+      distinctId: person || anon,
+      anonymousId: anon,
+      personId: person || undefined,
+      sessionId: sid,
+      product: product,
+      url: clean(location.href),
+      path: clean(location.pathname),
+      referrer: clean(document.referrer) || undefined,
+      properties: props || undefined,
+      library: LIB,
+      libraryVersion: VERSION,
+    })
+    clearTimeout(timer)
+    timer = setTimeout(flush, 400)
+  }
+
+  // ── element locator (the autocapture detail) ──────────────────────────────
+  // A compact, stable, PII-light descriptor of the element interacted with, so
+  // movements read logically: tag, short text, id, data-*, and an ancestor path.
+  function locator(el) {
+    if (!el || el === document) return null
+    var o = {
+      tag: el.tagName ? el.tagName.toLowerCase() : '',
+      id: el.id || undefined,
+      name:
+        (el.getAttribute && (el.getAttribute('name') || el.getAttribute('aria-label'))) ||
+        undefined,
+    }
+    var txt = (el.innerText || el.value || '').trim().replace(/\s+/g, ' ').slice(0, 80)
+    if (txt) o.text = txt
+    // A link target is a URL like any other — a share/invite href carries the
+    // same token shapes the page URL does.
+    if (el.getAttribute && el.getAttribute('href')) o.href = clean(el.getAttribute('href'))
+    if (el.dataset) for (var k in el.dataset) if (k !== 'hz') (o.data = o.data || {})[k] = el.dataset[k]
+    var p = [],
+      n = el,
+      i = 0
+    while (n && n.tagName && i++ < 4) {
+      var seg = n.tagName.toLowerCase()
+      if (n.id) {
+        seg += '#' + n.id
+        p.unshift(seg)
+        break
+      }
+      if (n.className && typeof n.className === 'string')
+        seg += '.' + n.className.trim().split(/\s+/).slice(0, 2).join('.')
+      p.unshift(seg)
+      n = n.parentElement
+    }
+    o.sel = p.join('>')
+    return o
+  }
+  function interactive(el) {
+    return el && el.closest && el.closest('a,button,[role=button],input,select,textarea,[data-hz],[onclick]')
+  }
+
+  // ── auto pageviews (initial + SPA) ────────────────────────────────────────
+  var last = ''
+  function page() {
+    var k = location.pathname + location.search
+    if (k === last) return
+    last = k
+    send('pageview', '$pageview')
+  }
+  page()
+  ;['pushState', 'replaceState'].forEach(function (m) {
+    var o = history[m]
+    history[m] = function () {
+      var r = o.apply(this, arguments)
+      page()
+      return r
+    }
+  })
+  addEventListener('popstate', page)
+
+  // ── autocapture: clicks, outbound, scroll depth, form submits ─────────────
+  if (capture) {
+    addEventListener(
+      'click',
+      function (e) {
+        var el = interactive(e.target)
+        if (!el) return
+        var loc = locator(el)
+        send('event', '$click', loc)
+        if (el.tagName === 'A' && el.host && el.host !== location.host)
+          send('event', '$outbound', { url: clean(el.href), el: loc })
+      },
+      true,
+    )
+    addEventListener('submit', function (e) { send('event', '$form', locator(e.target)) }, true)
+    var seen = {}
+    addEventListener(
+      'scroll',
+      function () {
+        var d = document.documentElement
+        var pct = Math.round(((scrollY + innerHeight) / (d.scrollHeight || 1)) * 100)
+        ;[25, 50, 75, 100].forEach(function (m) {
+          if (pct >= m && !seen[m]) {
+            seen[m] = 1
+            send('event', '$scroll', { depth: m })
+          }
+        })
+      },
+      { passive: true },
+    )
+  }
+
+  // ── core web vitals (best-effort, no dep) ─────────────────────────────────
+  var vitals = {}
+  try {
+    new PerformanceObserver(function (l) {
+      l.getEntries().forEach(function (x) { vitals.lcp = Math.round(x.startTime) })
+    }).observe({ type: 'largest-contentful-paint', buffered: true })
+    new PerformanceObserver(function (l) {
+      l.getEntries().forEach(function (x) {
+        if (!x.hadRecentInput) vitals.cls = +((vitals.cls || 0) + x.value).toFixed(3)
+      })
+    }).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)
+    flush()
+  })
+
+  // ── public API (manual funnel/identify) + GA/Meta fan-out ─────────────────
+  function assign(a, b) {
+    if (b) for (var k in b) a[k] = b[k]
+    return a
+  }
+  window.hanzo = {
+    track: function (name, props) { send('event', name, props || undefined) },
+    identify: function (id, traits) {
+      person = id
+      try { localStorage.setItem('hz_uid', id) } catch (e) {}
+      send('identify', undefined, traits || undefined)
+    },
+    page: function (props) {
+      last = ''
+      page()
+      if (props) send('event', 'page_props', props)
+    },
+    flush: flush,
+  }
+  var ga = s.getAttribute('data-ga'),
+    fb = s.getAttribute('data-fb')
+  function load(src) {
+    var el = document.createElement('script')
+    el.async = true
+    el.src = src
+    document.head.appendChild(el)
+  }
+  if (ga) {
+    load('https://www.googletagmanager.com/gtag/js?id=' + ga)
+    window.dataLayer = window.dataLayer || []
+    window.gtag = function () { dataLayer.push(arguments) }
+    gtag('js', new Date())
+    gtag('config', ga)
+    var _t = window.hanzo.track
+    window.hanzo.track = function (n, p) {
+      _t(n, p)
+      try { gtag('event', n, p || {}) } catch (e) {}
+    }
+  }
+  if (fb) {
+    !(function (f) {
+      if (f.fbq) return
+      var n = (f.fbq = function () {
+        n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments)
+      })
+      if (!f._fbq) f._fbq = n
+      n.push = n
+      n.loaded = !0
+      n.version = '2.0'
+      n.queue = []
+    })(window)
+    load('https://connect.facebook.net/en_US/fbevents.js')
+    fbq('init', fb)
+    fbq('track', 'PageView')
+    var _u = window.hanzo.track
+    window.hanzo.track = function (n, p) {
+      _u(n, p)
+      try { fbq('trackCustom', n, p || {}) } catch (e) {}
+    }
+  }
+})()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "description": "Hanzo Event \u2014 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 \u2014 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/",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "src",
+    "hz.js",
     "README.md",
     "TAXONOMY.md"
   ],

package/src/core.test.ts

@@ -2,6 +2,20 @@ import { describe, it, expect, beforeEach } from 'vitest'
 import { Analytics, VERSION } from './core'
 import { EVENTS, PAGEVIEW } from './events'
 import type { Transport, WireEvent } from './types'
+import pkg from '../package.json' with { type: 'json' }
+
+// VERSION is stamped on every event as `libraryVersion`, and it is the only way
+// to tell from the warehouse which build emitted a row. It is hand-maintained
+// (it lives alone to keep sentry.ts from importing core.ts), so it silently fell
+// a release behind: 0.3.4 shipped stamping "0.3.3", making its rows
+// indistinguishable from the previous release's. Every other assertion compares
+// VERSION to itself and so cannot catch that. This one pins it to the version
+// actually published.
+describe('VERSION', () => {
+  it('matches the published package version', () => {
+    expect(VERSION).toBe(pkg.version)
+  })
+})
 
 interface Sent {
   url: string
@@ -167,6 +181,108 @@ describe('Analytics capture', () => {
     }
   })
 
+  // Stamping the location on EVERY event multiplied an exposure that used to
+  // cost one row per page load: a reset/invite/magic link carries a JWT in the
+  // query and an address in `?email=`, so without scrubbing, every click on that
+  // page ships both to the warehouse in cleartext. The error plane has always
+  // scrubbed its free text; the location field is free text too.
+  describe('location scrubbing', () => {
+    const withLocation = (href: string, referrer: string, fn: () => void) => {
+      const g = globalThis as Record<string, unknown>
+      const hadWindow = 'window' in g
+      const hadDocument = 'document' in g
+      const u = new URL(href)
+      g.window = {
+        location: { href, pathname: u.pathname, search: u.search },
+        addEventListener: () => {},
+      }
+      g.document = { referrer, visibilityState: 'visible' }
+      try {
+        fn()
+      } finally {
+        if (!hadWindow) delete g.window
+        if (!hadDocument) delete g.document
+      }
+    }
+
+    const SECRET_URL =
+      'https://hanzo.ai/invite/accept?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.QWxnSWdub3JlZA&email=cfo@acme.com'
+
+    it('redacts a secret and PII from the url of every event kind', () => {
+      withLocation(SECRET_URL, '', () => {
+        const a = mk()
+        a.capture('$click')
+        a.pageview()
+        a.flush()
+
+        // Both kinds, because pageview() reaches the wire through a different
+        // branch than autocapture does.
+        for (const e of tx.all) {
+          expect(e.url).not.toContain('eyJhbGciOiJIUzI1NiJ9')
+          expect(e.url).not.toContain('cfo@acme.com')
+          expect(e.url).toContain('[redacted]')
+          expect(e.url).toContain('[email]')
+          // Scrubbed, not dropped — the page is still attributable, which is the
+          // whole reason the field is stamped.
+          expect(e.url).toContain('https://hanzo.ai/invite/accept')
+        }
+      })
+    })
+
+    // pageview() used to pass its own `url` through `...extra`, which merges
+    // AFTER the field build() reads — so scrubbing only the read would have left
+    // the highest-volume event emitting the raw location. The scrub runs on the
+    // assembled record precisely so no call site can route around it.
+    it('cannot be bypassed by a call site that supplies its own location', () => {
+      withLocation(SECRET_URL, '', () => {
+        const a = mk()
+        a.pageview('/invite/accept?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.QWxnSWdub3JlZA')
+        a.flush()
+        const view = tx.all.find((e) => e.type === 'pageview')!
+        expect(view.path).not.toContain('eyJhbGciOiJIUzI1NiJ9')
+        expect(view.path).toContain('[redacted]')
+      })
+    })
+
+    // document.referrer is the previous page's full URL and is stamped on every
+    // event, so it leaks the same way the current location does.
+    it('redacts the referrer', () => {
+      withLocation('https://hanzo.ai/dashboard', SECRET_URL, () => {
+        const a = mk()
+        a.capture('$click')
+        a.flush()
+        expect(tx.all[0].referrer).not.toContain('eyJhbGciOiJIUzI1NiJ9')
+        expect(tx.all[0].referrer).not.toContain('cfo@acme.com')
+      })
+    })
+
+    // capturePII is an explicit opt-in for END-USER identifiers. It is NOT a
+    // mode that ships credentials: there is no configuration under which a
+    // secret leaves the browser.
+    it('still redacts secrets when capturePII is enabled', () => {
+      withLocation(SECRET_URL, '', () => {
+        const a = mk({ capturePII: true })
+        a.capture('$click')
+        a.flush()
+        expect(tx.all[0].url).not.toContain('eyJhbGciOiJIUzI1NiJ9')
+        expect(tx.all[0].url).toContain('[redacted]')
+        expect(tx.all[0].url).toContain('cfo@acme.com')
+      })
+    })
+
+    // A redactor that mangles ordinary URLs would destroy the analytics it
+    // exists to protect, so the common case must pass through byte-for-byte.
+    it('leaves an ordinary url untouched', () => {
+      withLocation('https://hanzo.ai/pricing?plan=pro&utm_source=x', '', () => {
+        const a = mk()
+        a.capture('$click')
+        a.flush()
+        expect(tx.all[0].url).toBe('https://hanzo.ai/pricing?plan=pro&utm_source=x')
+        expect(tx.all[0].path).toBe('/pricing')
+      })
+    })
+  })
+
   it('auto-flushes when the batch size is reached', () => {
     const a = mk({ batchSize: 3 })
     a.capture('a')

package/src/core.ts

@@ -45,6 +45,7 @@ import {
 } from './attribution'
 import { dsnForProduct } from './dsn'
 import { PAGEVIEW } from './events'
+import { scrubText } from './scrub'
 import {
   buildEnvelope,
   buildSentryEvent,
@@ -311,9 +312,12 @@ export class Analytics {
 
   /** pageview records a $pageview for the current (or given) location. */
   pageview(path?: string, properties?: Record<string, unknown>): void {
-    const url = isBrowser() ? window.location.href : undefined
+    // 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)
-    this.enqueue('pageview', PAGEVIEW, { url, path: p, properties })
+    this.enqueue('pageview', PAGEVIEW, { path: p, properties })
   }
 
   /** capture records a named product event with optional properties. Commerce
@@ -467,7 +471,7 @@ export class Analytics {
 
   private build(kind: EventKind, event: string | undefined, extra: Partial<WireEvent>): WireEvent {
     const anon = anonId()
-    return {
+    const wire: WireEvent = {
       messageId: uid(),
       type: kind,
       event,
@@ -500,6 +504,32 @@ export class Analytics {
       libraryVersion: VERSION,
       ...extra,
     }
+
+    // A location is free text an attacker (or an ordinary product flow) controls,
+    // and it is now stamped on EVERY event rather than only pageviews — so the
+    // one field that is always a URL gets the same policy the error plane has
+    // always applied to error text. A password-reset, invite or magic link puts
+    // a JWT in the query and an address in `?email=`; without this, one click on
+    // that page ships both to the warehouse in cleartext, and every later click
+    // repeats it.
+    //
+    // AFTER `...extra`, deliberately. A call site can pass its own location —
+    // pageview() passes `path`, and until this commit it passed `url` too — and
+    // `extra` merges over the fields read above, so scrubbing at the read would
+    // have left the highest-volume event emitting a raw location while looking
+    // scrubbed. Applied to the ASSEMBLED record, the guarantee holds for every
+    // call site, including ones not written yet.
+    //
+    // `scrubText` is the SAME policy as the error plane (secrets always,
+    // PII unless capturePII) rather than a second URL-specific redactor: one
+    // definition of "must not leave the browser", already tested, mirroring the
+    // server's. Guarded on presence so an absent field stays absent instead of
+    // becoming the empty string that `host` derivation reads as a page.
+    const capturePII = this.cfg.capturePII ?? false
+    if (wire.url) wire.url = scrubText(wire.url, capturePII)
+    if (wire.path) wire.path = scrubText(wire.path, capturePII)
+    if (wire.referrer) wire.referrer = scrubText(wire.referrer, capturePII)
+    return wire
   }
 
   private schedule(): void {

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.3'
+export const VERSION = '0.3.8'