@hanzo/event 0.3.0 → 0.3.2

package/README.md

@@ -2,23 +2,44 @@
 
 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:
+never to a third-party.
+
+ONE API surface over **TWO** planes. They are separate pipes, and neither can
+starve the other:
 
 ```
-POST {host}/v1/event   body: { batch: [Event, …] }   ->  { accepted, dropped }
+1. event stream  POST {host}/v1/event    body: { batch: [Event, …] } -> { accepted, dropped }
+2. error plane   POST {dsn}/v1/sentry/{projectId}/envelope/?sentry_key=…   (a real Sentry envelope)
 ```
 
-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.
+> ### Errors need a DSN. Without one, nothing reaches Sentry.
+>
+> **There is no server-side fan-out from `/v1/event` into Sentry.** Versions
+> ≤ 0.3.1 of this README claimed there was — that "Cloud fans the one stream out
+> into three lenses". It does not. `/v1/event` writes a `type:'error'` row to the
+> cloud event warehouse (readable via `GET /v1/errors`) and stops there. Because
+> every Hanzo property believed that claim, nobody set a DSN, and the entire
+> fleet reported **zero** errors to Sentry until 0.3.2 added the envelope.
+>
+> Set `dsn` (or `NEXT_PUBLIC_HANZO_EVENT_DSN`). Mint one per property with
+> `POST /v1/sentry/projects`. The key is publishable and write-only — safe in a
+> browser bundle, same trust class as a `pk_` ingest key. No DSN means the error
+> plane is **inert**: nothing is sent, nothing throws, analytics is unaffected.
+> Assert `client.errorPlaneEnabled` if you want to know which you have.
+
+Web analytics (analytics.hanzo.ai) is a **third, separate** plane and is NOT this
+client — it is the `hz.js` tag, which speaks a different wire (a bare JSON array).
+Note that `analytics.hanzo.ai/v1/event` and `api.hanzo.ai/v1/event` share a path
+spelling but are **different protocols**; point this client at the API host.
 
 - **Batched** with a size + interval flush, and **beacon-on-unload**
   (`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`.
+  `unhandledrejection`, and a React `ErrorBoundary` are reported on both planes —
+  a Sentry envelope to the DSN host, and a correlated `type:'error'` event on the
+  stream. Opt out with `captureErrors: false`.
+- **Scrubbed at the source**: secrets are always redacted and PII is masked
+  client-side before an error leaves the device.
 - **First-touch attribution**: UTM + referrer + `refCode` are parsed once and
   persisted, then attached to every event.
 - **Cohorts**: `signupWeek`, `channel`, `refCode` ride each event.
@@ -76,10 +97,12 @@ 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`.
 
+**Pass a `dsn` or none of this reaches Sentry.**
+
 ```tsx
 import { ErrorBoundary } from '@hanzo/event/react'
 
-<AnalyticsProvider config={{ product: 'console' }}>
+<AnalyticsProvider config={{ product: 'console', dsn: process.env.NEXT_PUBLIC_HANZO_EVENT_DSN }}>
   <ErrorBoundary fallback={(err, reset) => <Crash error={err} onReset={reset} />}>
     <App />
   </ErrorBoundary>
@@ -90,19 +113,40 @@ import { ErrorBoundary } from '@hanzo/event/react'
 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).
+Each report goes to both planes:
+
+- **Sentry** — a real Sentry envelope to the DSN's ingest route. This is the only
+  thing that creates an issue in the error dashboard, with grouping and stack
+  frames. Sent one envelope per error, immediately; batching a crash report is
+  how you lose it.
+- **the event stream** — a `type:'error'` event; Cloud folds the exception into
+  `properties.$exception` and stamps `event_type='error'`, so the error stays
+  correlated with the session's pageviews (`GET /v1/errors`). This is product
+  signal, *not* error tracking, and it never reaches Sentry on its own.
+
+The message and any `properties` are scrubbed of secrets and PII before sending,
+and the message is capped at 8KB. `captureError` never throws back into your app,
+and a failure on one plane cannot suppress the other.
 
 ## 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).
