@holdyapp/sdk 0.2.1 → 1.0.0

package/src/queue.ts

@@ -1,296 +0,0 @@
-/**
- * Event queue · IndexedDB-backed retry com exponential backoff.
- *
- * Por que existe: SDK fire-and-forget perde eventos quando rede falha
- * (offline · 429 · 500 transitório · pagehide mid-flight). Sem fila, drop
- * silencioso · learning loop pega só os 80-90% que chegam.
- *
- * Comportamento:
- *   · enqueue(events) tenta enviar imediatamente. Se falha (ou já tinha fila),
- *     grava em IndexedDB com nextRetryAt = agora + 1s.
- *   · flusher background polla a cada 5s, dequeue ordenado por nextRetryAt,
- *     manda batch. Sucesso → delete da fila. Falha → backoff próximo.
- *   · Backoff: 1s → 2s → 4s → 8s → 16s. Após 5 tentativas, drop com log.
- *   · Cap 1000 itens (rough proxy 50KB cada · 50MB max). Quando cheio, drop
- *     o mais antigo (FIFO).
- *   · pagehide: tenta drain síncrono final via keepalive fetch (browser
- *     entrega depois mesmo se aba fechou).
- *
- * Fallback: ambientes sem IndexedDB (SSR · Privacy mode em Safari rígido) caem
- * pra fila em memória — perde tudo no reload, mas SDK ainda funciona.
- */
-
-const DB_NAME = 'holdy_sdk_v1'
-const STORE_NAME = 'event_queue'
-const MAX_QUEUE_SIZE = 1000
-const MAX_ATTEMPTS = 5
-const FLUSH_INTERVAL_MS = 5000
-const BACKOFF_BASE_MS = 1000
-
-export interface QueuedBatch {
-  /** Auto-increment key. */
-  id?: number
-  /** Eventos serializados (já com idempotency_key gerado). */
-  events: unknown[]
-  attempts: number
-  next_retry_at: number
-  created_at: number
-}
-
-export interface SendFn {
-  /** Retorna true em sucesso, false em falha (caller decide retry). */
-  (body: { events: unknown[] }): Promise<boolean>
-}
-
-interface QueueDriver {
-  add(batch: Omit<QueuedBatch, 'id'>): Promise<void>
-  /** Retorna itens elegíveis pra retry (next_retry_at <= now), ordenados. */
-  pickDue(now: number, limit: number): Promise<QueuedBatch[]>
-  update(item: QueuedBatch): Promise<void>
-  remove(id: number): Promise<void>
-  count(): Promise<number>
-  dropOldest(n: number): Promise<void>
-  /** Pra pagehide drain. */
-  all(): Promise<QueuedBatch[]>
-}
-
-/* ─────────────────────────────────────────────────────────────────────────
- * IndexedDB driver
- * ──────────────────────────────────────────────────────────────────────── */
-
-function isIdbAvailable(): boolean {
-  return typeof indexedDB !== 'undefined'
-}
-
-let dbPromise: Promise<IDBDatabase> | null = null
-
-function openDb(): Promise<IDBDatabase> {
-  if (dbPromise) return dbPromise
-  dbPromise = new Promise((resolve, reject) => {
-    const req = indexedDB.open(DB_NAME, 1)
-    req.onupgradeneeded = () => {
-      const db = req.result
-      if (!db.objectStoreNames.contains(STORE_NAME)) {
-        db.createObjectStore(STORE_NAME, { keyPath: 'id', autoIncrement: true })
-      }
-    }
-    req.onsuccess = () => resolve(req.result)
-    req.onerror = () => reject(req.error)
-  })
-  return dbPromise
-}
-
-function withStore<T>(
-  mode: IDBTransactionMode,
-  fn: (store: IDBObjectStore) => IDBRequest | Promise<T>,
-): Promise<T> {
-  return openDb().then(
-    (db) =>
-      new Promise<T>((resolve, reject) => {
-        const tx = db.transaction(STORE_NAME, mode)
-        const store = tx.objectStore(STORE_NAME)
-        let result: T | undefined
-        try {
-          const out = fn(store)
-          if (out instanceof IDBRequest) {
-            out.onsuccess = () => {
-              result = out.result as T
-            }
-            out.onerror = () => reject(out.error)
-          } else {
-            void out.then((v) => (result = v))
-          }
-        } catch (e) {
-          reject(e)
-          return
-        }
-        tx.oncomplete = () => resolve(result as T)
-        tx.onerror = () => reject(tx.error)
-        tx.onabort = () => reject(tx.error)
-      }),
-  )
-}
-
-const idbDriver: QueueDriver = {
-  async add(batch) {
-    await withStore('readwrite', (store) => store.add(batch))
-  },
-  async pickDue(now, limit) {
-    const all = await withStore<QueuedBatch[]>('readonly', (store) => store.getAll())
-    return (all ?? [])
-      .filter((b) => b.next_retry_at <= now)
-      .sort((a, b) => a.next_retry_at - b.next_retry_at)
-      .slice(0, limit)
-  },
-  async update(item) {
-    await withStore('readwrite', (store) => store.put(item))
-  },
-  async remove(id) {
-    await withStore('readwrite', (store) => store.delete(id))
-  },
-  async count() {
-    return withStore<number>('readonly', (store) => store.count())
-  },
-  async dropOldest(n) {
-    const all = await withStore<QueuedBatch[]>('readonly', (store) => store.getAll())
-    const sorted = (all ?? []).sort((a, b) => a.created_at - b.created_at).slice(0, n)
-    for (const item of sorted) {
-      if (item.id !== undefined) {
-        await withStore('readwrite', (store) => store.delete(item.id as number))
-      }
-    }
-  },
-  async all() {
-    return (await withStore<QueuedBatch[]>('readonly', (store) => store.getAll())) ?? []
-  },
-}
-
-/* ─────────────────────────────────────────────────────────────────────────
- * In-memory fallback driver
- * ──────────────────────────────────────────────────────────────────────── */
-
-class MemoryDriver implements QueueDriver {
-  private items: QueuedBatch[] = []
-  private nextId = 1
-
-  async add(batch: Omit<QueuedBatch, 'id'>): Promise<void> {
-    this.items.push({ ...batch, id: this.nextId++ })
-  }
-  async pickDue(now: number, limit: number): Promise<QueuedBatch[]> {
-    return this.items
-      .filter((b) => b.next_retry_at <= now)
-      .sort((a, b) => a.next_retry_at - b.next_retry_at)
-      .slice(0, limit)
-  }
-  async update(item: QueuedBatch): Promise<void> {
-    const idx = this.items.findIndex((i) => i.id === item.id)
-    if (idx >= 0) this.items[idx] = item
-  }
-  async remove(id: number): Promise<void> {
-    this.items = this.items.filter((i) => i.id !== id)
-  }
-  async count(): Promise<number> {
-    return this.items.length
-  }
-  async dropOldest(n: number): Promise<void> {
-    this.items.sort((a, b) => a.created_at - b.created_at)
-    this.items.splice(0, n)
-  }
-  async all(): Promise<QueuedBatch[]> {
-    return [...this.items]
-  }
-}
-
-/* ─────────────────────────────────────────────────────────────────────────
- * EventQueue · facade
- * ──────────────────────────────────────────────────────────────────────── */
-
-export class EventQueue {
-  private readonly driver: QueueDriver
-  private readonly send: SendFn
-  private flushTimer: ReturnType<typeof setInterval> | null = null
-  private flushing = false
-  private readonly log: (...args: unknown[]) => void
-
-  constructor(send: SendFn, log: (...args: unknown[]) => void = () => undefined) {
-    this.driver = isIdbAvailable() ? idbDriver : new MemoryDriver()
-    this.send = send
-    this.log = log
-    this.startFlusher()
-    this.bindPagehide()
-  }
-
-  /**
-   * Tenta enviar imediato; se falhar OU já houver fila pendente (ordem),
-   * adiciona com next_retry_at = agora + 1s.
-   */
-  async enqueue(events: unknown[]): Promise<void> {
-    if (events.length === 0) return
-
-    // Se já há fila, vai pro final pra preservar ordem temporal.
-    const pending = await this.driver.count().catch(() => 0)
-    if (pending === 0) {
-      const ok = await this.send({ events }).catch(() => false)
-      if (ok) return
-    }
-
-    // Cap · drop oldest se cheia
-    if (pending >= MAX_QUEUE_SIZE) {
-      const overflow = pending - MAX_QUEUE_SIZE + 1
-      await this.driver.dropOldest(overflow).catch(() => undefined)
-      this.log('queue full · dropped', overflow, 'oldest batches')
-    }
-
-    const now = Date.now()
-    await this.driver
-      .add({
-        events,
-        attempts: 0,
-        next_retry_at: now + BACKOFF_BASE_MS,
-        created_at: now,
-      })
-      .catch((e) => this.log('queue add failed', e))
-  }
-
-  private startFlusher(): void {
-    if (this.flushTimer) return
-    if (typeof setInterval === 'undefined') return
-    this.flushTimer = setInterval(() => {
-      void this.flushOnce()
-    }, FLUSH_INTERVAL_MS)
-  }
-
-  private async flushOnce(): Promise<void> {
-    if (this.flushing) return
-    this.flushing = true
-    try {
-      const now = Date.now()
-      const due = await this.driver.pickDue(now, 10).catch(() => [])
-      for (const item of due) {
-        const ok = await this.send({ events: item.events }).catch(() => false)
-        if (ok && item.id !== undefined) {
-          await this.driver.remove(item.id).catch(() => undefined)
-          continue
-        }
-        const attempts = item.attempts + 1
-        if (attempts >= MAX_ATTEMPTS) {
-          if (item.id !== undefined) await this.driver.remove(item.id).catch(() => undefined)
-          this.log('dropped batch after max attempts', { events: item.events.length })
-          continue
-        }
-        const backoff = BACKOFF_BASE_MS * Math.pow(2, attempts)
-        await this.driver
-          .update({ ...item, attempts, next_retry_at: Date.now() + backoff })
-          .catch(() => undefined)
-      }
-    } finally {
-      this.flushing = false
-    }
-  }
-
-  private bindPagehide(): void {
-    if (typeof window === 'undefined') return
-    const drain = (): void => {
-      // Pagehide é sincrônico · não podemos await IDB. Em vez disso, dispara
-      // 1 fetch keepalive por batch pendente. Browser entrega após close.
-      void this.driver
-        .all()
-        .then((items) => {
-          for (const item of items) {
-            void this.send({ events: item.events }).catch(() => undefined)
-          }
-        })
-        .catch(() => undefined)
-    }
-    window.addEventListener('pagehide', drain)
-    window.addEventListener('beforeunload', drain)
-  }
-
-  /** Pra testes. */
-  destroy(): void {
-    if (this.flushTimer) {
-      clearInterval(this.flushTimer)
-      this.flushTimer = null
-    }
-  }
-}

