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

package/src/outbound.ts

@@ -1,390 +0,0 @@
-import type {
-  ResolvedWhatsAppApiAccount,
-  WhatsAppApiSendTextParams,
-} from "./types.js";
-import { readFile } from "node:fs/promises";
-import { mediaKindFromMimeOrName, mimeFromFileName } from "./utils/media/mime.js";
-import { normalizeOutboundPayload } from "./utils/outbound/payload.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);
-  }
-}
-
-function readRetryAfterMs(res: Response): number | null {
-  const value = res.headers.get("retry-after");
-  if (!value) {
-    return null;
-  }
-  const seconds = Number(value);
-  if (Number.isFinite(seconds) && seconds > 0) {
-    return Math.ceil(seconds * 1000);
-  }
-  return null;
-}
-
-function resolveGraphAuth(account: ResolvedWhatsAppApiAccount): { phoneNumberId: string; accessToken: string } {
-  const phoneNumberId = account.outboundPhoneNumberId?.trim();
-  const accessToken = account.outboundAccessToken?.trim();
-  if (!phoneNumberId || !accessToken) {
-    throw new Error("Missing outboundPhoneNumberId/outboundAccessToken in whatsapp-api account config");
-  }
-  return { phoneNumberId, accessToken };
-}
-
-async function sendWithRetry(params: {
-  endpoint: string;
-  account: ResolvedWhatsAppApiAccount;
-  accessToken: string;
-  payload: Record<string, unknown>;
-}): Promise<string> {
-  let lastErr: unknown = null;
-  const maxAttempts = Math.max(1, params.account.maxRetries + 1);
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    try {
-      const res = await withTimeout(
-        params.endpoint,
-        {
-          method: "POST",
-          headers: {
-            authorization: `Bearer ${params.accessToken}`,
-            "content-type": "application/json",
-          },
-          body: JSON.stringify(params.payload),
-        },
-        params.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;
-        const retryAfterMs = readRetryAfterMs(res);
-        if (attempt < maxAttempts) {
-          await sleep(retryAfterMs ?? params.account.retryBackoffMs * attempt);
-        }
-        continue;
-      }
-      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(params.account.retryBackoffMs * attempt);
-      continue;
-    }
-  }
-
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
-}
-
-async function uploadMediaFromLocalPath(params: {
-  endpoint: string;
-  account: ResolvedWhatsAppApiAccount;
-  accessToken: string;
-  localPath: string;
-  kind: "image" | "video" | "audio" | "document";
-}): Promise<{ id: string; mimeType?: string }> {
-  const bytes = await readFile(params.localPath);
-  if (bytes.byteLength > params.account.mediaMaxBytes) {
-    throw new Error(
-      `Local media exceeds mediaMaxBytes (${bytes.byteLength} > ${params.account.mediaMaxBytes})`,
-    );
-  }
-  const fileName = params.localPath.split("/").pop() ?? "media.bin";
-  const mimeType = mimeFromFileName(fileName);
-  const uploadEndpoint = params.endpoint.replace(/\/messages$/, "/media");
-  const maxAttempts = Math.max(1, params.account.maxRetries + 1);
-  let lastErr: unknown = null;
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    try {
-      const form = new FormData();
-      form.append("messaging_product", "whatsapp");
-      form.append("type", mimeType ?? "application/octet-stream");
-      form.append(
-        "file",
-        new Blob([bytes], { type: mimeType ?? "application/octet-stream" }),
-        fileName,
-      );
-      const res = await withTimeout(
-        uploadEndpoint,
-        {
-          method: "POST",
-          headers: {
-            authorization: `Bearer ${params.accessToken}`,
-          },
-          body: form,
-        },
-        params.account.requestTimeoutMs,
-      );
-      const bodyText = await res.text();
-      if (!res.ok) {
-        const err = new Error(`Meta media upload failed: HTTP ${res.status} ${bodyText}`);
-        if (!isRetryableStatus(res.status)) {
-          throw err;
-        }
-        lastErr = err;
-      } else {
-        const parsed = JSON.parse(bodyText) as { id?: string };
-        if (!parsed.id?.trim()) {
-          throw new Error("Meta media upload did not return media id");
-        }
-        return { id: parsed.id.trim(), mimeType };
-      }
-    } catch (err) {
-      lastErr = err;
-    }
-    if (attempt < maxAttempts) {
-      await sleep(params.account.retryBackoffMs * attempt);
-    }
-  }
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown media upload error"));
-}
-
-function isLocalMediaPath(value: string): boolean {
-  return value.startsWith("/") || value.toLowerCase().startsWith("file://");
-}
-
-function toLocalPath(value: string): string {
-  if (value.toLowerCase().startsWith("file://")) {
-    return decodeURIComponent(value.replace(/^file:\/\//i, ""));
-  }
-  return value;
-}
-
-async function sendWhatsAppApiMedia(params: {
-  to: string;
-  text?: string;
-  mediaUrl: string;
-  account: ResolvedWhatsAppApiAccount;
-}): Promise<string> {
-  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
-  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
-  const kind = mediaKindFromMimeOrName({ fileNameOrUrl: params.mediaUrl });
-
-  let mediaPayload: Record<string, unknown>;
-  if (isLocalMediaPath(params.mediaUrl)) {
-    const localPath = toLocalPath(params.mediaUrl);
-    const uploaded = await uploadMediaFromLocalPath({
-      endpoint,
-      account: params.account,
-      accessToken,
-      localPath,
-      kind,
-    });
-    mediaPayload =
-      kind === "document"
-        ? { id: uploaded.id, filename: localPath.split("/").pop() ?? "document" }
-        : { id: uploaded.id };
-  } else {
-    mediaPayload =
-      kind === "document"
-        ? { link: params.mediaUrl, filename: params.mediaUrl.split("/").pop() ?? "document" }
-        : { link: params.mediaUrl };
-  }
-  if (params.text && (kind === "image" || kind === "video" || kind === "document")) {
-    mediaPayload.caption = params.text;
-  }
-
-  return await sendWithRetry({
-    endpoint,
-    account: params.account,
-    accessToken,
-    payload: {
-      messaging_product: "whatsapp",
-      to: normalizeRecipient(params.to),
-      type: kind,
-      [kind]: mediaPayload,
-    },
-  });
-}
-
-async function sendWhatsAppApiLocation(params: {
-  to: string;
-  location: {
-    latitude: number;
-    longitude: number;
-    name?: string;
-    address?: string;
-  };
-  account: ResolvedWhatsAppApiAccount;
-}): Promise<string> {
-  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
-  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
-  return await sendWithRetry({
-    endpoint,
-    account: params.account,
-    accessToken,
-    payload: {
-      messaging_product: "whatsapp",
-      to: normalizeRecipient(params.to),
-      type: "location",
-      location: {
-        latitude: params.location.latitude,
-        longitude: params.location.longitude,
-        name: params.location.name,
-        address: params.location.address,
-      },
-    },
-  });
-}
-
-async function sendWhatsAppApiContacts(params: {
-  to: string;
-  contacts: Array<{
-    name: {
-      formatted_name: string;
-      first_name?: string;
-      last_name?: string;
-    };
-    phones?: Array<{
-      phone: string;
-      type?: string;
-      wa_id?: string;
-    }>;
-  }>;
-  account: ResolvedWhatsAppApiAccount;
-}): Promise<string> {
-  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
-  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
-  return await sendWithRetry({
-    endpoint,
-    account: params.account,
-    accessToken,
-    payload: {
-      messaging_product: "whatsapp",
-      to: normalizeRecipient(params.to),
-      type: "contacts",
-      contacts: params.contacts,
-    },
-  });
-}
-
-export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Promise<string> {
-  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
-
-  const recipient = normalizeRecipient(params.to);
-  if (!recipient) {
-    throw new Error("Recipient id is empty");
-  }
-
-  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
-  const payload = {
-    messaging_product: "whatsapp",
-    to: recipient,
-    type: "text",
-    text: { body: params.text },
-  };
-
-  return await sendWithRetry({
-    endpoint,
-    account: params.account,
-    accessToken,
-    payload,
-  });
-}
-
-export function normalizeReplyText(payload: unknown): string {
-  return normalizeOutboundPayload(payload).text;
-}
-
-export async function sendWhatsAppApiReplyPayload(params: {
-  to: string;
-  payload: unknown;
-  account: ResolvedWhatsAppApiAccount;
-}): Promise<string[]> {
-  const normalized = normalizeOutboundPayload(params.payload);
-  if (
-    !normalized.text &&
-    normalized.mediaUrls.length === 0 &&
-    !normalized.location &&
-    normalized.contacts.length === 0
-  ) {
-    return [];
-  }
-  if (
-    normalized.mediaUrls.length === 0 &&
-    !normalized.location &&
-    normalized.contacts.length === 0
-  ) {
-    return [await sendWhatsAppApiText({ to: params.to, text: normalized.text, account: params.account })];
-  }
-
-  const sentIds: string[] = [];
-  if (normalized.text && normalized.mediaUrls.length === 0) {
-    sentIds.push(await sendWhatsAppApiText({ to: params.to, text: normalized.text, account: params.account }));
-  }
-
-  for (const [index, mediaUrl] of normalized.mediaUrls.entries()) {
-    const messageId = await sendWhatsAppApiMedia({
-      to: params.to,
-      mediaUrl,
-      text: index === 0 ? normalized.text : undefined,
-      account: params.account,
-    });
-    sentIds.push(messageId);
-  }
-
-  if (normalized.location) {
-    sentIds.push(
-      await sendWhatsAppApiLocation({
-        to: params.to,
-        location: normalized.location,
-        account: params.account,
-      }),
-    );
-  }
-
-  if (normalized.contacts.length > 0) {
-    sentIds.push(
-      await sendWhatsAppApiContacts({
-        to: params.to,
-        contacts: normalized.contacts,
-        account: params.account,
-      }),
-    );
-  }
-
-  return sentIds;
-}

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

package/src/types.ts

@@ -1,61 +0,0 @@
-export type ResolvedWhatsAppApiAccount = {
-  accountId: string;
-  enabled: boolean;
-  webhookPath: string;
-  inboundSharedSecret?: string;
-  inboundAccessToken?: string;
-  outboundPhoneNumberId?: string;
-  outboundAccessToken?: string;
-  outboundApiVersion: string;
-  requestTimeoutMs: number;
-  maxRetries: number;
-  retryBackoffMs: number;
-  dedupeTtlMs: number;
-  maxBodyBytes: number;
-  mediaMaxBytes: number;
-  mediaRequestTimeoutMs: number;
-  mediaTempDir?: string;
-};
-
-export type WhatsAppApiInboundMedia = {
-  id: string;
-  kind: "image" | "video" | "audio" | "document" | "sticker";
-  mimeType?: string;
-  fileName?: string;
-};
-
-export type WhatsAppApiInboundLocation = {
-  latitude: number;
-  longitude: number;
-  name?: string;
-  address?: string;
-  url?: string;
-};
-
-export type WhatsAppApiInboundContact = {
-  name?: string;
-  phones: string[];
-};
-
-export type WhatsAppApiInboundMessage = {
-  accountId: string;
-  from: string;
-  to: string;
-  messageId: string;
-  text: string;
-  chatType: "direct";
-  timestamp?: number;
-  senderName?: string;
-  replyToId?: string;
-  replyToBody?: string;
-  replyToSender?: string;
-  media?: WhatsAppApiInboundMedia;
-  location?: WhatsAppApiInboundLocation;
-  contacts?: WhatsAppApiInboundContact[];
-};
-
-export type WhatsAppApiSendTextParams = {
-  to: string;
-  text: string;
-  account: ResolvedWhatsAppApiAccount;
-};

package/src/utils/common.ts

@@ -1,19 +0,0 @@
-export function asRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as Record<string, unknown>;
-}
-
-export function asArray(value: unknown): unknown[] {
-  return Array.isArray(value) ? value : [];
-}
-
-export function asTrimmedString(value: unknown): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed || undefined;
-}
-

