@holdyapp/sdk 0.2.0 → 1.0.0

package/src/auto-capture.ts

@@ -1,129 +1,102 @@
 /**
- * Auto-capture · Stage 28 G_auto.
+ * Auto-capture de navegação · @holdyapp/sdk/web.
  *
- * Quando HoldyConfig.autoCapture=true, instalamos hooks globais que
- * emitem `session.activity` automaticamente:
+ * Emite pageview no carregamento e a cada mudança de rota, inclusive nas que
+ * não recarregam a página (SPA). Sem isto, instrumentar exige que o cliente
+ * chame `page()` em cada tela — e o primeiro dado só aparece depois de um
+ * trabalho que ele ainda não fez.
  *
- *   · initial_load        · 1x ao init
- *   · route_change        · cada history.pushState/replaceState/popstate
- *   · visibility_change   · página voltou a ficar visível
- *
- * Tudo client-side · não precisa que o customer declare nada. Permite que
- * o widget de install do Holdy mostre "✓ conectado" segundos após o user
- * carregar a página.
- *
- * Idempotente · re-rodar `installAutoCapture` é no-op via guard global.
- * Cleanup ao destroy via array de unsubscribers retornado.
+ * Idempotente: reinstalar é no-op (guard global). O retorno desfaz o patch de
+ * `history`, então `destroy()` devolve o browser como estava.
  */
 
-export interface AutoCaptureEmit {
-  (path: string, title: string | undefined, referrer: string | undefined, kind: 'initial_load' | 'route_change' | 'visibility_change'): void
-}
+const INSTALLED_FLAG = '__holdy_autocapture__'
 
-const INSTALLED_FLAG = '__holdy_autocapture_installed__'
+/** pushState seguido de replaceState é uma mudança lógica só. */
 const ROUTE_DEBOUNCE_MS = 50
 
+export type NavigationKind = 'initial_load' | 'route_change'
+
+export interface AutoCaptureOptions {
+  onNavigate: (kind: NavigationKind) => void
+}
+
 interface GlobalWithFlag {
   [INSTALLED_FLAG]?: boolean
-  history?: History
 }
 
