@holdyapp/sdk 1.1.0 → 1.5.0

package/src/changes.ts

@@ -0,0 +1,357 @@
+import { changeArm, matchesPathTemplate, type ChangeArm } from './arm'
+
+export type ChangeAnchor =
+  | { kind: 'selector'; value: string }
+  | { kind: 'text'; value: string }
+  | { kind: 'page' }
+
+export interface ProductChange {
+  id: string
+  kind: 'copy' | 'guidance'
+  path: string
+  anchor: ChangeAnchor
+  expected_text: string | null
+  content: { text: string }
+  holdout_pct: number
+}
+
+export interface ProductChangesOptions {
+  baseUrl: string
+  apiKey: string
+  getAccountKey: () => string | null
+  track: (name: string, properties: Record<string, unknown>) => void
+  debug?: boolean
+}
+
+export interface ProductChangesHandle {
+  onNavigate(): void
+  refresh(): Promise<void>
+  teardown(): void
+}
+
+const REFRESH_MS = 5 * 60 * 1000
+const NAV_REFRESH_MS = 60 * 1000
+const SCAN_DEBOUNCE_MS = 250
+const SEEN_KEY = 'holdy_changes_seen'
+const DISMISSED_KEY = 'holdy_changes_dismissed'
+const TIP_GAP_PX = 8
+
+const TIP_CSS = `:host{all:initial}
+.tip{position:fixed;box-sizing:border-box;max-width:280px;padding:10px 12px;border-radius:8px;background:#111;color:#fff;font:13px/1.45 system-ui,-apple-system,sans-serif;box-shadow:0 8px 24px rgba(0,0,0,.18);pointer-events:auto;display:flex;gap:10px;align-items:flex-start}
+.tip p{margin:0;flex:1}
+.tip button{all:unset;cursor:pointer;opacity:.7;font-size:15px;line-height:1}
+.tip button:hover,.tip button:focus-visible{opacity:1}
+@media (prefers-color-scheme:dark){.tip{background:#fff;color:#111}}`
+
+export function normalizeText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+export function parseChanges(body: unknown): ProductChange[] {
+  const list = (body as { changes?: unknown } | null)?.changes
+  return Array.isArray(list) ? list.filter(isChange) : []
+}
+
+function isAnchor(value: unknown): value is ChangeAnchor {
+  const a = value as { kind?: unknown; value?: unknown } | null
+  if (a?.kind === 'page') return true
+  return (a?.kind === 'selector' || a?.kind === 'text') && typeof a.value === 'string' && a.value.length > 0
+}
+
+function isChange(value: unknown): value is ProductChange {
+  const c = value as ProductChange | null
+  return (
+    typeof c?.id === 'string' &&
+    (c.kind === 'copy' || c.kind === 'guidance') &&
+    typeof c.path === 'string' &&
+    isAnchor(c.anchor) &&
+    typeof c.content?.text === 'string' &&
+    typeof c.holdout_pct === 'number'
+  )
+}
+
+export function changesForPage(
+  changes: readonly ProductChange[],
+  path: string,
+  accountKey: string | null,
+): Array<{ change: ProductChange; arm: ChangeArm }> {
+  if (!accountKey) return []
+  return changes
+    .filter((c) => matchesPathTemplate(c.path, path))
+    .map((change) => ({ change, arm: changeArm(change.id, accountKey, change.holdout_pct) }))
+}
+
+function storage(kind: 'local' | 'session'): Storage | undefined {
+  try {
+    return kind === 'local' ? window.localStorage : window.sessionStorage
+  } catch {
+    return undefined
+  }
+}
+
+function readSet(store: Storage | undefined, key: string): Set<string> {
+  try {
+    return new Set(JSON.parse(store?.getItem(key) ?? '[]') as string[])
+  } catch {
+    return new Set()
+  }
+}
+
+function addToSet(store: Storage | undefined, key: string, value: string): void {
+  try {
+    const set = readSet(store, key)
+    set.add(value)
+    store?.setItem(key, JSON.stringify([...set].slice(-200)))
+  } catch {
+    return
+  }
+}
+
+function query(selector: string): Element | null {
+  try {
+    return document.querySelector(selector)
+  } catch {
+    return null
+  }
+}
+
+const TEXT_ANCHOR_TAGS = 'button,a,[role="button"],label,summary,h1,h2,h3,h4,li,td,th,p,span,strong'
+const TEXT_ANCHOR_SCAN_LIMIT = 3000
+
+export function findByText(value: string): Element | null {
+  const wanted = normalizeText(value)
+  let best: Element | null = null
+  let bestLength = Number.POSITIVE_INFINITY
+  const nodes = document.querySelectorAll(TEXT_ANCHOR_TAGS)
+  const total = Math.min(nodes.length, TEXT_ANCHOR_SCAN_LIMIT)
+  for (let i = 0; i < total; i += 1) {
+    const el = nodes[i]
+    const raw = el.textContent ?? ''
+    if (raw.length >= bestLength || normalizeText(raw) !== wanted) continue
+    best = el
+    bestLength = raw.length
+  }
+  return best
+}
+
+function findAnchor(anchor: ChangeAnchor): Element | null {
+  if (anchor.kind === 'page') return null
+  return anchor.kind === 'selector' ? query(anchor.value) : findByText(anchor.value)
+}
+
+function findTextNode(el: Element, match: (text: string) => boolean): Text | null {
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (match(normalizeText(node.textContent ?? ''))) return node as Text
+  }
+  return null
+}
+
+interface AppliedCopy {
+  node: Text
+  original: string
+  next: string
+}
+
+export function installProductChanges(opts: ProductChangesOptions): ProductChangesHandle {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return { onNavigate: () => undefined, refresh: async () => undefined, teardown: () => undefined }
+  }
+
+  let changes: ProductChange[] = []
+  let lastFetch = 0
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let root: ShadowRoot | null = null
+  let host: HTMLElement | null = null
+  const copies = new Map<string, AppliedCopy>()
+  const tips = new Map<string, () => void>()
+
+  const log = (message: string): void => {
+    if (opts.debug) console.warn(`[holdy] ${message}`)
+  }
+
+  const expose = (change: ProductChange, arm: ChangeArm): void => {
+    const key = `${change.id}:${arm}`
+    const session = storage('session')
+    if (readSet(session, SEEN_KEY).has(key)) return
+    addToSet(session, SEEN_KEY, key)
+    opts.track('$change_exposure', { change_id: change.id, arm, kind: change.kind })
+  }
+
+  const eligibleCopyNode = (el: Element, change: ProductChange): Text | null => {
+    const expected = change.expected_text ? normalizeText(change.expected_text) : null
+    const next = normalizeText(change.content.text)
+    return findTextNode(el, (text) => text.length > 0 && (text === next || expected === null || text === expected))
+  }
+
+  const applyCopy = (el: Element, change: ProductChange): boolean => {
+    const next = normalizeText(change.content.text)
+    const current = copies.get(change.id)
+    if (current && current.node.isConnected && normalizeText(current.node.textContent ?? '') === next) return true
+    const node = eligibleCopyNode(el, change)
+    if (!node) return false
+    const text = node.textContent ?? ''
+    if (normalizeText(text) !== next) {
+      copies.set(change.id, { node, original: text, next: change.content.text })
+      node.textContent = text.replace(text.trim(), change.content.text)
+    }
+    return true
+  }
+
+  const restoreCopy = (id: string): void => {
+    const applied = copies.get(id)
+    if (!applied) return
+    if (applied.node.isConnected && normalizeText(applied.node.textContent ?? '') === normalizeText(applied.next)) {
+      applied.node.textContent = applied.original
+    }
+    copies.delete(id)
+  }
+
+  const ensureRoot = (): ShadowRoot | null => {
+    if (root) return root
+    if (!document.body) return null
+    host = document.createElement('holdy-changes')
+    host.setAttribute('data-holdy-root', '1')
+    host.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;z-index:2147483647;pointer-events:none'
+    root = host.attachShadow({ mode: 'closed' })
+    const style = document.createElement('style')
+    style.textContent = TIP_CSS
+    root.appendChild(style)
+    document.body.appendChild(host)
+    return root
+  }
+
+  const showTip = (anchor: Element | null, change: ProductChange): boolean => {
+    if (tips.has(change.id)) return true
+    if (readSet(storage('local'), DISMISSED_KEY).has(change.id)) return true
+    const shadow = ensureRoot()
+    if (!shadow) return false
+
+    const card = document.createElement('div')
+    card.className = 'tip'
+    card.setAttribute('role', 'tooltip')
+    const text = document.createElement('p')
+    text.textContent = change.content.text
+    const close = document.createElement('button')
+    close.type = 'button'
+    close.setAttribute('aria-label', 'Fechar')
+    close.textContent = '×'
+    card.append(text, close)
+    card.style.top = '-9999px'
+    card.style.left = '-9999px'
+    shadow.appendChild(card)
+
+    const remove = (): void => {
+      card.remove()
+      window.removeEventListener('scroll', position, true)
+      window.removeEventListener('resize', position)
+      tips.delete(change.id)
+    }
+
+    function position(): void {
+      if (!anchor) {
+        const corner = card.getBoundingClientRect()
+        card.style.top = `${Math.max(8, window.innerHeight - corner.height - 16)}px`
+        card.style.left = `${Math.max(8, window.innerWidth - corner.width - 16)}px`
+        return
+      }
+      if (!anchor.isConnected) {
+        remove()
+        return
+      }
+      const a = anchor.getBoundingClientRect()
+      const c = card.getBoundingClientRect()
+      let top = a.bottom + TIP_GAP_PX
+      if (top + c.height > window.innerHeight - 8) top = a.top - c.height - TIP_GAP_PX
+      const left = Math.min(Math.max(8, a.left + a.width / 2 - c.width / 2), window.innerWidth - c.width - 8)
+      card.style.top = `${Math.max(8, top)}px`
+      card.style.left = `${Math.max(8, left)}px`
+    }
+
+    close.addEventListener('click', () => {
+      addToSet(storage('local'), DISMISSED_KEY, change.id)
+      opts.track('$change_dismissed', { change_id: change.id, kind: change.kind })
+      remove()
+    })
+    tips.set(change.id, remove)
+    requestAnimationFrame(position)
+    window.addEventListener('scroll', position, true)
+    window.addEventListener('resize', position)
+    return true
+  }
+
+  const scan = (): void => {
+    timer = null
+    const active = changesForPage(changes, location.pathname, opts.getAccountKey())
+    const activeIds = new Set(active.map((a) => a.change.id))
+    for (const id of [...copies.keys()]) if (!activeIds.has(id)) restoreCopy(id)
+    for (const [id, remove] of [...tips]) if (!activeIds.has(id)) remove()
+
+    for (const { change, arm } of active) {
+      const el = findAnchor(change.anchor)
+      if (!el && change.anchor.kind !== 'page') continue
+      if (change.kind === 'copy') {
+        if (!el) continue
+        const shown = arm === 'change' ? applyCopy(el, change) : eligibleCopyNode(el, change) !== null
+        if (shown) expose(change, arm)
+      } else if (arm === 'holdout' || showTip(el, change)) {
+        expose(change, arm)
+      }
+    }
+  }
+
+  const schedule = (): void => {
+    if (timer === null) timer = setTimeout(scan, SCAN_DEBOUNCE_MS)
+  }
+
+  const refresh = async (): Promise<void> => {
+    lastFetch = Date.now()
+    try {
+      const res = await fetch(`${opts.baseUrl}/runtime/changes`, {
+        headers: { Authorization: `Bearer ${opts.apiKey}` },
+      })
+      if (!res.ok) {
+        log(`changes ${res.status}`)
+        return
+      }
+      changes = parseChanges(await res.json())
+      schedule()
+    } catch (err) {
+      log(`changes network error: ${(err as Error).message}`)
+    }
+  }
+
+  const observer =
+    typeof MutationObserver !== 'undefined'
+      ? new MutationObserver(() => {
+          if (changes.length > 0 || copies.size > 0 || tips.size > 0) schedule()
+        })
+      : null
+  const observe = (): void => {
+    if (document.body) observer?.observe(document.body, { childList: true, subtree: true, characterData: true })
+  }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', observe, { once: true })
+  else observe()
+
+  const interval = setInterval(() => void refresh(), REFRESH_MS)
+  void refresh()
+
+  return {
+    onNavigate: () => {
+      if (Date.now() - lastFetch > NAV_REFRESH_MS) void refresh()
+      schedule()
+    },
+    refresh,
+    teardown: () => {
+      clearInterval(interval)
+      if (timer !== null) clearTimeout(timer)
+      observer?.disconnect()
+      for (const id of [...copies.keys()]) restoreCopy(id)
+      for (const remove of [...tips.values()]) remove()
+      host?.remove()
+      host = null
+      root = null
+      changes = []
+    },
+  }
+}

