@mafesoftware/kapso-wa 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 6ad0993: Webhooks, media, plantillas y reconexión: lo que consult360 y ediflow escribían a mano contra Kapso.
+  
+  - `verificarFirmaWebhook(cuerpoCrudo, firmaHex, secreto)`: HMAC-SHA256 en hex sobre el cuerpo crudo contra `X-Webhook-Signature`, en tiempo constante (`node:crypto`, como `mercadopago-ar`). Sin secreto o sin firma da `false`.
+  - `leerEventoWebhook(crudo, nombreEvento?)`: el segundo argumento es la cabecera `X-Webhook-Event` y manda sobre `cuerpo.event`/`cuerpo.type`. **Kapso no pone el nombre del evento en el cuerpo v2**: sin la cabecera, un mensaje real sale `"ignorado"`. Llamarla sin el segundo argumento sigue funcionando igual que antes.
+  - `leerEventosWebhook(crudo, nombreEvento?)`: desarma el sobre de lote (`batch: true, data: [...]`) que manda Kapso con buffering. `leerEventoWebhook` con un lote ahora devuelve `"ignorado"` diciendo que se use ésta, en vez de leerlo mal.
+  - Mensajes entrantes: `tipo` suma `"imagen" | "video" | "documento" | "audio" | "ubicacion"`, con `media?: { id, mimeType?, nombreArchivo?, url? }` (`url` = `message.kapso.media_url`), el epígrafe en `texto` y la ubicación como `"lat,lng"`. Se agrega `nombreContacto?` (`conversation.contact_name`). El botón de respuesta rápida de una plantilla (`type: "button"`) sale como `"boton"` con su payload. Si falta `from`, el remitente sale de `conversation.phone_number`.
+  - Estados: `failed` trae `error?: { codigo?, titulo?, mensaje? }` del último elemento de `message.kapso.statuses`. La `fechaHora` de un estado v2 ahora sale del historial o de `message.timestamp` (antes, con el payload v2, quedaba en "ahora").
+  - Conexión de número: lee `customer.id` del payload v2 (`{ phone_number_id, customer: { id, external_id } }`); antes solo miraba `customer_id` suelto y el evento real salía `"ignorado"`. Suma `idExterno?` (`customer.external_id`).
+  - `bajarMedia(cred, mediaId)`: `GET /{media_id}?phone_number_id=…` → `download_url` (4 minutos, auth incluida) → bytes, sin mandar la clave al segundo paso.
+  - `registrarWebhookNumero(cred, phoneNumberId, { url, secreto, eventos? })` (kind `kapso`, por defecto `EVENTOS_WEBHOOK_NUMERO`: received/delivered/read/failed) y `listarWebhooksNumero(cred, phoneNumberId)`.
+  - `crearPlantilla(cred, wabaId, definicion)` y `listarPlantillas(cred, wabaId, opciones?)` por el proxy de Meta (`/{waba_id}/message_templates`), con nombre y estado.
+  - `crearSetupLink` suma `reconectarTelefono` (`reconnect_phone_number`); en ese caso no manda `allowed_connection_types` (Kapso lo fija al de la conexión existente y da 422 si no coincide) ni `meta_billing_mode` salvo que se pase.
+  - `crearCliente`: se documenta que cada app tiene que pasar su prefijo; el default `"gestionflow"` queda solo por compatibilidad.
+  - Nuevo tipo exportado `CredencialesPlataforma` (`{ apiKey, fetch?, timeoutMs? }`).
+  
+  **Cambio de comportamiento a revisar al actualizar**: un audio, una imagen, un video o un documento entrante antes salía `tipo: "otro"` y ahora sale con su propio tipo. Una app que filtraba media con `m.tipo === "otro"` (GestionFlow lo hace para no contestarle a una nota de voz) tiene que pasar a filtrar por `m.tipo !== "texto"` o similar.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -65,26 +65,94 @@ dentroDeVentana24h(ultimaVezQueEscribio); // true | false
 import { crearCliente, crearSetupLink } from "@mafesoftware/kapso-wa";
 
 const cred = { apiKey: "kapso_..." };
-const r = await crearCliente(cred, "Club Náutico", clubId);
+// Cada app pasa SU prefijo: el proyecto de Kapso es uno solo para todo MAFE
+// Software, y el default "gestionflow" queda solo por compatibilidad.
+const r = await crearCliente(cred, "Club Náutico", clubId, "padel360");
 if (r.ok) {
   const link = await crearSetupLink(cred, r.cliente.id, { volverBienA: "https://app/ok" });
   if (link.ok) redirigirA(link.url); // el club conecta su WhatsApp ahí
 }
+
+// Si la credencial de un número ya conectado se rompió, un link atado a ESE número:
+await crearSetupLink(cred, clienteId, { reconectarTelefono: "+5491145678901" });
+```
+
+### Webhook del número
+
+Los mensajes llegan por un webhook **de cada número** (el de proyecto solo trae
+conexiones). Se registra una vez, al conectarse el número; el secreto lo elige
+la app.
+
+```ts
+import { registrarWebhookNumero, listarWebhooksNumero, EVENTOS_WEBHOOK_NUMERO } from "@mafesoftware/kapso-wa";
+
+const cred = { apiKey: "kapso_..." };
+const ya = await listarWebhooksNumero(cred, phoneNumberId);
+if (ya.ok && !ya.webhooks.some((w) => w.url === urlWebhook)) {
+  await registrarWebhookNumero(cred, phoneNumberId, { url: urlWebhook, secreto: secretoWebhook });
+  // eventos por defecto: EVENTOS_WEBHOOK_NUMERO (received, delivered, read, failed)
+}
 ```
 
 ### Webhook entrante
 
 ```ts
