@hanzo/event 0.2.0 → 0.3.0

package/README.md

@@ -1,18 +1,30 @@
 # @hanzo/event
 
-Tiny, batched product-analytics capture client for Hanzo surfaces. Emits
-`pageview` / `event` / `identify` / `group` to **Hanzo Cloud** — never to a
-third-party or to `insights-capture` directly. Cloud (`/v1/analytics` +
-`/v1/tracker`) is the one front door and fans out to the insights/datastore
-warehouse.
+The ONE telemetry client for Hanzo surfaces. Emits every kind of event —
+`pageview` / `event` / `identify` / `group` **and errors** — to **Hanzo Cloud**,
+never to a third-party. There is exactly one front door:
+
+```
+POST {host}/v1/event   body: { batch: [Event, …] }   ->  { accepted, dropped }
+```
+
+Cloud resolves the tenant server-side and fans the one stream out into three
+lenses: **product analytics** (insights.hanzo.ai), **web analytics**
+(analytics.hanzo.ai), and **error tracking** (sentry.hanzo.ai). Errors are just
+events (`type:'error'`) on the same pipe — one client, one door.
 
 - **Batched** with a size + interval flush, and **beacon-on-unload**
-  (`sendBeacon` for cookie apps, `fetch(keepalive)` for token apps).
+  (`sendBeacon` for cookie/publishable-key apps, `fetch(keepalive)` for token apps).
+- **Auto error capture** (subsumes `@sentry`): `window.onerror`,
+  `unhandledrejection`, and a React `ErrorBoundary` become `type:'error'` events;
+  Cloud stamps `event_type='error'` → the sentry lens. Opt out with
+  `captureErrors: false`.
 - **First-touch attribution**: UTM + referrer + `refCode` are parsed once and
   persisted, then attached to every event.
 - **Cohorts**: `signupWeek`, `channel`, `refCode` ride each event.
 - **Tenant-safe**: the client NEVER sends an org/tenant — Cloud stamps it from
-  the validated session.
+  the validated session or the signed publishable key.
+- **Fail-soft**: telemetry loss is swallowed; the client never throws into the app.
 - **SSR-safe**: importing on the server is a no-op; it only acts in the browser.
 
 ## Core (framework-agnostic)
