Estado da conta

Evento é fluxo: o que aconteceu. Estado é estoque: quanto existe agora. Adoção e profundidade são perguntas de estoque, e estoque não se deriva de evento — se você instrumentou ontem e a conta existe há dois anos, nenhum evento sabe que ela tem 47 automações.

O pacote @holdyapp/server é o canal do estado. Ele não substitui o SDK de eventos: complementa. E a Holdy nunca lê o seu banco — sem credencial, sem conhecer o seu schema. Você empurra o que quer que ela saiba.

Setup

npm install @holdyapp/server

import Holdy from '@holdyapp/server'

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

Use uma chave secreta. A chave public_write vive exposta no bundle do browser e não é aceita aqui.

sync — estado da conta

Chame periodicamente (um cron diário costuma bastar) ou quando o estado mudar. É imediato, não bufferiza: estado precisa estar fresco.

await holdy.sync({
  companyId: 'acme-inc',
  subscription: { plan: 'growth', mrr: 1490, contractEnd: '2027-03-01' },
  usersActive: 12,
  usage: {
    automations: { current: 47, limit: 50, unit: 'automations' },
    ai_tokens:   { current: 812000, limit: 1000000, unit: 'tokens' },
  },
})

Por que o limit importa

O current sozinho diz quanto a conta usa. Com o limit, a Holdy sabe quão perto do teto ela está — e isso vira sinal sozinho: quando três ou mais contas passam de 85% da cota de uma mesma métrica, nasce uma oportunidade com as contas nomeadas, o plano escrito e a releitura marcada.

Nenhuma ferramenta de analytics consegue essa afirmação: o limite mora no seu sistema de cobrança e nunca no log de eventos.

Semântica

• UPSERT por métrica — cada metric_key guarda o valor atual; reenviar sobrescreve. É estado, não histórico.
• Não sobrescreve o que é seu — campos preenchidos à mão no app da Holdy nunca são apagados por um sync.
• Por usuário, se quiser — um gauge aceita userExternalId para medir assento a assento.
• Nunca lança — como o resto dos SDKs, telemetria não derruba o seu processo.

Ler de volta

O mesmo pacote lê o que a Holdy concluiu, para você mostrar dentro do seu produto ou usar em automações suas:

const consumo = await holdy.getConsumption({ companyId: 'acme-inc' })

A leitura é server-to-server, sempre. O SDK de browser não tem métodos de leitura por decisão: a chave dele é pública, e leitura ali exporia dados de todos os seus clientes a quem abrisse o DevTools.