@dadb/weixin-standalone-api 0.1.0

package/LICENSE

@@ -0,0 +1 @@
+MIT License

package/README.md

@@ -0,0 +1,356 @@
+# weixin-standalone-api
+
+Standalone Weixin bot API server (no OpenClaw runtime dependency).
+
+- QR login by mobile Weixin app
+- inbound message polling + local event queue
+- send text and image APIs
+- account and worker management APIs
+
+Chinese doc: [README.zh-CN.md](./README.zh-CN.md)
+
+## Requirements
+
+- Node.js `>=22`
+- Reachable Weixin iLink bot backend
+
+## Install
+
+```bash
+npm i -g weixin-standalone-api
+```
+
+or:
+
+```bash
+npm i weixin-standalone-api
+```
+
+## Run
+
+```bash
+WEIXIN_STANDALONE_TOKEN='replace_me' \
+WEIXIN_STANDALONE_HOST='127.0.0.1' \
+WEIXIN_STANDALONE_PORT='8788' \
+weixin-standalone-api
+```
+
+## Environment Variables
+
+- `WEIXIN_STANDALONE_TOKEN`: bearer token for API auth. If empty, auth is disabled.
+- `WEIXIN_STANDALONE_HOST`: default `127.0.0.1`
+- `WEIXIN_STANDALONE_PORT`: default `8788`
+- `WEIXIN_STANDALONE_STATE_DIR`: default `./.weixin-standalone`
+- `WEIXIN_BASE_URL`: default `https://ilinkai.weixin.qq.com`
+- `WEIXIN_CDN_BASE_URL`: default `https://novac2c.cdn.weixin.qq.com/c2c`
+- `WEIXIN_BOT_TYPE`: default `"3"`
+
+## API Auth
+
+When `WEIXIN_STANDALONE_TOKEN` is set, all APIs except `/healthz` require:
+
+```http
+Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>
+```
+
+## Response Format
+
+Success:
+
+```json
+{
+  "requestId": "uuid",
+  "data": {}
+}
+```
+
+Error:
+
+```json
+{
+  "requestId": "uuid",
+  "error": "error message"
+}
+```
+
+## API Reference
+
+### 1) Health
+
+`GET /healthz`
+
+Response:
+
+```json
+{ "ok": true, "requestId": "..." }
+```
+
+### 2) QR Login Start
+
+`POST /v1/login/qr/start`
+
+Body:
+
+```json
+{
+  "accountId": "optional",
+  "botType": "optional",
+  "baseUrl": "optional"
+}
+```
+
+Response:
+
+```json
+{
+  "requestId": "...",
+  "data": {
+    "sessionKey": "...",
+    "qrcodeUrl": "..."
+  }
+}
+```
+
+### 3) QR Login Wait
+
+`POST /v1/login/qr/wait`
+
+Body:
+
+```json
+{
+  "sessionKey": "...",
+  "timeoutMs": 480000
+}
+```
+
+Response:
+
+```json
+{
+  "requestId": "...",
+  "data": {
+    "connected": true,
+    "accountId": "xxx-im-bot",
+    "userId": "xxx@im.wechat"
+  }
+}
+```
+
+### 4) List Accounts
+
+`GET /v1/accounts`
+
+Response:
+
+```json
+{
+  "requestId": "...",
+  "data": [
+    {
+      "accountId": "xxx-im-bot",
+      "baseUrl": "https://...",
+      "userId": "xxx@im.wechat",
+      "enabled": true,
+      "createdAt": 1234567890,
+      "updatedAt": 1234567890,
+      "worker": {
+        "running": true,
+        "lastError": null,
+        "lastEventAt": 1234567890,
+        "startedAt": 1234567890
+      }
+    }
+  ]
+}
+```
+
+### 5) Start Worker
+
+`POST /v1/workers/start`
+
+Body:
+
+```json
+{ "accountId": "xxx-im-bot" }
+```
+
+### 6) Stop Worker
+
+`POST /v1/workers/stop`
+
+Body:
+
+```json
+{ "accountId": "xxx-im-bot" }
+```
+
+### 7) Send Text
+
+`POST /v1/messages/text`
+
+Body:
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "text": "hello",
+  "contextToken": "optional"
+}
+```
+
+Notes:
+- `contextToken` is required by upstream. If omitted, server will try cached token for `(accountId,to)`.
+
+### 8) Send Image
+
+`POST /v1/messages/image`
+
+Body (local file):
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "filePath": "/tmp/a.jpg",
+  "text": "optional",
+  "contextToken": "optional"
+}
+```
+
+Body (remote URL):
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "imageUrl": "https://example.com/a.jpg",
+  "text": "optional",
+  "contextToken": "optional"
+}
+```
+
+Constraints:
+- Exactly one of `filePath` or `imageUrl`
+- `imageUrl` must be `https`
+- Max image size: 20 MB
+
+### 9) Pull Events
+
+`GET /v1/events?accountId=xxx-im-bot&limit=100&cursor=<eventId>`
+
+Query:
+- `accountId` required
+- `limit` optional (1..500, default 100)
+- `cursor` optional
+
+Response:
+
+```json
+{
+  "requestId": "...",
+  "data": {
+    "items": [
+      {
+        "id": "...",
+        "accountId": "xxx-im-bot",
+        "from": "user@im.wechat",
+        "to": "bot@im.bot",
+        "text": "hello",
+        "contextToken": "...",
+        "raw": {},
+        "createdAt": 1234567890,
+        "ackedAt": null
+      }
+    ],
+    "nextCursor": "..."
+  }
+}
+```
+
+### 10) Ack Events
+
+`POST /v1/events/ack`
+
+Body:
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "ids": ["event-id-1", "event-id-2"]
+}
+```
+
+Response:
+
+```json
+{
+  "requestId": "...",
+  "data": { "acked": 2 }
+}
+```
+
+## End-to-End Quick Flow
+
+1. Start service
+2. Call `/v1/login/qr/start`
+3. Scan QR with mobile Weixin app
+4. Call `/v1/login/qr/wait` until `connected=true`
+5. Call `/v1/accounts` and ensure worker is running
+6. Pull inbound via `/v1/events`
+7. Reply via `/v1/messages/text` or `/v1/messages/image` using event `contextToken`
+8. Ack consumed events via `/v1/events/ack`
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Build:
+
+```bash
+npm run build
+npm run start
+```
+
+Typecheck:
+
+```bash
+npm run typecheck
+```
+
+## Versioning
+
+Patch:
+
+```bash
+npm run version:bump
+```
+
+Minor:
+
+```bash
+npm run version:bump -- minor
+```
+
+Major:
+
+```bash
+npm run version:bump -- major
+```
+
+Set exact:
+
+```bash
+npm run version:bump -- 1.2.3
+```
+
+## Publish
+
+```bash
+npm login
+npm publish
+```

