SDKs

Dois clientes tipados, gerados do mesmo contrato da API. Baixe em zero.nnumbers.com.br/downloads.

Por que arquivo, e não registro público

O namespace da plataforma não resolve por npm install nem por go get — é uma decisão de arquitetura. O que se distribui é o modelo real de consumo: o pacote npm empacotado e o pacote Go para vendorizar por cópia, exatamente como a CLI e o servidor MCP consomem o SDK Go.

TypeScript

npm install ./zero-sdk-typescript.tgz

import { ZeroClient } from '@nnumbers/zero';

const zero = new ZeroClient({
  baseUrl: 'https://api.zero.nnumbers.com.br',
  token: process.env.ZERO_TOKEN,
});

// publicar, com chave de idempotência — repetir nunca duplica
const publicacao = await zero.createDeployment(servico, {},
  { idempotencyKey: crypto.randomUUID() });

Go

tar -xzf zero-sdk-go.tar.gz -C internal/

import "suaempresa.com/app/internal/zero"

cliente, err := zero.New(zero.Config{
    BaseURL: "https://api.zero.nnumbers.com.br",
    Token:   zero.StaticToken(os.Getenv("ZERO_TOKEN")),
})

O que os dois garantem

• Idempotência — toda mutação aceita uma chave; repetir a chamada nunca cria dois recursos.
• Erros tipados — o catálogo de erros da plataforma vira tipo, com o código e a ação sugerida.
• Acompanhamento ao vivo — o fluxo de uma operação chega como iterável (TypeScript) ou canal (Go), sem você montar SSE à mão.

Campos que podem vir nulos

Campo que a API pode devolver como nulo é tipado como anulável: T | null em TypeScript, ponteiro em Go. O compilador passa a exigir o tratamento do nulo — em Go, confira nil antes de desreferenciar; em TypeScript, estreite o tipo antes de usar o valor.

Rede entre projetos

Os dois SDKs têm as operações da rede entre projetos: redes, o ambiente na rede, permissões, exposição do projeto, nome interno e entradas internas do Gateway.

const rede = await zero.createNetwork(organizacao, { name: 'pagamentos' },
  { idempotencyKey: crypto.randomUUID() });
await zero.attachEnvironmentNetwork(ambiente, { network_id: rede.id });
await zero.setServiceInternalName(servico, { name: 'api' });   // api.zero.internal

Duas listas misturam formas, e o campo kind diz qual é cada item: as permissões de uma rede (service_grant ou gateway_entry_grant) e quem chega a um projeto (service_grant ou private_route). Em TypeScript, a união estreita pelo kind, sem conversão:

for (const item of (await zero.listNetworkAccessGrants(rede.id)).items) {
  if (item.kind === 'service_grant') console.log(item.target_service_name, item.port);
  else console.log(item.entry_address);
}

Em Go, os itens chegam como json.RawMessage, e zero.DecodificarPermissaoDaRede e zero.DecodificarChegadaAoProjeto os separam pelo kind. Um kind que a sua versão do SDK não conhece volta sem forma e sem erro, com o JSON em Bruto — a listagem não quebra por causa de um tipo novo.

A rede de um ambiente fora de qualquer rede vem nula: network é null em TypeScript e nil em Go.

Trocar o endereço

setCanonicalDomain (TypeScript) e SetCanonicalDomain (Go) trocam o endereço público do projeto. A resposta traz, além do endereço novo:

Campo	O que é
operation_id	A publicação que põe o endereço novo no ar — acompanhe-a até o fim. Nulo quando o projeto nunca publicou: o anterior é liberado na hora e não há o que acompanhar
previous	O endereço anterior. Pode ser nulo

Enquanto a publicação corre, o endereço anterior aparece entre os domínios do projeto com o estado releasing: ele responde até a publicação com o endereço novo ficar pronta, e então é liberado.