ZippyBee Pad SDK

简单易用的微信自动化工具包，支持多微信号管理和实时消息监听。

✨ 特性

• 🔥 多微信号支持 - 同时管理多个微信号
• ⚡ 实时消息 - WebSocket 实时推送，自动重连
• 🛠️ 动态 API - 基于 Swagger 自动生成方法
• 🎯 简单易用 - 简洁的 API 设计，易于上手
• 📝 TypeScript - 完整类型支持

安装

npm install zippybee-pad

快速开始

初始化

import { WcfPad } from "zippybee-pad";

const wcf = WcfPad.getInstance({
  baseURL: "http://localhost:8080", // 服务地址
  wsPort: 9001, // WebSocket 端口
});

登录微信

// 扫码登录
await wcf.login(
  {
    loginType: "mac",
  },
  (loginData) => {
    console.log("登录成功:", loginData);
  },
);

console.log("二维码信息:", result.Data?.QrCodeUrl);

### 3. 监听消息

```typescript
// 监听单个微信号消息
### 监听消息

```typescript
# ZippyBee Pad SDK

简单易用的微信自动化工具包，支持多微信号管理和实时消息监听。

## ✨ 特性

- 🔥 **多微信号支持** - 同时管理多个微信号
- ⚡ **实时消息** - WebSocket 实时推送，自动重连
- 🛠️ **动态 API** - 基于 Swagger 自动生成方法
- 🎯 **简单易用** - 简洁的 API 设计，易于上手
- 📝 **TypeScript** - 完整类型支持

## 📦 安装

```bash
npm install zippybee-pad
```

## 🚀 快速开始

### 1. 初始化

```typescript
import { WcfPad } from "zippybee-pad";

const wcf = WcfPad.getInstance({
  baseURL: "http://localhost:8080",  // 服务地址
  wsPort: 9001,                      // WebSocket 端口
  timeout: 6000,                     // 可选，超时时间
});
```

### 2. 登录微信

```typescript
// 扫码登录
const result = await wcf.login({
  loginType: "mac"  // 或 "car"
}, (loginData) => {
  console.log("登录成功:", loginData);
});

console.log("二维码链接:", result.Data?.QrCodeUrl);
```

### 3. 监听消息

```typescript
// 监听单个微信号消息
const unsubscribe = wcf.listen("wxid_123", (message) => {
  console.log("收到消息:", message);
});

// 监听多个微信号
const unsubscribe1 = wcf.listen("wxid_1", handleMessages);
const unsubscribe2 = wcf.listen("wxid_2", handleMessages);

// 取消监听
unsubscribe1();
```

### 4. 发送消息

```typescript
// 发送文本消息
await wcf.SendTextMsg({
  wxid: "friend_wxid",
  msg: "Hello World!",
});

// 发送图片
await wcf.SendImgMsg({
  wxid: "friend_wxid",
  path: "/path/to/image.jpg",
});

// 发送文件
await wcf.SendFileMsg({
  wxid: "friend_wxid",
  path: "/path/to/file.pdf",
});
```

### 5. 管理连接

```typescript
// 手动连接
wcf.connect("wxid_123");

// 断开连接
wcf.disconnectConnection("wxid_123");

// 查看连接状态
const state = wcf.getConnectionState("wxid_123");
console.log(state); // 'OPEN', 'CONNECTING', 'CLOSED' 等

// 获取所有已连接的微信号
const connectedIds = wcf.getConnectedWxIds();

// 清理无用连接
const cleaned = wcf.cleanupIdleConnections();
```

发送消息

// 发送文本消息
await wcf.SendTextMsg({
  wxid: "friend_wxid",
  msg: "Hello World!",
});

// 发送图片
await wcf.SendImgMsg({
  wxid: "friend_wxid",
  path: "/path/to/image.jpg",
});

管理连接

// 手动连接
wcf.connect("wxid_123");

// 断开连接
wcf.disconnectConnection("wxid_123");

// 查看连接状态
const state = wcf.getConnectionState("wxid_123");
console.log(state); // 'OPEN', 'CONNECTING', 'CLOSED' 等

// 获取所有已连接的微信号
const connectedIds = wcf.getConnectedWxIds();

🛠️ API 参考

配置选项

interface WcfPadOption {
  baseURL: string; // 服务地址
  wsPort: number; // WebSocket 端口
  timeout?: number; // 超时时间，默认 6000ms
}

核心方法

实例管理

• WcfPad.getInstance(config) - 获取单例实例

登录认证