-import { leerEventoWebhook } from "@mafesoftware/kapso-wa";
+import { verificarFirmaWebhook, leerEventosWebhook, leerEventoWebhook } from "@mafesoftware/kapso-wa";
+
+export async function POST(request: Request) {
+  const crudo = await request.text(); // el cuerpo CRUDO: re-serializarlo rompe la firma
+  if (!verificarFirmaWebhook(crudo, request.headers.get("x-webhook-signature"), secretoWebhook)) {
+    return new Response("firma inválida", { status: 401 });
+  }
+  // El nombre del evento viene en la CABECERA, no en el cuerpo.
+  const nombre = request.headers.get("x-webhook-event");
+  // Con buffering, Kapso manda un lote ({ batch: true, data: [...] }): leerEventosWebhook lo desarma.
+  for (const evento of leerEventosWebhook(JSON.parse(crudo), nombre)) {
+    if (evento.tipo === "mensaje") {
+      // evento.mensaje: { tipo, de, phoneNumberId, texto, payload?, media?, nombreContacto?, mensajeId, fechaHora }
+    } else if (evento.tipo === "estado" && evento.estado === "failed") {
+      // evento.error?: { codigo: 131047, titulo, mensaje }
+    } else if (evento.tipo === "numero_conectado") {
+      // evento.clienteId (Kapso), evento.idExterno ("<prefijo>:<id>")
+    }
+    // "ignorado": de otra app o que no se reconoce — el webhook igual contesta 200
+  }
+  return new Response("ok");
+}
+
+// Un evento suelto (sin buffering) también se puede leer de a uno:
+const evento = leerEventoWebhook(JSON.parse(crudo), request.headers.get("x-webhook-event"));
+```
 
-const evento = leerEventoWebhook(cuerpoDelWebhook); // nunca tira
-if (evento.tipo === "mensaje") {
-  // evento.mensaje: { tipo, de, phoneNumberId, texto, payload?, mensajeId, fechaHora }
-} else if (evento.tipo === "ignorado") {
-  // evento de otra aplicación, o que no se reconoce — el webhook igual contesta 200
+### Media entrante
+
+```ts
+import { bajarMedia } from "@mafesoftware/kapso-wa";
+
+if (evento.tipo === "mensaje" && evento.mensaje.media) {
+  // `media.url` (message.kapso.media_url) suele venir ya listo; por id:
+  const r = await bajarMedia({ apiKey: "kapso_...", phoneNumberId }, evento.mensaje.media.id);
+  if (r.ok) await guardar(r.bytes, r.mimeType); // Uint8Array
 }
 ```
 
+### Plantillas
+
+```ts
+import { crearPlantilla, listarPlantillas } from "@mafesoftware/kapso-wa";
+
+const cred = { apiKey: "kapso_..." };
+const r = await crearPlantilla(cred, wabaId, {
+  nombre: "ef_expensa_vence",
+  categoria: "UTILITY",
+  componentes: [{ type: "BODY", text: "Hola {{1}}, tu expensa vence el {{2}}.", example: { body_text: [["Juana", "10/11"]] } }],
+});
+// r.plantilla.estado === "PENDING" hasta que Meta la revisa
+
+const lista = await listarPlantillas(cred, wabaId, { estado: "APPROVED" });
+if (lista.ok) lista.plantillas.map((p) => `${p.nombre}: ${p.estado}`);
+```
+
 ## Probar
 
 ```bash

package/dist/index.d.ts

@@ -31,14 +31,17 @@
  */
 /** Un `fetch` compatible. Se inyecta en los tests para no salir a la red. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
-export type Credenciales = {
+/** Lo que necesita una llamada a la API de plataforma (clientes, webhooks, plantillas). */
+export type CredencialesPlataforma = {
     apiKey: string;
-    /** El número desde el que se manda. Es un dato del CLUB, no del deployment. */
-    phoneNumberId: string;
     fetch?: FetchLike;
     /** Milisegundos antes de cortar. 15 s por defecto. */
     timeoutMs?: number;
 };
+export type Credenciales = CredencialesPlataforma & {
+    /** El número desde el que se manda. Es un dato del CLUB, no del deployment. */
+    phoneNumberId: string;
+};
 /**
  * Por qué falló, y sobre todo **si reintentar sirve**.
  *
@@ -135,12 +138,14 @@ export type ClienteKapso = {
  * `externalCustomerId` lleva el prefijo de la aplicación
  * (`gestionflow:<clubId>`) porque el webhook de conexión trae **solo** el id de
  * cliente y nunca el producto: sin prefijo no hay forma de saber de quién es.
+ *
+ * **Cada aplicación tiene que pasar SU prefijo** (`"consult360"`, `"ediflow"`…).
+ * El default `"gestionflow"` queda solo por compatibilidad con la primera app
+ * que usó el paquete: otra app que lo omita da de alta a sus clientes como si
+ * fueran de GestionFlow, y como el proyecto de Kapso es uno solo para todo MAFE
+ * Software, después no hay forma de separarlos.
  */
