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

package/package.json

@@ -1,21 +1,47 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.0.1",
+  "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,86 +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;
-
-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),
-    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,
-  };
-}

package/src/channel.ts

@@ -1,246 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { listAccountIds, resolveAccount } from "./accounts.js";
-import { sendWhatsAppApiText, normalizeReplyText } from "./outbound.js";
-import { getPluginRuntime } from "./runtime.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; 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 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 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,
-    OriginatingChannel: CHANNEL_ID,
-    OriginatingTo: to,
-  });
-
-  await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg,
-    dispatcherOptions: {
-      deliver: async (payload: unknown) => {
-        const text = normalizeReplyText(payload);
-        if (!text) {
-          log?.info?.(
-            `[${CHANNEL_ID}] skipping outbound: reply text empty for messageId=${message.messageId}`,
-          );
-          return;
-        }
-        log?.info?.(
-          `[${CHANNEL_ID}] sending reply to ${message.from}, length=${text.length}`,
-        );
-        const account = resolveAccount(cfg, accountId);
-        const messageId = await sendWhatsAppApiText({
-          to: message.from,
-          text,
-          account,
-        });
-        log?.info?.(
-          `[${CHANNEL_ID}] reply sent to ${message.from}, messageId=${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: false,
-      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,126 +0,0 @@
-import type { WhatsAppApiInboundMessage } from "./types.js";
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as Record<string, unknown>;
-}
-
-function asArray(value: unknown): unknown[] {
-  return Array.isArray(value) ? value : [];
-}
-
-function readTextPayload(msg: Record<string, unknown>): string {
-  const msgType = typeof msg.type === "string" ? msg.type : "";
-  if (msgType === "text") {
-    const text = asRecord(msg.text);
-    return typeof text?.body === "string" ? text.body.trim() : "";
-  }
-
-  if (msgType === "image") return "<media:image>";
-  if (msgType === "video") return "<media:video>";
-  if (msgType === "audio") return "<media:audio>";
-  if (msgType === "document") return "<media:document>";
-  if (msgType === "sticker") return "<media:sticker>";
-  if (msgType === "location") return "<location>";
-  if (msgType === "contacts") return "<contacts>";
-  if (msgType === "reaction") return "<reaction>";
-  if (msgType === "button") return "<button>";
-  if (msgType === "interactive") return "<interactive>";
-
-  return "";
-}
-
-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 text = readTextPayload(msg);
-        if (!text) {
-          continue;
-        }
-
-        const context = asRecord(msg.context);
-        const replyToId = typeof context?.id === "string" ? context.id.trim() : undefined;
-        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,
-          chatType: "direct",
-          timestamp,
-          senderName: contactNames.get(from),
-          replyToId,
-        });
-      }
-    }
-  }
-
-  return result;
-}

package/src/outbound.ts

@@ -1,126 +0,0 @@
-import type {
-  ResolvedWhatsAppApiAccount,
-  WhatsAppApiSendTextParams,
-} from "./types.js";
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function normalizeRecipient(to: string): string {
-  const trimmed = to.trim();
-  if (trimmed.startsWith("+")) {
-    return trimmed.slice(1);
-  }
-  return trimmed;
-}
-
-function readGraphError(bodyText: string): string | null {
-  try {
-    const parsed = JSON.parse(bodyText) as { error?: { message?: string } };
-    return parsed.error?.message ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function isRetryableStatus(status: number): boolean {
-  return status === 429 || status >= 500;
-}
-
-async function withTimeout(input: RequestInfo | URL, init: RequestInit, timeoutMs: number) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(input, {
-      ...init,
-      signal: controller.signal,
-    });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Promise<string> {
-  const account = params.account;
-  const phoneNumberId = account.outboundPhoneNumberId?.trim();
-  const accessToken = account.outboundAccessToken?.trim();
-  if (!phoneNumberId || !accessToken) {
-    throw new Error("Missing outboundPhoneNumberId/outboundAccessToken in whatsapp-api account config");
-  }
-
-  const recipient = normalizeRecipient(params.to);
-  if (!recipient) {
-    throw new Error("Recipient id is empty");
-  }
-
-  const endpoint = `https://graph.facebook.com/${account.outboundApiVersion}/${phoneNumberId}/messages`;
-  const payload = {
-    messaging_product: "whatsapp",
-    to: recipient,
-    type: "text",
-    text: { body: params.text },
-  };
-
-  let lastErr: unknown = null;
-  const maxAttempts = Math.max(1, account.maxRetries + 1);
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    try {
-      const res = await withTimeout(
-        endpoint,
-        {
-          method: "POST",
-          headers: {
-            authorization: `Bearer ${accessToken}`,
-            "content-type": "application/json",
-          },
-          body: JSON.stringify(payload),
-        },
-        account.requestTimeoutMs,
-      );
-      const bodyText = await res.text();
-      if (!res.ok) {
-        const detail = readGraphError(bodyText);
-        const err = new Error(
-          `Meta API send failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`,
-        );
-        if (!isRetryableStatus(res.status)) {
-          throw err;
-        }
-        lastErr = err;
-      } else {
-        const parsed = JSON.parse(bodyText) as { messages?: Array<{ id?: string }> };
-        const messageId = parsed.messages?.[0]?.id;
-        return messageId && messageId.trim() ? messageId.trim() : "unknown";
-      }
-    } catch (err) {
-      lastErr = err;
-      if (attempt >= maxAttempts) {
-        break;
-      }
-      await sleep(account.retryBackoffMs * attempt);
-      continue;
-    }
-
-    if (attempt >= maxAttempts) {
-      break;
-    }
-    await sleep(account.retryBackoffMs * attempt);
-  }
-
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
-}
-
-export function normalizeReplyText(payload: unknown): string {
-  if (!payload || typeof payload !== "object") {
-    return "";
-  }
-  const asRecord = payload as Record<string, unknown>;
-  const candidates = [asRecord.text, asRecord.body];
-  for (const candidate of candidates) {
-    if (typeof candidate === "string" && candidate.trim()) {
-      return candidate.trim();
-    }
-  }
-  return "";
-}

package/src/runtime.ts

@@ -1,18 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-
-let pluginApi: OpenClawPluginApi | null = null;
-
-export function setPluginApi(api: OpenClawPluginApi): void {
-  pluginApi = api;
-}
-
-export function getPluginApi(): OpenClawPluginApi {
-  if (!pluginApi) {
-    throw new Error("whatsapp-api plugin API not initialized");
-  }
-  return pluginApi;
-}
-
-export function getPluginRuntime(): OpenClawPluginApi["runtime"] {
-  return getPluginApi().runtime;
-}