@hanzo/event 0.2.0

package/src/attribution.ts

@@ -0,0 +1,82 @@
+// Pure attribution helpers: parse first-touch UTM/referrer/refCode from a URL,
+// derive the acquisition channel, and compute the ISO week for the signup cohort.
+// No I/O, no globals — trivially testable.
+
+import type { Attribution } from './types'
+
+const SOCIAL_HOSTS = [
+  'facebook.', 'instagram.', 'twitter.', 'x.com', 't.co', 'linkedin.',
+  'reddit.', 'youtube.', 'tiktok.', 'pinterest.', 'news.ycombinator.com',
+]
+const SEARCH_HOSTS = ['google.', 'bing.', 'duckduckgo.', 'yahoo.', 'baidu.', 'ecosia.']
+
+/** parseAttribution reads UTM params + ref/refCode from a query string and pairs
+ *  them with the referrer. `search` is a location.search value ("?utm_source=…"). */
+export function parseAttribution(search: string, referrer: string): Attribution {
+  const q = new URLSearchParams(search || '')
+  const get = (k: string) => {
+    const v = q.get(k)
+    return v ? v.trim() : undefined
+  }
+  const a: Attribution = {
+    utm: {
+      source: get('utm_source'),
+      medium: get('utm_medium'),
+      campaign: get('utm_campaign'),
+      term: get('utm_term'),
+      content: get('utm_content'),
+    },
+    referrer: referrer ? referrer.trim() : undefined,
+    refCode: get('ref') || get('refCode') || get('ref_code') || undefined,
+  }
+  a.channel = deriveChannel(a)
+  return a
+}
+
+/** deriveChannel classifies the visit: paid | referral | social | organic | direct. */
+export function deriveChannel(a: Attribution): string {
+  const medium = (a.utm.medium || '').toLowerCase()
+  if (/(cpc|ppc|paid|paidsearch|display|cpm)/.test(medium)) return 'paid'
+  if (a.utm.source || a.utm.campaign) return 'campaign'
+  if (a.refCode) return 'referral'
+  const host = hostOf(a.referrer)
+  if (!host) return 'direct'
+  if (SOCIAL_HOSTS.some((h) => host.includes(h))) return 'social'
+  if (SEARCH_HOSTS.some((h) => host.includes(h))) return 'organic'
+  return 'referral'
+}
+
+/** hostOf extracts a bare lowercase host from a URL; "" when unparseable. */
+export function hostOf(raw?: string): string {
+  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()
+}
+
+/** hasAttribution reports whether anything was captured (so we don't persist an
+ *  empty first-touch that would shadow a later real one). */
+export function hasAttribution(a: Attribution): boolean {
+  return Boolean(
+    a.utm.source || a.utm.medium || a.utm.campaign || a.utm.term ||
+      a.utm.content || a.refCode || (a.referrer && hostOf(a.referrer)),
+  )
+}
+
+/** isoWeek returns the ISO-8601 week label, e.g. "2026-W28". */
+export function isoWeek(d: Date): string {
+  // Copy to UTC midnight; ISO week: Thursday-anchored.
+  const date = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+  const day = date.getUTCDay() || 7
+  date.setUTCDate(date.getUTCDate() + 4 - day)
+  const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1))
+  const week = Math.ceil(((date.getTime() - yearStart.getTime()) / 86400000 + 1) / 7)
+  return `${date.getUTCFullYear()}-W${String(week).padStart(2, '0')}`
+}

