napcat-sdk 0.1.0 → 0.1.2

package/readme.md

@@ -0,0 +1,70 @@
+# NapCat SDK for TypeScript
+
+## Getting Started
+
+The NapCat SDK for TypeScript allows developers to easily integrate NapCat's functionalities into their TypeScript applications. This SDK provides a set of tools and utilities to interact with NapCat services seamlessly.
+
+## Installation
+
+You can install the NapCat SDK via npm. Run the following command in your terminal:
+
+```bash
+pnpm install napcat-sdk
+```
+
+## Quick Start
+
+To connect to NapCat, you need to create an instance of the NapCat client. Here's a simple example:
+
+```typescript
+import { NapCat, segment } from 'napcat-sdk'
+
+// 1. Create a new NapCat client instance
+const napcat = new NapCat({
+  // protocol: 'ws', // Optional: specify the protocol (default is 'ws')
+  // host: 'localhost', // Optional: specify a custom host
+  // port: 3333, // Optional: specify a custom port
+  token: 'here-your-auth-token', // Required: your authentication token
+})
+
+// 2. Subscribe to events
+napcat.on('message', (event) => {
+  // replay is a method to send a message quickly, optional with reply mark
+  event.reply('Hello from NapCat SDK!', true) // true is for reply mark
+
+  // you can call all the NapCat api through `napcat.api()` method
+  const { value } = await napcat.api<{ value: unknown }>('awesome-function')
+})
+
+// you can also listen to specific message sub-types
+napcat.on('message.group', async (event) => {
+  // all methods of a message event are available
+  await event.addEssence(event.message_id)
+  await event.recall()
+
+  // You can also interact with group instance to do some operations
+  await event.group.setTitle(114514, 'Special Title')
+
+  // message to send is allowed to be an array of segments
+  await event.reply(['Hi! ', napcat.segment.face(66)])
+
+  // or just use napcat to send messages
+  await napcat.sendGroupMsg(event.group_id, 'Hello Group!')
+})
+
+// and more events...
+napcat.on('notice', (event) => {})
+napcat.on('notice.group', (event) => {})
+napcat.on('request', (event) => {})
+napcat.on('request.group.invite', (event) => {
+  // approve the group invite request, or event.reject() to reject
+  event.approve() 
+})
+
+// close the connection when needed
+napcat.close() 
+```
+
+## License
+
+MIT License © 2025-PRESENT Viki

package/.node-version

@@ -1 +0,0 @@
-24.11.1

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from './napcat'
-export * from './logger'
-export * from './types'
-export * from './segment'

package/src/logger.ts

@@ -1,27 +0,0 @@
-export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
-
-export type Logger = Record<LogLevel, (...args: unknown[]) => void>
-
-const LOG_LEVELS: Record<LogLevel, number> = {
-  fatal: 0,
-  error: 1,
-  warn: 2,
-  info: 3,
-  debug: 4,
-  trace: 5,
-}
-
-const LOG_LEVEL_KEYS = Object.keys(LOG_LEVELS) as LogLevel[]
-
-const noop = () => {}
-
-export const ABSTRACT_LOGGER: Logger = Object.fromEntries(LOG_LEVEL_KEYS.map((level) => [level, noop])) as Logger
-
-export const CONSOLE_LOGGER: Logger = Object.fromEntries(
-  LOG_LEVEL_KEYS.map((level) => [
-    level,
-    (...args: unknown[]) => {
-      console[level === 'fatal' ? 'error' : level === 'trace' ? 'debug' : level](...args)
-    },
-  ]),
-) as Logger

package/src/napcat.ts

