@tencent-weixin/openclaw-weixin 1.0.0

package/src/api/api.ts

@@ -0,0 +1,240 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadConfigRouteTag } from "../auth/accounts.js";
+import { logger } from "../util/logger.js";
+import { redactBody, redactUrl } from "../util/redact.js";
+
+import type {
+  BaseInfo,
+  GetUploadUrlReq,
+  GetUploadUrlResp,
+  GetUpdatesReq,
+  GetUpdatesResp,
+  SendMessageReq,
+  SendTypingReq,
+  GetConfigResp,
+} from "./types.js";
+
+export type WeixinApiOptions = {
+  baseUrl: string;
+  token?: string;
+  timeoutMs?: number;
+  /** Long-poll timeout for getUpdates (server may hold the request up to this). */
+  longPollTimeoutMs?: number;
+};
+
+// ---------------------------------------------------------------------------
+// BaseInfo — attached to every outgoing CGI request
+// ---------------------------------------------------------------------------
+
+function readChannelVersion(): string {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.resolve(dir, "..", "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+const CHANNEL_VERSION = readChannelVersion();
+
+/** Build the `base_info` payload included in every API request. */
+export function buildBaseInfo(): BaseInfo {
+  return { channel_version: CHANNEL_VERSION };
+}
+
+/** Default timeout for long-poll getUpdates requests. */
+const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
+/** Default timeout for regular API requests (sendMessage, getUploadUrl). */
+const DEFAULT_API_TIMEOUT_MS = 15_000;
+/** Default timeout for lightweight API requests (getConfig, sendTyping). */
+const DEFAULT_CONFIG_TIMEOUT_MS = 10_000;
+
+function ensureTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url : `${url}/`;
+}
+
+/** X-WECHAT-UIN header: random uint32 -> decimal string -> base64. */
+function randomWechatUin(): string {
+  const uint32 = crypto.randomBytes(4).readUInt32BE(0);
+  return Buffer.from(String(uint32), "utf-8").toString("base64");
+}
+
+function buildHeaders(opts: { token?: string; body: string }): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    AuthorizationType: "ilink_bot_token",
+    "Content-Length": String(Buffer.byteLength(opts.body, "utf-8")),
+    "X-WECHAT-UIN": randomWechatUin(),
+  };
+  if (opts.token?.trim()) {
+    headers.Authorization = `Bearer ${opts.token.trim()}`;
+  }
+  const routeTag = loadConfigRouteTag();
+  if (routeTag) {
+    headers.SKRouteTag = routeTag;
+  }
+  logger.debug(
+    `requestHeaders: ${JSON.stringify({ ...headers, Authorization: headers.Authorization ? "Bearer ***" : undefined })}`,
+  );
+  return headers;
+}
+
+/**
+ * Common fetch wrapper: POST JSON to a Weixin API endpoint with timeout + abort.
+ * Returns the raw response text on success; throws on HTTP error or timeout.
+ */
+async function apiFetch(params: {
+  baseUrl: string;
+  endpoint: string;
+  body: string;
+  token?: string;
+  timeoutMs: number;
+  label: string;
+}): Promise<string> {
+  const base = ensureTrailingSlash(params.baseUrl);
+  const url = new URL(params.endpoint, base);
+  const hdrs = buildHeaders({ token: params.token, body: params.body });
+  logger.debug(`POST ${redactUrl(url.toString())} body=${redactBody(params.body)}`);
+
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), params.timeoutMs);
+  try {
+    const res = await fetch(url.toString(), {
+      method: "POST",
+      headers: hdrs,
+      body: params.body,
+      signal: controller.signal,
+    });
+    clearTimeout(t);
+    const rawText = await res.text();
+    logger.debug(`${params.label} status=${res.status} raw=${redactBody(rawText)}`);
+    if (!res.ok) {
+      throw new Error(`${params.label} ${res.status}: ${rawText}`);
+    }
+    return rawText;
+  } catch (err) {
+    clearTimeout(t);
+    throw err;
+  }
+}
+
+/**
+ * Long-poll getUpdates. Server should hold the request until new messages or timeout.
+ *
+ * On client-side timeout (no server response within timeoutMs), returns an empty response
+ * with ret=0 so the caller can simply retry. This is normal for long-poll.
+ */
+export async function getUpdates(
+  params: GetUpdatesReq & {
+    baseUrl: string;
+    token?: string;
+    timeoutMs?: number;
+  },
+): Promise<GetUpdatesResp> {
+  const timeout = params.timeoutMs ?? DEFAULT_LONG_POLL_TIMEOUT_MS;
+  try {
+    const rawText = await apiFetch({
+      baseUrl: params.baseUrl,
+      endpoint: "ilink/bot/getupdates",
+      body: JSON.stringify({
+        get_updates_buf: params.get_updates_buf ?? "",
+        base_info: buildBaseInfo(),
+      }),
+      token: params.token,
+      timeoutMs: timeout,
+      label: "getUpdates",
+    });
+    const resp: GetUpdatesResp = JSON.parse(rawText);
+    return resp;
+  } catch (err) {
+    // Long-poll timeout is normal; return empty response so caller can retry
+    if (err instanceof Error && err.name === "AbortError") {
+      logger.debug(`getUpdates: client-side timeout after ${timeout}ms, returning empty response`);
+      return { ret: 0, msgs: [], get_updates_buf: params.get_updates_buf };
+    }
+    throw err;
+  }
+}
+
+/** Get a pre-signed CDN upload URL for a file. */
+export async function getUploadUrl(
+  params: GetUploadUrlReq & WeixinApiOptions,
+): Promise<GetUploadUrlResp> {
+  const rawText = await apiFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/getuploadurl",
+    body: JSON.stringify({
+      filekey: params.filekey,
+      media_type: params.media_type,
+      to_user_id: params.to_user_id,
+      rawsize: params.rawsize,
+      rawfilemd5: params.rawfilemd5,
+      filesize: params.filesize,
+      thumb_rawsize: params.thumb_rawsize,
+      thumb_rawfilemd5: params.thumb_rawfilemd5,
+      thumb_filesize: params.thumb_filesize,
+      no_need_thumb: params.no_need_thumb,
+      aeskey: params.aeskey,
+      base_info: buildBaseInfo(),
+    }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_API_TIMEOUT_MS,
+    label: "getUploadUrl",
+  });
+  const resp: GetUploadUrlResp = JSON.parse(rawText);
+  return resp;
+}
+
+/** Send a single message downstream. */
+export async function sendMessage(
+  params: WeixinApiOptions & { body: SendMessageReq },
+): Promise<void> {
+  await apiFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/sendmessage",
+    body: JSON.stringify({ ...params.body, base_info: buildBaseInfo() }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_API_TIMEOUT_MS,
+    label: "sendMessage",
+  });
+}
+
+/** Fetch bot config (includes typing_ticket) for a given user. */
+export async function getConfig(
+  params: WeixinApiOptions & { ilinkUserId: string; contextToken?: string },
+): Promise<GetConfigResp> {
+  const rawText = await apiFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/getconfig",
+    body: JSON.stringify({
+      ilink_user_id: params.ilinkUserId,
+      context_token: params.contextToken,
+      base_info: buildBaseInfo(),
+    }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
+    label: "getConfig",
+  });
+  const resp: GetConfigResp = JSON.parse(rawText);
+  return resp;
+}
+
+/** Send a typing indicator to a user. */
+export async function sendTyping(
+  params: WeixinApiOptions & { body: SendTypingReq },
+): Promise<void> {
+  await apiFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/sendtyping",
+    body: JSON.stringify({ ...params.body, base_info: buildBaseInfo() }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
+    label: "sendTyping",
+  });
+}

