Skip to content

About

微寻微信协议 API 的 TypeScript/Node.js SDK:226 个接口、大整数安全、实时消息

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

weixun-node

微寻微信协议 API 的 TypeScript / Node.js SDK。

覆盖 226 个客户可用接口,强类型、内置限速、大整数安全,配套 WebSocket 实时消息与扫码登录。

安装

npm install weixun

Node.js 18+(需内置 fetch)

快速开始

import { Client } from 'weixun';

const c = new Client('http://127.0.0.1:7006', '你的协议 license Key');

const res = await c.message.sendText({ to: 'wxid_xxxxx', text: '订单已发货' });
if (!res.ok) console.error('发送失败:', res.errorMessage);

// 实时收消息
const stream = c.message; // 见下方 Stream
import { Stream } from 'weixun';
new Stream(c, {
  onMessage: (m) => console.log(m.from, m.content),
}).start();

核心设计

这个 SDK 不是简单的 HTTP 包装,它把 API 实际使用中容易踩的坑都处理掉了。

1. 成功判定不是看 HTTP 状态码

API 绝大多数情况都返回 HTTP 200,成败在响应体的 Code 字段。 而且 Code 可能是数字 200,也可能是字符串 "200"。

判定顺序:

  1. Code 存在且为 0 或 200 → 成功
  2. Code 不存在 → 回退 Success == true
  3. 都无法判定 → 失败

关键反例:/user/SetProxy 返回 Code=200 但 Success 缺失或为 false, 所以不能用 Success == true 作为主判据。

2. 64 位 ID 一律用字符串

new_msg_id 这类字段超过 2^53,JS 的 JSON.parse 会静默截断。 部分接口已做字符串化处理,其余仍是裸数字。

SDK 在契约层就把 23 个 64 位字段声明为 string。

3. 内置限速(服务端不限流)

服务端不对请求做频率限制:并发猛发不会收到错误码,而是直接承担微信侧的风控后果。

SDK 默认 40 条/分钟(官方风控建议)。关闭需显式配置,请自行承担风险。

4. 逐条结果字段不统一

批量发送接口返回数组,但:

  • 接收方字段有两种拼写:toUSerName(14 处)与 toUserName(9 处)
  • 成功标志有 7 种命名:isSendSuccess / isCommentSuccess / isMarkSuccess / …
  • 错误信息有拼写错误:errMgs(UploadFriendCircleImage)

SDK 统一归一化为 ok / to / errorMessage。

5. 登录状态机

5 个状态(waiting / login_processing / ipad_required / online / security_verify_required)+ 13 个 reasonCode。轮询节奏建议 2.5 秒(官方推荐)。

目录结构

src/
├── index.ts       公共导出
├── client.ts      Client + 统一调用出口
├── envelope.ts    信封判定 + parseJSONSafe(大整数保护)
├── message.ts     消息服务 + 逐条结果归一化
├── stream.ts      WebSocket 流
├── login.ts       扫码登录状态机
├── upload.ts      multipart + base64
└── ratelimit.ts   令牌桶

接口契约

contract/weixun-api.json 是本 SDK 覆盖的接口定义(OpenAPI 3.0),共 226 个端点。 已修正 64 位整数精度、空引用、非标准类型等问题。

接口若有版本更新,运行 scripts/sync-contract.sh 同步契约后重新生成模型即可。 contract/CONTRACT_VERSION 记录当前契约版本,便于追溯。

测试

npm test

测试读取 conformance/fixtures/ 下的行为样本,七个语言跑同一套断言, 任何语言行为不一致都会被发现。

边界

  • 本 SDK 是非微信官方接口的客户端,与腾讯无关
  • 账号风控由使用者自行承担,建议先用测试 Key 验证
  • 微寻只提供收发消息的通道,机器人逻辑与知识库都在调用方自己的程序里

许可证

MIT

About

微寻微信协议 API 的 TypeScript/Node.js SDK:226 个接口、大整数安全、实时消息

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages