@hanzo/event 0.2.0 → 0.3.0

package/src/core.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest'
-import { Analytics } from './core'
+import { Analytics, VERSION } from './core'
 import { EVENTS, PAGEVIEW } from './events'
 import type { Transport, WireEvent } from './types'
 
@@ -7,14 +7,25 @@ interface Sent {
   url: string
   beacon: boolean
   token?: string
+  ingestKey?: string
+  raw: string
   batch: WireEvent[]
 }
 
+// FakeTransport records the EXACT bytes the client would put on the wire, so the
+// tests assert the real POST /v1/event body shape ({ batch: [...] }), not a mock.
 class FakeTransport implements Transport {
   sent: Sent[] = []
-  send(url: string, body: string, opts: { beacon: boolean; token?: string }) {
+  send(url: string, body: string, opts: { beacon: boolean; token?: string; ingestKey?: string }) {
     const parsed = JSON.parse(body) as { batch: WireEvent[] }
-    this.sent.push({ url, beacon: opts.beacon, token: opts.token, batch: parsed.batch })
+    this.sent.push({
+      url,
+      beacon: opts.beacon,
+      token: opts.token,
+      ingestKey: opts.ingestKey,
+      raw: body,
+      batch: parsed.batch,
+    })
   }
   get all(): WireEvent[] {
     return this.sent.flatMap((s) => s.batch)
@@ -22,9 +33,11 @@ class FakeTransport implements Transport {
 }
 
 let tx: FakeTransport
+// Default to same-origin (host:'') so path assertions read the bare /v1/event door;
+// tests that care about the edge host pass it explicitly.
 function mk(overrides = {}) {
   tx = new FakeTransport()
-  return new Analytics({ product: 'console', transport: tx, flushIntervalMs: 999999, ...overrides })
+  return new Analytics({ product: 'console', host: '', transport: tx, flushIntervalMs: 999999, ...overrides })
 }
 
 describe('Analytics capture', () => {
@@ -32,23 +45,57 @@ describe('Analytics capture', () => {
     tx = new FakeTransport()
   })
 
-  it('flushes an event as a {batch:[...]} with product + name, no tenant/org field', () => {
+  it('flushes an event as { batch:[…] } to /v1/event, no tenant/org field', () => {
     const a = mk()
     a.capture(EVENTS.SIGNUP_COMPLETED, { plan: 'pro' })
     a.flush()
     expect(tx.sent).toHaveLength(1)
-    expect(tx.sent[0].url).toBe('/v1/analytics')
+    expect(tx.sent[0].url).toBe('/v1/event')
+    // The body is the canonical { batch: [...] } envelope, exactly one door.
+    const parsed = JSON.parse(tx.sent[0].raw)
+    expect(Array.isArray(parsed.batch)).toBe(true)
     const e = tx.all[0]
     expect(e.type).toBe('event')
     expect(e.event).toBe('signup_completed')
     expect(e.product).toBe('console')
     expect(e.properties).toEqual({ plan: 'pro' })
-    // The client must never send a tenant/org — the server stamps it.
+    // The client must NEVER send a tenant/org — the server stamps it.
     expect((e as Record<string, unknown>).tenant).toBeUndefined()
     expect((e as Record<string, unknown>).org).toBeUndefined()
     expect((e as Record<string, unknown>).tenantId).toBeUndefined()
   })
 
+  it('the wire is the canonical /v1/event Event: only known cloud fields, no tenant', () => {
+    const a = mk({ host: 'https://api.hanzo.ai' })
+    a.identify('user-9')
+    a.capture(EVENTS.ORDER_COMPLETED, { kind: 'plan' }, { productId: 'plan_pro', revenue: 49, quantity: 1, currency: 'usd' })
+    a.flush()
+    // ONE POST, ONE door, ONE batched envelope.
+    expect(tx.sent).toHaveLength(1)
+    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/event')
+    const parsed = JSON.parse(tx.sent[0].raw) as { batch: WireEvent[] }
+    expect(Object.keys(parsed)).toEqual(['batch'])
+    // Every field the client emits is a known cloud CaptureEvent field — no tenant.
+    const allowed = new Set([
+      'messageId', 'type', 'event', 'timestamp', 'distinctId', 'anonymousId',
+      'personId', 'sessionId', 'product', 'url', 'path', 'referrer', 'utm',
+      'refCode', 'channel', 'groupId', 'signupWeek', 'productId', 'quantity',
+      'revenue', 'currency', 'error', 'properties', 'library', 'libraryVersion',
+    ])
+    for (const ev of parsed.batch) {
+      for (const k of Object.keys(ev)) expect(allowed.has(k)).toBe(true)
+      expect((ev as Record<string, unknown>).tenant).toBeUndefined()
+      expect((ev as Record<string, unknown>).tenantId).toBeUndefined()
+      expect(ev.library).toBe('@hanzo/event')
+      expect(ev.libraryVersion).toBe(VERSION)
+    }
+    const order = parsed.batch.find((e) => e.event === EVENTS.ORDER_COMPLETED)!
+    expect(order.productId).toBe('plan_pro')
+    expect(order.revenue).toBe(49)
+    expect(order.quantity).toBe(1)
+    expect(order.currency).toBe('usd')
+  })
+
   it('pageview emits the reserved $pageview name', () => {
     const a = mk()
     a.pageview('/pricing')
@@ -107,16 +154,29 @@ describe('Analytics capture', () => {
     a.capture('x')
     a.flush(true) // beacon requested…
     expect(tx.sent[0].token).toBe('jwt-abc')
-    expect(tx.sent[0].beacon).toBe(false) // …but a token forces keepalive fetch
-    expect(tx.sent[0].url).toBe('/v1/analytics')
+    expect(tx.sent[0].beacon).toBe(false) // …but a JWT forces keepalive fetch
+    expect(tx.sent[0].url).toBe('/v1/event')
+  })
+
+  it('cookie apps beacon to /v1/event on unload flush', () => {
+    const a = mk() // no token, no key
+    a.capture('x')
+    a.flush(true)
+    expect(tx.sent[0].beacon).toBe(true)
+    expect(tx.sent[0].token).toBeUndefined()
+    expect(tx.sent[0].url).toBe('/v1/event')
   })
 
-  it('cookie apps beacon to the tracker route on unload flush', () => {
-    const a = mk() // no token
+  it('publishable-key apps ride ingestKey and still beacon on unload', () => {
+    const a = mk({ ingestKey: 'pk_live_123' })
     a.capture('x')
     a.flush(true)
+    // The key is offered to the transport (rides ?ingest_key on the beacon), and
+    // a publishable key does NOT block the unload beacon.
+    expect(tx.sent[0].ingestKey).toBe('pk_live_123')
+    expect(tx.sent[0].token).toBeUndefined()
     expect(tx.sent[0].beacon).toBe(true)
-    expect(tx.sent[0].url).toBe('/v1/tracker')
+    expect(tx.sent[0].url).toBe('/v1/event')
   })
 
   it('setCohort rides subsequent events', () => {
@@ -134,30 +194,35 @@ describe('Analytics capture', () => {
     const a = mk({ host: 'https://api.hanzo.ai' })
     a.capture('x')
     a.flush()
-    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/analytics')
+    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/event')
   })
 
-  it('stamps every event with the @hanzo/event library id', () => {
+  it('stamps every event with the @hanzo/event library id + version', () => {
     const a = mk()
     a.capture('x')
     a.flush()
     expect(tx.all[0].library).toBe('@hanzo/event')
+    expect(tx.all[0].libraryVersion).toBe(VERSION)
   })
 })
 
 describe('Event error capture', () => {
-  it('captureError emits a type:error event with the exception, and flushes at once', () => {
+  it('captureError emits a type:error event carrying a TOP-LEVEL exception, flushed at once', () => {
     const a = mk()
     a.captureError(new TypeError('boom'))
     // captureError flushes promptly — no explicit flush() needed.
     expect(tx.sent).toHaveLength(1)
     const e = tx.all[0]
+    // type:'error' is the field Cloud folds to event_type='error' → sentry lens.
     expect(e.type).toBe('error')
     expect(e.event).toBe('boom')
+    // The exception rides the TOP-LEVEL `error` field (what cloud foldException
+    // reads), NOT properties — a properties-only exception would not be lensed.
     expect(e.error?.type).toBe('TypeError')
     expect(e.error?.message).toBe('boom')
     expect(e.error?.stack).toBeTruthy()
     expect(e.error?.handled).toBe(true) // a caught, manually-reported error
+    expect((e.properties ?? {})).not.toHaveProperty('$exception')
   })
 
   it('normalizes a thrown string into an exception', () => {
@@ -184,11 +249,12 @@ describe('Event error capture', () => {
     expect(e.error?.message).toBe('via alias')
   })
 
-  it('an error is still an event on the ONE stream — same route + product', () => {
+  it('an error is still an event on the ONE stream — same /v1/event door + product', () => {
     const a = mk({ host: 'https://api.hanzo.ai' })
     a.captureError(new Error('x'))
-    // Same batched route as any other event — one pipe, not a second SDK.
-    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/analytics')
+    // Same batched door as any other event — one pipe, not a second SDK.
+    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/event')
+    expect(tx.sent[0].raw.startsWith('{"batch":')).toBe(true)
     expect(tx.all[0].product).toBe('console')
     // never the tenant — the server stamps it, errors included.
     expect((tx.all[0] as Record<string, unknown>).tenant).toBeUndefined()

package/src/core.ts

@@ -1,8 +1,28 @@
-// The framework-agnostic event client. Buffers events and flushes them as one
-// batch to Hanzo Cloud — /v1/analytics normally, /v1/tracker via sendBeacon on
-// page unload. It NEVER sends the org/tenant: the server stamps that from the
-// validated session. The client only supplies its own visitor identity. Errors
-// are just events (type:'error') on the same stream — one client, one pipe.
+// The framework-agnostic event client. Buffers events and flushes them as ONE
+// batch through the ONE Hanzo Cloud ingestion front door:
+//
+//   POST {host}/v1/event   body: { batch: [Event, …] }   -> { accepted, dropped }
+//
+// It NEVER sends the org/tenant: Cloud resolves that server-side (from the
+// validated session, or the signed publishable key) and stamps it. The client
+// only supplies its own visitor identity. Errors are just events (type:'error')
+// on the same stream — one client, one pipe, lensed server-side into product
+// analytics (insights), web analytics (analytics), and error tracking (sentry).
+//
+// Auth is orthogonal — the SAME body to the SAME door, differing only in how the
+// caller proves its tenant:
+//
+//   • 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.
+//
+// The wire is the canonical `Event` (== the cloud CaptureEvent): its `type` field
+// is what Cloud folds to event_type='error', so a captured exception reaches the
+// error-tracking lens. (A four-field {event,distinctId,time,properties} object has
+// no `type`, so it can never be lensed as an error — this batched Event wire is
+// the one that lights up all three lenses.)
 
 import {
   parseAttribution,
@@ -28,10 +48,16 @@ import type {
   WireEvent,
 } from './types'
 
-export const VERSION = '0.2.0'
+export const VERSION = '0.3.0'
 
-const ANALYTICS_PATH = '/v1/analytics'
-const TRACKER_PATH = '/v1/tracker' // beacon-on-unload alias
+const EVENT_PATH = '/v1/event' // the ONE canonical ingestion front door
+const DEFAULT_HOST = 'https://api.hanzo.ai' // the one edge; cookie apps pass host:''
+
+/** appendQuery adds a single query param to a URL string — used to carry a
+ *  publishable key on a headerless sendBeacon (?ingest_key=…). */
+function appendQuery(url: string, key: string, value: string): string {
+  return url + (url.includes('?') ? '&' : '?') + key + '=' + encodeURIComponent(value)
+}
 
 function uid(): string {
   const c = typeof crypto !== 'undefined' ? crypto : undefined
@@ -55,12 +81,15 @@ function normalizeError(err: unknown): Exception {
 const isBrowser = () => typeof window !== 'undefined'
 
 /** DefaultTransport: fetch(keepalive) for authenticated/normal sends;
- *  navigator.sendBeacon for headerless page-unload beacons. */
+ *  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. */
 class DefaultTransport implements Transport {
-  send(url: string, body: string, opts: { beacon: boolean; token?: string }): void {
+  send(url: string, body: string, opts: { beacon: boolean; token?: string; ingestKey?: string }): void {
     if (opts.beacon && isBrowser() && typeof navigator.sendBeacon === 'function') {
+      const beaconUrl = opts.ingestKey ? appendQuery(url, 'ingest_key', opts.ingestKey) : url
       try {
-        navigator.sendBeacon(url, new Blob([body], { type: 'application/json' }))
+        navigator.sendBeacon(beaconUrl, new Blob([body], { type: 'application/json' }))
         return
       } catch {
         /* fall through to fetch */
@@ -68,7 +97,8 @@ class DefaultTransport implements Transport {
     }
     if (typeof fetch !== 'function') return
     const headers: Record<string, string> = { 'Content-Type': 'application/json' }
-    if (opts.token) headers.Authorization = `Bearer ${opts.token}`
+    const bearer = opts.ingestKey ?? opts.token
+    if (bearer) headers.Authorization = `Bearer ${bearer}`
     void fetch(url, {
       method: 'POST',
       headers,
@@ -76,7 +106,7 @@ class DefaultTransport implements Transport {
       keepalive: true,
       credentials: 'include',
     }).catch(() => {
-      /* analytics loss is acceptable; never throw into the app */
+      /* telemetry loss is acceptable; never throw into the app */
     })
   }
 }
@@ -96,7 +126,7 @@ export class Analytics {
 
   constructor(config: AnalyticsConfig) {
     this.cfg = {
-      host: '',
+      host: DEFAULT_HOST,
       batchSize: 20,
       flushIntervalMs: 5000,
       enabled: true,
@@ -107,8 +137,9 @@ export class Analytics {
   }
 
   /** init is idempotent and browser-only for its side effects: capture first-touch
-   *  attribution, hydrate cohort, and register the unload flush. Safe to call from
-   *  a React effect on every render. */
+   *  attribution, hydrate cohort, register the unload flush, and (unless opted out)
+   *  auto-capture unhandled errors. Safe to call from a React effect on every
+   *  render. */
   init(): void {
     if (this.started || !this.cfg.enabled) return
     this.started = true
@@ -130,7 +161,8 @@ export class Analytics {
     window.addEventListener('pagehide', () => this.flush(true))
 
     // Auto error capture — the drop-in @sentry replacement. Unhandled errors and
-    // rejected promises become type:'error' events on the same stream.
+    // rejected promises become type:'error' events on the same stream, which Cloud
+    // stamps event_type='error' → the sentry.hanzo.ai lens.
     if (this.cfg.captureErrors) {
       window.addEventListener('error', (e: ErrorEvent) => {
         this.captureError(e.error ?? e.message, { handled: false })
@@ -174,11 +206,12 @@ export class Analytics {
   track = this.capture.bind(this)
 
   /** captureError records an exception as a first-class error event — the ONE
-   *  error path (subsumes @sentry). A caught error, an unhandled rejection, or a
-   *  manual report all become a type:'error' event on the same stream, lensed to
-   *  the error-tracking view server-side. Never throws back into the app; errors
-   *  are higher-signal than pageviews, so it flushes promptly (a crash may unload
-   *  the page moments later). */
+   *  error path (subsumes @sentry). A caught error, an unhandled rejection, a
+   *  React render error, or a manual report all become a type:'error' event on the
+   *  same stream; Cloud folds the exception into properties.$exception and stamps
+   *  event_type='error', so it surfaces in the error-tracking lens. Never throws
+   *  back into the app; errors are higher-signal than pageviews, so it flushes
+   *  promptly (a crash may unload the page moments later). */
   captureError(
     err: unknown,
     context?: { handled?: boolean; properties?: Record<string, unknown> },
@@ -198,21 +231,32 @@ export class Analytics {
     this.cohort = mergeCohort(patch)
   }
 
-  /** flush drains the buffer to the server as one batch. beacon=true uses the
-   *  unload-safe path. */
+  /** flush drains the buffer to the server as ONE batch through the ONE ingest
+   *  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.
+   *    • 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
+   *      cookie fine).
+   */
   flush(beacon = false): void {
     if (!this.cfg.enabled || this.queue.length === 0) return
     const batch = this.queue
     this.queue = []
     this.clearTimer()
-    const token = this.cfg.getToken?.() ?? undefined
-    // sendBeacon cannot carry an Authorization header, so token apps always use
-    // keepalive fetch; cookie apps may beacon to the tracker route on unload.
+
+    const key = this.cfg.ingestKey?.trim() || undefined
+    // A publishable key and a bearer JWT are mutually exclusive doors; the key wins.
+    const token = key ? undefined : this.cfg.getToken?.() ?? undefined
+    // Only a headerful 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 path = useBeacon ? TRACKER_PATH : ANALYTICS_PATH
     const body = JSON.stringify({ batch })
-    if (this.cfg.debug) console.debug('[analytics] flush', batch.length, path)
-    this.transport.send(this.cfg.host + path, body, { beacon: useBeacon, token: token ?? undefined })
+    if (this.cfg.debug) console.debug('[event] flush →', EVENT_PATH, batch.length)
+    this.transport.send(this.cfg.host + EVENT_PATH, body, { beacon: useBeacon, token, ingestKey: key })
   }
 
   // ── internals ────────────────────────────────────────────────────────────

package/src/types.ts

@@ -1,11 +1,13 @@
 // Public types for the Hanzo Event client.
 
 /** The event kinds — the closed set the server understands. An error is just
- *  another event on the one stream (lensed to the error-tracking view). */
+ *  another event on the one stream (Cloud stamps type:'error' → event_type='error',
+ *  the key the error-tracking lens filters on). */
 export type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error'
 
-/** A captured exception. Carried on a `type:'error'` event; the server lenses it
- *  into the error-tracking view (sentry.hanzo.ai). */
+/** A captured exception. Carried on a `type:'error'` event's top-level `error`
+ *  field; Cloud folds it into properties.$exception and lenses the event into the
+ *  error-tracking view (sentry.hanzo.ai). */
 export interface Exception {
   /** Constructor/class name, e.g. "TypeError". */
   type?: string
@@ -41,8 +43,10 @@ export interface Cohort {
   refCode?: string
 }
 
-/** One event as sent on the wire. tenant/org is NEVER set here — the server
- *  stamps it from the validated session. */
+/** One event as sent on the wire — the canonical Hanzo Cloud event. Maps 1:1 to
+ *  the cloud `CaptureEvent` (camelCase JSON keys); a batch of these is POSTed to
+ *  the ONE front door `/v1/event` as `{ batch: [WireEvent, …] }`. tenant/org is
+ *  NEVER a field here — the server stamps it from the validated session/key. */
 export interface WireEvent {
   messageId: string
   type: EventKind
@@ -65,28 +69,41 @@ export interface WireEvent {
   quantity?: number
   revenue?: number
   currency?: string
-  /** Set on `type:'error'` events — the captured exception. */
+  /** Set on `type:'error'` events — the captured exception. Cloud lifts it into
+   *  properties.$exception (foldException) for the error-tracking lens. */
   error?: Exception
   properties?: Record<string, unknown>
   library?: string
   libraryVersion?: string
 }
 
-/** Injectable transports — overridden in tests; default in core.ts uses fetch. */
+/** Injectable transports — overridden in tests; the default in core.ts uses fetch
+ *  (keepalive) and sendBeacon. A bearer JWT or a publishable pk_ key rides
+ *  Authorization on fetch; on a headerless beacon a publishable key rides the
+ *  ?ingest_key query. */
 export interface Transport {
   /** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
-  send(url: string, body: string, opts: { beacon: boolean; token?: string }): void
+  send(url: string, body: string, opts: { beacon: boolean; token?: string; ingestKey?: string }): void
 }
 
 export interface AnalyticsConfig {
-  /** Cloud base URL. Same-origin ("") for cookie-auth apps (console/admin);
-   *  e.g. "https://api.hanzo.ai" for bearer apps (app/site). */
+  /** Cloud base URL. Defaults to "https://api.hanzo.ai" (the one edge). Set to
+   *  same-origin ("") for cookie-auth apps served behind the same edge
+   *  (console/admin/chat), so the browser rides the session cookie. */
   host?: string
   /** Emitting surface: console | chat | app | site | admin. */
   product: string
   /** Bearer token provider for token-auth apps. Omit for cookie/session apps
    *  (the client then relies on same-origin credentials). */
   getToken?: () => string | undefined | null
+  /** Publishable ingest key (pk_…). When set, the client authenticates to the ONE
+   *  front door `/v1/event` with this key instead of a bearer/cookie: it rides
+   *  Authorization: Bearer pk_… on fetch and ?ingest_key=pk_… on a headerless
+   *  page-unload beacon, so ALL THREE lenses (web + product + error) light up with
+   *  no bearer and unload beacons work anonymously. The key is write-only (cannot
+   *  read) and safe to ship in a bundle; mint one per org via POST /v1/ingest/keys.
+   *  Recommended for marketing/public pages and the full sentry-subsuming setup. */
+  ingestKey?: string
   /** Max events buffered before an automatic flush. */
   batchSize?: number
   /** Auto-flush cadence in ms. */

package/LICENSE.md

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 hanzo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.