package/src/api/config-cache.ts

@@ -0,0 +1,79 @@
+import { getConfig } from "./api.js";
+
+/** Subset of getConfig fields that we actually need; add new fields here as needed. */
+export interface CachedConfig {
+  typingTicket: string;
+}
+
+const CONFIG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CONFIG_CACHE_INITIAL_RETRY_MS = 2_000;
+const CONFIG_CACHE_MAX_RETRY_MS = 60 * 60 * 1000;
+
+interface ConfigCacheEntry {
+  config: CachedConfig;
+  everSucceeded: boolean;
+  nextFetchAt: number;
+  retryDelayMs: number;
+}
+
+/**
+ * Per-user getConfig cache with periodic random refresh (within 24h) and
+ * exponential-backoff retry (up to 1h) on failure.
+ */
+export class WeixinConfigManager {
+  private cache = new Map<string, ConfigCacheEntry>();
+
+  constructor(
+    private apiOpts: { baseUrl: string; token?: string },
+    private log: (msg: string) => void,
+  ) {}
+
+  async getForUser(userId: string, contextToken?: string): Promise<CachedConfig> {
+    const now = Date.now();
+    const entry = this.cache.get(userId);
+    const shouldFetch = !entry || now >= entry.nextFetchAt;
+
+    if (shouldFetch) {
+      let fetchOk = false;
+      try {
+        const resp = await getConfig({
+          baseUrl: this.apiOpts.baseUrl,
+          token: this.apiOpts.token,
+          ilinkUserId: userId,
+          contextToken,
+        });
+        if (resp.ret === 0) {
+          this.cache.set(userId, {
+            config: { typingTicket: resp.typing_ticket ?? "" },
+            everSucceeded: true,
+            nextFetchAt: now + Math.random() * CONFIG_CACHE_TTL_MS,
+            retryDelayMs: CONFIG_CACHE_INITIAL_RETRY_MS,
+          });
+          this.log(
+            `[weixin] config ${entry?.everSucceeded ? "refreshed" : "cached"} for ${userId}`,
+          );
+          fetchOk = true;
+        }
+      } catch (err) {
+        this.log(`[weixin] getConfig failed for ${userId} (ignored): ${String(err)}`);
+      }
+      if (!fetchOk) {
+        const prevDelay = entry?.retryDelayMs ?? CONFIG_CACHE_INITIAL_RETRY_MS;
+        const nextDelay = Math.min(prevDelay * 2, CONFIG_CACHE_MAX_RETRY_MS);
+        if (entry) {
+          entry.nextFetchAt = now + nextDelay;
+          entry.retryDelayMs = nextDelay;
+        } else {
+          this.cache.set(userId, {
+            config: { typingTicket: "" },
+            everSucceeded: false,
+            nextFetchAt: now + CONFIG_CACHE_INITIAL_RETRY_MS,
+            retryDelayMs: CONFIG_CACHE_INITIAL_RETRY_MS,
+          });
+        }
+      }
+    }
+
+    return this.cache.get(userId)?.config ?? { typingTicket: "" };
+  }
+}

