@johpaz/hive-sdk 0.4.6 → 0.4.8

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";

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

@@ -0,0 +1,235 @@
+/**
+ * Verificación y lectura de los webhooks de la WhatsApp Cloud API.
+ *
+ * Son funciones puras a propósito: quien las usa decide después qué hacer con
+ * el mensaje. El canal del SDK arma un `IncomingMessage`; hive-cloud, que es
+ * multi-inquilino sobre Postgres, arma una conversación, lo ingesta al CRM y lo
+ * mete en su retén. Las dos cosas comparten exactamente esto: comprobar la
+ * firma y entender el payload.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export interface WhatsAppReferral {
+  /** Id del anuncio que originó la conversación (`source_id`). */
+  sourceId?: string;
+  sourceUrl?: string;
+  sourceType?: string;
+  headline?: string;
+  body?: string;
+  /** El identificador de clic que la Conversions API necesita para cerrar el círculo. */
+  ctwaClid?: string;
+}
+
+export interface WhatsAppMediaRef {
+  id: string;
+  mimeType?: string;
+  caption?: string;
+  fileName?: string;
+  /** `true` si es una nota de voz y no un archivo de audio adjunto. */
+  voice?: boolean;
+}
+
+export type WhatsAppMediaKind = "audio" | "image" | "document" | "video" | "sticker";
+
+export interface WhatsAppInbound {
+  id: string;
+  from: string;
+  timestamp?: number;
+  /** `text`, `image`, `audio`, `interactive`, `button`, `location`, … */
+  type: string;
+  text?: string;
+  media?: WhatsAppMediaRef;
+  mediaKind?: WhatsAppMediaKind;
+  /** Respuesta a un botón o a una lista. */
+  interactive?: { id: string; title?: string };
+  referral?: WhatsAppReferral;
+  profileName?: string;
+  /** El mensaje tal como llegó, para lo que este tipo no cubra. */
+  raw: unknown;
+}
+
+export interface WhatsAppStatusEvent {
+  id: string;
+  recipientId: string;
+  /** `sent`, `delivered`, `read`, `failed`. */
+  status: string;
+  timestamp?: number;
+  errors?: { code: number; title?: string }[];
+}
+
+export interface WhatsAppWebhookEvent {
+  phoneNumberId: string;
+  displayPhoneNumber?: string;
+  messages: WhatsAppInbound[];
+  statuses: WhatsAppStatusEvent[];
+}
+
+/**
+ * Comprueba la firma `X-Hub-Signature-256` con el secreto de la app.
+ *
+ * Sin esto, cualquiera que conozca la URL puede inyectar conversaciones.
+ */
+export function verifySignature(
+  rawBody: string,
+  signatureHeader: string | null | undefined,
+  appSecret: string
+): boolean {
+  if (!signatureHeader || !appSecret) return false;
+  const expected = Buffer.from(
+    `sha256=${createHmac("sha256", appSecret).update(rawBody).digest("hex")}`
+  );
+  const actual = Buffer.from(signatureHeader);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+/**
+ * Resuelve el `hub.challenge` que Meta manda al registrar el webhook.
+ *
+ * El token se comprueba con un predicado en vez de compararlo acá porque cada
+ * aplicación lo guarda distinto: el SDK tiene uno por canal, y hive-cloud tiene
+ * un hash por cuenta de cliente y un token en texto plano para el número de
+ * plataforma.
+ */
+export function verifyChallenge(
+  query: URLSearchParams | Record<string, string | undefined>,
+  isValidToken: (token: string) => boolean
+): string | null {
+  const get = (key: string): string | undefined =>
+    query instanceof URLSearchParams ? (query.get(key) ?? undefined) : query[key];
+
+  const mode = get("hub.mode");
+  const token = get("hub.verify_token");
+  const challenge = get("hub.challenge");
+
+  if (mode !== "subscribe" || !token || !challenge) return null;
+  if (!isValidToken(token)) return null;
+  return challenge;
+}
+
+/** Compara dos tokens en texto plano sin filtrar información por el tiempo. */
+export function safeTokenEquals(received: string, expected: string): boolean {
+  const a = Buffer.from(received);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+const MEDIA_KINDS: WhatsAppMediaKind[] = ["audio", "image", "document", "video", "sticker"];
+
+/**
+ * Convierte el payload del webhook en eventos por número.
+ *
+ * Recorre **todas** las `entry` y `changes`: Meta puede agrupar varias
+ * notificaciones en un mismo POST, y quedarse con `entry[0].changes[0]` pierde
+ * mensajes en silencio.
+ */
+export function parseWebhook(body: unknown): WhatsAppWebhookEvent[] {
+  const entries = (body as { entry?: unknown[] })?.entry;
+  if (!Array.isArray(entries)) return [];
+
+  const events: WhatsAppWebhookEvent[] = [];
+
+  for (const entry of entries) {
+    const changes = (entry as { changes?: unknown[] })?.changes;
+    if (!Array.isArray(changes)) continue;
+
+    for (const change of changes) {
+      const typed = change as { field?: string; value?: Record<string, any> };
+      if (typed.field && typed.field !== "messages") continue;
+
+      const value = typed.value;
+      const phoneNumberId = value?.metadata?.phone_number_id;
+      if (!phoneNumberId) continue;
+
+      const contacts: any[] = Array.isArray(value?.contacts) ? value!.contacts : [];
+      const messages: WhatsAppInbound[] = [];
+      const statuses: WhatsAppStatusEvent[] = [];
+
+      for (const msg of Array.isArray(value?.messages) ? value!.messages : []) {
+        messages.push(normalizeMessage(msg, contacts));
+      }
+
+      for (const status of Array.isArray(value?.statuses) ? value!.statuses : []) {
+        statuses.push({
+          id: String(status.id ?? ""),
+          recipientId: String(status.recipient_id ?? ""),
+          status: String(status.status ?? ""),
+          timestamp: status.timestamp ? Number(status.timestamp) : undefined,
+          errors: Array.isArray(status.errors)
+            ? status.errors.map((e: any) => ({ code: Number(e.code), title: e.title }))
+            : undefined,
+        });
+      }
+
+      events.push({
+        phoneNumberId: String(phoneNumberId),
+        displayPhoneNumber: value?.metadata?.display_phone_number,
+        messages,
+        statuses,
+      });
+    }
+  }
+
+  return events;
+}
+
+function normalizeMessage(msg: any, contacts: any[]): WhatsAppInbound {
+  const from = String(msg.from ?? "");
+  const type = String(msg.type ?? "unknown");
+
+  const inbound: WhatsAppInbound = {
+    id: String(msg.id ?? ""),
+    from,
+    timestamp: msg.timestamp ? Number(msg.timestamp) : undefined,
+    type,
+    profileName: contacts.find((c) => c?.wa_id === from)?.profile?.name,
+    raw: msg,
+  };
+
+  if (msg.referral?.source_id || msg.referral?.ctwa_clid) {
+    inbound.referral = {
+      sourceId: msg.referral.source_id ? String(msg.referral.source_id) : undefined,
+      sourceUrl: msg.referral.source_url,
+      sourceType: msg.referral.source_type,
+      headline: msg.referral.headline,
+      body: msg.referral.body,
+      ctwaClid: msg.referral.ctwa_clid ? String(msg.referral.ctwa_clid) : undefined,
+    };
+  }
+
+  if (type === "text") {
+    inbound.text = msg.text?.body ?? "";
+    return inbound;
+  }
+
+  if (MEDIA_KINDS.includes(type as WhatsAppMediaKind)) {
+    const payload = msg[type] ?? {};
+    inbound.mediaKind = type as WhatsAppMediaKind;
+    inbound.media = {
+      id: String(payload.id ?? ""),
+      mimeType: payload.mime_type,
+      caption: payload.caption,
+      fileName: payload.filename,
+      voice: payload.voice === true,
+    };
+    if (payload.caption) inbound.text = payload.caption;
+    return inbound;
+  }
+
+  if (type === "interactive") {
+    const reply = msg.interactive?.button_reply ?? msg.interactive?.list_reply;
+    if (reply) {
+      inbound.interactive = { id: String(reply.id ?? ""), title: reply.title };
+      inbound.text = reply.title ?? reply.id;
+    }
+    return inbound;
+  }
+
+  if (type === "button") {
+    inbound.interactive = { id: String(msg.button?.payload ?? ""), title: msg.button?.text };
+    inbound.text = msg.button?.text ?? msg.button?.payload;
+    return inbound;
+  }
+
+  return inbound;
+}