package/src/core.test.ts

@@ -7,7 +7,7 @@ interface SentBatch {
   events: Array<Record<string, unknown>>
 }
 
-function mockFetch(status = 202) {
+function mockFetch(status = 202, headers: Record<string, string> = {}) {
   const sent: SentBatch[] = []
   const fn = vi.fn(async (url: unknown, init?: RequestInit) => {
     sent.push({
@@ -15,7 +15,7 @@ function mockFetch(status = 202) {
       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
+    return { ok: status < 400, status, headers: new Headers(headers) } as Response
   })
   vi.stubGlobal('fetch', fn)
   return { sent, fn }
@@ -34,6 +34,7 @@ function makeClient(opts: Partial<ConstructorParameters<typeof HoldyCore>[1]> =
 describe('HoldyCore', () => {
   afterEach(() => {
     vi.unstubAllGlobals()
+    vi.restoreAllMocks()
   })
 
   it('track enfileira envelope canônico e flush envia pra /events/bulk com Bearer', async () => {
@@ -111,17 +112,90 @@ describe('HoldyCore', () => {
     expect(sent[0].events).toHaveLength(2)
   })
 
-  it('5xx re-enfileira (retry dedupe-safe) · 4xx dropa (evita loop)', async () => {
+  it('todo evento sai com external_id, o mesmo quando o lote é reenviado', async () => {
+    const failing = mockFetch(503)
+    const holdy = makeClient()
+    holdy.track('a')
+    holdy.track('b')
+    await holdy.flush()
+    const ids = failing.sent[0].events.map((e) => e.external_id)
+    expect(ids.every((id) => typeof id === 'string' && id.length > 0)).toBe(true)
+    expect(new Set(ids).size).toBe(2)
+
+    vi.unstubAllGlobals()
+    const retry = mockFetch()
+    vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 61_000)
+    await holdy.flush()
+    expect(retry.sent[0].events.map((e) => e.external_id)).toEqual(ids)
+  })
+
+  it('5xx re-enfileira e espera o backoff antes de tentar de novo', async () => {
     const { sent } = mockFetch(500)
     const holdy = makeClient()
     holdy.track('x')
+    const t0 = Date.now()
+    vi.spyOn(Date, 'now').mockReturnValue(t0)
     await holdy.flush()
     expect(holdy.pending).toBe(1)
+
+    await holdy.flush()
     expect(sent).toHaveLength(1)
 
-    vi.unstubAllGlobals()
+    vi.spyOn(Date, 'now').mockReturnValue(t0 + 61_000)
+    await holdy.flush()
+    expect(sent).toHaveLength(2)
+  })
+
+  it('429 respeita Retry-After e não descarta o lote', async () => {
+    const { sent } = mockFetch(429, { 'Retry-After': '30' })
+    const holdy = makeClient()
+    holdy.track('x')
+    const t0 = Date.now()
+    vi.spyOn(Date, 'now').mockReturnValue(t0)
+    await holdy.flush()
+    expect(holdy.pending).toBe(1)
+
+    vi.spyOn(Date, 'now').mockReturnValue(t0 + 29_000)
+    await holdy.flush()
+    expect(sent).toHaveLength(1)
+
+    vi.spyOn(Date, 'now').mockReturnValue(t0 + 30_001)
+    await holdy.flush()
+    expect(sent).toHaveLength(2)
+    expect(holdy.pending).toBe(1)
+  })
+
+  it('4xx de payload descarta o lote', async () => {
     mockFetch(400)
+    const holdy = makeClient()
+    holdy.track('x')
+    await holdy.flush()
+    expect(holdy.pending).toBe(0)
+  })
+
+  it('chave inválida avisa uma vez no console, mesmo sem debug', async () => {
+    mockFetch(401)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const holdy = makeClient()
+    holdy.track('a')
+    await holdy.flush()
+    holdy.track('b')
+    await holdy.flush()
+    expect(holdy.pending).toBe(0)
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('shutdown envia mesmo durante o backoff', async () => {
+    mockFetch(500)
+    const holdy = makeClient()
+    holdy.track('x')
     await holdy.flush()
+    expect(holdy.pending).toBe(1)
+
+    vi.unstubAllGlobals()
+    const ok = mockFetch()
+    await holdy.shutdown()
+    expect(ok.sent).toHaveLength(1)
     expect(holdy.pending).toBe(0)
   })
 

package/src/core.ts

@@ -1,9 +1,13 @@
 /**
  * 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).
+ * Todo evento sai com `external_id` próprio, então reenviar um lote nunca
+ * duplica (dedupe server-side por source + external_id + occurred_at).
+ * 429 respeita Retry-After; 5xx e rede esperam com backoff exponencial; o lote
+ * volta pra frente da fila em vez de sumir. Chave inválida ou origem recusada
+ * avisam uma vez no console, mesmo sem debug. 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'
@@ -13,10 +17,13 @@ const DEFAULT_FLUSH_AT = 20
 const DEFAULT_FLUSH_INTERVAL_MS = 5000
 const MAX_QUEUE = 1000
 const BULK_LIMIT = 500
+const MAX_BACKOFF_MS = 60_000
+
+type SendOutcome = { kind: 'sent' } | { kind: 'dropped' } | { kind: 'retry'; afterMs: number | null }
 
 export class HoldyCore {
-  private readonly apiKey: string
-  private readonly baseUrl: string
+  protected readonly apiKey: string
+  protected readonly baseUrl: string
   private readonly flushAt: number
   private readonly debug: boolean
   private readonly source: 'sdk_web' | 'sdk_server'
@@ -24,6 +31,9 @@ export class HoldyCore {
   private queue: CanonicalEvent[] = []
   private timer: ReturnType<typeof setInterval> | null = null
   private flushing: Promise<void> | null = null
+  private retryAt = 0
+  private failures = 0
+  private readonly warned = new Set<string>()
 
   protected userId: string | null = null
   protected anonymousId: string | null = null
@@ -69,6 +79,7 @@ export class HoldyCore {
       event: name,
       occurred_at: occurredAt,
       source: this.source,
+      external_id: newEventId(),
       ...(userId ? { user_id: userId } : {}),
       ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),
       properties: properties ?? {},
@@ -76,7 +87,7 @@ export class HoldyCore {
     }
 
     this.queue.push(event)
-    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)
+    this.trimQueue()
     if (this.queue.length >= this.flushAt) void this.flush()
   }
 
@@ -92,16 +103,9 @@ export class HoldyCore {
     this.track('$group', traits ?? {})
   }
 
-  /** Drena a fila. Nunca lança — falha re-enfileira e loga em debug. */
+  /** Drena a fila. Nunca lança — falha re-enfileira e espera antes de tentar de novo. */
   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
+    return this.startFlush(false)
   }
 
   /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */
@@ -110,22 +114,51 @@ export class HoldyCore {
       clearInterval(this.timer)
       this.timer = null
     }
-    await this.flush()
+    await this.startFlush(true)
+  }
+
+  private startFlush(force: boolean): Promise<void> {
+    // Serializa flushes concorrentes (timer + flushAt + manual).
+    if (this.flushing) return this.flushing
+    if (this.queue.length === 0) return Promise.resolve()
+    if (!force && Date.now() < this.retryAt) return Promise.resolve()
+
+    this.flushing = this.drain().finally(() => {
+      this.flushing = null
+    })
+    return this.flushing
   }
 
   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).
+      const outcome = await this.send(batch)
+      if (outcome.kind === 'retry') {
         this.queue.unshift(...batch)
+        this.trimQueue()
+        this.scheduleRetry(outcome.afterMs)
         return
       }
+      this.failures = 0
+      this.retryAt = 0
     }
   }
 
-  private async send(events: CanonicalEvent[]): Promise<boolean> {
+  private scheduleRetry(afterMs: number | null): void {
+    this.failures += 1
+    if (afterMs !== null) {
+      this.retryAt = Date.now() + afterMs
+      return
+    }
+    const backoff = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** (this.failures - 1))
+    this.retryAt = Date.now() + backoff + Math.floor(Math.random() * backoff * 0.2)
+  }
+
+  private trimQueue(): void {
+    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)
+  }
+
+  private async send(events: CanonicalEvent[]): Promise<SendOutcome> {
     try {
       const res = await fetch(`${this.baseUrl}/events/bulk`, {
         method: 'POST',
@@ -136,19 +169,29 @@ export class HoldyCore {
         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
+      if (res.ok) return { kind: 'sent' }
+
+      if (res.status === 429) {
+        this.log('rate limited · will retry after Retry-After')
+        return { kind: 'retry', afterMs: retryAfterMs(res) }
+      }
+      if (res.status >= 500) {
+        this.log(`bulk failed ${res.status} · will retry with backoff`)
+        return { kind: 'retry', afterMs: null }
       }
-      return true
+      if (res.status === 401) {
+        this.warnOnce('401', 'API key inválida ou revogada · eventos descartados. Confira a chave em Configurações › SDK.')
+        return { kind: 'dropped' }
+      }
+      if (res.status === 403) {
+        this.warnOnce('403', 'Origem não permitida ou chave sem escopo events:write · eventos descartados.')
+        return { kind: 'dropped' }
+      }
+      this.log(`bulk rejected ${res.status} · batch dropped`)
+      return { kind: 'dropped' }
     } catch (err) {
-      this.log(`bulk network error: ${(err as Error).message} · will retry`)
-      return false
+      this.log(`bulk network error: ${(err as Error).message} · will retry with backoff`)
+      return { kind: 'retry', afterMs: null }
     }
   }
 
@@ -156,6 +199,12 @@ export class HoldyCore {
     if (this.debug) console.warn(`[holdy] ${msg}`)
   }
 
+  private warnOnce(key: string, msg: string): void {
+    if (this.warned.has(key)) return
+    this.warned.add(key)
+    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
@@ -170,3 +219,18 @@ export class HoldyCore {
     return this.queue.length
   }
 }
+
+function retryAfterMs(res: Response): number | null {
+  const raw = typeof res.headers?.get === 'function' ? res.headers.get('Retry-After') : null
+  if (!raw) return null
+  const seconds = Number(raw)
+  if (!Number.isFinite(seconds) || seconds < 0) return null
+  return Math.min(MAX_BACKOFF_MS, seconds * 1000)
+}
+
+function newEventId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto
+  if (typeof c?.randomUUID === 'function') return c.randomUUID()
+  const rand = () => Math.random().toString(36).slice(2, 12)
+  return `${Date.now().toString(36)}-${rand()}-${rand()}`
+}