-export function installAutoCapture(emit: AutoCaptureEmit): () => void {
+export function installAutoCapture(opts: AutoCaptureOptions): () => void {
   if (typeof window === 'undefined' || typeof history === 'undefined') {
     return () => undefined
   }
+
   const w = window as unknown as GlobalWithFlag
-  if (w[INSTALLED_FLAG]) {
-    return () => undefined
-  }
+  if (w[INSTALLED_FLAG]) return () => undefined
   w[INSTALLED_FLAG] = true
 
   const cleanups: Array<() => void> = []
   let lastPath = currentPath()
-  let pendingRouteEmit: ReturnType<typeof setTimeout> | null = null
+  let pending: ReturnType<typeof setTimeout> | null = null
 
-  function safeEmit(kind: 'initial_load' | 'route_change' | 'visibility_change'): void {
+  function emit(kind: NavigationKind): void {
     try {
-      const path = currentPath()
-      const title = typeof document !== 'undefined' ? document.title : undefined
-      const referrer = typeof document !== 'undefined' ? document.referrer || undefined : undefined
-      emit(path, title, referrer, kind)
+      opts.onNavigate(kind)
     } catch {
-      // never throw from auto-capture · não pode quebrar a app do cliente
+      // Telemetria nunca derruba a app do cliente.
     }
   }
 
   function scheduleRouteEmit(): void {
-    // Debounce: pushState seguido de replaceState é 1 mudança lógica.
-    if (pendingRouteEmit) clearTimeout(pendingRouteEmit)
-    pendingRouteEmit = setTimeout(() => {
+    if (pending) clearTimeout(pending)
+    pending = setTimeout(() => {
+      pending = null
       const path = currentPath()
-      if (path !== lastPath) {
-        lastPath = path
-        safeEmit('route_change')
-      }
-      pendingRouteEmit = null
+      // Só conta como pageview se a rota mudou de fato — replaceState de
+      // estado interno (filtro, scroll) não é navegação.
+      if (path === lastPath) return
+      lastPath = path
+      emit('route_change')
     }, ROUTE_DEBOUNCE_MS)
   }
 
-  // 1) Initial load
-  safeEmit('initial_load')
+  emit('initial_load')
+
+  const originalPush = history.pushState
+  const originalReplace = history.replaceState
 
-  // 2) Monkeypatch history.pushState/replaceState (SPA SDR navigation)
-  const origPush = history.pushState
-  const origReplace = history.replaceState
   history.pushState = function patchedPush(...args: Parameters<History['pushState']>) {
-    const result = origPush.apply(this, args)
+    const result = originalPush.apply(this, args)
     scheduleRouteEmit()
     return result
   }
   history.replaceState = function patchedReplace(...args: Parameters<History['replaceState']>) {
-    const result = origReplace.apply(this, args)
+    const result = originalReplace.apply(this, args)
     scheduleRouteEmit()
     return result
   }
   cleanups.push(() => {
-    history.pushState = origPush
-    history.replaceState = origReplace
+    history.pushState = originalPush
+    history.replaceState = originalReplace
   })
 
-  // 3) popstate · botão voltar/avançar do browser
-  const popHandler = (): void => scheduleRouteEmit()
-  window.addEventListener('popstate', popHandler)
-  cleanups.push(() => window.removeEventListener('popstate', popHandler))
-
-  // 4) hashchange · single-page apps que usam hash routing (router antigo)
-  const hashHandler = (): void => scheduleRouteEmit()
-  window.addEventListener('hashchange', hashHandler)
-  cleanups.push(() => window.removeEventListener('hashchange', hashHandler))
-
-  // 5) visibility_change · tab voltou a ficar visível depois de >5min
-  let hiddenAt: number | null = null
-  const visHandler = (): void => {
-    if (typeof document === 'undefined') return
-    if (document.visibilityState === 'hidden') {
-      hiddenAt = Date.now()
-    } else if (document.visibilityState === 'visible' && hiddenAt) {
-      const elapsed = Date.now() - hiddenAt
-      hiddenAt = null
-      // Re-emit só se ficou hidden >5min · evita flood quando user troca aba rapidinho
-      if (elapsed > 5 * 60_000) safeEmit('visibility_change')
-    }
-  }
-  if (typeof document !== 'undefined') {
-    document.addEventListener('visibilitychange', visHandler)
-    cleanups.push(() => document.removeEventListener('visibilitychange', visHandler))
-  }
+  // Voltar/avançar do browser e routers baseados em hash.
+  const onPop = (): void => scheduleRouteEmit()
+  window.addEventListener('popstate', onPop)
+  cleanups.push(() => window.removeEventListener('popstate', onPop))
+
+  const onHash = (): void => scheduleRouteEmit()
+  window.addEventListener('hashchange', onHash)
+  cleanups.push(() => window.removeEventListener('hashchange', onHash))
 
-  // Final cleanup function · usado pelo destroy()
   return () => {
-    if (pendingRouteEmit) clearTimeout(pendingRouteEmit)
-    for (const c of cleanups) c()
+    if (pending) clearTimeout(pending)
+    for (const cleanup of cleanups) cleanup()
     w[INSTALLED_FLAG] = false
   }
 }
 
+/** Rota comparável · path + query, sem hash de âncora. */
 function currentPath(): string {
-  if (typeof window === 'undefined' || !window.location) return '/'
-  return window.location.pathname + window.location.search + window.location.hash
+  if (typeof location === 'undefined') return '/'
+  return `${location.pathname}${location.search}${location.hash}`
 }

package/src/browser.ts

@@ -0,0 +1,55 @@
+/**
+ * Entrada do bundle IIFE · global `Holdy` pra instalação por `<script>`.
+ *
+ * Existe pro cliente que não tem bundler (ou não quer mexer no build) poder
+ * instrumentar colando duas linhas no HTML. A API é a mesma de `@holdyapp/sdk/web`
+ * em forma de funções soltas, porque `Holdy.track(...)` é o que se espera de um
+ * global.
+ *
+ * Chamar antes de `init` não lança: telemetria não derruba a página do cliente.
+ */
+
+import { HoldyWeb, type HoldyWebOptions } from './web'
+import type { Properties } from './types'
+
+let instance: HoldyWeb | null = null
+
+export function init(opts: HoldyWebOptions): HoldyWeb {
+  // Idempotente: script duplicado na página não duplica evento.
+  if (!instance) instance = new HoldyWeb(opts)
+  return instance
+}
+
+export function track(name: string, properties?: Properties): void {
+  instance?.track(name, properties)
+}
+
+export function identify(userId: string, traits?: Properties): void {
+  instance?.identify(userId, traits)
+}
+
+export function group(accountKey: string, traits?: Properties): void {
+  instance?.group(accountKey, traits)
+}
+
+export function page(name?: string, properties?: Properties): void {
+  instance?.page(name, properties)
+}
+
+export function reset(): void {
+  instance?.reset()
+}
+
+export async function flush(): Promise<void> {
+  await instance?.flush()
+}
+
+export async function shutdown(): Promise<void> {
+  await instance?.shutdown()
+  instance = null
+}
+
+/** Instância corrente · útil pra depurar no console do browser. */
+export function getInstance(): HoldyWeb | null {
+  return instance
+}

package/src/core.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { HoldyCore } from './core'
+
+interface SentBatch {
+  url: string
+  auth: string | undefined
+  events: Array<Record<string, unknown>>
+}
+
+function mockFetch(status = 202) {
+  const sent: SentBatch[] = []
+  const fn = vi.fn(async (url: unknown, init?: RequestInit) => {
+    sent.push({
+      url: String(url),
+      auth: (init?.headers as Record<string, string> | undefined)?.Authorization,
+      events: (JSON.parse(String(init?.body)) as { events: Array<Record<string, unknown>> }).events,
+    })
+    return { ok: status < 400, status } as Response
+  })
+  vi.stubGlobal('fetch', fn)
+  return { sent, fn }
+}
+
+function makeClient(opts: Partial<ConstructorParameters<typeof HoldyCore>[1]> = {}) {
+  return new HoldyCore('sdk_server', {
+    apiKey: 'hol_test_key',
+    baseUrl: 'https://example.test/api/v1',
+    flushIntervalMs: 0,
+    flushAt: 100,
+    ...opts,
+  })
+}
+
+describe('HoldyCore', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('track enfileira envelope canônico e flush envia pra /events/bulk com Bearer', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient()
+    holdy.track('invite_sent', { plan: 'pro' })
+    expect(holdy.pending).toBe(1)
+
+    await holdy.flush()
+    expect(sent).toHaveLength(1)
+    expect(sent[0].url).toBe('https://example.test/api/v1/events/bulk')
+    expect(sent[0].auth).toBe('Bearer hol_test_key')
+    expect(sent[0].events[0]).toMatchObject({
+      event: 'invite_sent',
+      source: 'sdk_server',
+      properties: { plan: 'pro' },
+    })
+    expect(holdy.pending).toBe(0)
+  })
+
+  it('identify emite $identify e persiste user_id nos próximos events', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient()
+    holdy.identify('user_42', { role: 'admin' })
+    holdy.track('pageview')
+    await holdy.flush()
+
+    expect(sent[0].events[0]).toMatchObject({
+      event: '$identify',
+      user_id: 'user_42',
+      properties: { role: 'admin' },
+    })
+    expect(sent[0].events[1]).toMatchObject({ event: 'pageview', user_id: 'user_42' })
+  })
+
+  it('group emite $group e associa context.account_external_id aos próximos', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient()
+    holdy.group('acme-inc', { plan: 'scale' })
+    holdy.track('feature_used')
+    await holdy.flush()
+
+    expect(sent[0].events[0]).toMatchObject({
+      event: '$group',
+      context: { account_external_id: 'acme-inc' },
+      properties: { plan: 'scale' },
+    })
+    expect(sent[0].events[1]).toMatchObject({
+      event: 'feature_used',
+      context: { account_external_id: 'acme-inc' },
+    })
+    // account_id (uuid Holdy) nunca sai da porta — Data layer resolve
+    expect('account_id' in sent[0].events[1]).toBe(false)
+  })
+
+  it('overrides stateless (server): userId/accountKey por chamada', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient()
+    holdy.track('sync_done', {}, { userId: 'u9', accountKey: 'org-77' })
+    await holdy.flush()
+
+    expect(sent[0].events[0]).toMatchObject({
+      user_id: 'u9',
+      context: { account_external_id: 'org-77' },
+    })
+  })
+
+  it('flushAt dispara flush automático', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient({ flushAt: 2 })
+    holdy.track('a')
+    expect(sent).toHaveLength(0)
+    holdy.track('b')
+    await vi.waitFor(() => expect(sent).toHaveLength(1))
+    expect(sent[0].events).toHaveLength(2)
+  })
+
+  it('5xx re-enfileira (retry dedupe-safe) · 4xx dropa (evita loop)', async () => {
+    const { sent } = mockFetch(500)
+    const holdy = makeClient()
+    holdy.track('x')
+    await holdy.flush()
+    expect(holdy.pending).toBe(1)
+    expect(sent).toHaveLength(1)
+
+    vi.unstubAllGlobals()
+    mockFetch(400)
+    await holdy.flush()
+    expect(holdy.pending).toBe(0)
+  })
+
+  it('network error nunca lança — re-enfileira', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => {
+      throw new Error('ECONNREFUSED')
+    }))
+    const holdy = makeClient()
+    holdy.track('x')
+    await expect(holdy.flush()).resolves.toBeUndefined()
+    expect(holdy.pending).toBe(1)
+  })
+
+  it('batches > 500 são fatiados', async () => {
+    const { sent } = mockFetch()
+    const holdy = makeClient({ flushAt: 10000 })
+    for (let i = 0; i < 750; i++) holdy.track(`e${i}`)
+    await holdy.flush()
+    expect(sent).toHaveLength(2)
+    expect(sent[0].events).toHaveLength(500)
+    expect(sent[1].events).toHaveLength(250)
+  })
+})

