# SDKs e CLI

Os SDKs oficiais são gerados do mesmo contrato desta referência e provados contra a mesma conformidade. A CLI `kernos` vem com o pacote Node.

> **Nesta fase de testes** Os pacotes ainda não estão nos registros públicos: a Kernos entrega o repositório dos SDKs junto com o convite. Os comandos de instalar de cada registro passam a valer quando os pacotes forem publicados.

| Linguagem | Começar |
| --- | --- |
| Node.js / TypeScript | `new Kernos(process.env.KERNOS_API_KEY)` |
| Python | `Kernos(os.environ["KERNOS_API_KEY"])` |
| PHP | `new Kernos\Kernos(getenv('KERNOS_API_KEY'))` |
| Java e Kotlin | `new Kernos(System.getenv("KERNOS_API_KEY"))` |
| C# / .NET | `new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"))` |
| Go | `kernos.New(os.Getenv("KERNOS_API_KEY"))` |
| Rust | `Kernos::new(&std::env::var("KERNOS_API_KEY")?)` |
| Qualquer outra (Delphi, ADVPL, low-code) | `curl` e a coleção do Postman: a API é REST. |

## O que todo SDK faz igual

- **A chave escolhe o ambiente:** `ksk_test_` fala com o piloto, `ksk_live_` com a produção.
- **`Kernos-Version`** fixa na versão do contrato com que o SDK foi gerado.
- **Idempotência:** toda escrita leva `Idempotency-Key`, e as novas tentativas repetem a mesma. Um pedido nunca entra duas vezes.
- **Novas tentativas** no 429 (respeitando `Retry-After`), no 5xx e na falha de rede, até 2 vezes. Nunca num 4xx.
- **Erro tipado** com `status`, `code` (o `error_code` estável), `message`, `field` e `trace_id`.
- **Webhook:** `sign` e `construct_event`, que confere a `Kernos-Signature` sobre o corpo cru e recusa corpo mexido, segredo errado e aviso velho. Aceita os dois `v1` da troca de segredo.

## A CLI kernos

**terminal**

```sh
kernos login --key ksk_test_…                      # guarda a chave em ~/.config/kernos (só você lê)
kernos events --type shipment.dispatch             # os eventos das últimas 24 h, ou depois de --after
kernos listen --forward-to http://localhost:3000/webhook   # entrega cada evento no seu receptor local, assinado
kernos trigger ping                                # manda um ping ao webhook cadastrado
kernos trigger shipment.dispatch                   # manda um evento de teste com data de exemplo
kernos trigger shipment.dispatch --forward-to http://localhost:3000/webhook   # o mesmo, direto no seu receptor local, sem webhook cadastrado
kernos events resend <entrega>                     # põe uma entrega que falhou de volta na fila
kernos logs tail --follow                          # o registro de pedidos da sua chave
kernos logs get <request_id>                       # o pedido e, na chave de teste, o corpo da resposta
kernos docs guias/receber-eventos                  # lê a página da documentação, em Markdown, no terminal
kernos agent setup --for claude                    # escreve no projeto as regras para o seu agente de código (agents, claude ou cursor)
kernos secret roll --grace 24                      # troca o whsec_; o antigo vale por mais 24 h
```

O `listen` não precisa de endereço público: ele pergunta à `GET /v1/events` e assina cada entrega com um segredo local, que imprime ao começar.