package/src/render/kinds/banner.ts

@@ -1,52 +0,0 @@
-import type { InterventionPayload } from '../../types'
-import {
-  buildActionsRow,
-  buildCloseButton,
-  buildCtaButton,
-  buildTextNode,
-  type RenderControl,
-  type RenderHandlers,
-} from './shared'
-
-export function renderBanner(
-  payload: InterventionPayload,
-  handlers: RenderHandlers,
-): RenderControl {
-  const card = document.createElement('div')
-  card.className = 'holdy-card holdy-banner'
-  card.setAttribute('role', 'status')
-
-  const text = buildTextNode(payload.text)
-  card.appendChild(text)
-
-  const close = buildCloseButton(() => dismiss('dismissed'))
-  const cta = buildCtaButton(payload, () => {
-    handlers.onExecuted()
-    cleanup()
-  })
-
-  // Banner mantém actions inline (não em row separada) pra economizar altura.
-  const inlineActions = buildActionsRow(cta, close)
-  if (inlineActions) {
-    inlineActions.style.marginTop = '0'
-    card.appendChild(inlineActions)
-  } else {
-    card.appendChild(close)
-  }
-
-  let dismissed = false
-  const cleanup = (): void => {
-    if (dismissed) return
-    dismissed = true
-    card.remove()
-  }
-
-  const dismiss = (outcome: 'dismissed' | 'no_show' | 'failed' = 'dismissed'): void => {
-    if (dismissed) return
-    if (outcome === 'dismissed') handlers.onDismissed()
-    if (outcome === 'failed') handlers.onFailed()
-    cleanup()
-  }
-
-  return { el: card, dismiss: (o) => dismiss(o === 'failed' || o === 'no_show' ? o : 'dismissed') }
-}

