web-dc-api 0.0.58 → 0.0.60

package/dist/types/index.d.ts

@@ -0,0 +1,40 @@
+export { DC } from './dc.js';
+export { isServiceWorkerActive, registerServiceWorker, updateServiceWorker } from './common/service-worker.js';
+export { AIChatMessage, AIChatMessageRequest, AIMessageContent, AIMessageMediaSource, AIProxyConfig, AIStreamResponseFlag, APPInfo, Account, AccountInfo, DCConnectInfo, EIP712SignReqMessage, FileTransmit, FunctionDef, IAICallConfig, IAppInfo, ModelConfig, NFTBindStatus, OnStreamResponseType, PeerStatus, ProxyCallConfig, ResponseMessage, SendMessage, SignHandler, SignReqMessage, SignReqMessageData, SignResponseMessage, ThemeAuthInfo, ThemeComment, ThemeObj, ToolDefinition, UploadStatus, User, UserProxyCallConfig } from './common/types/types.js';
+export { IAuthOperations } from './interfaces/auth-interface.js';
+export { IClientOperations } from './interfaces/client-interface.js';
+export { IDatabaseOperations } from './interfaces/database-interface.js';
+export { IFileOperations } from './interfaces/file-interface.js';
+export { IMessageOperations } from './interfaces/message-interface.js';
+export { IKeyValueOperations } from './interfaces/keyvalue-interface.js';
+export { ICommentOperations } from './interfaces/comment-interface.js';
+export { ICacheOperations } from './interfaces/cache-interface.js';
+export { DCContext } from './interfaces/DCContext.js';
+export { IUtilOperations } from './interfaces/util-interface.js';
+export { CommentType, Direction, OffChainOpTimes, OffChainOpTimesLimit, OffChainSpaceLimit, dc_protocol, dial_timeout, keyExpire, walletOrigin, walletUrl, walletWindowName } from './common/define.js';
+export { ThemePermission } from './common/constants.js';
+export { CoreModuleName, DCModule, ModuleSystem } from './common/module-system.js';
+export { FileModule } from './modules/file-module.js';
+export { AuthModule } from './modules/auth-module.js';
+export { CommentModule } from './modules/comment-module.js';
+export { DatabaseModule } from './modules/database-module.js';
+export { MessageModule } from './modules/message-module.js';
+export { KeyValueModule } from './modules/keyvalue-module.js';
+export { ClientModule } from './modules/client-module.js';
+export { CacheModule } from './modules/cache-module.js';
+export { AIProxyModule } from './modules/aiproxy-module.js';
+export { UtilModule } from './modules/util-module.js';
+export { LogLevel, configureLogger, createLogger } from './util/logger.js';
+export { KeyManager } from './common/dc-key/keyManager.js';
+export { Ed25519PrivKey, Ed25519PubKey } from './common/dc-key/ed25519.js';
+export { Errors } from './common/error.js';
+
+declare global {
+    interface PromiseConstructor {
+        withResolvers<T = any>(): {
+            promise: Promise<T>;
+            resolve: (value: T | PromiseLike<T>) => void;
+            reject: (reason?: any) => void;
+        };
+    }
+}

package/dist/types/interfaces/DCContext.d.ts

@@ -0,0 +1,33 @@
+import { Ed25519PubKey } from '../common/dc-key/ed25519.js';
+import { DCConnectInfo, APPInfo, AccountInfo, Account } from '../common/types/types.js';
+import { HeliaLibp2p } from 'helia';
+import { Libp2p } from '@libp2p/interface';
+import { ChainUtil } from '../common/chain.js';
+import { DcUtil } from '../common/dcutil.js';
+import { DBManager } from '../implements/threaddb/dbmanager.js';
+import { DCGrpcServer } from '../implements/threaddb/net/grpcserver.js';
+
+/**
+ * 核心系统上下文接口
+ * 定义所有模块可以访问的核心系统组件
+ */
+interface DCContext {
+    dcNodeClient: HeliaLibp2p<Libp2p>;
+    dcChain: ChainUtil;
+    dcutil: DcUtil;
+    swInited: boolean;
+    connectedDc: DCConnectInfo;
+    AccountBackupDc: DCConnectInfo;
+    appInfo: APPInfo;
+    accountInfo: AccountInfo;
+    userInfo: Account | null;
+    dbManager?: DBManager;
+    publicKey: Ed25519PubKey | undefined;
+    ethAddress: string | undefined;
+    grpcServer: DCGrpcServer;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+    getPubkeyRaw(): Uint8Array;
+    getPublicKey(): Ed25519PubKey;
+}
+
+export type { DCContext };

