# SDK TypeScript

> @messajo/sdk: instalar, primeira chamada, paginação, erros, repetição segura, webhooks e eventos por WebSocket.

`@messajo/sdk` é o SDK oficial da API `/v1`. Os tipos são gerados do mesmo OpenAPI da [referência](/reference), então todo campo e todo código de erro aparecem no autocompletar.

- Zero dependências, ESM. Roda no Node 20+, Bun, Deno, Workers e navegador.
- Licença **MIT**: pode embutir no seu código fechado.

## Instalar

```bash
npm install @messajo/sdk
```

## Primeira chamada

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({
  apiKey: process.env.MESSAJO_API_KEY!,
});

const me = await messajo.me.get();
console.log(me.organization.name, me.api_key.permissions);

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Olá! Mensagem enviada pelo SDK." },
});
console.log(sent.id, sent.status);
```

| Opção | Padrão | O que é |
|---|---|---|
| `apiKey` | — | a chave `mj_…` (organização) ou `mjc_…` (conexão) |
| `baseUrl` | `https://api.messajo.com/v1` | a URL base da API|
| `maxRetries` | `2` | repetições automáticas (veja abaixo) |
| `timeoutMs` | `30000` | limite de cada tentativa |
| `fetch` | o global | para injetar outro `fetch` (proxy, testes) |

Recursos: `me`, `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `connections`, `destinations`, `deliveries`, `events`, `connectionLinks`, `publications` e `apiKeys`. A camada espelho da Meta sai crua em `messajo.mirror("whatsapp", connectionId, "message_templates")`.

## Chave de conexão

Uma chave `mjc_…` (criada na conexão) enxerga só aquela conexão: a `/v1` resolve o `connection_id` pela chave e ele pode ser omitido. Chaves da organização (`mj_…`) enxergam todas as conexões e são as únicas que gerenciam chaves; a `mjc_` recebe `403 organization_key_required` ali. Veja [Autenticação](/api/authentication/). `messajo.connection(id?)` devolve um cliente que injeta o `connection_id`:

```ts
// Chave de conexão: sem connection_id.
const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection();
await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } });

// Chave da organização: fixa a conexão uma vez.
const sales = messajo.connection("conn_...");
await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } });

// Gerenciar chaves da conexão (só chave da organização).
const key = await sales.apiKeys.create({ name: "Integração CRM", permissions: ["send", "read"] });
```

Ficam com o `connection_id` fixado: `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `publications`, `events`, `destinations.create` e `apiKeys`; `apiKeys.list`/`create` exigem `connection(id)`.

## Paginação

`paginate` percorre qualquer lista `{ data, next_cursor }` seguindo o cursor:

```ts
for await (const conversation of messajo.paginate(messajo.conversations.list, {
  window: "open",
})) {
  console.log(conversation.id, conversation.contact.display_name);
}
```

Para uma página só, chame a lista direto: `await messajo.messages.list({ limit: 50 })`. Veja [Histórico](/api/history/).

## Erros

Toda resposta de erro vira um `MessajoError` com os campos do [corpo de erro](/errors/):

```ts
import { MessajoError } from "@messajo/sdk";

try {
  await messajo.messages.send({ /* ... */ });
} catch (error) {
  if (error instanceof MessajoError) {
    console.error(error.status, error.code, error.metaCode, error.requestId, error.docsUrl);
    if (error.code === "outside_service_window") {
      // fora da janela de 24 h: mande um template
    }
  }
}
```

`retryable`, `retryAfterMs` e `details` também estão no erro.

## Repetição segura

- O SDK gera um `Idempotency-Key` em toda escrita (`POST`). Para controlar a chave, passe `{ idempotencyKey }` como último argumento, por exemplo `messajo.messages.send(body, { idempotencyKey: pedido.id })`.
- `GET` e escritas com `Idempotency-Key` repetem sozinhos em `429`, `503` e falha de rede, respeitando `retry_after_ms` e `Retry-After`, até `maxRetries`.
- `502` [`meta_unknown_outcome`](/errors#meta_unknown_outcome) **nunca** é repetido: a mensagem pode ter saído. Confira pelo `message.status` antes de reenviar.

## Webhooks

```ts
import { verifyWebhookSignature } from "@messajo/sdk";

const body = await request.text(); // corpo cru, antes do JSON.parse
const result = await verifyWebhookSignature({
  header: request.headers.get("Messajo-Signature"),
  body,
  secret: process.env.MESSAJO_WEBHOOK_SECRET!,
});
if (!result.ok) {
  return new Response(result.reason, { status: 400 });
}
const event = JSON.parse(body);
```

`reason` é `missing`, `malformed`, `outside_tolerance` (mais de 5 minutos) ou `mismatch`. Usa WebCrypto, então funciona igual no Node, no Bun, no Deno e em Workers. Detalhes em [Verificar a assinatura](/webhooks/verify-signature/).

## Eventos por WebSocket

Para um destino do tipo `websocket` ([Tipos de destino](/webhooks/destinations/#websocket)):

```ts
import { connectEvents } from "@messajo/sdk";

const socket = connectEvents({
  client: messajo,
  destinationId: "dst_...",
  onEvent: async (event) => {
    // o ack sai quando isto resolve; se lançar, o Messajo entrega de novo
  },
  onError: (error) => console.error(error),
});
await socket.ready; // id da sessão
// socket.close() para encerrar
```

A ordem não é garantida e o mesmo evento pode chegar mais de uma vez: desduplique por `event.id`. No Node 20, que não tem `WebSocket` global, passe a opção `WebSocket` (do pacote `ws`).

## Versões

A versão do SDK acompanha a do servidor (`0.3.0-beta.1` com o beta). Versões de pré-lançamento saem na tag `beta` do npm: `npm install @messajo/sdk@beta`.