package/src/core.ts

@@ -0,0 +1,172 @@
+/**
+ * Core do @holdyapp/sdk · fila + flush pra POST /api/v1/events/bulk.
+ *
+ * Retry de batch inteiro é seguro (partial accept + dedupe server-side).
+ * Fila é bounded: acima de MAX_QUEUE dropa os mais antigos (telemetria nunca
+ * derruba o app do cliente — nenhum método público lança).
+ */
+
+import type { CanonicalEvent, HoldyOptions, Properties, TrackOverrides } from './types'
+
+export const DEFAULT_BASE_URL = 'https://holdy.chat/api/v1'
+const DEFAULT_FLUSH_AT = 20
+const DEFAULT_FLUSH_INTERVAL_MS = 5000
+const MAX_QUEUE = 1000
+const BULK_LIMIT = 500
+
+export class HoldyCore {
+  private readonly apiKey: string
+  private readonly baseUrl: string
+  private readonly flushAt: number
+  private readonly debug: boolean
+  private readonly source: 'sdk_web' | 'sdk_server'
+
+  private queue: CanonicalEvent[] = []
+  private timer: ReturnType<typeof setInterval> | null = null
+  private flushing: Promise<void> | null = null
+
+  protected userId: string | null = null
+  protected anonymousId: string | null = null
+  protected accountKey: string | null = null
+
+  constructor(source: 'sdk_web' | 'sdk_server', opts: HoldyOptions) {
+    this.source = source
+    this.apiKey = opts.apiKey
+    this.accountKey = opts.accountKey ?? null
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '')
+    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT)
+    this.debug = opts.debug ?? false
+
+    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS
+    if (intervalMs > 0) {
+      this.timer = setInterval(() => void this.flush(), intervalMs)
+      // Node: não segura o processo vivo só pelo timer do SDK.
+      if (typeof (this.timer as { unref?: () => void }).unref === 'function') {
+        ;(this.timer as unknown as { unref: () => void }).unref()
+      }
+    }
+  }
+
+  track(name: string, properties?: Properties, overrides?: TrackOverrides): void {
+    if (!name || typeof name !== 'string') return
+
+    const userId = overrides?.userId ?? this.userId ?? undefined
+    const accountKey = overrides?.accountKey ?? this.accountKey ?? undefined
+    const occurredAt = overrides?.occurredAt
+      ? new Date(overrides.occurredAt).toISOString()
+      : new Date().toISOString()
+
+    // Ordem: ambiente observado pelo SDK → context da chamada → carrier de
+    // account. O que o caller passou vence o inferido; o carrier vence tudo,
+    // porque é o que a Data layer usa pra resolver a conta.
+    const context: Properties = {
+      ...this.environmentContext(),
+      ...(overrides?.context ?? {}),
+    }
+    if (accountKey) context.account_external_id = accountKey
+
+    const event: CanonicalEvent = {
+      event: name,
+      occurred_at: occurredAt,
+      source: this.source,
+      ...(userId ? { user_id: userId } : {}),
+      ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),
+      properties: properties ?? {},
+      ...(Object.keys(context).length > 0 ? { context } : {}),
+    }
+
+    this.queue.push(event)
+    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)
+    if (this.queue.length >= this.flushAt) void this.flush()
+  }
+
+  identify(userId: string, traits?: Properties): void {
+    if (!userId || typeof userId !== 'string') return
+    this.userId = userId
+    this.track('$identify', traits ?? {})
+  }
+
+  group(accountKey: string, traits?: Properties): void {
+    if (!accountKey || typeof accountKey !== 'string') return
+    this.accountKey = accountKey
+    this.track('$group', traits ?? {})
+  }
+
+  /** Drena a fila. Nunca lança — falha re-enfileira e loga em debug. */
+  async flush(): Promise<void> {
+    // Serializa flushes concorrentes (timer + flushAt + manual).
+    if (this.flushing) return this.flushing
+    if (this.queue.length === 0) return
+
+    this.flushing = this.drain().finally(() => {
+      this.flushing = null
+    })
+    return this.flushing
+  }
+
+  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */
+  async shutdown(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+    await this.flush()
+  }
+
+  private async drain(): Promise<void> {
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, BULK_LIMIT)
+      const ok = await this.send(batch)
+      if (!ok) {
+        // Devolve pra frente da fila e para — próximo flush re-tenta (dedupe-safe).
+        this.queue.unshift(...batch)
+        return
+      }
+    }
+  }
+
+  private async send(events: CanonicalEvent[]): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/events/bulk`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ events }),
+        ...(this.source === 'sdk_web' ? { keepalive: true } : {}),
+      })
+      if (!res.ok) {
+        // 4xx: batch estruturalmente inválido não re-tenta (evita loop infinito).
+        if (res.status >= 400 && res.status < 500) {
+          this.log(`bulk rejected ${res.status} · batch dropped`)
+          return true
+        }
+        this.log(`bulk failed ${res.status} · will retry`)
+        return false
+      }
+      return true
+    } catch (err) {
+      this.log(`bulk network error: ${(err as Error).message} · will retry`)
+      return false
+    }
+  }
+
+  private log(msg: string): void {
+    if (this.debug) console.warn(`[holdy] ${msg}`)
+  }
+
+  /**
+   * Ambiente que o SDK observa sozinho (url, referrer, browser, utm…).
+   * Vazio no core; `HoldyWeb` preenche. O server não infere ambiente — não
+   * existe "página atual" num worker.
+   */
+  protected environmentContext(): Properties {
+    return {}
+  }
+
+  /** Interno · exposto pra testes. */
+  get pending(): number {
+    return this.queue.length
+  }
+}