package/src/core.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Analytics } from './core'
+import { EVENTS, PAGEVIEW } from './events'
+import type { Transport, WireEvent } from './types'
+
+interface Sent {
+  url: string
+  beacon: boolean
+  token?: string
+  batch: WireEvent[]
+}
+
+class FakeTransport implements Transport {
+  sent: Sent[] = []
+  send(url: string, body: string, opts: { beacon: boolean; token?: string }) {
+    const parsed = JSON.parse(body) as { batch: WireEvent[] }
+    this.sent.push({ url, beacon: opts.beacon, token: opts.token, batch: parsed.batch })
+  }
+  get all(): WireEvent[] {
+    return this.sent.flatMap((s) => s.batch)
+  }
+}
+
+let tx: FakeTransport
+function mk(overrides = {}) {
+  tx = new FakeTransport()
+  return new Analytics({ product: 'console', transport: tx, flushIntervalMs: 999999, ...overrides })
+}
+
+describe('Analytics capture', () => {
+  beforeEach(() => {
+    tx = new FakeTransport()
+  })
+
+  it('flushes an event as a {batch:[...]} with product + name, no tenant/org field', () => {
+    const a = mk()
+    a.capture(EVENTS.SIGNUP_COMPLETED, { plan: 'pro' })
+    a.flush()
+    expect(tx.sent).toHaveLength(1)
+    expect(tx.sent[0].url).toBe('/v1/analytics')
+    const e = tx.all[0]
+    expect(e.type).toBe('event')
+    expect(e.event).toBe('signup_completed')
+    expect(e.product).toBe('console')
+    expect(e.properties).toEqual({ plan: 'pro' })
+    // The client must never send a tenant/org — the server stamps it.
+    expect((e as Record<string, unknown>).tenant).toBeUndefined()
+    expect((e as Record<string, unknown>).org).toBeUndefined()
+    expect((e as Record<string, unknown>).tenantId).toBeUndefined()
+  })
+
+  it('pageview emits the reserved $pageview name', () => {
+    const a = mk()
+    a.pageview('/pricing')
+    a.flush()
+    const e = tx.all[0]
+    expect(e.type).toBe('pageview')
+    expect(e.event).toBe(PAGEVIEW)
+    expect(e.path).toBe('/pricing')
+  })
+
+  it('auto-flushes when the batch size is reached', () => {
+    const a = mk({ batchSize: 3 })
+    a.capture('a')
+    a.capture('b')
+    expect(tx.sent).toHaveLength(0) // under threshold, buffered
+    a.capture('c')
+    expect(tx.sent).toHaveLength(1) // threshold hit → flushed
+    expect(tx.all).toHaveLength(3)
+  })
+
+  it('identify binds personId to subsequent distinctId', () => {
+    const a = mk()
+    a.capture('anon_event')
+    a.identify('user-42')
+    a.capture('known_event')
+    a.flush()
+    const anon = tx.all.find((e) => e.event === 'anon_event')!
+    const known = tx.all.find((e) => e.event === 'known_event')!
+    expect(known.personId).toBe('user-42')
+    expect(known.distinctId).toBe('user-42')
+    // the pre-identify event has no personId
+    expect(anon.personId).toBeUndefined()
+  })
+
+  it('carries commerce fields on order events', () => {
+    const a = mk()
+    a.capture(EVENTS.ORDER_COMPLETED, { kind: 'plan' }, { productId: 'plan_pro', revenue: 49, quantity: 1, currency: 'usd' })
+    a.flush()
+    const e = tx.all[0]
+    expect(e.productId).toBe('plan_pro')
+    expect(e.revenue).toBe(49)
+    expect(e.quantity).toBe(1)
+    expect(e.currency).toBe('usd')
+  })
+
+  it('a disabled client emits nothing', () => {
+    const a = mk({ enabled: false })
+    a.capture('x')
+    a.pageview()
+    a.flush()
+    expect(tx.sent).toHaveLength(0)
+  })
+
+  it('token apps send Authorization and never beacon (headerless) on unload flush', () => {
+    const a = mk({ getToken: () => 'jwt-abc' })
+    a.capture('x')
+    a.flush(true) // beacon requested…
+    expect(tx.sent[0].token).toBe('jwt-abc')
+    expect(tx.sent[0].beacon).toBe(false) // …but a token forces keepalive fetch
+    expect(tx.sent[0].url).toBe('/v1/analytics')
+  })
+
+  it('cookie apps beacon to the tracker route on unload flush', () => {
+    const a = mk() // no token
+    a.capture('x')
+    a.flush(true)
+    expect(tx.sent[0].beacon).toBe(true)
+    expect(tx.sent[0].url).toBe('/v1/tracker')
+  })
+
+  it('setCohort rides subsequent events', () => {
+    const a = mk()
+    a.setCohort({ signupWeek: '2026-W29', channel: 'paid', refCode: 'REF9' })
+    a.capture('x')
+    a.flush()
+    const e = tx.all[0]
+    expect(e.signupWeek).toBe('2026-W29')
+    expect(e.channel).toBe('paid')
+    expect(e.refCode).toBe('REF9')
+  })
+
+  it('prefixes the configured host onto the path', () => {
+    const a = mk({ host: 'https://api.hanzo.ai' })
+    a.capture('x')
+    a.flush()
+    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/analytics')
+  })
+
+  it('stamps every event with the @hanzo/event library id', () => {
+    const a = mk()
+    a.capture('x')
+    a.flush()
+    expect(tx.all[0].library).toBe('@hanzo/event')
+  })
+})
+
+describe('Event error capture', () => {
+  it('captureError emits a type:error event with the exception, and flushes at once', () => {
+    const a = mk()
+    a.captureError(new TypeError('boom'))
+    // captureError flushes promptly — no explicit flush() needed.
+    expect(tx.sent).toHaveLength(1)
+    const e = tx.all[0]
+    expect(e.type).toBe('error')
+    expect(e.event).toBe('boom')
+    expect(e.error?.type).toBe('TypeError')
+    expect(e.error?.message).toBe('boom')
+    expect(e.error?.stack).toBeTruthy()
+    expect(e.error?.handled).toBe(true) // a caught, manually-reported error
+  })
+
+  it('normalizes a thrown string into an exception', () => {
+    const a = mk()
+    a.captureError('plain failure')
+    const e = tx.all[0]
+    expect(e.type).toBe('error')
+    expect(e.error?.message).toBe('plain failure')
+  })
+
+  it('marks handled=false for unhandled/global errors and carries properties', () => {
+    const a = mk()
+    a.captureError(new Error('unhandled'), { handled: false, properties: { source: 'onerror' } })
+    const e = tx.all[0]
+    expect(e.error?.handled).toBe(false)
+    expect(e.properties).toEqual({ source: 'onerror' })
+  })
+
+  it('captureException is an alias of captureError', () => {
+    const a = mk()
+    a.captureException(new Error('via alias'))
+    const e = tx.all[0]
+    expect(e.type).toBe('error')
+    expect(e.error?.message).toBe('via alias')
+  })
+
+  it('an error is still an event on the ONE stream — same route + product', () => {
+    const a = mk({ host: 'https://api.hanzo.ai' })
+    a.captureError(new Error('x'))
+    // Same batched route as any other event — one pipe, not a second SDK.
+    expect(tx.sent[0].url).toBe('https://api.hanzo.ai/v1/analytics')
+    expect(tx.all[0].product).toBe('console')
+    // never the tenant — the server stamps it, errors included.
+    expect((tx.all[0] as Record<string, unknown>).tenant).toBeUndefined()
+  })
+})