package/src/utils/media/inbound.ts

@@ -1,164 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { tmpdir } from "node:os";
-import type { ResolvedWhatsAppApiAccount, WhatsAppApiInboundMessage } from "../../types.js";
-import { asRecord } from "../common.js";
-import { extensionFromMime } from "./mime.js";
-
-type LogLike = {
-  warn?: (message: string) => void;
-};
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-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);
-  }
-}
-
-async function fetchWithRetry(params: {
-  account: ResolvedWhatsAppApiAccount;
-  url: string;
-  init: RequestInit;
-}): Promise<Response> {
-  const maxAttempts = Math.max(1, params.account.maxRetries + 1);
-  let lastErr: unknown = null;
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    try {
-      const res = await withTimeout(
-        params.url,
-        params.init,
-        Math.max(500, params.account.mediaRequestTimeoutMs),
-      );
-      if (res.ok) {
-        return res;
-      }
-      const body = await res.text();
-      const err = new Error(`HTTP ${res.status} ${body}`);
-      if (!isRetryableStatus(res.status)) {
-        throw err;
-      }
-      lastErr = err;
-    } catch (err) {
-      lastErr = err;
-    }
-    if (attempt < maxAttempts) {
-      await sleep(params.account.retryBackoffMs * attempt);
-    }
-  }
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown media error"));
-}
-
-function resolveAccessToken(account: ResolvedWhatsAppApiAccount): string {
-  const token = account.inboundAccessToken?.trim() ?? account.outboundAccessToken?.trim();
-  if (!token) {
-    throw new Error("Missing inboundAccessToken/outboundAccessToken for media download");
-  }
-  return token;
-}
-
-function resolveMediaStorageDir(account: ResolvedWhatsAppApiAccount): string {
-  const root = account.mediaTempDir?.trim() || path.join(tmpdir(), "openclaw-whatsapp-api-media");
-  return path.join(root, account.accountId);
-}
-
-function sanitizeFileName(base: string): string {
-  return base.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-
-export async function downloadInboundMediaAttachment(params: {
-  account: ResolvedWhatsAppApiAccount;
-  message: WhatsAppApiInboundMessage;
-  log?: LogLike;
-}): Promise<{ mediaPath?: string; mediaType?: string }> {
-  try {
-    const media = params.message.media;
-    if (!media?.id) {
-      return {};
-    }
-
-    const token = resolveAccessToken(params.account);
-    const mediaInfoEndpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${media.id}`;
-    let mediaInfoRes: Response;
-    try {
-      mediaInfoRes = await fetchWithRetry({
-        account: params.account,
-        url: mediaInfoEndpoint,
-        init: {
-          method: "GET",
-          headers: {
-            authorization: `Bearer ${token}`,
-          },
-        },
-      });
-    } catch (err) {
-      params.log?.warn?.(`[whatsapp-api] media metadata fetch failed for mediaId=${media.id}: ${String(err)}`);
-      return {};
-    }
-
-    const metaRaw = (await mediaInfoRes.json()) as unknown;
-    const meta = asRecord(metaRaw);
-    const mediaUrl = typeof meta?.url === "string" ? meta.url.trim() : "";
-    if (!mediaUrl) {
-      params.log?.warn?.(`[whatsapp-api] media metadata missing URL for mediaId=${media.id}`);
-      return {};
-    }
-    const mediaType =
-      (typeof meta?.mime_type === "string" && meta.mime_type.trim()) || media.mimeType || undefined;
-
-    let mediaRes: Response;
-    try {
-      mediaRes = await fetchWithRetry({
-        account: params.account,
-        url: mediaUrl,
-        init: {
-          method: "GET",
-          headers: {
-            authorization: `Bearer ${token}`,
-          },
-        },
-      });
-    } catch (err) {
-      params.log?.warn?.(`[whatsapp-api] media download failed for mediaId=${media.id}: ${String(err)}`);
-      return {};
-    }
-
-    const bytes = new Uint8Array(await mediaRes.arrayBuffer());
-    if (bytes.byteLength > params.account.mediaMaxBytes) {
-      params.log?.warn?.(
-        `[whatsapp-api] media too large for mediaId=${media.id}: ${bytes.byteLength} > ${params.account.mediaMaxBytes}`,
-      );
-      return {};
-    }
-
-    const dir = resolveMediaStorageDir(params.account);
-    await mkdir(dir, { recursive: true });
-    const extension = extensionFromMime(mediaType);
-    const baseName = sanitizeFileName(media.fileName || `${media.kind}-${media.id}${extension}`);
-    const filePath = path.join(dir, `${Date.now()}-${baseName}`);
-    await writeFile(filePath, bytes);
-    return {
-      mediaPath: filePath,
-      mediaType,
-    };
-  } catch (err) {
-    params.log?.warn?.(
-      `[whatsapp-api] media attachment resolution failed for messageId=${params.message.messageId}: ${String(err)}`,
-    );
-    return {};
-  }
-}