package/src/api/session-guard.ts

@@ -0,0 +1,58 @@
+import { logger } from "../util/logger.js";
+
+const SESSION_PAUSE_DURATION_MS = 60 * 60 * 1000;
+
+/** Error code returned by the server when the bot session has expired. */
+export const SESSION_EXPIRED_ERRCODE = -14;
+
+const pauseUntilMap = new Map<string, number>();
+
+/** Pause all inbound/outbound API calls for `accountId` for one hour. */
+export function pauseSession(accountId: string): void {
+  const until = Date.now() + SESSION_PAUSE_DURATION_MS;
+  pauseUntilMap.set(accountId, until);
+  logger.info(
+    `session-guard: paused accountId=${accountId} until=${new Date(until).toISOString()} (${SESSION_PAUSE_DURATION_MS / 1000}s)`,
+  );
+}
+
+/** Returns `true` when the bot is still within its one-hour cooldown window. */
+export function isSessionPaused(accountId: string): boolean {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return false;
+  if (Date.now() >= until) {
+    pauseUntilMap.delete(accountId);
+    return false;
+  }
+  return true;
+}
+
+/** Milliseconds remaining until the pause expires (0 when not paused). */
+export function getRemainingPauseMs(accountId: string): number {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return 0;
+  const remaining = until - Date.now();
+  if (remaining <= 0) {
+    pauseUntilMap.delete(accountId);
+    return 0;
+  }
+  return remaining;
+}
+
+/** Throw if the session is currently paused. Call before any API request. */
+export function assertSessionActive(accountId: string): void {
+  if (isSessionPaused(accountId)) {
+    const remainingMin = Math.ceil(getRemainingPauseMs(accountId) / 60_000);
+    throw new Error(
+      `session paused for accountId=${accountId}, ${remainingMin} min remaining (errcode ${SESSION_EXPIRED_ERRCODE})`,
+    );
+  }
+}
+
+/**
+ * Reset internal state — only for tests.
+ * @internal
+ */
+export function _resetForTest(): void {
+  pauseUntilMap.clear();
+}