@@ -58,6 +70,41 @@ function UpgradeButton() {
 }
 ```
 
+## Errors (the @sentry replacement)
+
+Unhandled errors and promise rejections are captured automatically. React render
+errors never reach `window.onerror`, so wrap your tree in the `ErrorBoundary` to
+catch those too. Report caught errors yourself with `captureError`.
+
+```tsx
+import { ErrorBoundary } from '@hanzo/event/react'
+
+<AnalyticsProvider config={{ product: 'console' }}>
+  <ErrorBoundary fallback={(err, reset) => <Crash error={err} onReset={reset} />}>
+    <App />
+  </ErrorBoundary>
+</AnalyticsProvider>
+```
+
+```ts
+try { risky() } catch (err) { analytics.captureError(err, { properties: { where: 'checkout' } }) }
+```
+
+Each becomes a `type:'error'` event carrying the exception; Cloud folds it into
+`properties.$exception`, stamps `event_type='error'`, and it surfaces in the
+error-tracking lens (`GET /v1/errors` → sentry.hanzo.ai).
+
+## Publishable key (public pages, no bearer)
+
+Marketing/public pages have no session. Mint a write-only publishable key
+(`POST /v1/ingest/keys`) and pass it as `ingestKey`; it rides `Authorization`
+on fetch and `?ingest_key` on an unload beacon, so all three lenses light up
+anonymously. It is safe to ship in a bundle (write-only, cannot read).
+
+```ts
+createAnalytics({ product: 'site', host: 'https://api.hanzo.ai', ingestKey: 'pk_live_…' })
+```
+
 ## Goals & cohorts
 
 `GOALS` and `COHORTS` (see `goals.ts`) are the shared, machine-readable insights

package/dist/{core-DDGwms7M.d.cts → core-CrbiAQhN.d.cts}

@@ -1,8 +1,10 @@
 /** 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). */
 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). */
 interface Exception {
     /** Constructor/class name, e.g. "TypeError". */
     type?: string;
@@ -35,8 +37,10 @@ interface Cohort {
     channel?: string;
     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. */
 interface WireEvent {
     messageId: string;
     type: EventKind;
@@ -59,29 +63,43 @@ 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. */
 interface Transport {
     /** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
     send(url: string, body: string, opts: {
         beacon: boolean;
         token?: string;
+        ingestKey?: string;
     }): void;
 }
 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. */
@@ -98,7 +116,7 @@ interface AnalyticsConfig {
     debug?: boolean;
 }
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.0";
 declare class Analytics {
     private cfg;
     private transport;
@@ -110,8 +128,9 @@ declare class Analytics {
     private started;
     constructor(config: AnalyticsConfig);
     /** 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;
     /** identify binds the current visitor to a stable person id (post-login). */
     identify(personId: string, traits?: Record<string, unknown>): void;
@@ -126,11 +145,12 @@ declare class Analytics {
     /** track is an alias of capture (Segment familiarity). */
     track: (event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, "productId" | "quantity" | "revenue" | "currency">) => void;
     /** 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>;
@@ -143,8 +163,17 @@ declare class Analytics {
     /** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
      *  every subsequent event. */
     setCohort(patch: Cohort): void;
-    /** 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?: boolean): void;
     private enqueue;
     private build;

package/dist/{core-DDGwms7M.d.ts → core-CrbiAQhN.d.ts}

@@ -1,8 +1,10 @@
 /** 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). */
 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). */
 interface Exception {
     /** Constructor/class name, e.g. "TypeError". */
     type?: string;
@@ -35,8 +37,10 @@ interface Cohort {
     channel?: string;
     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. */
 interface WireEvent {
     messageId: string;
     type: EventKind;
@@ -59,29 +63,43 @@ 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. */
 interface Transport {
     /** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
     send(url: string, body: string, opts: {
         beacon: boolean;
         token?: string;
+        ingestKey?: string;
     }): void;
 }
 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. */
@@ -98,7 +116,7 @@ interface AnalyticsConfig {
     debug?: boolean;
 }
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.0";
 declare class Analytics {
     private cfg;
     private transport;
@@ -110,8 +128,9 @@ declare class Analytics {
     private started;
     constructor(config: AnalyticsConfig);
     /** 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;
     /** identify binds the current visitor to a stable person id (post-login). */
     identify(personId: string, traits?: Record<string, unknown>): void;
@@ -126,11 +145,12 @@ declare class Analytics {
     /** track is an alias of capture (Segment familiarity). */
     track: (event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, "productId" | "quantity" | "revenue" | "currency">) => void;
     /** 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>;
@@ -143,8 +163,17 @@ declare class Analytics {
     /** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
      *  every subsequent event. */
     setCohort(patch: Cohort): void;
-    /** 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?: boolean): void;
     private enqueue;
     private build;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Cohort, A as Attribution } from './core-DDGwms7M.cjs';
-export { a as Analytics, b as AnalyticsConfig, E as EventKind, c as Exception, T as Transport, V as VERSION, W as WireEvent, d as createAnalytics } from './core-DDGwms7M.cjs';
+import { C as Cohort, A as Attribution } from './core-CrbiAQhN.cjs';
+export { a as Analytics, b as AnalyticsConfig, E as EventKind, c as Exception, T as Transport, V as VERSION, W as WireEvent, d as createAnalytics } from './core-CrbiAQhN.cjs';
 
 /** Read the persisted first-touch attribution. */
 declare function getFirstTouch(): Attribution | undefined;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Cohort, A as Attribution } from './core-DDGwms7M.js';
-export { a as Analytics, b as AnalyticsConfig, E as EventKind, c as Exception, T as Transport, V as VERSION, W as WireEvent, d as createAnalytics } from './core-DDGwms7M.js';
+import { C as Cohort, A as Attribution } from './core-CrbiAQhN.js';
+export { a as Analytics, b as AnalyticsConfig, E as EventKind, c as Exception, T as Transport, V as VERSION, W as WireEvent, d as createAnalytics } from './core-CrbiAQhN.js';
 
 /** Read the persisted first-touch attribution. */
 declare function getFirstTouch(): Attribution | undefined;

package/dist/index.js

@@ -193,9 +193,12 @@ function mergeCohort(patch) {
 }
 
 // src/core.ts
-var VERSION = "0.2.0";
-var ANALYTICS_PATH = "/v1/analytics";
-var TRACKER_PATH = "/v1/tracker";
+var VERSION = "0.3.0";
+var EVENT_PATH = "/v1/event";
+var DEFAULT_HOST = "https://api.hanzo.ai";
+function appendQuery(url, key, value) {
+  return url + (url.includes("?") ? "&" : "?") + key + "=" + encodeURIComponent(value);
+}
 function uid2() {
   const c = typeof crypto !== "undefined" ? crypto : void 0;
   if (c && "randomUUID" in c) return c.randomUUID();
@@ -216,15 +219,17 @@ var isBrowser = () => typeof window !== "undefined";
 var DefaultTransport = class {
   send(url, body, opts) {
     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 {
       }
     }
     if (typeof fetch !== "function") return;
     const headers = { "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,
@@ -247,7 +252,7 @@ var Analytics = class {
     /** captureException — @sentry-familiar alias of captureError. */
     this.captureException = this.captureError.bind(this);
     this.cfg = {
-      host: "",
+      host: DEFAULT_HOST,
       batchSize: 20,
       flushIntervalMs: 5e3,
       enabled: true,
@@ -257,8 +262,9 @@ var Analytics = class {
     this.transport = config.transport ?? new DefaultTransport();
   }
   /** 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() {
     if (this.started || !this.cfg.enabled) return;
     this.started = true;
@@ -305,11 +311,12 @@ var Analytics = class {
     this.enqueue("event", event, { properties, ...commerce });
   }
   /** 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, context) {
     const ex = normalizeError(err);
     ex.handled = context?.handled ?? true;
@@ -321,19 +328,28 @@ var Analytics = class {
   setCohort(patch) {
     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) {
     if (!this.cfg.enabled || this.queue.length === 0) return;
     const batch = this.queue;
     this.queue = [];
     this.clearTimer();
-    const token = this.cfg.getToken?.() ?? void 0;
+    const key = this.cfg.ingestKey?.trim() || void 0;
+    const token = key ? void 0 : this.cfg.getToken?.() ?? void 0;
     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 ?? void 0 });
+    if (this.cfg.debug) console.debug("[event] flush \u2192", EVENT_PATH, batch.length);
+    this.transport.send(this.cfg.host + EVENT_PATH, body, { beacon: useBeacon, token, ingestKey: key });
   }
   // ── internals ────────────────────────────────────────────────────────────
   enqueue(kind, event, extra) {