package/src/render/kinds/checklist.ts

@@ -1,175 +0,0 @@
-import type { ChecklistItem, InterventionPayload } from '../../types'
-import {
-  buildCloseButton,
-  type RenderControl,
-  type RenderHandlers,
-} from './shared'
-
-const STATE_KEY_PREFIX = 'holdy_checklist_'
-
-/**
- * Checklist · sticky bottom-right com lista de tarefas.
- *
- * Persistência: estado por decision_id em localStorage (chave
- * `holdy_checklist_{decision_id}`). Rehidratado em re-render.
- *
- * UX:
- *   · cada item tem checkbox · clique marca/desmarca
- *   · item com href abre em _self quando label clicado (após marcar)
- *   · primeiro completed dispara onExecuted UMA vez (não a cada check)
- *   · todos completed dispara onExecuted com metadata={completed:true}
- *   · close button dispara onDismissed
- *
- * NÃO há outcome 'converted' aqui — fica pro caller (Holdy backend) detectar
- * via workflow.completed downstream.
- */
-export function renderChecklist(
-  payload: InterventionPayload,
-  decisionId: string,
-  handlers: RenderHandlers,
-): RenderControl {
-  const items = payload.items ?? []
-  if (items.length === 0) {
-    // payload inválido · checklist sem items
-    handlers.onFailed({ reason: 'empty_items' })
-    const empty = document.createElement('div')
-    return { el: empty, dismiss: () => undefined }
-  }
-
-  const state = readState(decisionId, items)
-
-  const card = document.createElement('div')
-  card.className = 'holdy-card holdy-checklist'
-  card.setAttribute('role', 'region')
-  card.setAttribute('aria-label', payload.title ?? 'Lista de tarefas')
-
-  // Header com title + close
-  const header = document.createElement('div')
-  header.className = 'holdy-checklist-header'
-
-  if (payload.title) {
-    const h = document.createElement('h3')
-    h.className = 'holdy-checklist-title'
-    h.textContent = payload.title
-    header.appendChild(h)
-  }
-
-  const close = buildCloseButton(() => dismiss('dismissed'))
-  header.appendChild(close)
-  card.appendChild(header)
-
-  if (payload.text) {
-    const text = document.createElement('p')
-    text.className = 'holdy-card-text'
-    text.textContent = payload.text
-    card.appendChild(text)
-  }
-
-  // Lista
-  const list = document.createElement('ul')
-  list.className = 'holdy-checklist-list'
-
-  let firedExecuted = false
-  let firedCompleted = false
-
-  const renderItems = (): void => {
-    list.textContent = ''
-    items.forEach((item) => {
-      const li = document.createElement('li')
-      li.className = state[item.id] ? 'holdy-checklist-item is-done' : 'holdy-checklist-item'
-
-      const checkbox = document.createElement('input')
-      checkbox.type = 'checkbox'
-      checkbox.className = 'holdy-checklist-checkbox'
-      checkbox.checked = !!state[item.id]
-      checkbox.setAttribute('aria-label', `Marcar ${item.label}`)
-      checkbox.addEventListener('change', () => toggleItem(item, checkbox.checked))
-
-      const labelEl = item.href
-        ? document.createElement('a')
-        : document.createElement('span')
-      labelEl.className = 'holdy-checklist-label'
-      labelEl.textContent = item.label
-      if (item.href) {
-        ;(labelEl as HTMLAnchorElement).href = item.href
-        ;(labelEl as HTMLAnchorElement).rel = 'noopener noreferrer'
-        labelEl.addEventListener('click', () => toggleItem(item, true))
-      }
-
-      li.appendChild(checkbox)
-      li.appendChild(labelEl)
-      list.appendChild(li)
-    })
-  }
-
-  const toggleItem = (item: ChecklistItem, completed: boolean): void => {
-    state[item.id] = completed
-    persistState(decisionId, state)
-
-    if (completed && !firedExecuted) {
-      firedExecuted = true
-      handlers.onExecuted({ item_id: item.id })
-    }
-
-    const allDone = items.every((i) => state[i.id])
-    if (allDone && !firedCompleted) {
-      firedCompleted = true
-      handlers.onExecuted({ completed: true })
-    }
-
-    renderItems()
-  }
-
-  renderItems()
-  card.appendChild(list)
-
-  let dismissed = false
-  const cleanup = (): void => {
-    if (dismissed) return
-    dismissed = true
-    card.remove()
-  }
-
-  const dismiss = (outcome: 'dismissed' | 'no_show' | 'failed' = 'dismissed'): void => {
-    if (dismissed) return
-    if (outcome === 'dismissed') handlers.onDismissed()
-    if (outcome === 'failed') handlers.onFailed()
-    cleanup()
-  }
-
-  return { el: card, dismiss: (o) => dismiss(o === 'failed' || o === 'no_show' ? o : 'dismissed') }
-}
-
-function readState(
-  decisionId: string,
-  items: ChecklistItem[],
-): Record<string, boolean> {
-  // Default: respeitar `completed` do payload (server pode pré-marcar items)
-  const initial: Record<string, boolean> = {}
-  items.forEach((i) => {
-    initial[i.id] = !!i.completed
-  })
-
-  if (typeof localStorage === 'undefined') return initial
-  try {
-    const raw = localStorage.getItem(STATE_KEY_PREFIX + decisionId)
-    if (!raw) return initial
-    const parsed = JSON.parse(raw) as Record<string, boolean>
-    // Merge · localStorage tem prioridade sobre server pre-marks
-    items.forEach((i) => {
-      if (typeof parsed[i.id] === 'boolean') initial[i.id] = parsed[i.id]
-    })
-    return initial
-  } catch {
-    return initial
-  }
-}
-
-function persistState(decisionId: string, state: Record<string, boolean>): void {
-  if (typeof localStorage === 'undefined') return
-  try {
-    localStorage.setItem(STATE_KEY_PREFIX + decisionId, JSON.stringify(state))
-  } catch {
-    // quota · silent
-  }
-}

