@hanzo/event 0.3.2 → 0.3.3

package/src/funnels.ts

@@ -0,0 +1,154 @@
+// The ONE funnel registry. A funnel is DATA — an ordered list of event names —
+// so the products, the Insights UI, and the docs can never drift: every step is
+// a name from EVENTS (funnels.test.ts fails the build otherwise), and a GOAL that
+// has a funnel points AT one of these rather than restating the steps.
+//
+// Why here and not in Insights: the taxonomy is code that all three surfaces
+// already import (`@hanzo/event`). A funnel defined in the read lens could name
+// an event no surface emits; a funnel defined next to EVENTS cannot.
+
+import { EVENTS, PAGEVIEW } from './events'
+
+/** 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. */
+export const PRODUCTS = ['site', 'app', 'chat', 'console', 'admin', 'cloud'] as const
+export type ProductId = (typeof PRODUCTS)[number]
+
+export 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 }
+}
+
+export 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[]
+}
+
+const s = (event: string, label: string, where?: FunnelStep['where']): FunnelStep => ({
+  event,
+  label,
+  ...(where ? { where } : {}),
+})
+
+export 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. */
+  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 → 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 → 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'),
+    ],
+  },
+} as const satisfies Record<string, FunnelDef>
+
+export 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). */
+export function eventsOf(id: FunnelId): string[] {
+  return FUNNELS[id].steps.map((step) => step.event)
+}

package/src/goals.ts

@@ -1,44 +1,58 @@
 // Insights goals + cohorts, defined once as data so the console/insights UI and
 // every product agree on what "a Signup", "a Sale", and "upgrade intent" mean.
 // This is the machine-readable spec — the shared source of truth a sync step can
-// push into Insights, and what the guide documents.
+// push into Insights, and what TAXONOMY.md documents.
+//
+// A goal answers "what counts as a conversion". A funnel answers "by what path".
+// The paths live in funnels.ts and a goal REFERENCES one by id: the steps are
+// written down exactly once.
 
 import { EVENTS } from './events'
+import { eventsOf, type FunnelId } from './funnels'
 
 export 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?: { property: string; equals: string }
 }
 
-export const GOALS: Record<'signup' | 'sale' | 'upgradeIntent', GoalDef> = {
-  // Signup: the conversion is signup_completed; the funnel is the four steps.
+export const GOALS: Record<'signup' | 'sale' | 'upgradeIntent' | 'activation', GoalDef> = {
+  // 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'),
   },
 }
 

package/src/index.ts

@@ -15,6 +15,8 @@ export { EVENTS, PAGEVIEW } from './events'
 export type { EventName } from './events'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
+export { FUNNELS, PRODUCTS, eventsOf } from './funnels'
+export type { FunnelDef, FunnelStep, FunnelId, ProductId } from './funnels'
 export {
   parseAttribution,
   deriveChannel,

package/src/scrub.ts

@@ -70,7 +70,12 @@ function redactPAN(s: string): string {
   })
 }
 
-const RE_EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g
+// Bounded to the RFC 5321 maxima (local-part 64, domain 255) for the same reason
+// as the creds-in-URL rule: the unbounded form backtracks quadratically across a
+// long run of local-part-legal characters that never reaches an '@' — measured at
+// 20ms on an 8KB worst case, on the main thread, per captured error. No real
+// address is excluded by these caps.
+const RE_EMAIL = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}/g
 const RE_IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g
 const RE_IPV6 = /\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{1,4}\b/g
 

package/src/sentry.test.ts

@@ -258,3 +258,55 @@ describe('fingerprint grouping (port of server model)', () => {
     expect(f1).not.toBe(f2)
   })
 })
+
+// ── hostile thrown objects ─────────────────────────────────────────────────
+//
+// `name`, `message` and `stack` are ordinary getters. A thrown object is free to
+// define any of them to throw, and the thrown value is the least trustworthy
+// input this library handles. normalizeError must be TOTAL — buildSentryEvent
+// throwing here meant the crash report was lost on both planes.
+
+describe('normalizeError survives hostile input', () => {
+  const bomb = (prop: string) => {
+    const e = new Error('real message')
+    Object.defineProperty(e, prop, {
+      get() {
+        throw new Error(prop + ' bomb')
+      },
+      configurable: true,
+    })
+    return e
+  }
+
+  for (const prop of ['stack', 'message', 'name']) {
+    it(`a throwing ${prop} getter does not throw`, () => {
+      expect(() => normalizeError(bomb(prop))).not.toThrow()
+      const n = normalizeError(bomb(prop))
+      expect(typeof n.name).toBe('string')
+      expect(typeof n.message).toBe('string')
+    })
+  }
+
+  it('buildSentryEvent still produces a usable event from a getter bomb', () => {
+    const ev = buildSentryEvent({ error: bomb('stack'), identity: { product: 'test' } })
+    expect(ev.exception?.values[0].type).toBe('Error')
+    // The message survived because only `stack` was hostile.
+    expect(ev.exception?.values[0].value).toBe('real message')
+    expect(ev.exception?.values[0].stacktrace?.frames).toEqual([])
+  })
+
+  it('an object with a throwing toString is still reportable', () => {
+    const evil = {
+      toString() {
+        throw new Error('toString bomb')
+      },
+    }
+    expect(() => normalizeError(evil)).not.toThrow()
+    expect(() => buildSentryEvent({ error: evil, identity: {} })).not.toThrow()
+  })
+
+  it('a frozen/null-prototype throwable is still reportable', () => {
+    const weird = Object.freeze(Object.create(null)) as unknown
+    expect(() => buildSentryEvent({ error: weird, identity: {} })).not.toThrow()
+  })
+})

package/src/sentry.ts

@@ -148,13 +148,43 @@ export function framesFromStack(stack: string | undefined): SentryFrame[] {
 /** 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 }
+    // `name`, `message` and `stack` are ordinary getters, and the thrown object is
+    // the least trustworthy input this library handles — any of them may throw.
+    // Losing the whole report to a hostile getter is not acceptable.
+    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 : undefined,
+    }
   }
   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) }
+  }
+}
+
+/** read pulls a property off a possibly-hostile value without letting a throwing
+ *  getter escape. */
+function read(o: unknown, k: string): unknown {
+  try {
+    return (o as Record<string, unknown>)[k]
+  } catch {
+    return undefined
+  }
+}
+
+/** str coerces to a string without letting a throwing toString/Symbol.toPrimitive
+ *  escape. */
+function str(v: unknown): string {
+  try {
+    return String(v)
   } catch {
-    return { name: 'Error', message: String(err) }
+    return '[unstringifiable]'
   }
 }
 

package/src/version.ts

@@ -1,4 +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'
+export const VERSION = '0.3.3'