@laburen/openclaw-plugin-whatsapp-api 0.1.0 → 0.2.0

package/package.json

@@ -1,21 +1,47 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "WhatsApp API channel plugin for OpenClaw",
+  "main": "index.js",
   "files": [
-    "index.ts",
-    "src",
+    "index.js",
+    "index.d.ts",
     "openclaw.plugin.json",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "node --test --import tsx/esm tests/*.test.ts",
+    "lint": "eslint src/ index.ts",
+    "lint:fix": "eslint src/ index.ts --fix"
+  },
   "license": "MIT",
+  "peerDependencies": {
+    "openclaw": ">=2026.3.22"
+  },
   "devDependencies": {
-    "openclaw": "*"
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^9.39.3",
+    "tsdown": "^0.21.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "openclaw": "^2026.3.22"
   },
   "openclaw": {
     "extensions": [
-      "./index.ts"
-    ]
+      "./index.js"
+    ],
+    "channel": {
+      "id": "whatsapp-api",
+      "label": "WhatsApp API",
+      "selectionLabel": "WhatsApp API (Cloud)",
+      "docsPath": "/channels/whatsapp-api",
+      "blurb": "WhatsApp Cloud API channel with router-fed inbound webhook and direct Meta Graph API outbound.",
+      "order": 10
+    }
   }
 }

package/index.ts

@@ -1,16 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { createWhatsAppApiChannel } from "./src/channel.js";
-import { setPluginApi } from "./src/runtime.js";
-
-const plugin = {
-  id: "whatsapp-api",
-  name: "WhatsApp API",
-  description: "WhatsApp API channel plugin with inbound webhook and direct Meta outbound",
-  register(api: OpenClawPluginApi) {
-    setPluginApi(api);
-    api.registerChannel({ plugin: createWhatsAppApiChannel(api) });
-    api.logger.info("[whatsapp-api] plugin registered");
-  },
-};
-
-export default plugin;

package/src/accounts.ts

