@hanzo/event 0.2.0

package/src/react.tsx

@@ -0,0 +1,122 @@
+// React bindings for @hanzo/event — a provider, an accessor hook, a route-change
+// pageview hook, and an error boundary. Framework-neutral: it takes the current
+// path as an argument (the Next app wires usePathname(); a Vite/router app passes
+// its own), so this file never imports next/*.
+//
+//   'use client'
+//   import { AnalyticsProvider, useAnalytics, usePageview, ErrorBoundary } from '@hanzo/event/react'
+//
+//   <AnalyticsProvider config={{ product: 'console' }}>…</AnalyticsProvider>
+//   const a = useAnalytics(); usePageview(usePathname())
+
+import {
+  Component,
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react'
+import { Analytics, createAnalytics } from './core'
+import type { AnalyticsConfig } from './types'
+
+const Ctx = createContext<Analytics | null>(null)
+
+export interface AnalyticsProviderProps {
+  /** Provide a pre-built client, or a config to build one. */
+  client?: Analytics
+  config?: AnalyticsConfig
+  /** Fire a pageview for the initial load (default true). */
+  autoPageview?: boolean
+  children: ReactNode
+}
+
+export function AnalyticsProvider(props: AnalyticsProviderProps) {
+  const { client, config, autoPageview = true, children } = props
+  const instance = useMemo<Analytics>(() => {
+    if (client) return client
+    if (config) return createAnalytics(config)
+    throw new Error('AnalyticsProvider requires `client` or `config`')
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client])
+
+  useEffect(() => {
+    instance.init()
+    if (autoPageview) instance.pageview()
+  }, [instance, autoPageview])
+
+  return createElement(Ctx.Provider, { value: instance }, children)
+}
+
+/** useAnalytics returns the client. Outside a provider it returns a no-op-safe
+ *  null-guarded proxy so calls never throw during SSR/tests. */
+export function useAnalytics(): Analytics {
+  const a = useContext(Ctx)
+  if (!a) return noop
+  return a
+}
+
+/** usePageview fires a pageview on every route CHANGE (not the initial mount —
+ *  the provider's autoPageview covers that, so pages are counted exactly once). */
+export function usePageview(path: string | null | undefined): void {
+  const a = useContext(Ctx)
+  const first = useRef(true)
+  useEffect(() => {
+    if (first.current) {
+      first.current = false
+      return
+    }
+    if (a && path) a.pageview(path)
+  }, [a, path])
+}
+
+// A shared no-op client for use outside a provider — keeps call sites total.
+const noop = new Analytics({ product: 'unknown', enabled: false })
+
+export interface ErrorBoundaryProps {
+  children: ReactNode
+  /** Rendered when a child throws. A function receives the error + a reset. */
+  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode)
+  /** Explicit client; defaults to the one from AnalyticsProvider. */
+  client?: Analytics
+}
+
+interface ErrorBoundaryState {
+  error: Error | null
+}
+
+/** ErrorBoundary reports React render errors to the client as error events —
+ *  React swallows these before window.onerror sees them, so a boundary is the
+ *  ONLY way to capture them. This is the React half of the @sentry replacement.
+ *  Pair it with AnalyticsProvider (it reads the client from context), or pass an
+ *  explicit `client`. */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  static contextType = Ctx
+  declare context: React.ContextType<typeof Ctx>
+  state: ErrorBoundaryState = { error: null }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    const client = this.props.client ?? this.context ?? undefined
+    client?.captureError(error, {
+      handled: false,
+      properties: { componentStack: info.componentStack, react: true },
+    })
+  }
+
+  private reset = () => this.setState({ error: null })
+
+  render(): ReactNode {
+    const { error } = this.state
+    if (error === null) return this.props.children
+    const { fallback } = this.props
+    if (typeof fallback === 'function') return fallback(error, this.reset)
+    return fallback ?? null
+  }
+}

package/src/storage.ts