package/src/api/types.ts

@@ -0,0 +1,222 @@
+/**
+ * Weixin protocol types (mirrors proto: GetUpdatesReq/Resp, WeixinMessage, SendMessageReq).
+ * API uses JSON over HTTP; bytes fields are base64 strings in JSON.
+ */
+
+/** Common request metadata attached to every CGI request. */
+export interface BaseInfo {
+  channel_version?: string;
+}
+
+/** proto: UploadMediaType */
+export const UploadMediaType = {
+  IMAGE: 1,
+  VIDEO: 2,
+  FILE: 3,
+  VOICE: 4,
+} as const;
+
+export interface GetUploadUrlReq {
+  filekey?: string;
+  /** proto field 2: media_type, see UploadMediaType */
+  media_type?: number;
+  to_user_id?: string;
+  /** 原文件明文大小 */
+  rawsize?: number;
+  /** 原文件明文 MD5 */
+  rawfilemd5?: string;
+  /** 原文件密文大小（AES-128-ECB 加密后） */
+  filesize?: number;
+  /** 缩略图明文大小（IMAGE/VIDEO 时必填） */
+  thumb_rawsize?: number;
+  /** 缩略图明文 MD5（IMAGE/VIDEO 时必填） */
+  thumb_rawfilemd5?: string;
+  /** 缩略图密文大小（IMAGE/VIDEO 时必填） */
+  thumb_filesize?: number;
+  /** 不需要缩略图上传 URL，默认 false */
+  no_need_thumb?: boolean;
+  /** 加密 key */
+  aeskey?: string;
+}
+
+export interface GetUploadUrlResp {
+  /** 原图上传加密参数 */
+  upload_param?: string;
+  /** 缩略图上传加密参数，无缩略图时为空 */
+  thumb_upload_param?: string;
+}
+
+export const MessageType = {
+  NONE: 0,
+  USER: 1,
+  BOT: 2,
+} as const;
+
+export const MessageItemType = {
+  NONE: 0,
+  TEXT: 1,
+  IMAGE: 2,
+  VOICE: 3,
+  FILE: 4,
+  VIDEO: 5,
+} as const;
+
+export const MessageState = {
+  NEW: 0,
+  GENERATING: 1,
+  FINISH: 2,
+} as const;
+
+export interface TextItem {
+  text?: string;
+}
+
+/** CDN media reference; aes_key is base64-encoded bytes in JSON. */
+export interface CDNMedia {
+  encrypt_query_param?: string;
+  aes_key?: string;
+  /** 加密类型: 0=只加密fileid, 1=打包缩略图/中图等信息 */
+  encrypt_type?: number;
+}
+
+export interface ImageItem {
+  /** 原图 CDN 引用 */
+  media?: CDNMedia;
+  /** 缩略图 CDN 引用 */
+  thumb_media?: CDNMedia;
+  /** Raw AES-128 key as hex string (16 bytes); preferred over media.aes_key for inbound decryption. */
+  aeskey?: string;
+  url?: string;
+  mid_size?: number;
+  thumb_size?: number;
+  thumb_height?: number;
+  thumb_width?: number;
+  hd_size?: number;
+}
+
+export interface VoiceItem {
+  media?: CDNMedia;
+  /** 语音编码类型：1=pcm 2=adpcm 3=feature 4=speex 5=amr 6=silk 7=mp3 8=ogg-speex */
+  encode_type?: number;
+  bits_per_sample?: number;
+  /** 采样率 (Hz) */
+  sample_rate?: number;
+  /** 语音长度 (毫秒) */
+  playtime?: number;
+  /** 语音转文字内容 */
+  text?: string;
+}
+
+export interface FileItem {
+  media?: CDNMedia;
+  file_name?: string;
+  md5?: string;
+  len?: string;
+}
+
+export interface VideoItem {
+  media?: CDNMedia;
+  video_size?: number;
+  play_length?: number;
+  video_md5?: string;
+  thumb_media?: CDNMedia;
+  thumb_size?: number;
+  thumb_height?: number;
+  thumb_width?: number;
+}
+
+export interface RefMessage {
+  message_item?: MessageItem;
+  title?: string; // 摘要
+}
+
+export interface MessageItem {
+  type?: number;
+  create_time_ms?: number;
+  update_time_ms?: number;
+  is_completed?: boolean;
+  msg_id?: string;
+  ref_msg?: RefMessage;
+  text_item?: TextItem;
+  image_item?: ImageItem;
+  voice_item?: VoiceItem;
+  file_item?: FileItem;
+  video_item?: VideoItem;
+}
+
+/** Unified message (proto: WeixinMessage). Replaces the old split Message + MessageContent + FullMessage. */
+export interface WeixinMessage {
+  seq?: number;
+  message_id?: number;
+  from_user_id?: string;
+  to_user_id?: string;
+  client_id?: string;
+  create_time_ms?: number;
+  update_time_ms?: number;
+  delete_time_ms?: number;
+  session_id?: string;
+  group_id?: string;
+  message_type?: number;
+  message_state?: number;
+  item_list?: MessageItem[];
+  context_token?: string;
+}
+
+/** GetUpdates request: bytes fields are base64 strings in JSON. */
+export interface GetUpdatesReq {
+  /** @deprecated compat only, will be removed */
+  sync_buf?: string;
+  /** Full context buf cached locally; send "" when none (first request or after reset). */
+  get_updates_buf?: string;
+}
+
+/** GetUpdates response: bytes fields are base64 strings in JSON. */
+export interface GetUpdatesResp {
+  ret?: number;
+  /** Error code returned by the server (e.g. -14 = session timeout). Present when request fails. */
+  errcode?: number;
+  errmsg?: string;
+  msgs?: WeixinMessage[];
+  /** @deprecated compat only */
+  sync_buf?: string;
+  /** Full context buf to cache locally and send on next request. */
+  get_updates_buf?: string;
+  /** Server-suggested timeout (ms) for the next getUpdates long-poll. */
+  longpolling_timeout_ms?: number;
+}
+
+/** SendMessage request: wraps a single WeixinMessage. */
+export interface SendMessageReq {
+  msg?: WeixinMessage;
+}
+
+export interface SendMessageResp {
+  // empty
+}
+
+/** Typing status: 1 = typing (default), 2 = cancel typing. */
+export const TypingStatus = {
+  TYPING: 1,
+  CANCEL: 2,
+} as const;
+
+/** SendTyping request: send a typing indicator to a user. */
+export interface SendTypingReq {
+  ilink_user_id?: string;
+  typing_ticket?: string;
+  /** 1=typing (default), 2=cancel typing */
+  status?: number;
+}
+
+export interface SendTypingResp {
+  ret?: number;
+  errmsg?: string;
+}
+
+/** GetConfig response: bot config including typing_ticket. */
+export interface GetConfigResp {
+  ret?: number;
+  errmsg?: string;
+  /** Base64-encoded typing ticket for sendTyping. */
+  typing_ticket?: string;
+}