@hanzo/event 0.3.1 → 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

@@ -8,10 +8,15 @@
 // React apps use the './react' entry for the provider + hooks + error boundary.
 
 export { Analytics, createAnalytics, VERSION, getCohort, getFirstTouch } from './core'
+export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
+export type { ErrorIdentity } from './sentry'
+export { scrubText, redactSecrets, scrubPII } from './scrub'
 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,
@@ -22,9 +27,14 @@ export {
 export type {
   AnalyticsConfig,
   Attribution,
+  CaptureErrorOptions,
   Cohort,
+  Dsn,
   EventKind,
   Exception,
+  SentryEvent,
+  SentryFrame,
+  SentryLevel,
   Transport,
   WireEvent,
 } from './types'

package/src/scrub.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest'
+import { redactSecrets, scrubPII, scrubText, MAX_SCRUB_LEN } from './scrub'
+
+describe('redactSecrets (always applied)', () => {
+  it('redacts a hanzo key', () => {
+    expect(redactSecrets('key=hk-ABCDEFGHIJKLMNOP1234 tail')).toContain('[redacted]')
+    expect(redactSecrets('key=hk-ABCDEFGHIJKLMNOP1234 tail')).not.toContain('hk-ABCDEFGHIJKLMNOP1234')
+  })
+  it('redacts a JWT', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abcdefghij'
+    expect(redactSecrets(`token ${jwt}`)).not.toContain(jwt)
+  })
+  it('redacts a bearer token', () => {
+    expect(redactSecrets('Authorization: Bearer abcdef0123456789ABCDEF')).toContain('[redacted]')
+  })
+  it('redacts openai/stripe/aws/github/google/slack shapes', () => {
+    expect(redactSecrets('sk-proj-ABCDEFGHIJKLMNOPQRST')).toContain('[redacted]')
+    expect(redactSecrets('sk_live_ABCDEFGHIJKLMNOP1234')).toContain('[redacted]')
+    expect(redactSecrets('AKIAABCDEFGHIJKLMNOP')).toContain('[redacted]')
+    expect(redactSecrets('ghp_ABCDEFGHIJKLMNOPQRSTUVWX')).toContain('[redacted]')
+    expect(redactSecrets('AIzaABCDEFGHIJKLMNOPQRSTUVWXYZ012345')).toContain('[redacted]')
+    expect(redactSecrets('xoxb-1111-2222-abcdefghij')).toContain('[redacted]')
+  })
+  it('redacts credentials embedded in a URL/DSN', () => {
+    expect(redactSecrets('postgres://user:s3cretpw@db.host:5432/x')).toContain('[redacted]')
+    expect(redactSecrets('postgres://user:s3cretpw@db.host:5432/x')).not.toContain('s3cretpw')
+  })
+})
+
+describe('scrubPII (default; opt-out via capturePII)', () => {
+  it('masks emails and IPs', () => {
+    expect(scrubPII('from alice@example.com at 192.168.1.7')).toBe('from [email] at [ip]')
+  })
+  it('scrubText masks by default and retains when capturePII=true', () => {
+    expect(scrubText('alice@example.com', false)).toBe('[email]')
+    expect(scrubText('alice@example.com', true)).toBe('alice@example.com')
+  })
+  it('scrubText still redacts secrets even when capturePII=true', () => {
+    expect(scrubText('hk-ABCDEFGHIJKLMNOP1234', true)).toContain('[redacted]')
+  })
+  it('is total on empty/undefined', () => {
+    expect(scrubText(undefined)).toBe('')
+    expect(scrubText('')).toBe('')
+  })
+})
+
+// ── denial of service ──────────────────────────────────────────────────────
+//
+// The scrubber runs SYNCHRONOUSLY on the main thread inside captureError, and its
+// input is attacker-influenced: `throw new Error(await res.text())` against an
+// HTML error page is a one-line way to hand it 128KB. The creds-in-URL pattern
+// backtracked quadratically on colon-rich text with no terminating '@' — 4.9s at
+// 32KB, >60s at 128KB. Both the input cap and the bounded pattern are load-bearing.
+
+describe('input bounding', () => {
+  it('caps input length and says so', () => {
+    const out = scrubText('a'.repeat(MAX_SCRUB_LEN * 4))
+    expect(out.length).toBeLessThan(MAX_SCRUB_LEN + 64)
+    expect(out.endsWith('… [truncated]')).toBe(true)
+  })
+
+  it('scrubs pathological colon-rich input in bounded time', () => {
+    // The exact shape that blew up: many colons, no '@' to terminate the match.
+    const hostile = '<div class="a:b:c">'.repeat(8000) // ~150KB
+    const t0 = Date.now()
+    const out = scrubText(hostile)
+    const ms = Date.now() - t0
+    expect(out).toBeTruthy()
+    // Was >60s unbounded. Generous ceiling so the test is not flaky on slow CI.
+    expect(ms).toBeLessThan(1000)
+  })
+
+  it('still redacts real credentials in a URL', () => {
+    expect(scrubText('postgres://user:hunter2@db.internal/app')).toContain('[redacted]')
+    expect(scrubText('postgres://user:hunter2@db.internal/app')).not.toContain('hunter2')
+  })
+})
+
+// ── PAN false positives ────────────────────────────────────────────────────
+//
+// The bare digit-run rule redacted every millisecond epoch and order id it saw,
+// destroying the readability of the messages this client exists to deliver. It is
+// now gated on Luhn, which every real card satisfies — so the false positives go
+// away without introducing a false negative.
+
+describe('card numbers', () => {
+  it('redacts a real (Luhn-valid) card number', () => {
+    expect(scrubText('card 4111111111111111 declined')).toContain('[redacted]')
+    expect(scrubText('card 4111-1111-1111-1111 declined')).toContain('[redacted]')
+  })
+
+  it('leaves an epoch timestamp alone', () => {
+    const out = scrubText('request 1753468800000 timed out')
+    expect(out).toBe('request 1753468800000 timed out')
+  })
+})