package/src/render/kinds/cta.ts

@@ -1,53 +0,0 @@
-import type { InterventionPayload } from '../../types'
-import {
-  buildActionsRow,
-  buildCloseButton,
-  buildCtaButton,
-  buildTextNode,
-  type RenderControl,
-  type RenderHandlers,
-} from './shared'
-
-/**
- * CTA sticky bottom-right · usado quando não há anchor específico mas a
- * intervention precisa de presença persistente (ex: convite pra rodar
- * onboarding workflow).
- */
-export function renderCta(
-  payload: InterventionPayload,
-  handlers: RenderHandlers,
-): RenderControl {
-  const card = document.createElement('div')
-  card.className = 'holdy-card holdy-cta'
-  card.setAttribute('role', 'dialog')
-  card.setAttribute('aria-label', 'Sugestão Holdy')
-
-  const text = buildTextNode(payload.text)
-  card.appendChild(text)
-
-  const close = buildCloseButton(() => dismiss('dismissed'))
-  const cta = buildCtaButton(payload, () => {
-    handlers.onExecuted()
-    cleanup()
-  })
-
-  const actions = buildActionsRow(cta, close)
-  if (actions) card.appendChild(actions)
-  else card.appendChild(close)
-
-  let dismissed = false
-  const cleanup = (): void => {
-    if (dismissed) return
-    dismissed = true
-    card.remove()
-  }
-
-  const dismiss = (outcome: 'dismissed' | 'no_show' | 'failed' = 'dismissed'): void => {
-    if (dismissed) return
-    if (outcome === 'dismissed') handlers.onDismissed()
-    if (outcome === 'failed') handlers.onFailed()
-    cleanup()
-  }
-
-  return { el: card, dismiss: (o) => dismiss(o === 'failed' || o === 'no_show' ? o : 'dismissed') }
-}

