Instalar e configurar

Um pacote, duas variáveis de ambiente e nenhuma configuração obrigatória. Tudo o que está abaixo tem padrão, e o padrão é o que serve à maioria dos Apps.

Instalar

pnpm add @trivo/sdk

Um pacote só: o que o SDK precisa do núcleo do Trivo vem embutido nele, com uma entrada de exports — não há import interno que vire contrato por acidente, e não há um segundo pacote para manter em versão casada.

O SDK é ESM e roda em Node. Ele não tem dependência de runtime além do fetch da plataforma, e a opção fetch existe para quem precisa passar por um proxy próprio.

As duas variáveis de ambiente

export TRIVO_APP_TOKEN='trivo_app.SEU_APPLICATION_ID.o-segredo'
export TRIVO_BASE_URL='https://o-endereco-do-seu-trivo'

import { createApp } from "@trivo/sdk";

// Sem argumento nenhum: lê TRIVO_APP_TOKEN e TRIVO_BASE_URL do ambiente.
const app = createApp();

// Se o seu cofre entrega o segredo em memória, passe SÓ o que ele entrega: o
// que você não passa continua vindo do ambiente.
const outro = createApp({ token: await cofre.ler("trivo") });

O caminho preguiçoso é também o certo, e isso é de propósito. O SDK não lê arquivo, não procura .env e não aceita token em URL: as três seriam formas de o segredo acabar num lugar de que ninguém lembra. O Application ID sai do próprio token, então não há um id para configurar duas vezes — nem como configurar um id que não é o seu.

Faltando qualquer uma das duas, createApp lança na hora, com o nome da variável na mensagem. Token com forma errada também: a recusa acontece antes da primeira chamada, e não como um 401 no meio da noite.

As opções de createApp

Opção	Padrão	O que ela muda
`intents`	omitida	As famílias de evento que você quer. Omitir entrega o conjunto padrão; declarar uma lista vazia é recusa, com `EMPTY_INTENTS` — o SDK repassa a decisão em vez de escondê-la. Ver Intents.
`maxAttempts`	3	Quantas tentativas no total (a primeira inclusive) uma chamada REST faz.
`maxRetryDelayMs`	30 000	O teto da espera que o SDK cumpre sozinho. Acima disso ele devolve o erro com `retryAfterSeconds` e sai da frente: dormir dez minutos dentro de uma chamada que quem escreveu acha rápida é pior do que a recusa.
`gatewaySilenceMs`	60 000	Quanto silêncio no gateway conta como conexão morta. O servidor bate a cada 25 s, e o padrão são dois batimentos perdidos mais folga.
`transport`	`"auto"`	`"stream"` é o fluxo; `"mailbox"` é o recuo em JSON; `"auto"` começa no fluxo e recua sozinho depois de duas aberturas mudas. O caso é concreto: um proxy que segura a resposta inteira faz o `GET` responder 200 sem nenhum byte atravessar.
`mailboxPollMs`	1 000	De quanto em quanto perguntar à caixa. O balde do servidor é de 90 leituras por minuto, e o padrão cabe nele com folga.
`handlerConcurrency`	256	Quantos handlers seus podem estar em voo. `0` desliga o teto. Ele existe para o pico patológico — uma rajada de mil eventos virando mil handlers vivos —, e não para regular o uso normal.
`eventQueueLimit`	1 000	A partir de quantos eventos pendentes o SDK para de ler o gateway. É contrapressão de verdade: parar de ler fecha a janela TCP e o Trivo segura o resto. O número é do processo, e não de um canal.
`eventOrdering`	`"none"`	`"channel"` serializa por canal e mantém canais, servidores e pessoas diferentes em paralelo. Não existe modo "tudo em ordem": uma fila só para o App inteiro faria trinta servidores esperarem por um handler lento em um deles.
`maxConcurrentRequests`	32	Chamadas REST em voo. O excedente espera na fila em vez de abrir socket: cem handlers chamando a API juntos abriam cem conexões e colhiam cem `429` ao mesmo tempo.
`fetch`	o da plataforma	Existe para os ensaios e para quem tem proxy próprio.

const app = createApp({
  intents: ["messages", "interactions"],
  handlerConcurrency: 256,     // handlers em voo
  eventQueueLimit: 1000,       // passado isso, o SDK PARA DE LER o gateway
  maxConcurrentRequests: 32,   // chamadas REST em voo
  eventOrdering: "channel",    // serializa por canal; o padrão é "none"
});
app.pendingEvents; // enfileirados + em voo, para a sua métrica

Os tetos aceitam Infinity

Infinity é "sem teto" dito por extenso, e vira o 0 que já significa isso. Fração é engano de digitação e volta ao padrão — sem essa régua, 0.5 truncaria para 0, e o número mais restritivo que alguém tentou escrever produziria o comportamento mais permissivo possível.

O que o SDK já resolve, e você não escreve

Queda de rede. Reconexão com espera crescente e ruído, e retomada por Last-Event-ID — você recebe o intervalo perdido.
Silêncio. O vigia do batimento derruba a conexão morta que o sistema operacional ainda acha viva, e o recuo para a caixa JSON acontece sozinho.
Parar quando mandam parar. Fechamento com reconnect: false não vira laço: o SDK desiste e avisa por onStatus.
O 429. O Retry-After é obedecido, com ruído para cima e teto de sanidade. Os números estão em Limites e ritmo.
A versão da API. O cabeçalho viaja sozinho, nos dois canais.
A assinatura das entregas. O InteractionVerifier é a implementação auditada disso, e é o caminho suportado.