@dadb/weixin-standalone-api 0.1.0 → 0.1.1

package/README.md

@@ -1,32 +1,32 @@
 # 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
+独立的微信机器人 API 服务（不依赖 OpenClaw 运行时）。
 
-Chinese doc: [README.zh-CN.md](./README.zh-CN.md)
-
-## Requirements
+### 功能
+- 手机微信扫码登录
+- 入站消息轮询 + 本地事件队列
+- 文本/图片发送接口
+- 账号与 worker 管理接口
 
+### 运行要求
 - Node.js `>=22`
-- Reachable Weixin iLink bot backend
+- 可访问的微信 iLink bot 后端
 
-## Install
+### 安装
 
 ```bash
-npm i -g weixin-standalone-api
+npm i -g @dadb/weixin-standalone-api
 ```
 
-or:
+或：
 
 ```bash
-npm i weixin-standalone-api
+npm i @dadb/weixin-standalone-api
 ```
 
-## Run
+### 启动
 
 ```bash
 WEIXIN_STANDALONE_TOKEN='replace_me' \
@@ -35,322 +35,231 @@ WEIXIN_STANDALONE_PORT='8788' \
 weixin-standalone-api
 ```
 
-## Environment Variables
+### 环境变量
+- `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`: 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:
+设置了 `WEIXIN_STANDALONE_TOKEN` 后，除 `/healthz` 外都要带：
 
 ```http
 Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>
 ```
 
-## Response Format
+### 返回格式
 
-Success:
+成功：
 
 ```json
-{
-  "requestId": "uuid",
-  "data": {}
-}
+{ "requestId": "uuid", "data": {} }
 ```
 
-Error:
+失败：
 
 ```json
-{
-  "requestId": "uuid",
-  "error": "error message"
-}
+{ "requestId": "uuid", "error": "错误信息" }
 ```
 
-## API Reference
-
-### 1) Health
+### API 说明
 
 `GET /healthz`
 
-Response:
-
-```json
-{ "ok": true, "requestId": "..." }
-```
-
-### 2) QR Login Start
-
 `POST /v1/login/qr/start`
 
-Body:
-
+请求体：
 ```json
-{
-  "accountId": "optional",
-  "botType": "optional",
-  "baseUrl": "optional"
-}
+{ "accountId": "可选", "botType": "可选", "baseUrl": "可选" }
 ```
 
-Response:
-
+返回：
 ```json
-{
-  "requestId": "...",
-  "data": {
-    "sessionKey": "...",
-    "qrcodeUrl": "..."
-  }
-}
+{ "requestId": "...", "data": { "sessionKey": "...", "qrcodeUrl": "..." } }
 ```
 
-### 3) QR Login Wait
-
 `POST /v1/login/qr/wait`
 
-Body:
-
+请求体：
 ```json
-{
-  "sessionKey": "...",
-  "timeoutMs": 480000
-}
+{ "sessionKey": "...", "timeoutMs": 480000 }
 ```
 
-Response:
-
+返回：
 ```json
-{
-  "requestId": "...",
-  "data": {
-    "connected": true,
-    "accountId": "xxx-im-bot",
-    "userId": "xxx@im.wechat"
-  }
-}
+{ "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"
+  "contextToken": "可选"
 }
 ```
 
-Notes:
-- `contextToken` is required by upstream. If omitted, server will try cached token for `(accountId,to)`.
-
-### 8) Send Image
+说明：`contextToken` 是上游会话关键字段；不传则尝试命中缓存 `(accountId,to)`。
 
 `POST /v1/messages/image`
 
-Body (local file):
-
+请求体（本地文件）：
 ```json
 {
   "accountId": "xxx-im-bot",
   "to": "target@im.wechat",
   "filePath": "/tmp/a.jpg",
-  "text": "optional",
-  "contextToken": "optional"
+  "text": "可选",
+  "contextToken": "可选"
 }
 ```
 