package/dist/types/interfaces/aiproxy-interface.d.ts

@@ -0,0 +1,97 @@
+import { AIProxyConfig, ProxyCallConfig, UserProxyCallConfig, OnStreamResponseType, IAICallConfig } from '../common/types/types.js';
+import { AIProxyUserPermission } from '../common/constants.js';
+
+/**
+ * AI代理操作接口
+ * 提供AI代理的配置和调用功能
+ */
+interface IAIProxyOperations {
+    /**
+     * 创建AI调用的Proxy配置
+     * @param appId 应用ID
+     * @param configTheme 配置主题
+     * @returns [状态码, 错误信息]
+     */
+    createProxyConfig(appId: string, configTheme: string): Promise<[number | null, Error | null]>;
+    /**
+    * 删除AI调用的Proxy配置
+    * @param appId 应用ID
+    * @param configTheme 配置主题
+    * @returns [状态码, 错误信息]
+    */
+    deleteProxyConfig(appId: string, configTheme: string): Promise<[number | null, Error | null]>;
+    /**
+     * 配置AI代理的访问配置
+     * 如果serverConfig为空,则表示删除该serviceName的配置
+     * @param appId 应用ID
+     * @param configAuthor 配置作者的公钥
+     * @param configTheme 配置主题
+     * @param serviceName 服务名称
+     * @param serviceConfig 服务配置(可选)
+     * @param vaccount 虚拟账户(可选)
+     * @returns [是否配置成功, 错误信息]
+     */
+    configAIProxy(appId: string, configAuthor: string, configTheme: string, serviceName: string, serviceConfig?: AIProxyConfig, vaccount?: string): Promise<[boolean | null, Error | null]>;
+    /**
+     * 配置用户的访问权限
+     * @param appId 应用ID
+     * @param configAuthor 配置作者的公钥
+     * @param configTheme 配置主题
+     * @param authPubkey 被授权用户的公钥
+     * @param permission 权限级别
+     * @param authConfig 授权配置
+     * @param vaccount 虚拟账户(可选)
+     * @returns [状态码, 错误信息]
+     */
+    configAuth(appId: string, configAuthor: string, configTheme: string, authPubkey: string, permission: AIProxyUserPermission, authConfig: ProxyCallConfig, vaccount?: string): Promise<[number | null, Error | null]>;
+    /**
+     * 获取AI代理的所有配置
+     * 包括服务与授权列表
+     * @param appId 应用ID
+     * @param themeAuthor 主题作者的公钥
+     * @param configTheme 配置主题
+     * @param vaccount 虚拟账户(可选)
+     * @returns [用户授权配置列表, AI代理配置列表, 错误信息]
+     */
+    GetAIProxyConfig(appId: string, themeAuthor: string, configTheme: string, vaccount?: string): Promise<[UserProxyCallConfig[] | null, AIProxyConfig[] | null, Error | null]>;
+    /**
+     * 获取当前用户自身的AI代理授权信息
+     * @param appId 应用ID
+     * @param themeAuthor 主题作者的公钥
+     * @param configTheme 配置主题
+     * @returns [授权配置, 错误信息]
+     */
+    GetUserOwnAIProxyAuth(appId: string, themeAuthor: string, configTheme: string): Promise<[ProxyCallConfig | null, Error | null]>;
+    /**
+     * 执行AI代理调用
+     * 包括代理与AI的通信或者与MCPServer的通信
+     * @param reqBody 请求体
+     * @param forceRefresh 是否强制刷新,强制刷鞋会消耗一定数量的token,一般在更新了用户授权后,才需要强制刷新
+     * @param onStreamResponse 流式响应回调函数
+     * @param appId 应用ID(可选),为空时使用默认的调用配置中的appId
+     * @param themeAuthor(可选) 主题作者的公钥,为空时使用默认的调用配置中的themeAuthor
+     * @param configTheme(可选) 配置主题,为空时使用默认的调用配置中的configTheme
+     * @param serviceName(可选) 服务器名称,为空时使用默认的调用配置中的serviceName
+     * @param headers 请求头(可选),为空时使用默认的调用配置中的headers
+     * @param path 请求路径(可选),为空时使用默认的调用配置中的path
+     * @param model 模型名称(可选),为空时使用默认的调用配置中的model
+     * @returns 调用状态码
+     */
+    DoAIProxyCall(context: {
+        signal?: AbortSignal;
+    }, reqBody: string, forceRefresh: boolean, onStreamResponse: OnStreamResponseType, appId?: string, themeAuthor?: string, configTheme?: string, serviceName?: string, headers?: Record<string, string>, path?: string, model?: string): Promise<[number | null, Error | null]>;
+    /**
+     * 设置AI调用的配置
+     * @param appId 应用ID
+     * @param themeAuthor 主题作者的公钥
+     * @param configTheme 配置主题
+     * @param serviceName 服务名称
+     * @param headers 请求头(可选)
+     * @param path 请求路径(可选)
+     * @param model 模型名称(可选)
+     * @returns Promise<void>
+     * */
+    SetAICallConfig(callConfig: IAICallConfig): Promise<Error | null>;
+}
+
+export type { IAIProxyOperations };

