wechat-ilink-client 0.1.0

package/README.md

@@ -0,0 +1,313 @@
+# wechat-ilink-client
+
+[简体中文](./README.zh_CN.md)
+
+Standalone TypeScript client for the WeChat iLink bot protocol, reverse-engineered from [`@tencent-weixin/openclaw-weixin`](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin).
+
+No dependency on the OpenClaw framework. Zero runtime dependencies. A pure, stateless library you can use to build your own WeChat bots.
+
+## Design Principles
+
+- **Stateless** — the library does NOT read or write files. Credential storage, sync buf persistence, and QR code rendering are entirely the caller's responsibility.
+- **Zero runtime dependencies** — only Node.js built-ins.
+- **Minimal API surface** — a single `WeChatClient` class for most use cases, with lower-level primitives exported for advanced usage.
+
+## Features
+
+- QR code login (returns the URL; caller handles rendering)
+- Long-poll message receiving (`getUpdates`) with opt-in cursor persistence
+- Send text, image, video, and file messages
+- CDN media upload/download with AES-128-ECB encryption
+- Typing indicator support
+- EventEmitter-based API
+- Full TypeScript types for the entire protocol
+
+## Requirements
+
+- Node.js >= 20
+
+## Install
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+```typescript
+import { WeChatClient, MessageType } from "wechat-ilink-client";
+
+const client = new WeChatClient();
+
+// Step 1: Login via QR code
+const result = await client.login({
+  onQRCode(url) {
+    // You handle QR rendering — print it, show it in a GUI, etc.
+    console.log("Scan this QR code:", url);
+  },
+});
+if (!result.connected) {
+  console.error("Login failed:", result.message);
+  process.exit(1);
+}
+// You handle persistence — save these yourself:
+// result.botToken, result.accountId, result.baseUrl
+
+// Step 2: Handle incoming messages
+client.on("message", async (msg) => {
+  if (msg.message_type !== MessageType.USER) return;
+
+  const text = WeChatClient.extractText(msg);
+  const from = msg.from_user_id!;
+
+  await client.sendText(from, `Echo: ${text}`);
+});
+
+// Step 3: Start the long-poll loop (blocks until stop() is called)
+await client.start();
+```
+
+On subsequent runs, construct the client directly from saved credentials:
+
+```typescript
+const client = new WeChatClient({
+  accountId: savedAccountId,
+  token: savedToken,
+  baseUrl: savedBaseUrl,
+});
+// Ready — go straight to .on("message", ...) and .start()
+```
+
+### Persisting the Long-Poll Cursor
+
+To resume from where you left off across restarts, pass `loadSyncBuf` / `saveSyncBuf` callbacks to `start()`:
+
+```typescript
+await client.start({
+  loadSyncBuf: () => fs.readFileSync("sync.json", "utf-8"),
+  saveSyncBuf: (buf) => fs.writeFileSync("sync.json", buf),
+});
+```
+
+## Examples
+
+### Echo Bot
+
+A complete working bot with file-based persistence and QR rendering.
+
+First, install `qrcode-terminal` to render QR codes inline in your terminal:
+
+```bash
+pnpm add qrcode-terminal
+```
+
+Then run:
+
+```bash
+pnpm tsx examples/echo-bot.ts          # first run — shows QR code
+pnpm tsx examples/echo-bot.ts          # subsequent — resumes session
+pnpm tsx examples/echo-bot.ts --fresh  # force re-login
+```
+
+Or via the script:
+
+```bash
+pnpm echo-bot
+```
+
+> Without `qrcode-terminal` the example still works — it prints the QR code URL instead.
+
+The example stores credentials at `~/.wechat-echo-bot/` — this is the example's choice, not the library's.
+
+## API Reference
+
+### `WeChatClient`
+
+The high-level client. Extends `EventEmitter`.
+
+#### Constructor
+
+```typescript
+new WeChatClient(opts?: {
+  baseUrl?: string;      // default: "https://ilinkai.weixin.qq.com"
+  cdnBaseUrl?: string;   // default: "https://novac2c.cdn.weixin.qq.com/c2c"
+  token?: string;        // bearer token
+  accountId?: string;    // account ID
+  channelVersion?: string;
+  routeTag?: string;
+})
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `login(opts?)` | Run QR code login. Sets token/accountId in memory. Does NOT persist. |
+| `start(opts?)` | Start the long-poll monitor. Emits `"message"` events. Blocks until `stop()`. |
+| `stop()` | Stop the long-poll loop. |
+| `sendText(to, text, contextToken?)` | Send a text message. Context token is auto-resolved from cache. |
+| `sendMedia(to, filePath, caption?, contextToken?)` | Upload and send a file (image/video/file routed by MIME type). |
+| `sendUploadedImage(to, uploaded, caption?, contextToken?)` | Send a previously uploaded image. |
+| `sendUploadedVideo(to, uploaded, caption?, contextToken?)` | Send a previously uploaded video. |
+| `sendUploadedFile(to, fileName, uploaded, caption?, contextToken?)` | Send a previously uploaded file. |
+| `sendTyping(userId, typingTicket, status?)` | Send/cancel typing indicator. |
+| `getTypingTicket(userId, contextToken?)` | Fetch the typing ticket for a user. |
+| `uploadImage(filePath, toUserId)` | Upload an image to CDN. |
+| `uploadVideo(filePath, toUserId)` | Upload a video to CDN. |
+| `uploadFile(filePath, toUserId)` | Upload a file to CDN. |
+| `downloadMedia(item)` | Download and decrypt a media `MessageItem`. |
+| `getContextToken(userId)` | Get the cached context token for a user. |
+| `getAccountId()` | Get the current account ID. |
+
+#### `start()` Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `longPollTimeoutMs` | `number` | Long-poll timeout in ms. Server may override. |
+| `signal` | `AbortSignal` | For external cancellation. |
+| `loadSyncBuf` | `() => string \| undefined \| Promise<...>` | Called once at startup to load a persisted cursor. |
+| `saveSyncBuf` | `(buf: string) => void \| Promise<void>` | Called after each poll with the new cursor. |
+
+#### `login()` Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeoutMs` | `number` | Max wait for QR scan (default: 480_000). |
+| `botType` | `string` | bot_type parameter (default: "3"). |
+| `maxRefreshes` | `number` | Max QR refreshes on expiry (default: 3). |
+| `onQRCode` | `(url: string) => void` | Called with the QR code URL. **Caller renders.** |
+| `onStatus` | `(status) => void` | Called on status changes (wait/scaned/expired/confirmed). |
+| `signal` | `AbortSignal` | For cancellation. |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message` | `WeixinMessage` | Inbound message from a user. |
+| `error` | `Error` | Non-fatal poll/API error. |
+| `sessionExpired` | _(none)_ | Server returned errcode -14. Bot pauses automatically. |
+| `poll` | `GetUpdatesResp` | Raw response from each getUpdates call. |
+
+#### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `WeChatClient.extractText(msg)` | Extract text body from a `WeixinMessage`. |
+| `WeChatClient.isMediaItem(item)` | Check if a `MessageItem` is image/voice/file/video. |
+
+### `ApiClient`
+
+Low-level HTTP client. Used internally by `WeChatClient`, also exported for direct use.
+
+```typescript
+const api = new ApiClient({ baseUrl, token });
+
+await api.getUpdates(syncBuf, timeoutMs);
+await api.sendMessage(req);
+await api.getUploadUrl(req);
+await api.getConfig(userId, contextToken);
+await api.sendTyping(req);
+await api.getQRCode(botType);
+await api.pollQRCodeStatus(qrcode);
+```
+
+### `normalizeAccountId(raw)`
+
+Converts a raw account ID (e.g. `"hex@im.bot"`) to a safe key (`"hex-im-bot"`).
+
+## Protocol Overview
+
+The WeChat iLink bot backend lives at `https://ilinkai.weixin.qq.com`. All API endpoints use `POST` with JSON bodies (except QR login which uses `GET`).
+
+### Authentication
+
+Every request includes these headers:
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `application/json` |
+| `AuthorizationType` | `ilink_bot_token` |
+| `Authorization` | `Bearer <token>` |
+| `X-WECHAT-UIN` | Base64 of a random uint32 |
+
+The token is obtained through QR code login:
+
+1. `GET ilink/bot/get_bot_qrcode?bot_type=3` — returns a QR code URL
+2. `GET ilink/bot/get_qrcode_status?qrcode=...` — long-poll until `"confirmed"`
+3. Response includes `bot_token`, `ilink_bot_id`, `baseurl`
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `ilink/bot/getupdates` | Long-poll for inbound messages (cursor: `get_updates_buf`) |
+| `ilink/bot/sendmessage` | Send a message (text/image/video/file) |
+| `ilink/bot/getuploadurl` | Get CDN pre-signed upload parameters |
+| `ilink/bot/getconfig` | Get account config (typing ticket) |
+| `ilink/bot/sendtyping` | Send/cancel typing indicator |
+
+### Message Structure
+
+Messages use a `WeixinMessage` envelope containing an `item_list` of typed items:
+
+| Type | Value | Item field |
+|------|-------|------------|
+| TEXT | 1 | `text_item.text` |
+| IMAGE | 2 | `image_item` (CDN media ref + AES key) |
+| VOICE | 3 | `voice_item` (CDN media ref, optional STT text) |
+| FILE | 4 | `file_item` (CDN media ref + filename) |
+| VIDEO | 5 | `video_item` (CDN media ref) |
+
+The `context_token` field on inbound messages **must** be echoed back in all replies.
+
+### CDN Media
+
+All media is encrypted with **AES-128-ECB** (PKCS7 padding, random 16-byte key per file).
+
+**Upload flow:**
+1. Read file, compute MD5 and AES ciphertext size
+2. Call `getUploadUrl` with file metadata
+3. Encrypt with AES-128-ECB, POST to CDN URL
+4. CDN returns `x-encrypted-param` header (the download param)
+
+**Download flow:**
+1. Build URL: `{cdnBaseUrl}/download?encrypted_query_param=...`
+2. Fetch ciphertext
+3. Decrypt with the `aes_key` from the `CDNMedia` reference
+
+AES key encoding varies by media type:
+- Images: `base64(raw 16 bytes)`
+- Files/voice/video: `base64(hex string of 16 bytes)`
+
+## Project Structure
+
+```
+src/
+  index.ts                 Public API exports
+  client.ts                WeChatClient (high-level, stateless)
+  monitor.ts               Long-poll getUpdates loop with backoff
+  api/
+    types.ts               Protocol types (messages, CDN, requests/responses)
+    client.ts              Low-level HTTP ApiClient
+  auth/
+    qr-login.ts            QR code login flow (returns URL, no rendering)
+  cdn/
+    aes-ecb.ts             AES-128-ECB encrypt/decrypt
+    cdn-url.ts             CDN URL builders
+    cdn-upload.ts          Encrypted upload to CDN
+    cdn-download.ts        Download + decrypt from CDN
+  media/
+    upload.ts              File -> CDN upload pipeline
+    download.ts            Download media from inbound messages
+    send.ts                Build and send text/image/video/file messages
+  util/
+    mime.ts                MIME type <-> extension mapping
+    random.ts              ID and filename generation
+examples/
+  echo-bot.ts              Complete echo bot (with its own persistence + QR rendering)
+```
+
+## License
+
+MIT

