@hanzo/event 0.3.0 → 0.3.2

package/src/sentry.ts

@@ -0,0 +1,279 @@
+// Pure builders for the error path: parse a Hanzo-minted DSN, turn a JS Error into
+// a Sentry `event`, and frame it into a Sentry envelope. No I/O, no globals — the
+// Analytics client (core.ts) wires these to identity + transport.
+//
+// The wire shapes are a from-scratch model of the PUBLIC, documented Sentry ingest
+// protocol (develop.sentry.dev), verified against the Hanzo /v1/sentry ingest
+// (o11y pkg/modules/errortracking/implerrortracking: parseEnvelope, SentryEvent,
+// normalizeEvent, computeFingerprint). No upstream (FSL) code is used.
+
+import { scrubText } from './scrub'
+import { VERSION } from './version'
+import type {
+  CaptureErrorOptions,
+  Dsn,
+  SentryEvent,
+  SentryFrame,
+  SentryLevel,
+} from './types'
+
+/** Max stack frames kept — well under the server's 250 cap, plenty for grouping. */
+const MAX_FRAMES = 50
+/** Max stack lines examined, and max length of a line worth examining. Guards the
+ *  frame regexes against a hostile `stack` string (see framesFromStack). */
+const MAX_LINES = 500
+const MAX_LINE_LEN = 2048
+/** Max tag string length, so one huge property can't bloat the envelope. */
+const MAX_TAG_LEN = 1024
+/** Max tags copied from properties. */
+const MAX_TAGS = 50
+
+/** eventId mints a 32-hex-char id (no dashes) — the Sentry event_id shape. */
+export function eventId(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && 'randomUUID' in c) return c.randomUUID().replace(/-/g, '')
+  let s = ''
+  for (let i = 0; i < 32; i++) s += Math.floor(Math.random() * 16).toString(16)
+  return s
+}
+
+/** byteLen returns the UTF-8 byte length used for envelope item framing. */
+function byteLen(s: string): number {
+  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(s).length
+  // Node fallback.
+  if (typeof Buffer !== 'undefined') return Buffer.byteLength(s, 'utf8')
+  return s.length
+}
+
+/**
+ * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<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 function parseDsn(dsn: string | undefined | null): Dsn | null {
+  if (!dsn) return null
+  const m = /^(https?):\/\/([^@]+)@([^/]+)(\/.*)?$/.exec(dsn.trim())
+  if (!m) return null
+  const scheme = m[1]
+  const publicKey = m[2]
+  const host = m[3]
+  const path = m[4] ?? ''
+  if (!publicKey || !host) return null
+  const segs = path.split('/').filter(Boolean)
+  const projectId = segs.length > 0 ? segs[segs.length - 1] : ''
+  if (!projectId) return null
+  const origin = `${scheme}://${host}`
+  const ingestUrl =
+    `${origin}/v1/sentry/${encodeURIComponent(projectId)}/envelope/` +
+    `?sentry_key=${encodeURIComponent(publicKey)}`
+  return { publicKey, origin, projectId, ingestUrl }
+}
+
+const V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+)|([^)]+))\)?\s*$/
+const MOZ_FRAME = /^\s*(?:(.*?)@)?(.+?):(\d+):(\d+)\s*$/
+
+/** inApp marks a frame as the app's own code (vs vendor/runtime) for grouping. */
+function inApp(file: string): boolean {
+  if (!file) return false
+  return !(
+    file.includes('node_modules') ||
+    file.startsWith('webpack-internal') ||
+    file.startsWith('webpack://') ||
+    file.startsWith('chrome-extension://') ||
+    file.startsWith('moz-extension://')
+  )
+}
+
+/**
+ * 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 function framesFromStack(stack: string | undefined): SentryFrame[] {
+  if (!stack) return []
+  // Both frame regexes use lazy nested quantifiers, which backtrack badly on a
+  // long line that never matches. A stack is attacker-influenced (a thrown value
+  // can carry any `stack` string), so bound the work: skip absurd lines and stop
+  // after MAX_LINES. Only the innermost MAX_FRAMES are kept anyway.
+  const lines = stack.split('\n', MAX_LINES)
+  const frames: SentryFrame[] = []
+  for (const raw of lines) {
+    if (raw.length > MAX_LINE_LEN) continue
+    const line = raw.trimEnd()
+    if (!line) continue
+    // Header lines like "TypeError: x is not a function" match neither frame
+    // regex (no "at " prefix, no trailing :line:col) and are skipped naturally.
+    let fn: string | undefined
+    let file = ''
+    let lineno = 0
+    let colno = 0
+    const v = V8_FRAME.exec(line)
+    if (v) {
+      fn = v[1]
+      if (v[2]) {
+        file = v[2]
+        lineno = Number(v[3]) || 0
+        colno = Number(v[4]) || 0
+      } else {
+        file = (v[5] || '').trim()
+      }
+    } else {
+      const f = MOZ_FRAME.exec(line)
+      if (!f) continue
+      fn = f[1]
+      file = f[2]
+      lineno = Number(f[3]) || 0
+      colno = Number(f[4]) || 0
+    }
+    if (!file && !fn) continue
+    frames.push({
+      function: fn || '<anonymous>',
+      filename: file,
+      abs_path: file,
+      lineno,
+      colno,
+      in_app: inApp(file),
+    })
+  }
+  // Reverse to oldest-first and cap to the innermost MAX_FRAMES.
+  frames.reverse()
+  if (frames.length > MAX_FRAMES) return frames.slice(frames.length - MAX_FRAMES)
+  return frames
+}
+
+/** normalizeError coerces an unknown throwable into {name, message, stack}. */
+export function normalizeError(err: unknown): { name: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    return { name: err.name || 'Error', message: err.message || String(err), stack: err.stack }
+  }
+  if (typeof err === 'string') return { name: 'Error', message: err }
+  try {
+    return { name: 'Error', message: JSON.stringify(err) }
+  } catch {
+    return { name: 'Error', message: String(err) }
+  }
+}
+
+/** 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
+}
+
+function coerceTag(v: unknown): string {
+  const s = typeof v === 'string' ? v : (() => {
+    try {
+      return JSON.stringify(v) ?? String(v)
+    } catch {
+      try {
+        return String(v) // circular — fall back to the primitive coercion
+      } catch {
+        return '[unstringifiable]' // ...which a throwing toString can also refuse
+      }
+    }
+  })()
+  return s.length > MAX_TAG_LEN ? s.slice(0, MAX_TAG_LEN) : s
+}
+
+/**
+ * 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 function buildSentryEvent(input: BuildEventInput): SentryEvent {
+  const { error, options = {}, identity, capturePII = false } = input
+  const norm = normalizeError(error)
+  const handled = options.handled !== false
+  const level: SentryLevel = options.level ?? (handled ? 'error' : 'fatal')
+
+  const tags: Record<string, string> = { handled: String(handled) }
+  if (identity.product) tags.product = identity.product
+  if (identity.sessionId) tags.session = identity.sessionId
+  // Tags come from arbitrary caller `properties`. Read each key in isolation:
+  // Object.entries() invokes every getter at once, so one throwing getter would
+  // cost us the entire envelope — losing the stack trace to save a tag. Keys are
+  // optional; the exception is not.
+  try {
+    const props = (options.properties ?? {}) as Record<string, unknown>
+    let n = 0
+    for (const k of Object.keys(props)) {
+      if (n >= MAX_TAGS) break
+      try {
+        const val = props[k]
+        if (val === undefined || val === null) continue
+        tags[k] = scrubText(coerceTag(val), capturePII)
+        n++
+      } catch {
+        continue // throwing getter or unstringifiable value — skip this key only
+      }
+    }
+  } catch {
+    /* unenumerable/exotic properties object — ship the exception without tags */
+  }
+
+  const event: SentryEvent = {
+    event_id: input.id ?? eventId(),
+    timestamp: (input.now ?? Date.now()) / 1000,
+    platform: 'javascript',
+    level,
+    logger: identity.product,
+    environment: identity.environment,
+    release: identity.release,
+    exception: {
+      values: [
+        {
+          type: norm.name,
+          value: scrubText(norm.message, capturePII),
+          stacktrace: { frames: framesFromStack(norm.stack) },
+        },
+      ],
+    },
+    tags,
+    sdk: { name: '@hanzo/event', version: VERSION },
+  }
+  if (identity.userId) event.user = { id: identity.userId }
+  return event
+}
+
+/**
+ * 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 function buildEnvelope(event: SentryEvent, dsn: Dsn, sentAt?: string): string {
+  const payload = JSON.stringify(event)
+  const header = JSON.stringify({
+    event_id: event.event_id,
+    dsn: `${dsn.origin}/v1/sentry/${dsn.projectId}`,
+    sent_at: sentAt ?? new Date().toISOString(),
+  })
+  const itemHeader = JSON.stringify({
+    type: 'event',
+    content_type: 'application/json',
+    length: byteLen(payload),
+  })
+  return `${header}\n${itemHeader}\n${payload}\n`
+}

package/src/types.ts

@@ -1,13 +1,15 @@
 // 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 (Cloud stamps type:'error' → event_type='error',
- *  the key the error-tracking lens filters on). */
+/** 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. */
 export type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error'
 
