KOOK SDK 开发文档

KOOK 开放平台 JavaScript SDK，提供双模式：简单 API（快速上手）与完整客户端（discord.js 风格：事件 + 缓存 + 模型），覆盖服务器、频道、消息、语音、OAuth 等 21 个服务模块。

一、安装

npm install @gedaxin/kook

要求 Node.js ≥ 18。依赖：axios ^1.7.0。

二、快速开始

模式 A：简单 API（推荐快速上手）

import kook from '@gedaxin/kook';

kook.etc.token('your-bot-token');          // 设置 Token

const { items } = await kook.guild.list({}); // 获取服务器列表

await kook.message.create({                 // 发送消息
  channel_id: '123456789',
  type: 1,                                  // 文字消息
  content: 'Hello KOOK!'
});

const all = await kook.paginate(kook.guild.list); // 自动分页获取全量

模式 B：完整客户端（discord.js 风格）

import { Client } from '@gedaxin/kook';

const client = new Client({ token: 'your-bot-token' });

client.on('messageCreate', msg => {
  console.log(msg.content);
});
client.on('ready', () => console.log('Bot 已就绪'));

await client.login(); // 自动获取 Gateway 并建立 WebSocket 连接

三、客户端配置

四、缓存与 fetch（discord.js 风格）

所有 Manager 均支持 Collection 风格操作：

client.guilds.cache.get(guildId);                      // 缓存查询
client.guilds.cache.filter(ch => ch.isText);           // 链式过滤
client.guilds.cache.find(g => g.name === 'My Guild');  // 条件查找
client.guilds.cache.some(g => g.level > 5);            // 条件判断

// fetch：缓存命中直接返回，未命中自动请求 API
const channel = await client.channels.fetch(channelId);
const user    = await client.users.fetch(userId);
const guild   = await client.guilds.fetch(guildId);
const member  = await client.guilds.cache.get(gid).members.fetch(uid);

// 快捷方法
await client.fetchGuilds();        // 获取全部服务器（带缓存）
await client.sendMessage({ channel_id: 'xxx', content: 'hello' });

// 模型自我刷新
await guild.fetch();               // 刷新 Guild 数据

五、事件列表

六、服务接口一览（21 个模块）

七、工具与错误处理

import { paginate, Snowflake, Constants, KookAPIError } from '@gedaxin/kook';

const allGuilds = await paginate(kook.guild.list);   // 自动分页
Snowflake.getTimestamp('1704067200000');              // ID 解析时间戳
Constants.MessageType.TEXT;                            // 1

try {
  await kook.message.create({ ... });
} catch (err) {
  if (err instanceof KookAPIError) {
    if (err.isPermissionDenied) { /* 权限不足 */ }
    if (err.isNotFound)         { /* 资源不存在 */ }
  }
}

八、模型类

所有 API 返回数据自动封装为模型实例：

const { items } = await kook.guild.list({});
items.forEach(guild => {
  console.log(guild.name, guild.ownerId, guild.memberCount, guild.icon);
});

const user = new User({ id: 'xxx', username: 'test' });
console.log(user.avatarURL(128)); // 头像 URL

九、架构