package/dist/types/interfaces/auth-interface.d.ts

@@ -0,0 +1,100 @@
+import { AccountInfo, Account, NFTBindStatus, User } from '../common/types/types.js';
+
+/**
+ * 认证操作接口
+ * 处理用户身份验证、账户管理和访问控制
+ */
+interface IAuthOperations {
+    /**
+     * 账户登录通过钱包
+     * @returns 是否登录成功
+     */
+    accountLoginWithWallet(accountInfo?: AccountInfo): Promise<[Account | null, Error | null]>;
+    /**
+     * 账户登录
+     * @param nftAccount NFT账户
+     * @param password 密码
+     * @param safecode 安全码,默认000000
+     * @returns 是否登录成功
+     */
+    accountLogin(nftAccount: string, password: string, safecode: string): Promise<[string, Error | null]>;
+    /**
+     * 签名数据
+     * @param payload 要签名的数据
+     * @returns 签名结果
+     */
+    sign(payload: Uint8Array): Promise<[Uint8Array | null, Error | null]>;
+    /**
+     * 解密数据
+     * @param payload 要解密的数据
+     * @returns 解密结果
+     */
+    decryptWithWallet(payload: Uint8Array): Promise<[Uint8Array | null, Error | null]>;
+    /**
+     * 将公钥绑定NFT账号
+     * @param account NFT账号
+     * @param password 密码
+     * @param seccode 安全码
+     * @param mnemonic 助记词,将安全存储在DC云端
+     * @returns [状态码, 错误信息]
+     */
+    bindNFTAccount(account: string, password: string, seccode: string, mnemonic: string): Promise<[NFTBindStatus | null, Error | null]>;
+    /**
+     * 创建APP访问账号,返回APP专用私钥
+     * @param appId 应用ID
+     * @param mnemonic 助记词
+     * @returns [私钥字符串, 错误]
+     */
+    generateAppAccount(appId: string, mnemonic: string): Promise<[string | null, Error | null]>;
+    /**
+     * 检查NFT账号是否成功绑定到当前用户的公钥
+     * @param nftAccount NFT账号
+     * @param pubKeyStr 公钥字符串
+     * @returns 是否成功绑定
+     */
+    isNftAccountBindSuccess(nftAccount: string, pubKeyStr: string): Promise<[boolean | null, Error | null]>;
+    /**
+     * 检查NFT账号是否已经被公钥绑定
+     * @param nftAccount NFT账号
+     * @returns 是否被其他账号绑定
+     */
+    isNftAccountBinded(nftAccount: string): Promise<[boolean | null, Error | null]>;
+    /**
+      * 获取用户信息
+      * @param nftAccount NFT账户
+      * @returns 用户信息
+      */
+    getUserInfoWithNft(nftAccount: string): Promise<[User | null, Error | null]>;
+    /**
+     * 获取用户钱包信息
+     * @param pubkeyAccount 账户名
+     * @returns 用户信息
+     */
+    getUserInfoWithAccount(pubkeyAccount: string): Promise<[User | null, Error | null]>;
+    /**
+     * 开启定时验证token线程
+     */
+    startDcPeerTokenKeepValidTask(): Promise<[boolean, Error | null]>;
+    /**
+     * 检查用户空间是否足够
+     * @param needSize 需要的空间大小
+     * @returns 空间信息
+     */
+    ifEnoughUserSpace(needSize?: number): Promise<[boolean | null, Error | null]>;
+    /**
+     * 刷新用户信息
+     * @returns 用户信息
+     */
+    refreshUserInfo(): Promise<[User | null, Error | null]>;
+    /**
+     * 获取用户默认数据库
+     * @param threadId 数据库ID
+     * @param rk 读取密钥,主要用来加解密真正的数据,注意对数据记录进行加密和解密
+     * @param sk 服务密钥,主要用来处理传输过程加解密,主要对数据链表头进行加密和解密
+     * @param remark 备注信息
+     * @returns 用户默认数据库信息
+     */
+    setUserDefaultDB(threadId: string, rk: string, sk: string, remark: string, vaccount?: string): Promise<Error | null>;
+}
+
+export type { IAuthOperations };