-export declare function crearCliente(cred: {
-    apiKey: string;
-    fetch?: FetchLike;
-    timeoutMs?: number;
-}, nombre: string, clubId: string, prefijo?: string): Promise<{
+export declare function crearCliente(cred: CredencialesPlataforma, nombre: string, clubId: string, prefijo?: string): Promise<{
     ok: true;
     cliente: ClienteKapso;
 } | {
@@ -170,17 +175,26 @@ export declare function crearCliente(cred: {
  * Solo hay **un link activo por cliente**: crear otro revoca el anterior. Y
  * sobre un número YA conectado no se emite un link nuevo — puede intentar una
  * segunda conexión y arruinar la que funciona.
+ *
+ * ## Reconectar un número que se cayó
+ *
+ * La excepción es `reconectarTelefono` (`reconnect_phone_number`, el número
+ * como se muestra, p. ej. `"+5491145678901"`): cuando la credencial se rompió
+ * (token revocado, cambio de contraseña), el link queda atado a ESE número y a
+ * su WABA, y solo renueva la credencial. Kapso fija ahí el tipo de conexión al
+ * de la conexión existente y contesta 422 si se le manda otro, así que en ese
+ * caso **no se manda `allowed_connection_types`**, y tampoco
+ * `meta_billing_mode` salvo que se pase explícito (es de la WABA y no cambia).
+ * Si el número no es de ese cliente, también es 422.
  */
-export declare function crearSetupLink(cred: {
-    apiKey: string;
-    fetch?: FetchLike;
-    timeoutMs?: number;
-}, clienteId: string, opciones?: {
+export declare function crearSetupLink(cred: CredencialesPlataforma, clienteId: string, opciones?: {
     metaBilling?: "customer_managed" | "partner_managed";
     volverBienA?: string;
     volverMalA?: string;
     colorPrimario?: string;
     idioma?: string;
+    /** Número ya conectado de este cliente cuya credencial hay que renovar. */
+    reconectarTelefono?: string;
 }): Promise<{
     ok: true;
     url: string;
@@ -190,18 +204,202 @@ export declare function crearSetupLink(cred: {
     categoria: CategoriaError;
     error: string;
 }>;
+/**
+ * Los eventos que un número le manda a la aplicación por defecto.
+ *
+ * Uno por estado: no existe `whatsapp.message.status_updated`. `sent` no va
+ * porque eso ya lo dice la respuesta del envío.
+ */
+export declare const EVENTOS_WEBHOOK_NUMERO: readonly ["whatsapp.message.received", "whatsapp.message.delivered", "whatsapp.message.read", "whatsapp.message.failed"];
+export type WebhookNumero = {
+    id: string;
+    url: string;
+    eventos: string[];
+    activo: boolean;
+};
+/**
+ * Registra el webhook de un número (`kind: "kapso"`).
+ *
+ * Los mensajes se rutean **por número**, no por proyecto: el webhook de
+ * proyecto solo trae conexiones (`whatsapp.phone_number.*`). Por eso cada
+ * número que se conecta registra el suyo apuntando a la aplicación dueña, y un
+ * mensaje al número de un club nunca termina en otra app del mismo proyecto.
+ *
+ * El `secreto` es obligatorio y **Kapso no lo genera**: lo elige la app. Con uno
+ * solo para todos sus números, `verificarFirmaWebhook` usa un único secreto.
+ *
+ * Registrar dos veces la misma URL deja dos webhooks y cada evento llega
+ * duplicado: mirar antes con `listarWebhooksNumero`.
+ */
+export declare function registrarWebhookNumero(cred: CredencialesPlataforma, phoneNumberId: string, webhook: {
+    url: string;
+    secreto: string;
+    eventos?: readonly string[];
+}): Promise<{
+    ok: true;
+    webhook: WebhookNumero;
+} | {
+    ok: false;
+    categoria: CategoriaError;
+    error: string;
+    estado?: number;
+}>;
+/**
+ * Los webhooks de un número, el más nuevo primero.
+ *
+ * Devuelve el arreglo ya desenvuelto del `{ data: [...] }` de Kapso: leer
+ * `.data.data` daba `undefined` y la lista se veía vacía siempre.
+ */
+export declare function listarWebhooksNumero(cred: CredencialesPlataforma, phoneNumberId: string): Promise<{
+    ok: true;
+    webhooks: WebhookNumero[];
+} | {
+    ok: false;
+    categoria: CategoriaError;
+    error: string;
+    estado?: number;
+}>;
+export type CategoriaPlantilla = "UTILITY" | "MARKETING" | "AUTHENTICATION";
+export type Plantilla = {
+    id: string;
+    nombre: string;
+    idioma?: string;
+    /** `APPROVED`, `PENDING`, `REJECTED`… tal cual lo dice Meta. */
+    estado: string;
+    categoria?: string;
+};
+/**
+ * Da de alta una plantilla en la WABA del club. Queda `PENDING` hasta que Meta
+ * la revisa (minutos a horas); recién `APPROVED` se puede mandar.
+ *
+ * `componentes` es el arreglo `components` de Meta tal cual (`BODY`, `HEADER`,
+ * `FOOTER`, `BUTTONS`), con sus `example`: Meta rechaza un cuerpo con
+ * parámetros sin ejemplo. El nombre lleva el prefijo de la app (ver el
+ * encabezado del módulo).
+ *
+ * La WABA es del club, así que esto se corre **una vez por club** al conectar
+ * su número, no una vez por aplicación.
+ */
+export declare function crearPlantilla(cred: CredencialesPlataforma, wabaId: string, definicion: {
+    nombre: string;
+    idioma?: string;
+    categoria: CategoriaPlantilla;
+    componentes: readonly unknown[];
+    formatoParametros?: "POSITIONAL" | "NAMED";
+}): Promise<{
+    ok: true;
+    plantilla: Plantilla;
+} | {
+    ok: false;
+    categoria: CategoriaError;
+    error: string;
+    estado?: number;
+}>;
+/**
+ * Las plantillas de una WABA con su estado. Sirve para saber si una ya está
+ * aprobada antes de mandarla, o si hay que darla de alta.
+ *
+ * Trae hasta `limite` (100 por defecto, el máximo de Meta). Si hay más,
+ * `siguiente` es el cursor para pedir la página que sigue con `despues`.
+ */
+export declare function listarPlantillas(cred: CredencialesPlataforma, wabaId: string, opciones?: {
+    nombre?: string;
+    estado?: string;
+    limite?: number;
+    despues?: string;
+}): Promise<{
+    ok: true;
+    plantillas: Plantilla[];
+    siguiente?: string;
+} | {
+    ok: false;
+    categoria: CategoriaError;
+    error: string;
+    estado?: number;
+}>;
+/**
+ * Baja lo adjunto a un mensaje entrante (foto de un comprobante, audio…).
+ *
+ * Son dos pasos: `GET /{media_id}?phone_number_id=…` devuelve los datos de Meta
+ * más un `download_url` de Kapso con la autenticación adentro (vale **4
+ * minutos**), y después se baja ese `download_url` sin la clave. El `url` de
+ * Meta que viene al lado NO sirve: pide el token de Meta, que no tenemos.
+ *
+ * En un evento de Kapso suele venir además `mensaje.media.url`
+ * (`message.kapso.media_url`), que ya está espejado; esto es para cuando solo
+ * se tiene el id, o para bajarlo más tarde.
+ */
+export declare function bajarMedia(cred: Credenciales, mediaId: string): Promise<{
+    ok: true;
+    bytes: Uint8Array;
+    mimeType: string;
+    nombreArchivo?: string;
+} | {
+    ok: false;
+    categoria: CategoriaError;
+    error: string;
+    estado?: number;
+}>;
+/**
+ * ¿Este cuerpo lo mandó Kapso de verdad?
+ *
+ * Kapso firma cada entrega con HMAC-SHA256 sobre el **cuerpo crudo**, en hex,
+ * con el `secret_key` que se eligió al registrar el webhook, y lo manda en la
+ * cabecera `X-Webhook-Signature`.
+ *
+ * **Crudo** quiere decir los bytes tal como llegaron (`await request.text()`),
+ * no un `JSON.stringify` del objeto ya parseado: cualquier diferencia de orden
+ * de claves o de escapes rompe la firma, y lo rompe de a ratos, que es la peor
+ * forma de romperse.
+ *
+ * Sin secreto o sin firma el resultado es `false`, nunca "dejar pasar": un
+ * webhook sin verificar deja que cualquiera POSTee "el socio 1042 pregunta por
+ * su deuda" haciéndose pasar por su teléfono. Decidir qué hacer en desarrollo
+ * es de la aplicación (el paquete no mira `NODE_ENV`).
+ *
+ * Usa `node:crypto` como `verificarFirmaWebhook` de `@mafesoftware/mercadopago-ar`:
+ * sincrónico, y corre en Node ≥ 20 y en las funciones de Vercel. La comparación
+ * es en tiempo constante.
+ */
+export declare function verificarFirmaWebhook(cuerpoCrudo: string | Uint8Array, firmaHex: string | null | undefined, secreto: string): boolean;
+/** Lo adjunto a un mensaje entrante: imagen, video, documento o audio. */
+export type MediaEntrante = {
+    /** El id de Meta. Con esto se baja por `bajarMedia`. */
+    id: string;
+    mimeType?: string;
+    nombreArchivo?: string;
+    /**
+     * `message.kapso.media_url`: Kapso ya lo espejó y lo deja listo para bajar
+     * sin pasar por `bajarMedia`. Puede no venir (p. ej. en un webhook `meta`).
+     */
+    url?: string;
+};
 export type MensajeEntrante = {
-    tipo: "texto" | "boton" | "opcion_lista" | "otro";
+    tipo: "texto" | "boton" | "opcion_lista" | "imagen" | "video" | "documento" | "audio" | "ubicacion" | "otro";
     /** El número que escribió, en E.164 sin `+`. */
     de: string;
     phoneNumberId: string;
-    /** El texto, o el título del botón/opción que tocaron. */
+    /**
+     * El texto; el título del botón/opción que tocaron; el epígrafe de una
+     * imagen, video o documento (vacío si no tiene); o `"lat,lng"` en una
+     * ubicación.
+     */
     texto: string;
     /** El `id` que le pusimos al botón o a la opción. Es nuestro, no de Meta. */
     payload?: string;
+    /** Solo en imagen, video, documento y audio. */
+    media?: MediaEntrante;
+    /** `conversation.contact_name`: el nombre de perfil de WhatsApp, si Kapso lo sabe. */
+    nombreContacto?: string;
     mensajeId: string;
     fechaHora: Date;
 };
+/** El error que Meta adjunta a un estado `failed` (p. ej. 131047, fuera de la ventana). */
+export type ErrorDeEstado = {
+    codigo?: number;
+    titulo?: string;
+    mensaje?: string;
+};
 export type EventoWebhook = {
     tipo: "mensaje";
     mensaje: MensajeEntrante;
@@ -210,20 +408,59 @@ export type EventoWebhook = {
     mensajeId: string;
     estado: string;
     fechaHora: Date;
+    error?: ErrorDeEstado;
 } | {
     tipo: "numero_conectado";
+    /** El id de cliente de Kapso (`customer.id`), el que devolvió `crearCliente`. */
     clienteId: string;
     phoneNumberId: string;
     telefono?: string;
+    /** `customer.external_id`: el `<prefijo>:<id>` que se le puso en `crearCliente`. */
+    idExterno?: string;
 } | {
     tipo: "numero_desconectado";
     clienteId: string;
     phoneNumberId: string;
+    idExterno?: string;
 } | {
     tipo: "ignorado";
     motivo: string;
 };
-export declare function leerEventoWebhook(crudo: unknown): EventoWebhook;
+/**
+ * Lee UN evento del webhook. **Nunca tira.**
+ *
+ * **El nombre del evento viaja en la cabecera `X-Webhook-Event`, no en el
+ * cuerpo**: el cuerpo v2 de un mensaje es `{ message, conversation,
+ * phone_number_id }` y no dice qué evento es. Por eso el segundo argumento —
+ * pasarle `request.headers.get("x-webhook-event")` — manda sobre
+ * `cuerpo.event`/`cuerpo.type`, que quedan solo como respaldo. Sin la cabecera,
+ * un mensaje real de Kapso sale `"ignorado"`.
+ *
+ * Lo que no se entiende sale como `"ignorado"` y **el webhook igual contesta
+ * 200**. Si contestara error, Kapso reintenta el mismo cuerpo y los eventos que
+ * sí importan se quedan atrás en la cola.
+ *
+ * Un evento de un cliente que no es nuestro también es `"ignorado"`: el webhook
+ * de proyecto dispara para TODAS las aplicaciones que comparten el proyecto, y
+ * filtrar es responsabilidad de cada una.
+ *
+ * Un lote (`batch: true`, con buffering prendido) no se lee acá: sale
+ * `"ignorado"` diciendo que se use `leerEventosWebhook`, para no perder en
+ * silencio todos los mensajes menos uno.
+ */
+export declare function leerEventoWebhook(crudo: unknown, nombreEvento?: string | null): EventoWebhook;
+/**
+ * Lee TODO lo que trae una entrega del webhook, sea un evento suelto o un lote.
+ *
+ * Con buffering prendido para `whatsapp.message.received`, Kapso manda
+ * **siempre** un sobre `{ type, batch: true, data: [...], batch_info }`, aunque
+ * traiga un solo mensaje. Cada elemento de `data` tiene la misma forma que un
+ * evento suelto. Sin buffering, devuelve un arreglo de uno.
+ *
+ * El nombre del evento sale de la cabecera `X-Webhook-Event` si se pasa, y si
+ * no del `type` del sobre. Nunca tira.
+ */
+export declare function leerEventosWebhook(crudo: unknown, nombreEvento?: string | null): EventoWebhook[];
 /**
  * ¿Se le puede mandar texto libre a esta persona?
  *

package/dist/index.js

@@ -29,6 +29,7 @@
  * esa clave abre TODOS los números del proyecto, así que una aplicación toca
  * únicamente los números de sus propios clientes.
  */
+import { createHmac, timingSafeEqual } from "node:crypto";
 const BASE_META = "https://api.kapso.ai/meta/whatsapp/v24.0";
 const BASE_PLATAFORMA = "https://api.kapso.ai/platform/v1";
 /* ============================================================
@@ -239,6 +240,12 @@ async function postMensaje(cred, cuerpo) {
  * `externalCustomerId` lleva el prefijo de la aplicación
  * (`gestionflow:<clubId>`) porque el webhook de conexión trae **solo** el id de
  * cliente y nunca el producto: sin prefijo no hay forma de saber de quién es.
+ *
+ * **Cada aplicación tiene que pasar SU prefijo** (`"consult360"`, `"ediflow"`…).
+ * El default `"gestionflow"` queda solo por compatibilidad con la primera app
+ * que usó el paquete: otra app que lo omita da de alta a sus clientes como si
+ * fueran de GestionFlow, y como el proyecto de Kapso es uno solo para todo MAFE
+ * Software, después no hay forma de separarlos.
  */
 export async function crearCliente(cred, nombre, clubId, prefijo = "gestionflow") {
     const r = await pedir(cred, `${BASE_PLATAFORMA}/customers`, {
@@ -280,6 +287,17 @@ export async function crearCliente(cred, nombre, clubId, prefijo = "gestionflow"
  * Solo hay **un link activo por cliente**: crear otro revoca el anterior. Y
  * sobre un número YA conectado no se emite un link nuevo — puede intentar una
  * segunda conexión y arruinar la que funciona.
+ *
+ * ## Reconectar un número que se cayó
+ *
+ * La excepción es `reconectarTelefono` (`reconnect_phone_number`, el número
+ * como se muestra, p. ej. `"+5491145678901"`): cuando la credencial se rompió
+ * (token revocado, cambio de contraseña), el link queda atado a ESE número y a
+ * su WABA, y solo renueva la credencial. Kapso fija ahí el tipo de conexión al
+ * de la conexión existente y contesta 422 si se le manda otro, así que en ese
+ * caso **no se manda `allowed_connection_types`**, y tampoco
+ * `meta_billing_mode` salvo que se pase explícito (es de la WABA y no cambia).
+ * Si el número no es de ese cliente, también es 422.
  */
 export async function crearSetupLink(cred, clienteId, opciones = {}) {
     const r = await pedir(cred, `${BASE_PLATAFORMA}/customers/${encodeURIComponent(clienteId)}/setup_links`, {
@@ -287,8 +305,15 @@ export async function crearSetupLink(cred, clienteId, opciones = {}) {
         body: JSON.stringify({
             setup_link: {
                 language: opciones.idioma ?? "es",
-                allowed_connection_types: ["coexistence"],
-                meta_billing_mode: opciones.metaBilling ?? "customer_managed",
+                ...(opciones.reconectarTelefono
+                    ? {
+                        reconnect_phone_number: opciones.reconectarTelefono,
+                        ...(opciones.metaBilling ? { meta_billing_mode: opciones.metaBilling } : {}),
+                    }
+                    : {
+                        allowed_connection_types: ["coexistence"],
+                        meta_billing_mode: opciones.metaBilling ?? "customer_managed",
+                    }),
                 ...(opciones.volverBienA ? { success_redirect_url: opciones.volverBienA } : {}),
                 ...(opciones.volverMalA ? { failure_redirect_url: opciones.volverMalA } : {}),
                 ...(opciones.colorPrimario ? { theme_config: { primary_color: opciones.colorPrimario } } : {}),
@@ -303,17 +328,242 @@ export async function crearSetupLink(cred, clienteId, opciones = {}) {
         return { ok: false, categoria: "rechazado", error: "Kapso no devolvió una URL" };
     return { ok: true, url: fila.url, expira: fila.expires_at };
 }
+/* ============================================================
+   WEBHOOKS DEL NÚMERO
+   ============================================================ */
 /**
- * Lee un evento del webhook. **Nunca tira.**
+ * Los eventos que un número le manda a la aplicación por defecto.
  *
- * Lo que no se entiende sale como `"ignorado"` y **el webhook igual contesta
- * 200**. Si contestara error, Kapso reintenta el mismo cuerpo para siempre y
- * los eventos que sí importan se quedan atrás en la cola.
+ * Uno por estado: no existe `whatsapp.message.status_updated`. `sent` no va
+ * porque eso ya lo dice la respuesta del envío.
+ */
+export const EVENTOS_WEBHOOK_NUMERO = [
+    "whatsapp.message.received",
+    "whatsapp.message.delivered",
+    "whatsapp.message.read",
+    "whatsapp.message.failed",
+];
+/**
+ * Registra el webhook de un número (`kind: "kapso"`).
  *
- * Un evento de un cliente que no es nuestro también es `"ignorado"`: el webhook
- * de proyecto dispara para TODAS las aplicaciones que comparten el proyecto, y
- * filtrar es responsabilidad de cada una.
+ * Los mensajes se rutean **por número**, no por proyecto: el webhook de
+ * proyecto solo trae conexiones (`whatsapp.phone_number.*`). Por eso cada
+ * número que se conecta registra el suyo apuntando a la aplicación dueña, y un
+ * mensaje al número de un club nunca termina en otra app del mismo proyecto.
+ *
+ * El `secreto` es obligatorio y **Kapso no lo genera**: lo elige la app. Con uno
+ * solo para todos sus números, `verificarFirmaWebhook` usa un único secreto.
+ *
+ * Registrar dos veces la misma URL deja dos webhooks y cada evento llega
+ * duplicado: mirar antes con `listarWebhooksNumero`.
+ */
+export async function registrarWebhookNumero(cred, phoneNumberId, webhook) {
+    if (!phoneNumberId)
+        return { ok: false, categoria: "numero", error: "falta el phoneNumberId" };
+    if (!webhook.url)
+        return { ok: false, categoria: "rechazado", error: "falta la URL del webhook" };
+    if (!webhook.secreto)
+        return { ok: false, categoria: "credenciales", error: "falta el secreto del webhook" };
+    const eventos = webhook.eventos?.length ? [...webhook.eventos] : [...EVENTOS_WEBHOOK_NUMERO];
+    const r = await pedir(cred, `${BASE_PLATAFORMA}/whatsapp/phone_numbers/${encodeURIComponent(phoneNumberId)}/webhooks`, {
+        method: "POST",
+        body: JSON.stringify({
+            whatsapp_webhook: { kind: "kapso", url: webhook.url, events: eventos, secret_key: webhook.secreto, active: true },
+        }),
+    });
+    if (!r.ok)
+        return r;
+    const d = r.datos;
+    const fila = aWebhook(d?.data ?? d);
+    if (!fila)
+        return { ok: false, categoria: "rechazado", error: "Kapso no devolvió un id de webhook" };
+    return { ok: true, webhook: fila };
+}
+/**
+ * Los webhooks de un número, el más nuevo primero.
+ *
+ * Devuelve el arreglo ya desenvuelto del `{ data: [...] }` de Kapso: leer
+ * `.data.data` daba `undefined` y la lista se veía vacía siempre.
+ */
+export async function listarWebhooksNumero(cred, phoneNumberId) {
+    if (!phoneNumberId)
+        return { ok: false, categoria: "numero", error: "falta el phoneNumberId" };
+    const r = await pedir(cred, `${BASE_PLATAFORMA}/whatsapp/phone_numbers/${encodeURIComponent(phoneNumberId)}/webhooks`, {
+        method: "GET",
+    });
+    if (!r.ok)
+        return r;
+    const d = r.datos;
+    const filas = Array.isArray(d?.data) ? d.data : Array.isArray(d) ? d : [];
+    return { ok: true, webhooks: filas.map(aWebhook).filter((w) => w !== null) };
+}
+function aWebhook(crudo) {
+    if (!crudo?.id)
+        return null;
+    return {
+        id: String(crudo.id),
+        url: String(crudo.url ?? ""),
+        eventos: Array.isArray(crudo.events) ? crudo.events.map(String) : [],
+        activo: crudo.active !== false,
+    };
+}
+/**
+ * Da de alta una plantilla en la WABA del club. Queda `PENDING` hasta que Meta
+ * la revisa (minutos a horas); recién `APPROVED` se puede mandar.
+ *
+ * `componentes` es el arreglo `components` de Meta tal cual (`BODY`, `HEADER`,
+ * `FOOTER`, `BUTTONS`), con sus `example`: Meta rechaza un cuerpo con
+ * parámetros sin ejemplo. El nombre lleva el prefijo de la app (ver el
+ * encabezado del módulo).
+ *
+ * La WABA es del club, así que esto se corre **una vez por club** al conectar
+ * su número, no una vez por aplicación.
+ */
+export async function crearPlantilla(cred, wabaId, definicion) {
+    if (!wabaId)
+        return { ok: false, categoria: "credenciales", error: "falta el id de la WABA" };
+    if (!definicion.nombre)
+        return { ok: false, categoria: "plantilla", error: "falta el nombre de la plantilla" };
+    const idioma = definicion.idioma ?? "es_AR";
+    const r = await pedir(cred, `${BASE_META}/${encodeURIComponent(wabaId)}/message_templates`, {
+        method: "POST",
+        body: JSON.stringify({
+            name: definicion.nombre,
+            language: idioma,
+            category: definicion.categoria,
+            ...(definicion.formatoParametros ? { parameter_format: definicion.formatoParametros } : {}),
+            components: definicion.componentes,
+        }),
+    });
+    if (!r.ok)
+        return r;
+    // El proxy de Meta contesta `{ id, status, category }` SIN el sobre `data`.
+    const d = r.datos;
+    const fila = d?.data ?? d;
+    if (!fila?.id)
+        return { ok: false, categoria: "rechazado", error: "Kapso no devolvió un id de plantilla" };
+    return {
+        ok: true,
+        plantilla: {
+            id: String(fila.id),
+            nombre: definicion.nombre,
+            idioma,
+            estado: String(fila.status ?? "PENDING"),
+            ...(fila.category ? { categoria: String(fila.category) } : {}),
+        },
+    };
+}
+/**
+ * Las plantillas de una WABA con su estado. Sirve para saber si una ya está
+ * aprobada antes de mandarla, o si hay que darla de alta.
+ *
+ * Trae hasta `limite` (100 por defecto, el máximo de Meta). Si hay más,
+ * `siguiente` es el cursor para pedir la página que sigue con `despues`.
  */
+export async function listarPlantillas(cred, wabaId, opciones = {}) {
+    if (!wabaId)
+        return { ok: false, categoria: "credenciales", error: "falta el id de la WABA" };
+    const limite = Math.min(Math.max(1, Math.trunc(opciones.limite ?? 100)), 100);
+    const q = new URLSearchParams({ limit: String(limite) });
+    if (opciones.nombre)
+        q.set("name", opciones.nombre);
+    if (opciones.estado)
+        q.set("status", opciones.estado);
+    if (opciones.despues)
+        q.set("after", opciones.despues);
+    const r = await pedir(cred, `${BASE_META}/${encodeURIComponent(wabaId)}/message_templates?${q}`, { method: "GET" });
+    if (!r.ok)
+        return r;
+    const d = r.datos;
+    const filas = Array.isArray(d?.data) ? d.data : [];
+    const plantillas = filas
+        .filter((f) => f?.name)
+        .map((f) => ({
+        id: String(f.id ?? ""),
+        nombre: String(f.name),
+        ...(f.language ? { idioma: String(f.language) } : {}),
+        estado: String(f.status ?? ""),
+        ...(f.category ? { categoria: String(f.category) } : {}),
+    }));
+    // Meta deja `cursors.after` aun en la última página: solo hay "siguiente" si
+    // dice `next`, o si la página vino llena.
+    const despues = d?.paging?.cursors?.after;
+    const hayMas = Boolean(d?.paging?.next) || filas.length >= limite;
+    return { ok: true, plantillas, ...(despues && hayMas ? { siguiente: despues } : {}) };
+}
+/* ============================================================
+   MEDIA ENTRANTE
+   ============================================================ */
+/**
+ * Baja lo adjunto a un mensaje entrante (foto de un comprobante, audio…).
+ *
+ * Son dos pasos: `GET /{media_id}?phone_number_id=…` devuelve los datos de Meta
+ * más un `download_url` de Kapso con la autenticación adentro (vale **4
+ * minutos**), y después se baja ese `download_url` sin la clave. El `url` de
+ * Meta que viene al lado NO sirve: pide el token de Meta, que no tenemos.
+ *
+ * En un evento de Kapso suele venir además `mensaje.media.url`
+ * (`message.kapso.media_url`), que ya está espejado; esto es para cuando solo
+ * se tiene el id, o para bajarlo más tarde.
+ */
+export async function bajarMedia(cred, mediaId) {
+    if (!cred.phoneNumberId)
+        return { ok: false, categoria: "credenciales", error: "falta el phoneNumberId del club" };
+    if (!mediaId)
+        return { ok: false, categoria: "rechazado", error: "falta el id de la media" };
+    const q = new URLSearchParams({ phone_number_id: cred.phoneNumberId });
+    const r = await pedir(cred, `${BASE_META}/${encodeURIComponent(mediaId)}?${q}`, { method: "GET" });
+    if (!r.ok)
+        return r;
+    const d = r.datos;
+    if (!d?.download_url)
+        return { ok: false, categoria: "rechazado", error: "Kapso no devolvió un download_url" };
+    const b = await bajarBytes(cred, d.download_url);
+    if (!b.ok)
+        return b;
+    return {
+        ok: true,
+        bytes: b.bytes,
+        mimeType: d.mime_type || b.tipo || "application/octet-stream",
+        ...(d.filename ? { nombreArchivo: String(d.filename) } : {}),
+    };
+}
+/* ============================================================
+   WEBHOOK ENTRANTE
+   ============================================================ */
+/**
+ * ¿Este cuerpo lo mandó Kapso de verdad?
+ *
+ * Kapso firma cada entrega con HMAC-SHA256 sobre el **cuerpo crudo**, en hex,
+ * con el `secret_key` que se eligió al registrar el webhook, y lo manda en la
+ * cabecera `X-Webhook-Signature`.
+ *
+ * **Crudo** quiere decir los bytes tal como llegaron (`await request.text()`),
+ * no un `JSON.stringify` del objeto ya parseado: cualquier diferencia de orden
+ * de claves o de escapes rompe la firma, y lo rompe de a ratos, que es la peor
+ * forma de romperse.
+ *
+ * Sin secreto o sin firma el resultado es `false`, nunca "dejar pasar": un
+ * webhook sin verificar deja que cualquiera POSTee "el socio 1042 pregunta por
+ * su deuda" haciéndose pasar por su teléfono. Decidir qué hacer en desarrollo
+ * es de la aplicación (el paquete no mira `NODE_ENV`).
+ *
+ * Usa `node:crypto` como `verificarFirmaWebhook` de `@mafesoftware/mercadopago-ar`:
+ * sincrónico, y corre en Node ≥ 20 y en las funciones de Vercel. La comparación
+ * es en tiempo constante.
+ */
+export function verificarFirmaWebhook(cuerpoCrudo, firmaHex, secreto) {
+    if (!secreto || !firmaHex)
+        return false;
+    // El hex de Kapso viene en minúsculas; se normaliza por si un proxy lo toca.
+    const recibida = Buffer.from(firmaHex.trim().toLowerCase(), "utf8");
+    const calculada = Buffer.from(createHmac("sha256", secreto).update(cuerpoCrudo).digest("hex"), "utf8");
+    // timingSafeEqual tira si los largos difieren, así que se chequea antes. El
+    // largo de un HMAC no es secreto: siempre son 64 caracteres.
+    if (recibida.length !== calculada.length)
+        return false;
+    return timingSafeEqual(recibida, calculada);
+}
 /**
  * Cuánto texto se acepta de un mensaje entrante.
  *
@@ -324,31 +574,66 @@ export async function crearSetupLink(cred, clienteId, opciones = {}) {
  */
 const MAXIMO_TEXTO = 4096;
 const soloLoQueEntra = (v) => String(v ?? "").slice(0, MAXIMO_TEXTO);
-export function leerEventoWebhook(crudo) {
+/** Lo que Meta llama `image`/`video`/`document`/`audio`, en nuestros nombres. */
+const TIPOS_MEDIA = {
+    image: "imagen",
+    video: "video",
+    document: "documento",
+    audio: "audio",
+};
+/**
+ * Lee UN evento del webhook. **Nunca tira.**
+ *
+ * **El nombre del evento viaja en la cabecera `X-Webhook-Event`, no en el
+ * cuerpo**: el cuerpo v2 de un mensaje es `{ message, conversation,
+ * phone_number_id }` y no dice qué evento es. Por eso el segundo argumento —
+ * pasarle `request.headers.get("x-webhook-event")` — manda sobre
+ * `cuerpo.event`/`cuerpo.type`, que quedan solo como respaldo. Sin la cabecera,
+ * un mensaje real de Kapso sale `"ignorado"`.
+ *
+ * Lo que no se entiende sale como `"ignorado"` y **el webhook igual contesta
+ * 200**. Si contestara error, Kapso reintenta el mismo cuerpo y los eventos que
+ * sí importan se quedan atrás en la cola.
+ *
+ * Un evento de un cliente que no es nuestro también es `"ignorado"`: el webhook
+ * de proyecto dispara para TODAS las aplicaciones que comparten el proyecto, y
+ * filtrar es responsabilidad de cada una.
+ *
+ * Un lote (`batch: true`, con buffering prendido) no se lee acá: sale
+ * `"ignorado"` diciendo que se use `leerEventosWebhook`, para no perder en
+ * silencio todos los mensajes menos uno.
+ */
+export function leerEventoWebhook(crudo, nombreEvento) {
     if (!crudo || typeof crudo !== "object")
         return { tipo: "ignorado", motivo: "cuerpo vacío" };
     const e = crudo;
-    const evento = String(e.event ?? e.type ?? "");
+    if (e.batch === true) {
+        const n = Array.isArray(e.data) ? e.data.length : 0;
+        return { tipo: "ignorado", motivo: `lote de ${n} eventos: usar leerEventosWebhook` };
+    }
+    const evento = String(nombreEvento?.trim() || e.event || e.type || "");
     const datos = e.data ?? e.payload ?? e;
-    if (evento === "whatsapp.phone_number.created") {
+    if (evento === "whatsapp.phone_number.created" || evento === "whatsapp.phone_number.deleted") {
         const id = datos?.phone_number_id ?? datos?.id;
-        const cliente = datos?.customer_id ?? datos?.external_customer_id;
+        // v2 manda `customer: { id, external_id }`; `customer_id` suelto es de v1.
+        const cliente = datos?.customer?.id ?? datos?.customer_id ?? datos?.external_customer_id;
+        const externo = datos?.customer?.external_id ?? datos?.customer?.external_customer_id;
+        const conectado = evento === "whatsapp.phone_number.created";
         if (!id || !cliente)
-            return { tipo: "ignorado", motivo: "conexión sin ids" };
-        return {
-            tipo: "numero_conectado",
+            return { tipo: "ignorado", motivo: conectado ? "conexión sin ids" : "desconexión sin ids" };
+        const comun = {
             clienteId: String(cliente),
             phoneNumberId: String(id),
+            ...(externo ? { idExterno: String(externo) } : {}),
+        };
+        if (!conectado)
+            return { tipo: "numero_desconectado", ...comun };
+        return {
+            tipo: "numero_conectado",
+            ...comun,
             telefono: datos?.display_phone_number ? String(datos.display_phone_number) : undefined,
         };
     }
-    if (evento === "whatsapp.phone_number.deleted") {
-        const id = datos?.phone_number_id ?? datos?.id;
-        const cliente = datos?.customer_id ?? datos?.external_customer_id;
-        if (!id || !cliente)
-            return { tipo: "ignorado", motivo: "desconexión sin ids" };
-        return { tipo: "numero_desconectado", clienteId: String(cliente), phoneNumberId: String(id) };
-    }
     // Kapso manda UN evento por estado. No existe
     // `whatsapp.message.status_updated`: suscribirse a ese nombre inventado deja
     // las marcas de entrega vacias para siempre sin que nada parezca roto.
@@ -357,58 +642,139 @@ export function leerEventoWebhook(crudo) {
         const id = datos?.message?.id ?? datos?.id ?? datos?.message_id;
         if (!id)
             return { tipo: "ignorado", motivo: "estado sin id de mensaje" };
-        return { tipo: "estado", mensajeId: String(id), estado: estado[1], fechaHora: leerFecha(datos) };
-    }
-    if (evento === "whatsapp.message.received") {
-        const m = datos?.message ?? datos;
-        const de = m?.from ?? datos?.from;
-        if (!de)
-            return { tipo: "ignorado", motivo: "mensaje sin remitente" };
-        const phoneNumberId = datos?.phone_number_id ?? m?.phone_number_id ?? datos?.metadata?.phone_number_id ?? "";
-        const interactivo = m?.interactive;
-        if (interactivo?.type === "button_reply") {
-            return {
-                tipo: "mensaje",
-                mensaje: {
-                    tipo: "boton",
-                    de: String(de),
-                    phoneNumberId: String(phoneNumberId),
-                    texto: soloLoQueEntra(interactivo.button_reply?.title),
-                    payload: interactivo.button_reply?.id ? soloLoQueEntra(interactivo.button_reply.id) : undefined,
-                    mensajeId: String(m?.id ?? ""),
-                    fechaHora: leerFecha(m ?? datos),
-                },
-            };
-        }
-        if (interactivo?.type === "list_reply") {
-            return {
-                tipo: "mensaje",
-                mensaje: {
-                    tipo: "opcion_lista",
-                    de: String(de),
-                    phoneNumberId: String(phoneNumberId),
-                    texto: soloLoQueEntra(interactivo.list_reply?.title),
-                    payload: interactivo.list_reply?.id ? soloLoQueEntra(interactivo.list_reply.id) : undefined,
-                    mensajeId: String(m?.id ?? ""),
-                    fechaHora: leerFecha(m ?? datos),
-                },
-            };
-        }
-        const texto = m?.text?.body ?? m?.body;
+        const error = estado[1] === "failed" ? errorDeEstado(datos) : undefined;
+        // En v2 la hora está en el último estado del historial, o en el mensaje;
+        // la raíz no trae `timestamp`, y leerla ahí fechaba todo con "ahora".
+        const ultimo = ultimoEstado(datos);
         return {
-            tipo: "mensaje",
-            mensaje: {
-                tipo: texto ? "texto" : "otro",
-                de: String(de),
-                phoneNumberId: String(phoneNumberId),
-                texto: texto ? soloLoQueEntra(texto) : "",
-                mensajeId: String(m?.id ?? ""),
-                fechaHora: leerFecha(m ?? datos),
-            },
+            tipo: "estado",
+            mensajeId: String(id),
+            estado: estado[1],
+            fechaHora: leerFecha(ultimo?.timestamp != null ? ultimo : (datos?.message?.timestamp != null ? datos.message : datos)),
+            ...(error ? { error } : {}),
         };
     }
+    if (evento === "whatsapp.message.received")
+        return leerMensaje(datos);
     return { tipo: "ignorado", motivo: `evento no manejado: ${evento || "(sin nombre)"}` };
 }
+/**
+ * Lee TODO lo que trae una entrega del webhook, sea un evento suelto o un lote.
+ *
+ * Con buffering prendido para `whatsapp.message.received`, Kapso manda
+ * **siempre** un sobre `{ type, batch: true, data: [...], batch_info }`, aunque
+ * traiga un solo mensaje. Cada elemento de `data` tiene la misma forma que un
+ * evento suelto. Sin buffering, devuelve un arreglo de uno.
+ *
+ * El nombre del evento sale de la cabecera `X-Webhook-Event` si se pasa, y si
+ * no del `type` del sobre. Nunca tira.
+ */
+export function leerEventosWebhook(crudo, nombreEvento) {
+    if (crudo && typeof crudo === "object" && crudo.batch === true) {
+        const sobre = crudo;
+        if (!Array.isArray(sobre.data))
+            return [{ tipo: "ignorado", motivo: "lote sin data" }];
+        const evento = String(nombreEvento?.trim() || sobre.type || sobre.event || "");
+        return sobre.data.map((item) => leerEventoWebhook(item, evento));
+    }
+    return [leerEventoWebhook(crudo, nombreEvento)];
+}
+function leerMensaje(datos) {
+    const m = datos?.message ?? datos;
+    const conversacion = datos?.conversation;
+    // `from` puede no venir (identidades BSUID, y los elementos de un lote no lo
+    // traen): el teléfono de la conversación es el mismo número.
+    const de = m?.from ?? datos?.from ?? conversacion?.phone_number;
+    if (!de)
+        return { tipo: "ignorado", motivo: "mensaje sin remitente" };
+    const phoneNumberId = datos?.phone_number_id ??
+        m?.phone_number_id ??
+        datos?.metadata?.phone_number_id ??
+        conversacion?.phone_number_id ??
+        m?.kapso?.phone_number_id ??
+        "";
+    const base = {
+        de: String(de).replace(/^\+/, ""),
+        phoneNumberId: String(phoneNumberId),
+        ...(conversacion?.contact_name ? { nombreContacto: soloLoQueEntra(conversacion.contact_name) } : {}),
+        mensajeId: String(m?.id ?? ""),
+        fechaHora: leerFecha(m ?? datos),
+    };
+    const mensaje = (resto) => ({
+        tipo: "mensaje",
+        mensaje: { ...base, ...resto },
+    });
+    const interactivo = m?.interactive;
+    if (interactivo?.type === "button_reply" || interactivo?.type === "list_reply") {
+        const r = interactivo.type === "button_reply" ? interactivo.button_reply : interactivo.list_reply;
+        return mensaje({
+            tipo: interactivo.type === "button_reply" ? "boton" : "opcion_lista",
+            texto: soloLoQueEntra(r?.title),
+            payload: r?.id ? soloLoQueEntra(r.id) : undefined,
+        });
+    }
+    // El botón de respuesta rápida de una PLANTILLA no llega como `interactive`
+    // sino como `type: "button"`, con el payload que se aprobó en la plantilla.
+    if (m?.type === "button" && m?.button) {
+        return mensaje({
+            tipo: "boton",
+            texto: soloLoQueEntra(m.button.text),
+            payload: m.button.payload ? soloLoQueEntra(m.button.payload) : undefined,
+        });
+    }
+    const tipoMedia = TIPOS_MEDIA[String(m?.type ?? "")];
+    if (tipoMedia) {
+        const obj = m?.[m.type] ?? {};
+        const kapso = m?.kapso ?? {};
+        const datosMedia = kapso.media_data ?? {};
+        const url = kapso.media_url ?? datosMedia.url;
+        const mimeType = obj.mime_type ?? datosMedia.content_type;
+        const nombreArchivo = obj.filename ?? datosMedia.filename;
+        return mensaje({
+            tipo: tipoMedia,
+            texto: soloLoQueEntra(obj.caption ?? kapso.message_type_data?.caption ?? ""),
+            media: {
+                id: String(obj.id ?? ""),
+                ...(mimeType ? { mimeType: String(mimeType) } : {}),
+                ...(nombreArchivo ? { nombreArchivo: String(nombreArchivo) } : {}),
+                ...(url ? { url: String(url) } : {}),
+            },
+        });
+    }
+    if (m?.type === "location") {
+        const lat = Number(m.location?.latitude);
+        const lng = Number(m.location?.longitude);
+        // Una ubicación sin coordenadas no ubica nada: mejor `otro` que "NaN,NaN".
+        if (m.location?.latitude != null && m.location?.longitude != null && Number.isFinite(lat) && Number.isFinite(lng)) {
+            return mensaje({ tipo: "ubicacion", texto: `${lat},${lng}` });
+        }
+        return mensaje({ tipo: "otro", texto: "" });
+    }
+    const texto = m?.text?.body ?? m?.body;
+    return mensaje({ tipo: texto ? "texto" : "otro", texto: texto ? soloLoQueEntra(texto) : "" });
+}
+/**
+ * Por qué falló un mensaje. Meta lo deja en el ÚLTIMO elemento de
+ * `message.kapso.statuses` (el historial crudo de estados), en `errors[0]`.
+ */
+function ultimoEstado(datos) {
+    const estados = datos?.message?.kapso?.statuses;
+    return Array.isArray(estados) && estados.length ? estados[estados.length - 1] : undefined;
+}
+function errorDeEstado(datos) {
+    const ultimo = ultimoEstado(datos);
+    const crudo = ultimo?.errors?.[0] ?? datos?.message?.errors?.[0] ?? datos?.errors?.[0];
+    if (!crudo || typeof crudo !== "object")
+        return undefined;
+    const error = {
+        ...(typeof crudo.code === "number" ? { codigo: crudo.code } : {}),
+        ...(crudo.title ? { titulo: String(crudo.title) } : {}),
+        ...(crudo.message ?? crudo.error_data?.details
+            ? { mensaje: String(crudo.message ?? crudo.error_data.details) }
+            : {}),
+    };
+    return Object.keys(error).length ? error : undefined;
+}
 /**
  * ¿Se le puede mandar texto libre a esta persona?
  *
@@ -464,13 +830,7 @@ async function pedir(cred, url, init) {
         clearTimeout(corte);
     }
     const texto = await rta.text().catch(() => "");
-    let datos = null;
-    try {
-        datos = texto ? JSON.parse(texto) : null;
-    }
-    catch {
-        datos = null;
-    }
+    const datos = leerJson(texto);
     if (rta.ok)
         return { ok: true, datos };
     return {
@@ -480,6 +840,47 @@ async function pedir(cred, url, init) {
         estado: rta.status,
     };
 }
+/**
+ * Baja bytes de una URL que ya trae su autenticación (el `download_url` de
+ * Kapso): **sin** `X-API-Key`, que no hace falta y no tiene por qué viajar. El
+ * corte por tiempo cubre también la lectura del cuerpo, que es lo que tarda en
+ * un archivo grande.
+ */
+async function bajarBytes(cred, url) {
+    const hacerFetch = cred.fetch ?? globalThis.fetch;
+    if (!hacerFetch)
+        return { ok: false, categoria: "red", error: "no hay fetch disponible" };
+    const control = new AbortController();
+    const corte = setTimeout(() => control.abort(), cred.timeoutMs ?? 15_000);
+    try {
+        const rta = await hacerFetch(url, { method: "GET", signal: control.signal });
+        if (!rta.ok) {
+            const texto = await rta.text().catch(() => "");
+            return {
+                ok: false,
+                categoria: categoriaDe(rta.status, texto),
+                error: detalleDe(leerJson(texto), texto, rta.status),
+                estado: rta.status,
+            };
+        }
+        const bytes = new Uint8Array(await rta.arrayBuffer());
+        return { ok: true, bytes, tipo: rta.headers?.get("content-type") ?? undefined };
+    }
+    catch (e) {
+        return { ok: false, categoria: "red", error: mensajeDe(e) };
+    }
+    finally {
+        clearTimeout(corte);
+    }
+}
+function leerJson(texto) {
+    try {
+        return texto ? JSON.parse(texto) : null;
+    }
+    catch {
+        return null;
+    }
+}
 function categoriaDe(estado, texto) {
     // 402 es la facturacion de Meta pausada, y no se arregla reintentando: hasta
     // que alguien cargue un medio de pago, NINGUN envio pago sale.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mafesoftware/kapso-wa",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "WhatsApp por Kapso (proxy de la Cloud API de Meta). fetch inyectable.",
   "license": "MIT",
   "type": "module",