SDKs

Um cliente tipado, gerado do contrato oficial 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 — é uma decisão de arquitetura. O que se distribui é o modelo real de consumo: o pacote npm empacotado, exatamente como a CLI e o servidor MCP consomem o SDK.

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() });

O que ele garante

• 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, 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. O compilador passa a exigir o tratamento do nulo — estreite o tipo antes de usar o valor.

Rede entre projetos

O SDK tem 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);
}

A rede de um ambiente fora de qualquer rede vem nula: network é null.

Dentro da aplicação: quem entrou

O runtime da aplicação publicada com o login da organização existe só no SDK de TypeScript: @nnumbers/zero/app no servidor (NNumbers.init(), nn.auth.user(req) e, com a capacidade ligada, nn.querymesh.query(req, sql)) e @nnumbers/zero/react na interface. Ele confere a identidade que a plataforma entrega a cada requisição e devolve a pessoa — ou null. O SDK publicado de Go é o cliente da API de gerenciamento, não o runtime; em outra linguagem, siga o protocolo de runtime. Ver Quem entrou, no código e Consultar o QueryMesh em nome de quem entrou.

Trocar o endereço

setCanonicalDomain troca 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.