• login(params, callback) - 登录微信
• checkLogin(uuid, timeout) - 检查登录状态

消息监听

• listen(wx_id, callback) - 监听消息，返回取消函数
• getListenerCount(wx_id) - 获取监听器数量

连接管理

• connect(wx_id) - 连接指定微信号
• disconnectConnection(wx_id) - 断开指定连接
• disconnect() - 断开所有连接
• cleanupIdleConnections() - 清理无用连接

状态查询

• getConnectionState(wx_id) - 获取连接状态
• getConnectedWxIds() - 获取已连接的微信号列表
• getAllConnectionStates() - 获取所有连接状态

消息发送

• send(wx_id, message, immediate?) - 发送 WebSocket 消息

性能监控

• getPerformanceStats() - 获取性能统计
• getOptimizationSuggestions() - 获取优化建议

重连设置

• setReconnectConfig(maxAttempts, interval) - 设置重连参数

动态 API 方法

所有 Swagger 定义的方法都会自动注册到实例上，常用的包括：

// 消息发送
await wcf.SendTextMsg(params); // 发送文本
await wcf.SendImgMsg(params); // 发送图片
await wcf.SendFileMsg(params); // 发送文件
await wcf.SendEmojiMsg(params); // 发送表情

// 系统操作
await wcf.IsRunning(); // 检查运行状态
await wcf.GetUserInfo(); // 获取用户信息
await wcf.GetContactList(); // 获取联系人列表
await wcf.GetChatRoomList(); // 获取群聊列表

// 二维码相关
await wcf.GetQRCode(params); // 获取登录二维码
await wcf.CheckUuid(params); // 检查登录状态

📋 完整示例

import { WcfPad } from "zippybee-pad";

async function main() {
  // 1. 初始化
  const wcf = WcfPad.getInstance({
    baseURL: "http://localhost:8080",
    wsPort: 9001,
  });

  // 2. 设置重连参数
  wcf.setReconnectConfig(5, 3000);

  // 3. 登录微信
  const loginResult = await wcf.login(
    {
      loginType: "mac",
    },
    (loginData) => {
      console.log("🎉 登录成功!", loginData);

      // 4. 登录成功后开始监听消息
      const wx_id = loginData.WxId;

      const unsubscribe = wcf.listen(wx_id, async (message) => {
        console.log("📨 收到新消息:", message);

        // 5. 自动回复逻辑
        if (message.type === "text") {
          await wcf.SendTextMsg({
            wxid: message.sender,
            msg: `收到您的消息: ${message.content}`,
          });
        }
      });

      // 6. 定时清理无用连接
      setInterval(() => {
        const cleaned = wcf.cleanupIdleConnections();
        if (cleaned > 0) {
          console.log(`清理了 ${cleaned} 个空闲连接`);
        }
      }, 300000); // 5分钟清理一次
    },
  );

  console.log("📱 请扫描二维码:", loginResult.Data?.QrCodeUrl);
}

main().catch(console.error);

🔧 性能监控

// 获取性能统计
const stats = wcf.getPerformanceStats();
console.log("性能统计:", stats);

// 获取优化建议
const suggestions = wcf.getOptimizationSuggestions();
suggestions.forEach((suggestion) => {
  console.log("建议:", suggestion);
});

❓ 常见问题

Q: 如何确保连接稳定？

A: SDK 内置了自动重连机制，支持指数退避重连策略。可通过 setReconnectConfig() 调整参数。

Q: 可以同时连接多少个微信号？

A: 理论上没有限制，建议根据服务器性能合理控制。可通过 getPerformanceStats() 监控。

Q: 如何处理消息丢失？

A: SDK 提供了消息队列和批量发送机制，确保消息可靠传输。

Q: API 方法如何调用？

A: 所有 Swagger 定义的方法都会自动注册到 WcfPad 实例上，可以直接调用。

Q: 如何调试连接问题？

A: 使用 getConnectionState() 查看状态，getPerformanceStats() 查看统计信息。

📝 注意事项

1. 单例模式: WcfPad.getInstance() 始终返回同一个实例
2. 自动管理: WebSocket 连接会根据监听器自动连接/断开
3. 错误隔离: 单个连接的错误不会影响其他连接
4. 内存管理: 记得调用返回的取消函数来清理监听器
5. 重连机制: 支持指数退避的自动重连策略
6. 性能监控: 定期调用 cleanupIdleConnections() 清理无用连接

🤝 贡献

欢迎提交 Issues 和 Pull Requests！

📄 许可证

MIT License