-/** 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). */
+/** 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. */
 export interface Exception {
   /** Constructor/class name, e.g. "TypeError". */
   type?: string
@@ -70,7 +72,8 @@ export interface WireEvent {
   revenue?: number
   currency?: string
   /** Set on `type:'error'` events — the captured exception. Cloud lifts it into
-   *  properties.$exception (foldException) for the error-tracking lens. */
+   *  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
@@ -82,8 +85,21 @@ export interface WireEvent {
  *  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; ingestKey?: string }): void
+  /** 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
 }
 
 export interface AnalyticsConfig {
@@ -99,10 +115,11 @@ export interface AnalyticsConfig {
   /** 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. */
+   *  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
@@ -111,11 +128,96 @@ 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) as error events. Browser-only. Defaults to enabled —
-   *  this is what makes the client a drop-in @sentry replacement. */
+   *  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
+
+  // ── error plane (Sentry envelope -> sentry.hanzo.ai) ──────────────────────
+
+  /** 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
+}
+
+// ── Sentry envelope wire types (a from-scratch model of the PUBLIC, documented
+//    Sentry ingest protocol — develop.sentry.dev; no upstream code) ───────────
+
+export type SentryLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug'
+
+export interface SentryFrame {
+  filename?: string
+  function?: string
+  module?: string
+  abs_path?: string
+  lineno?: number
+  colno?: number
+  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
+  /** Fully-derived envelope ingest URL incl. ?sentry_key=. */
+  ingestUrl: string
+}
+
+/** Options for Analytics.captureError. */
+export 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
 }

