@kookapp/im-socket

KOOK IM 传输内核 — 平台无关的 WebSocket 连接管理。

是什么

@kookapp/im-socket 是 KOOK IM 三层架构的第一层（传输内核），负责：

• WebSocket 连接与 Gateway 获取
• 状态机、心跳保活、断线重连
• 帧协议编解码、SN 重排、Resume 续传

本包不直接面向业务，由上层适配器（如 WebIMLibAdapter）封装后使用。详细架构与状态机见 architecture.md。

快速使用

浏览器环境

import { IMSocket } from '@kookapp/im-socket'

const transport = new IMSocket({
  token: 'Bearer xxx',
  gatewayURL: 'https://api.kookapp.cn',
  compress: 1,
})

transport.on('message', (frame) => { /* 业务消息 */ })
transport.on('statechange', ({ from, to }) => { /* 状态变更 */ })

transport.start()

Node.js 环境

通过 createSocket 注入 ws 包，无需污染全局 WebSocket：

import WebSocket from 'ws'
import { IMSocket } from '@kookapp/im-socket'

const transport = new IMSocket({
  token: 'Bot xxx',
  gatewayURL: 'https://www.kookapp.cn',
  compress: 0,
  createSocket: (url) => new WebSocket(url),
  gatewayProvider: async () => {
    const res = await fetch('https://www.kookapp.cn/api/v3/gateway/index?compress=0', {
      headers: { Authorization: 'Bot xxx' },
    })
    const data = await res.json()
    return { url: data.data.url }
  },
})

transport.on('message', (frame) => { /* 业务消息 */ })
transport.start()

更多 API、扩展点与常量见 architecture.md。

依赖

• eventemitter3
• pako

零平台依赖，默认使用全局 WebSocket。Node.js 环境可通过 createSocket 注入 ws 等第三方实现。