@hanzo/event 0.3.21 → 0.3.23

package/hz.js

@@ -55,7 +55,7 @@
   }
 
   var LIB = 'hz.js'
-  var VERSION = '0.3.21'
+  var VERSION = '0.3.23'
   var host = (s.getAttribute('data-host') || 'https://api.hanzo.ai').replace(/\/+$/, '')
   var product = s.getAttribute('data-product') || location.hostname
   var capture = s.getAttribute('data-capture') !== '0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.21",
+  "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/",
@@ -75,6 +75,9 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   },
+  "dependencies": {
+    "@hanzo/events": "^0.2.1"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/src/events.ts

@@ -1,76 +1,21 @@
-// The ONE product-analytics vocabulary. Every Hanzo surface emits these exact
-// names so funnels, goals, and cohorts line up across console/chat/app/site/admin.
-// Pageviews use the reserved "$pageview" name (emitted by analytics.pageview()),
-// matching the server read lens.
-//
-// Naming is a closed convention, not a style preference (see TAXONOMY.md):
-//   • snake_case, `<object>_<verb-in-past-tense>` — signup_completed, plan_clicked.
-//   • Names are CONSTANTS, never interpolated. A dimension (framework, model,
-//     plan, source) is a PROPERTY, never part of the name. `deploy_succeeded`
-//     with {framework:'static'} — never `deploy_static_succeeded`.
-//   • One name per user-visible moment, shared by every surface. The surface is
-//     already on the wire as `product`, so a name is never product-prefixed.
-
-export const EVENTS = {
-  // Signup funnel: view -> submit -> verify -> completed -> first action.
-  SIGNUP_VIEWED: 'signup_viewed',
-  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',
-  WAITLIST_SHARED: 'waitlist_shared',
-  REFERRAL_USED: 'referral_used',
-  REFERRAL_CLAIMED: 'referral_claimed',
-
-  // Upgrade-intent + purchase.
-  PRICING_VIEWED: 'pricing_viewed',
-  PLAN_CLICKED: 'plan_clicked',
-  CHECKOUT_STARTED: 'checkout_started',
-  ORDER_COMPLETED: 'order_completed',
-
-  // Feature usage — generic + the common key surfaces across products.
-  FEATURE_USED: 'feature_used',
-  API_KEY_CREATED: 'api_key_created',
-  APP_CREATED: 'app_created',
-  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',
-
-  // 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',
-} as const
-
-export type EventName = (typeof EVENTS)[keyof typeof EVENTS]
-
-/** The reserved event name a pageview is stored under (server + read lens). */
-export const PAGEVIEW = '$pageview'
-
-/** The reserved name every captured exception is emitted under. Error Tracking
- *  reads exactly this name; an exception emitted under its own message instead
- *  makes every distinct message a permanent entry in the event taxonomy. */
-export const EXCEPTION = '$exception'
+/**
+ * The vocabulary, re-exported from where it is now defined.
+ *
+ * These names used to be declared here. They moved to @hanzo/events — the
+ * plural package is the catalog (many events, what each means, what each
+ * carries), this one is the client (one call sends one event). Splitting them
+ * that way is what lets the ingest door read the same catalog: the door is Go
+ * and cannot import TypeScript, so @hanzo/events also ships the data as JSON,
+ * and there is still exactly one definition.
+ *
+ * Nothing about the API moved. Every existing import keeps working, the names
+ * and their values are unchanged, and `pkgs/events/test/catalog.mjs` fails the
+ * build if a name and its meaning ever disagree.
+ *
+ * The naming convention lives with the names, in @hanzo/events and TAXONOMY.md:
+ * snake_case `<object>_<verb-past>`, a dimension is a PROPERTY and never part
+ * of the name, one name per user-visible moment shared by every surface.
+ */
+
+export { EVENTS, PAGEVIEW, EXCEPTION } from '@hanzo/events'
+export type { EventName } from '@hanzo/events'

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)
-  })
-})