package/src/core.ts

@@ -0,0 +1,274 @@
+// The framework-agnostic event client. Buffers events and flushes them as one
+// batch to Hanzo Cloud — /v1/analytics normally, /v1/tracker via sendBeacon on
+// page unload. It NEVER sends the org/tenant: the server stamps that from the
+// validated session. The client only supplies its own visitor identity. Errors
+// are just events (type:'error') on the same stream — one client, one pipe.
+
+import {
+  parseAttribution,
+  hasAttribution,
+  deriveChannel,
+} from './attribution'
+import { PAGEVIEW } from './events'
+import {
+  anonId,
+  sessionId,
+  getFirstTouch,
+  setFirstTouchOnce,
+  getCohort,
+  mergeCohort,
+} from './storage'
+import type {
+  AnalyticsConfig,
+  Attribution,
+  Cohort,
+  EventKind,
+  Exception,
+  Transport,
+  WireEvent,
+} from './types'
+
+export const VERSION = '0.2.0'
+
+const ANALYTICS_PATH = '/v1/analytics'
+const TRACKER_PATH = '/v1/tracker' // beacon-on-unload alias
+
+function uid(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && 'randomUUID' in c) return c.randomUUID()
+  return 'm-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
+}
+
+/** Normalize anything thrown (Error | string | unknown) into an Exception. */
+function normalizeError(err: unknown): Exception {
+  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 isBrowser = () => typeof window !== 'undefined'
+
+/** DefaultTransport: fetch(keepalive) for authenticated/normal sends;
+ *  navigator.sendBeacon for headerless page-unload beacons. */
+class DefaultTransport implements Transport {
+  send(url: string, body: string, opts: { beacon: boolean; token?: string }): void {
+    if (opts.beacon && isBrowser() && typeof navigator.sendBeacon === 'function') {
+      try {
+        navigator.sendBeacon(url, new Blob([body], { type: 'application/json' }))
+        return
+      } catch {
+        /* fall through to fetch */
+      }
+    }
+    if (typeof fetch !== 'function') return
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (opts.token) headers.Authorization = `Bearer ${opts.token}`
+    void fetch(url, {
+      method: 'POST',
+      headers,
+      body,
+      keepalive: true,
+      credentials: 'include',
+    }).catch(() => {
+      /* analytics loss is acceptable; never throw into the app */
+    })
+  }
+}
+
+export class Analytics {
+  private cfg: Required<
+    Pick<AnalyticsConfig, 'product' | 'batchSize' | 'flushIntervalMs' | 'enabled' | 'captureErrors'>
+  > &
+    AnalyticsConfig
+  private transport: Transport
+  private queue: WireEvent[] = []
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private personId?: string
+  private attribution: Attribution = { utm: {} }
+  private cohort: Cohort = {}
+  private started = false
+
+  constructor(config: AnalyticsConfig) {
+    this.cfg = {
+      host: '',
+      batchSize: 20,
+      flushIntervalMs: 5000,
+      enabled: true,
+      captureErrors: true,
+      ...config,
+    }
+    this.transport = config.transport ?? new DefaultTransport()
+  }
+
+  /** init is idempotent and browser-only for its side effects: capture first-touch
+   *  attribution, hydrate cohort, and register the unload flush. Safe to call from
+   *  a React effect on every render. */
+  init(): void {
+    if (this.started || !this.cfg.enabled) return
+    this.started = true
+    if (!isBrowser()) return
+
+    const parsed = parseAttribution(window.location.search, document.referrer)
+    this.attribution = hasAttribution(parsed)
+      ? setFirstTouchOnce(parsed)
+      : getFirstTouch() ?? parsed
+    this.cohort = mergeCohort({
+      channel: this.attribution.channel ?? deriveChannel(this.attribution),
+      refCode: this.attribution.refCode,
+    })
+
+    const flushHidden = () => {
+      if (document.visibilityState === 'hidden') this.flush(true)
+    }
+    window.addEventListener('visibilitychange', flushHidden)
+    window.addEventListener('pagehide', () => this.flush(true))
+
+    // Auto error capture — the drop-in @sentry replacement. Unhandled errors and
+    // rejected promises become type:'error' events on the same stream.
+    if (this.cfg.captureErrors) {
+      window.addEventListener('error', (e: ErrorEvent) => {
+        this.captureError(e.error ?? e.message, { handled: false })
+      })
+      window.addEventListener('unhandledrejection', (e: PromiseRejectionEvent) => {
+        this.captureError(e.reason, { handled: false })
+      })
+    }
+  }
+
+  /** identify binds the current visitor to a stable person id (post-login). */
+  identify(personId: string, traits?: Record<string, unknown>): void {
+    this.personId = personId
+    this.enqueue('identify', undefined, { properties: traits })
+  }
+
+  /** group associates the visitor with an org/team (analytics grouping, not the
+   *  server tenant — the server still derives tenant from the session). */
+  group(groupId: string, traits?: Record<string, unknown>): void {
+    this.enqueue('group', undefined, { groupId, properties: traits })
+  }
+
+  /** pageview records a $pageview for the current (or given) location. */
+  pageview(path?: string, properties?: Record<string, unknown>): void {
+    const url = isBrowser() ? window.location.href : undefined
+    const p = path ?? (isBrowser() ? window.location.pathname : undefined)
+    this.enqueue('pageview', PAGEVIEW, { url, path: p, properties })
+  }
+
+  /** capture records a named product event with optional properties. Commerce
+   *  fields (productId/quantity/revenue/currency) may be passed for order events. */
+  capture(
+    event: string,
+    properties?: Record<string, unknown>,
+    commerce?: Pick<WireEvent, 'productId' | 'quantity' | 'revenue' | 'currency'>,
+  ): void {
+    this.enqueue('event', event, { properties, ...commerce })
+  }
+
+  /** track is an alias of capture (Segment familiarity). */
+  track = this.capture.bind(this)
+
+  /** captureError records an exception as a first-class error event — the ONE
+   *  error path (subsumes @sentry). A caught error, an unhandled rejection, or a
+   *  manual report all become a type:'error' event on the same stream, lensed to
+   *  the error-tracking view server-side. Never throws back into the app; errors
+   *  are higher-signal than pageviews, so it flushes promptly (a crash may unload
+   *  the page moments later). */
+  captureError(
+    err: unknown,
+    context?: { handled?: boolean; properties?: Record<string, unknown> },
+  ): void {
+    const ex = normalizeError(err)
+    ex.handled = context?.handled ?? true
+    this.enqueue('error', ex.message, { error: ex, properties: context?.properties })
+    this.flush()
+  }
+
+  /** captureException — @sentry-familiar alias of captureError. */
+  captureException = this.captureError.bind(this)
+
+  /** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
+   *  every subsequent event. */
+  setCohort(patch: Cohort): void {
+    this.cohort = mergeCohort(patch)
+  }
+
+  /** flush drains the buffer to the server as one batch. beacon=true uses the
+   *  unload-safe path. */
+  flush(beacon = false): void {
+    if (!this.cfg.enabled || this.queue.length === 0) return
+    const batch = this.queue
+    this.queue = []
+    this.clearTimer()
+    const token = this.cfg.getToken?.() ?? undefined
+    // sendBeacon cannot carry an Authorization header, so token apps always use
+    // keepalive fetch; cookie apps may beacon to the tracker route on unload.
+    const useBeacon = beacon && !token
+    const path = useBeacon ? TRACKER_PATH : ANALYTICS_PATH
+    const body = JSON.stringify({ batch })
+    if (this.cfg.debug) console.debug('[analytics] flush', batch.length, path)
+    this.transport.send(this.cfg.host + path, body, { beacon: useBeacon, token: token ?? undefined })
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  private enqueue(kind: EventKind, event: string | undefined, extra: Partial<WireEvent>): void {
+    if (!this.cfg.enabled) return
+    if (!this.started) this.init()
+    this.queue.push(this.build(kind, event, extra))
+    if (this.queue.length >= this.cfg.batchSize) this.flush()
+    else this.schedule()
+  }
+
+  private build(kind: EventKind, event: string | undefined, extra: Partial<WireEvent>): WireEvent {
+    const anon = anonId()
+    return {
+      messageId: uid(),
+      type: kind,
+      event,
+      timestamp: new Date().toISOString(),
+      distinctId: this.personId ?? anon,
+      anonymousId: anon,
+      personId: this.personId,
+      sessionId: sessionId(),
+      product: this.cfg.product,
+      referrer: this.attribution.referrer,
+      utm: this.attribution.utm,
+      refCode: this.cohort.refCode ?? this.attribution.refCode,
+      channel: this.cohort.channel ?? this.attribution.channel,
+      signupWeek: this.cohort.signupWeek,
+      library: '@hanzo/event',
+      libraryVersion: VERSION,
+      ...extra,
+    }
+  }
+
+  private schedule(): void {
+    if (this.timer || !this.cfg.enabled) return
+    this.timer = setTimeout(() => {
+      this.timer = null
+      this.flush()
+    }, this.cfg.flushIntervalMs)
+  }
+
+  private clearTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+}
+
+/** createAnalytics builds a client instance. Most apps use one shared instance. */
+export function createAnalytics(config: AnalyticsConfig): Analytics {
+  return new Analytics(config)
+}
+
+// Re-export the hydrate helpers so consumers can read persisted cohort/attribution
+// (e.g. to send refCode to the referrals API) without reaching into storage.
+export { getCohort, getFirstTouch }

package/src/events.ts

@@ -0,0 +1,42 @@
+// 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.
+
+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',
+  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',
+  DEPLOY_STARTED: 'deploy_started',
+  PROJECT_CREATED: 'project_created',
+  AGENT_CREATED: 'agent_created',
+  CHAT_STARTED: 'chat_started',
+  CHAT_MESSAGE_SENT: 'chat_message_sent',
+  TASK_STARTED: 'task_started',
+  TASK_COMPLETED: 'task_completed',
+} 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'

package/src/goals.ts

@@ -0,0 +1,55 @@
+// 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.
+
+import { EVENTS } from './events'
+
+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). */
+  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.
+  signup: {
+    label: 'Signup',
+    event: EVENTS.SIGNUP_COMPLETED,
+    funnel: [
+      EVENTS.SIGNUP_VIEWED,
+      EVENTS.SIGNUP_SUBMITTED,
+      EVENTS.SIGNUP_VERIFIED,
+      EVENTS.FIRST_ACTION,
+    ],
+  },
+  // Sale: a completed order qualified as a plan purchase (kind=plan).
+  sale: {
+    label: 'Sale',
+    event: EVENTS.ORDER_COMPLETED,
+    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],
+  },
+}
+
+export interface CohortDef {
+  /** The hanzo.events column the cohort dimension maps to. */
+  field: string
+  label: string
+}
+
+export const COHORTS: Record<'signupWeek' | 'channel' | 'refCode', CohortDef> = {
+  signupWeek: { field: 'signup_week', label: 'Signup week' },
+  channel: { field: 'channel', label: 'Acquisition channel' },
+  refCode: { field: 'ref_code', label: 'Referral code' },
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// @hanzo/event — framework-agnostic entry. The ONE telemetry client.
+//
+//   import { createAnalytics, EVENTS } from '@hanzo/event'
+//   const a = createAnalytics({ product: 'console' })  // same-origin, cookie auth
+//   a.pageview(); a.capture(EVENTS.SIGNUP_COMPLETED)
+//   a.captureError(err)            // errors are events too — one stream
+//
+// React apps use the './react' entry for the provider + hooks + error boundary.
+
+export { Analytics, createAnalytics, VERSION, getCohort, getFirstTouch } from './core'
+export { EVENTS, PAGEVIEW } from './events'
+export type { EventName } from './events'
+export { GOALS, COHORTS } from './goals'
+export type { GoalDef, CohortDef } from './goals'
+export {
+  parseAttribution,
+  deriveChannel,
+  hasAttribution,
+  hostOf,
+  isoWeek,
+} from './attribution'
+export type {
+  AnalyticsConfig,
+  Attribution,
+  Cohort,
+  EventKind,
+  Exception,
+  Transport,
+  WireEvent,
+} from './types'