package/dist/types/interfaces/cache-interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 临时缓存操作接口
+ * 提供从分布式网络获取和设置缓存值的功能,调用前请确保DC网络已连接,且用户已登录
+ */
+interface ICacheOperations {
+    /**
+     * 从DC网络获取缓存值
+     * @param key 缓存键
+     * @returns 缓存值，如果键不存在则返回null
+     * @throws 当操作失败时抛出错误
+     */
+    getCacheValue(key: string): Promise<[string | null, Error | null]>;
+    /**
+     * 设置缓存值
+     * @param value 缓存值
+     * @param expire 可选，过期时间(秒)，默认为一天
+     * @returns 设置操作的结果
+     * @throws 当操作失败时抛出错误
+     */
+    setCacheKey(value: string, expire?: number): Promise<[string | null, Error | null]>;
+}
+
+export type { ICacheOperations };

package/dist/types/interfaces/client-interface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * client接口
+ */
+interface IClientOperations {
+    /**
+     * 获取链接DC节点的hostID以及本机的公网地址
+     *
+     * @returns peerID表示DC节点的hostID,reqAddr表示本机的公网地址
+     */
+    getHostID(): Promise<[{
+        peerID: string;
+        reqAddr: string;
+    } | null, Error | null]>;
+}
+
+export type { IClientOperations };

package/dist/types/interfaces/comment-interface.d.ts

