@holdyapp/sdk

Holdy SDK · behavioral telemetry + in-product interventions for B2B SaaS Customer Success.

< 15kb gzipped. Sem dependências runtime. ESM + CJS + IIFE builds.

Instalação rápida

Opção 1 · npx (recomendado · 1 minuto)

npx @holdyapp/install <SUA_API_KEY>

Detecta seu framework (Next.js, Vite, Vue, Nuxt, vanilla HTML) e injeta o snippet no lugar certo.

Opção 2 · Script tag (CDN)

<script src="https://app.holdy.com.br/sdk/v0/holdy.iife.js"></script>
<script>
  Holdy.init({
    apiKey: 'hol_live_xxxxxxxx',
    accountId: 'acme-corp',
    autoCapture: true,
  })
</script>

Opção 3 · npm + ES module

npm install @holdyapp/sdk

import { Holdy } from '@holdyapp/sdk'

Holdy.init({
  apiKey: 'hol_live_xxxxxxxx',
  accountId: 'acme-corp',
  autoCapture: true,
})

Identify rico

Holdy nunca sobrescreve dados preenchidos no wizard — sempre COALESCE. Você pode chamar identify() várias vezes; backend só preenche campos vazios.

Holdy.identify({
  account: {
    external_id: 'acct_123',
    name: 'Acme Corp',
    logo_url: 'https://acme.com/logo.png',
    plan: 'Enterprise',
    mrr: 5000,
  },
  user: {
    external_id: 'user_456',
    email: '[email protected]',
    name: 'John Doe',
    role: 'decision_maker',
  },
})

Track manual (eventos canônicos)

20 primitives semânticos validados por taxonomia v1. Lista completa em https://app.holdy.com.br/api/v1/docs.

// Workflow bloqueado · um dos sinais mais úteis pro motor de decisão
Holdy.track('workflow.blocked', {
  workflow: 'invoice-export',
  reason: 'permission_denied',
  severity: 'high',
})

// Fricção detectada (rage clicks, retry loop, etc)
Holdy.track('friction.detected', {
  signal: 'rage_click',
  surface: '/billing',
})

// Sinal de expansão
Holdy.track('expansion.intent_detected', {
  workflow: 'pricing-page-view',
  evidence: 'visited 3x in 7d',
})

Auto-capture (sem código)

Quando autoCapture: true (recomendado em desenvolvimento e produção), o SDK monitora navegação do SPA automaticamente:

• Carregamento inicial da página
• pushState / replaceState (Next.js, React Router, Vue Router)
• popstate (botão voltar)

Cada navegação gera memory.append com {kind: 'route', path, title, referrer}. Você vê dados no Holdy assim que o cliente carregar a página — sem precisar instrumentar nada manualmente.

Track manual continua disponível para os sinais semânticos (workflow/friction/expansion/outcome) que o auto-capture não pode adivinhar.

Render in-product

Quando o backend de decisão sugere uma intervenção (tooltip, banner, modal, checklist, spotlight, CTA), o SDK renderiza automaticamente. Desabilitar:

Holdy.init({
  apiKey: '...',
  renderInterventions: false, // SDK só captura, não renderiza nada
})

Reportar outcome

Holdy.onDecision((decision) => {
  // ... seu código pode reagir
})

// Após o user agir em consequência:
Holdy.reportOutcome(decisionId, 'converted', { value: 99 })

Configuração completa

interface HoldyConfig {
  apiKey: string                  // hol_live_… ou hol_test_…
  apiUrl?: string                 // default: https://app.holdy.com.br/api/v1
  accountId?: string              // ID Holdy ou external_id (use identify pra rico)
  userId?: string
  sessionId?: string
  consumer?: 'ui' | 'csm' | 'agent'
  debug?: boolean                 // console.warn em erros
  renderInterventions?: boolean   // default: true
  autoCapture?: boolean           // default: false · auto page.view tracking
}

Tamanho

Bundle IIFE gzip < 15kb (budget enforced no build).

Licença

MIT