fishpi 0.1.26 → 0.1.28

package/lib/index.d.mts

@@ -49,7 +49,16 @@ declare class ArticlePost implements IArticlePost {
    * 提问悬赏积分
    */
   offerPoint?: number;
+  /**
+   * 从接口数据转换为 ArticlePost 实例
+   * @param article 帖子数据
+   * @returns ArticlePost 实例
+   */
   static from(article: IArticlePost): ArticlePost & IArticlePost;
+  /**
+   * 转换为接口请求数据
+   * @returns 接口请求数据
+   */
   toJson(): {
     articleTitle: string;
     articleContent: string;
@@ -64,6 +73,9 @@ declare class ArticlePost implements IArticlePost {
     articleQnAOfferPoint: number | undefined;
   };
 }
+/**
+ * 评论提交信息
+ */
 declare class CommentPost implements ICommentPost {
   /**
    * 文章 Id
@@ -85,7 +97,16 @@ declare class CommentPost implements ICommentPost {
    * 回复评论 Id
    */
   originalId?: string;
+  /**
+   * 从接口数据转换为 CommentPost 实例
+   * @param comment 评论数据
+   * @returns CommentPost 实例
+   */
   static from(comment: ICommentPost): CommentPost & ICommentPost;
+  /**
+   * 转换为接口请求数据
+   * @returns 接口请求数据
+   */
   toJson(): {
     articleId: string;
     commentAnonymous: number;
@@ -877,8 +898,16 @@ declare class BreezemoonContent {
    * 发布城市（可能为空，请注意做判断）
    */
   city: string;
+  /**
+   * 从接口数据转换为 BreezemoonContent 实例
+   * @param src 接口数据
+   * @returns BreezemoonContent 实例
+   */
   static from(src: Record<string, any>): BreezemoonContent;
 }
+/**
+ * 清风明月列表
+ */
 declare class BreezemoonList {
   /**
    * 分页信息
@@ -888,6 +917,11 @@ declare class BreezemoonList {
    * 清风明月列表
    */
   breezemoons: BreezemoonContent[];
+  /**
+   * 从接口数据转换为 BreezemoonList 实例
+   * @param src 接口数据
+   * @returns BreezemoonList 实例
+   */
   static from(src: Record<string, any>): BreezemoonList;
 }
 //#endregion
@@ -953,8 +987,14 @@ interface IChatRevoke {
    * 消息 Id
    */
   data: string;
+  /**
+   * 消息类型
+   */
   type: 'revoke';
 }
+/**
+ * 私聊查询参数
+ */
 interface IChatQuery {
   /**
    * 页码
@@ -969,6 +1009,9 @@ interface IChatQuery {
    */
   autoRead?: boolean;
 }
+/**
+ * 私聊通知信息
+ */
 interface IChatNotice {
   /**
    * 命令
@@ -1665,10 +1708,25 @@ interface IRedPacketStatusMsg {
 }
 //#endregion
 //#region src/types/user.d.ts
+/**
+ * 基础用户信息
+ */
 interface IUserLite {
+  /**
+   * 用户 ID
+   */
   oId: string;
+  /**
+   * 用户头像 URL
+   */
   userAvatarURL: string;
+  /**
+   * 用户昵称
+   */
   userNickname: string;
+  /**
+   * 用户名
+   */
   userName: string;
 }
 /**
@@ -1755,7 +1813,15 @@ declare class UserInfo {
    * MBTI 性格类型
    */
   mbti: string;
+  /**
+   * 获取用户显示名称
+   */
   get name(): string;
+  /**
+   * 从接口数据转换为 UserInfo 实例
+   * @param user 接口数据
+   * @returns UserInfo 实例
+   */
   static from(user: Record<string, any>): UserInfo;
 }
 /**
@@ -1938,8 +2004,17 @@ interface UserUpdateParams {
  * 摸鱼大闯关信息
  */
 declare class MoFishGame implements IMoFishGame {
+  /**
+   * 用户名
+   */
   userName: string;
+  /**
+   * 关卡
+   */
   stage: string;
+  /**
+   * 时间
+   */
   time: number;
 }
 /**
@@ -1963,7 +2038,13 @@ interface IMoFishGame {
  * 用户 IP 信息
  */
 interface IUserIP {
+  /**
+   * 最近登录 IP
+   */
   latestLoginIP: string;
+  /**
+   * 用户 ID
+   */
   userId: string;
 }
 /**
@@ -2952,6 +3033,9 @@ declare class Pagination {
 }
 //#endregion
 //#region src/ws.d.ts
+/**
+ * 通用 WebSocket 事件
+ */
 interface IWebSocketEvent {
   /**
    * Websocket 打开
@@ -2966,7 +3050,13 @@ interface IWebSocketEvent {
    */
   error: (error: ErrorEvent) => void;
 }
+/**
+ * WebSocket 事件基础类
+ */
 declare class WsEventBase<T> {
+  /**
+   * 事件触发器
+   */
   emitter: {
     listeners: Map<string, Function[]>;
     on(event: string, listener: Function): /*elided*/any;
@@ -2975,7 +3065,13 @@ declare class WsEventBase<T> {
     emit(event: string, ...args: any[]): /*elided*/any;
     removeAllListeners(event?: string): /*elided*/any;
   };
+  /**
+   * WebSocket 连接对象
+   */
   ws: ReconnectingWebSocket | null;
+  /**
+   * WebSocket 配置
+   */
   rwsOptions: Options;
   constructor();
   /**
@@ -2992,6 +3088,7 @@ declare class WsEventBase<T> {
    * WebSocket 监听
    * @param event WebSocket 事件
    * @param listener 监听器
+   * @returns EventEmitter
    */
   on<K extends keyof T>(event: K, listener: T[K]): {
     listeners: Map<string, Function[]>;
@@ -3005,6 +3102,7 @@ declare class WsEventBase<T> {
    * 移除 WebSocket 监听
    * @param event WebSocket 事件
    * @param listener 监听器
+   * @returns EventEmitter
    */
   off<K extends keyof T>(event?: K, listener?: T[K]): {
     listeners: Map<string, Function[]>;
@@ -3018,6 +3116,7 @@ declare class WsEventBase<T> {
    *  WebSocket 单次监听
    * @param event WebSocket 事件
    * @param listener 监听器
+   * @returns EventEmitter
    */
   once<K extends keyof T>(event: K, listener: T[K]): {
     listeners: Map<string, Function[]>;
@@ -3118,13 +3217,38 @@ interface IChatRoomEvents extends IWebSocketEvent {
    */
   all: (type: string, data: any) => void;
 }
+/**
+ * 摸鱼派聊天室接口
+ */
 declare class ChatRoom extends WsEventBase<IChatRoomEvents> {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 讨论话题
+   */
   private _discusse;
+  /**
+   * 在线用户列表
+   */
   private _onlines;
+  /**
+   * WebSocket 心跳定时器
+   */
   private wsTimer;
+  /**
+   * 客户端类型
+   */
   private client;
+  /**
+   * 客户端版本
+   */
   private version;
+  /**
+   * 实例化聊天室
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 当前在线人数列表，需要先调用 addListener 添加聊天室消息监听
@@ -3136,6 +3260,7 @@ declare class ChatRoom extends WsEventBase<IChatRoomEvents> {
   get discusse(): string;
   /**
    * 設置当前聊天室话题
+   * @param val 话题内容
    */
   set discusse(val: string);
   /**
@@ -3157,10 +3282,12 @@ declare class ChatRoom extends WsEventBase<IChatRoomEvents> {
   history(page?: number, type?: ChatContentType): Promise<IChatRoomMessage[]>;
   /**
    * 获取指定消息附近的聊天室消息
-   * @param oId 消息 Id
-   * @param mode 获取模式，context 上下文模式，after 之后模式
-   * @param size 获取消息数量，默认 25，最大 100
-   * @param type 获取消息类型，默认 HTML
+   * @param params 获取参数
+   * @param params.oId 消息 Id
+   * @param params.mode 获取模式，context 上下文模式，after 之后模式
+   * @param params.size 获取消息数量，默认 25，最大 100
+   * @param params.type 获取消息类型，默认 HTML
+   * @returns 聊天室消息列表
    */
   get({
     oId,
@@ -3243,6 +3370,9 @@ declare class RedPacket {
 }
 //#endregion
 //#region src/notice.d.ts
+/**
+ * 通知事件监听器
+ */
 interface INoticeEvents extends IWebSocketEvent {
   /**
    * 清风明月更新
@@ -3270,21 +3400,33 @@ interface INoticeEvents extends IWebSocketEvent {
    */
   warnBroadcast: (data: INoticeWarnBroadcast) => void;
 }
+/**
+ * 摸鱼派通知接口
+ */
 declare class Notice extends WsEventBase<INoticeEvents> {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 实例化通知
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
   /**
    * 获取未读消息数
+   * @returns 未读消息数信息
    */
   count(): Promise<INoticeCount>;
   /**
    * 获取消息列表
    * @param type 消息类型
+   * @returns 消息列表
    */
   list(type: NoticeType): Promise<NoticeList>;
   /**
@@ -3302,22 +3444,39 @@ declare class Notice extends WsEventBase<INoticeEvents> {
    */
   reconnect(): Promise<unknown>;
   /**
-   * 连接用户私聊频道
+   * 连接通知频道
+   * @param reload 是否重新连接
    * @returns Websocket 连接对象
    */
   connect(reload?: boolean): Promise<ReconnectingWebSocket>;
 }
 //#endregion
 //#region src/emoji.d.ts
+/**
+ * 摸鱼派表情接口
+ */
 declare class Emoji {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 自定义表情列表
+   */
   private emojis;
+  /**
+   * 各个模块的实例化
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
+  /**
+   * 默认表情列表
+   */
   get default(): {
     doge: string;
     trollface: string;
@@ -3511,12 +3670,22 @@ declare class Emoji {
 }
 //#endregion
 //#region src/user.d.ts
+/**
+ * 摸鱼派用户接口
+ */
 declare class User {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 实例化用户
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
   /**
@@ -3570,27 +3739,53 @@ declare class User {
   /**
    * 修改用户头像
    * @param userAvatarURL 用户头像地址
+   * @returns void
    */
   updateUserAvatar(userAvatarURL: string): Promise<void>;
   /**
    * 修改用户信息
    * @param data 用户信息参数
+   * @returns void
    */
   updateUserInfo(data: UserUpdateParams): Promise<void>;
 }
 //#endregion
 //#region src/article.d.ts
+/**
+ * 文章事件监听器
+ */
 interface IArticleEvents extends IWebSocketEvent {
+  /**
+   * 热度更新
+   * @param msg 文章热度信息
+   */
   heat: (msg: IArticleHeat) => void;
+  /**
+   * 评论通知
+   * @param msg 文章评论信息
+   */
   comment: (msg: ArticleComment) => void;
 }
+/**
+ * 摸鱼派文章接口
+ */
 declare class Article {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 文章频道
+   */
   private channels;
+  /**
+   * 各个模块的实例化
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
   /**
@@ -3608,8 +3803,11 @@ declare class Article {
   update(id: string, data: IArticlePost): Promise<string>;
   /**
    * 查询文章列表
-   * @param type 查询类型
-   * @param tag 指定查询标签，可选
+   * @param params 查询参数
+   * @param params.type 查询类型
+   * @param params.page 页码，默认 1
+   * @param params.size 每页数量，默认 20
+   * @param params.tag 指定查询标签，可选
    * @returns 文章列表
    */
   list({
@@ -3654,6 +3852,7 @@ declare class Article {
   /**
    * 感谢文章
    * @param id 文章id
+   * @returns void
    */
   thank(id: string): Promise<void>;
   /**
@@ -3664,16 +3863,19 @@ declare class Article {
   /**
    * 取消收藏文章
    * @param followingId 文章id
+   * @returns void
    */
   unfollow(followingId: string): Promise<void>;
   /**
    * 关注文章
    * @param followingId 文章id
+   * @returns void
    */
   watch(followingId: string): Promise<void>;
   /**
    * 取消关注文章
    * @param followingId 文章id
+   * @returns void
    */
   unwatch(followingId: string): Promise<void>;
   /**
@@ -3684,53 +3886,91 @@ declare class Article {
   /**
    * 获取文章在线人数
    * @param id 文章id
+   * @returns 文章热度值
    */
   heat(id: string): Promise<number>;
   /**
    * 获取帖子的Markdown原文
    * @param articleId 文章Id
+   * @returns 文章 Markdown 内容
    */
   md(articleId: string): Promise<string>;
+  /**
+   * 获取文章频道
+   * @param id 文章 Id
+   * @param type 文章类型
+   * @returns 文章频道实例
+   */
   channel(id: string, type: ArticleType): ArticleChannel;
 }
+/**
+ * 文章实时频道
+ */
 declare class ArticleChannel extends WsEventBase<IArticleEvents> {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 文章 Id
+   */
   private id;
+  /**
+   * 文章类型
+   */
   private type;
-  constructor(token: string, id: string, type: ArticleType);
   /**
-   * 添加文章监听器
-   * @param id 文章id
+   * 实例化文章频道
+   * @param token 认证 Token
+   * @param id 文章 Id
    * @param type 文章类型
-   * @param callback 监听回调
+   */
+  constructor(token: string, id: string, type: ArticleType);
+  /**
+   * 连接实时频道
+   * @param reload 是否强制重连
+   * @returns WebSocket 实例
    */
   connect(reload?: boolean): Promise<ReconnectingWebSocket>;
 }
 //#endregion
 //#region src/comment.d.ts
+/**
+ * 摸鱼派评论接口
+ */
 declare class Comment {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 各个模块的实例化
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
   /**
    * 发布评论
    * @param data 评论信息
+   * @returns void
    */
   send(data: ICommentPost): Promise<void>;
   /**
    * 更新评论
    * @param id 评论 Id
    * @param data 评论信息
+   * @returns 评论内容
    */
   update(id: string, data: ICommentPost): Promise<string>;
   /**
    * 评论点赞
    * @param id 评论 Id
    * @param type 点赞类型
+   * @returns 投票状态
    */
   vote(id: string, type: 'up' | 'down'): Promise<VoteType>;
   /**
@@ -3746,6 +3986,9 @@ declare class Comment {
 }
 //#endregion
 //#region src/chat.d.ts
+/**
+ * 私聊事件监听器
+ */
 interface IChatEvents extends IWebSocketEvent {
   /**
    * 私聊消息
@@ -3758,9 +4001,23 @@ interface IChatEvents extends IWebSocketEvent {
    */
   revoke: (oId: string) => void;
 }
+/**
+ * 私聊频道
+ */
 declare class ChatChannel extends WsEventBase<IChatEvents> {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 目标用户名
+   */
   private user;
+  /**
+   * 实例化私聊频道
+   * @param user 目标用户名
+   * @param apiKey 接口 API Key
+   */
   constructor(user: string, apiKey: string);
   /**
    * 重新设置请求 Token
@@ -3772,7 +4029,15 @@ declare class ChatChannel extends WsEventBase<IChatEvents> {
    * @returns Websocket 连接对象
    */
   connect(reload?: boolean): Promise<ReconnectingWebSocket>;
+  /**
+   * 发送私聊消息
+   * @param msg 消息内容
+   * @returns void
+   */
   send(msg: string): Promise<void>;
+  /**
+   * 关闭私聊频道
+   */
   close(): void;
   /**
    * 获取用户私聊历史消息
@@ -3829,18 +4094,29 @@ declare class Chat {
 }
 //#endregion
 //#region src/breezemoon.d.ts
+/**
+ * 摸鱼派清风明月接口
+ */
 declare class Breezemoon {
+  /**
+   * 接口 API Key
+   */
   private apiKey;
+  /**
+   * 各个模块的实例化
+   * @param token 认证 Token
+   */
   constructor(token?: string);
   /**
    * 重新设置请求 Token
-   * @param apiKey 接口 API Key
+   * @param token 接口 API Key
    */
   setToken(token: string): void;
   /**
    * 获取清风明月列表
    * @param page 消息页码
    * @param size 每页个数
+   * @returns 清风明月列表
    */
   list(page?: number, size?: number): Promise<BreezemoonContent[]>;
   /**
@@ -3848,29 +4124,44 @@ declare class Breezemoon {
    * @param user 用户名
    * @param page 消息页码
    * @param size 每页个数
+   * @returns 清风明月列表
    */
   listByUser(user: string, page?: number, size?: number): Promise<BreezemoonList>;
   /**
    * 发送清风明月
    * @param content 内容
+   * @returns void
    */
   send(content: string): Promise<void>;
 }
 //#endregion
 //#region src/finger.d.ts
+/**
+ * 摸鱼派金手指接口
+ */
 declare class Finger {
+  /**
+   * 金手指密钥
+   */
   private goldFingerKey;
+  /**
+   * 实例化金手指
+   * @param key 金手指密钥
+   */
   constructor(key: string);
   /**
    * 设置金手指
    * @param key 金手指密钥
+   * @returns void
    */
   setFinger(key: string): void;
   /**
    * 上传摸鱼大闯关关卡数据
-   * @param userName: 用户在摸鱼派的用户名
-   * @param stage: 关卡数
-   * @param time: 通过此关时间（毫秒级时间戳）
+   * @param params 关卡数据
+   * @param params.userName 用户在摸鱼派的用户名
+   * @param params.stage 关卡数
+   * @param params.time 通过此关时间（毫秒级时间戳）
+   * @returns void
    */
   addMofishScore({
     userName,
@@ -3883,13 +4174,15 @@ declare class Finger {
   }): Promise<void>;
   /**
    * 查询用户最近登录的IP地址
-   * @param userName: 用户在摸鱼派的用户名
+   * @param userName 用户在摸鱼派的用户名
+   * @returns 用户 IP 信息
    */
   queryLatestLoginIP(userName: string): Promise<IUserIP>;
   /**
    * 添加勋章
-   * @param userName: 用户在摸鱼派的用户名
-   * @param metal: 勋章信息
+   * @param userName 用户在摸鱼派的用户名
+   * @param metal 勋章信息
+   * @returns void
    */
   addMetal(userName: string, metal: MetalBase): Promise<void>;
   /**
@@ -3933,9 +4226,19 @@ declare class Finger {
    * @param userName: 用户在摸鱼派的用户名
    */
   getYesterDayLivenessReward(userName: string): Promise<number>;
+  /**
+   * 给指定用户发送通知
+   * @param userName: 用户在摸鱼派的用户名
+   * @param notification: 通知内容
+   * @returns void
+   */
+  sendNotice(userName: string, notification: string): Promise<void>;
 }
 //#endregion
 //#region src/index.d.ts
+/**
+ * 摸鱼派 SDK 主入口
+ */
 declare class FishPi {
   /**
    *  请求 API 的 API Key
@@ -3978,7 +4281,17 @@ declare class FishPi {
    * @param token 接口 API Key，没有可以传空
    */
   constructor(token?: string);
+  /**
+   * 设置请求 Token
+   * @param apiKey 接口 API Key
+   * @returns void
+   */
   setToken(apiKey: string): Promise<void>;
+  /**
+   * 设置 API 域名
+   * @param domain API 域名
+   * @returns void
+   */
   setDomain(domain: string): Promise<void>;
   /**
    * 登录账号返回 API Key
@@ -3988,17 +4301,19 @@ declare class FishPi {
   /**
    * 预注册账号
    * @param data 用户信息
-   * @returns
+   * @returns void
    */
   preRegister(data: PreRegisterInfo): Promise<void>;
   /**
    * 验证手机验证码
    * @param code 验证码
-   * @returns
+   * @returns 验证状态
    */
   verify(code: string): Promise<number>;
   /**
    * 注册账号
+   * @param data 注册信息
+   * @returns void
    */
   register(data: RegisterInfo): Promise<void>;
   /**