@@ -0,0 +1,113 @@
+import { OpenFlag, ThemePermission } from '../common/constants.js';
+import { ThemeObj, ThemeComment, ThemeAuthInfo } from '../common/types/types.js';
+
+/**
+ * 评论操作接口
+ * 提供评论系统的所有功能操作
+ */
+interface ICommentOperations {
+    /**
+     * 为指定主题开通评论功能
+     * @param theme 主题/对象标识符
+     * @param openFlag 开放标志 0-公开 1-私密 2-鉴权
+     * @param commentSpace 可选，评论空间上限大小(字节)，默认50MB
+     * @returns 操作结果  0:成功 1:评论空间没有配置 2:评论空间不足 3:评论数据同步中
+     */
+    addThemeObj(theme: string, openFlag: OpenFlag, commentSpace?: number): Promise<[number | null, Error | null]>;
+    /**
+     * 添加用户链下评论空间,DC为了提升性能,用户发布评论等操作,无需上链,有DC节点在TEE环境维护用户的评论空间使用情况,新用户在发布评论前需要先添加评论空间,每次调用会分配50MB的链下空间,用于发布评论等链下操作
+     * @returns 添加结果 true:成功  false:失败
+     */
+    addUserOffChainSpace(): Promise<[boolean | null, Error | null]>;
+    /**
+     * 为用户添加链下操作次数,DC为了提升性能,用户发布评论等操作,无需上链,用于发布评论等链下操作次数,
+     * @param times 操作次数
+     * @param vaccount 可选，用户的虚拟账号
+     * @returns 操作结果  0:成功 1:评论空间没有配置 2:评论空间不足 3:评论数据同步中
+     */
+    addUserOffChainOpTimes(times: number, vaccount?: string): Promise<[boolean | null, Error | null]>;
+    /**
+     * 为已开通评论的主题增加评论空间,为了防止每个主题评论空间浪费,每个主题在创建时会分配50MB的评论空间,如果后续不够,可以通过这个接口增加
+     * 本方法可以为指定主题的keyvaluedb增加空间
+     * @param theme 主题/对象标识符
+     * @param addSpace 要增加的空间大小(字节)
+     * @returns 操作结果
+     */
+    addThemeSpace(theme: string, addSpace: number): Promise<[number | null, Error | null]>;
+    /**
+     * 向指定主题发布评论
+     * @param theme 主题/对象标识符
+     * @param themeAuthor 主题作者的公钥
+     * @param commentType 评论类型
+     * @param comment 评论内容
+     * @param refercommentkey 可选，引用的评论键
+     * @param openFlag 可选，评论可见性标志
+     * @returns 评论发布结果
+     */
+    publishCommentToTheme(theme: string, themeAuthor: string, commentType: number, comment: string, openFlag?: number, refercommentkey?: string): Promise<[string | null, Error | null]>;
+    /**
+     * 删除自己发布的评论,只是删除了在自己列表中的评论,不能删除已经发布到主题下的评论
+     * @param theme 主题/对象标识符
+     * @param themeAuthor 主题作者的公钥
+     * @param commentKey 评论的唯一键
+     * @returns 删除操作结果
+     */
+    deleteSelfComment(theme: string, themeAuthor: string, commentKey: string): Promise<[number | null, Error | null]>;
+    /**
+     * 获取指定作者的主题对象列表,无法查询作者设置为私密的主题
+     * @param themeAuthor 主题作者的公钥
+     * @param startHeight 可选，查询起始高度
+     * @param direction 可选，查询方向 (0:从新到旧, 1:从旧到新)
+     * @param offset 可选，结果集偏移量
+     * @param limit 可选，最大返回数量，默认100
+     * @param seekKey 可选，查询的起始键,格式为返回记录的 blockheight/key
+     * @returns 主题对象列表
+     */
+    getThemeObj(themeAuthor: string, startHeight?: number, direction?: number, offset?: number, limit?: number, seekKey?: string): Promise<[ThemeObj[] | null, Error | null]>;
+    /**
+     * 获取指定主题的评论列表,无法查询作者设置为私密的评论
+     * @param theme 主题/对象标识符
+     * @param themeAuthor 主题作者的公钥
+     * @param startHeight 可选，查询起始高度
+     * @param direction 可选，查询方向 (0:从新到旧, 1:从旧到新)
+     * @param offset 可选，结果集偏移量
+     * @param limit 可选，最大返回数量，默认100
+     * @param seekKey 可选，查询的起始键,格式为返回记录的 blockheight/key
+     * @returns 主题的评论列表
+     */
+    getThemeComments(theme: string, themeAuthor: string, startHeight?: number, direction?: number, offset?: number, limit?: number, seekKey?: string): Promise<[ThemeComment[] | null, Error | null]>;
+    /**
+      * 配置主题的授权信息
+      * @param appId 应用ID
+      * @param themeAuthor 主题作者的公钥
+      * @param theme 主题名称
+      * @param authPubkey 被授权者的公钥
+      * @param permission 权限级别
+      * @param remark 备注信息
+      * @param vaccount 可选的虚拟账户
+      * @returns [授权状态码, 错误信息]
+      */
+    configAuth(themeAuthor: string, theme: string, authPubkey: string, permission: ThemePermission, remark: string, vaccount?: string): Promise<[number | null, Error | null]>;
+    /**
+     * 获取指定主题的授权列表,
+     * @param appId 应用ID
+     * @param themeAuthor 主题作者的公钥
+     * @param theme 主题/对象标识符
+     * @param vaccount 可选，虚拟账户
+     * @returns [授权列表, 评论列表, 错误信息]
+     */
+    getAuthList(themeAuthor: string, theme: string, vaccount?: string): Promise<[ThemeAuthInfo[] | null, ThemeComment[] | null, Error | null]>;
+    /**
+     * 获取指定用户发布的评论列表,无法查询用户设置为私密的评论
+     * @param userPubkey 用户公钥
+     * @param startHeight 可选，查询起始高度
+     * @param direction 可选，查询方向 (0:从新到旧, 1:从旧到新)
+     * @param offset 可选，结果集偏移量
+     * @param limit 可选，最大返回数量，默认100
+     * @param seekKey 可选，查询的起始键,格式为返回记录的 blockheight/key
+     * @returns 用户的评论列表
+     */
+    getUserComments(userPubkey: string, startHeight?: number, direction?: number, offset?: number, limit?: number, seekKey?: string): Promise<[ThemeComment[] | null, Error | null]>;
+}
+
+export type { ICommentOperations };

