bilitoolkit-types 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hzhilong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# bilitoolkit-types
+
+[哔哩工具姬](https://github.com/hzhilong/bilitoolkit) 类型库。

package/dist/index.d.ts

@@ -0,0 +1,559 @@
+import { BiliClientConfig, BiliClient, BaseService, BaseApi, UserCard, UserInfoWithCookie, UserCookie } from '@ybgnb/bili-api';
+import { FunctionKeys, BizResult, LogLevel, CommonError, Logger } from '@ybgnb/utils';
+
+/**
+ * bili-api 客户端配置（用于主进程代理发起 bili-api ）
+ */
+interface BiliApiClientConfig extends Omit<BiliClientConfig, 'logging' | 'logLevel'> {
+    id: string;
+    referer: string;
+}
+/**
+ * bili-api 接口方法（用于主进程代理发起 bili-api ）
+ */
+type BiliApiMethod = {
+    [K in keyof BiliClient]: BiliClient[K] extends BaseService | BaseApi ? BiliClient[K][FunctionKeys<BiliClient[K]>] : never;
+}[keyof BiliClient];
+/**
+ * bili-api 的层级代理对象类型（用于主进程创建代理，保留类→方法的嵌套结构）
+ * 例如：const proxy: BiliApiProxy = { UserService: { getUser: ... } }
+ */
+type BiliApiProxy = {
+    [K in keyof BiliClient]: BiliClient[K] extends BaseService | BaseApi ? Pick<BiliClient[K], FunctionKeys<BiliClient[K]>> : never;
+};
+/**
+ * api 代理的上下文
+ */
+interface ApiProxyContext {
+    /** 由createBiliClient创建的客户端id */
+    clientId: string;
+    /** 中止信号（自己传一个唯一ID） */
+    abortSignalId?: AbortSignalId;
+}
+/**
+ * api 终止信号
+ */
+type AbortSignalId = string;
+
+/**
+ * bili API
+ */
+interface ToolkitBiliApi {
+    /**
+     * 创建接口请求的客户端
+     * @description 用于后续主线程发起bili接口请求（可操作多用户）
+     */
+    createBiliClient(config?: Partial<Omit<BiliApiClientConfig, 'id'>>): Promise<BiliApiClientConfig>;
+    /**
+     * 调用 bili-api 方法（由主线程发起请求，所以可以操作多用户）
+     * @param context         api 代理的上下文
+     * @param apiInvokePath   api 调用路径（可传入服务方法 client.xxxService.xxx 或者基础请求方法 client.api.xxx，不包含'client.'，
+     * @param args            api 方法参数
+     * @description           建议使用 bilitoolkit-api-runtime 包装的方法 createBiliClient 创建客户端后以函数式调用接口。
+     * @example await api(null, c.user.getUserCards, 22)
+     */
+    invokeBiliApi<AM extends BiliApiMethod>(context: ApiProxyContext, apiInvokePath: AM, ...args: Parameters<AM>): Promise<BizResult<Awaited<ReturnType<AM>>>>;
+    /**
+     * 终止 bili-api 请求
+     * @param abortSignalId   终止信号 ID
+     */
+    abortBiliApi(abortSignalId: AbortSignalId): Promise<void>;
+}
+
+/**
+ * 数据库相关的API（当前插件所属的数据库）
+ */
+interface ToolkitDBApi {
+    /**
+     * 获取当前环境的根目录路径
+     */
+    getRootDir(): Promise<string>;
+    /**
+     * 判断是否存在该文档
+     * @param id 文档id
+     */
+    has(id: string): Promise<boolean>;
+    /**
+     * 读取文档
+     * @param  id 文档id
+     */
+    read<T extends object>(id: string): Promise<T | null>;
+    /**
+     * 初始化文档
+     * @param id    文档id
+     * @param defaultData  文档默认内容
+     */
+    init<T extends object>(id: string, defaultData?: T): Promise<T | null>;
+    /**
+     * 批量读取文档
+     * @param  idPrefix 文档id前缀，为空则获取所有
+     */
+    bulkRead<T extends object>(idPrefix?: string): Promise<Array<T | null>>;
+    /**
+     * 写入文档
+     * @param  id 文档id
+     * @param data 文档内容
+     */
+    write<T extends object>(id: string, data: T): Promise<void>;
+    /**
+     * 批量写入文档
+     * @param docs 文档
+     */
+    bulkWrite<T extends object>(docs: {
+        id: string;
+        data: T;
+    }[]): Promise<void>;
+    /**
+     * 删除文档
+     * @param  id 文档id
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * 批量删除文档
+     * @param idPrefix 文档id前缀，为空则删除所有
+     */
+    bulkDelete(idPrefix?: string): Promise<string[]>;
+}
+
+/**
+ * 应用主题模式
+ */
+type AppThemeMode = 'light' | 'dark' | 'system';
+/**
+ * 应用主题背景模式 默认|跟随主题色
+ */
+type AppThemeBackgroundMode = 'default' | 'follow-primary';
+/**
+ * 应用主题状态
+ */
+interface AppThemeState {
+    primaryColorIndex: number;
+    primaryColor: string;
+    themeMode: AppThemeMode;
+    bgMode: AppThemeBackgroundMode;
+    dark: boolean;
+}
+
+/**
+ * 事件相关的API（单向通信）
+ */
+interface ToolkitEventApi {
+    /**
+     * 监听窗口显示（需要首次进入监听的话，需要使用preload.js）
+     */
+    onWindowShown(listener: () => void): Promise<void>;
+    /**
+     * 监听应用主题变化
+     */
+    onUpdateAppTheme(listener: (theme: AppThemeState) => void): Promise<void>;
+    /**
+     * 监听用户退出
+     */
+    onUserLogout(listener: (user: UserCard) => void): Promise<void>;
+    /**
+     * 监听事件
+     */
+    on(eventName: string, listener: (...data: unknown[]) => void): Promise<void>;
+    /**
+     * 发射事件
+     */
+    emit(eventName: string, ...data: unknown[]): Promise<void>;
+}
+
+/**
+ * 文件相关的API（当前插件所属的文件夹）
+ */
+interface ToolkitFileApi {
+    /**
+     * 获取当前环境的根目录路径
+     */
+    getRootDir(): Promise<string>;
+    /**
+     * 判断是否文件是否存在
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * 读取文件
+     */
+    read(filePath: string): Promise<Uint8Array>;
+    /**
+     * 写入文件
+     */
+    write(filePath: string, content: Uint8Array): Promise<void>;
+    /**
+     * 分块写入
+     */
+    writeChunk(filePath: string, content: Uint8Array, position?: number): Promise<void>;
+    /**
+     * 删除文件，不存在会抛异常
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * 批量删除文件
+     */
+    bulkDelete(filePaths: string[]): Promise<void>;
+    /**
+     * 打开文件，返回可用于读写操作的文件句柄。
+     * @param filePath - 文件的相对路径（相对于 getRootDir()）
+     * @param flags     打开模式
+     */
+    open(filePath: string, flags?: string | number): Promise<FileHandle>;
+}
+/**
+ * 文件句柄（适合分块读写大文件）
+ */
+interface FileHandle {
+    /** 将数据写入文件 */
+    write(data: Uint8Array): Promise<void>;
+    /** 将缓冲区数据强制写入磁盘 */
+    flush(): Promise<void>;
+    /** 从当前偏移量读取指定大小的数据，返回读取结果（包含数据和实际读取字节数） */
+    read(size?: number): Promise<FileReadResult>;
+    /** 移动文件读写指针到指定位置 */
+    seek(offset: number, whence?: FileSeekWhence): Promise<void>;
+    /** 获取文件状态（如大小、修改时间等） */
+    stat(): Promise<FileStat>;
+    /**
+     * 获取当前文件偏移量
+     */
+    tell(): Promise<number>;
+    /** 关闭文件句柄，释放资源 */
+    close(): Promise<void>;
+}
+type FileSeekWhence = 'start' | 'current' | 'end';
+interface FileReadResult {
+    data: Uint8Array;
+    eof: boolean;
+}
+interface FileStat {
+    size: number;
+    createdAt?: number;
+    modifiedAt?: number;
+    isFile?: boolean;
+    isDirectory?: boolean;
+}
+
+/**
+ * 全局数据的API（同窗口）
+ * _get开头的是通过具体名称获取，其他get开头的都是直接获取具体的数据
+ */
+interface ToolkitGlobalDataApi {
+    /**
+     * 获取应用全局数据
+     * @param name      数据名称
+     * @param timeout   超时处理
+     * @param args      参数
+     */
+    getData(name: string, timeout: boolean, ...args: any[]): Promise<unknown>;
+    /**
+     * 获取插件全局数据
+     * @param pluginId  插件id
+     * @param name      数据名称
+     * @param timeout   超时处理
+     * @param args      参数
+     */
+    getPluginData(pluginId: string, name: string, timeout: boolean, ...args: any[]): Promise<unknown>;
+    /**
+     * 注册全局数据
+     * @param name
+     * @param getFn
+     */
+    register(name: string, getFn: (...args: any[]) => Promise<BizResult<any>>): Promise<void>;
+}
+
+interface AppLog {
+    level: LogLevel;
+    data: string[];
+}
+
+/**
+ * 系统相关的API
+ */
+interface ToolkitSystemApi {
+    /**
+     * ping
+     * 主进程返回 true
+     */
+    ping(): Promise<boolean>;
+    /**
+     * 使用系统默认浏览器浏览网页
+     */
+    browsePage(path: string): Promise<void>;
+    /**
+     * 打开资源管理器并定位到文件或者文件夹
+     */
+    showItemInFolder(path: string): Promise<void>;
+    /**
+     * 保存日志
+     */
+    saveLog(appLog: AppLog): Promise<void>;
+    /**
+     * 获取日志级别
+     */
+    getLogLevel(): Promise<LogLevel>;
+    /**
+     * 系统是否处于深色模式（系统模式，非应用设置）
+     */
+    shouldUseDarkColors(): Promise<boolean>;
+    /**
+     * 获取应用主题状态
+     */
+    getAppThemeState(): Promise<AppThemeState>;
+}
+
+/**
+ * 定时器类型：延迟/间隔
+ */
+type TimerType = 'delay' | 'interval';
+/**
+ * 定时器 ID
+ */
+type TimerId = string;
+/**
+ * 定时器选项
+ */
+interface TimerOptions {
+    /** 定时器 ID，请自己生成ID，至少在自己环境的是唯一 */
+    timerId: TimerId;
+    /** 定时器类型 */
+    type: TimerType;
+    /** 持续时间/间隔时间 ms */
+    duration: number;
+    /** 问询的超时时间，默认 500ms */
+    ackTimeout?: number;
+}
+/**
+ * 定时器回调
+ */
+interface TimerCallback {
+    /**
+     * 定时器触发监听器
+     * @return 是否成功确认本次触发请求。
+     * 返回 false 表示当前渲染进程不可继续处理该定时器，主进程应取消该定时器。
+     */
+    onTrigger: () => Promise<boolean>;
+}
+/**
+ * 定时器 API（不能保证精确时间）
+ */
+interface ToolkitTimerApi {
+    /**
+     * 注册定时器
+     * @param options   定时器选项
+     * @param callback  定时器回调
+     */
+    register(options: TimerOptions, callback: TimerCallback): Promise<void>;
+    /**
+     * 取消定时器
+     * @param timerId
+     */
+    cancel(timerId: TimerId): Promise<void>;
+}
+
+/**
+ * 用户 API
+ */
+interface ToolkitUserApi {
+    /**
+     * 切换用户
+     * @param injectCookie 切换成功后，是否往浏览器环境注入用cookie
+     * @default false
+     */
+    switchUser(injectCookie?: boolean): Promise<UserInfoWithCookie>;
+    /**
+     * 删除当前浏览器环境的用户cookie
+     */
+    delCurrUserCookie(): Promise<void>;
+    /**
+     * 获取用户 cookie
+     */
+    getCurrUserCookie(): Promise<string[]>;
+    /**
+     * 切换当前用户
+     * @description 切换成功后，会往浏览器环境注入用cookie
+     */
+    switchCurrUser(user: UserInfoWithCookie): Promise<void>;
+    /**
+     * 通过用户cookie获取用户信息，可用于检测cookie有效性
+     */
+    getMyInfoByCookie(userCookie: UserCookie): Promise<UserInfoWithCookie>;
+}
+
+/**
+ * 窗口相关的API
+ */
+interface ToolkitWindowApi {
+    /**
+     * 最小化窗口
+     */
+    minimize(): Promise<void>;
+    /**
+     * 最大化窗口
+     * @param max 最大化/取消最大化
+     */
+    maximize(max: boolean): Promise<void>;
+    /**
+     * 关闭窗口
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * 工具箱全局 API 定义
+ */
+interface ToolkitApi {
+    /**
+     * 窗口管理 API
+     */
+    window: ToolkitWindowApi;
+    /**
+     * 系统级别的 API
+     */
+    system: ToolkitSystemApi;
+    /**
+     * 数据库 API
+     */
+    db: ToolkitDBApi;
+    /**
+     * 文件 API
+     */
+    file: ToolkitFileApi;
+    /**
+     * 用户 API
+     */
+    user: ToolkitUserApi;
+    /**
+     * bili API
+     */
+    bili: ToolkitBiliApi;
+    /**
+     * 事件 API
+     */
+    event: ToolkitEventApi;
+    /**
+     * 全局数据 API
+     */
+    global: ToolkitGlobalDataApi;
+    /**
+     * 定时器 API
+     */
+    timer: ToolkitTimerApi;
+}
+
+/**
+ * APP 业务逻辑错误（不打印调用栈）
+ */
+declare class AppError extends CommonError {
+    constructor(message: string, cause?: unknown);
+}
+declare function convertToAppError(error: unknown, prefix?: string): AppError;
+
+/**
+ * 任务配置结构定义（用于描述用户可填写的字段）
+ */
+interface TaskConfigSchema<T extends readonly TaskConfigField[] = any> {
+    fields: T;
+}
+/**
+ * 单个配置字段定义
+ */
+interface TaskConfigField<Name extends string = string> {
+    /** 字段唯一标识（对应 config 中的 key） */
+    name: Name;
+    /** 字段显示名称 */
+    label: string;
+    /** 字段类型 */
+    type: 'user' | 'users' | 'input' | 'textarea' | 'number' | 'select' | 'checkbox' | 'switch';
+    /** 是否必填 */
+    required?: boolean;
+    /** 默认值 */
+    default?: any;
+    /** 可选项（用于 select 等） */
+    options?: {
+        label: string;
+        value: any;
+    }[];
+    /** 字段描述（用于提示） */
+    description?: string;
+    /** 验证的正则 */
+    regex?: string;
+}
+/** 根据字段定义数组推导出配置对象类型（以 name 为 key 的联合类型） */
+type InferConfig<T extends readonly TaskConfigField[]> = {
+    [K in T[number]['name']]: any;
+};
+
+/**
+ * 任务调度配置
+ */
+type TaskSchedule = {
+    /** cron 表达式调度 */
+    type: 'cron';
+    /** cron 表达式 */
+    value: string;
+} | {
+    /** 固定间隔调度 */
+    type: 'interval';
+    /** 间隔时间（秒） */
+    value: string;
+};
+
+type TaskPluginToolkitApi = Omit<ToolkitApi, 'window' | 'user' | 'bili'>;
+/**
+ * 任务执行上下文
+ */
+interface TaskContext<C = Record<string, any>> {
+    /** 用户填写的配置 */
+    config?: C;
+    /** 日志记录器 */
+    logger: Logger;
+    /** 工具 API */
+    api: TaskPluginToolkitApi;
+    /**
+     * 取消信号
+     */
+    signal?: AbortSignal;
+}
+/**
+ * 任务执行结果
+ */
+interface TaskResult {
+    /** 是否执行成功 */
+    success: boolean;
+    /** 简要信息 */
+    message: string;
+    /** 详情，支持html */
+    details?: string;
+}
+/**
+ * 定时任务插件接口
+ */
+interface TaskPlugin<T extends readonly TaskConfigField[] = any> {
+    /**
+     * 任务配置结构定义（已改成从plugin-meta.json读取）
+     */
+    /**
+     * 获取调度配置（已改成从plugin-meta.json读取）
+     * - 不提供则表示该任务仅支持手动执行
+     */
+    /**
+     * 执行任务
+     */
+    run(context: TaskContext<InferConfig<T>>): Promise<TaskResult>;
+}
+/**
+ * 任务插件元信息
+ */
+interface TaskPluginMeta<T extends readonly TaskConfigField[] = any> {
+    /**
+     * 任务配置结构定义
+     */
+    taskConfigSchema?: TaskConfigSchema<T>;
+    /**
+     * 调度配置
+     * - 不提供则表示该任务仅支持手动执行
+     */
+    taskSchedule?: TaskSchedule;
+}
+
+export { type AbortSignalId, type ApiProxyContext, AppError, type AppLog, type AppThemeBackgroundMode, type AppThemeMode, type AppThemeState, type BiliApiClientConfig, type BiliApiMethod, type BiliApiProxy, type FileHandle, type FileReadResult, type FileSeekWhence, type FileStat, type InferConfig, type TaskConfigField, type TaskConfigSchema, type TaskContext, type TaskPlugin, type TaskPluginMeta, type TaskPluginToolkitApi, type TaskResult, type TaskSchedule, type TimerCallback, type TimerId, type TimerOptions, type TimerType, type ToolkitApi, type ToolkitBiliApi, type ToolkitDBApi, type ToolkitEventApi, type ToolkitFileApi, type ToolkitGlobalDataApi, type ToolkitSystemApi, type ToolkitTimerApi, type ToolkitUserApi, type ToolkitWindowApi, convertToAppError };

package/dist/index.js

@@ -0,0 +1,20 @@
+// src/types/api/bili-api-invoke.ts
+import "@ybgnb/bili-api";
+
+// src/types/common/app-error.ts
+import { CommonError, getErrorMessage } from "@ybgnb/utils";
+var AppError = class extends CommonError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function convertToAppError(error, prefix) {
+  return new AppError(`${prefix} ${getErrorMessage(error)}`, error);
+}
+export {
+  AppError,
+  convertToAppError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/api/bili-api-invoke.ts","../src/types/common/app-error.ts"],"sourcesContent":["import { BaseApi, BaseService, BiliClient, type BiliClientConfig } from '@ybgnb/bili-api'\nimport type { FunctionKeys } from '@ybgnb/utils'\n\n/**\n * bili-api 客户端配置（用于主进程代理发起 bili-api ）\n */\nexport interface BiliApiClientConfig extends Omit<BiliClientConfig, 'logging' | 'logLevel'> {\n  id: string\n  // 请求头的 referer\n  referer: string\n}\n\n/**\n * bili-api 接口方法（用于主进程代理发起 bili-api ）\n */\nexport type BiliApiMethod = {\n  [K in keyof BiliClient]: BiliClient[K] extends BaseService | BaseApi\n    ? BiliClient[K][FunctionKeys<BiliClient[K]>]\n    : never\n}[keyof BiliClient]\n\n/**\n * bili-api 的层级代理对象类型（用于主进程创建代理，保留类→方法的嵌套结构）\n * 例如：const proxy: BiliApiProxy = { UserService: { getUser: ... } }\n */\nexport type BiliApiProxy = {\n  [K in keyof BiliClient]: BiliClient[K] extends BaseService | BaseApi\n    ? Pick<BiliClient[K], FunctionKeys<BiliClient[K]>>\n    : never\n}\n\n/**\n * api 代理的上下文\n */\nexport interface ApiProxyContext {\n  /** 由createBiliClient创建的客户端id */\n  clientId: string\n  /** 中止信号（自己传一个唯一ID） */\n  abortSignalId?: AbortSignalId\n}\n\n/**\n * api 终止信号\n */\nexport type AbortSignalId = string\n","import { CommonError, getErrorMessage } from '@ybgnb/utils'\n\n/**\n * APP 业务逻辑错误（不打印调用栈）\n */\nexport class AppError extends CommonError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause)\n\n    this.name = new.target.name\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\nexport function convertToAppError(error: unknown, prefix?: string) {\n  return new AppError(`${prefix} ${getErrorMessage(error)}`, error)\n}\n"],"mappings":";AAAA,OAAwE;;;ACAxE,SAAS,aAAa,uBAAuB;AAKtC,IAAM,WAAN,cAAuB,YAAY;AAAA,EACxC,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AAEpB,SAAK,OAAO,WAAW;AACvB,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;AAEO,SAAS,kBAAkB,OAAgB,QAAiB;AACjE,SAAO,IAAI,SAAS,GAAG,MAAM,IAAI,gBAAgB,KAAK,CAAC,IAAI,KAAK;AAClE;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "bilitoolkit-types",
+  "version": "0.0.1",
+  "author": "hzhilong",
+  "description": "『哔哩工具姬』类型库",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hzhilong/bilitoolkit-types"
+  },
+  "keywords": [
+    "BiliToolkit",
+    "哔哩工具姬"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/hzhilong/bilitoolkit-types/issues"
+  },
+  "homepage": "https://github.com/hzhilong/bilitoolkit-types#readme",
+  "devDependencies": {
+    "barrelsby": "^2.8.1",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "import-suffixer": "^0.0.1",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.43.0"
+  },
+  "peerDependencies": {
+    "@ybgnb/utils": "^0.2.8",
+    "@ybgnb/bili-api": "^0.0.3"
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.dev.json --noEmit && eslint .",
+    "lint": "eslint . --fix",
+    "format": "prettier --write src/",
+    "barrelsby": "barrelsby -c barrelsby.json && import-suffixer \"src/**/*.ts\"",
+    "build": "tsup",
+    "npm login": "npm login",
+    "pnpm publish": "pnpm publish --access public"
+  }
+}