@@ -1,102 +0,0 @@
-import type { ResolvedWhatsAppApiAccount } from "./types.js";
-
-const CHANNEL_ID = "whatsapp-api";
-const DEFAULT_ACCOUNT_ID = "default";
-const DEFAULT_WEBHOOK_PATH = "/webhook/whatsapp-api";
-const DEFAULT_API_VERSION = "v22.0";
-const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
-const DEFAULT_MAX_RETRIES = 2;
-const DEFAULT_RETRY_BACKOFF_MS = 500;
-const DEFAULT_DEDUPE_TTL_MS = 5 * 60_000;
-const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
-const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
-const DEFAULT_MEDIA_REQUEST_TIMEOUT_MS = 15_000;
-
-function getChannelConfig(cfg: Record<string, unknown>): Record<string, unknown> {
-  const channels = (cfg.channels as Record<string, unknown> | undefined) ?? {};
-  return (channels[CHANNEL_ID] as Record<string, unknown> | undefined) ?? {};
-}
-
-export function listAccountIds(cfg: Record<string, unknown>): string[] {
-  const channelCfg = getChannelConfig(cfg);
-  const ids = new Set<string>();
-  const accounts =
-    (channelCfg.accounts as Record<string, Record<string, unknown>> | undefined) ?? {};
-
-  if (Object.keys(accounts).length > 0) {
-    for (const id of Object.keys(accounts)) {
-      ids.add(id);
-    }
-  } else {
-    ids.add(DEFAULT_ACCOUNT_ID);
-  }
-
-  return [...ids];
-}
-
-export function resolveAccount(
-  cfg: Record<string, unknown>,
-  accountId?: string | null,
-): ResolvedWhatsAppApiAccount {
-  const channelCfg = getChannelConfig(cfg);
-  const id = accountId ?? DEFAULT_ACCOUNT_ID;
-  const accounts =
-    (channelCfg.accounts as Record<string, Record<string, unknown>> | undefined) ?? {};
-  const accountCfg = accounts[id] ?? {};
-
-  return {
-    accountId: id,
-    enabled: (accountCfg.enabled as boolean | undefined) ?? true,
-    webhookPath:
-      (accountCfg.webhookPath as string | undefined) ??
-      (channelCfg.webhookPath as string | undefined) ??
-      DEFAULT_WEBHOOK_PATH,
-    inboundSharedSecret:
-      (accountCfg.inboundSharedSecret as string | undefined) ??
-      (channelCfg.inboundSharedSecret as string | undefined),
-    inboundAccessToken:
-      (accountCfg.inboundAccessToken as string | undefined) ??
-      (channelCfg.inboundAccessToken as string | undefined),
-    outboundPhoneNumberId:
-      (accountCfg.outboundPhoneNumberId as string | undefined) ??
-      (channelCfg.outboundPhoneNumberId as string | undefined),
-    outboundAccessToken:
-      (accountCfg.outboundAccessToken as string | undefined) ??
-      (channelCfg.outboundAccessToken as string | undefined),
-    outboundApiVersion:
-      (accountCfg.outboundApiVersion as string | undefined) ??
-      (channelCfg.outboundApiVersion as string | undefined) ??
-      DEFAULT_API_VERSION,
-    requestTimeoutMs:
-      (accountCfg.requestTimeoutMs as number | undefined) ??
-      (channelCfg.requestTimeoutMs as number | undefined) ??
-      DEFAULT_REQUEST_TIMEOUT_MS,
-    maxRetries:
-      (accountCfg.maxRetries as number | undefined) ??
-      (channelCfg.maxRetries as number | undefined) ??
-      DEFAULT_MAX_RETRIES,
-    retryBackoffMs:
-      (accountCfg.retryBackoffMs as number | undefined) ??
-      (channelCfg.retryBackoffMs as number | undefined) ??
-      DEFAULT_RETRY_BACKOFF_MS,
-    dedupeTtlMs:
-      (accountCfg.dedupeTtlMs as number | undefined) ??
-      (channelCfg.dedupeTtlMs as number | undefined) ??
-      DEFAULT_DEDUPE_TTL_MS,
-    maxBodyBytes:
-      (accountCfg.maxBodyBytes as number | undefined) ??
-      (channelCfg.maxBodyBytes as number | undefined) ??
-      DEFAULT_MAX_BODY_BYTES,
-    mediaMaxBytes:
-      (accountCfg.mediaMaxBytes as number | undefined) ??
-      (channelCfg.mediaMaxBytes as number | undefined) ??
-      DEFAULT_MEDIA_MAX_BYTES,
-    mediaRequestTimeoutMs:
-      (accountCfg.mediaRequestTimeoutMs as number | undefined) ??
-      (channelCfg.mediaRequestTimeoutMs as number | undefined) ??
-      DEFAULT_MEDIA_REQUEST_TIMEOUT_MS,
-    mediaTempDir:
-      (accountCfg.mediaTempDir as string | undefined) ??
-      (channelCfg.mediaTempDir as string | undefined),
-  };
-}

package/src/channel.ts