@@ -0,0 +1,112 @@
+// SSR-safe browser storage for stable identifiers and first-touch state. Every
+// accessor no-ops (returns undefined) when there is no window/localStorage, so the
+// client imports cleanly in a Next.js server component.
+
+import type { Attribution, Cohort } from './types'
+
+const KEY = {
+  anon: 'hz_anon_id',
+  session: 'hz_session',
+  firstTouch: 'hz_first_touch',
+  cohort: 'hz_cohort',
+} as const
+
+/** 30-minute inactivity window defines a session (PostHog/GA convention). */
+const SESSION_TTL_MS = 30 * 60 * 1000
+
+function ls(): Storage | undefined {
+  try {
+    if (typeof window === 'undefined' || !window.localStorage) return undefined
+    return window.localStorage
+  } catch {
+    return undefined // Safari private mode / blocked storage
+  }
+}
+
+function uid(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && 'randomUUID' in c) return c.randomUUID()
+  return 'a-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
+}
+
+/** Stable anonymous id, minted once per browser and reused across sessions. */
+export function anonId(): string | undefined {
+  const s = ls()
+  if (!s) return undefined
+  let v = s.getItem(KEY.anon)
+  if (!v) {
+    v = uid()
+    s.setItem(KEY.anon, v)
+  }
+  return v
+}
+
+interface SessionState {
+  id: string
+  last: number
+}
+
+/** Current session id, rotated after SESSION_TTL_MS of inactivity. */
+export function sessionId(now = Date.now()): string | undefined {
+  const s = ls()
+  if (!s) return undefined
+  let state: SessionState | null = null
+  try {
+    state = JSON.parse(s.getItem(KEY.session) || 'null')
+  } catch {
+    state = null
+  }
+  if (!state || now - state.last > SESSION_TTL_MS) {
+    state = { id: uid(), last: now }
+  } else {
+    state.last = now
+  }
+  s.setItem(KEY.session, JSON.stringify(state))
+  return state.id
+}
+
+/** Read the persisted first-touch attribution. */
+export function getFirstTouch(): Attribution | undefined {
+  const s = ls()
+  if (!s) return undefined
+  try {
+    const v = s.getItem(KEY.firstTouch)
+    return v ? (JSON.parse(v) as Attribution) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Persist first-touch attribution ONCE — never overwrite an existing record. */
+export function setFirstTouchOnce(a: Attribution): Attribution {
+  const s = ls()
+  const existing = getFirstTouch()
+  if (existing) return existing
+  if (s) s.setItem(KEY.firstTouch, JSON.stringify(a))
+  return a
+}
+
+/** Read persisted cohort dimensions. */
+export function getCohort(): Cohort | undefined {
+  const s = ls()
+  if (!s) return undefined
+  try {
+    const v = s.getItem(KEY.cohort)
+    return v ? (JSON.parse(v) as Cohort) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Merge + persist cohort dimensions (signupWeek set once). */
+export function mergeCohort(patch: Cohort): Cohort {
+  const s = ls()
+  const cur = getCohort() || {}
+  const next: Cohort = {
+    signupWeek: cur.signupWeek || patch.signupWeek,
+    channel: patch.channel || cur.channel,
+    refCode: cur.refCode || patch.refCode,
+  }
+  if (s) s.setItem(KEY.cohort, JSON.stringify(next))
+  return next
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+// Public types for the Hanzo Event client.
+
+/** The event kinds — the closed set the server understands. An error is just
+ *  another event on the one stream (lensed to the error-tracking view). */
+export type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error'
+
+/** A captured exception. Carried on a `type:'error'` event; the server lenses it
+ *  into the error-tracking view (sentry.hanzo.ai). */
+export interface Exception {
+  /** Constructor/class name, e.g. "TypeError". */
+  type?: string
+  /** The error message. */
+  message: string
+  /** Stack trace when available. */
+  stack?: string
+  /** false = an unhandled/global error (window.onerror, unhandledrejection);
+   *  true = a caught error the app chose to report. Defaults true. */
+  handled?: boolean
+}
+
+/** First-touch marketing attribution, parsed once and persisted. */
+export interface Attribution {
+  utm: {
+    source?: string
+    medium?: string
+    campaign?: string
+    term?: string
+    content?: string
+  }
+  referrer?: string
+  refCode?: string
+  /** Derived acquisition channel: direct | organic | paid | social | referral. */
+  channel?: string
+}
+
+/** Cohort dimensions carried on every event once known (see goals.ts COHORTS). */
+export interface Cohort {
+  /** ISO week the person first signed up, e.g. "2026-W28". */
+  signupWeek?: string
+  channel?: string
+  refCode?: string
+}
+
+/** One event as sent on the wire. tenant/org is NEVER set here — the server
+ *  stamps it from the validated session. */
+export interface WireEvent {
+  messageId: string
+  type: EventKind
+  event?: string
+  timestamp: string
+  distinctId?: string
+  anonymousId?: string
+  personId?: string
+  sessionId?: string
+  product?: string
+  url?: string
+  path?: string
+  referrer?: string
+  utm?: Attribution['utm']
+  refCode?: string
+  channel?: string
+  groupId?: string
+  signupWeek?: string
+  productId?: string
+  quantity?: number
+  revenue?: number
+  currency?: string
+  /** Set on `type:'error'` events — the captured exception. */
+  error?: Exception
+  properties?: Record<string, unknown>
+  library?: string
+  libraryVersion?: string
+}
+
+/** Injectable transports — overridden in tests; default in core.ts uses fetch. */
+export interface Transport {
+  /** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
+  send(url: string, body: string, opts: { beacon: boolean; token?: string }): void
+}
+
+export interface AnalyticsConfig {
+  /** Cloud base URL. Same-origin ("") for cookie-auth apps (console/admin);
+   *  e.g. "https://api.hanzo.ai" for bearer apps (app/site). */
+  host?: string
+  /** Emitting surface: console | chat | app | site | admin. */
+  product: string
+  /** Bearer token provider for token-auth apps. Omit for cookie/session apps
+   *  (the client then relies on same-origin credentials). */
+  getToken?: () => string | undefined | null
+  /** Max events buffered before an automatic flush. */
+  batchSize?: number
+  /** Auto-flush cadence in ms. */
+  flushIntervalMs?: number
+  /** Turn the client off entirely (e.g. opt-out / DNT). Defaults to enabled. */
+  enabled?: boolean
+  /** Auto-capture unhandled errors + promise rejections (window.onerror,
+   *  unhandledrejection) as error events. Browser-only. Defaults to enabled —
+   *  this is what makes the client a drop-in @sentry replacement. */
+  captureErrors?: boolean
+  /** Override the transport (tests). */
+  transport?: Transport
+  /** Debug logging. */
+  debug?: boolean
+}