@cloudbase/js-sdk 2.26.1 → 2.26.3

package/index.d.ts

@@ -78,11 +78,19 @@ declare namespace cloudbase {
   }
 
   interface ICloudbaseConfig {
+    /** 环境 ID，在腾讯云开发控制台 → 环境 → 环境总览中获取 */
     env: string
+    /**
+     * 地域信息
+     * @example 'ap-shanghai'
+     */
     region?: string
+    /** 网络请求超时上限，单位 ms，默认 15000 */
     timeout?: number
+    /** 本地登录态保留期限 */
     persistence?: Persistence
     oauthClient?: any
+    /** 是否开启调试模式 */
     debug?: boolean
     _fromApp?: ICloudbase
     clientId?: string
@@ -95,7 +103,31 @@ declare namespace cloudbase {
     }
     accessKey?: string
     endPointMode?: EndPointKey
-    lang?: LANGS 
+    lang?: LANGS
+    /**
+     * 认证相关配置
+     * @example
+     * ```typescript
+     * cloudbase.init({
+     *   env: 'your-env-id',
+     *   auth: {
+     *     detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
+     *   }
+     * })
+     * ```
+     */
+    auth?: {
+      /** 是否自动检测 URL 中的 OAuth 回调参数，默认 false */
+      detectSessionInUrl?: boolean
+      /** 密钥 ID（Node.js 端使用） */
+      secretId?: string
+      /** 密钥（Node.js 端使用） */
+      secretKey?: string
+      /** 临时会话 Token（Node.js 端使用） */
+      sessionToken?: string
+      /** 密钥类型 */
+      secretType?: 'SESSION_SECRET' | 'SECRET'
+    }
   }
 
   interface ICloudbaseExtension {
@@ -148,20 +180,49 @@ declare namespace cloudbase {
    *
    * @example
    * ```javascript
+   * // 基本用法
    * const app = cloudbase.init({
    *   env: 'your-envid',
    *   timeout: 15000
    * });
+   *
+   * // 推荐：从环境变量读取环境 ID
+   * const app = cloudbase.init({
+   *   env: process.env.CLOUDBASE_ENV || import.meta.env.VITE_CLOUDBASE_ENV || 'your-envid'
+   * });
+   *
+   * // 使用认证配置
+   * const app = cloudbase.init({
+   *   env: 'your-envid',
+   *   auth: {
+   *     detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
+   *   }
+   * });
    * ```
    *
    * @param config 初始化配置
-   * @param config.env 环境ID
+   * @param config.env 环境ID，在腾讯云开发控制台 → 环境 → 环境总览中获取
    * @param config.timeout 【可选】网络请求超时上限，单位`ms`，默认值`15000`
+   * @param config.auth 【可选】认证相关配置
    *
    * @return {!cloudbase.app.App} 初始化成功的Cloudbase实例
    */
   function init(config: ICloudbaseConfig): cloudbase.app.App
 
+  /**
+   * 检查 Cloudbase 实例是否已完成初始化
+   *
+   * @example
+   * ```javascript
+   * if (!cloudbase.isInitialized()) {
+   *   cloudbase.init({ env: 'your-envid' });
+   * }
+   * ```
+   *
+   * @returns 是否已初始化
+   */
+  function isInitialized(): boolean
+
   function updateConfig(config: ICloudbaseUpgradedConfig): void
 
   function updateLang(lang: LANGS): void
@@ -512,8 +573,7 @@ declare namespace cloudbase.app {
 
     getFileInfo(
       params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
-      callback?: Function,
-    ): Promise<cloudbase.storage.ICloudbaseGetTempFileURLResult>
+    ): Promise<cloudbase.storage.ICloudbaseGetFileInfoResult>
     /**
      * 云存储-获取上传元信息
      *
@@ -522,10 +582,21 @@ declare namespace cloudbase.app {
      * @param callback
      */
     getUploadMetadata(params: cloudbase.storage.ICloudbaseGetUploadMetadataParams, callback?: Function): Promise<any>
+
+    /**
+     * Supabase 风格的文件存储 API
+     *
+     * @example
+     * ```typescript
+     * const bucket = app.storage.from('my-bucket')
+     * const { data, error } = await bucket.upload('path/to/file.jpg', file)
+     * ```
+     */
+    storage: cloudbase.storage.SupabaseFileAPILikeStorage
     /**
      * 获取数据库实例
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#%E8%8E%B7%E5%8F%96%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AE%9E%E4%BE%8B}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#%E8%8E%B7%E5%8F%96%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AE%9E%E4%BE%8B}
      *
      * @example
      * ```javascript
@@ -537,7 +608,7 @@ declare namespace cloudbase.app {
      *
      * @return 数据库实例
      */
-    database(dbConfig?: object): cloudbase.database.App
+    database(dbConfig?: cloudbase.database.IDbConfig): cloudbase.database.App
     /**
      * 调用扩展能力插件功能
      *
@@ -863,6 +934,7 @@ declare namespace cloudbase.auth {
     setPassword(params: authModels.SetPasswordRequest): Promise<void>
     /**
      * 获取用户信息
+     * @deprecated 请使用 getCurrentUser 代替
      *
      * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetuserinfo}
      */
@@ -1307,6 +1379,296 @@ declare namespace cloudbase.auth {
      * @param params
      */
     signInWithPhoneAuth(params: { phoneCode: string }): Promise<SignInRes>
+
+    // ========== v1 兼容 API ==========
+
+    /**
+     * v1 API: 获取用于微信登录的 WeixinAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInWithOAuth({ provider: appid }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.weixinAuthProvider({ appid: 'wx-appid', scope: 'snsapi_login' });
+     * provider.signInWithRedirect();
+     * ```
+     *
+     * @param options
+     * @param options.appid 微信 AppID
+     * @param options.scope 微信授权范围
+     */
+    weixinAuthProvider(options: { appid: string; scope: string }): cloudbase.auth.WeixinAuthProvider
+
+    /**
+     * v1 API: 获取用于自定义登录的 CustomAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.customAuthProvider();
+     * await provider.signIn(ticket);
+     * ```
+     */
+    customAuthProvider(): cloudbase.auth.CustomAuthProvider
+
+    /**
+     * v1 API: 获取用于匿名登录的 AnonymousAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.anonymousAuthProvider();
+     * await provider.signIn();
+     * ```
+     */
+    anonymousAuthProvider(): cloudbase.auth.AnonymousAuthProvider
+
+    /**
+     * v1 API: 使用邮箱和密码注册云开发账户
+     *
+     * @deprecated 建议使用 auth.signUp({ email, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * await auth.signUpWithEmailAndPassword('user@example.com', 'password123');
+     * ```
+     *
+     * @param email 邮箱
+     * @param password 密码
+     */
+    signUpWithEmailAndPassword(email: string, password: string): Promise<SignUpRes>
+
+    /**
+     * v1 API: 使用邮箱和密码登录云开发（支持两种调用方式）
+     *
+     * @deprecated 建议使用 auth.signInWithPassword({ email, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * // 方式一（v1 风格）：
+     * await auth.signInWithEmailAndPassword('user@example.com', 'password123');
+     *
+     * // 方式二（v3 风格）：
+     * const { data, error } = await auth.signInWithEmailAndPassword({
+     *   email: 'user@example.com',
+     *   password: 'password123'
+     * });
+     * ```
+     *
+     * @param emailOrParams - 邮箱字符串（v1）或包含 email 和 password 的对象（v3）
+     * @param password - 密码（仅 v1 风格时使用）
+     */
+    signInWithEmailAndPassword(emailOrParams: string | { email: string; password: string; is_encrypt?: boolean }, password?: string): Promise<SignInRes | ILoginState>
+
+    /**
+     * v1 API: 发送重置密码的邮件
+     *
+     * @deprecated 建议使用 auth.resetPasswordForEmail(email) 替代。
+     *
+     * @example
+     * ```javascript
+     * await auth.sendPasswordResetEmail('user@example.com');
+     * ```
+     *
+     * @param email 邮箱
+     */
+    sendPasswordResetEmail(email: string): Promise<void>
+
+    /**
+     * v1 API: 使用用户名和密码登录云开发
+     *
+     * @deprecated 建议使用 auth.signInWithPassword({ username, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.signInWithUsernameAndPassword('username', 'password123');
+     * ```
+     *
+     * @param username 用户名
+     * @param password 密码
+     */
+    signInWithUsernameAndPassword(username: string, password: string): Promise<ILoginState>
+
+    /**
+     * v1 API: 发送手机验证码
+     *
+     * @deprecated 建议使用 auth.signInWithOtp({ phone }) 或 auth.getVerification({ phone_number }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const success = await auth.sendPhoneCode('+8613800138000');
+     * ```
+     *
+     * @param phoneNumber 手机号
+     * @returns 是否发送成功
+     */
+    sendPhoneCode(phoneNumber: string): Promise<boolean>
+
+    /**
+     * v1 API: 手机号注册（支持短信验证码+密码方式）
+     *
+     * @deprecated 建议使用 auth.signUp({ phone_number, verification_code, password? }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.signUpWithPhoneCode('+8613800138000', '123456', 'password');
+     * ```
+     *
+     * @param phoneNumber 手机号
+     * @param phoneCode 验证码
+     * @param password 可选密码
+     */
+    signUpWithPhoneCode(phoneNumber: string, phoneCode: string, password?: string): Promise<ILoginState>
+
+    /**
+     * v1 API: 手机号登录（支持短信验证码 or 密码方式）
+     *
+     * @deprecated 密码方式建议使用 auth.signInWithPassword({ phone, password }) 替代；
+     * 验证码方式建议使用 auth.signInWithOtp({ phone }) 替代。
+     *
+     * @example
+     * ```javascript
+     * // 验证码登录
+     * const loginState = await auth.signInWithPhoneCodeOrPassword({
+     *   phoneNumber: '+8613800138000',
+     *   phoneCode: '123456'
+     * });
+     *
+     * // 密码登录
+     * const loginState = await auth.signInWithPhoneCodeOrPassword({
+     *   phoneNumber: '+8613800138000',
+     *   password: 'password123'
+     * });
+     * ```
+     *
+     * @param params
+     */
+    signInWithPhoneCodeOrPassword(params: {
+      phoneNumber: string
+      phoneCode?: string
+      password?: string
+    }): Promise<ILoginState>
+
+    /**
+     * v1 API: 手机号强制重置密码
+     *
+     * @deprecated 建议使用 auth.resetPasswordForEmail(phoneNumber) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.forceResetPwdByPhoneCode({
+     *   phoneNumber: '+8613800138000',
+     *   phoneCode: '123456',
+     *   password: 'newPassword'
+     * });
+     * ```
+     *
+     * @param params
+     */
+    forceResetPwdByPhoneCode(params: {
+      phoneNumber: string
+      phoneCode: string
+      password: string
+    }): Promise<ILoginState>
+
+    /**
+     * v1 API: 接收一个回调函数，在刷新短期访问令牌前调用，根据返回值决定是否刷新
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 监听 TOKEN_REFRESHED 事件替代。
+     *
+     * @param callback 回调函数，返回 true 则刷新，返回 false 则不刷新
+     */
+    shouldRefreshAccessToken(callback: () => boolean): void
+
+    /**
+     * v1 API: 接收一个回调函数，在登录状态过期时调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_OUT 事件。
+     *
+     * @param callback 登录态过期回调
+     */
+    onLoginStateExpired(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在短期访问令牌刷新后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 TOKEN_REFRESHED 事件。
+     *
+     * @param callback 令牌刷新回调
+     */
+    onAccessTokenRefreshed(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在匿名登录状态被转换后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_IN 事件。
+     *
+     * @param callback 匿名转正回调
+     */
+    onAnonymousConverted(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在登录类型发生变化后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_IN / SIGNED_OUT 事件。
+     *
+     * @param callback 登录类型变化回调
+     */
+    onLoginTypeChanged(callback: Function): void
+  }
+
+  // ========== v1 兼容 Provider 类 ==========
+
+  /**
+   * v1 微信登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInWithOAuth({ provider }) 替代。
+   */
+  interface WeixinAuthProvider {
+    /**
+     * 跳转微信授权页面进行登录
+     * @deprecated 建议使用 auth.signInWithOAuth({ provider: 'providerId' }) 替代。
+     */
+    signInWithRedirect(): void
+    /**
+     * 获取微信授权重定向结果
+     * @deprecated 建议使用 auth.verifyOAuth({ code, state, provider }) 替代。
+     */
+    getRedirectResult(options?: { createUser?: boolean; syncUserInfo?: boolean }): Promise<any>
+    /**
+     * 获取微信绑定重定向结果
+     * @deprecated 建议使用 auth.linkIdentity({ provider: 'providerId' }) 替代。
+     */
+    getLinkRedirectResult(options?: { withUnionId?: boolean }): Promise<void>
+  }
+
+  /**
+   * v1 自定义登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+   */
+  interface CustomAuthProvider {
+    /**
+     * 使用自定义登录凭据 ticket 登录云开发
+     * @param ticket 自定义登录 ticket
+     * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+     */
+    signIn(ticket: string): Promise<void>
+  }
+
+  /**
+   * v1 匿名登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+   */
+  interface AnonymousAuthProvider {
+    /**
+     * 匿名登录云开发
+     * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+     */
+    signIn(): Promise<void>
   }
 }
 /**
@@ -1427,68 +1789,427 @@ declare namespace cloudbase.storage {
     }>
     requestId?: string
   }
-}
 
-declare namespace cloudbase.database {
-  /**
-   * realtime types
-   */
-  interface IWatchOptions {
-    // server realtime data init & change event
-    onChange: (snapshot: ISnapshot) => void
-    // error while connecting / listening
-    onError: (error: any) => void
+  interface ICloudbaseGetFileInfoResultItem {
+    code?: string
+    message?: string
+    fileID: string
+    tempFileURL: string
+    fileName?: string
+    cloudId?: string
+    contentType?: string
+    mime?: string
+    size?: number
+    cacheControl?: string
+    lastModified?: string
+    etag?: string
   }
-  interface DBRealtimeListener {
-    /**
-     * 关闭实时推送
-     *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#shu-ju-ku-shi-shi-tui-song}
-     *
-     * @example
-     * // 启动监听
-     * const ref = db
-     *   .collection("collName")
-     *   .where({ test: _.gt(0) })
-     *   .watch({
-     *     onChange: (snapshot) => {
-     *       console.log("收到snapshot**********", snapshot);
-     *     },
-     *     onError: (error) => {
-     *       console.log("收到error**********", error);
-     *     }
-     *   });
-     * // 关闭监听
-     * ref.close();
-     */
-    close: () => void
+
+  interface ICloudbaseGetFileInfoResult {
+    fileList: ICloudbaseGetFileInfoResultItem[]
+    requestId: string
   }
-  type DataType = 'init' | 'update' | 'add' | 'remove' | 'replace' | 'limit'
-  type QueueType = 'init' | 'enqueue' | 'dequeue' | 'update'
-  interface ISnapshot {
-    id: number
-    docChanges: ISingleDBEvent[]
-    docs: Record<string, any>
-    type?: SnapshotType
+
+  // ---- Supabase-like Storage Types ----
+
+  type FileBody =
+    | ArrayBuffer
+    | ArrayBufferView
+    | Blob
+    | Buffer
+    | File
+    | FormData
+    | NodeJS.ReadableStream
+    | ReadableStream<Uint8Array>
+    | URLSearchParams
+    | string
+
+  interface FileOptions {
+    cacheControl?: string
+    contentType?: string
+    upsert?: boolean
+    duplex?: string
+    metadata?: Record<string, any>
+    headers?: Record<string, string>
   }
 
-  interface ISingleDBEvent {
-    id: number
-    dataType: DataType
-    queueType: QueueType
-    docId: string
-    doc: Record<string, any>
-    updatedFields?: any
-    removedFields?: any
+  interface TransformOptions {
+    width?: number
+    height?: number
+    resize?: 'cover' | 'contain' | 'fill'
+    quality?: number
+    format?: 'origin'
   }
 
-  type SnapshotType = 'init'
+  interface FileObject {
+    name: string
+    bucket_id: string
+    owner: string
+    id: string
+    updated_at: string
+    created_at: string
+    /** @deprecated */
+    last_accessed_at: string
+    metadata: Record<string, any>
+    buckets: {
+      id: string
+      name: string
+      owner: string
+      public: boolean
+      created_at: string
+      updated_at: string
+    }
+  }
 
-  interface IWatchable {
-    /**
-     * 开启实时推送
-     *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AE%9E%E6%97%B6%E6%8E%A8%E9%80%81}
+  interface FileObjectV2 {
+    id: string
+    version: string
+    name: string
+    bucketId: string
+    updatedAt: string
+    createdAt: string
+    /** @deprecated */
+    lastAccessedAt: string
+    size?: number
+    cacheControl?: string
+    contentType?: string
+    etag?: string
+    lastModified?: string
+    metadata?: Record<string, any>
+  }
+
+  class StorageError extends Error {
+    name: 'StorageError'
+    constructor(message: string)
+  }
+
+  /**
+   * Supabase 风格的文件存储 API
+   *
+   * 通过 `app.storage` 获取实例，提供类似 Supabase Storage 的操作接口。
+   *
+   * @example
+   * ```typescript
+   * const app = cloudbase.init({ env: 'your-envid' })
+   * const bucket = app.storage.from('my-bucket')
+   *
+   * // 上传文件
+   * const { data, error } = await bucket.upload('path/to/file.jpg', file)
+   *
+   * // 获取签名 URL
+   * const { data } = await bucket.createSignedUrl('path/to/file.jpg', 3600)
+   *
+   * // 下载文件
+   * const { data } = await bucket.download('path/to/file.jpg')
+   * ```
+   */
+  interface SupabaseFileAPILikeStorage {
+    /**
+     * 启用错误抛出模式，而非返回 `{ data: null, error }` 格式
+     */
+    throwOnError(): this
+
+    /**
+     * 选择存储桶
+     *
+     * @param bucket 存储桶名称
+     * @returns 当前实例（链式调用）
+     *
+     * @example
+     * ```typescript
+     * const bucket = app.storage.from('my-bucket')
+     * ```
+     */
+    from(bucket?: string): this
+
+    /**
+     * 上传文件
+     *
+     * @param path 文件路径
+     * @param fileBody 文件内容
+     * @param fileOptions 上传选项
+     */
+    upload(
+      path: string,
+      fileBody: FileBody,
+      fileOptions?: FileOptions,
+    ): Promise<
+      | { data: { id: string; path: string; fullPath: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 上传文件到已签名的 URL
+     *
+     * @param path 文件路径
+     * @param token 签名 Token
+     * @param fileBody 文件内容
+     * @param fileOptions 上传选项
+     */
+    uploadToSignedUrl(
+      path: string,
+      token: string,
+      fileBody: FileBody,
+      fileOptions?: FileOptions,
+    ): Promise<
+      | { data: { id: string; path: string; fullPath: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 创建用于上传的签名 URL
+     *
+     * @param path 文件路径
+     */
+    createSignedUploadUrl(path: string): Promise<
+      | {
+          data: {
+            signedUrl: string
+            token: string
+            path: string
+            authorization?: string
+            id?: string
+            cosFileId?: string
+            downloadUrl?: string
+          }
+          error: null
+        }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 更新（覆盖）文件
+     *
+     * @param path 文件路径
+     * @param fileBody 文件内容
+     * @param fileOptions 上传选项
+     */
+    update(
+      path: string,
+      fileBody: FileBody,
+      fileOptions?: FileOptions,
+    ): Promise<
+      | { data: { id: string; path: string; fullPath: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 移动文件（复制后删除源文件）
+     *
+     * @param fromPath 源文件路径
+     * @param toPath 目标文件路径
+     */
+    move(
+      fromPath: string,
+      toPath: string,
+    ): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 复制文件
+     *
+     * @param fromPath 源文件路径
+     * @param toPath 目标文件路径
+     */
+    copy(
+      fromPath: string,
+      toPath: string,
+    ): Promise<
+      | { data: { path: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 创建签名下载 URL
+     *
+     * @param path 文件路径
+     * @param expiresIn 有效期（秒）
+     * @param options 可选配置
+     */
+    createSignedUrl(
+      path: string,
+      expiresIn: number,
+      options?: {
+        download?: string | boolean
+        transform?: TransformOptions
+      },
+    ): Promise<
+      | { data: { signedUrl: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 批量创建签名下载 URL
+     *
+     * @param paths 文件路径数组
+     * @param expiresIn 有效期（秒）
+     */
+    createSignedUrls(
+      paths: string[],
+      expiresIn: number,
+    ): Promise<
+      | { data: Array<{ path: string; signedUrl: string; error: string | null }>; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 下载文件，返回 Blob
+     *
+     * @param path 文件路径
+     * @param options 图片转换选项
+     */
+    download(
+      path: string,
+      options?: TransformOptions,
+    ): Promise<{ data: Blob; error: StorageError | null }>
+
+    /**
+     * 获取文件详细信息
+     *
+     * @param pathOrFileId 相对路径或 CloudBase fileID
+     */
+    info(pathOrFileId: string): Promise<
+      | { data: FileObjectV2; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 检查文件是否存在
+     *
+     * @param pathOrFileId 相对路径或 CloudBase fileID
+     */
+    exists(pathOrFileId: string): Promise<
+      | { data: boolean; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 获取文件的公开 URL
+     *
+     * @param path 文件路径
+     * @param options 可选配置
+     */
+    getPublicUrl(
+      path: string,
+      options?: {
+        download?: string | boolean
+        transform?: TransformOptions
+      },
+    ): Promise<
+      | { data: { publicUrl: string } }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 批量删除文件
+     *
+     * @param paths 文件路径数组
+     */
+    remove(paths: string[]): Promise<
+      | { data: FileObject[]; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    // ---- 继承自 CloudbaseStorage 的方法 ----
+
+    uploadFile(
+      params: ICloudbaseUploadFileParams,
+      callback?: Function,
+    ): Promise<ICloudbaseUploadFileResult>
+
+    deleteFile(
+      params: ICloudbaseDeleteFileParams,
+      callback?: Function,
+    ): Promise<ICloudbaseDeleteFileResult>
+
+    getTempFileURL(
+      params: ICloudbaseGetTempFileURLParams,
+      callback?: Function,
+    ): Promise<ICloudbaseGetTempFileURLResult>
+
+    downloadFile(
+      params: ICloudbaseDownloadFileParams,
+      callback?: Function,
+    ): Promise<ICloudbaseDownloadFileResult>
+
+    getUploadMetadata(
+      params: ICloudbaseGetUploadMetadataParams,
+      callback?: Function,
+    ): Promise<ICloudbaseFileMetaDataRes>
+
+    copyFile(
+      params: ICloudbaseCopyFileParams,
+      callback?: Function,
+    ): Promise<ICloudbaseCopyFileResult>
+
+    getFileInfo(
+      params: ICloudbaseGetTempFileURLParams,
+    ): Promise<ICloudbaseGetFileInfoResult>
+  }
+}
+
+declare namespace cloudbase.database {
+  /**
+   * realtime types
+   */
+  interface IWatchOptions {
+    // server realtime data init & change event
+    onChange: (snapshot: ISnapshot) => void
+    // error while connecting / listening
+    onError: (error: any) => void
+  }
+  interface DBRealtimeListener {
+    /**
+     * 关闭实时推送
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#shu-ju-ku-shi-shi-tui-song}
+     *
+     * @example
+     * // 启动监听
+     * const ref = db
+     *   .collection("collName")
+     *   .where({ test: _.gt(0) })
+     *   .watch({
+     *     onChange: (snapshot) => {
+     *       console.log("收到snapshot**********", snapshot);
+     *     },
+     *     onError: (error) => {
+     *       console.log("收到error**********", error);
+     *     }
+     *   });
+     * // 关闭监听
+     * ref.close();
+     */
+    close: () => void
+  }
+  type DataType = 'init' | 'update' | 'add' | 'remove' | 'replace' | 'limit'
+  type QueueType = 'init' | 'enqueue' | 'dequeue' | 'update'
+  interface ISnapshot {
+    id: number
+    docChanges: ISingleDBEvent[]
+    docs: Record<string, any>
+    type?: SnapshotType
+  }
+
+  interface ISingleDBEvent {
+    id: number
+    dataType: DataType
+    queueType: QueueType
+    docId: string
+    doc: Record<string, any>
+    updatedFields?: any
+    removedFields?: any
+  }
+
+  type SnapshotType = 'init'
+
+  interface IWatchable {
+    /**
+     * 开启实时推送
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AE%9E%E6%97%B6%E6%8E%A8%E9%80%81}
      *
      * @example
      * const ref = db
@@ -1515,21 +2236,44 @@ declare namespace cloudbase.database {
    */
   interface ICollection extends IQuery {
     /**
-     * 插入一条文档
+     * 向集合中添加一条新记录
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#add}
+     *
+     * @example
+     * const result = await db.collection('todos').add({
+     *   title: '学习 CloudBase',
+     *   completed: false
+     * })
+     * console.log('新增成功，文档 ID:', result.id)
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#add}
+     * @param data 要新增的数据对象，支持嵌套对象、数组、地理位置等数据类型
      *
-     * @param data 文档数据
+     * @return Promise<AddRes> 包含新增文档的 id 和 requestId
      */
-    add(data: Object): Promise<Pick<SetRes, 'code' | 'message'>>
+    add(data: Object): Promise<AddRes>
     /**
      * 获取一条文档的引用
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#record--document}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#record--document}
      *
      * @param id 文档ID
      */
-    doc(id: string): IDocument
+    doc(id: string | number): IDocument
+    /**
+     * 获取聚合操作对象
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#aggregate}
+     *
+     * @example
+     * const result = await db.collection('todos')
+     *   .aggregate()
+     *   .group({ _id: '$priority', count: { $sum: 1 } })
+     *   .end()
+     *
+     * @return 聚合操作对象，可链式调用各种聚合阶段方法
+     */
+    aggregate(): IAggregate
   }
   /**
    * command types
@@ -1549,7 +2293,7 @@ declare namespace cloudbase.database {
     /**
      * 表示字段等于某个值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#eq}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#eq}
      *
      * @example
      * const _ = db.command;
@@ -1564,7 +2308,7 @@ declare namespace cloudbase.database {
     /**
      * 表示字段不等于某个值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#neq}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#neq}
      *
      * @example
      * const _ = db.command;
@@ -1579,7 +2323,7 @@ declare namespace cloudbase.database {
     /**
      * 字段大于指定值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#gt}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#gt}
      *
      * @example
      * const _ = db.command;
@@ -1594,7 +2338,7 @@ declare namespace cloudbase.database {
     /**
      * 字段大于或等于指定值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#neq}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#neq}
      *
      * @example
      * const _ = db.command;
@@ -1609,7 +2353,7 @@ declare namespace cloudbase.database {
     /**
      * 字段小于指定值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#lt}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#lt}
      *
      * @example
      * const _ = db.command;
@@ -1624,7 +2368,7 @@ declare namespace cloudbase.database {
     /**
      * 字段小于或等于指定值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#lte}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#lte}
      *
      * @example
      * const _ = db.command;
@@ -1639,7 +2383,7 @@ declare namespace cloudbase.database {
     /**
      * 字段值在给定的数组中
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#in}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#in}
      *
      * @example
      * const _ = db.command;
@@ -1654,7 +2398,7 @@ declare namespace cloudbase.database {
     /**
      * 字段值不在给定的数组中
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#nin}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#nin}
      *
      * @example
      * const _ = db.command;
@@ -1669,7 +2413,7 @@ declare namespace cloudbase.database {
     /**
      * 表示需同时满足指定的两个或以上的条件
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#and}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#and}
      *
      * @example
      * const _ = db.command;
@@ -1684,7 +2428,7 @@ declare namespace cloudbase.database {
     /**
      * 表示需满足所有指定条件中的至少一个
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#or}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#or}
      *
      * @example
      * const _ = db.command;
@@ -1699,7 +2443,7 @@ declare namespace cloudbase.database {
     /**
      * 用于设定字段等于指定值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#set}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#set}
      *
      * @example
      * const _ = db.command;
@@ -1720,7 +2464,7 @@ declare namespace cloudbase.database {
     /**
      * 用于指示字段自增某个值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#inc}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#inc}
      *
      * @example
      * const _ = db.command;
@@ -1739,7 +2483,7 @@ declare namespace cloudbase.database {
     /**
      * 用于指示字段自乘某个值
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#mul}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#mul}
      *
      * @example
      * const _ = db.command;
@@ -1758,7 +2502,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示删除某个字段
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#remove}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#remove}
      *
      * @example
      * const _ = db.command;
@@ -1773,7 +2517,7 @@ declare namespace cloudbase.database {
     /**
      * 向数组尾部追加元素
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#push}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#push}
      *
      * @example
      * const _ = db.command;
@@ -1789,7 +2533,7 @@ declare namespace cloudbase.database {
     /**
      * 删除数组尾部元素
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#pop}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#pop}
      *
      * @example
      * const _ = db.command;
@@ -1804,7 +2548,7 @@ declare namespace cloudbase.database {
     /**
      * 向数组头部添加元素
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#unshift}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#unshift}
      *
      * @example
      * const _ = db.command;
@@ -1820,7 +2564,7 @@ declare namespace cloudbase.database {
     /**
      * 删除数组头部元素
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#shift}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#shift}
      *
      * @example
      * const _ = db.command;
@@ -1832,10 +2576,148 @@ declare namespace cloudbase.database {
      *
      */
     shift(): any
+    /**
+     * 条件取反
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('users').where({
+     *   status: _.not(_.eq('deleted'))
+     * })
+     *
+     * @param condition 查询条件
+     */
+    not(condition: any): any
+    /**
+     * 都不满足指定的条件
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('users').where(
+     *   _.nor([{ status: 'banned' }, { status: 'deleted' }])
+     * )
+     *
+     * @param conditions 条件数组
+     */
+    nor(conditions: any[]): any
+    /**
+     * 判断字段是否存在
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('users').where({
+     *   avatar: _.exists(true)
+     * })
+     *
+     * @param val true 表示字段存在，false 表示不存在
+     */
+    exists(val: boolean): any
+    /**
+     * 取模运算
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('users').where({
+     *   age: _.mod([2, 0])
+     * })
+     *
+     * @param val [除数, 余数]
+     */
+    mod(val: [number, number]): any
+    /**
+     * 数组包含所有指定元素
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('articles').where({
+     *   tags: _.all(['javascript', 'nodejs'])
+     * })
+     *
+     * @param list 必须包含的元素数组
+     */
+    all(list: any[]): any
+    /**
+     * 数组元素匹配
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('orders').where({
+     *   items: _.elemMatch({ price: _.gt(100) })
+     * })
+     *
+     * @param condition 匹配条件对象
+     */
+    elemMatch(condition: Object): any
+    /**
+     * 数组长度匹配
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('articles').where({
+     *   tags: _.size(3)
+     * })
+     *
+     * @param size 数组长度
+     */
+    size(size: number): any
+    /**
+     * 取最小值更新
+     *
+     * @param val 比较值
+     */
+    min(val: number): any
+    /**
+     * 取最大值更新
+     *
+     * @param val 比较值
+     */
+    max(val: number): any
+    /**
+     * 重命名字段
+     *
+     * @param newFieldName 新字段名
+     */
+    rename(newFieldName: string): any
+    /**
+     * 位运算
+     *
+     * @param options 位运算选项，如 { and: 5 }
+     */
+    bit(options: Object): any
+    /**
+     * 删除数组中匹配的元素
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('articles').doc('id').update({
+     *   tags: _.pull('要删除的标签')
+     * })
+     *
+     * @param val 要删除的元素或匹配条件
+     */
+    pull(val: any): any
+    /**
+     * 删除数组中所有匹配的元素
+     *
+     * @param list 要删除的元素数组
+     */
+    pullAll(list: any[]): any
+    /**
+     * 向数组添加不重复的元素
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection('articles').doc('id').update({
+     *   tags: _.addToSet('唯一标签')
+     * })
+     *
+     * @param val 要添加的元素
+     */
+    addToSet(val: any): any
     /**
      * 按从近到远的顺序，找出字段值在给定点的附近的文档
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#geonear}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#geonear}
      *
      * @example
      * const _ = db.command;
@@ -1856,7 +2738,7 @@ declare namespace cloudbase.database {
     /**
      * 找出字段值在指定 Polygon / MultiPolygon 内的文档，无排序
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#geowithin}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#geowithin}
      *
      * @example
      * const _ = db.command;
@@ -1875,7 +2757,7 @@ declare namespace cloudbase.database {
     /**
      * 找出字段值和给定的地理位置图形相交的文档
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#geointersects}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#geointersects}
      *
      * @example
      * const _ = db.command;
@@ -1895,9 +2777,9 @@ declare namespace cloudbase.database {
    */
   interface IDocument extends IWatchable {
     /**
-     * 更新文档，如果要更新的文档不存在时新增一个文档
+     * 设置文档数据，如果文档不存在则创建新文档
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#update-set}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#update-set}
      *
      * @example
      * collection
@@ -1905,55 +2787,65 @@ declare namespace cloudbase.database {
      *   .set({name:'cloudbase'})
      *   .then(res=>{})
      *
-     * @param data 文档数据
+     * @param data 要设置的数据对象，将完全替换原有文档内容
      *
-     * @return Promise
+     * @return Promise<SetRes> 包含 updated 或 upsertedId
      */
     set(data: Object): Promise<SetRes>
     /**
-     * 获取查询结果
+     * 获取文档数据
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#get}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#get}
      *
      * @example
      * collection
      *   .doc('docId')
      *   .get()
-     *   .then(res=>{})
+     *   .then(res=>{ console.log(res.data) })
      *
-     * @return Promise-查询结果
+     * @return Promise<GetRes> 包含 data 数组和 requestId
      */
     get(): Promise<GetRes>
     /**
-     * 更新文档，如果要更新的文档不存在什么也不会做
+     * 更新文档数据，如果文档不存在则不做任何操作
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#update--set}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#update--set}
      *
      * @example
      * collection
      *   .doc('docId')
-     *   .update({name:'cloudbase'})
-     *   .then(res=>{})
+     *   .update({completed: true})
+     *   .then(res=>{ console.log(res.updated) })
      *
-     * @param data 文档数据
+     * @param data 要更新的数据对象，支持操作符
      *
-     * @return Promise
+     * @return Promise<UpdateRes> 包含 updated 字段
      */
-    update(data: Object): Promise<SetRes>
+    update(data: Object): Promise<UpdateRes>
     /**
      * 删除一条文档
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#remove-2}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#remove-2}
      *
      * @example
      * collection
      *   .doc('docId')
      *   .remove()
-     *   .then(res=>{})
+     *   .then(res=>{ console.log(res.deleted) })
      *
-     * @return Promise
+     * @return Promise<RemoveRes> 包含 deleted 字段
+     */
+    remove(): Promise<RemoveRes>
+    /**
+     * 指定要返回的字段
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#field}
+     *
+     * @param projection 字段投影对象，true 表示返回，false 表示不返回
+     *
+     * @return 文档引用，可继续链式调用 get()
      */
-    remove(): Promise<any>
+    field(projection: Object): IDocument
   }
   /**
    * query types
@@ -1962,7 +2854,7 @@ declare namespace cloudbase.database {
     code?: string
     message?: string
     updated?: number
-    upsertedId?: number
+    upsertedId?: string
     requestId: string
   }
   interface GetRes {
@@ -1975,11 +2867,181 @@ declare namespace cloudbase.database {
   interface UpdateRes {
     requestId: string
     updated?: number
-    upsertId?: string
+    upsertedId?: string
+    code?: string
+    message?: string
+  }
+
+  interface AddRes {
+    id: string
+    requestId: string
+    code?: string
+    message?: string
+  }
+
+  interface CountRes {
+    total: number
+    requestId: string
+    code?: string
+    message?: string
+  }
+
+  interface RemoveRes {
+    deleted: number
+    requestId: string
+    code?: string
+    message?: string
+  }
+
+  interface CreateCollectionRes {
+    data: string
+    requestId: string
+    code?: string
+    message?: string
+  }
+
+  interface IRunCommandsReq {
+    /** 命令对象数组 */
+    commands: Object[]
+    /** 事务 ID（可选） */
+    transactionId?: string
+  }
+
+  interface IRunCommandsResult {
+    requestId: string
+    /** 命令执行结果数组 */
+    list: Object[][]
     code?: string
     message?: string
   }
 
+  /**
+   * 数据库配置
+   */
+  interface IDbConfig {
+    /** 实例 ID（可选），不填则使用默认实例 */
+    instance?: string
+    /** 数据库名称（可选），不填则使用默认数据库 */
+    database?: string
+  }
+
+  /**
+   * 聚合操作对象
+   */
+  interface IAggregate {
+    /**
+     * 添加新字段
+     */
+    addFields(fieldObj: Object): IAggregate
+    /**
+     * 分桶
+     */
+    bucket(bucketObj: Object): IAggregate
+    /**
+     * 自动分桶
+     */
+    bucketAuto(bucketObj: Object): IAggregate
+    /**
+     * 计数
+     */
+    count(fieldName: string): IAggregate
+    /**
+     * 地理位置附近查询
+     */
+    geoNear(options: Object): IAggregate
+    /**
+     * 分组统计
+     *
+     * @example
+     * db.collection('todos').aggregate()
+     *   .group({ _id: '$priority', count: { $sum: 1 } })
+     *   .end()
+     */
+    group(groupObj: Object): IAggregate
+    /**
+     * 限制结果数量
+     */
+    limit(limit: number): IAggregate
+    /**
+     * 联表查询
+     */
+    lookup(lookupObj: Object): IAggregate
+    /**
+     * 条件筛选
+     */
+    match(matchObj: Object): IAggregate
+    /**
+     * 字段投影
+     */
+    project(projectObj: Object): IAggregate
+    /**
+     * 替换根文档
+     */
+    replaceRoot(replaceObj: Object): IAggregate
+    /**
+     * 随机采样
+     */
+    sample(sampleObj: Object): IAggregate
+    /**
+     * 跳过数量
+     */
+    skip(skip: number): IAggregate
+    /**
+     * 排序
+     */
+    sort(sortObj: Object): IAggregate
+    /**
+     * 按数量排序
+     */
+    sortByCount(fieldName: string): IAggregate
+    /**
+     * 展开数组
+     */
+    unwind(fieldPath: string | Object): IAggregate
+    /**
+     * 结束聚合管道，返回结果
+     */
+    end(): Promise<GetRes>
+  }
+
+  /**
+   * 事务对象
+   */
+  interface ITransaction {
+    /**
+     * 获取事务内的集合引用
+     */
+    collection(name: string): ITransactionCollection
+    /**
+     * 提交事务
+     */
+    commit(): Promise<void>
+    /**
+     * 回滚事务
+     *
+     * @param reason 回滚原因
+     */
+    rollback(reason?: any): Promise<void>
+  }
+
+  /**
+   * 事务内的集合引用
+   */
+  interface ITransactionCollection {
+    doc(id: string): ITransactionDocument
+  }
+
+  /**
+   * 事务内的文档引用
+   */
+  interface ITransactionDocument {
+    get(): Promise<GetRes>
+    create(data: Object): Promise<any>
+    set(data: Object): Promise<SetRes>
+    update(data: Object): Promise<UpdateRes>
+    remove(): Promise<RemoveRes>
+  }
+
   interface QueryOrder {
     field?: string
     direction?: 'asc' | 'desc'
@@ -1997,7 +3059,7 @@ declare namespace cloudbase.database {
     /**
      * 获取数据库查询结果
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#get}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#get}
      *
      * @example
      * collection
@@ -2013,7 +3075,7 @@ declare namespace cloudbase.database {
     /**
      * 更新数据库文档
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#update-set}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#update-set}
      *
      * @example
      * collection
@@ -2031,7 +3093,7 @@ declare namespace cloudbase.database {
     /**
      * 获取数据库查询结果的数目
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#count}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#count}
      *
      * @example
      * collection
@@ -2041,13 +3103,13 @@ declare namespace cloudbase.database {
      *   .count()
      *   .then(res=>{})
      *
-     * @return Promise-查询结果
+     * @return Promise<CountRes> 包含 total 字段
      */
-    count(): Promise<any>
+    count(): Promise<CountRes>
     /**
      * 设置过滤条件
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#where}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#where}
      *
      * @example
      * collection
@@ -2062,7 +3124,7 @@ declare namespace cloudbase.database {
     /**
      * 指定查询结果集数量上限
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#limit}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#limit}
      *
      * @example
      * collection
@@ -2077,7 +3139,7 @@ declare namespace cloudbase.database {
     /**
      * 指定查询返回结果时从指定序列后的结果开始返回，常用于分页
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#skip}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#skip}
      *
      * @example
      * collection
@@ -2092,7 +3154,7 @@ declare namespace cloudbase.database {
     /**
      * 指定查询排序条件
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#orderby}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#orderby}
      *
      * @example
      * collection
@@ -2108,7 +3170,7 @@ declare namespace cloudbase.database {
     /**
      * 指定返回结果中文档需返回的字段
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#field}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#field}
      *
      * @example
      * collection
@@ -2123,7 +3185,7 @@ declare namespace cloudbase.database {
     /**
      * 删除查询到的结果
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#remove-1}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#remove-1}
      *
      * @example
      * collection
@@ -2132,9 +3194,9 @@ declare namespace cloudbase.database {
      *   })
      *   .remove()
      *
-     * @return Promise
+     * @return Promise<RemoveRes> 包含 deleted 字段
      */
-    remove(): Promise<any>
+    remove(): Promise<RemoveRes>
   }
   /**
    * geo types
@@ -2149,7 +3211,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示地理位置点
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#point}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#point}
      *
      * @example
      * const point = new db.Geo.Point(lng,lat);
@@ -2165,7 +3227,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示地理路径，是由两个或者更多的 Point 组成的线段
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#linestring}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#linestring}
      *
      * @example
      * const point = new db.Geo.LineString([pointA,pointB]);
@@ -2180,7 +3242,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示地理上的一个多边形
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#polygon}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#polygon}
      *
      * @example
      * const point = new db.Geo.Polygon([lineStringA,lineStringB]);
@@ -2195,7 +3257,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示多个点 Point 的集合
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#multipoint}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multipoint}
      *
      * @example
      * const point = new db.Geo.MultiPoint([pointA,pointB]);
@@ -2210,7 +3272,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示多个地理路径 LineString 的集合
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#multilinestring}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multilinestring}
      *
      * @example
      * const point = new db.Geo.MultiLineString([lineA,lineB]);
@@ -2225,7 +3287,7 @@ declare namespace cloudbase.database {
     /**
      * 用于表示多个地理多边形 Polygon 的集合
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#multipolygon}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multipolygon}
      *
      * @example
      * const point = new db.Geo.MultiPolygon([polygonA,polygonB]);
@@ -2255,19 +3317,19 @@ declare namespace cloudbase.database {
     /**
      * 数据库指令
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database#%E6%9F%A5%E8%AF%A2%E6%8C%87%E4%BB%A4}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#%E6%9F%A5%E8%AF%A2%E6%8C%87%E4%BB%A4}
      */
     command: ICommand
     /**
      * 数据库Geo地理位置
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#geo-shu-ju-lei-xing}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#geo-shu-ju-lei-xing}
      */
     Geo: IGeo
     /**
      * 根据正则表达式进行筛选
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#regexp}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#regexp}
      *
      * @example
      * db.collection('articles').where({
@@ -2285,7 +3347,7 @@ declare namespace cloudbase.database {
     /**
      * 创建集合的引用
      *
-     * {@link https://docs.cloudbase.net/api-reference/webv3/database.html#collection}
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#collection}
      *
      * @example
      * const coll = db.collection('demo');
@@ -2295,8 +3357,93 @@ declare namespace cloudbase.database {
      * @return 集合的引用
      */
     collection(name: string): ICollection
+    /**
+     * 创建集合
+     *
+     * **⚠️ 权限说明**：此方法通常需要管理员权限，客户端 SDK（Web/小程序）在默认安全规则下
+     * 可能无权限调用此方法。如果调用失败，请通过以下方式创建集合：
+     * 1. 登录[腾讯云开发控制台](https://console.cloud.tencent.com/tcb/database)手动创建
+     * 2. 在云函数中使用管理端 SDK 创建
+     * 3. 使用 CLI 工具创建：`tcb service:collection-create <collName>`
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#createcollection}
+     *
+     * @example
+     * ```javascript
+     * // 管理端 SDK 或具有管理员权限时可用
+     * const result = await db.createCollection('new-collection')
+     * ```
+     *
+     * @param collName 集合名称
+     *
+     * @return Promise<CreateCollectionRes>
+     */
+    createCollection(collName: string): Promise<CreateCollectionRes>
+    /**
+     * 构造服务端时间对象
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#serverdate}
+     *
+     * @example
+     * db.collection('todos').add({
+     *   createdAt: db.serverDate()
+     * })
+     *
+     * @param options 可选配置，支持 offset（毫秒偏移量）
+     *
+     * @return 服务端时间对象
+     */
+    serverDate(options?: { offset?: number }): any
+    /**
+     * 开启一个新事务
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#starttransaction}
+     *
+     * @example
+     * const transaction = await db.startTransaction()
+     * // ... 事务操作
+     * await transaction.commit()
+     *
+     * @return Promise<ITransaction> 事务对象
+     */
+    startTransaction(): Promise<ITransaction>
+    /**
+     * 执行事务操作，自动处理提交和回滚
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#runtransaction}
+     *
+     * @example
+     * const result = await db.runTransaction(async (transaction) => {
+     *   const doc = await transaction.collection('accounts').doc('id').get()
+     *   await transaction.collection('accounts').doc('id').update({ balance: doc.data.balance - 100 })
+     *   return { success: true }
+     * })
+     *
+     * @param callback 事务回调函数
+     * @param times 事务冲突时的重试次数，默认为 3
+     *
+     * @return Promise<any> 事务回调函数的返回值
+     */
+    runTransaction(callback: (transaction: ITransaction) => Promise<any>, times?: number): Promise<any>
+    /**
+     * 执行 MongoDB 原生命令
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#runcommands}
+     *
+     * @example
+     * const result = await db.runCommands({
+     *   commands: [
+     *     { find: 'users', filter: { age: { $gte: 18 } }, limit: 10 }
+     *   ]
+     * })
+     *
+     * @param params 命令参数，包含 commands 数组和可选的 transactionId
+     *
+     * @return Promise<IRunCommandsResult>
+     */
+    runCommands(params: IRunCommandsReq): Promise<IRunCommandsResult>
   }
 }
 
-export default cloudbase
+export = cloudbase
 export as namespace cloudbase