@@ -1,497 +0,0 @@
-import crypto from 'node:crypto'
-import mitt from 'mitt'
-import pkg from '../package.json' with { type: 'json' }
-import { segment } from './segment'
-import { CONSOLE_LOGGER, ABSTRACT_LOGGER } from './logger'
-import { NAPCAT_NOTICE_EVENT_MAP, NAPCAT_NOTICE_NOTIFY_MAP } from './onebot'
-
-import type { Emitter } from 'mitt'
-import type { Logger } from './logger'
-import type { EventMap, MiokiOptions, OptionalProps } from './types'
-import type {
-  API,
-  Friend,
-  FriendWithInfo,
-  Group,
-  GroupMessageEvent,
-  GroupWithInfo,
-  NormalizedElementToSend,
-  PrivateMessageEvent,
-  Sendable,
-} from './onebot'
-
-export const name = pkg.name
-export const version = pkg.version
-
-export { CONSOLE_LOGGER, ABSTRACT_LOGGER, pkg as PKG }
-
-export const DEFAULT_NAPCAT_OPTIONS = {
-  protocol: 'ws',
-  host: 'localhost',
-  port: 3333,
-  logger: ABSTRACT_LOGGER,
-} satisfies Required<OptionalProps<MiokiOptions>>
-
-export class NapCat {
-  /** WebSocket 实例 */
-  #ws: WebSocket | null = null
-  /** 事件发射器 */
-  #event: Emitter<EventMap & Record<string | symbol, unknown>> = mitt()
-  /** Echo 事件发射器 */
-  #echoEvent: Emitter<Record<string, unknown>> = mitt()
-
-  constructor(private readonly options: MiokiOptions) {}
-
-  /** 配置项 */
-  get #config(): Required<MiokiOptions> {
-    return {
-      protocol: this.options.protocol || DEFAULT_NAPCAT_OPTIONS.protocol,
-      host: this.options.host || DEFAULT_NAPCAT_OPTIONS.host,
-      port: this.options.port || DEFAULT_NAPCAT_OPTIONS.port,
-      logger: this.options.logger || DEFAULT_NAPCAT_OPTIONS.logger,
-      token: this.options.token,
-    }
-  }
-
-  /** WebSocket 实例 */
-  get ws(): WebSocket {
-    if (!this.#ws) {
-      this.logger.error('WebSocket is not connected.')
-      throw new Error('WebSocket is not connected.')
-    }
-
-    return this.#ws
-  }
-
-  /** 日志记录器 */
-  get logger(): Logger {
-    return this.#config.logger
-  }
-
-  /** 消息段构建器 */
-  get segment(): typeof segment {
-    return segment
-  }
-
-  /** 生成唯一的 echo ID */
-  #echoId() {
-    return crypto.randomBytes(16).toString('hex')
-  }
-
-  /** 构建 WebSocket 连接地址 */
-  #buildWsUrl(): string {
-    return `${this.#config.protocol}://${this.#config.host}:${this.#config.port}?access_token=${this.#config.token}`
-  }
-
-  /** 包装回复消息 */
-  #wrapReply(sendable: Sendable | Sendable[], message_id?: number, reply?: boolean): Sendable[] {
-    const sendableList = typeof sendable === 'string' ? [sendable] : [sendable].flat()
-
-    if (reply && message_id) {
-      return [segment.reply(String(message_id)), ...sendableList]
-    }
-
-    return sendableList
-  }
-
-  /** 确保 WebSocket 已连接 */
-  #ensureWsConnection(ws: WebSocket | null): asserts ws is WebSocket {
-    if (!ws) {
-      this.logger.error('WebSocket is not connected.')
-      throw new Error('WebSocket is not connected.')
-    }
-
-    if (ws.readyState !== WebSocket.OPEN) {
-      this.logger.error('WebSocket is not open.')
-      throw new Error('WebSocket is not open.')
-    }
-  }
-
-  /** 标准化可发送消息元素 */
-  #normalizeSendable(msg: Sendable | Sendable[]): NormalizedElementToSend[] {
-    return [msg].flat(2).map((item) => {
-      if (typeof item === 'string') {
-        return { type: 'text', data: { text: item } }
-      }
-      if (item.type === 'at') {
-        return { type: 'at', data: { qq: String(item.qq) } }
-      }
-      const { type, ...data } = item
-      return { type, data } as NormalizedElementToSend
-    })
-  }
-
-  /** 等待服务器响应操作 */
-  #waitForAction<T extends any>(echoId: string) {
-    const eventName = `echo#${echoId}`
-
-    return new Promise<T>((resolve, reject) => {
-      const handle = (data: any) => {
-        if (!data || data.echo !== echoId) return
-
-        this.#echoEvent.off(eventName, handle)
-
-        if (data.retcode === 0) {
-          resolve(data.data as T)
-        } else {
-          reject(`Server Error: ${data.message}`)
-        }
-      }
-
-      this.#echoEvent.on(eventName, handle)
-    })
-  }
-
-  /** 构建群对象 */
-  #buildGroup<T extends object>(group_id: number, group_name: string = '', extraInfo: T = {} as T): Group & T {
-    return {
-      ...extraInfo,
-      group_id,
-      group_name,
-      doSign: () => this.api('set_group_sign', { group_id }),
-      getInfo: () => this.api('get_group_info', { group_id }),
-      getMemberList: async () => this.api('get_group_member_list', { group_id }),
-      getMemberInfo: (user_id: number) => this.api('get_group_member_info', { group_id, user_id }),
-      setTitle: (title: string) => this.api('set_group_special_title', { group_id, title }),
-      setCard: (user_id: number, card: string) => this.api('set_group_card', { group_id, user_id, card }),
-      addEssence: (message_id: string) => this.api('set_essence_msg', { message_id }),
-      delEssence: (message_id: string) => this.api('delete_essence_msg', { message_id }),
-      recall: (message_id: number) => this.api('delete_msg', { message_id }),
-      banMember: (user_id: number, duration: number) => this.api('set_group_ban', { group_id, user_id, duration }),
-      sendMsg: (sendable: Sendable | Sendable[]) => this.sendGroupMsg(group_id, sendable),
-    }
-  }
-
-  /** 构建好友对象 */
-  #buildFriend<T extends object>(user_id: number, nickname: string = '', extraInfo: T = {} as T): Friend & T {
-    return {
-      ...extraInfo,
-      user_id,
-      nickname,
-      delete: (block?: boolean, both?: boolean) =>
-        this.api('delete_friend', { user_id, temp_block: block, temp_both_del: both }),
-      sendMsg: (sendable: Sendable | Sendable[]) => this.sendPrivateMsg(user_id, sendable),
-      getInfo: () => this.api('get_stranger_info', { user_id }),
-    }
-  }
-
-  /** 构建群消息事件 */
-  #buildPrivateMessageEvent(event: PrivateMessageEvent) {
-    return {
-      ...event,
-      message: (event.message || []).map((el: any) => ({ type: el.type, ...el.data })),
-      friend: this.#buildFriend(event.user_id, event.sender?.nickname || ''),
-      recall: () => this.api('delete_msg', { message_id: event.message_id }),
-      reply: (sendable: Sendable | Sendable[], reply = false) =>
-        this.sendPrivateMsg(event.user_id, this.#wrapReply(sendable, event.message_id, reply)),
-    }
-  }
-
-  /** 构建群消息事件对象 */
-  #buildGroupMessageEvent(event: GroupMessageEvent) {
-    return {
-      ...event,
-      message: (event.message || []).map((el: any) => ({ type: el.type, ...el.data })),
-      group: this.#buildGroup(event.group_id, event.group?.group_name || ''),
-      recall: () => this.api('delete_msg', { message_id: event.message_id }),
-      addReaction: (id: string) =>
-        this.api('set_msg_emoji_like', { message_id: event.message_id, emoji_id: id, set: true }),
-      delReaction: (id: string) =>
-        this.api('set_msg_emoji_like', { message_id: event.message_id, emoji_id: id, set: false }),
-      addEssence: () => this.api('set_essence_msg', { message_id: event.message_id }),
-      delEssence: () => this.api('delete_essence_msg', { message_id: event.message_id }),
-      reply: (sendable: Sendable | Sendable[], reply = false) =>
-        this.sendGroupMsg(event.group_id, this.#wrapReply(sendable, event.message_id, reply)),
-    }
-  }
-
-  /** 绑定内部事件处理器 */
-  #bindInternalEvents(data: any) {
-    if (data.echo) {
-      this.#echoEvent.emit(`echo#${data.echo}`, data)
-      return
-    }
-
-    if (data.post_type) {
-      switch (data.post_type) {
-        case 'meta_event': {
-          this.logger.trace(`received meta_event: ${JSON.stringify(data)}`)
-          this.#event.emit('meta_event', data)
-
-          if (data.meta_event_type) {
-            this.#event.emit(`meta_event.${data.meta_event_type}`, data)
-            if (data.sub_type) {
-              this.#event.emit(`meta_event.${data.meta_event_type}.${data.sub_type}`, data)
-            }
-          }
-
-          break
-        }
-
-        case 'message': {
-          if (data.message_type === 'private') {
-            data = this.#buildPrivateMessageEvent(data)
-          } else {
-            data = this.#buildGroupMessageEvent(data)
-          }
-
-          this.#event.emit('message', data)
-
-          switch (data.message_type) {
-            case 'private': {
-              this.logger.trace(`received private message: ${JSON.stringify(data)}`)
-              this.#event.emit('message.private', data)
-              this.#event.emit(`message.private.${data.sub_type}`, data)
-
-              break
-            }
-
-            case 'group': {
-              this.logger.trace(`received group message: ${JSON.stringify(data)}`)
-              this.#event.emit('message.group', data)
-              this.#event.emit(`message.group.${data.sub_type}`, data)
-
-              break
-            }
-
-            default: {
-              this.logger.debug(`received unknown message type: ${JSON.stringify(data)}`)
-
-              break
-            }
-          }
-
-          break
-        }
-
-        case 'message_sent': {
-          this.logger.trace(`received message_sent: ${JSON.stringify(data)}`)
-          this.#event.emit('message_sent', data)
-
-          if (data.message_type) {
-            this.#event.emit(`message_sent.${data.message_type}`, data)
-            if (data.sub_type) {
-              this.#event.emit(`message_sent.${data.message_type}.${data.sub_type}`, data)
-            }
-          }
-
-          break
-        }
-
-        case 'notice': {
-          this.logger.trace(`received notice: ${JSON.stringify(data)}`)
-
-          if (!data.notice_type) {
-            this.logger.debug(`received unknown notice type: ${JSON.stringify(data)}`)
-            break
-          }
-
-          const isNotify = data.notice_type === 'notify'
-          const isPoke = data.sub_type === 'poke'
-          const isGroup = !!data.group_id
-
-          const { notice_type, sub_type } = isNotify
-            ? isPoke
-              ? { notice_type: isGroup ? 'group' : 'friend', sub_type: 'poke' }
-              : NAPCAT_NOTICE_NOTIFY_MAP[data.sub_type] || {}
-            : NAPCAT_NOTICE_EVENT_MAP[data.notice_type] || {}
-
-          data.original_notice_type = data.notice_type
-          data.notice_type = notice_type || data.notice_type
-
-          if (data.sub_type && data.sub_type !== sub_type) {
-            data.action_type = data.sub_type
-          }
-
-          data.sub_type = sub_type || data.sub_type
-
-          if (isGroup) {
-            data.group = this.#buildGroup(data.group_id, data.group_name || '')
-          } else {
-            data.friend = this.#buildFriend(data.user_id, data.nickname || '')
-          }
-
-          this.#event.emit('notice', data)
-
-          if (notice_type) {
-            this.#event.emit(`notice.${notice_type}`, data)
-            if (sub_type) {
-              this.#event.emit(`notice.${notice_type}.${sub_type}`, data)
-            }
-          }
-
-          break
-        }
-
-        case 'request': {
-          this.logger.trace(`received request: ${JSON.stringify(data)}`)
-
-          if (data.request_type === 'friend') {
-            data.reject = () => this.api('set_friend_request', { flag: data.flag, approve: false })
-            data.approve = () => this.api('set_friend_request', { flag: data.flag, approve: true })
-          }
-
-          if (data.request_type === 'group') {
-            data.reject = (reason?: string) =>
-              this.api('set_group_add_request', { flag: data.flag, approve: false, reason })
-            data.approve = () => this.api('set_group_add_request', { flag: data.flag, approve: true })
-          }
-
-          this.#event.emit('request', data)
-
-          if (data.request_type) {
-            this.#event.emit(`request.${data.request_type}`, data)
-            if (data.sub_type) {
-              this.#event.emit(`request.${data.request_type}.${data.sub_type}`, data)
-            }
-          }
-
-          break
-        }
-
-        default: {
-          this.logger.debug(`received: ${JSON.stringify(data)}`)
-          this.#event.emit(data.post_type, data)
-          return
-        }
-      }
-
-      return
-    }
-  }
-
-  /** 获取一个群的信息，可以用于发送群消息等操作 */
-  async pickGroup(group_id: number): Promise<GroupWithInfo> {
-    const groupInfo = await this.api<ReturnType<Group['getInfo']>>('get_group_info', { group_id })
-    return this.#buildGroup(group_id, groupInfo.group_name, groupInfo)
-  }
-
-  /** 获取一个好友的信息，可以用于发送私聊消息等操作 */
-  async pickFriend(user_id: number): Promise<FriendWithInfo> {
-    const friendInfo = await this.api<ReturnType<Friend['getInfo']>>('get_stranger_info', { user_id })
-    return this.#buildFriend(user_id, friendInfo.nickname, friendInfo)
-  }
-
-  /**
-   * 注册一次性事件监听器
-   */
-  once<T extends keyof EventMap>(type: T, handler: (event: EventMap[NoInfer<T>]) => void) {
-    const onceHandler = (event: EventMap[NoInfer<T>]) => {
-      handler(event)
-      this.#event.off(type, onceHandler)
-    }
-
-    this.logger.debug(`registering once: ${String(type)}`)
-    this.#event.on(type, onceHandler)
-  }
-
-  /**
-   * 注册事件监听器，支持主类型或者点分子类型
-   *
-   * 如： `notice`、`message.private`、`request.group.invite` 等
-   *
-   * 如果需要移除监听器，请调用 `off` 方法
-   */
-  on<T extends keyof EventMap>(type: T, handler: (event: EventMap[NoInfer<T>]) => void) {
-    this.logger.debug(`registering: ${String(type)}`)
-    this.#event.on(type, handler)
-  }
-
-  /**
-   * 移除事件监听器
-   */
-  off<T extends keyof EventMap>(type: T, handler: (event: EventMap[NoInfer<T>]) => void) {
-    this.logger.debug(`unregistering: ${String(type)}`)
-    this.#event.off(type, handler)
-  }
-
-  api<T extends any>(action: API | (string & {}), params: Record<string, any> = {}): Promise<T> {
-    this.#ensureWsConnection(this.#ws)
-    this.logger.debug(`calling api action: ${action} with params: ${JSON.stringify(params)}`)
-    const echo = this.#echoId()
-    this.#ws.send(JSON.stringify({ echo, action, params }))
-    return this.#waitForAction<T>(echo)
-  }
-
-  /**
-   * 发送私聊消息
-   */
-  sendPrivateMsg(user_id: number, sendable: Sendable | Sendable[]) {
-    return this.api<{ message_id: number }>('send_private_msg', {
-      user_id,
-      message: this.#normalizeSendable(sendable),
-    })
-  }
-
-  /**
-   * 发送群消息
-   */
-  sendGroupMsg(group_id: number, sendable: Sendable | Sendable[]) {
-    return this.api<{ message_id: number }>('send_group_msg', {
-      group_id,
-      message: this.#normalizeSendable(sendable),
-    })
-  }
-
-  /** 启动 NapCat SDK 实例，建立 WebSocket 连接 */
-  async bootstrap() {
-    const { logger: _, ...config } = this.#config
-
-    this.logger.info(`bootstrap with config: ${JSON.stringify(config)}`)
-
-    return new Promise<void>((resolve, reject) => {
-      const ws = new WebSocket(this.#buildWsUrl())
-
-      ws.onmessage = (event) => {
-        const data = (() => {
-          try {
-            return JSON.parse(event.data)
-          } catch {
-            return null
-          }
-        })() as any
-
-        if (!data) {
-          this.logger.warn(`received non-json message: ${event.data}`)
-          return
-        }
-
-        this.#event.emit('ws.message', data)
-        this.#bindInternalEvents(data)
-      }
-
-      ws.onclose = () => {
-        this.logger.info('closed')
-        this.#event.emit('ws.close')
-      }
-
-      ws.onerror = (error) => {
-        this.logger.error(`error: ${error}`)
-        this.#event.emit('ws.error', error)
-        reject(error)
-      }
-
-      ws.onopen = () => {
-        this.logger.info('connected')
-        this.#event.emit('ws.open')
-        resolve()
-      }
-
-      this.#ws = ws
-
-      this.logger.trace(`WebSocket instance created: ${this.#ws}`)
-    })
-  }
-
-  /** 销毁 NapCat SDK 实例，关闭 WebSocket 连接 */
-  async destroy() {
-    if (this.#ws) {
-      this.logger.info('destroying NapCat SDK instance...')
-      this.#ws.close()
-      this.#ws = null
-      this.logger.info('NapCat SDK instance destroyed.')
-    } else {
-      this.logger.warn('NapCat SDK instance is not initialized.')
-    }
-  }
-}