package/README.zh_CN.md

@@ -0,0 +1,313 @@
+# wechat-ilink-client
+
+[English](./README.md)
+
+独立的 TypeScript 微信 iLink 机器人协议客户端，通过逆向 [`@tencent-weixin/openclaw-weixin`](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) 实现。
+
+不依赖 OpenClaw 框架。零运行时依赖。一个纯粹的、无状态的库，可直接用于构建你自己的微信机器人。
+
+## 设计原则
+
+- **无状态** — 库本身不读写任何文件。凭据存储、游标持久化、二维码渲染完全由调用者负责。
+- **零运行时依赖** — 仅使用 Node.js 内置模块。
+- **最小 API** — 一个 `WeChatClient` 类覆盖大多数场景，同时导出底层原语供高级使用。
+
+## 功能
+
+- 二维码扫码登录（返回 URL；调用者自行渲染）
+- 长轮询消息接收（`getUpdates`），游标持久化可选
+- 发送文本、图片、视频、文件消息
+- CDN 媒体上传/下载，AES-128-ECB 加密
+- 输入状态指示器（正在输入...）
+- 基于 EventEmitter 的 API
+- 完整的 TypeScript 协议类型定义
+
+## 环境要求
+
+- Node.js >= 20
+
+## 安装
+
+```bash
+pnpm install
+pnpm build
+```
+
+## 快速开始
+
+```typescript
+import { WeChatClient, MessageType } from "wechat-ilink-client";
+
+const client = new WeChatClient();
+
+// 第 1 步：二维码登录
+const result = await client.login({
+  onQRCode(url) {
+    // 你来处理二维码渲染 — 打印、显示在 GUI 中等
+    console.log("请扫描此二维码:", url);
+  },
+});
+if (!result.connected) {
+  console.error("登录失败:", result.message);
+  process.exit(1);
+}
+// 你来处理持久化 — 自行保存以下信息：
+// result.botToken, result.accountId, result.baseUrl
+
+// 第 2 步：处理收到的消息
+client.on("message", async (msg) => {
+  if (msg.message_type !== MessageType.USER) return;
+
+  const text = WeChatClient.extractText(msg);
+  const from = msg.from_user_id!;
+
+  await client.sendText(from, `Echo: ${text}`);
+});
+
+// 第 3 步：启动长轮询循环（阻塞直到调用 stop()）
+await client.start();
+```
+
+后续运行时，直接从已保存的凭据构造客户端：
+
+```typescript
+const client = new WeChatClient({
+  accountId: savedAccountId,
+  token: savedToken,
+  baseUrl: savedBaseUrl,
+});
+// 已就绪 — 直接设置 .on("message", ...) 并调用 .start()
+```
+
+### 持久化长轮询游标
+
+若要在重启后从上次位置恢复，向 `start()` 传入 `loadSyncBuf` / `saveSyncBuf` 回调：
+
+```typescript
+await client.start({
+  loadSyncBuf: () => fs.readFileSync("sync.json", "utf-8"),
+  saveSyncBuf: (buf) => fs.writeFileSync("sync.json", buf),
+});
+```
+
+## 示例
+
+### Echo Bot（回声机器人）
+
+一个完整的示例，带有文件持久化和二维码渲染。
+
+首先安装 `qrcode-terminal` 以在终端内渲染二维码：
+
+```bash
+pnpm add qrcode-terminal
+```
+
+然后运行：
+
+```bash
+pnpm tsx examples/echo-bot.ts          # 首次运行 — 显示二维码
+pnpm tsx examples/echo-bot.ts          # 后续运行 — 恢复会话
+pnpm tsx examples/echo-bot.ts --fresh  # 强制重新登录
+```
+
+或通过脚本：
+
+```bash
+pnpm echo-bot
+```
+
+> 未安装 `qrcode-terminal` 时示例仍可运行 — 会直接打印二维码 URL。
+
+示例将凭据存储在 `~/.wechat-echo-bot/` — 这是示例自己的选择，不是库的行为。
+
+## API 参考
+
+### `WeChatClient`
+
+高级客户端，继承自 `EventEmitter`。
+
+#### 构造函数
+
+```typescript
+new WeChatClient(opts?: {
+  baseUrl?: string;      // 默认: "https://ilinkai.weixin.qq.com"
+  cdnBaseUrl?: string;   // 默认: "https://novac2c.cdn.weixin.qq.com/c2c"
+  token?: string;        // Bearer token
+  accountId?: string;    // 账户 ID
+  channelVersion?: string;
+  routeTag?: string;
+})
+```
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `login(opts?)` | 执行二维码登录。仅在内存中设置 token/accountId。**不持久化。** |
+| `start(opts?)` | 启动长轮询监听。触发 `"message"` 事件。阻塞直到调用 `stop()`。 |
+| `stop()` | 停止长轮询循环。 |
+| `sendText(to, text, contextToken?)` | 发送文本消息。context token 自动从缓存中获取。 |
+| `sendMedia(to, filePath, caption?, contextToken?)` | 上传并发送文件（根据 MIME 类型自动路由为图片/视频/文件）。 |
+| `sendUploadedImage(to, uploaded, caption?, contextToken?)` | 发送已上传的图片。 |
+| `sendUploadedVideo(to, uploaded, caption?, contextToken?)` | 发送已上传的视频。 |
+| `sendUploadedFile(to, fileName, uploaded, caption?, contextToken?)` | 发送已上传的文件。 |
+| `sendTyping(userId, typingTicket, status?)` | 发送/取消输入状态指示器。 |
+| `getTypingTicket(userId, contextToken?)` | 获取用户的 typing ticket。 |
+| `uploadImage(filePath, toUserId)` | 上传图片到 CDN。 |
+| `uploadVideo(filePath, toUserId)` | 上传视频到 CDN。 |
+| `uploadFile(filePath, toUserId)` | 上传文件到 CDN。 |
+| `downloadMedia(item)` | 下载并解密 `MessageItem` 中的媒体内容。 |
+| `getContextToken(userId)` | 获取用户的缓存 context token。 |
+| `getAccountId()` | 获取当前账户 ID。 |
+
+#### `start()` 选项
+
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `longPollTimeoutMs` | `number` | 长轮询超时（毫秒），服务器可能覆盖此值。 |
+| `signal` | `AbortSignal` | 用于外部取消。 |
+| `loadSyncBuf` | `() => string \| undefined \| Promise<...>` | 启动时调用一次，加载已持久化的游标。 |
+| `saveSyncBuf` | `(buf: string) => void \| Promise<void>` | 每次轮询后调用，传入新的游标值。 |
+
+#### `login()` 选项
+
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `timeoutMs` | `number` | 等待扫码的最大时间（默认: 480_000）。 |
+| `botType` | `string` | bot_type 参数（默认: "3"）。 |
+| `maxRefreshes` | `number` | 二维码过期后最大刷新次数（默认: 3）。 |
+| `onQRCode` | `(url: string) => void` | 收到二维码 URL 时调用。**调用者自行渲染。** |
+| `onStatus` | `(status) => void` | 状态变化时调用（wait/scaned/expired/confirmed）。 |
+| `signal` | `AbortSignal` | 用于取消。 |
+
+#### 事件
+
+| 事件 | 载荷 | 说明 |
+|------|------|------|
+| `message` | `WeixinMessage` | 收到用户消息。 |
+| `error` | `Error` | 非致命的轮询/API 错误。 |
+| `sessionExpired` | _(无)_ | 服务器返回 errcode -14。机器人会自动暂停。 |
+| `poll` | `GetUpdatesResp` | 每次 getUpdates 调用的原始响应。 |
+
+#### 静态方法
+
+| 方法 | 说明 |
+|------|------|
+| `WeChatClient.extractText(msg)` | 从 `WeixinMessage` 中提取文本内容。 |
+| `WeChatClient.isMediaItem(item)` | 判断 `MessageItem` 是否为图片/语音/文件/视频。 |
+
+### `ApiClient`
+
+底层 HTTP 客户端。`WeChatClient` 内部使用，也可直接使用。
+
+```typescript
+const api = new ApiClient({ baseUrl, token });
+
+await api.getUpdates(syncBuf, timeoutMs);
+await api.sendMessage(req);
+await api.getUploadUrl(req);
+await api.getConfig(userId, contextToken);
+await api.sendTyping(req);
+await api.getQRCode(botType);
+await api.pollQRCodeStatus(qrcode);
+```
+
+### `normalizeAccountId(raw)`
+
+将原始账户 ID（如 `"hex@im.bot"`）转换为安全 key（`"hex-im-bot"`）。
+
+## 协议概述
+
+微信 iLink 机器人后端地址为 `https://ilinkai.weixin.qq.com`。所有 API 端点使用 `POST` + JSON 请求体（二维码登录使用 `GET`）。
+
+### 认证
+
+每个请求包含以下 HTTP 头：
+
+| 请求头 | 值 |
+|--------|-----|
+| `Content-Type` | `application/json` |
+| `AuthorizationType` | `ilink_bot_token` |
+| `Authorization` | `Bearer <token>` |
+| `X-WECHAT-UIN` | 随机 uint32 的 Base64 编码 |
+
+Token 通过二维码扫码登录获取：
+
+1. `GET ilink/bot/get_bot_qrcode?bot_type=3` — 返回二维码 URL
+2. `GET ilink/bot/get_qrcode_status?qrcode=...` — 长轮询直到状态为 `"confirmed"`
+3. 响应包含 `bot_token`、`ilink_bot_id`、`baseurl`
+
+### 端点列表
+
+| 端点 | 说明 |
+|------|------|
+| `ilink/bot/getupdates` | 长轮询接收消息（游标：`get_updates_buf`） |
+| `ilink/bot/sendmessage` | 发送消息（文本/图片/视频/文件） |
+| `ilink/bot/getuploadurl` | 获取 CDN 预签名上传参数 |
+| `ilink/bot/getconfig` | 获取账户配置（typing ticket） |
+| `ilink/bot/sendtyping` | 发送/取消输入状态指示器 |
+
+### 消息结构
+
+消息使用 `WeixinMessage` 信封，包含 `item_list` 类型化消息项：
+
+| 类型 | 值 | 对应字段 |
+|------|----|----------|
+| TEXT | 1 | `text_item.text` |
+| IMAGE | 2 | `image_item`（CDN 媒体引用 + AES 密钥） |
+| VOICE | 3 | `voice_item`（CDN 媒体引用，可选语音转文字） |
+| FILE | 4 | `file_item`（CDN 媒体引用 + 文件名） |
+| VIDEO | 5 | `video_item`（CDN 媒体引用） |
+
+收到消息中的 `context_token` 字段**必须**在所有回复中原样返回。
+
+### CDN 媒体
+
+所有媒体文件使用 **AES-128-ECB** 加密（PKCS7 填充，每个文件随机 16 字节密钥）。
+
+**上传流程：**
+1. 读取文件，计算 MD5 和 AES 密文大小
+2. 调用 `getUploadUrl` 获取上传参数
+3. AES-128-ECB 加密后 POST 到 CDN URL
+4. CDN 返回 `x-encrypted-param` 响应头（即下载参数）
+
+**下载流程：**
+1. 构建 URL：`{cdnBaseUrl}/download?encrypted_query_param=...`
+2. 获取密文
+3. 使用 `CDNMedia` 引用中的 `aes_key` 解密
+
+AES 密钥编码因媒体类型而异：
+- 图片：`base64(原始 16 字节)`
+- 文件/语音/视频：`base64(16 字节的十六进制字符串)`
+
+## 项目结构
+
+```
+src/
+  index.ts                 公共 API 导出
+  client.ts                WeChatClient（高级，无状态）
+  monitor.ts               长轮询 getUpdates 循环（含退避策略）
+  api/
+    types.ts               协议类型（消息、CDN、请求/响应）
+    client.ts              底层 HTTP ApiClient
+  auth/
+    qr-login.ts            二维码登录流程（仅返回 URL，不渲染）
+  cdn/
+    aes-ecb.ts             AES-128-ECB 加密/解密
+    cdn-url.ts             CDN URL 构建器
+    cdn-upload.ts          加密上传到 CDN
+    cdn-download.ts        从 CDN 下载并解密
+  media/
+    upload.ts              文件 -> CDN 上传流水线
+    download.ts            从收到的消息中下载媒体
+    send.ts                构建并发送文本/图片/视频/文件消息
+  util/
+    mime.ts                MIME 类型 <-> 扩展名映射
+    random.ts              ID 和文件名生成
+examples/
+  echo-bot.ts              完整的回声机器人（带有自己的持久化和二维码渲染）
+```
+
+## 许可证
+
+MIT