package/src/scrub.ts

@@ -0,0 +1,117 @@
+// Client-side redaction for error text — a faithful port of the server's
+// errortracking scrub (o11y pkg/modules/errortracking/implerrortracking/scrub.go),
+// applied BEFORE anything leaves the browser. Two layers, default-secure:
+//
+//   - Secret shapes are ALWAYS redacted (sk-… keys, bearer/JWT tokens, DB DSNs,
+//     PANs, cloud keys). There is no mode that ships a secret off-device.
+//   - PII (email/IP) is scrubbed UNLESS capturePII is explicitly enabled.
+//
+// The server scrubs again — this is defense in depth, not a substitute — but the
+// point is that a Hanzo browser never emits a raw secret/email/IP in the first
+// place. Pure, no I/O.
+
+const REDACTED = '[redacted]'
+const EMAIL_MARK = '[email]'
+const IP_MARK = '[ip]'
+
+// Secret patterns mirror scrub.go's secretPatterns. Order matters (broad DSN/PAN
+// rules run last). All are applied unconditionally.
+const SECRET_PATTERNS: RegExp[] = [
+  /-----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,
+]
+
+/** Candidate card numbers. Gated by Luhn below — the bare digit-run pattern is a
+ *  false-positive cannon that redacts every millisecond epoch, order id and
+ *  phone number it sees ("request 1753468800000 timed out" became
+ *  "request [redacted]timed out"), which destroys the readability of the very
+ *  error messages this client exists to deliver. */
+const RE_PAN = /\b(?:\d[ -]?){13,19}\b/g
+
+/** luhn reports whether a digit string satisfies the Luhn checksum. Every real
+ *  card number does, so gating redaction on it removes the false positives
+ *  WITHOUT introducing a false negative — the safe direction for a redactor. */
+function luhn(digits: string): boolean {
+  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
+}
+
+/** redactPAN removes digit runs that actually check out as card numbers. */
+function redactPAN(s: string): string {
+  return s.replace(RE_PAN, (m) => {
+    const digits = m.replace(/[ -]/g, '')
+    if (digits.length < 13 || digits.length > 19) return m
+    return luhn(digits) ? REDACTED : m
+  })
+}
+
+// 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
+
+/** redactSecrets removes known secret shapes. Always applied. */
+export function redactSecrets(s: string): string {
+  for (const re of SECRET_PATTERNS) s = s.replace(re, REDACTED)
+  return redactPAN(s)
+}
+
+/** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
+export function scrubPII(s: string): string {
+  s = s.replace(RE_EMAIL, EMAIL_MARK)
+  s = s.replace(RE_IPV6, IP_MARK)
+  s = s.replace(RE_IPV4, IP_MARK)
+  return s
+}
+
+/** Longest free-text field this module will scrub. Every pattern here is a regex
+ *  run synchronously on the main thread, and the input is attacker-influenced —
+ *  `throw new Error(await res.text())` against an HTML error page is a one-line
+ *  way to hand us 128KB. Bounding the INPUT bounds the work regardless of which
+ *  pattern is pathological. 8KB is far beyond any real error message. */
+export const MAX_SCRUB_LEN = 8192
+
+/** truncate caps a string at MAX_SCRUB_LEN, marking that it was cut so a reader
+ *  never mistakes a truncated message for the whole one. */
+export function truncate(s: string, max = MAX_SCRUB_LEN): string {
+  return s.length > max ? s.slice(0, max) + '… [truncated]' : s
+}
+
+/** scrubText applies the redaction policy to a free-text field. Input is capped
+ *  first: unbounded text is a denial-of-service surface, not just a size problem. */
+export function scrubText(s: string | undefined, capturePII = false): string {
+  if (!s) return s ?? ''
+  s = truncate(s)
+  s = redactSecrets(s)
+  if (!capturePII) s = scrubPII(s)
+  return s
+}