package/dist/types/interfaces/database-interface.d.ts

@@ -0,0 +1,138 @@
+import { ICollectionConfig, IDBInfo } from '../implements/threaddb/core/core.js';
+
+/**
+ * 数据库操作接口,这个数据库主要由threadid确保唯一,servicekey,readkey多重加密来确保数据安全,其中readkey永远不离开用户,servicekey会在DC云端的TEE环境中参与数据备份
+ * 提供基于ThreadDB的分布式数据库管理功能
+ */
+interface IDatabaseOperations {
+    /**
+     * 初始化数据库管理器
+     * 创建数据库操作所需的组件和服务
+     * @returns 错误信息
+     */
+    initDBManager(): Promise<Error | null>;
+    /**
+     * 创建新数据库
+     * @param name 数据库名称
+     * @param b32Rk base32编码的读取密钥
+     * @param b32Sk base32编码的服务密钥
+     * @param jsonCollections 集合配置数组，定义数据库中的集合结构
+     * @returns 创建的线程ID和错误信息
+     */
+    newDB(name: string, b32Rk: string, b32Sk: string, jsonCollections: ICollectionConfig[]): Promise<[string | null, Error | null]>;
+    /**
+     * 从分布式网络同步数据库
+     * @param threadid 线程ID
+     * @param dbname 数据库名称
+     * @param dbAddr 数据库地址
+     * @param b32Rk base32编码的读取密钥
+     * @param b32Sk base32编码的服务密钥
+     * @param block 是否阻塞等待同步完成
+     * @param collectionInfos 集合配置数组，定义数据库中的集合结构
+     * @returns 错误信息或null表示成功
+     */
+    syncDbFromDC(threadid: string, dbname: string, dbAddr: string, b32Rk: string, b32Sk: string, block: boolean, collectionInfos: ICollectionConfig[]): Promise<Error | null>;
+    /**
+     * 刷新数据库，从分布式网络获取最新数据
+     * @param threadid 数据库线程ID
+     * @returns 错误信息或null表示成功
+     */
+    refreshDBFromDC(threadid: string): Promise<Error | null>;
+    /**
+     * 同步数据库到分布式网络
+     * @param tId 线程ID
+     * @returns 错误信息或null表示成功
+     */
+    syncDBToDC(tId: string): Promise<Error | null>;
+    /**
+     * 获取数据库信息
+     * @param id threaddbID
+     * @returns 数据库信息字符串,或错误
+     */
+    getDBInfo(id: string): Promise<[IDBInfo | null, Error | null]>;
+    /**
+     * 升级集合结构
+     * @param threadId 线程ID
+     * @param collections 集合配置列表
+     * @returns 错误信息或null
+     */
+    upgradeCollections(threadId: string, collections: ICollectionConfig[]): Promise<Error | null>;
+    /**
+     * 关闭数据库管理器
+     * @throws 关闭失败时抛出错误
+     */
+    close(): Promise<Error | null>;
+    /**
+     * 在集合中创建新对象实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param jsonInstance JSON字符串表示的实例对象
+     * @returns 创建的实例ID,或错误
+     */
+    create(threadId: string, collectionName: string, jsonInstance: string): Promise<[string | null, Error | null]>;
+    /**
+     * 通过ID删除实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param instanceID 要删除的实例ID
+     * @throws 删除失败时抛出错误
+     */
+    delete(threadId: string, collectionName: string, instanceID: string): Promise<Error | null>;
+    /**
+     * 更新已存在的实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param instance JSON字符串表示的实例对象
+     * @throws 更新失败时抛出错误
+     */
+    save(threadId: string, collectionName: string, instance: string): Promise<Error | null>;
+    /**
+     * 批量删除多个实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param instanceIDs 逗号分隔或JSON数组表示的实例ID列表
+     * @throws 删除失败时抛出错误
+     */
+    deleteMany(threadId: string, collectionName: string, instanceIDs: string): Promise<Error | null>;
+    /**
+     * 检查指定实例是否存在
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param instanceID 要检查的实例ID
+     * @returns 布尔值表示实例是否存在
+     */
+    has(threadId: string, collectionName: string, instanceID: string): Promise<boolean>;
+    /**
+     * 根据查询条件查找实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param queryString JSON字符串表示的查询条件,
+     * 格式举例:(condition表示and条件组合, ors表示或条件组合, sort表示排序, seek表示分页)
+     * 格式1: `{"condition":"age=80 and name='John'"}`,"sort":{"fieldPath":"age","desc":true}}`
+     * 格式2: `{"ors":[{"condition":"age = 21 and name = 'foo'"}]}`
+     * 格式3: `{"condition":"age > 21 ","ors":[{"condition":"age = 21 and name = 'foo'"}],"sort":{"fieldPath":"age","desc":true},skip:10,"seek":"01fyc691gh671nf0s8qpt0ych8"}`
+     * @returns JSON字符串表示的查询结果
+     * @throws 查询失败时抛出错误
+     */
+    find(threadId: string, collectionName: string, queryString?: string): Promise<[string | null, Error | null]>;
+    /**
+     * 通过ID查找实例
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param instanceID 实例ID
+     * @returns JSON字符串表示的实例
+     * @throws 查询失败时抛出错误
+     */
+    findByID(threadId: string, collectionName: string, instanceID: string): Promise<[string | null, Error | null]>;
+    /**
+     * 获取在指定时间后被修改的实例ID列表
+     * @param threadId 线程ID
+     * @param collectionName 集合名称
+     * @param time 时间戳（毫秒）
+     * @returns JSON字符串表示的实例ID列表
+     * @throws 查询失败时抛出错误
+     */
+    modifiedSince(threadId: string, collectionName: string, time: number): Promise<[string | null, Error | null]>;
+}
+
+export type { IDatabaseOperations };

