@zhin.js/adapter-weixin-ilink 0.1.0

package/src/ilink-meta.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BaseInfo } from "./ilink-types.js";
+
+export const ILINK_APP_ID = "bot";
+export const DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
+export const DEFAULT_API_BASE_URL = "https://ilinkai.weixin.qq.com";
+
+const DEFAULT_BOT_AGENT = "Zhin.js";
+const BOT_AGENT_MAX_LEN = 256;
+
+let channelVersion = "0.0.0";
+let configuredBotAgent: string | undefined;
+
+function readPackageVersion(): string {
+  try {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+channelVersion = readPackageVersion();
+
+export function configureIlinkMeta(opts: { botAgent?: string; version?: string }): void {
+  if (opts.botAgent) configuredBotAgent = opts.botAgent;
+  if (opts.version) channelVersion = opts.version;
+}
+
+export function buildClientVersion(version: string): number {
+  const parts = version.split(".").map((p) => parseInt(p, 10));
+  const major = parts[0] ?? 0;
+  const minor = parts[1] ?? 0;
+  const patch = parts[2] ?? 0;
+  return ((major & 0xff) << 16) | ((minor & 0xff) << 8) | (patch & 0xff);
+}
+
+export const ILINK_APP_CLIENT_VERSION = buildClientVersion(channelVersion);
+
+export function sanitizeBotAgent(raw: string | undefined): string {
+  if (!raw || typeof raw !== "string") return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+  const trimmed = raw.trim();
+  if (!trimmed) return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+  const productRe = /^[A-Za-z0-9_.\-]{1,32}\/[A-Za-z0-9_.+\-]{1,32}$/;
+  const tokens = trimmed.split(/\s+/).filter((tok) => productRe.test(tok));
+  if (tokens.length === 0) return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+  const joined = tokens.join(" ");
+  if (Buffer.byteLength(joined, "utf-8") <= BOT_AGENT_MAX_LEN) return joined;
+  return (configuredBotAgent ?? DEFAULT_BOT_AGENT);
+}
+
+export function buildBaseInfo(): BaseInfo {
+  return {
+    channel_version: channelVersion,
+    bot_agent: sanitizeBotAgent(configuredBotAgent),
+  };
+}

package/src/ilink-random.ts

@@ -0,0 +1,17 @@
+import crypto from "node:crypto";
+
+/**
+ * Generate a prefixed unique ID using timestamp + crypto random bytes.
+ * Format: `{prefix}:{timestamp}-{8-char hex}`
+ */
+export function generateId(prefix: string): string {
+  return `${prefix}:${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+/**
+ * Generate a temporary file name with random suffix.
+ * Format: `{prefix}-{timestamp}-{8-char hex}{ext}`
+ */
+export function tempFileName(prefix: string, ext: string): string {
+  return `${prefix}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`;
+}

package/src/ilink-redact.ts

@@ -0,0 +1,54 @@
+const DEFAULT_BODY_MAX_LEN = 200;
+const DEFAULT_TOKEN_PREFIX_LEN = 6;
+
+/**
+ * Truncate a string, appending a length indicator when trimmed.
+ * Returns `""` for empty/undefined input.
+ */
+export function truncate(s: string | undefined, max: number): string {
+  if (!s) return "";
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…(len=${s.length})`;
+}
+
+/**
+ * Redact a token/secret: show only the first few chars + total length.
+ * Returns `"(none)"` when absent.
+ */
+export function redactToken(token: string | undefined, prefixLen = DEFAULT_TOKEN_PREFIX_LEN): string {
+  if (!token) return "(none)";
+  if (token.length <= prefixLen) return `****(len=${token.length})`;
+  return `${token.slice(0, prefixLen)}…(len=${token.length})`;
+}
+
+/** Field names whose values should be masked in logged JSON bodies. */
+const SENSITIVE_FIELDS = /\b(context_token|bot_token|token|authorization|Authorization)\b/;
+
+/**
+ * Truncate a JSON body string to `maxLen` chars for safe logging.
+ * Redacts known sensitive fields before truncating.
+ */
+export function redactBody(body: string | undefined, maxLen = DEFAULT_BODY_MAX_LEN): string {
+  if (!body) return "(empty)";
+  // Mask values of known sensitive JSON keys: "key":"value" → "key":"<redacted>"
+  const redacted = body.replace(
+    /"(context_token|bot_token|token|authorization|Authorization)"\s*:\s*"[^"]*"/g,
+    '"$1":"<redacted>"',
+  );
+  if (redacted.length <= maxLen) return redacted;
+  return `${redacted.slice(0, maxLen)}…(truncated, totalLen=${redacted.length})`;
+}
+
+/**
+ * Strip query string (which often contains signatures/tokens) from a URL,
+ * keeping only origin + pathname.
+ */
+export function redactUrl(rawUrl: string): string {
+  try {
+    const u = new URL(rawUrl);
+    const base = `${u.origin}${u.pathname}`;
+    return u.search ? `${base}?<redacted>` : base;
+  } catch {
+    return truncate(rawUrl, 80);
+  }
+}

package/src/ilink-session-guard.ts

@@ -0,0 +1,58 @@
+import { logger } from "./ilink-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/ilink-types.ts

@@ -0,0 +1,261 @@
+/**
+ * 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;
+  /**
+   * Self-declared identity of the upstream bot/app, analogous to HTTP
+   * `User-Agent`. Filled from `channels.openclaw-weixin.botAgent` in
+   * openclaw.json; defaults to `"OpenClaw"` when unset.
+   *
+   * Format: UA-style `Name/Version` tokens, optionally followed by
+   * `(comment)`, multiple tokens space-separated. ASCII only, total
+   * length <= 256 bytes after sanitization.
+   *
+   * For observability only (logging, monitoring aggregation); not used
+   * for authentication or routing.
+   */
+  bot_agent?: 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;
+  /** 完整上传 URL（服务端直接返回，无需客户端拼接） */
+  upload_full_url?: 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;
+  /** 完整下载 URL（服务端直接返回，无需客户端拼接） */
+  full_url?: string;
+}
+
+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;
+}
+
+/** proto: NotifyStopReq — notify server when the channel client is stopping. */
+export interface NotifyStopReq {
+  base_info?: BaseInfo;
+}
+
+/** proto: NotifyStopResp */
+export interface NotifyStopResp {
+  ret?: number;
+  errmsg?: string;
+}
+
+/** proto: NotifyStartReq — notify server when the channel client is starting. */
+export interface NotifyStartReq {
+  base_info?: BaseInfo;
+}
+
+/** proto: NotifyStartResp */
+export interface NotifyStartResp {
+  ret?: number;
+  errmsg?: string;
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * 微信 iLink（ClawBot）适配器入口
+ */
+import path from "node:path";
+import { usePlugin, type Plugin } from "zhin.js";
+import type { Router } from "@zhin.js/host-router";
+import { PageManager } from "@zhin.js/host-api";
+import { WeixinIlinkAdapter } from "./adapter.js";
+import { registerRoutes } from "./routes.js";
+
+declare module "zhin.js" {
+  namespace Plugin {
+    interface Contexts {
+      web: PageManager;
+      router: Router;
+    }
+  }
+  interface Adapters {
+    "weixin-ilink": WeixinIlinkAdapter;
+  }
+}
+
+export * from "./types.js";
+export { WeixinIlinkBot } from "./bot.js";
+export { WeixinIlinkAdapter } from "./adapter.js";
+export {
+  WeixinIlinkTypingIndicatorManager,
+  enableTypingIndicator,
+  type WeixinIlinkTypingIndicatorConfig,
+} from "./typing-indicator.js";
+export { registerLoginAssistRoutes } from "./login-assist-routes.js";
+
+const plugin = usePlugin();
+const { provide, useContext, root } = plugin;
+
+provide({
+  name: "weixin-ilink",
+  description: "WeChat personal account via Tencent iLink Bot API (ClawBot)",
+  mounted: async (p: Plugin) => {
+    const adapter = new WeixinIlinkAdapter(p);
+    await adapter.start();
+    return adapter;
+  },
+  dispose: async (adapter: WeixinIlinkAdapter) => {
+    await adapter.stop();
+  },
+} as any);
+
+useContext("web", (pageManager) => {
+  pageManager.addEntry({
+    id: "weixin-ilink",
+    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
+    production: path.resolve(import.meta.dirname, "../dist/index.js"),
+    meta: { name: "微信 iLink" },
+  });
+});
+
+useContext("router", "weixin-ilink", async (router: Router, adapter: WeixinIlinkAdapter) => {
+  registerRoutes(router, adapter, root);
+});

package/src/login-assist-routes.ts

@@ -0,0 +1,36 @@
+/**
+ * loginAssist HTTP 路由（供 Web 控制台消费扫码等待等待办）
+ */
+import type { Router } from "@zhin.js/host-router";
+import type { Plugin } from "zhin.js";
+
+export function registerLoginAssistRoutes(router: Router, root: Plugin): void {
+  const loginAssist = root.inject("loginAssist");
+  if (!loginAssist) return;
+
+  router.get("/api/login-assist/pending", async (ctx) => {
+    ctx.body = loginAssist.listPending();
+  });
+
+  router.post("/api/login-assist/submit", async (ctx: any) => {
+    const body = (ctx.request.body ?? {}) as { id?: string; value?: string | Record<string, unknown> };
+    if (!body.id) {
+      ctx.status = 400;
+      ctx.body = { success: false, message: "missing id" };
+      return;
+    }
+    const ok = loginAssist.submit(body.id, body.value ?? "");
+    ctx.body = { success: ok };
+  });
+
+  router.post("/api/login-assist/cancel", async (ctx: any) => {
+    const body = (ctx.request.body ?? {}) as { id?: string; reason?: string };
+    if (!body.id) {
+      ctx.status = 400;
+      ctx.body = { success: false, message: "missing id" };
+      return;
+    }
+    const ok = loginAssist.cancel(body.id, body.reason);
+    ctx.body = { success: ok };
+  });
+}