@johpaz/hive-sdk 0.4.7 → 0.4.8

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;
+}

package/packages/core/src/channels/whatsapp.ts

@@ -1,11 +1,7 @@
-import makeWASocket, {
-  DisconnectReason,
-  useMultiFileAuthState,
-  fetchLatestBaileysVersion,
-  downloadMediaMessage,
-  type WASocket,
-  type ConnectionState,
-  type WAMessage,
+import type {
+  WASocket,
+  ConnectionState,
+  WAMessage,
 } from "@whiskeysockets/baileys";
 import type { ChannelConfig, IncomingMessage, OutboundMessage } from "./base.ts";
 import { BaseChannel } from "./base.ts";
@@ -15,18 +11,44 @@ import { homedir } from "node:os";
 import { logger } from "../utils/logger.ts";
 import { updateDoc } from "../storage/hive.ts";
 import type { ChannelDoc } from "../storage/collections.ts";
-// @ts-ignore — no type definitions for qrcode-terminal
-import qrcodeTerminal from "qrcode-terminal";
-
-// Baileys uses the `ws` npm package which triggers "[bun] Warning: ws.WebSocket 'upgrade'
-// event is not implemented in bun" etc. Bun writes these directly to stderr from native
-// code, bypassing process.emitWarning. Patch process.stderr.write to filter them out.
-const _origStderrWrite = process.stderr.write.bind(process.stderr);
-(process.stderr as any).write = function (chunk: string | Buffer, ...args: unknown[]) {
-  const str = typeof chunk === "string" ? chunk : Buffer.isBuffer(chunk) ? chunk.toString() : "";
-  if (str.includes("[bun] Warning:") && str.includes("not implemented in bun")) return true;
-  return _origStderrWrite(chunk, ...(args as any[]));
-};
+
+/**
+ * Baileys se carga recién cuando alguien conecta este canal de verdad.
+ *
+ * Antes se importaba arriba de todo. Como el índice del SDK re-exporta este
+ * archivo, cualquiera que importara `@johpaz/hive-sdk` —hive-cloud, por
+ * ejemplo, que no usa ningún canal del SDK— se traía Baileys entero y, de
+ * paso, el parche de `process.stderr.write` de acá abajo, en cada proceso.
+ * Diferido, quien no usa WhatsApp por código QR no paga nada.
+ */
+let baileys: typeof import("@whiskeysockets/baileys") | null = null;
+
+async function loadBaileys(): Promise<NonNullable<typeof baileys>> {
+  if (!baileys) {
+    filterBunWsWarnings();
+    baileys = await import("@whiskeysockets/baileys");
+  }
+  return baileys;
+}
+
+let stderrFiltered = false;
+
+/**
+ * Baileys usa el paquete `ws`, que dispara "[bun] Warning: ws.WebSocket
+ * 'upgrade' event is not implemented in bun" y parecidos. Bun los escribe
+ * directo a stderr desde código nativo, sin pasar por `process.emitWarning`,
+ * así que la única forma de filtrarlos es envolver `process.stderr.write`.
+ */
+function filterBunWsWarnings(): void {
+  if (stderrFiltered) return;
+  stderrFiltered = true;
+  const original = process.stderr.write.bind(process.stderr);
+  (process.stderr as any).write = function (chunk: string | Buffer, ...args: unknown[]) {
+    const str = typeof chunk === "string" ? chunk : Buffer.isBuffer(chunk) ? chunk.toString() : "";
+    if (str.includes("[bun] Warning:") && str.includes("not implemented in bun")) return true;
+    return original(chunk, ...(args as any[]));
+  };
+}
 
 export interface WhatsAppConfig extends ChannelConfig {
   accountId: string;
@@ -114,6 +136,9 @@ export class WhatsAppChannel extends BaseChannel {
     this.log.info("Connecting to WhatsApp...");
 
     try {
+      const { default: makeWASocket, useMultiFileAuthState, fetchLatestBaileysVersion } =
+        await loadBaileys();
+
       const { state, saveCreds } = await useMultiFileAuthState(this.authPath);
       const { version } = await fetchLatestBaileysVersion();
       this.connectionState.waVersion = version.join(".");
@@ -170,13 +195,13 @@ export class WhatsAppChannel extends BaseChannel {
     if (qr) {
       this.connectionState.status = "qr";
       this.connectionState.qrCode = qr;
-      this.printQR(qr);
+      void this.printQR(qr);
       this.log.info("Scan the QR code above with WhatsApp");
     }
 
     if (connection === "close") {
       const statusCode = (lastDisconnect?.error as { output?: { statusCode: number } })?.output?.statusCode;
-      const shouldReconnect = statusCode !== DisconnectReason.loggedOut;
+      const shouldReconnect = statusCode !== baileys!.DisconnectReason.loggedOut;
 
       this.connectionState.status = "disconnected";
       this.log.warn(`WhatsApp disconnected: ${statusCode}`);
@@ -186,8 +211,8 @@ export class WhatsAppChannel extends BaseChannel {
       } catch { /* ignore DB errors */ }
 
       const needsSessionClear =
-        statusCode === DisconnectReason.loggedOut ||
-        statusCode === DisconnectReason.badSession;
+        statusCode === baileys!.DisconnectReason.loggedOut ||
+        statusCode === baileys!.DisconnectReason.badSession;
       // NOTE: 515 (restartRequired) is sent by WhatsApp AFTER a successful pairing
       // to signal Baileys to reconnect with the new credentials — do NOT clear session.
 
@@ -233,11 +258,16 @@ export class WhatsAppChannel extends BaseChannel {
     return { ...this.connectionState };
   }
 
-  private printQR(qr: string): void {
+  private async printQR(qr: string): Promise<void> {
     this.log.info("\n" + "=".repeat(50));
     this.log.info("  WHATSAPP QR CODE - Scan with your phone");
     this.log.info("=".repeat(50) + "\n");
 
+    // @ts-ignore — no type definitions for qrcode-terminal
+    const qrcodeTerminal = (await import("qrcode-terminal")).default as {
+      generate: (text: string, opts: { small: boolean }, cb: (qr: string) => void) => void;
+    };
+
     qrcodeTerminal.generate(qr, { small: false }, (qrString: string) => {
       this.log.info(qrString);
     });
@@ -307,7 +337,7 @@ export class WhatsAppChannel extends BaseChannel {
 
   if (hasAudio && this.socket) {
     try {
-      audioBuffer = await downloadMediaMessage(
+      audioBuffer = await baileys!.downloadMediaMessage(
         typedMsg as unknown as WAMessage,
         "buffer",
         {},
@@ -320,7 +350,7 @@ export class WhatsAppChannel extends BaseChannel {
 
   if (hasImage && this.socket) {
     try {
-      imageBuffer = await downloadMediaMessage(
+      imageBuffer = await baileys!.downloadMediaMessage(
         typedMsg as unknown as WAMessage,
         "buffer",
         {},
@@ -336,7 +366,7 @@ export class WhatsAppChannel extends BaseChannel {
 
   if (hasDocument && this.socket) {
     try {
-      documentBuffer = await downloadMediaMessage(
+      documentBuffer = await baileys!.downloadMediaMessage(
         typedMsg as unknown as WAMessage,
         "buffer",
         {},

package/packages/core/src/config/loader.ts

@@ -6,7 +6,7 @@ import { availableParallelism, homedir } from "node:os";
 
 const LogLevelSchema = z.enum(["debug", "info", "warn", "error"]);
 const DMPolicySchema = z.enum(["open", "pairing", "allowlist"]);
-const TransportSchema = z.enum(["stdio", "sse", "websocket"]);
+const TransportSchema = z.enum(["stdio", "sse", "websocket", "http"]);
 
 export function loadEnv(hiveDir: string): void {
   const envPath = path.join(hiveDir, ".env");
@@ -559,6 +559,8 @@ function buildDefaultConfig(): Config {
         slack: 40000,
         webchat: 100000,
         whatsapp: 65536,
+        // Meta rechaza cualquier `text.body` de más de 4096 caracteres.
+        whatsapp_cloud: 4096,
       },
       skillScanning: true,
       warnOnInsecureConfig: true,

package/packages/core/src/gateway/server.ts

@@ -5,11 +5,13 @@
  * - POST /chat — chat with an agent
  * - GET /status — health check
  * - WebSocket /ws — real-time streaming
+ * - GET|POST /webhooks/whatsapp-cloud/:accountId — WhatsApp por la API oficial
  */
 
 import { logger } from "../utils/logger.ts";
 import { runAgent } from "../agent/agent-loop.ts";
 import type { MCPClientManager } from "../mcp/index.ts";
+import type { ChannelManager } from "../channels/manager.ts";
 
 const log = logger.child("gateway");
 
@@ -18,6 +20,12 @@ export interface GatewayConfig {
   port?: number;
   agentId?: string;
   mcpManager?: MCPClientManager | null;
+  /**
+   * Hace falta para los canales que reciben por webhook, como WhatsApp por la
+   * API oficial de Meta. Sin él, el gateway no tiene a quién entregarle lo que
+   * Meta empuja.
+   */
+  channelManager?: ChannelManager | null;
 }
 
 export async function startGateway(config: GatewayConfig = {}) {
@@ -54,6 +62,22 @@ export async function startGateway(config: GatewayConfig = {}) {
         return handleChat(req, agentId, config.mcpManager);
       }
 
+      // WhatsApp por la API oficial: Meta empuja acá cada mensaje del número.
+      // El gateway escucha en 127.0.0.1 y Meta exige HTTPS público, así que
+      // esta ruta necesita un proxy inverso o un túnel por delante.
+      const whatsappCloud = url.pathname.match(/^\/webhooks\/whatsapp-cloud\/([^/]+)$/);
+      if (whatsappCloud) {
+        if (!config.channelManager) {
+          log.warn("llegó un webhook de WhatsApp pero el gateway no tiene ChannelManager");
+          return new Response("Channels not configured", { status: 503 });
+        }
+        return config.channelManager.handleWebhook(
+          "whatsapp_cloud",
+          decodeURIComponent(whatsappCloud[1]!),
+          req
+        );
+      }
+
       return new Response("Not Found", { status: 404 });
     },
     websocket: {

package/packages/core/src/index.ts

@@ -84,6 +84,23 @@ export { BaseChannel } from "./channels/base.ts";
 export { TelegramChannel } from "./channels/telegram.ts";
 export { DiscordChannel } from "./channels/discord.ts";
 export { WhatsAppChannel } from "./channels/whatsapp.ts";
+export {
+  WhatsAppCloudChannel,
+  WhatsAppCloudClient,
+  WhatsAppCloudError,
+  splitWhatsAppText,
+  parseWebhook as parseWhatsAppWebhook,
+  verifySignature as verifyWhatsAppSignature,
+  verifyChallenge as verifyWhatsAppChallenge,
+} from "./channels/whatsapp-cloud/index.ts";
+export type {
+  WhatsAppCloudConfig,
+  WhatsAppTemplate,
+  WhatsAppInbound,
+  WhatsAppWebhookEvent,
+  WhatsAppStatusEvent,
+  WhatsAppReferral,
+} from "./channels/whatsapp-cloud/index.ts";
 export { SlackChannel } from "./channels/slack.ts";
 export { WebChatChannel } from "./channels/webchat.ts";
 

package/packages/core/src/mcp/MCPClient.ts

@@ -183,6 +183,15 @@ export class MCPClientManager {
         });
       }
 
+      case "http": {
+        const url = state.config.url;
+        if (!url) throw new Error("Streamable HTTP transport requires 'url' config");
+        return createTransport({
+          type: "http",
+          http: { url, headers: state.config.headers },
+        });
+      }
+
       default:
         throw new Error(`Unknown transport type: ${transportType}`);
     }

package/packages/core/src/mcp/config.ts

@@ -3,7 +3,8 @@ export interface MCPConfig {
 }
 
 export interface MCPServerConfig {
-  transport: "stdio" | "sse" | "websocket";
+  /** "http" es Streamable HTTP, el transporte remoto estándar de MCP. "sse" es el HTTP+SSE original, de dos endpoints. */
+  transport: "stdio" | "sse" | "websocket" | "http";
   enabled?: boolean;
   command?: string;
   args?: string[];

package/packages/core/src/mcp/transports/index.ts

@@ -1,4 +1,5 @@
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 
 // CORRECCIÓN 1 — quitar extensión .ts de los imports
@@ -18,13 +19,37 @@ export interface StdioTransportConfig {
   env?: Record<string, string>;
 }
 
-export type TransportType = "stdio" | "sse" | "websocket";
+/**
+ * Streamable HTTP: el transporte remoto ESTÁNDAR de MCP hoy.
+ *
+ * No es lo mismo que `sse`. Aquel es el transporte HTTP+SSE original, de dos
+ * endpoints (un GET que abre el stream y un POST aparte para enviar), que la
+ * especificación reemplazó por éste: un único endpoint que acepta POST y
+ * devuelve JSON o un stream SSE según haga falta.
+ *
+ * Sin este caso, un servidor MCP remoto moderno es inalcanzable: no expone el
+ * `/sse` de dos endpoints que espera `SSETransport` y la conexión muere en un
+ * 404. Se descubrió intentando conectar un navegador headless que sólo sirve
+ * Streamable HTTP, pero no es un caso particular de ese servidor: es lo que
+ * publica hoy cualquier MCP remoto.
+ */
+export interface HttpTransportConfig {
+  /** URL del endpoint MCP, normalmente terminado en `/mcp`. */
+  url: string;
+  /** Cabeceras extra en cada petición — típicamente la autorización. */
+  headers?: Record<string, string>;
+  /** Sesión previa a reanudar, si el servidor emitió un id de sesión. */
+  sessionId?: string;
+}
+
+export type TransportType = "stdio" | "sse" | "websocket" | "http";
 
 export interface TransportOptions {
   type: TransportType;
   stdio?: StdioTransportConfig;
   sse?: SSETransportConfig;
   websocket?: WebSocketTransportConfig;
+  http?: HttpTransportConfig;
 }
 
 export function createTransport(options: TransportOptions): Transport {
@@ -58,6 +83,24 @@ export function createTransport(options: TransportOptions): Transport {
       return new WebSocketTransport(options.websocket);
     }
 
+    case "http": {
+      if (!options.http) {
+        throw new Error("http config required for Streamable HTTP transport");
+      }
+      // La implementación la pone el SDK oficial de MCP, que ya es dependencia
+      // nuestra: no hay nada que reescribir acá, sólo faltaba el caso.
+      let url: URL;
+      try {
+        url = new URL(options.http.url);
+      } catch {
+        throw new Error(`Invalid MCP endpoint URL: ${options.http.url}`);
+      }
+      return new StreamableHTTPClientTransport(url, {
+        requestInit: options.http.headers ? { headers: options.http.headers } : undefined,
+        sessionId: options.http.sessionId,
+      });
+    }
+
     default: {
       // exhaustive check — TypeScript avisa si falta un caso
       const _exhaustive: never = options.type;