# Biblioteca TypeScript

URL: https://wa.genuka.com/es/docs/library
Language: Spanish

> @genuka/whatsapp — constructores tipados, validación y normalización de eventos.

`@genuka/whatsapp` no es un cliente HTTP más. Es la capa que evita los 400 evitables, hace que el
manejo de webhooks sea exhaustivo en tiempo de compilación y convierte los \~200 códigos de error de
Meta en siete decisiones accionables.

> [!NOTE]
> La biblioteca funciona de forma independiente contra la Cloud API de Meta, sin cuenta de Genuka.
> Se distribuye bajo licencia MIT.

## Instalación

```bash
npm install @genuka/whatsapp
```

## Construir un mensaje

Las longitudes, las cardinalidades y el formato del número de teléfono se verifican **antes** de la
llamada de red.

```ts
import { messages } from "@genuka/whatsapp";

const choice = messages.buttons("+237 6 99 00 11 22", {
  body: "How can we help?",
  buttons: [
    { id: "order", title: "My order" },
    { id: "support", title: "A problem" },
  ],
});
```

Un error de construcción se lanza de inmediato, con la ruta del campo problemático:

```txt
ValidationError: interactive.buttons: must contain at most 3 items (got 4)
```

## La ventana de 24 horas

```ts
import { sendStrategy } from "@genuka/whatsapp";

sendStrategy(contact.lastInboundAt); // "free_form" | "template"
```

Una llamada a función, en lugar de un `131047` descubierto cuando el intento ya fue facturado.

## Manejar un webhook

Meta anida todo en `entry[].changes[].value`, donde el verdadero discriminante no es un campo sino
la *presencia* de `messages` o de `statuses`. La biblioteca lo aplana de una vez por todas.

```ts
import { parseWebhook, eventKey } from "@genuka/whatsapp/webhooks";

for (const event of parseWebhook(await request.json())) {
  if (await alreadyProcessed(eventKey(event))) continue;

  switch (event.kind) {
    case "message":         // entrante
    case "status":          // sent / delivered / read / failed / deleted
    case "template":        // aprobación, calidad, recategorización
    case "account":         // calidad del número, límites, suspensión
    case "user_preference": // baja de marketing (opt-out)
    case "coexistence":     // historial, ecos, contactos
    case "unknown":         // nunca se pierde, siempre se reenvía
  }
}
```

El parser **nunca lanza excepciones**: un payload mal formado produce una lista vacía. Una excepción
aquí se convertiría en un 500, y Meta reenviaría todo el lote.

## Decidir qué hacer con un error

`errorClass` lleva la decisión, no el código numérico.

```ts
import { WhatsAppError } from "@genuka/whatsapp";

try {
  await send(payload);
} catch (error) {
  if (!(error instanceof WhatsAppError)) throw error;

  switch (error.errorClass) {
    case "needs_template":      return resendAsTemplate();      // 131047
    case "recipient_permanent": return markUnreachable();       // 131026, 131050
    case "recipient_throttled": return requeueLater();          // 131049
    case "media":               return reuploadAndRetryOnce();  // 131052
    case "retryable":           return backoff();               // 4, 130429, 5xx
    case "config":              return alertOperator();         // 190, 133010
    case "template":            return surfaceToCustomer();     // 132xxx
    case "validation":
    case "unknown":             throw error;
  }
}
```

## Dos transportes, un mismo núcleo

El mismo payload construido puede viajar por dos rutas, con los mismos constructores, la misma
validación y la misma taxonomía de errores:

```ts
// Con una clave de Genuka WA: sin ningún token de Meta de por medio
import { GenukaTransport } from "@genuka/whatsapp";
const transport = new GenukaTransport({ apiKey: process.env.GENUKA_WA_API_KEY! });

// Directo a Meta, si tienes tus propias credenciales
import { MetaTransport } from "@genuka/whatsapp";
const transport = new MetaTransport({ accessToken: process.env.META_TOKEN! });
```

## Referencia completa

Cada módulo tiene su propia guía, extraída del propio paquete: viven junto al código que describen,
así que no se desfasan:

* [Enviar mensajes](https://wa.genuka.com/sdk/messages)
* [Plantillas](https://wa.genuka.com/sdk/templates)
* [Multimedia](https://wa.genuka.com/sdk/media)
* [Webhooks](https://wa.genuka.com/sdk/webhooks)
* [Flows](https://wa.genuka.com/sdk/flows)
* [Gestión](https://wa.genuka.com/sdk/management)
* [Coexistencia](https://wa.genuka.com/sdk/coexistence)
* [Llamadas](https://wa.genuka.com/sdk/calling)

## Versión de la Graph API

La biblioteca fija explícitamente una versión de la Graph API en lugar de seguir "latest". Un cambio
de versión silencioso es la mejor manera de descubrir un cambio incompatible en producción: modificar
`DEFAULT_GRAPH_VERSION` es una versión publicada a propósito.
