@hanzo/event 0.3.1 → 0.3.3

package/dist/index.mjs

@@ -46,16 +46,16 @@ function deriveChannel(a) {
 }
 function hostOf(raw) {
   if (!raw) return "";
-  let s = raw.trim();
-  const scheme = s.indexOf("://");
-  if (scheme >= 0) s = s.slice(scheme + 3);
-  const cut = s.search(/[/?#]/);
-  if (cut >= 0) s = s.slice(0, cut);
-  const at = s.indexOf("@");
-  if (at >= 0) s = s.slice(at + 1);
-  const colon = s.indexOf(":");
-  if (colon >= 0) s = s.slice(0, colon);
-  return s.toLowerCase().trim();
+  let s2 = raw.trim();
+  const scheme = s2.indexOf("://");
+  if (scheme >= 0) s2 = s2.slice(scheme + 3);
+  const cut = s2.search(/[/?#]/);
+  if (cut >= 0) s2 = s2.slice(0, cut);
+  const at = s2.indexOf("@");
+  if (at >= 0) s2 = s2.slice(at + 1);
+  const colon = s2.indexOf(":");
+  if (colon >= 0) s2 = s2.slice(0, colon);
+  return s2.toLowerCase().trim();
 }
 function hasAttribution(a) {
   return Boolean(
@@ -78,6 +78,12 @@ var EVENTS = {
   SIGNUP_SUBMITTED: "signup_submitted",
   SIGNUP_VERIFIED: "signup_verified",
   SIGNUP_COMPLETED: "signup_completed",
+  /** A RETURNING user authenticated — the non-signup half of the IAM callback.
+   *  Keeping it distinct is what stops returning logins from inflating signups. */
+  LOGIN_COMPLETED: "login_completed",
+  /** Activation: the first moment of real value. ONE event for every product —
+   *  the product-specific moment is the `action` property (api_call, app_live,
+   *  chat_reply), never a new event name. */
   FIRST_ACTION: "first_action",
   // Waitlist + referral.
   WAITLIST_JOINED: "waitlist_joined",
@@ -93,16 +99,308 @@ var EVENTS = {
   FEATURE_USED: "feature_used",
   API_KEY_CREATED: "api_key_created",
   APP_CREATED: "app_created",
-  DEPLOY_STARTED: "deploy_started",
   PROJECT_CREATED: "project_created",
   AGENT_CREATED: "agent_created",
   CHAT_STARTED: "chat_started",
   CHAT_MESSAGE_SENT: "chat_message_sent",
+  /** The user switched model/endpoint — the single strongest quality signal a
+   *  chat surface emits (a switch usually follows a bad answer). */
+  MODEL_SWITCHED: "model_switched",
   TASK_STARTED: "task_started",
-  TASK_COMPLETED: "task_completed"
+  TASK_COMPLETED: "task_completed",
+  // Build → ship. `build_*` is a MODEL producing an artifact; `deploy_*` is that
+  // artifact going live. Intent (build_started) is never the same event as the
+  // artifact existing (app_created) — conflating them makes the funnel lie.
+  BUILD_STARTED: "build_started",
+  /** A model finished producing an artifact (an app build, a chat reply, an agent
+   *  run). Carries `durationMs` — the outcome event owns its own duration, so no
+   *  paired start event is needed. */
+  GENERATION_COMPLETED: "generation_completed",
+  GENERATION_FAILED: "generation_failed",
+  DEPLOY_STARTED: "deploy_started",
+  DEPLOY_SUCCEEDED: "deploy_succeeded",
+  DEPLOY_FAILED: "deploy_failed"
 };
 var PAGEVIEW = "$pageview";
 
+// src/scrub.ts
+var REDACTED = "[redacted]";
+var EMAIL_MARK = "[email]";
+var IP_MARK = "[ip]";
+var SECRET_PATTERNS = [
+  /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/g,
+  /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g,
+  // JWT
+  /\bbearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi,
+  // bearer token
+  /\b(?:sk|pk|rk)-[A-Za-z0-9]{2,}-?[A-Za-z0-9]{12,}/g,
+  // openai-style
+  /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{16,}/g,
+  // stripe
+  /\bhk-[A-Za-z0-9]{16,}/g,
+  // hanzo key
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  // aws access key id
+  /\bASIA[0-9A-Z]{16}\b/g,
+  // aws sts key id
+  /\bAIza[0-9A-Za-z_-]{20,}/g,
+  // google api key
+  /\bgh[posru]_[A-Za-z0-9]{20,}/g,
+  // github token
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,
+  // slack token
+  // Creds in a URL/DSN. The repetition is BOUNDED on purpose: the unbounded form
+  // ([^\s:@/]+:[^\s@/]+@) backtracks quadratically on colon-rich text with no
+  // terminating '@' — an HTML error page pasted into an error message took 4.9s
+  // at 32KB and >60s at 128KB, freezing the main thread from inside captureError.
+  // Real userinfo is far below these caps, so bounding costs nothing.
+  /[a-zA-Z][a-zA-Z0-9+.-]{0,32}:\/\/[^\s:@/]{1,256}:[^\s@/]{1,256}@/g
+];
+var RE_PAN = /\b(?:\d[ -]?){13,19}\b/g;
+function luhn(digits) {
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (alt) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+function redactPAN(s2) {
+  return s2.replace(RE_PAN, (m) => {
+    const digits = m.replace(/[ -]/g, "");
+    if (digits.length < 13 || digits.length > 19) return m;
+    return luhn(digits) ? REDACTED : m;
+  });
+}
+var RE_EMAIL = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}/g;
+var RE_IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g;
+var RE_IPV6 = /\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{1,4}\b/g;
+function redactSecrets(s2) {
+  for (const re of SECRET_PATTERNS) s2 = s2.replace(re, REDACTED);
+  return redactPAN(s2);
+}
+function scrubPII(s2) {
+  s2 = s2.replace(RE_EMAIL, EMAIL_MARK);
+  s2 = s2.replace(RE_IPV6, IP_MARK);
+  s2 = s2.replace(RE_IPV4, IP_MARK);
+  return s2;
+}
+var MAX_SCRUB_LEN = 8192;
+function truncate(s2, max = MAX_SCRUB_LEN) {
+  return s2.length > max ? s2.slice(0, max) + "\u2026 [truncated]" : s2;
+}
+function scrubText(s2, capturePII = false) {
+  if (!s2) return s2 ?? "";
+  s2 = truncate(s2);
+  s2 = redactSecrets(s2);
+  if (!capturePII) s2 = scrubPII(s2);
+  return s2;
+}
+
+// src/version.ts
+var VERSION = "0.3.3";
+
+// src/sentry.ts
+var MAX_FRAMES = 50;
+var MAX_LINES = 500;
+var MAX_LINE_LEN = 2048;
+var MAX_TAG_LEN = 1024;
+var MAX_TAGS = 50;
+function eventId() {
+  const c = typeof crypto !== "undefined" ? crypto : void 0;
+  if (c && "randomUUID" in c) return c.randomUUID().replace(/-/g, "");
+  let s2 = "";
+  for (let i = 0; i < 32; i++) s2 += Math.floor(Math.random() * 16).toString(16);
+  return s2;
+}
+function byteLen(s2) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s2).length;
+  if (typeof Buffer !== "undefined") return Buffer.byteLength(s2, "utf8");
+  return s2.length;
+}
+function parseDsn(dsn) {
+  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 };
+}
+var V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+)|([^)]+))\)?\s*$/;
+var MOZ_FRAME = /^\s*(?:(.*?)@)?(.+?):(\d+):(\d+)\s*$/;
+function inApp(file) {
+  if (!file) return false;
+  return !(file.includes("node_modules") || file.startsWith("webpack-internal") || file.startsWith("webpack://") || file.startsWith("chrome-extension://") || file.startsWith("moz-extension://"));
+}
+function framesFromStack(stack) {
+  if (!stack) return [];
+  const lines = stack.split("\n", MAX_LINES);
+  const frames = [];
+  for (const raw of lines) {
+    if (raw.length > MAX_LINE_LEN) continue;
+    const line = raw.trimEnd();
+    if (!line) continue;
+    let fn;
+    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)
+    });
+  }
+  frames.reverse();
+  if (frames.length > MAX_FRAMES) return frames.slice(frames.length - MAX_FRAMES);
+  return frames;
+}
+function normalizeError(err) {
+  if (err instanceof Error) {
+    const name = read(err, "name");
+    const message = read(err, "message");
+    const stack = read(err, "stack");
+    return {
+      name: typeof name === "string" && name ? name : "Error",
+      message: typeof message === "string" && message ? message : str(err),
+      stack: typeof stack === "string" ? stack : void 0
+    };
+  }
+  if (typeof err === "string") return { name: "Error", message: err };
+  try {
+    return { name: "Error", message: JSON.stringify(err) ?? str(err) };
+  } catch {
+    return { name: "Error", message: str(err) };
+  }
+}
+function read(o, k) {
+  try {
+    return o[k];
+  } catch {
+    return void 0;
+  }
+}
+function str(v) {
+  try {
+    return String(v);
+  } catch {
+    return "[unstringifiable]";
+  }
+}
+function coerceTag(v) {
+  const s2 = typeof v === "string" ? v : (() => {
+    try {
+      return JSON.stringify(v) ?? String(v);
+    } catch {
+      try {
+        return String(v);
+      } catch {
+        return "[unstringifiable]";
+      }
+    }
+  })();
+  return s2.length > MAX_TAG_LEN ? s2.slice(0, MAX_TAG_LEN) : s2;
+}
+function buildSentryEvent(input) {
+  const { error, options = {}, identity, capturePII = false } = input;
+  const norm = normalizeError(error);
+  const handled = options.handled !== false;
+  const level = options.level ?? (handled ? "error" : "fatal");
+  const tags = { handled: String(handled) };
+  if (identity.product) tags.product = identity.product;
+  if (identity.sessionId) tags.session = identity.sessionId;
+  try {
+    const props = options.properties ?? {};
+    let n = 0;
+    for (const k of Object.keys(props)) {
+      if (n >= MAX_TAGS) break;
+      try {
+        const val = props[k];
+        if (val === void 0 || val === null) continue;
+        tags[k] = scrubText(coerceTag(val), capturePII);
+        n++;
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+  }
+  const event = {
+    event_id: input.id ?? eventId(),
+    timestamp: (input.now ?? Date.now()) / 1e3,
+    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;
+}
+function buildEnvelope(event, dsn, sentAt) {
+  const payload = JSON.stringify(event);
+  const header = JSON.stringify({
+    event_id: event.event_id,
+    dsn: `${dsn.origin}/v1/sentry/${dsn.projectId}`,
+    sent_at: sentAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const itemHeader = JSON.stringify({
+    type: "event",
+    content_type: "application/json",
+    length: byteLen(payload)
+  });
+  return `${header}
+${itemHeader}
+${payload}
+`;
+}
+
 // src/storage.ts
 var KEY = {
   anon: "hz_anon_id",
@@ -125,21 +423,21 @@ function uid() {
   return "a-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
 }
 function anonId() {
-  const s = ls();
-  if (!s) return void 0;
-  let v = s.getItem(KEY.anon);
+  const s2 = ls();
+  if (!s2) return void 0;
+  let v = s2.getItem(KEY.anon);
   if (!v) {
     v = uid();
-    s.setItem(KEY.anon, v);
+    s2.setItem(KEY.anon, v);
   }
   return v;
 }
 function sessionId(now = Date.now()) {
-  const s = ls();
-  if (!s) return void 0;
+  const s2 = ls();
+  if (!s2) return void 0;
   let state = null;
   try {
-    state = JSON.parse(s.getItem(KEY.session) || "null");
+    state = JSON.parse(s2.getItem(KEY.session) || "null");
   } catch {
     state = null;
   }
@@ -148,52 +446,68 @@ function sessionId(now = Date.now()) {
   } else {
     state.last = now;
   }
-  s.setItem(KEY.session, JSON.stringify(state));
+  s2.setItem(KEY.session, JSON.stringify(state));
   return state.id;
 }
 function getFirstTouch() {
-  const s = ls();
-  if (!s) return void 0;
+  const s2 = ls();
+  if (!s2) return void 0;
   try {
-    const v = s.getItem(KEY.firstTouch);
+    const v = s2.getItem(KEY.firstTouch);
     return v ? JSON.parse(v) : void 0;
   } catch {
     return void 0;
   }
 }
 function setFirstTouchOnce(a) {
-  const s = ls();
+  const s2 = ls();
   const existing = getFirstTouch();
   if (existing) return existing;
-  if (s) s.setItem(KEY.firstTouch, JSON.stringify(a));
+  if (s2) s2.setItem(KEY.firstTouch, JSON.stringify(a));
   return a;
 }
 function getCohort() {
-  const s = ls();
-  if (!s) return void 0;
+  const s2 = ls();
+  if (!s2) return void 0;
   try {
-    const v = s.getItem(KEY.cohort);
+    const v = s2.getItem(KEY.cohort);
     return v ? JSON.parse(v) : void 0;
   } catch {
     return void 0;
   }
 }
 function mergeCohort(patch) {
-  const s = ls();
+  const s2 = ls();
   const cur = getCohort() || {};
   const next = {
     signupWeek: cur.signupWeek || patch.signupWeek,
     channel: patch.channel || cur.channel,
     refCode: cur.refCode || patch.refCode
   };
-  if (s) s.setItem(KEY.cohort, JSON.stringify(next));
+  if (s2) s2.setItem(KEY.cohort, JSON.stringify(next));
   return next;
 }
 
 // src/core.ts
-var VERSION = "0.3.0";
 var EVENT_PATH = "/v1/event";
 var DEFAULT_HOST = "https://api.hanzo.ai";
+var ENVELOPE_CONTENT_TYPE = "application/x-sentry-envelope";
+function readEnvDsn() {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return process.env.NEXT_PUBLIC_HANZO_EVENT_DSN || process.env.HANZO_EVENT_DSN || void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function readEnv(name) {
+  try {
+    if (typeof process !== "undefined" && process.env) return process.env[name] || void 0;
+  } catch {
+  }
+  return void 0;
+}
 function appendQuery(url, key, value) {
   return url + (url.includes("?") ? "&" : "?") + key + "=" + encodeURIComponent(value);
 }
@@ -202,30 +516,42 @@ function uid2() {
   if (c && "randomUUID" in c) return c.randomUUID();
   return "m-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
 }
-function normalizeError(err) {
-  if (err instanceof Error) {
-    return { type: err.name, message: err.message, stack: err.stack };
-  }
-  if (typeof err === "string") return { message: err };
+function normalizeError2(err) {
+  const n = normalizeError(err);
+  return { type: n.name, message: n.message, stack: n.stack };
+}
+var isBrowser = () => typeof window !== "undefined";
+function serializeBatch(batch) {
   try {
-    return { message: JSON.stringify(err) };
+    return JSON.stringify({ batch });
   } catch {
-    return { message: String(err) };
   }
+  const parts = [];
+  for (const e of batch) {
+    try {
+      parts.push(JSON.stringify(e));
+    } catch {
+      try {
+        parts.push(JSON.stringify({ ...e, properties: { $unserializable: true } }));
+      } catch {
+      }
+    }
+  }
+  return parts.length > 0 ? '{"batch":[' + parts.join(",") + "]}" : null;
 }
-var isBrowser = () => typeof window !== "undefined";
 var DefaultTransport = class {
   send(url, body, opts) {
+    const contentType = opts.contentType ?? "application/json";
     if (opts.beacon && isBrowser() && typeof navigator.sendBeacon === "function") {
       const beaconUrl = opts.ingestKey ? appendQuery(url, "ingest_key", opts.ingestKey) : url;
       try {
-        navigator.sendBeacon(beaconUrl, new Blob([body], { type: "application/json" }));
+        navigator.sendBeacon(beaconUrl, new Blob([body], { type: contentType }));
         return;
       } catch {
       }
     }
     if (typeof fetch !== "function") return;
-    const headers = { "Content-Type": "application/json" };
+    const headers = { "Content-Type": contentType };
     const bearer = opts.ingestKey ?? opts.token;
     if (bearer) headers.Authorization = `Bearer ${bearer}`;
     void fetch(url, {
@@ -234,7 +560,12 @@ var DefaultTransport = class {
       body,
       keepalive: true,
       credentials: "include"
-    }).catch(() => {
+    }).then((res) => {
+      if (!res.ok && opts.debug) {
+        console.warn("[event] ingest rejected", res.status, url.split("?")[0]);
+      }
+    }).catch((e) => {
+      if (opts.debug) console.warn("[event] ingest failed", url.split("?")[0], e);
     });
   }
 };
@@ -245,6 +576,8 @@ var Analytics = class {
     this.attribution = { utm: {} };
     this.cohort = {};
     this.started = false;
+    /** Guards against an error thrown *inside* the error path re-entering it. */
+    this.reentrant = false;
     /** track is an alias of capture (Segment familiarity). */
     this.track = this.capture.bind(this);
     /** captureException — @sentry-familiar alias of captureError. */
@@ -258,6 +591,19 @@ var Analytics = class {
       ...config
     };
     this.transport = config.transport ?? new DefaultTransport();
+    this.dsn = parseDsn(config.dsn ?? readEnvDsn());
+  }
+  /** 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() {
+    return this.dsn !== null;
+  }
+  /** errorIngestUrl is the fully-derived envelope endpoint, or undefined when the
+   *  plane is inert. Diagnostics only. */
+  get errorIngestUrl() {
+    return this.dsn?.ingestUrl;
   }
   /** init is idempotent and browser-only for its side effects: capture first-touch
    *  attribution, hydrate cohort, register the unload flush, and (unless opted out)
@@ -308,18 +654,38 @@ var Analytics = class {
   capture(event, properties, commerce) {
     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, 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 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, context) {
-    const ex = normalizeError(err);
-    ex.handled = context?.handled ?? true;
-    this.enqueue("error", ex.message, { error: ex, properties: context?.properties });
-    this.flush();
+    if (this.reentrant) return;
+    this.reentrant = true;
+    try {
+      try {
+        this.sendError(err, context);
+      } catch {
+      }
+      try {
+        const ex = normalizeError2(err);
+        ex.handled = context?.handled ?? true;
+        this.enqueue("error", ex.message, { error: ex, properties: context?.properties });
+        this.flush();
+      } catch {
+      }
+    } finally {
+      this.reentrant = false;
+    }
   }
   /** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
    *  every subsequent event. */
@@ -345,11 +711,53 @@ var Analytics = class {
     const key = this.cfg.ingestKey?.trim() || void 0;
     const token = key ? void 0 : this.cfg.getToken?.() ?? void 0;
     const useBeacon = beacon && !token;
-    const body = JSON.stringify({ batch });
+    const body = serializeBatch(batch);
+    if (body === null) {
+      if (this.cfg.debug) console.debug("[event] flush \u2192 dropped, batch unserializable");
+      return;
+    }
     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 });
+    this.transport.send(this.cfg.host + EVENT_PATH, body, {
+      beacon: useBeacon,
+      token,
+      ingestKey: key,
+      debug: this.cfg.debug
+    });
   }
   // ── internals ────────────────────────────────────────────────────────────
+  /** 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. */
+  sendError(err, options) {
+    if (!this.cfg.enabled || !this.dsn) return;
+    const event = buildSentryEvent({
+      error: err,
+      options,
+      identity: this.errorIdentity(),
+      capturePII: this.cfg.capturePII ?? false
+    });
+    const body = buildEnvelope(event, this.dsn);
+    if (this.cfg.debug) console.debug("[event] error \u2192", this.dsn.ingestUrl, event.event_id);
+    this.transport.send(this.dsn.ingestUrl, body, {
+      beacon: false,
+      contentType: ENVELOPE_CONTENT_TYPE,
+      debug: this.cfg.debug
+    });
+  }
+  /** errorIdentity is the SAME identity the event stream stamps — the OIDC subject
+   *  once identify() has run, else the anon id. Never email/PII. */
+  errorIdentity() {
+    return {
+      userId: this.personId ?? anonId(),
+      sessionId: sessionId(),
+      product: this.cfg.product,
+      release: this.cfg.release ?? readEnv("NEXT_PUBLIC_HANZO_RELEASE"),
+      environment: this.cfg.environment ?? readEnv("NODE_ENV")
+    };
+  }
   enqueue(kind, event, extra) {
     if (!this.cfg.enabled) return;
     if (!this.started) this.init();
@@ -397,30 +805,139 @@ function createAnalytics(config) {
   return new Analytics(config);
 }
 
+// src/funnels.ts
+var PRODUCTS = ["site", "app", "chat", "console", "admin", "cloud"];
+var s = (event, label, where) => ({
+  event,
+  label,
+  ...where ? { where } : {}
+});
+var FUNNELS = {
+  /** hanzo.ai: land → sign up. IAM hosts the form, so `signup_submitted` is the
+   *  redirect INTO IAM and `signup_completed` is the return at /auth/callback. */
+  signup: {
+    label: "Signup",
+    products: ["site"],
+    join: "person",
+    steps: [
+      s(PAGEVIEW, "Landed"),
+      s(EVENTS.SIGNUP_VIEWED, "Opened signup"),
+      s(EVENTS.SIGNUP_SUBMITTED, "Redirected to Hanzo ID"),
+      s(EVENTS.SIGNUP_COMPLETED, "Account created"),
+      s(EVENTS.FIRST_ACTION, "First action")
+    ]
+  },
+  /** The developer activation path: an account is worth nothing until a key has
+   *  made a call. `first_action{action:'api_call'}` is emitted SERVER-SIDE by
+   *  Cloud on an org's first successful /v1 request — a browser cannot see it. */
+  apiActivation: {
+    label: "API activation",
+    products: ["site", "cloud"],
+    join: "person",
+    steps: [
+      s(EVENTS.SIGNUP_COMPLETED, "Account created"),
+      s(EVENTS.API_KEY_CREATED, "Key minted"),
+      s(EVENTS.FIRST_ACTION, "First successful API call", {
+        property: "action",
+        equals: "api_call"
+      })
+    ]
+  },
+  /** Upgrade intent → revenue. `order_completed{kind:'plan'}` is the Sale goal. */
+  upgrade: {
+    label: "Upgrade",
+    products: ["site", "app", "console"],
+    join: "person",
+    steps: [
+      s(EVENTS.PRICING_VIEWED, "Viewed pricing"),
+      s(EVENTS.PLAN_CLICKED, "Chose a plan"),
+      s(EVENTS.CHECKOUT_STARTED, "Started checkout"),
+      s(EVENTS.ORDER_COMPLETED, "Paid")
+    ]
+  },
+  /** hanzo.app: describe → build → deploy → live URL. The whole product thesis
+   *  in five steps; `deploy_succeeded` is the moment a live URL exists. */
+  appShip: {
+    label: "Describe \u2192 ship",
+    products: ["app"],
+    join: "person",
+    steps: [
+      s(PAGEVIEW, "Landed"),
+      s(EVENTS.BUILD_STARTED, "Described an app"),
+      s(EVENTS.GENERATION_COMPLETED, "Got a working build"),
+      s(EVENTS.DEPLOY_STARTED, "Hit publish"),
+      s(EVENTS.DEPLOY_SUCCEEDED, "Live URL")
+    ]
+  },
+  /** hanzo.chat: visit → first message → answer. `generation_completed` is what
+   *  separates "typed something" from "got value". */
+  chatEngage: {
+    label: "Chat engagement",
+    products: ["chat"],
+    join: "person",
+    steps: [
+      s(PAGEVIEW, "Landed"),
+      s(EVENTS.CHAT_STARTED, "Started a conversation"),
+      s(EVENTS.CHAT_MESSAGE_SENT, "Sent a message"),
+      s(EVENTS.GENERATION_COMPLETED, "Got an answer")
+    ]
+  },
+  /** The cross-surface handoff: the hanzo.ai composer forwards its prompt to
+   *  hanzo.chat. Two origins, two anonymousIds — so this is an AGGREGATE funnel.
+   *  The join is the `referrerProduct` property hanzo.chat reads off `?hz_ref=`,
+   *  which makes the drop-off measurable without any cross-domain identity. */
+  siteToChat: {
+    label: "Site \u2192 Chat handoff",
+    products: ["site", "chat"],
+    join: "aggregate",
+    steps: [
+      s(EVENTS.CHAT_STARTED, "Submitted the hanzo.ai composer", {
+        property: "source",
+        equals: "composer"
+      }),
+      s(EVENTS.CHAT_STARTED, "Landed in hanzo.chat", {
+        property: "referrerProduct",
+        equals: "site"
+      }),
+      s(EVENTS.GENERATION_COMPLETED, "Got an answer")
+    ]
+  }
+};
+function eventsOf(id) {
+  return FUNNELS[id].steps.map((step) => step.event);
+}
+
 // src/goals.ts
 var GOALS = {
-  // Signup: the conversion is signup_completed; the funnel is the four steps.
+  // Signup: the conversion is signup_completed, along the site signup funnel.
   signup: {
     label: "Signup",
     event: EVENTS.SIGNUP_COMPLETED,
-    funnel: [
-      EVENTS.SIGNUP_VIEWED,
-      EVENTS.SIGNUP_SUBMITTED,
-      EVENTS.SIGNUP_VERIFIED,
-      EVENTS.FIRST_ACTION
-    ]
+    funnelId: "signup",
+    funnel: eventsOf("signup")
   },
   // Sale: a completed order qualified as a plan purchase (kind=plan).
   sale: {
     label: "Sale",
     event: EVENTS.ORDER_COMPLETED,
+    funnelId: "upgrade",
+    funnel: eventsOf("upgrade"),
     filter: { property: "kind", equals: "plan" }
   },
   // Upgrade intent: a plan click; pricing_viewed is the top of its funnel.
   upgradeIntent: {
     label: "Upgrade Intent",
     event: EVENTS.PLAN_CLICKED,
-    funnel: [EVENTS.PRICING_VIEWED, EVENTS.PLAN_CLICKED, EVENTS.CHECKOUT_STARTED]
+    funnelId: "upgrade",
+    funnel: eventsOf("upgrade")
+  },
+  // Activation: the ONE north-star conversion — an account that did the first
+  // valuable thing (a successful API call, a live app, a chat answer).
+  activation: {
+    label: "Activation",
+    event: EVENTS.FIRST_ACTION,
+    funnelId: "apiActivation",
+    funnel: eventsOf("apiActivation")
   }
 };
 var COHORTS = {
@@ -429,6 +946,6 @@ var COHORTS = {
   refCode: { field: "ref_code", label: "Referral code" }
 };
 
-export { Analytics, COHORTS, EVENTS, GOALS, PAGEVIEW, VERSION, createAnalytics, deriveChannel, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution };
+export { Analytics, COHORTS, EVENTS, FUNNELS, GOALS, PAGEVIEW, PRODUCTS, VERSION, buildEnvelope, buildSentryEvent, createAnalytics, deriveChannel, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map