@johpaz/hive-sdk 0.4.7 → 0.4.8

package/packages/core/src/channels/whatsapp-cloud/channel.ts

@@ -0,0 +1,334 @@
+/**
+ * Canal de WhatsApp por la API oficial de Meta (Cloud API).
+ *
+ * Es el camino para empresas: número de WhatsApp Business propio, plantillas de
+ * marketing y atribución de los anuncios que abren una conversación. El otro
+ * canal de WhatsApp del SDK (`whatsapp`, con Baileys y código QR) no es oficial
+ * y sirve para uso personal, no para un negocio.
+ *
+ * A diferencia de los demás canales, este no abre ninguna conexión: Meta empuja
+ * los mensajes a una URL pública. Quien hospeda el canal tiene que enrutarle las
+ * peticiones a `handleWebhook()`; el gateway del SDK ya lo hace en
+ * `/webhooks/whatsapp-cloud/:accountId`.
+ */
+
+import { BaseChannel, type ChannelConfig, type IncomingMessage, type OutboundMessage } from "../base.ts";
+import { logger } from "../../utils/logger.ts";
+import { updateDoc } from "../../storage/hive.ts";
+import type { ChannelDoc } from "../../storage/collections.ts";
+import {
+  CUSTOMER_WINDOW_MS,
+  WhatsAppCloudClient,
+  WhatsAppCloudError,
+  type WhatsAppTemplate,
+} from "./client.ts";
+import {
+  parseWebhook,
+  safeTokenEquals,
+  verifyChallenge,
+  verifySignature,
+  type WhatsAppInbound,
+} from "./webhook.ts";
+
+/** Cuántos ids de mensaje se recuerdan para descartar los reintentos de Meta. */
+const SEEN_LIMIT = 1000;
+
+export interface WhatsAppCloudConfig extends ChannelConfig {
+  accountId: string;
+  /** Id del número en Meta (no el número en sí). */
+  phoneNumberId: string;
+  /** Token permanente, normalmente de un usuario del sistema. */
+  accessToken: string;
+  /** Secreto de la app de Meta, con el que se firma cada webhook. */
+  appSecret: string;
+  /** El token que uno inventa y pega en el panel de Meta al registrar la URL. */
+  verifyToken: string;
+  graphVersion?: string;
+  /**
+   * Mandar la narración intermedia del agente como mensajes sueltos.
+   *
+   * Apagado a propósito: desde el 1/10/2026 Meta cobra cada mensaje de servicio
+   * dentro de la ventana, así que narrar el progreso sale caro. En su lugar se
+   * renueva el "escribiendo…", que no cuesta nada.
+   */
+  sendProgress?: boolean;
+  /** Plantilla aprobada para hablarle a alguien fuera de la ventana de 24 h. */
+  windowFallbackTemplate?: WhatsAppTemplate;
+  /** Inyectable para tests o para salir por un proxy. */
+  fetch?: typeof fetch;
+}
+
+export interface WhatsAppCloudState {
+  status: "disconnected" | "pending_verification" | "connected" | "error";
+  phoneNumberId: string;
+  lastWebhookAt?: number;
+  error?: string;
+}
+
+export class WhatsAppCloudChannel extends BaseChannel {
+  name = "whatsapp_cloud";
+  accountId: string;
+  config: WhatsAppCloudConfig;
+
+  readonly client: WhatsAppCloudClient;
+
+  private state: WhatsAppCloudState;
+  private log = logger.child("whatsapp-cloud");
+  /** Último mensaje entrante por sesión: abre la ventana y da el id para el "escribiendo…". */
+  private lastInbound: Map<string, { at: number; messageId: string }> = new Map();
+  private seen: Set<string> = new Set();
+
+  constructor(config: WhatsAppCloudConfig) {
+    super();
+    this.config = config;
+    this.accountId = config.accountId;
+    this.client = new WhatsAppCloudClient({
+      phoneNumberId: config.phoneNumberId,
+      accessToken: config.accessToken,
+      graphVersion: config.graphVersion,
+      fetch: config.fetch,
+    });
+    this.state = { status: "disconnected", phoneNumberId: config.phoneNumberId };
+  }
+
+  /** La ruta que hay que registrar en el panel de Meta, detrás de HTTPS público. */
+  get webhookPath(): string {
+    return `/webhooks/whatsapp-cloud/${this.accountId}`;
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+    // No hay nada que conectar: queda esperando el webhook. Hasta que Meta haga
+    // su verificación, el canal está dado de alta pero no recibe nada.
+    this.state.status = this.state.lastWebhookAt ? "connected" : "pending_verification";
+    this.log.info(`Canal listo — registrá ${this.webhookPath} en la app de Meta`);
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    this.state.status = "disconnected";
+    this.log.info("Canal detenido");
+  }
+
+  /**
+   * Atiende una petición de Meta: la verificación inicial y cada mensaje.
+   *
+   * Responde 200 en cuanto el evento es válido, sin esperar el turno del
+   * agente: Meta reintenta lo que tarde y termina desuscribiendo la app.
+   */
+  async handleWebhook(req: Request): Promise<Response> {
+    if (req.method === "GET") {
+      const challenge = verifyChallenge(new URL(req.url).searchParams, (token) =>
+        safeTokenEquals(token, this.config.verifyToken)
+      );
+      if (!challenge) {
+        this.log.warn("verificación rechazada: token incorrecto");
+        return new Response("Verification failed", { status: 403 });
+      }
+      await this.setStatus("connected");
+      return new Response(challenge, { status: 200 });
+    }
+
+    if (req.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+
+    const rawBody = await req.text();
+    if (!verifySignature(rawBody, req.headers.get("x-hub-signature-256"), this.config.appSecret)) {
+      this.log.warn("firma HMAC inválida — evento descartado");
+      return new Response("Invalid signature", { status: 401 });
+    }
+
+    let body: unknown;
+    try {
+      body = JSON.parse(rawBody);
+    } catch {
+      return new Response("Invalid JSON", { status: 400 });
+    }
+
+    this.state.lastWebhookAt = Date.now();
+    if (this.state.status !== "connected") await this.setStatus("connected");
+
+    for (const event of parseWebhook(body)) {
+      // Un mismo WABA puede tener varios números apuntando a la misma URL.
+      if (event.phoneNumberId !== this.config.phoneNumberId) continue;
+
+      for (const message of event.messages) {
+        void this.ingest(message).catch((error) =>
+          this.log.error(`no se pudo procesar ${message.id}: ${(error as Error).message}`)
+        );
+      }
+    }
+
+    return new Response("EVENT_RECEIVED", { status: 200 });
+  }
+
+  async send(sessionId: string, message: OutboundMessage): Promise<void> {
+    const isInterim = message.type === "progress";
+    if (isInterim && !this.config.sendProgress) {
+      // La narración no se manda: cada mensaje intermedio se cobra. El
+      // "escribiendo…" cuenta lo mismo y es gratis.
+      await this.startTyping(sessionId).catch(() => {});
+      return;
+    }
+
+    const text = message.content ?? message.chunk ?? "";
+    if (!text) return;
+
+    const to = this.toRecipient(sessionId);
+    const last = this.lastInbound.get(sessionId);
+    const expired = last ? Date.now() - last.at >= CUSTOMER_WINDOW_MS : false;
+
+    // Sin registro de entrante (por ejemplo tras un reinicio) se intenta igual:
+    // la ventana puede estar abierta y quien manda la última palabra es Meta.
+    if (!expired) {
+      try {
+        await this.client.sendText(to, text);
+        return;
+      } catch (error) {
+        if (!(error instanceof WhatsAppCloudError) || !error.windowClosed) throw error;
+        this.log.info(`ventana cerrada para ${to} según Meta`);
+      }
+    }
+
+    await this.sendOutsideWindow(to, text);
+  }
+
+  async sendAudio(sessionId: string, audio: Buffer, mimeType: string): Promise<void> {
+    await this.client.sendAudio(this.toRecipient(sessionId), audio, mimeType);
+  }
+
+  /** Muestra "escribiendo…". Meta lo apaga al responder o a los 25 segundos. */
+  async startTyping(sessionId: string): Promise<void> {
+    const last = this.lastInbound.get(sessionId);
+    if (!last) return;
+    await this.client.markRead(last.messageId, { typing: true }).catch(() => {});
+  }
+
+  /** No hace falta apagarlo: responder ya lo apaga. */
+  async stopTyping(_sessionId: string): Promise<void> {}
+
+  async markAsRead(sessionId: string, messageId?: string): Promise<void> {
+    const id = messageId ?? this.lastInbound.get(sessionId)?.messageId;
+    if (!id) return;
+    await this.client.markRead(id).catch(() => {});
+  }
+
+  getState(): WhatsAppCloudState {
+    return { ...this.state };
+  }
+
+  getConfig(): WhatsAppCloudConfig {
+    return { ...this.config };
+  }
+
+  private async ingest(message: WhatsAppInbound): Promise<void> {
+    if (!message.id || this.seen.has(message.id)) return;
+    this.remember(message.id);
+
+    if (!this.isUserAllowed(message.from)) {
+      this.log.info(`mensaje descartado, ${message.from} no está en la lista permitida`);
+      return;
+    }
+
+    const sessionId = this.formatSessionId(message.from, "direct");
+    this.lastInbound.set(sessionId, { at: Date.now(), messageId: message.id });
+
+    const incoming: IncomingMessage = {
+      sessionId,
+      channel: this.name,
+      accountId: this.accountId,
+      peerId: message.from,
+      peerKind: "direct",
+      content: message.text ?? "",
+      metadata: {
+        messageId: message.id,
+        timestamp: message.timestamp,
+        pushName: message.profileName,
+        type: message.type,
+        ...(message.referral ? { referral: message.referral } : {}),
+        ...(message.interactive ? { interactive: message.interactive } : {}),
+      },
+    };
+
+    if (message.media?.id && message.mediaKind) {
+      try {
+        const media = await this.client.downloadMedia(message.media.id);
+        if (message.mediaKind === "audio") {
+          incoming.audio = { buffer: media.buffer, mimeType: media.mimeType };
+          if (!incoming.content) incoming.content = "[Audio message]";
+        } else if (message.mediaKind === "image" || message.mediaKind === "sticker") {
+          incoming.image = {
+            buffer: media.buffer,
+            mimeType: media.mimeType,
+            caption: message.media.caption,
+          };
+        } else if (message.mediaKind === "document") {
+          incoming.document = {
+            buffer: media.buffer,
+            mimeType: media.mimeType,
+            fileName: message.media.fileName ?? media.fileName,
+          };
+        }
+      } catch (error) {
+        this.log.warn(`no se pudo bajar el medio ${message.media.id}: ${(error as Error).message}`);
+      }
+    }
+
+    if (!incoming.content && !incoming.audio && !incoming.image && !incoming.document) {
+      this.log.debug(`mensaje ${message.id} de tipo ${message.type} sin contenido utilizable`);
+      return;
+    }
+
+    // Acuse de recibo inmediato: el doble tilde y el "escribiendo…" son lo que
+    // le dice a la persona que su mensaje llegó, aunque la respuesta demore.
+    void this.client.markRead(message.id, { typing: true }).catch(() => {});
+
+    await this.handleMessage(incoming);
+  }
+
+  private async sendOutsideWindow(to: string, text: string): Promise<void> {
+    const template = this.config.windowFallbackTemplate;
+    if (!template) {
+      throw new WhatsAppCloudError(
+        400,
+        131047,
+        "Pasaron más de 24 h desde el último mensaje del cliente: Meta sólo acepta " +
+          "una plantilla aprobada. Configurá `windowFallbackTemplate` en el canal."
+      );
+    }
+    this.log.info(`fuera de la ventana: se manda la plantilla "${template.name}" en vez del texto`);
+    this.log.debug(`texto no enviado: ${text.slice(0, 120)}`);
+    await this.client.sendTemplate(to, template);
+  }
+
+  /** El sessionId es el `wa_id`; se tolera un prefijo por si alguien lo compone. */
+  private toRecipient(sessionId: string): string {
+    const parts = sessionId.split(":");
+    return (parts[parts.length - 1] ?? "").replace(/\D/g, "");
+  }
+
+  private remember(messageId: string): void {
+    this.seen.add(messageId);
+    if (this.seen.size > SEEN_LIMIT) {
+      const oldest = this.seen.values().next().value;
+      if (oldest) this.seen.delete(oldest);
+    }
+  }
+
+  private async setStatus(status: WhatsAppCloudState["status"]): Promise<void> {
+    this.state.status = status;
+    try {
+      await updateDoc<ChannelDoc>("channels", this.accountId, {
+        status,
+        last_active: Date.now(),
+      });
+    } catch {
+      // Sin base no se pierde nada: el estado en memoria ya quedó bien.
+    }
+  }
+}
+
+export function createWhatsAppCloudChannel(config: WhatsAppCloudConfig): WhatsAppCloudChannel {
+  return new WhatsAppCloudChannel(config);
+}

package/packages/core/src/channels/whatsapp-cloud/client.ts

@@ -0,0 +1,368 @@
+/**
+ * Cliente de la WhatsApp Cloud API — la API oficial de Meta.
+ *
+ * No agrega dependencias: sólo `fetch`. Cada instancia habla por UN número
+ * (`phoneNumberId`), que es la unidad con la que Meta cobra, limita el caudal y
+ * numera los errores.
+ *
+ * Por qué existe acá y no en cada aplicación: la versión del Graph caduca sola.
+ * Meta garantiza unos dos años por versión y después manda las llamadas a la
+ * más vieja que siga viva, sin avisar y cambiando el comportamiento. Teniendo
+ * un único cliente, subir de versión es una línea para todos los consumidores.
+ */
+
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("whatsapp-cloud");
+
+/** Última versión estable del Graph. Se puede pisar con `META_GRAPH_API_VERSION`. */
+export const DEFAULT_GRAPH_VERSION = "v26.0";
+
+/** Meta rechaza cualquier `text.body` de más de 4096 caracteres. */
+export const WHATSAPP_TEXT_LIMIT = 4096;
+
+/** La ventana de atención al cliente: fuera de ella sólo se aceptan plantillas. */
+export const CUSTOMER_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+const RATE_WINDOW_MS = 1000;
+/** Meta acepta del orden de 80 mensajes por segundo por número. */
+const MAX_REQUESTS_PER_WINDOW = 80;
+/** Cuánto se espera como mucho a que se libere un lugar antes de fallar. */
+const MAX_THROTTLE_WAIT_MS = 5000;
+
+export interface WhatsAppCloudClientConfig {
+  phoneNumberId: string;
+  accessToken: string;
+  /** Por defecto `META_GRAPH_API_VERSION`, y si no está, `DEFAULT_GRAPH_VERSION`. */
+  graphVersion?: string;
+  /** Inyectable para tests. */
+  fetch?: typeof fetch;
+}
+
+export interface WhatsAppTemplate {
+  name: string;
+  language?: string;
+  components?: unknown[];
+}
+
+export interface WhatsAppMediaDownload {
+  buffer: Buffer;
+  mimeType: string;
+  fileName?: string;
+}
+
+/**
+ * Un error de la Cloud API con su código de Meta a mano.
+ *
+ * Los códigos importan porque cambian la decisión de quien llama: 131047 no es
+ * un fallo, es "se cerró la ventana de 24 h y hay que mandar una plantilla".
+ */
+export class WhatsAppCloudError extends Error {
+  readonly status: number;
+  readonly code: number;
+  readonly subcode?: number;
+  readonly fbtraceId?: string;
+
+  constructor(
+    status: number,
+    code: number,
+    message: string,
+    extra?: { subcode?: number; fbtraceId?: string }
+  ) {
+    super(message);
+    this.name = "WhatsAppCloudError";
+    this.status = status;
+    this.code = code;
+    this.subcode = extra?.subcode;
+    this.fbtraceId = extra?.fbtraceId;
+  }
+
+  static from(status: number, payload: unknown): WhatsAppCloudError {
+    const error = (payload as { error?: Record<string, unknown> })?.error ?? {};
+    const code = Number(error.code ?? 0);
+    const message = String(error.message ?? `HTTP ${status}`);
+    return new WhatsAppCloudError(status, code, `Meta API error: ${message}`, {
+      subcode: error.error_subcode !== undefined ? Number(error.error_subcode) : undefined,
+      fbtraceId: error.fbtrace_id ? String(error.fbtrace_id) : undefined,
+    });
+  }
+
+  /** 131047: pasaron más de 24 h desde el último mensaje del cliente. */
+  get windowClosed(): boolean {
+    return this.code === 131047;
+  }
+
+  /** 130429: caudal de la app; 131056: demasiados mensajes al mismo destinatario. */
+  get rateLimited(): boolean {
+    return this.code === 130429 || this.code === 131056 || this.status === 429;
+  }
+
+  /** 190: el token expiró o fue revocado. */
+  get tokenExpired(): boolean {
+    return this.code === 190;
+  }
+
+  /** 131026: el destinatario no puede recibir el mensaje. */
+  get undeliverable(): boolean {
+    return this.code === 131026;
+  }
+
+  /** 368: la cuenta de WhatsApp Business está restringida por incumplir la política. */
+  get accountRestricted(): boolean {
+    return this.code === 368;
+  }
+
+  /** Si reintentar tiene sentido. Un 131047 o un 368 no se arreglan reintentando. */
+  get retryable(): boolean {
+    return this.rateLimited || this.status >= 500;
+  }
+}
+
+/**
+ * Parte un texto en trozos que Meta acepte, cortando donde menos se note:
+ * primero entre párrafos, después entre líneas y, sólo si no queda otra, por
+ * el último espacio antes del límite.
+ */
+export function splitWhatsAppText(text: string, limit = WHATSAPP_TEXT_LIMIT): string[] {
+  if (text.length <= limit) return text ? [text] : [];
+
+  const chunks: string[] = [];
+  let pending = "";
+
+  const push = (): void => {
+    const trimmed = pending.trim();
+    if (trimmed) chunks.push(trimmed);
+    pending = "";
+  };
+
+  for (const paragraph of text.split(/\n{2,}/)) {
+    const candidate = pending ? `${pending}\n\n${paragraph}` : paragraph;
+
+    if (candidate.length <= limit) {
+      pending = candidate;
+      continue;
+    }
+
+    push();
+
+    if (paragraph.length <= limit) {
+      pending = paragraph;
+      continue;
+    }
+
+    // Un párrafo solo ya no entra: se parte por líneas, y una línea gigante
+    // (un log, una tabla) por el último espacio antes del límite.
+    for (const line of paragraph.split("\n")) {
+      const withLine = pending ? `${pending}\n${line}` : line;
+      if (withLine.length <= limit) {
+        pending = withLine;
+        continue;
+      }
+      push();
+
+      let rest = line;
+      while (rest.length > limit) {
+        const window = rest.slice(0, limit);
+        const cut = window.lastIndexOf(" ");
+        const at = cut > limit * 0.5 ? cut : limit;
+        chunks.push(rest.slice(0, at).trim());
+        rest = rest.slice(at).trimStart();
+      }
+      pending = rest;
+    }
+  }
+
+  push();
+  return chunks;
+}
+
+export class WhatsAppCloudClient {
+  readonly phoneNumberId: string;
+  readonly graphVersion: string;
+
+  private readonly accessToken: string;
+  // Deliberadamente más laxo que `typeof fetch`: lo que se inyecta en los tests
+  // no implementa extras del runtime como `preconnect`, y acá no hacen falta.
+  private readonly fetchImpl: (input: string, init?: RequestInit) => Promise<Response>;
+  private bucket = { count: 0, resetAt: 0 };
+
+  constructor(config: WhatsAppCloudClientConfig) {
+    this.phoneNumberId = config.phoneNumberId;
+    this.accessToken = config.accessToken;
+    this.graphVersion =
+      config.graphVersion ?? process.env.META_GRAPH_API_VERSION ?? DEFAULT_GRAPH_VERSION;
+    this.fetchImpl = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+
+  /** Manda un texto, partido en varios mensajes si hace falta. Devuelve los ids. */
+  async sendText(to: string, text: string, opts?: { previewUrl?: boolean }): Promise<string[]> {
+    const chunks = splitWhatsAppText(text);
+    const ids: string[] = [];
+
+    // En serie a propósito: en paralelo los mensajes llegarían desordenados.
+    for (const chunk of chunks) {
+      const data = await this.post<{ messages?: { id?: string }[] }>({
+        messaging_product: "whatsapp",
+        recipient_type: "individual",
+        to,
+        type: "text",
+        text: { preview_url: opts?.previewUrl ?? false, body: chunk },
+      });
+      const id = data.messages?.[0]?.id;
+      if (id) ids.push(id);
+    }
+
+    if (chunks.length > 1) {
+      log.debug(`texto de ${text.length} caracteres enviado en ${chunks.length} mensajes`);
+    }
+    return ids;
+  }
+
+  /** Manda una plantilla aprobada: lo único que Meta acepta fuera de la ventana. */
+  async sendTemplate(to: string, template: WhatsAppTemplate): Promise<string> {
+    const data = await this.post<{ messages?: { id?: string }[] }>({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to,
+      type: "template",
+      template: {
+        name: template.name,
+        language: { code: template.language ?? "es" },
+        components: template.components ?? [],
+      },
+    });
+    return data.messages?.[0]?.id ?? "";
+  }
+
+  /** Sube el audio y lo manda como nota de voz. */
+  async sendAudio(to: string, audio: Buffer, mimeType = "audio/ogg"): Promise<string> {
+    const mediaId = await this.uploadMedia(audio, mimeType, "audio.ogg");
+    const data = await this.post<{ messages?: { id?: string }[] }>({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to,
+      type: "audio",
+      audio: { id: mediaId },
+    });
+    return data.messages?.[0]?.id ?? "";
+  }
+
+  /**
+   * Marca el mensaje como leído y, si se pide, muestra "escribiendo…".
+   *
+   * Van juntos en la misma llamada porque así lo define Meta. El indicador se
+   * apaga solo al responder, o a los 25 segundos.
+   */
+  async markRead(messageId: string, opts?: { typing?: boolean }): Promise<void> {
+    await this.post({
+      messaging_product: "whatsapp",
+      status: "read",
+      message_id: messageId,
+      ...(opts?.typing ? { typing_indicator: { type: "text" } } : {}),
+    });
+  }
+
+  /** Sube un archivo y devuelve su id de medio. */
+  async uploadMedia(bytes: Buffer, mimeType: string, fileName = "file"): Promise<string> {
+    await this.throttle();
+
+    const form = new FormData();
+    form.append("messaging_product", "whatsapp");
+    form.append("type", mimeType);
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: mimeType }), fileName);
+
+    const res = await this.fetchImpl(this.url(`${this.phoneNumberId}/media`), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+      body: form,
+    });
+    const data = (await res.json().catch(() => ({}))) as { id?: string };
+    if (!res.ok || !data.id) throw WhatsAppCloudError.from(res.status, data);
+    return data.id;
+  }
+
+  /**
+   * Baja un medio recibido. Son dos pasos: el id da una URL firmada, y esa URL
+   * también exige el token.
+   */
+  async downloadMedia(mediaId: string): Promise<WhatsAppMediaDownload> {
+    await this.throttle();
+    const metaRes = await this.fetchImpl(this.url(mediaId), {
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+    });
+    const meta = (await metaRes.json().catch(() => ({}))) as {
+      url?: string;
+      mime_type?: string;
+      file_name?: string;
+    };
+    if (!metaRes.ok || !meta.url) throw WhatsAppCloudError.from(metaRes.status, meta);
+
+    const fileRes = await this.fetchImpl(meta.url, {
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+    });
+    if (!fileRes.ok) {
+      throw new WhatsAppCloudError(fileRes.status, 0, `No se pudo bajar el medio ${mediaId}`);
+    }
+
+    return {
+      buffer: Buffer.from(await fileRes.arrayBuffer()),
+      mimeType: meta.mime_type ?? "application/octet-stream",
+      fileName: meta.file_name,
+    };
+  }
+
+  private url(path: string): string {
+    return `https://graph.facebook.com/${this.graphVersion}/${path}`;
+  }
+
+  private async post<T = unknown>(body: Record<string, unknown>): Promise<T> {
+    await this.throttle();
+
+    const res = await this.fetchImpl(this.url(`${this.phoneNumberId}/messages`), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    const data = (await res.json().catch(() => ({}))) as T;
+    if (!res.ok) throw WhatsAppCloudError.from(res.status, data);
+    return data;
+  }
+
+  /**
+   * Cupo por número. A diferencia del de hive-cloud, que fallaba al llenarse,
+   * este espera a que se abra la ventana: un texto largo sale en varios
+   * mensajes seguidos y no tiene por qué morir por su propio caudal.
+   */
+  private async throttle(): Promise<void> {
+    const deadline = Date.now() + MAX_THROTTLE_WAIT_MS;
+
+    for (;;) {
+      const now = Date.now();
+      if (now >= this.bucket.resetAt) {
+        this.bucket = { count: 0, resetAt: now + RATE_WINDOW_MS };
+      }
+      if (this.bucket.count < MAX_REQUESTS_PER_WINDOW) {
+        this.bucket.count++;
+        return;
+      }
+      if (now >= deadline) {
+        throw new WhatsAppCloudError(
+          429,
+          130429,
+          `Caudal propio superado para el número ${this.phoneNumberId}`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, this.bucket.resetAt - now));
+    }
+  }
+}
+
+export function createWhatsAppCloudClient(
+  config: WhatsAppCloudClientConfig
+): WhatsAppCloudClient {
+  return new WhatsAppCloudClient(config);
+}

package/packages/core/src/channels/whatsapp-cloud/index.ts

@@ -0,0 +1,3 @@
+export * from "./client.ts";
+export * from "./webhook.ts";
+export * from "./channel.ts";