# SDK de TypeScript

> @messajo/sdk: instalar, primera llamada, paginación, errores, reintentos seguros, webhooks y eventos por WebSocket.

`@messajo/sdk` es el SDK oficial de la API `/v1`. Los tipos se generan del mismo OpenAPI de la [referencia](/es/reference), así que cada campo y cada código de error aparecen en el autocompletado.

- Cero dependencias, ESM. Funciona en Node 20+, Bun, Deno, Workers y el navegador.
- Licencia **MIT**: puedes incluirlo en tu código cerrado.

## Instalar

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

## Primera llamada

```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: "¡Hola! Mensaje enviado con el SDK." },
});
console.log(sent.id, sent.status);
```

| Opción | Por defecto | Qué es |
|---|---|---|
| `apiKey` | — | la clave `mj_…` (organización) o `mjc_…` (conexión) |
| `baseUrl` | `https://api.messajo.com/v1` | la URL base de la API|
| `maxRetries` | `2` | reintentos automáticos (consulta abajo) |
| `timeoutMs` | `30000` | límite de cada intento |
| `fetch` | el global | para inyectar otro `fetch` (proxy, pruebas) |

Recursos: `me`, `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `connections`, `destinations`, `deliveries`, `events`, `connectionLinks`, `publications` y `apiKeys`. La capa espejo de Meta sale cruda en `messajo.mirror("whatsapp", connectionId, "message_templates")`.

## Clave de conexión

Una clave `mjc_…` (creada en la conexión) ve solo esa conexión: la `/v1` resuelve el `connection_id` por la clave y se puede omitir. Las claves de la organización (`mj_…`) ven todas las conexiones y son las únicas que gestionan claves; la `mjc_` recibe `403 organization_key_required` ahí. Consulta [Autenticación](/es/api/authentication/). `messajo.connection(id?)` devuelve un cliente que inyecta el `connection_id`:

```ts
// Clave de conexión: sin connection_id.
const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection();
await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "¡Hola!" } });

// Clave de la organización: fija la conexión una vez.
const sales = messajo.connection("conn_...");
await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "¡Hola!" } });

// Gestionar las claves de la conexión (solo clave de la organización).
const key = await sales.apiKeys.create({ name: "Integración CRM", permissions: ["send", "read"] });
```

Fijan el `connection_id`: `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `publications`, `events`, `destinations.create` y `apiKeys`; `apiKeys.list`/`create` exigen `connection(id)`.

## Paginación

`paginate` recorre cualquier lista `{ data, next_cursor }` siguiendo el cursor:

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

Para una sola página, llama a la lista directamente: `await messajo.messages.list({ limit: 50 })`. Consulta [Historial](/es/api/history/).

## Errores

Toda respuesta de error se convierte en un `MessajoError` con los campos del [cuerpo de error](/es/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") {
      // fuera de la ventana de 24 h: manda una plantilla
    }
  }
}
```

`retryable`, `retryAfterMs` y `details` también están en el error.

## Reintentos seguros

- El SDK genera un `Idempotency-Key` en toda escritura (`POST`). Para controlar la clave, pasa `{ idempotencyKey }` como último argumento, por ejemplo `messajo.messages.send(body, { idempotencyKey: pedido.id })`.
- `GET` y las escrituras con `Idempotency-Key` se repiten solos ante `429`, `503` y fallos de red, respetando `retry_after_ms` y `Retry-After`, hasta `maxRetries`.
- `502` [`meta_unknown_outcome`](/es/errors#meta_unknown_outcome) **nunca** se repite: el mensaje puede haber salido. Revisa `message.status` antes de reenviar.

## Webhooks

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

const body = await request.text(); // cuerpo crudo, antes del 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` es `missing`, `malformed`, `outside_tolerance` (más de 5 minutos) o `mismatch`. Usa WebCrypto, así que funciona igual en Node, Bun, Deno y Workers. Detalles en [Verificar la firma](/es/webhooks/verify-signature/).

## Eventos por WebSocket

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

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

const socket = connectEvents({
  client: messajo,
  destinationId: "dst_...",
  onEvent: async (event) => {
    // el ack sale cuando esto se resuelve; si lanza, Messajo entrega de nuevo
  },
  onError: (error) => console.error(error),
});
await socket.ready; // id de la sesión
// socket.close() para terminar
```

El orden no está garantizado y el mismo evento puede llegar más de una vez: deduplica por `event.id`. En Node 20, que no tiene `WebSocket` global, pasa la opción `WebSocket` (del paquete `ws`).

## Versiones

La versión del SDK acompaña a la del servidor (`0.3.0-beta.1` en la beta). Las versiones preliminares salen con la etiqueta `beta` de npm: `npm install @messajo/sdk@beta`.