@@ -1,253 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { listAccountIds, resolveAccount } from "./accounts.js";
-import { sendWhatsAppApiReplyPayload, sendWhatsAppApiText } from "./outbound.js";
-import { getPluginRuntime } from "./runtime.js";
-import { downloadInboundMediaAttachment } from "./utils/media/inbound.js";
-import { handleWhatsAppApiWebhook } from "./webhook.js";
-import type { WhatsAppApiInboundMessage } from "./types.js";
-
-const CHANNEL_ID = "whatsapp-api";
-
-function waitUntilAbort(signal?: AbortSignal, onAbort?: () => void): Promise<void> {
-  return new Promise((resolve) => {
-    const done = () => {
-      onAbort?.();
-      resolve();
-    };
-    if (!signal) {
-      return;
-    }
-    if (signal.aborted) {
-      done();
-      return;
-    }
-    signal.addEventListener("abort", done, { once: true });
-  });
-}
-
-function buildInboundBody(rt: any, message: WhatsAppApiInboundMessage): string {
-  if (typeof rt?.channel?.reply?.formatInboundEnvelope === "function") {
-    return rt.channel.reply.formatInboundEnvelope({
-      channel: "WhatsApp API",
-      from: message.senderName || message.from,
-      timestamp: message.timestamp,
-      body: message.text,
-      chatType: "direct",
-      sender: {
-        name: message.senderName,
-        id: message.from,
-      },
-    });
-  }
-  return message.text;
-}
-
-async function dispatchInboundToAgent(params: {
-  accountId: string;
-  message: WhatsAppApiInboundMessage;
-  log?: { info?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void };
-  onOutbound?: () => void;
-}): Promise<void> {
-  const { accountId, message, log, onOutbound } = params;
-  const rt = getPluginRuntime() as any;
-  const cfg = await rt.config.loadConfig();
-  const account = resolveAccount(cfg, accountId);
-  const route = rt.channel.routing.resolveAgentRoute({
-    cfg,
-    channel: CHANNEL_ID,
-    accountId,
-    peer: {
-      kind: "direct",
-      id: message.from,
-    },
-  });
-  const body = buildInboundBody(rt, message);
-  const to = `whatsapp-api:${message.from}`;
-  const mediaAttachment = await downloadInboundMediaAttachment({
-    account,
-    message,
-    log: params.log,
-  });
-  const ctxPayload = rt.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: message.text,
-    RawBody: message.text,
-    CommandBody: message.text,
-    From: `whatsapp-api:${message.from}`,
-    To: to,
-    SessionKey: route.sessionKey,
-    AccountId: route.accountId,
-    ChatType: "direct",
-    ConversationLabel: message.senderName || message.from,
-    SenderName: message.senderName,
-    SenderId: message.from,
-    Provider: CHANNEL_ID,
-    Surface: CHANNEL_ID,
-    MessageSid: message.messageId,
-    ReplyToId: message.replyToId,
-    ReplyToBody: message.replyToBody,
-    ReplyToSender: message.replyToSender,
-    MediaPath: mediaAttachment.mediaPath,
-    MediaType: mediaAttachment.mediaType,
-    OriginatingChannel: CHANNEL_ID,
-    OriginatingTo: to,
-  });
-
-  await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg,
-    dispatcherOptions: {
-      deliver: async (payload: unknown) => {
-        const account = resolveAccount(cfg, accountId);
-        const sent = await sendWhatsAppApiReplyPayload({
-          to: message.from,
-          payload,
-          account,
-        });
-        if (sent.length === 0) {
-          log?.info?.(
-            `[${CHANNEL_ID}] skipping outbound: reply payload empty for messageId=${message.messageId}`,
-          );
-          return;
-        }
-        log?.info?.(
-          `[${CHANNEL_ID}] sent ${sent.length} outbound message(s) to ${message.from} for inbound=${message.messageId}`,
-        );
-        onOutbound?.();
-      },
-      onError: (err: unknown, info: { kind?: string }) => {
-        log?.error?.(
-          `[${CHANNEL_ID}] ${info?.kind ?? "reply"} dispatch failed for account=${accountId} messageId=${message.messageId}: ${String(err)}`,
-        );
-      },
-    },
-  });
-}
-
-export function createWhatsAppApiChannel(api: OpenClawPluginApi) {
-  return {
-    id: CHANNEL_ID,
-    meta: {
-      id: CHANNEL_ID,
-      label: "WhatsApp API",
-      selectionLabel: "WhatsApp API (Cloud)",
-      detailLabel: "WhatsApp API (Cloud)",
-      docsPath: "/channels/whatsapp-api",
-      blurb: "WhatsApp Cloud API channel with router-fed inbound webhook",
-      order: 5,
-    },
-    capabilities: {
-      chatTypes: ["direct" as const],
-      media: true,
-      threads: false,
-      reactions: false,
-      edit: false,
-      unsend: false,
-      reply: false,
-      effects: false,
-      blockStreaming: false,
-    },
-    config: {
-      listAccountIds: (cfg: Record<string, unknown>) => listAccountIds(cfg),
-      resolveAccount: (cfg: Record<string, unknown>, accountId?: string | null) =>
-        resolveAccount(cfg, accountId),
-      defaultAccountId: () => "default",
-    },
-    outbound: {
-      deliveryMode: "gateway" as const,
-      sendText: async ({
-        to,
-        text,
-        cfg,
-        accountId,
-      }: {
-        to: string;
-        text: string;
-        cfg: Record<string, unknown>;
-        accountId?: string;
-      }) => {
-        const account = resolveAccount(cfg, accountId ?? null);
-        const messageId = await sendWhatsAppApiText({
-          to,
-          text,
-          account,
-        });
-        return {
-          channel: CHANNEL_ID,
-          chatId: to,
-          messageId,
-        };
-      },
-    },
-    gateway: {
-      startAccount: async (ctx: any) => {
-        const account = resolveAccount(ctx.cfg, ctx.accountId);
-
-        if (!account.enabled) {
-          ctx.log?.info?.(`[${CHANNEL_ID}] account ${account.accountId} disabled, skipping route`);
-          return waitUntilAbort(ctx.abortSignal);
-        }
-
-        const routePath = account.webhookPath;
-        ctx.setStatus?.({
-          accountId: account.accountId,
-          running: true,
-          lastStartAt: Date.now(),
-          lastError: null,
-        });
-        api.registerHttpRoute({
-          path: routePath,
-          auth: "plugin",
-          replaceExisting: true,
-          handler: async (req, res) => {
-            return await handleWhatsAppApiWebhook({
-              req,
-              res,
-              account,
-              log: ctx.log,
-              onMessage: async (message) => {
-                ctx.setStatus?.({
-                  accountId: account.accountId,
-                  lastInboundAt: Date.now(),
-                });
-                try {
-                  await dispatchInboundToAgent({
-                    accountId: account.accountId,
-                    message,
-                    log: ctx.log,
-                    onOutbound: () => {
-                      ctx.setStatus?.({
-                        accountId: account.accountId,
-                        lastOutboundAt: Date.now(),
-                      });
-                    },
-                  });
-                } catch (err) {
-                  ctx.setStatus?.({
-                    accountId: account.accountId,
-                    lastError: String(err),
-                  });
-                  throw err;
-                }
-              },
-            });
-          },
-        });
-
-        ctx.log?.info?.(`[${CHANNEL_ID}] registered HTTP route: ${routePath}`);
-
-        return waitUntilAbort(ctx.abortSignal, () => {
-          ctx.log?.info?.(`[${CHANNEL_ID}] stopped account ${account.accountId}`);
-          ctx.setStatus?.({
-            accountId: account.accountId,
-            running: false,
-            lastStopAt: Date.now(),
-          });
-        });
-      },
-      stopAccount: async (ctx: { accountId: string; log?: { info?: (msg: string) => void } }) => {
-        ctx.log?.info?.(`[${CHANNEL_ID}] stopAccount called for ${ctx.accountId}`);
-      },
-    },
-  };
-}

