Versionamento

Semver do SDK, estabilidade do contrato e política de depreciação.

Semver do SDK

O @wabroker/sdk segue SemVer. Esta documentação reflete a série 0.31. Enquanto o SDK estiver em 0.x, mudanças incompatíveis podem ocorrer em incrementos de minor (0.31 → 0.32); correções e adições compatíveis chegam em patch. Fixe uma faixa que você controla:

bash

npm install @wabroker/sdk@~0.31

A partir de 1.0

Quando o SDK chegar a 1.0, quebras passam a ser exclusivas de major. Até lá, leia as notas de cada minor antes de atualizar.

SDK .NET (Wabroker.Sdk)

O Wabroker.Sdk, publicado no NuGet, segue a mesma disciplina de SemVer do @wabroker/sdk — está em 0.2.0, então mudanças incompatíveis também podem vir em incrementos de minor enquanto o pacote estiver em 0.x. Fixe uma faixa:

bash

dotnet add package Wabroker.Sdk --version 0.2.*

Em ambos os SDKs, o cliente compõe a versão da API no path da requisição — {baseUrl}/{apiVersion}{path}, com apiVersion opcional e v1 por default. Sobrescrever apiVersion (ex.: para testar um endpoint em outra versão) não muda nada além do path — o resto do cliente segue igual.

A cobertura de recursos é parcial nesta série. Os 9 recursos de /v1 abaixo já têm cliente tipado e verificação de webhook (WabrokerWebhooks.VerifyAndParse):

messages
channels
tags
pools
templates
deliveries
suppressions
members
warming

Os 7 recursos restantes ainda não têm cliente dedicado no Wabroker.Sdk — estão no roadmap; até lá, fale com eles direto pela API HTTP (/v1/*): billing, apiKeys, settings, webhooks-config, compliance, meta e me.

Escolhendo entre TS e .NET

Se seu backend já é Node/TypeScript, o @wabroker/sdk tem cobertura completa dos 16 recursos e é a opção mais madura hoje. O Wabroker.Sdk é a escolha natural para um backend .NET, com paridade crescente a cada minor.

Estabilidade do contrato

O SDK é o dono do contrato compartilhado com o broker: os tipos de evento, de conteúdo e os códigos de erro vivem no pacote, então cliente e servidor não podem divergir. Dois princípios sustentam a compatibilidade:

Uniões fechadas — EventType, OutboundContent por kind e BrokerErrorCode são fechados. Trate-os exaustivamente e um default defensivo cobre valores futuros.
Campos aditivos são opcionais — novos campos entram como opcionais (ex.: profileName, filename em mensagens recebidas, ou o channelNumber que os eventos ganharam para amarrar conversas). Um consumidor de uma versão anterior simplesmente os ignora, sem quebrar.

Escreva código tolerante

Não pressuponha a ausência de campos que você não usa, e trate o default de todo switch sobre um discriminante. É o que mantém sua integração funcionando quando o contrato ganha um valor novo.

Verificação assinada e o contrato de fio

O header de assinatura (X-WaBroker-Signature) e o algoritmo de HMAC moram no pacote compartilhado — quem assina (broker) e quem verifica (você, via verifyAndParse) usam exatamente o mesmo código. Uma correção de segurança vale para os dois lados sem chance de drift. Mantenha o SDK atualizado para receber essas correções.

Política de depreciação

Um método ou campo a ser removido é primeiro marcado como deprecado, mantendo o comportamento, com a alternativa indicada (ex.: channels.connection é o nome canônico; channels.connect segue por compatibilidade).
A remoção efetiva acontece só num incremento que a SemVer permite (minor em 0.x; major a partir de 1.0).
Prefira sempre o nome canônico documentado nestas páginas.

Atualizar com segurança

Fixe a faixa (~0.31) e atualize deliberadamente.
Rode seu typecheck após atualizar — o SDK é tipado, e uma quebra de contrato aparece em compilação.
Valide envio e recebimento de ponta a ponta num ambiente de teste antes de promover.