Holdy
Documentação/SDK Server

SDK Server

Os eventos de negócio que mais importam — workspace criado, pagamento aprovado, integração conectada, limite atingido — acontecem no backend. O SDK server (@holdy/sdk/server) é o caminho para reportá-los. Requer Node 18+ e funciona em runtimes Edge.

Setup

import { Holdy } from '@holdy/sdk/server'

const holdy = new Holdy({ apiKey: process.env.HOLDY_API_KEY! })

Uso

O server é stateless por chamada: usuário e conta vão como overrides em cada track, nunca como estado da instância — em um servidor multi-tenant, estado de sessão vazaria identidade entre requests.

holdy.track('sync_completed', { rows: 1200 }, {
  userId: 'user_42',
  accountKey: 'acme-inc',
})

await holdy.flush() // ou holdy.shutdown() no teardown

Semântica

  • Batching opcional — eventos acumulam em fila e são enviados em batch para POST /api/v1/events/bulk. Chame flush() ao final de um job ou shutdown() no teardown do processo para não perder o que está na fila.
  • Retry seguro — mesmo comportamento do SDK web: 5xx e erro de rede re-enfileiram; o servidor deduplica; 4xx descarta.
  • Nunca lança — nenhum método público lança exceção.
  • Mesmo envelope, mesma porta — o SDK server usa o mesmo endpoint público da API REST. Não existe endpoint privado de SDK.