@hanzo/event 0.3.22 → 0.3.23

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.22",
-  "description": "Hanzo Event \u2014 the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes \u2014 the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
+  "version": "0.3.23",
+  "description": "Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
@@ -37,13 +37,6 @@
     "funnel",
     "hanzo"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
   "exports": {
     ".": {
       "import": {
@@ -83,6 +76,13 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@hanzo/events": "^0.2.0"
+    "@hanzo/events": "^0.2.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}

package/src/funnels.ts

@@ -1,154 +1,14 @@
-// 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)
-}
+/**
+ * The funnel registry, re-exported from where it is now defined.
+ *
+ * The funnels moved to @hanzo/events for the reason the names did: the read lens
+ * is Go and cannot import TypeScript, and that package already writes its data
+ * out as JSON. Defining a funnel beside the vocabulary also makes the anti-drift
+ * check local — a step naming an event that does not exist is caught where both
+ * are declared.
+ *
+ * Nothing about the API moved. Every existing import keeps working.
+ */
+
+export { FUNNELS, PRODUCTS, eventsOf } from '@hanzo/events'
+export type { FunnelDef, FunnelStep, FunnelId, ProductId } from '@hanzo/events'

package/src/goals.test.ts

@@ -0,0 +1,33 @@
+/**
+ * A goal points AT a funnel and never restates its steps.
+ *
+ * The steps are defined once, in @hanzo/events. A goal that spelled its own copy
+ * would be right on the day it was written and wrong the day a step moved — and
+ * the way that surfaces is a conversion rate quietly measuring the wrong thing.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { EVENTS } from './events'
+import { eventsOf } from './funnels'
+import { GOALS } from './goals'
+
+describe('goals', () => {
+  it('derive their funnel from the registry — one definition, never restated', () => {
+    for (const goal of Object.values(GOALS)) {
+      if (!goal.funnelId) continue
+      expect(goal.funnel).toEqual(eventsOf(goal.funnelId))
+    }
+  })
+
+  it('convert on an event the funnel actually contains', () => {
+    expect(GOALS.signup.funnel).toContain(EVENTS.SIGNUP_COMPLETED)
+    expect(GOALS.sale.funnel).toContain(EVENTS.ORDER_COMPLETED)
+    expect(GOALS.activation.funnel).toContain(EVENTS.FIRST_ACTION)
+  })
+
+  it('does not gate signup on an event nothing emits', () => {
+    // signup_verified is IAM-internal: no surface emits it, so its presence in
+    // the signup funnel would pin the conversion rate at 0.
+    expect(GOALS.signup.funnel).not.toContain(EVENTS.SIGNUP_VERIFIED)
+  })
+})

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.21'
+export const VERSION = '0.3.23'

package/src/funnels.test.ts

@@ -1,92 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { EVENTS, PAGEVIEW } from './events'
-import { FUNNELS, PRODUCTS, eventsOf, type FunnelId } from './funnels'
-import { GOALS } from './goals'
-
-const NAMES = new Set<string>([...Object.values(EVENTS), PAGEVIEW])
-const ids = Object.keys(FUNNELS) as FunnelId[]
-
-describe('event vocabulary', () => {
-  it('is snake_case with no product prefix or interpolation', () => {
-    for (const name of Object.values(EVENTS)) {
-      expect(name, name).toMatch(/^[a-z][a-z0-9]*(_[a-z0-9]+)+$/)
-    }
-  })
-
-  it('has no duplicate values (two constants must never share a name)', () => {
-    const values = Object.values(EVENTS)
-    expect(new Set(values).size).toBe(values.length)
-  })
-
-  it('reserves the $ prefix for the client (only $pageview)', () => {
-    expect(Object.values(EVENTS).some((n) => n.startsWith('$'))).toBe(false)
-    expect(PAGEVIEW).toBe('$pageview')
-  })
-})
-
-describe('funnels', () => {
-  it('only reference events that exist — the anti-drift guard', () => {
-    for (const id of ids) {
-      for (const step of FUNNELS[id].steps) {
-        expect(NAMES.has(step.event), `${id}: unknown event "${step.event}"`).toBe(true)
-      }
-    }
-  })
-
-  it('name only known products', () => {
-    for (const id of ids) {
-      for (const p of FUNNELS[id].products) {
-        expect(PRODUCTS, `${id}: unknown product "${p}"`).toContain(p)
-      }
-    }
-  })
-
-  it('are ordered lists of at least two steps', () => {
-    for (const id of ids) expect(FUNNELS[id].steps.length, id).toBeGreaterThanOrEqual(2)
-  })
-
-  it('mark a cross-origin funnel as aggregate (no shared anonymousId)', () => {
-    // Two surfaces + a logged-out visitor = two anonymousIds. Anything spanning
-    // origins must say so, or the read lens silently reports a false conversion.
-    for (const id of ids) {
-      if (FUNNELS[id].products.length > 1 && FUNNELS[id].join === 'person') {
-        // person-joined multi-product funnels are only legitimate post-login
-        // (site+cloud share the OIDC subject) — flag anything anonymous.
-        expect(FUNNELS[id].steps[0].event, id).not.toBe(PAGEVIEW)
-      }
-    }
-    expect(FUNNELS.siteToChat.join).toBe('aggregate')
-  })
-
-  it('the three product journeys are covered', () => {
-    expect(FUNNELS.signup.products).toContain('site')
-    expect(FUNNELS.appShip.products).toContain('app')
-    expect(FUNNELS.chatEngage.products).toContain('chat')
-  })
-
-  it('appShip ends at a live URL, not at a click', () => {
-    const last = FUNNELS.appShip.steps[FUNNELS.appShip.steps.length - 1]
-    expect(last.event).toBe(EVENTS.DEPLOY_SUCCEEDED)
-  })
-})
-
-describe('goals', () => {
-  it('derive their funnel from the registry — one definition, never restated', () => {
-    for (const goal of Object.values(GOALS)) {
-      if (!goal.funnelId) continue
-      expect(goal.funnel).toEqual(eventsOf(goal.funnelId))
-    }
-  })
-
-  it('convert on an event the funnel actually contains (or its head)', () => {
-    expect(GOALS.signup.funnel).toContain(EVENTS.SIGNUP_COMPLETED)
-    expect(GOALS.sale.funnel).toContain(EVENTS.ORDER_COMPLETED)
-    expect(GOALS.activation.funnel).toContain(EVENTS.FIRST_ACTION)
-  })
-
-  it('no longer gates signup on an event nothing emits', () => {
-    // signup_verified is IAM-internal: no surface emits it, so its presence in
-    // the signup funnel pinned the conversion rate at 0.
-    expect(GOALS.signup.funnel).not.toContain(EVENTS.SIGNUP_VERIFIED)
-  })
-})