package/src/render/kinds/modal.ts

@@ -1,129 +0,0 @@
-import type { InterventionPayload } from '../../types'
-import {
-  buildActionsRow,
-  buildCloseButton,
-  buildCtaButton,
-  buildTextNode,
-  type RenderControl,
-  type RenderHandlers,
-} from './shared'
-
-/**
- * Modal · overlay centralizado com backdrop.
- *
- * UX:
- *   · backdrop click dismissa (igual padrão Apple/Stripe)
- *   · ESC dismissa
- *   · focus trap entre primeiro/último focusable
- *   · scroll body bloqueado enquanto aberto
- *   · role=dialog + aria-modal pra acessibilidade
- *
- * Uso: intervention de alto peso (renewal aproximando, churn risk
- * crítico, expansion oferecida com 1 click). Limite global de 1.
- */
-export function renderModal(
-  payload: InterventionPayload,
-  handlers: RenderHandlers,
-): RenderControl {
-  const backdrop = document.createElement('div')
-  backdrop.className = 'holdy-modal-backdrop'
-
-  const card = document.createElement('div')
-  card.className = 'holdy-card holdy-modal'
-  card.setAttribute('role', 'dialog')
-  card.setAttribute('aria-modal', 'true')
-  card.tabIndex = -1
-
-  if (payload.title) {
-    const h = document.createElement('h2')
-    h.className = 'holdy-card-title'
-    h.textContent = payload.title
-    card.appendChild(h)
-  }
-
-  const text = buildTextNode(payload.text)
-  card.appendChild(text)
-
-  const close = buildCloseButton(() => dismiss('dismissed'))
-  const cta = buildCtaButton(payload, () => {
-    handlers.onExecuted()
-    cleanup()
-  })
-
-  const actions = buildActionsRow(cta, close)
-  if (actions) card.appendChild(actions)
-  else card.appendChild(close)
-
-  backdrop.appendChild(card)
-
-  // Body scroll lock
-  const prevBodyOverflow = document.body.style.overflow
-  document.body.style.overflow = 'hidden'
-
-  // Backdrop click dismissa (mas só se for clique direto no backdrop, não no card)
-  backdrop.addEventListener('click', (e) => {
-    if (e.target === backdrop) dismiss('dismissed', { reason: 'backdrop_click' })
-  })
-
-  // Focus management
-  const previouslyFocused = document.activeElement as HTMLElement | null
-  const focusFirst = (): void => {
-    requestAnimationFrame(() => {
-      const focusable = card.querySelector<HTMLElement>('a, button, [tabindex]:not([tabindex="-1"])')
-      ;(focusable ?? card).focus()
-    })
-  }
-  focusFirst()
-
-  const onKeydown = (e: KeyboardEvent): void => {
-    if (e.key === 'Escape') {
-      e.stopPropagation()
-      dismiss('dismissed', { reason: 'esc' })
-      return
-    }
-    if (e.key !== 'Tab') return
-    // Focus trap simples · só dentro do card
-    const focusables = Array.from(
-      card.querySelectorAll<HTMLElement>('a, button, [tabindex]:not([tabindex="-1"])'),
-    )
-    if (focusables.length === 0) return
-    const first = focusables[0]
-    const last = focusables[focusables.length - 1]
-    const active = document.activeElement
-    if (e.shiftKey && active === first) {
-      e.preventDefault()
-      last.focus()
-    } else if (!e.shiftKey && active === last) {
-      e.preventDefault()
-      first.focus()
-    }
-  }
-  document.addEventListener('keydown', onKeydown, true)
-
-  let dismissed = false
-  const cleanup = (): void => {
-    if (dismissed) return
-    dismissed = true
-    document.body.style.overflow = prevBodyOverflow
-    document.removeEventListener('keydown', onKeydown, true)
-    backdrop.remove()
-    if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
-      previouslyFocused.focus()
-    }
-  }
-
-  const dismiss = (
-    outcome: 'dismissed' | 'no_show' | 'failed' = 'dismissed',
-    metadata?: Record<string, unknown>,
-  ): void => {
-    if (dismissed) return
-    if (outcome === 'dismissed') handlers.onDismissed(metadata)
-    if (outcome === 'failed') handlers.onFailed(metadata)
-    cleanup()
-  }
-
-  return {
-    el: backdrop,
-    dismiss: (o) => dismiss(o === 'failed' || o === 'no_show' ? o : 'dismissed'),
-  }
-}