@hanzo/event 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -6,7 +6,7 @@ declare function getFirstTouch(): Attribution | undefined;
 /** Read persisted cohort dimensions. */
 declare function getCohort(): Cohort | undefined;
 
-declare const VERSION = "0.3.2";
+declare const VERSION = "0.3.3";
 
 /**
  * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
@@ -73,6 +73,12 @@ declare const EVENTS: {
     readonly SIGNUP_SUBMITTED: "signup_submitted";
     readonly SIGNUP_VERIFIED: "signup_verified";
     readonly 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. */
+    readonly 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. */
     readonly FIRST_ACTION: "first_action";
     readonly WAITLIST_JOINED: "waitlist_joined";
     readonly WAITLIST_SHARED: "waitlist_shared";
@@ -85,24 +91,127 @@ declare const EVENTS: {
     readonly FEATURE_USED: "feature_used";
     readonly API_KEY_CREATED: "api_key_created";
     readonly APP_CREATED: "app_created";
-    readonly DEPLOY_STARTED: "deploy_started";
     readonly PROJECT_CREATED: "project_created";
     readonly AGENT_CREATED: "agent_created";
     readonly CHAT_STARTED: "chat_started";
     readonly 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). */
+    readonly MODEL_SWITCHED: "model_switched";
     readonly TASK_STARTED: "task_started";
     readonly TASK_COMPLETED: "task_completed";
+    readonly 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. */
+    readonly GENERATION_COMPLETED: "generation_completed";
+    readonly GENERATION_FAILED: "generation_failed";
+    readonly DEPLOY_STARTED: "deploy_started";
+    readonly DEPLOY_SUCCEEDED: "deploy_succeeded";
+    readonly DEPLOY_FAILED: "deploy_failed";
 };
 type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** The reserved event name a pageview is stored under (server + read lens). */
 declare const PAGEVIEW = "$pageview";
 
