@hanzo/event 0.3.48 → 0.3.49

package/src/types.ts

@@ -1,15 +1,10 @@
 // Public types for the Hanzo Event client.
 
-/** 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. */
+/** The event kinds — the closed set the server understands. `error` is a captured
+ *  exception; the server files it on the error plane. */
 export 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. */
+/** A captured exception, as the `error` field of a `type:'error'` event. */
 export interface Exception {
   /** Constructor/class name, e.g. "TypeError". */
   type?: string
@@ -20,6 +15,8 @@ export interface Exception {
   /** false = an unhandled/global error (window.onerror, unhandledrejection);
    *  true = a caught error the app chose to report. Defaults true. */
   handled?: boolean
+  /** The structured stack, oldest first. */
+  frames?: { function?: string; file?: string; line?: number; column?: number }[]
 }
 
 /** One stack frame as Error Tracking renders it. The key names are the product's
@@ -125,9 +122,13 @@ export interface WireEvent {
   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. */
+   *  properties.$exception (foldException) for the event warehouse. The
+   *  server files it on the error plane. */
   error?: Exception
+  level?: string
+  release?: string
+  environment?: string
+  site?: string
   properties?: Record<string, unknown>
   library?: string
   libraryVersion?: string
@@ -176,8 +177,7 @@ export interface AnalyticsConfig {
    *  POST /v1/keys {"type":"publishable"}.
    *
    *  Omit it and the client reads NEXT_PUBLIC_PUBLISHABLE_KEY from the inlined
-   *  build env, the same way `dsn` falls back — so a surface declares BOTH planes
-   *  in its build and neither needs code to switch on. That is the ONE spelling
+   *  build env, That is the ONE spelling
    *  the fleet already carries: KMS holds deploy/PUBLISHABLE_KEY, and each
    *  Dockerfile takes PUBLISHABLE_KEY as a build-arg and re-exports it with the
    *  NEXT_PUBLIC_ prefix that makes Next inline it.
@@ -187,9 +187,7 @@ export interface AnalyticsConfig {
    *  edge refuses an unattributable write rather than filing it where its owner
    *  cannot read it. That failure is invisible from the page, which is why the key
    *  belongs in the env next to the DSN and not in a checklist.
-   *
-   *  This attributes 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
@@ -198,24 +196,13 @@ export interface AnalyticsConfig {
   /** 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. */
+   *  unhandledrejection). Browser-only, defaults to enabled. */
   captureErrors?: boolean
   /** Override the transport (tests). */
   transport?: Transport
   /** Debug logging. */
   debug?: boolean
 
-  // ── error plane (Sentry envelope -> sentry.hanzo.ai) ──────────────────────
-
-  /** Hanzo-minted Sentry DSN: "https://<version>:<hmac>@<host>/v1/event/<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 | …). */
@@ -225,8 +212,7 @@ export interface AnalyticsConfig {
   capturePII?: boolean
 }
 
-// ── Sentry envelope wire types (a from-scratch model of the PUBLIC, documented
-//    Sentry ingest protocol — develop.sentry.dev; no upstream code) ───────────
+// ── stack frame and level types ──────────────────────────────────────────────
 
 export type SentryLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug'
 
@@ -240,52 +226,6 @@ export interface SentryFrame {
   in_app?: boolean
 }
 
-export interface SentryExceptionValue {
-  type?: string
-  value?: string
-  module?: string
-  stacktrace?: { frames: SentryFrame[] }
-}
-
-export interface SentryUser {
-  /** Stable subject id (OIDC sub / anon id). NEVER email/username/ip. */
-  id?: string
-}
-
-export 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. */
-export 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
-  /** The DSN's own origin + path, e.g. "https://api.hanzo.ai/v1/event/<projectId>".
-   *  Every URL below is derived from this, so the ingest address is named once —
-   *  in dsnForProduct — and nowhere else. */
-  base: string
-  /** Fully-derived envelope ingest URL incl. ?sentry_key=. */
-  ingestUrl: string
-}
-
 /** Options for Analytics.captureError. */
 export interface CaptureErrorOptions {
   /** false => uncaught (window.onerror / unhandledrejection / render crash). */

package/src/uid.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, afterEach } from 'vitest'
 import { uuidv7, uuidv7Time } from './uid'
-import { eventId } from './sentry'
+const eventId = () => uuidv7().replace(/-/g, '')
 
 /** The event plane's admission gate, transcribed from the session rollup's own SQL:
  *  `bitAnd(bitShiftRight(toUInt128(accurateCastOrNull(id,'UUID')), 76), 15) = 7`.

package/dist/dsn.d.ts

@@ -1,43 +0,0 @@
-/**
- * The product → Sentinel DSN registry.
- *
- * An app declares WHAT it is (`product: 'console'`); this module knows WHERE its
- * errors go. That split is the whole point: no surface has to learn a DSN, carry
- * a build argument, or grow a config file to report errors — declaring the
- * product it already declares is enough.
- *
- * A Sentinel DSN is PUBLIC by construction. It ships inside the client bundle and
- * is readable in devtools on any deployed page, and it grants exactly one
- * capability: submitting new events. It cannot read issues, projects, or any
- * other data. So committing it is not leaking a secret — it is recording a public
- * identifier next to the code that needs it. (Contrast the server-side collector
- * DSN in the `team-analytics-sentry` Secret, which is HMAC-derived and revocable
- * precisely because a server-side credential is NOT public.)
- *
- * Why a literal map instead of deriving `hanzo-${product}`: the projects predate
- * this registry and do not derive cleanly — `site` lives in `hanzo-ai`, not
- * `hanzo-site`. An explicit map is honest about that; a derivation rule plus an
- * exception table is the same data with a trap in it.
- *
- * Projects are org-scoped and named `<org>-<app>`. To add one: create the project
- * (POST /v1/sentinel/projects with X-Org-Id), then add its `dsn` here keyed by the
- * product name the app passes to `createAnalytics`.
- */
-/** PRODUCT_PROJECT maps a `product` to its Sentinel project id. The DSN's KEY is no
- *  longer a per-project secret — it is the ONE org publishable key (below), so a
- *  surface's errors ride the SAME key its events do. The id only names WHICH
- *  project the errors group under, and cloud auto-provisions that project on first
- *  keyed ingest, so a new id needs nothing minted. `site` lives in the `hanzo-ai`
- *  project — an explicit map, because the projects predate this and do not derive
- *  cleanly from the product name. */
-export declare const PRODUCT_PROJECT: Readonly<Record<string, string>>;
-/** dsnForProduct builds the product's Sentinel DSN from the caller's resolved
- *  publishable `key` and the product's project — the SAME key the event stream
- *  carries, at the product's envelope endpoint. Returns undefined when there is no
- *  key or no project for the product, leaving the error plane inert rather than
- *  posting into the wrong one. The key is NOT baked here: it is the value the
- *  surface resolved (an explicit `ingestKey`, or the KMS-sourced
- *  NEXT_PUBLIC_PUBLISHABLE_KEY the build inlines) — the ONE live source, never a
- *  literal committed beside the code. */
-export declare function dsnForProduct(product: string | undefined, key: string | undefined): string | undefined;
-//# sourceMappingURL=dsn.d.ts.map

package/dist/dsn.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../src/dsn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;qCAMqC;AACrC,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI3D,CAAA;AAEF;;;;;;;yCAOyC;AACzC,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,GAAG,SAAS,CAKpB"}

package/dist/sentry.d.ts

@@ -1,62 +0,0 @@
-import type { CaptureErrorOptions, Dsn, SentryEvent, SentryFrame } from './types';
-/** eventId mints a 32-hex-char id (no dashes) — the Sentry event_id shape. Same
- *  minter as everything else, just formatted for Sentry's wire. */
-export declare function eventId(): string;
-/**
- * parseDsn parses "https://<version>:<hmac>@<host>/v1/event/<projectId>" into its
- * public key + the derived envelope ingest URL. The key (which itself contains a
- * ':') is taken verbatim as the userinfo — we do NOT split it as user:pass. The
- * key rides ?sentry_key= (not the DSN in the body) because that is the credential
- * channel the server trusts AND the only one sendBeacon can carry on unload.
- * Returns null for anything malformed (fail-safe: the caller then stays inert).
- */
-export declare function parseDsn(dsn: string | undefined | null): Dsn | null;
-/**
- * framesFromStack parses a browser Error.stack into Sentry frames, OLDEST-FIRST
- * (Sentry orders caller->callee; the crash site is last — matching the server's
- * pickCrashFrame). Handles both V8 ("at fn (file:li:co)") and
- * Firefox/Safari ("fn@file:li:co"). Unparseable lines are skipped.
- */
-export declare function framesFromStack(stack: string | undefined): SentryFrame[];
-/** normalizeError coerces an unknown throwable into {name, message, stack}. */
-export declare function normalizeError(err: unknown): {
-    name: string;
-    message: string;
-    stack?: string;
-};
-/** Identity carried onto every error event — the SAME ids analytics uses. */
-export interface ErrorIdentity {
-    /** OIDC sub (post-identify) or anon id. NEVER email/PII. */
-    userId?: string;
-    sessionId?: string;
-    product?: string;
-    release?: string;
-    environment?: string;
-}
-export interface BuildEventInput {
-    error: unknown;
-    options?: CaptureErrorOptions;
-    identity: ErrorIdentity;
-    capturePII?: boolean;
-    /** Injectable for deterministic tests. */
-    now?: number;
-    id?: string;
-}
-/**
- * buildSentryEvent turns a throwable + identity into a Sentry `event`. The message
- * (the leak surface) is scrubbed client-side; the user is ONLY the stable subject
- * id — never email/username/ip. Level defaults to error, or fatal for uncaught.
- */
-export declare function buildSentryEvent(input: BuildEventInput): SentryEvent;
-/**
- * buildEnvelope frames a Sentry event into a newline-delimited envelope:
- *
- *   {"event_id","dsn","sent_at"}\n
- *   {"type":"event","content_type":"application/json","length":N}\n
- *   <event json>\n
- *
- * The item is length-delimited (N = UTF-8 byte length) — the framing the server's
- * parseEnvelope reads first (falling back to newline-delimited otherwise).
- */
-export declare function buildEnvelope(event: SentryEvent, dsn: Dsn, sentAt?: string): string;
-//# sourceMappingURL=sentry.d.ts.map

package/dist/sentry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sentry.d.ts","sourceRoot":"","sources":["../src/sentry.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,mBAAmB,EACnB,GAAG,EACH,WAAW,EACX,WAAW,EAEZ,MAAM,SAAS,CAAA;AAahB;mEACmE;AACnE,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAUD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAqBnE;AAiBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,EAAE,CAkDxE;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAoB9F;AAsBD,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,QAAQ,EAAE,aAAa,CAAA;IACvB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAiBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CAqDpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAanF"}

package/src/dsn.test.ts

@@ -1,75 +0,0 @@
-import { describe, it, expect, afterEach } from 'vitest'
-
-import { createAnalytics } from './core'
-import { PRODUCT_PROJECT, dsnForProduct } from './dsn'
-import { parseDsn } from './sentry'
-
-const ENV = 'NEXT_PUBLIC_HANZO_EVENT_DSN'
-const OVERRIDE = 'https://1:aaaa@api.hanzo.ai/v1/event/env-project'
-const EXPLICIT = 'https://1:bbbb@api.hanzo.ai/v1/event/explicit-project'
-// A stand-in for the surface's own resolved key — the DSN carries whatever key
-// the caller resolved (config or the KMS-sourced env), never a literal.
-const KEY = 'pk-test-resolved-key'
-
-afterEach(() => {
-  delete process.env[ENV]
-})
-
-describe('the product registry', () => {
-  it('builds a product DSN from the CALLER key + the project — nothing baked', () => {
-    expect(dsnForProduct('console', KEY)).toBe(
-      `https://${KEY}@api.hanzo.ai/v1/event/${PRODUCT_PROJECT.console}`
-    )
-    expect(dsnForProduct('site', KEY)).toBe(
-      `https://${KEY}@api.hanzo.ai/v1/event/${PRODUCT_PROJECT.site}`
-    )
-  })
-
-  it('returns undefined without a key or without a project, rather than guessing', () => {
-    expect(dsnForProduct('console', undefined)).toBeUndefined() // no key -> inert
-    expect(dsnForProduct('not-a-product', KEY)).toBeUndefined()
-    expect(dsnForProduct(undefined, KEY)).toBeUndefined()
-    expect(dsnForProduct('', KEY)).toBeUndefined()
-  })
-
-  it('every product DSN parses to the caller key + its own project id', () => {
-    for (const [product, projectId] of Object.entries(PRODUCT_PROJECT)) {
-      const parsed = parseDsn(dsnForProduct(product, KEY))
-      expect(parsed, `${product} DSN must parse`).not.toBeNull()
-      expect(parsed!.projectId, `${product} project id`).toBe(projectId)
-      expect(parsed!.publicKey, `${product} carries the resolved key`).toBe(KEY)
-    }
-  })
-})
-
-describe('DSN precedence — most specific source wins', () => {
-  it('lights up the error plane from `product` + a resolved key, with no explicit dsn', () => {
-    const a = createAnalytics({ product: 'console', ingestKey: KEY, enabled: false })
-    expect(a.errorPlaneEnabled).toBe(true)
-    expect(a.errorIngestUrl).toContain(PRODUCT_PROJECT.console)
-  })
-
-  it('prefers an explicit dsn over both the env and the registry', () => {
-    process.env[ENV] = OVERRIDE
-    const a = createAnalytics({ product: 'console', ingestKey: KEY, dsn: EXPLICIT, enabled: false })
-    expect(a.errorIngestUrl).toContain('explicit-project')
-  })
-
-  it('prefers the env override over the registry, so a deploy can repoint a surface', () => {
-    process.env[ENV] = OVERRIDE
-    const a = createAnalytics({ product: 'console', ingestKey: KEY, enabled: false })
-    expect(a.errorIngestUrl).toContain('env-project')
-  })
-
-  it('stays inert for an unregistered product — never posts one surface into another project', () => {
-    const a = createAnalytics({ product: 'not-a-product', ingestKey: KEY, enabled: false })
-    expect(a.errorPlaneEnabled).toBe(false)
-    expect(a.errorIngestUrl).toBeUndefined()
-  })
-
-  it('stays inert with a product but no key — the error plane needs the live key', () => {
-    const a = createAnalytics({ product: 'console', enabled: false })
-    expect(a.errorPlaneEnabled).toBe(false)
-    expect(a.errorIngestUrl).toBeUndefined()
-  })
-})

package/src/dsn.ts

@@ -1,56 +0,0 @@
-/**
- * The product → Sentinel DSN registry.
- *
- * An app declares WHAT it is (`product: 'console'`); this module knows WHERE its
- * errors go. That split is the whole point: no surface has to learn a DSN, carry
- * a build argument, or grow a config file to report errors — declaring the
- * product it already declares is enough.
- *
- * A Sentinel DSN is PUBLIC by construction. It ships inside the client bundle and
- * is readable in devtools on any deployed page, and it grants exactly one
- * capability: submitting new events. It cannot read issues, projects, or any
- * other data. So committing it is not leaking a secret — it is recording a public
- * identifier next to the code that needs it. (Contrast the server-side collector
- * DSN in the `team-analytics-sentry` Secret, which is HMAC-derived and revocable
- * precisely because a server-side credential is NOT public.)
- *
- * Why a literal map instead of deriving `hanzo-${product}`: the projects predate
- * this registry and do not derive cleanly — `site` lives in `hanzo-ai`, not
- * `hanzo-site`. An explicit map is honest about that; a derivation rule plus an
- * exception table is the same data with a trap in it.
- *
- * Projects are org-scoped and named `<org>-<app>`. To add one: create the project
- * (POST /v1/sentinel/projects with X-Org-Id), then add its `dsn` here keyed by the
- * product name the app passes to `createAnalytics`.
- */
-
-/** PRODUCT_PROJECT maps a `product` to its Sentinel project id. The DSN's KEY is no
- *  longer a per-project secret — it is the ONE org publishable key (below), so a
- *  surface's errors ride the SAME key its events do. The id only names WHICH
- *  project the errors group under, and cloud auto-provisions that project on first
- *  keyed ingest, so a new id needs nothing minted. `site` lives in the `hanzo-ai`
- *  project — an explicit map, because the projects predate this and do not derive
- *  cleanly from the product name. */
-export const PRODUCT_PROJECT: Readonly<Record<string, string>> = Object.freeze({
-  console: '019fa40b-94ae-7f1d-8f7b-e92f123fad42', // console.hanzo.ai
-  app: '019f9b1e-57eb-7171-9d92-72c0b85e4b4b', // hanzo.app
-  site: '019f9b1e-5785-7359-ad0b-f75db8e58c99', // hanzo.ai (marketing; product `site`)
-})
-
-/** dsnForProduct builds the product's Sentinel DSN from the caller's resolved
- *  publishable `key` and the product's project — the SAME key the event stream
- *  carries, at the product's envelope endpoint. Returns undefined when there is no
- *  key or no project for the product, leaving the error plane inert rather than
- *  posting into the wrong one. The key is NOT baked here: it is the value the
- *  surface resolved (an explicit `ingestKey`, or the KMS-sourced
- *  NEXT_PUBLIC_PUBLISHABLE_KEY the build inlines) — the ONE live source, never a
- *  literal committed beside the code. */
-export function dsnForProduct(
-  product: string | undefined,
-  key: string | undefined
-): string | undefined {
-  if (!product || !key) return undefined
-  const projectId = PRODUCT_PROJECT[product]
-  if (!projectId) return undefined
-  return `https://${key}@api.hanzo.ai/v1/event/${projectId}`
-}