package/dist/types/interfaces/file-interface.d.ts

@@ -0,0 +1,97 @@
+import { SeekableFileStream } from '../implements/file/seekableFileStream.js';
+
+/**
+ * 文件操作接口
+ * 提供文件上传、下载、缓存等功能
+ */
+interface IFileOperations {
+    /**
+     * 获取可寻址文件流
+     * @param ipfsPath IPFS路径或CID
+     * @param decryptKey 解密密钥,base32的symmetric key
+     * @returns 可寻址文件流实例
+     */
+    getSeekableFileStream(ipfsPath: string, decryptKey: string): Promise<SeekableFileStream>;
+    /**
+     * 清理文件缓存
+     * @param pathname 可选的特定路径，不提供则清除所有缓存
+     */
+    clearFileCache(pathname?: string): void;
+    /**
+     * 获取缓存统计信息
+     * @returns 包含缓存总数和键列表的统计对象
+     */
+    getCacheStats(): [{
+        total: number;
+        keys: string[];
+    } | null, Error | null];
+    /**
+     * 获取文件内容
+     * @param cid 文件的内容标识符
+     * @param decryptKey 解密密钥
+     * @returns 文件的字节数组，失败则返回undefined
+     */
+    getFile(cid: string, decryptKey: string): Promise<[Uint8Array | null, Error | null]>;
+    /**
+     * 创建文件可读流
+     * @param cid 文件的内容标识符
+     * @param decryptKey 解密密钥
+     * @returns 可读流对象，失败则返回null
+     */
+    createFileStream(cid: string, decryptKey: string): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * 添加文件到存储
+     * @param file 要上传的文件对象
+     * @param enkey 加密密钥
+     * @param onUpdateTransmitSize 传输进度回调函数
+     * @returns 添加结果
+     */
+    addFile(file: File, enkey: string, onUpdateTransmitSize: (status: number, size: number) => void): Promise<[string | null, Error | null]>;
+    /**
+     * 添加文件夹到存储
+     * @param files 要上传的文件夹下的文件列表
+     * @param enkey 加密密钥,base32的symmetric key
+     * @param onUpdateTransmitCount 传输进度回调函数
+     * @returns 添加结果
+     */
+    addFolder(files: FileList, enkey: string, onUpdateTransmitCount: (status: number, total: number, process: number) => void): Promise<[string | null, Error | null]>;
+    /**
+     * 获取文件夹下的所有文件,包括内容（支持多级目录递归）
+     * @param cid 根目录的CID
+     * @param decryptKey 解密密钥
+     * @param recursive 是否递归获取子目录，默认false（保持向后兼容）
+     * @returns 文件列表：[{Name:文件或目录名，Type：0-文件 1-目录，Size：大小，Hash：文件或目录cid，Path：完整路径}]
+     */
+    getFolderFileListWithContent(cid: string, decryptKey: string, recursive: boolean): Promise<[Array<{
+        Name: string;
+        Type: number;
+        Size: number;
+        Hash: string;
+        Path: string;
+        Content?: Uint8Array;
+    }> | null, Error | null]>;
+    /**
+     * 获取文件夹下的文件列表（支持多级目录递归）
+     * @param cid 根目录的CID
+     * @param flag 是否需要连接节点
+     * @param recursive 是否递归获取子目录，默认false（保持向后兼容）
+     * @returns 返回JSON格式的文件列表：[{Name:文件或目录名，Type：0-文件 1-目录，Size：大小，Hash：文件或目录cid，Path：完整路径}]
+     */
+    getFolderFileList(cid: string, flag: number, recursive: boolean): Promise<[Array<{
+        Name: string;
+        Type: number;
+        Size: number;
+        Hash: string;
+        Path: string;
+        Content?: Uint8Array;
+    }> | null, Error | null]>;
+    /**
+     * 创建自定义文件列表
+     * @param filesMap 文件列表，可以是Map或Record对象
+     * @param rootFolderName 根文件夹名称
+     * @returns 自定义文件列表对象
+     */
+    createCustomFileList(filesMap: Map<string, string | Uint8Array | ArrayBuffer> | Record<string, string | Uint8Array | ArrayBuffer>, rootFolderName: string): [FileList | null, Error | null];
+}
+
+export type { IFileOperations };