+(`POST /v1/ingest/keys`) and pass it as `ingestKey`; it rides `Authorization` on
+fetch and `?ingest_key` on an unload beacon, so the **event stream** accepts
+anonymous traffic. It is safe to ship in a bundle (write-only, cannot read).
+
+The `ingestKey` authenticates the event stream ONLY. The error plane
+authenticates independently with the DSN key on `?sentry_key=`, and the two
+credentials are never sent to each other's host. A public page that wants errors
+in Sentry needs the `dsn` as well:
 
 ```ts
-createAnalytics({ product: 'site', host: 'https://api.hanzo.ai', ingestKey: 'pk_live_…' })
+createAnalytics({
+  product: 'site',
+  host: 'https://api.hanzo.ai',
+  ingestKey: 'pk_live_…',                          // event stream
+  dsn: process.env.NEXT_PUBLIC_HANZO_EVENT_DSN,    // error plane
+})
 ```
 
 ## Goals & cohorts

package/dist/core-B1XEdWLd.d.cts

@@ -0,0 +1,296 @@
+/** The event kinds — the closed set the server understands. `error` marks the
+ *  breadcrumb an exception leaves on the event stream (Cloud stamps
+ *  event_type='error' for the warehouse, GET /v1/errors). It does NOT reach the
+ *  Sentry dashboard — the envelope on the error plane does that. */
+type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error';
+/** A captured exception as it rides the EVENT STREAM — Cloud folds it into
+ *  properties.$exception for the warehouse. The richer copy (parsed stack frames,
+ *  grouping, release) travels on the error plane as a Sentry envelope; see
+ *  AnalyticsConfig.dsn. */
+interface Exception {
+    /** Constructor/class name, e.g. "TypeError". */
+    type?: string;
+    /** The error message. */
+    message: string;
+    /** Stack trace when available. */
+    stack?: string;
+    /** false = an unhandled/global error (window.onerror, unhandledrejection);
+     *  true = a caught error the app chose to report. Defaults true. */
+    handled?: boolean;
+}
+/** First-touch marketing attribution, parsed once and persisted. */
+interface Attribution {
+    utm: {
+        source?: string;
+        medium?: string;
+        campaign?: string;
+        term?: string;
+        content?: string;
+    };
+    referrer?: string;
+    refCode?: string;
+    /** Derived acquisition channel: direct | organic | paid | social | referral. */
+    channel?: string;
+}
+/** Cohort dimensions carried on every event once known (see goals.ts COHORTS). */
+interface Cohort {
+    /** ISO week the person first signed up, e.g. "2026-W28". */
+    signupWeek?: string;
+    channel?: string;
+    refCode?: string;
+}
+/** 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;
+    event?: string;
+    timestamp: string;
+    distinctId?: string;
+    anonymousId?: string;
+    personId?: string;
+    sessionId?: string;
+    product?: string;
+    url?: string;
+    path?: string;
+    referrer?: string;
+    utm?: Attribution['utm'];
+    refCode?: string;
+    channel?: string;
+    groupId?: string;
+    signupWeek?: string;
+    productId?: string;
+    quantity?: number;
+    revenue?: number;
+    currency?: string;
+    /** Set on `type:'error'` events — the captured exception. Cloud lifts it into
+     *  properties.$exception (foldException) for the event warehouse. Not a Sentry
+     *  path: the envelope on the error plane is what feeds the dashboard. */
+    error?: Exception;
+    properties?: Record<string, unknown>;
+    library?: string;
+    libraryVersion?: string;
+}
+/** 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).
+     *  `contentType` defaults to application/json; the error plane overrides it with
+     *  application/x-sentry-envelope. */
+    send(url: string, body: string, opts: {
+        beacon: boolean;
+        token?: string;
+        ingestKey?: string;
+        contentType?: string;
+        /** Surface non-OK / failed ingest on the console. Never on by default. */
+        debug?: boolean;
+    }): void;
+}
+interface AnalyticsConfig {
+    /** 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 anonymous traffic is accepted and unload beacons work
+     *  without a bearer. The key is write-only (cannot read) and safe to ship in a
+     *  bundle; mint one per org via POST /v1/ingest/keys. This authenticates the
+     *  EVENT STREAM only — the error plane authenticates independently with `dsn`,
+     *  and one does not stand in for the other. */
+    ingestKey?: string;
+    /** Max events buffered before an automatic flush. */
+    batchSize?: number;
+    /** Auto-flush cadence in ms. */
+    flushIntervalMs?: number;
+    /** Turn the client off entirely (e.g. opt-out / DNT). Defaults to enabled. */
+    enabled?: boolean;
+    /** Auto-capture unhandled errors + promise rejections (window.onerror,
+     *  unhandledrejection). Browser-only, defaults to enabled. Together with `dsn`
+     *  this is what makes the client a drop-in @sentry replacement — without a
+     *  `dsn` the captures never reach the Sentry dashboard. */
+    captureErrors?: boolean;
+    /** Override the transport (tests). */
+    transport?: Transport;
+    /** Debug logging. */
+    debug?: boolean;
+    /** Hanzo-minted Sentry DSN: "https://<version>:<hmac>@<host>/v1/sentry/<projectId>".
+     *  Publishable — the key authorizes writes to ONE project and can read nothing,
+     *  so it is safe in a browser bundle (same trust class as `ingestKey`). When
+     *  absent the client reads NEXT_PUBLIC_HANZO_EVENT_DSN; when neither is set the
+     *  error plane is inert (fail-safe: nothing sent, nothing thrown, analytics
+     *  unaffected). Mint one per property: POST /v1/sentry/projects. */
+    dsn?: string;
+    /** Release stamped on error events (a git SHA / app version). */
+    release?: string;
+    /** Deployment environment for error events (production | staging | …). */
+    environment?: string;
+    /** Retain end-user PII (emails/IPs) in error text. Default false = scrub
+     *  client-side before anything leaves the device (the server scrubs again). */
+    capturePII?: boolean;
+}
+type SentryLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+interface SentryFrame {
+    filename?: string;
+    function?: string;
+    module?: string;
+    abs_path?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+}
+interface SentryExceptionValue {
+    type?: string;
+    value?: string;
+    module?: string;
+    stacktrace?: {
+        frames: SentryFrame[];
+    };
+}
+interface SentryUser {
+    /** Stable subject id (OIDC sub / anon id). NEVER email/username/ip. */
+    id?: string;
+}
+interface SentryEvent {
+    event_id: string;
+    timestamp: number;
+    platform: 'javascript';
+    level: SentryLevel;
+    logger?: string;
+    environment?: string;
+    release?: string;
+    transaction?: string;
+    fingerprint?: string[];
+    message?: string;
+    exception?: {
+        values: SentryExceptionValue[];
+    };
+    tags?: Record<string, string>;
+    user?: SentryUser;
+    contexts?: Record<string, Record<string, unknown>>;
+    sdk?: {
+        name: string;
+        version: string;
+    };
+}
+/** Parsed DSN — the public key + the derived ingest URL. */
+interface Dsn {
+    /** "<version>:<hmac>" public key presented via ?sentry_key= (beacon-safe). */
+    publicKey: string;
+    /** Ingest origin, e.g. "https://sentry.hanzo.ai". */
+    origin: string;
+    /** Project id segment. */
+    projectId: string;
+    /** Fully-derived envelope ingest URL incl. ?sentry_key=. */
+    ingestUrl: string;
+}
+/** Options for Analytics.captureError. */
+interface CaptureErrorOptions {
+    /** false => uncaught (window.onerror / unhandledrejection / render crash). */
+    handled?: boolean;
+    /** Severity + free-form context; merged into the event's tags. */
+    properties?: Record<string, unknown>;
+    /** Override the event level (default: error, or fatal when handled === false). */
+    level?: SentryLevel;
+}
+
+declare class Analytics {
+    private cfg;
+    private transport;
+    private queue;
+    private timer;
+    private personId?;
+    private attribution;
+    private cohort;
+    private started;
+    /** Parsed error-plane DSN, or null when the plane is inert. */
+    private dsn;
+    /** Guards against an error thrown *inside* the error path re-entering it. */
+    private reentrant;
+    constructor(config: AnalyticsConfig);
+    /** 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
+     *  discovering months later that nothing was ever reported. */
+    get errorPlaneEnabled(): boolean;
+    /** errorIngestUrl is the fully-derived envelope endpoint, or undefined when the
+     *  plane is inert. Diagnostics only. */
+    get errorIngestUrl(): string | undefined;
+    /** init is idempotent and browser-only for its side effects: capture first-touch
+     *  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;
+    /** group associates the visitor with an org/team (analytics grouping, not the
+     *  server tenant — the server still derives tenant from the session). */
+    group(groupId: string, traits?: Record<string, unknown>): void;
+    /** pageview records a $pageview for the current (or given) location. */
+    pageview(path?: string, properties?: Record<string, unknown>): void;
+    /** capture records a named product event with optional properties. Commerce
+     *  fields (productId/quantity/revenue/currency) may be passed for order events. */
+    capture(event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, 'productId' | 'quantity' | 'revenue' | 'currency'>): void;
+    /** track is an alias of capture (Segment familiarity). */
+    track: (event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, "productId" | "quantity" | "revenue" | "currency">) => void;
+    /** captureError reports a caught error, an unhandled rejection, a React render
+     *  error, or a manual report to BOTH planes, from one call:
+     *
+     *    - the ERROR PLANE — a real Sentry envelope to the DSN host. This is the one
+     *      that produces an issue in sentry.hanzo.ai (grouping, stack frames, AST).
+     *      Inert when no DSN is configured.
+     *    - the EVENT STREAM — a `type:'error'` row in the cloud event warehouse, so
+     *      an error stays correlated with the session's pageviews for product
+     *      analysis (readable via GET /v1/errors).
+     *
+     *  Both carry the SAME session and subject id, so an error and the pageview
+     *  before it join up. Never throws back into the app; errors are higher-signal
+     *  than pageviews, so both planes flush promptly (a crash may unload the page
+     *  moments later). */
+    captureError(err: unknown, context?: CaptureErrorOptions): void;
+    /** captureException — @sentry-familiar alias of captureError. */
+    captureException: (err: unknown, context?: CaptureErrorOptions) => void;
+    /** 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 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;
+    /** sendError frames one exception as a Sentry envelope and posts it to the DSN's
+     *  ingest URL. The DSN's own key rides ?sentry_key= (the credential channel the
+     *  server trusts, and the only one a headerless beacon can carry), so NO bearer
+     *  or publishable key is attached here — the two planes authenticate
+     *  independently. Errors are sent one envelope per event, immediately: batching
+     *  a crash report is how you lose it. */
+    private sendError;
+    /** errorIdentity is the SAME identity the event stream stamps — the OIDC subject
+     *  once identify() has run, else the anon id. Never email/PII. */
+    private errorIdentity;
+    private enqueue;
+    private build;
+    private schedule;
+    private clearTimer;
+}
+/** createAnalytics builds a client instance. Most apps use one shared instance. */
+declare function createAnalytics(config: AnalyticsConfig): Analytics;
+
+export { type Attribution as A, type Cohort as C, type Dsn as D, type EventKind as E, type SentryEvent as S, type Transport as T, type WireEvent as W, type CaptureErrorOptions as a, type SentryFrame as b, Analytics as c, type AnalyticsConfig as d, type Exception as e, type SentryLevel as f, createAnalytics as g };