package/src/version.ts

@@ -0,0 +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.2'

package/dist/core-CrbiAQhN.d.cts

@@ -1,186 +0,0 @@
-/** The event kinds — the closed set the server understands. An error is just
- *  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'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;
-    /** 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 error-tracking lens. */
-    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). */
-    send(url: string, body: string, opts: {
-        beacon: boolean;
-        token?: string;
-        ingestKey?: string;
-    }): 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 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. */
-    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) as error events. Browser-only. Defaults to enabled —
-     *  this is what makes the client a drop-in @sentry replacement. */
-    captureErrors?: boolean;
-    /** Override the transport (tests). */
-    transport?: Transport;
-    /** Debug logging. */
-    debug?: boolean;
-}
-
-declare const VERSION = "0.3.0";
-declare class Analytics {
-    private cfg;
-    private transport;
-    private queue;
-    private timer;
-    private personId?;
-    private attribution;
-    private cohort;
-    private started;
-    constructor(config: AnalyticsConfig);
-    /** 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 records an exception as a first-class error event — the ONE
-     *  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>;
-    }): void;
-    /** captureException — @sentry-familiar alias of captureError. */
-    captureException: (err: unknown, context?: {
-        handled?: boolean;
-        properties?: Record<string, unknown>;
-    }) => 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;
-    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 EventKind as E, type Transport as T, VERSION as V, type WireEvent as W, Analytics as a, type AnalyticsConfig as b, type Exception as c, createAnalytics as d };