SDK Server

Envie do backend os eventos que não acontecem no browser com @holdyapp/sdk/server — stateless por chamada, com batching opcional e flush explícito.

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

Setup

import { Holdy } from '@holdyapp/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

Execuções de agente

Em produto com agente de IA, o trabalho roda no servidor, muitas vezes em background, e não existe sessão de browser. O run() trata cada tarefa do agente como uma execução: todos os eventos lá dentro carregam a mesma ai_run_id, e o início e o fim saem sozinhos com o nome que você deu.

const resposta = await holdy.run({ name: 'support_agent', accountKey: 'acme-inc' }, async (run) => {
  run.track('ticket_drafted', { ai_tokens: 1200, ai_cost_usd: 0.02 })
  return resolverTicket(ticket)
})

Eventos que saem — support_agent.started, cada run.track do meio e, no fim, support_agent.completed com duration_ms. Se a função lançar, sai support_agent.failed com o nome do erro (nunca a mensagem) e o erro continua propagando.
O retorno passa direto — o run() devolve o que a sua função devolve.
Chave própria — se o agente já tem um trace id, passe runId e ele vira a ai_run_id.
Custo — mande ai_tokens e ai_cost_usd nos passos. A Holdy soma por execução e divide pelo que concluiu, não pelo que rodou.

Com os eventos chegando, peça no Explorar um comportamento "na mesma execução" (por exemplo, "rascunhou e concluiu na mesma execução do support_agent") e a Holdy compõe no grão de execução. O custo por resultado aparece em Explorar › Consumo.

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 esperam com backoff, 429 respeita o Retry-After, e cada evento tem id próprio, então reenvio nunca duplica.
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.