package/README.zh-CN.md

@@ -0,0 +1,309 @@
+# weixin-standalone-api
+
+独立的微信机器人 API 服务（不依赖 OpenClaw 运行时）。
+
+- 手机微信扫码登录
+- 入站消息轮询 + 本地事件队列
+- 文本/图片发送接口
+- 账号与 worker 管理接口
+
+英文文档： [README.md](./README.md)
+
+## 运行要求
+
+- Node.js `>=22`
+- 可访问的微信 iLink bot 后端
+
+## 安装
+
+```bash
+npm i -g weixin-standalone-api
+```
+
+或：
+
+```bash
+npm i weixin-standalone-api
+```
+
+## 启动
+
+```bash
+WEIXIN_STANDALONE_TOKEN='replace_me' \
+WEIXIN_STANDALONE_HOST='127.0.0.1' \
+WEIXIN_STANDALONE_PORT='8788' \
+weixin-standalone-api
+```
+
+## 环境变量
+
+- `WEIXIN_STANDALONE_TOKEN`：API 访问令牌。为空时不鉴权。
+- `WEIXIN_STANDALONE_HOST`：默认 `127.0.0.1`
+- `WEIXIN_STANDALONE_PORT`：默认 `8788`
+- `WEIXIN_STANDALONE_STATE_DIR`：默认 `./.weixin-standalone`
+- `WEIXIN_BASE_URL`：默认 `https://ilinkai.weixin.qq.com`
+- `WEIXIN_CDN_BASE_URL`：默认 `https://novac2c.cdn.weixin.qq.com/c2c`
+- `WEIXIN_BOT_TYPE`：默认 `"3"`
+
+## 鉴权
+
+设置了 `WEIXIN_STANDALONE_TOKEN` 后，除 `/healthz` 之外都要带：
+
+```http
+Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>
+```
+
+## 返回格式
+
+成功：
+
+```json
+{
+  "requestId": "uuid",
+  "data": {}
+}
+```
+
+失败：
+
+```json
+{
+  "requestId": "uuid",
+  "error": "错误信息"
+}
+```
+
+## API 说明
+
+### 1）健康检查
+
+`GET /healthz`
+
+返回：
+
+```json
+{ "ok": true, "requestId": "..." }
+```
+
+### 2）发起扫码
+
+`POST /v1/login/qr/start`
+
+请求体：
+
+```json
+{
+  "accountId": "可选",
+  "botType": "可选",
+  "baseUrl": "可选"
+}
+```
+
+返回：
+
+```json
+{
+  "requestId": "...",
+  "data": {
+    "sessionKey": "...",
+    "qrcodeUrl": "..."
+  }
+}
+```
+
+### 3）等待扫码结果
+
+`POST /v1/login/qr/wait`
+
+请求体：
+
+```json
+{
+  "sessionKey": "...",
+  "timeoutMs": 480000
+}
+```
+
+返回：
+
+```json
+{
+  "requestId": "...",
+  "data": {
+    "connected": true,
+    "accountId": "xxx-im-bot",
+    "userId": "xxx@im.wechat"
+  }
+}
+```
+
+### 4）账号列表
+
+`GET /v1/accounts`
+
+### 5）启动账号 worker
+
+`POST /v1/workers/start`
+
+请求体：
+
+```json
+{ "accountId": "xxx-im-bot" }
+```
+
+### 6）停止账号 worker
+
+`POST /v1/workers/stop`
+
+请求体：
+
+```json
+{ "accountId": "xxx-im-bot" }
+```
+
+### 7）发送文本
+
+`POST /v1/messages/text`
+
+请求体：
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "text": "hello",
+  "contextToken": "可选"
+}
+```
+
+说明：
+- `contextToken` 是上游会话关键字段。
+- 不传时，服务会尝试从 `(accountId,to)` 的缓存中取。
+
+### 8）发送图片
+
+`POST /v1/messages/image`
+
+本地文件模式：
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "filePath": "/tmp/a.jpg",
+  "text": "可选",
+  "contextToken": "可选"
+}
+```
+
+远程 URL 模式：
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "to": "target@im.wechat",
+  "imageUrl": "https://example.com/a.jpg",
+  "text": "可选",
+  "contextToken": "可选"
+}
+```
+
+约束：
+- `filePath` 和 `imageUrl` 二选一
+- `imageUrl` 必须为 `https`
+- 图片最大 20MB
+
+### 9）拉取事件
+
+`GET /v1/events?accountId=xxx-im-bot&limit=100&cursor=<eventId>`
+
+参数：
+- `accountId` 必填
+- `limit` 可选（1..500，默认 100）
+- `cursor` 可选
+
+### 10）确认事件已处理
+
+`POST /v1/events/ack`
+
+请求体：
+
+```json
+{
+  "accountId": "xxx-im-bot",
+  "ids": ["event-id-1", "event-id-2"]
+}
+```
+
+返回：
+
+```json
+{
+  "requestId": "...",
+  "data": { "acked": 2 }
+}
+```
+
+## 最小联调流程
+
+1. 启动服务
+2. 调 `/v1/login/qr/start`
+3. 手机微信扫码
+4. 调 `/v1/login/qr/wait` 直到 `connected=true`
+5. 调 `/v1/accounts` 查看账号和 worker
+6. 调 `/v1/events` 拉入站消息
+7. 用事件里的 `contextToken` 调 `/v1/messages/text` 或 `/v1/messages/image`
+8. 调 `/v1/events/ack` 确认消费
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+构建与启动：
+
+```bash
+npm run build
+npm run start
+```
+
+类型检查：
+
+```bash
+npm run typecheck
+```
+
+## 版本脚本
+
+Patch：
+
+```bash
+npm run version:bump
+```
+
+Minor：
+
+```bash
+npm run version:bump -- minor
+```
+
+Major：
+
+```bash
+npm run version:bump -- major
+```
+
+指定版本：
+
+```bash
+npm run version:bump -- 1.2.3
+```
+
+## 发布
+
+```bash
+npm login
+npm publish
+```

package/bin/weixin-standalone-api.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/index.js");

package/dist/index.js

@@ -0,0 +1,604 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { URL } from "node:url";
+import { createCipheriv } from "node:crypto";
+import { z } from "zod";
+const DEFAULT_BASE_URL = process.env.WEIXIN_BASE_URL || "https://ilinkai.weixin.qq.com";
+const DEFAULT_CDN_BASE_URL = process.env.WEIXIN_CDN_BASE_URL || "https://novac2c.cdn.weixin.qq.com/c2c";
+const DEFAULT_BOT_TYPE = process.env.WEIXIN_BOT_TYPE || "3";
+const API_HOST = process.env.WEIXIN_STANDALONE_HOST || "127.0.0.1";
+const API_PORT = Number(process.env.WEIXIN_STANDALONE_PORT || "8788");
+const API_TOKEN = process.env.WEIXIN_STANDALONE_TOKEN?.trim() || "";
+const STATE_DIR = process.env.WEIXIN_STANDALONE_STATE_DIR?.trim() ||
+    path.join(process.cwd(), ".weixin-standalone");
+const ACCOUNTS_FILE = path.join(STATE_DIR, "accounts.json");
+const EVENTS_FILE = path.join(STATE_DIR, "events.json");
+const OUTBOUND_TMP_DIR = path.join("/tmp", "weixin-standalone", "outbound");
+const qrSessions = new Map();
+const workers = new Map();
+const workerStates = new Map();
+const contextTokenCache = new Map();
+const loginStartSchema = z.object({
+    accountId: z.string().trim().min(1).optional(),
+    botType: z.string().trim().min(1).optional(),
+    baseUrl: z.string().url().optional(),
+}).strict();
+const loginWaitSchema = z.object({
+    sessionKey: z.string().trim().min(1),
+    timeoutMs: z.number().int().positive().max(900_000).optional(),
+}).strict();
+const sendTextSchema = z.object({
+    accountId: z.string().trim().min(1),
+    to: z.string().trim().min(1),
+    text: z.string().max(4000),
+    contextToken: z.string().trim().optional(),
+}).strict();
+const sendImageSchema = z.object({
+    accountId: z.string().trim().min(1),
+    to: z.string().trim().min(1),
+    text: z.string().max(4000).optional(),
+    contextToken: z.string().trim().optional(),
+    filePath: z.string().trim().min(1).optional(),
+    imageUrl: z.string().url().optional(),
+}).strict().refine((v) => Boolean(v.filePath) !== Boolean(v.imageUrl), {
+    message: "exactly one of filePath or imageUrl is required",
+});
+const ackSchema = z.object({
+    accountId: z.string().trim().min(1),
+    ids: z.array(z.string().trim().min(1)).min(1).max(1000),
+}).strict();
+function aesEcbPaddedSize(plaintextSize) {
+    return Math.ceil((plaintextSize + 1) / 16) * 16;
+}
+function encryptAesEcb(plaintext, key) {
+    const cipher = createCipheriv("aes-128-ecb", key, null);
+    return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+}
+function buildCdnUploadUrl(params) {
+    return `${params.cdnBaseUrl}/upload?encrypted_query_param=${encodeURIComponent(params.uploadParam)}&filekey=${encodeURIComponent(params.filekey)}`;
+}
+async function uploadBufferToCdn(params) {
+    const cdnUrl = buildCdnUploadUrl({
+        cdnBaseUrl: params.cdnBaseUrl,
+        uploadParam: params.uploadParam,
+        filekey: params.filekey,
+    });
+    const ciphertext = encryptAesEcb(params.buf, params.aeskey);
+    let lastErr;
+    for (let i = 0; i < 3; i += 1) {
+        try {
+            const res = await fetch(cdnUrl, {
+                method: "POST",
+                headers: { "content-type": "application/octet-stream" },
+                body: new Uint8Array(ciphertext),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`${params.label}: CDN upload failed ${res.status} ${res.statusText} ${body}`);
+            }
+            const downloadParam = res.headers.get("x-encrypted-param");
+            if (!downloadParam)
+                throw new Error(`${params.label}: missing x-encrypted-param`);
+            return { downloadParam };
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < 2)
+                await new Promise((r) => setTimeout(r, 300 * (i + 1)));
+        }
+    }
+    throw (lastErr instanceof Error ? lastErr : new Error("CDN upload failed"));
+}
+function ensureStateDir() {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+}
+function readJson(file, fallback) {
+    try {
+        if (!fs.existsSync(file))
+            return fallback;
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+function writeJson(file, data) {
+    ensureStateDir();
+    fs.writeFileSync(file, JSON.stringify(data, null, 2), "utf-8");
+}
+function loadAccounts() {
+    return readJson(ACCOUNTS_FILE, {});
+}
+function saveAccounts(accounts) {
+    writeJson(ACCOUNTS_FILE, accounts);
+}
+function loadEvents() {
+    return readJson(EVENTS_FILE, []);
+}
+function saveEvents(events) {
+    writeJson(EVENTS_FILE, events);
+}
+function normalizeAccountId(input) {
+    const out = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+    if (out)
+        return out;
+    return "acc-" + crypto.createHash("sha1").update(input).digest("hex").slice(0, 12);
+}
+function keyForContext(accountId, userId) {
+    return accountId + "::" + userId;
+}
+function randomWechatUin() {
+    const uint32 = crypto.randomBytes(4).readUInt32BE(0);
+    return Buffer.from(String(uint32), "utf-8").toString("base64");
+}
+async function requestJson(params) {
+    const timeoutMs = params.timeoutMs ?? 15_000;
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const bodyText = params.body === undefined ? undefined : JSON.stringify(params.body);
+        const headers = {
+            ...(bodyText ? { "content-type": "application/json" } : {}),
+            ...(bodyText ? { "content-length": String(Buffer.byteLength(bodyText, "utf-8")) } : {}),
+            ...(params.token ? { AuthorizationType: "ilink_bot_token", Authorization: "Bearer " + params.token } : {}),
+            "X-WECHAT-UIN": randomWechatUin(),
+            ...params.headers,
+        };
+        const res = await fetch(params.url, {
+            method: params.method,
+            headers,
+            body: bodyText,
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        const raw = await res.text();
+        if (!res.ok) {
+            throw new Error("HTTP " + res.status + " " + res.statusText + " body=" + raw);
+        }
+        if (!raw.trim())
+            return {};
+        return JSON.parse(raw);
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+function extractText(itemList) {
+    const text = itemList?.find((i) => i.type === 1)?.text_item?.text;
+    return text || "";
+}
+function publishEvent(ev) {
+    const item = {
+        ...ev,
+        id: crypto.randomUUID(),
+        createdAt: Date.now(),
+    };
+    const events = loadEvents();
+    events.push(item);
+    saveEvents(events);
+    return item;
+}
+function resolveAccountOrThrow(accountId) {
+    const accounts = loadAccounts();
+    const account = accounts[accountId];
+    if (!account || !account.token) {
+        throw new Error("account not found or token missing: " + accountId);
+    }
+    return account;
+}
+async function getUploadUrl(params) {
+    const base = params.account.baseUrl.endsWith("/") ? params.account.baseUrl : params.account.baseUrl + "/";
+    const resp = await requestJson({
+        method: "POST",
+        url: new URL("ilink/bot/getuploadurl", base).toString(),
+        token: params.account.token,
+        body: {
+            filekey: params.filekey,
+            media_type: 1,
+            to_user_id: params.toUserId,
+            rawsize: params.rawsize,
+            rawfilemd5: params.rawfilemd5,
+            filesize: params.filesize,
+            no_need_thumb: true,
+            aeskey: params.aeskeyHex,
+            base_info: { channel_version: "standalone-1.0.0" },
+        },
+    });
+    if (!resp.upload_param)
+        throw new Error("getuploadurl missing upload_param");
+    return resp.upload_param;
+}
+async function sendMessage(params) {
+    const clientId = "standalone-" + crypto.randomUUID();
+    const base = params.account.baseUrl.endsWith("/") ? params.account.baseUrl : params.account.baseUrl + "/";
+    await requestJson({
+        method: "POST",
+        url: new URL("ilink/bot/sendmessage", base).toString(),
+        token: params.account.token,
+        body: {
+            msg: {
+                from_user_id: "",
+                to_user_id: params.to,
+                client_id: clientId,
+                message_type: 2,
+                message_state: 2,
+                item_list: params.itemList,
+                context_token: params.contextToken,
+            },
+            base_info: { channel_version: "standalone-1.0.0" },
+        },
+    });
+    return { messageId: clientId };
+}
+async function downloadImageToTemp(imageUrl) {
+    const u = new URL(imageUrl);
+    if (u.protocol !== "https:")
+        throw new Error("imageUrl must be https");
+    await fsp.mkdir(OUTBOUND_TMP_DIR, { recursive: true });
+    const res = await fetch(imageUrl, { method: "GET" });
+    if (!res.ok)
+        throw new Error("image download failed: " + res.status);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > 20 * 1024 * 1024)
+        throw new Error("image too large");
+    const ext = (res.headers.get("content-type") || "").includes("png") ? ".png" : ".jpg";
+    const filePath = path.join(OUTBOUND_TMP_DIR, crypto.randomUUID() + ext);
+    await fsp.writeFile(filePath, buf);
+    return filePath;
+}
+async function sendImage(params) {
+    const filePath = params.filePath || await downloadImageToTemp(params.imageUrl);
+    const buf = await fsp.readFile(filePath);
+    const rawsize = buf.length;
+    const rawfilemd5 = crypto.createHash("md5").update(buf).digest("hex");
+    const filesize = aesEcbPaddedSize(rawsize);
+    const filekey = crypto.randomBytes(16).toString("hex");
+    const aeskey = crypto.randomBytes(16);
+    const uploadParam = await getUploadUrl({
+        account: params.account,
+        toUserId: params.to,
+        filekey,
+        rawsize,
+        rawfilemd5,
+        filesize,
+        aeskeyHex: aeskey.toString("hex"),
+    });
+    const uploaded = await uploadBufferToCdn({
+        buf,
+        uploadParam,
+        filekey,
+        cdnBaseUrl: params.account.cdnBaseUrl || DEFAULT_CDN_BASE_URL,
+        aeskey,
+        label: "standalone-send-image",
+    });
+    const items = [];
+    if (params.text?.trim()) {
+        items.push({ type: 1, text_item: { text: params.text.trim() } });
+    }
+    items.push({
+        type: 2,
+        image_item: {
+            media: {
+                encrypt_query_param: uploaded.downloadParam,
+                aes_key: Buffer.from(aeskey).toString("base64"),
+                encrypt_type: 1,
+            },
+            mid_size: filesize,
+        },
+    });
+    return await sendMessage({
+        account: params.account,
+        to: params.to,
+        contextToken: params.contextToken,
+        itemList: items,
+    });
+}
+async function startLogin(baseUrl, botType) {
+    const base = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
+    const resp = await requestJson({
+        method: "GET",
+        url: new URL("ilink/bot/get_bot_qrcode?bot_type=" + encodeURIComponent(botType), base).toString(),
+        timeoutMs: 10_000,
+    });
+    if (!resp.qrcode || !resp.qrcode_img_content) {
+        throw new Error("qrcode response missing fields");
+    }
+    const sessionKey = crypto.randomUUID();
+    qrSessions.set(sessionKey, {
+        sessionKey,
+        qrcode: resp.qrcode,
+        qrcodeUrl: resp.qrcode_img_content,
+        baseUrl,
+        createdAt: Date.now(),
+    });
+    return { sessionKey, qrcodeUrl: resp.qrcode_img_content };
+}
+async function waitLogin(sessionKey, timeoutMs) {
+    const session = qrSessions.get(sessionKey);
+    if (!session)
+        throw new Error("session not found");
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const base = session.baseUrl.endsWith("/") ? session.baseUrl : session.baseUrl + "/";
+        const status = await requestJson({
+            method: "GET",
+            url: new URL("ilink/bot/get_qrcode_status?qrcode=" + encodeURIComponent(session.qrcode), base).toString(),
+            headers: { "iLink-App-ClientVersion": "1" },
+            timeoutMs: 35_000,
+        });
+        if (status.status === "confirmed" && status.bot_token && status.ilink_bot_id) {
+            const accountId = normalizeAccountId(status.ilink_bot_id);
+            const accounts = loadAccounts();
+            accounts[accountId] = {
+                accountId,
+                token: status.bot_token,
+                baseUrl: status.baseurl || session.baseUrl || DEFAULT_BASE_URL,
+                cdnBaseUrl: DEFAULT_CDN_BASE_URL,
+                userId: status.ilink_user_id,
+                enabled: true,
+                createdAt: accounts[accountId]?.createdAt || Date.now(),
+                updatedAt: Date.now(),
+            };
+            saveAccounts(accounts);
+            qrSessions.delete(sessionKey);
+            startWorker(accountId);
+            return { connected: true, accountId, userId: status.ilink_user_id };
+        }
+        if (status.status === "expired") {
+            break;
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    return { connected: false };
+}
+async function workerLoop(accountId, signal) {
+    const state = { running: true, startedAt: Date.now() };
+    workerStates.set(accountId, state);
+    while (!signal.aborted) {
+        try {
+            const accounts = loadAccounts();
+            const account = accounts[accountId];
+            if (!account || !account.token || account.enabled === false) {
+                throw new Error("account not configured or disabled");
+            }
+            const base = account.baseUrl.endsWith("/") ? account.baseUrl : account.baseUrl + "/";
+            const resp = await requestJson({
+                method: "POST",
+                url: new URL("ilink/bot/getupdates", base).toString(),
+                token: account.token,
+                timeoutMs: 35_000,
+                body: {
+                    get_updates_buf: account.syncBuf || "",
+                    base_info: { channel_version: "standalone-1.0.0" },
+                },
+            });
+            if ((resp.ret ?? 0) !== 0 || (resp.errcode ?? 0) !== 0) {
+                throw new Error("getupdates failed ret=" + String(resp.ret) + " errcode=" + String(resp.errcode) + " msg=" + String(resp.errmsg || ""));
+            }
+            if (resp.get_updates_buf) {
+                accounts[accountId] = { ...account, syncBuf: resp.get_updates_buf, updatedAt: Date.now() };
+                saveAccounts(accounts);
+            }
+            for (const msg of resp.msgs || []) {
+                const from = msg.from_user_id || "";
+                const to = msg.to_user_id || "";
+                const text = extractText(msg.item_list);
+                const ctx = msg.context_token;
+                if (from && ctx)
+                    contextTokenCache.set(keyForContext(accountId, from), ctx);
+                publishEvent({
+                    accountId,
+                    from,
+                    to,
+                    text,
+                    contextToken: ctx,
+                    raw: msg,
+                });
+                state.lastEventAt = Date.now();
+            }
+            state.lastError = undefined;
+            workerStates.set(accountId, state);
+        }
+        catch (err) {
+            state.lastError = String(err);
+            workerStates.set(accountId, state);
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+    }
+    workerStates.set(accountId, { ...state, running: false });
+}
+function startWorker(accountId) {
+    stopWorker(accountId);
+    const abort = new AbortController();
+    const loop = workerLoop(accountId, abort.signal);
+    workers.set(accountId, { abort, loop });
+}
+function stopWorker(accountId) {
+    const hit = workers.get(accountId);
+    if (!hit)
+        return;
+    hit.abort.abort();
+    workers.delete(accountId);
+}
+function parseBody(raw, schema) {
+    let obj = {};
+    if (raw.trim()) {
+        obj = JSON.parse(raw);
+    }
+    const out = schema.safeParse(obj);
+    if (!out.success) {
+        throw new Error("invalid body: " + JSON.stringify(out.error.flatten()));
+    }
+    return out.data;
+}
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function checkApiToken(req) {
+    if (!API_TOKEN)
+        return;
+    const token = String(req.headers.authorization || "");
+    if (token !== "Bearer " + API_TOKEN) {
+        throw new Error("unauthorized");
+    }
+}
+function bootWorkers() {
+    const accounts = loadAccounts();
+    for (const acc of Object.values(accounts)) {
+        if (acc.enabled && acc.token)
+            startWorker(acc.accountId);
+    }
+}
+async function handle(req, res) {
+    const requestId = crypto.randomUUID();
+    try {
+        const method = req.method || "GET";
+        const url = new URL(req.url || "/", "http://localhost");
+        if (method === "GET" && url.pathname === "/healthz") {
+            json(res, 200, { ok: true, requestId });
+            return;
+        }
+        checkApiToken(req);
+        const bodyText = method === "GET" ? "" : await readBody(req);
+        if (method === "POST" && url.pathname === "/v1/login/qr/start") {
+            const body = parseBody(bodyText, loginStartSchema);
+            const out = await startLogin(body.baseUrl || DEFAULT_BASE_URL, body.botType || DEFAULT_BOT_TYPE);
+            json(res, 200, { requestId, data: out });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/login/qr/wait") {
+            const body = parseBody(bodyText, loginWaitSchema);
+            const out = await waitLogin(body.sessionKey, body.timeoutMs ?? 480_000);
+            json(res, 200, { requestId, data: out });
+            return;
+        }
+        if (method === "GET" && url.pathname === "/v1/accounts") {
+            const accounts = loadAccounts();
+            const status = Object.values(accounts).map((acc) => ({
+                accountId: acc.accountId,
+                baseUrl: acc.baseUrl,
+                userId: acc.userId,
+                enabled: acc.enabled,
+                createdAt: acc.createdAt,
+                updatedAt: acc.updatedAt,
+                worker: workerStates.get(acc.accountId) || { running: false },
+            }));
+            json(res, 200, { requestId, data: status });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/workers/start") {
+            const body = parseBody(bodyText, z.object({ accountId: z.string().min(1) }).strict());
+            startWorker(body.accountId);
+            json(res, 200, { requestId, data: { started: true } });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/workers/stop") {
+            const body = parseBody(bodyText, z.object({ accountId: z.string().min(1) }).strict());
+            stopWorker(body.accountId);
+            json(res, 200, { requestId, data: { stopped: true } });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/messages/text") {
+            const body = parseBody(bodyText, sendTextSchema);
+            const account = resolveAccountOrThrow(body.accountId);
+            const ctx = body.contextToken || contextTokenCache.get(keyForContext(body.accountId, body.to));
+            if (!ctx)
+                throw new Error("contextToken is required (no cached token for this user)");
+            const out = await sendMessage({
+                account,
+                to: body.to,
+                contextToken: ctx,
+                itemList: [{ type: 1, text_item: { text: body.text } }],
+            });
+            json(res, 200, { requestId, data: out });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/messages/image") {
+            const body = parseBody(bodyText, sendImageSchema);
+            const account = resolveAccountOrThrow(body.accountId);
+            const ctx = body.contextToken || contextTokenCache.get(keyForContext(body.accountId, body.to));
+            if (!ctx)
+                throw new Error("contextToken is required (no cached token for this user)");
+            const out = await sendImage({
+                account,
+                to: body.to,
+                text: body.text,
+                contextToken: ctx,
+                filePath: body.filePath,
+                imageUrl: body.imageUrl,
+            });
+            json(res, 200, { requestId, data: out });
+            return;
+        }
+        if (method === "GET" && url.pathname === "/v1/events") {
+            const accountId = String(url.searchParams.get("accountId") || "").trim();
+            const limit = Math.min(500, Math.max(1, Number(url.searchParams.get("limit") || "100")));
+            const cursor = String(url.searchParams.get("cursor") || "").trim() || undefined;
+            if (!accountId)
+                throw new Error("accountId is required");
+            const events = loadEvents()
+                .filter((e) => e.accountId === accountId && !e.ackedAt)
+                .sort((a, b) => a.createdAt - b.createdAt);
+            const start = cursor ? Math.max(0, events.findIndex((e) => e.id === cursor) + 1) : 0;
+            const items = events.slice(start, start + limit);
+            const nextCursor = items.length ? items[items.length - 1].id : null;
+            json(res, 200, { requestId, data: { items, nextCursor } });
+            return;
+        }
+        if (method === "POST" && url.pathname === "/v1/events/ack") {
+            const body = parseBody(bodyText, ackSchema);
+            const set = new Set(body.ids);
+            const events = loadEvents();
+            let count = 0;
+            for (const ev of events) {
+                if (ev.accountId !== body.accountId)
+                    continue;
+                if (!set.has(ev.id))
+                    continue;
+                if (ev.ackedAt)
+                    continue;
+                ev.ackedAt = Date.now();
+                count += 1;
+            }
+            saveEvents(events);
+            json(res, 200, { requestId, data: { acked: count } });
+            return;
+        }
+        json(res, 404, { requestId, error: "not found" });
+    }
+    catch (err) {
+        json(res, 400, {
+            requestId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function main() {
+    ensureStateDir();
+    bootWorkers();
+    const server = http.createServer((req, res) => {
+        void handle(req, res);
+    });
+    server.listen(API_PORT, API_HOST, () => {
+        console.log("[standalone-api] listening on http://" + API_HOST + ":" + API_PORT);
+        if (API_TOKEN) {
+            console.log("[standalone-api] auth enabled via Authorization: Bearer <token>");
+        }
+        else {
+            console.log("[standalone-api] auth disabled (set WEIXIN_STANDALONE_TOKEN to enable)");
+        }
+    });
+}
+main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dadb/weixin-standalone-api",
+  "version": "0.1.0",
+  "description": "Standalone Weixin bot API server with QR login, inbound polling, and send message/image endpoints",
+  "license": "MIT",
+  "author": "dadb",
+  "type": "module",
+  "bin": {
+    "weixin-standalone-api": "./bin/weixin-standalone-api.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "dev": "node --experimental-strip-types ./src/index.ts",
+    "start": "node ./dist/index.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "version:bump": "node ./scripts/release-version.mjs",
+    "prepack": "npm run clean && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.3"
+  }
+}