open-index/open-npm huggingface dataset:
npm package: @kookapp/im-socket
Description: IM WebSocket connection handling library
Author: KOOK
Latest version: 0.0.2

# @kookapp/im-socket

KOOK IM 传输内核 — 平台无关的 WebSocket 连接管理。

## 是什么

`@kookapp/im-socket` 是 KOOK IM 三层架构的**第一层（传输内核）**，负责：

- WebSocket 连接与 Gateway 获取
- 状态机、心跳保活、断线重连
- 帧协议编解码、SN 重排、Resume 续传

本包不直接面向业务，由上层适配器（如 `WebIMLibAdapter`）封装后使用。详细架构与状态机见 [architecture.md](./architecture.md)。

## 快速使用

### 浏览器环境

```javascript
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`：

```javascript
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](./architecture.md)。

## 依赖

- `eventemitter3`
- `pako`

零平台依赖，默认使用全局 `WebSocket`。Node.js 环境可通过 `createSocket` 注入 `ws` 等第三方实现。