+/** The emitting surfaces — the closed set of `AnalyticsConfig.product` values.
+ *  `product` is on every event, so a funnel scopes by product instead of every
+ *  surface prefixing its event names. */
+declare const PRODUCTS: readonly ["site", "app", "chat", "console", "admin", "cloud"];
+type ProductId = (typeof PRODUCTS)[number];
+interface FunnelStep {
+    /** An EVENTS value (or PAGEVIEW). */
+    event: string;
+    /** Human label for the Insights step. */
+    label: string;
+    /** Property equality that qualifies the step, e.g. first_action{action:'api_call'}. */
+    where?: {
+        property: string;
+        equals: string;
+    };
+}
+interface FunnelDef {
+    label: string;
+    /** Surface(s) the steps are emitted from — matched against the `product` field. */
+    products: ProductId[];
+    /**
+     * How steps are joined:
+     *  • 'person'    — steps join on distinctId (one browser, or one logged-in
+     *                  person across surfaces). The normal case.
+     *  • 'aggregate' — steps are emitted on DIFFERENT origins by a LOGGED-OUT
+     *                  visitor, so there is no shared id: hanzo.ai, hanzo.app and
+     *                  hanzo.chat each mint their own anonymousId in their own
+     *                  storage. Read these as step-over-step COUNTS, never as a
+     *                  per-person conversion. Honest by construction.
+     */
+    join: 'person' | 'aggregate';
+    steps: FunnelStep[];
+}
+declare const 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. */
+    readonly signup: {
+        readonly label: "Signup";
+        readonly products: ["site"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** 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. */
+    readonly apiActivation: {
+        readonly label: "API activation";
+        readonly products: ["site", "cloud"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** Upgrade intent → revenue. `order_completed{kind:'plan'}` is the Sale goal. */
+    readonly upgrade: {
+        readonly label: "Upgrade";
+        readonly products: ["site", "app", "console"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** hanzo.app: describe → build → deploy → live URL. The whole product thesis
+     *  in five steps; `deploy_succeeded` is the moment a live URL exists. */
+    readonly appShip: {
+        readonly label: "Describe → ship";
+        readonly products: ["app"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** hanzo.chat: visit → first message → answer. `generation_completed` is what
+     *  separates "typed something" from "got value". */
+    readonly chatEngage: {
+        readonly label: "Chat engagement";
+        readonly products: ["chat"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** 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. */
+    readonly siteToChat: {
+        readonly label: "Site → Chat handoff";
+        readonly products: ["site", "chat"];
+        readonly join: "aggregate";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep];
+    };
+};
+type FunnelId = keyof typeof FUNNELS;
+/** eventsOf flattens a funnel to its ordered event names — what a goal's `funnel`
+ *  field carries, so the steps are defined exactly once (here). */
+declare function eventsOf(id: FunnelId): string[];
+
 interface GoalDef {
     /** Human label shown in Insights. */
     label: string;
     /** The event whose occurrence counts as the goal conversion. */
     event: string;
-    /** Optional ordered funnel leading to the goal (for funnel insights). */
+    /** The funnel leading to the goal — an id into FUNNELS (see funnels.ts). */
+    funnelId?: FunnelId;
+    /** The ordered event names of `funnelId`, derived — never hand-written. */
     funnel?: string[];
     /** Optional property equality filter that qualifies the conversion. */
     filter?: {
@@ -110,7 +219,7 @@ interface GoalDef {
         equals: string;
     };
 }
-declare const GOALS: Record<'signup' | 'sale' | 'upgradeIntent', GoalDef>;
+declare const GOALS: Record<'signup' | 'sale' | 'upgradeIntent' | 'activation', GoalDef>;
 interface CohortDef {
     /** The hanzo.events column the cohort dimension maps to. */
     field: string;
@@ -131,4 +240,4 @@ declare function hasAttribution(a: Attribution): boolean;
 /** isoWeek returns the ISO-8601 week label, e.g. "2026-W28". */
 declare function isoWeek(d: Date): string;
 
-export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, type ErrorIdentity, type EventName, GOALS, type GoalDef, PAGEVIEW, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };
+export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, type ErrorIdentity, type EventName, FUNNELS, type FunnelDef, type FunnelId, type FunnelStep, GOALS, type GoalDef, PAGEVIEW, PRODUCTS, type ProductId, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };

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,13 +99,27 @@ 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";
 
@@ -151,40 +171,40 @@ function luhn(digits) {
   }
   return sum % 10 === 0;
 }
-function redactPAN(s) {
-  return s.replace(RE_PAN, (m) => {
+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._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+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(s) {
-  for (const re of SECRET_PATTERNS) s = s.replace(re, REDACTED);
-  return redactPAN(s);
+function redactSecrets(s2) {
+  for (const re of SECRET_PATTERNS) s2 = s2.replace(re, REDACTED);
+  return redactPAN(s2);
 }
-function scrubPII(s) {
-  s = s.replace(RE_EMAIL, EMAIL_MARK);
-  s = s.replace(RE_IPV6, IP_MARK);
-  s = s.replace(RE_IPV4, IP_MARK);
-  return s;
+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(s, max = MAX_SCRUB_LEN) {
-  return s.length > max ? s.slice(0, max) + "\u2026 [truncated]" : s;
+function truncate(s2, max = MAX_SCRUB_LEN) {
+  return s2.length > max ? s2.slice(0, max) + "\u2026 [truncated]" : s2;
 }
-function scrubText(s, capturePII = false) {
-  if (!s) return s ?? "";
-  s = truncate(s);
-  s = redactSecrets(s);
-  if (!capturePII) s = scrubPII(s);
-  return s;
+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.2";
+var VERSION = "0.3.3";
 
 // src/sentry.ts
 var MAX_FRAMES = 50;
@@ -195,14 +215,14 @@ 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 s = "";
-  for (let i = 0; i < 32; i++) s += Math.floor(Math.random() * 16).toString(16);
-  return s;
+  let s2 = "";
+  for (let i = 0; i < 32; i++) s2 += Math.floor(Math.random() * 16).toString(16);
+  return s2;
 }
-function byteLen(s) {
-  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s).length;
-  if (typeof Buffer !== "undefined") return Buffer.byteLength(s, "utf8");
-  return s.length;
+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;
@@ -272,17 +292,38 @@ function framesFromStack(stack) {
 }
 function normalizeError(err) {
   if (err instanceof Error) {
-    return { name: err.name || "Error", message: err.message || String(err), stack: err.stack };
+    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) };
+    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 { name: "Error", message: String(err) };
+    return void 0;
+  }
+}
+function str(v) {
+  try {
+    return String(v);
+  } catch {
+    return "[unstringifiable]";
   }
 }
 function coerceTag(v) {
-  const s = typeof v === "string" ? v : (() => {
+  const s2 = typeof v === "string" ? v : (() => {
     try {
       return JSON.stringify(v) ?? String(v);
     } catch {
@@ -293,7 +334,7 @@ function coerceTag(v) {
       }
     }
   })();
-  return s.length > MAX_TAG_LEN ? s.slice(0, MAX_TAG_LEN) : s;
+  return s2.length > MAX_TAG_LEN ? s2.slice(0, MAX_TAG_LEN) : s2;
 }
 function buildSentryEvent(input) {
   const { error, options = {}, identity, capturePII = false } = input;
@@ -382,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;
   }
@@ -405,45 +446,45 @@ 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;
 }
 
@@ -476,15 +517,8 @@ function uid2() {
   return "m-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
 }
 function normalizeError2(err) {
-  if (err instanceof Error) {
-    return { type: err.name, message: err.message, stack: err.stack };
-  }
-  if (typeof err === "string") return { message: err };
-  try {
-    return { message: JSON.stringify(err) };
-  } catch {
-    return { message: String(err) };
-  }
+  const n = normalizeError(err);
+  return { type: n.name, message: n.message, stack: n.stack };
 }
 var isBrowser = () => typeof window !== "undefined";
 function serializeBatch(batch) {
@@ -771,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 = {
@@ -803,6 +946,6 @@ var COHORTS = {
   refCode: { field: "ref_code", label: "Referral code" }
 };
 
-export { Analytics, COHORTS, EVENTS, GOALS, PAGEVIEW, VERSION, buildEnvelope, buildSentryEvent, createAnalytics, deriveChannel, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };
+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