package/src/inbound.ts

@@ -1,233 +0,0 @@
-import type {
-  WhatsAppApiInboundContact,
-  WhatsAppApiInboundLocation,
-  WhatsAppApiInboundMessage,
-} from "./types.js";
-import { asArray, asRecord, asTrimmedString } from "./utils/common.js";
-
-function readTextPayload(msg: Record<string, unknown>): {
-  text: string;
-  media?: WhatsAppApiInboundMessage["media"];
-  location?: WhatsAppApiInboundLocation;
-  contacts?: WhatsAppApiInboundContact[];
-} {
-  const readLocationText = (location: WhatsAppApiInboundLocation): string => {
-    const coord = `${location.latitude.toFixed(6)}, ${location.longitude.toFixed(6)}`;
-    const parts = [location.name, location.address].filter(
-      (value): value is string => typeof value === "string" && Boolean(value.trim()),
-    );
-    const suffix = parts.length > 0 ? `; ${parts.join(" - ")}` : "";
-    return `<location: ${coord}${suffix}>`;
-  };
-
-  const readContactLabel = (contact: WhatsAppApiInboundContact): string | undefined => {
-    const primaryPhone = contact.phones[0];
-    const fields = [contact.name, primaryPhone].filter(
-      (value): value is string => typeof value === "string" && Boolean(value.trim()),
-    );
-    return fields.length > 0 ? fields.join(", ") : undefined;
-  };
-
-  const readContactsText = (contacts: WhatsAppApiInboundContact[]): string => {
-    if (contacts.length === 0) {
-      return "<contacts>";
-    }
-    if (contacts.length === 1) {
-      const label = readContactLabel(contacts[0]);
-      return label ? `<contact: ${label}>` : "<contact>";
-    }
-    const labels = contacts
-      .map((contact) => readContactLabel(contact))
-      .filter((value): value is string => Boolean(value));
-    if (labels.length === 0) {
-      return `<contacts: ${contacts.length} contacts>`;
-    }
-    const shown = labels.slice(0, 3);
-    const remaining = Math.max(contacts.length - shown.length, 0);
-    const suffix = remaining > 0 ? ` (+${remaining} more)` : "";
-    return `<contacts: ${shown.join(", ")}${suffix}>`;
-  };
-
-  const msgType = typeof msg.type === "string" ? msg.type : "";
-  if (msgType === "text") {
-    const text = asRecord(msg.text);
-    return {
-      text: typeof text?.body === "string" ? text.body.trim() : "",
-    };
-  }
-
-  if (
-    msgType === "image" ||
-    msgType === "video" ||
-    msgType === "audio" ||
-    msgType === "document" ||
-    msgType === "sticker"
-  ) {
-    const rawMedia = asRecord(msg[msgType]);
-    const mediaId = asTrimmedString(rawMedia?.id);
-    const mimeType = asTrimmedString(rawMedia?.mime_type);
-    const fileName = asTrimmedString(rawMedia?.filename);
-    const caption = asTrimmedString(rawMedia?.caption);
-    const placeholder = `<media:${msgType}>`;
-    return {
-      text: caption ? `${caption}\n\n${placeholder}` : placeholder,
-      media: mediaId
-        ? {
-            id: mediaId,
-            kind: msgType,
-            mimeType,
-            fileName,
-          }
-        : undefined,
-    };
-  }
-  if (msgType === "location") {
-    const rawLocation = asRecord(msg.location);
-    const latitude = Number(rawLocation?.latitude);
-    const longitude = Number(rawLocation?.longitude);
-    if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
-      return { text: "<location>" };
-    }
-    const location: WhatsAppApiInboundLocation = {
-      latitude,
-      longitude,
-      name: asTrimmedString(rawLocation?.name),
-      address: asTrimmedString(rawLocation?.address),
-      url: asTrimmedString(rawLocation?.url),
-    };
-    return {
-      text: readLocationText(location),
-      location,
-    };
-  }
-  if (msgType === "contacts") {
-    const contacts: WhatsAppApiInboundContact[] = [];
-    for (const contactRaw of asArray(msg.contacts)) {
-      const contact = asRecord(contactRaw);
-      if (!contact) {
-        continue;
-      }
-      const nameRecord = asRecord(contact.name);
-      const name =
-        asTrimmedString(nameRecord?.formatted_name) ??
-        asTrimmedString(nameRecord?.first_name) ??
-        asTrimmedString(nameRecord?.last_name);
-      const phones = asArray(contact.phones)
-        .map((phoneRaw) => asTrimmedString(asRecord(phoneRaw)?.phone))
-        .filter((value): value is string => Boolean(value));
-      contacts.push({ name, phones });
-    }
-    return {
-      text: readContactsText(contacts),
-      contacts,
-    };
-  }
-  if (msgType === "reaction") return { text: "<reaction>" };
-  if (msgType === "button") return { text: "<button>" };
-  if (msgType === "interactive") return { text: "<interactive>" };
-
-  return { text: "" };
-}
-
-export function parseWhatsAppCloudInbound(params: {
-  payload: unknown;
-  accountId: string;
-}): WhatsAppApiInboundMessage[] {
-  const root = asRecord(params.payload);
-  if (!root) {
-    return [];
-  }
-
-  const result: WhatsAppApiInboundMessage[] = [];
-  const entries = asArray(root.entry);
-  for (const entryRaw of entries) {
-    const entry = asRecord(entryRaw);
-    if (!entry) {
-      continue;
-    }
-
-    const changes = asArray(entry.changes);
-    for (const changeRaw of changes) {
-      const change = asRecord(changeRaw);
-      if (!change) {
-        continue;
-      }
-      if (change.field !== "messages") {
-        continue;
-      }
-
-      const value = asRecord(change.value);
-      if (!value) {
-        continue;
-      }
-      const metadata = asRecord(value.metadata) ?? {};
-      const to =
-        (typeof metadata.display_phone_number === "string" &&
-          metadata.display_phone_number.trim()) ||
-        (typeof metadata.phone_number_id === "string" && metadata.phone_number_id.trim()) ||
-        "";
-
-      const contactNames = new Map<string, string>();
-      for (const contactRaw of asArray(value.contacts)) {
-        const contact = asRecord(contactRaw);
-        if (!contact) {
-          continue;
-        }
-        const waId = typeof contact.wa_id === "string" ? contact.wa_id.trim() : "";
-        const profile = asRecord(contact.profile);
-        const name = typeof profile?.name === "string" ? profile.name.trim() : "";
-        if (waId && name) {
-          contactNames.set(waId, name);
-        }
-      }
-
-      const messages = asArray(value.messages);
-      for (const messageRaw of messages) {
-        const msg = asRecord(messageRaw);
-        if (!msg) {
-          continue;
-        }
-        const from = typeof msg.from === "string" ? msg.from.trim() : "";
-        const messageId = typeof msg.id === "string" ? msg.id.trim() : "";
-        if (!from || !messageId) {
-          continue;
-        }
-
-        const parsed = readTextPayload(msg);
-        if (!parsed.text) {
-          continue;
-        }
-
-        const context = asRecord(msg.context);
-        const replyToId = asTrimmedString(context?.id) ?? asTrimmedString(context?.message_id);
-        const replyToSender = asTrimmedString(context?.from);
-        const replyToBody =
-          asTrimmedString(context?.body) ??
-          asTrimmedString(asRecord(context?.text)?.body) ??
-          asTrimmedString(asRecord(context?.quoted_message)?.body);
-        const timestampRaw = typeof msg.timestamp === "string" ? Number(msg.timestamp) : NaN;
-        const timestamp =
-          Number.isFinite(timestampRaw) && timestampRaw > 0 ? timestampRaw * 1000 : undefined;
-
-        result.push({
-          accountId: params.accountId,
-          from,
-          to,
-          messageId,
-          text: parsed.text,
-          chatType: "direct",
-          timestamp,
-          senderName: contactNames.get(from),
-          replyToId,
-          replyToBody,
-          replyToSender,
-          media: parsed.media,
-          location: parsed.location,
-          contacts: parsed.contacts,
-        });
-      }
-    }
-  }
-
-  return result;
-}