NapCat SDK

@aemeath-projects/napcat 是 NapCat / OneBot 11 协议的全功能 TypeScript SDK。

特性

• 四种连接方式 — 正向 WS、反向 WS、HTTP、HTTP-SSE
• 完整 API 封装 — 消息、群管理、好友、文件、系统、扩展
• 类型安全 — 所有 API 返回 Result<T> 类型
• Tree-shaking — 按需导入，不用的模块不会打包

安装

pnpm add @aemeath-projects/napcat

快速示例

import {
  NapCatClient,
  WebSocketTransport,
  MessageApi,
  Seg,
} from '@aemeath-projects/napcat'

const transport = new WebSocketTransport({
  url: 'ws://localhost:3001',
  token: 'your-access-token',
  reconnect: { initialDelay: 1000, maxDelay: 30000 },
})

const client = new NapCatClient(transport)
const msg = new MessageApi(client)

client.on('message.group', async (event) => {
  if (event.raw_message === 'ping') {
    const result = await msg.sendGroupMsg(event.group_id, [Seg.text('pong')])
    if (!result.ok) {
      console.error('发送失败:', result.error.message)
    }
  }
})

await client.connect()

模块总览

模块	说明
NapCatClient	客户端，管理与 NapCat 的连接与事件分发
MessageApi	消息收发（私聊、群聊、合并转发）
GroupApi	群管理（成员、禁言、公告、相册）
FriendApi	好友操作（列表、备注、请求处理）
FileApi	文件上传/下载/管理
SystemApi	系统信息查询与账号设置
ExtensionApi	NapCat 扩展功能（戳一戳、AI 语音、自定义表情）
Seg	消息段构造器（21 种类型）

导航

• 快速开始 — 详细的接入指南
• 连接方式 — 四种 Transport 详解
• 消息段 — Seg 类型参考
• API 参考 — 完整 API 文档