-Body (remote URL):
-
+请求体（远程 URL）：
 ```json
 {
   "accountId": "xxx-im-bot",
   "to": "target@im.wechat",
   "imageUrl": "https://example.com/a.jpg",
-  "text": "optional",
-  "contextToken": "optional"
+  "text": "可选",
+  "contextToken": "可选"
 }
 ```
 
-Constraints:
-- Exactly one of `filePath` or `imageUrl`
-- `imageUrl` must be `https`
-- Max image size: 20 MB
-
-### 9) Pull Events
+约束：`filePath`/`imageUrl` 二选一；`imageUrl` 必须 https；最大 20MB。
 
 `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
+参数：`accountId` 必填，`limit` 可选（1..500，默认 100），`cursor` 可选。
 
 `POST /v1/events/ack`
 
-Body:
-
+请求体：
 ```json
-{
-  "accountId": "xxx-im-bot",
-  "ids": ["event-id-1", "event-id-2"]
-}
+{ "accountId": "xxx-im-bot", "ids": ["event-id-1", "event-id-2"] }
 ```
 
-Response:
-
+返回：
 ```json
-{
-  "requestId": "...",
-  "data": { "acked": 2 }
-}
+{ "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`
+### 最小联调流程
+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` 确认消费
 
-## Development
+### 开发与发布
 
 ```bash
 npm install
 npm run dev
-```
-
-Build:
-
-```bash
+npm run typecheck
 npm run build
-npm run start
+npm run version:bump
+npm publish
 ```
 
-Typecheck:
+---
 
-```bash
-npm run typecheck
-```
+## English
+
+Standalone Weixin bot API server without OpenClaw runtime dependency.
 
-## Versioning
+### Features
+- QR login via mobile Weixin app
+- inbound polling + local event queue
+- send text/image APIs
+- account and worker management
 
-Patch:
+### Install
 
 ```bash
-npm run version:bump
+npm i -g @dadb/weixin-standalone-api
 ```
 
-Minor:
+### Run
 
 ```bash
-npm run version:bump -- minor
+WEIXIN_STANDALONE_TOKEN='replace_me' \
+WEIXIN_STANDALONE_HOST='127.0.0.1' \
+WEIXIN_STANDALONE_PORT='8788' \
+weixin-standalone-api
 ```
 
-Major:
+### Environment Variables
+- `WEIXIN_STANDALONE_TOKEN`: bearer auth token, optional
+- `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"`
 
-```bash
-npm run version:bump -- major
+### Auth
+When token is set, all endpoints except `/healthz` require:
+
+```http
+Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>
 ```
 
-Set exact:
+### Response
+Success:
 
-```bash
-npm run version:bump -- 1.2.3
+```json
+{ "requestId": "uuid", "data": {} }
 ```
 
-## Publish
+Error:
 
-```bash
-npm login
-npm publish
+```json
+{ "requestId": "uuid", "error": "message" }
 ```
+
+### Endpoints
+- `GET /healthz`
+- `POST /v1/login/qr/start`
+- `POST /v1/login/qr/wait`
+- `GET /v1/accounts`
+- `POST /v1/workers/start`
+- `POST /v1/workers/stop`
+- `POST /v1/messages/text`
+- `POST /v1/messages/image`
+- `GET /v1/events`
+- `POST /v1/events/ack`
+
+### Minimal Flow
+1. Start server
+2. Call `/v1/login/qr/start`
+3. Scan QR with mobile Weixin app
+4. Poll `/v1/login/qr/wait` until `connected=true`
+5. Pull inbound events from `/v1/events`
+6. Reply with `/v1/messages/text` or `/v1/messages/image`
+7. Ack via `/v1/events/ack`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dadb/weixin-standalone-api",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone Weixin bot API server with QR login, inbound polling, and send message/image endpoints",
   "license": "MIT",
   "author": "dadb",
@@ -12,7 +12,6 @@
     "bin/",
     "dist/",
     "README.md",
-    "README.zh-CN.md",
     "LICENSE"
   ],
   "scripts": {

package/README.zh-CN.md

@@ -1,309 +0,0 @@
-# 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
-```