@cloudbase/js-sdk 3.6.2 → 3.6.3

package/core.d.ts

@@ -0,0 +1,4331 @@
+/**
+ * 共享类型定义（Web + Node.js 通用），以 ambient 形式声明。
+ *
+ * 说明：本文件不能出现顶层 `import` / `export` 语句，否则会变成模块而无法作为
+ * 全局 ambient 命名空间被 `index.d.ts` / `index.node.d.ts` 通过三斜线引用聚合。
+ * 因此所有外部依赖类型均以内联 `import('...')` 类型别名的形式声明在命名空间内部，
+ * 既避免污染全局作用域，又不会让本文件变成模块。
+ */
+declare namespace cloudbase {
+  type KV<T> = {
+    [key: string]: T
+  }
+
+  type ExcludeOf<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>
+
+  type MethodType = 'request' | 'post' | 'get' | 'head' | 'patch' | 'delete' | 'put'
+
+  interface ICallApiOptions {
+    /** 请求的path */
+    path?: string
+    /** 请求方法 */
+    method?: MethodType
+    /** 请求头 */
+    headers?: KV<any>
+    /** 请求体，根据content-type可以是不同类型 */
+    body?: KV<any> | string
+    /** 可传token，如果没有传值，则默认用当前登录的token */
+    token?: string
+  }
+
+  interface ICloudbaseApis {
+    [apiName: string]: {
+      [method in MethodType]: (callApiOptions: ICallApiOptions, opts?: KV<any>) => Promise<ResponseObject['data']>
+    }
+  }
+
+  // ===== 外部依赖类型别名（内联 import 类型，避免顶层 import 使本文件成为模块）=====
+  type OrmClient = import('@cloudbase/model').OrmClient
+  type OrmRawQueryClient = import('@cloudbase/model').OrmRawQueryClient
+  type IMySqlClient = import('@cloudbase/mysql').IMySqlClient
+  type AI = import('@cloudbase/ai').AI
+  type CloudbaseAdapter = import('@cloudbase/adapter-interface').CloudbaseAdapter
+  type ResponseObject = import('@cloudbase/adapter-interface').ResponseObject
+  type ICloudbaseUpgradedConfig = import('@cloudbase/types').ICloudbaseUpgradedConfig
+  type ICloudbase = import('@cloudbase/types').ICloudbase
+  type Persistence = import('@cloudbase/types').Persistence
+  type LANGS = import('@cloudbase/types').LANGS
+  type ICustomReqOpts = import('@cloudbase/types/functions').ICustomReqOpts
+
+  // ===== @cloudbase/auth 相关类型别名 =====
+  type SignInRes = import('@cloudbase/auth').SignInRes
+  type GetUserRes = import('@cloudbase/auth').GetUserRes
+  type CommonRes = import('@cloudbase/auth').CommonRes
+  type SignInWithOtpRes = import('@cloudbase/auth').SignInWithOtpRes
+  type SignInOAuthRes = import('@cloudbase/auth').SignInOAuthRes
+  type GetClaimsRes = import('@cloudbase/auth').GetClaimsRes
+  type ResetPasswordForEmailRes = import('@cloudbase/auth').ResetPasswordForEmailRes
+  type GetUserIdentitiesRes = import('@cloudbase/auth').GetUserIdentitiesRes
+  type LinkIdentityRes = import('@cloudbase/auth').LinkIdentityRes
+  type ReauthenticateRes = import('@cloudbase/auth').ReauthenticateRes
+  type ResendRes = import('@cloudbase/auth').ResendRes
+  type UpdateUserWithVerificationRes = import('@cloudbase/auth').UpdateUserWithVerificationRes
+  type OnAuthStateChangeCallback = import('@cloudbase/auth').OnAuthStateChangeCallback
+  type SignInWithPasswordReq = import('@cloudbase/auth').SignInWithPasswordReq
+  type SignInWithIdTokenReq = import('@cloudbase/auth').SignInWithIdTokenReq
+  type SignInWithOAuthReq = import('@cloudbase/auth').SignInWithOAuthReq
+  type VerifyOAuthReq = import('@cloudbase/auth').VerifyOAuthReq
+  type VerifyOtpReq = import('@cloudbase/auth').VerifyOtpReq
+  type LinkIdentityReq = import('@cloudbase/auth').LinkIdentityReq
+  type UnlinkIdentityReq = import('@cloudbase/auth').UnlinkIdentityReq
+  type UpdateUserReq = import('@cloudbase/auth').UpdateUserReq
+  type SignInWithOtpReq = import('@cloudbase/auth').SignInWithOtpReq
+  type ResetPasswordForOldReq = import('@cloudbase/auth').ResetPasswordForOldReq
+  type ResendReq = import('@cloudbase/auth').ResendReq
+  type SetSessionReq = import('@cloudbase/auth').SetSessionReq
+  type DeleteMeReq = import('@cloudbase/auth').DeleteMeReq
+  type SignUpRes = import('@cloudbase/auth').SignUpRes
+
+  // ===== @cloudbase/oauth authModels 命名空间别名 =====
+  namespace authModels {
+    type BindPhoneRequest = import('@cloudbase/oauth').authModels.BindPhoneRequest
+    type BindEmailRequest = import('@cloudbase/oauth').authModels.BindEmailRequest
+    type UnbindProviderRequest = import('@cloudbase/oauth').authModels.UnbindProviderRequest
+    type VerifyRequest = import('@cloudbase/oauth').authModels.VerifyRequest
+    type VerifyResponse = import('@cloudbase/oauth').authModels.VerifyResponse
+    type GetVerificationRequest = import('@cloudbase/oauth').authModels.GetVerificationRequest
+    type GetVerificationResponse = import('@cloudbase/oauth').authModels.GetVerificationResponse
+    type GetCustomSignTicketFn = import('@cloudbase/oauth').authModels.GetCustomSignTicketFn
+    type SetPasswordRequest = import('@cloudbase/oauth').authModels.SetPasswordRequest
+    type ModifyUserBasicInfoRequest = import('@cloudbase/oauth').authModels.ModifyUserBasicInfoRequest
+    type BindWithProviderRequest = import('@cloudbase/oauth').authModels.BindWithProviderRequest
+    type QueryUserProfileRequest = import('@cloudbase/oauth').authModels.QueryUserProfileRequest
+    type QueryUserProfileResponse = import('@cloudbase/oauth').authModels.QueryUserProfileResponse
+    type GrantProviderTokenRequest = import('@cloudbase/oauth').authModels.GrantProviderTokenRequest
+    type GrantProviderTokenResponse = import('@cloudbase/oauth').authModels.GrantProviderTokenResponse
+    type PatchProviderTokenRequest = import('@cloudbase/oauth').authModels.PatchProviderTokenRequest
+    type PatchProviderTokenResponse = import('@cloudbase/oauth').authModels.PatchProviderTokenResponse
+    type SignInWithProviderRequest = import('@cloudbase/oauth').authModels.SignInWithProviderRequest
+    type GrantTokenRequest = import('@cloudbase/oauth').authModels.GrantTokenRequest
+    type GenProviderRedirectUriRequest = import('@cloudbase/oauth').authModels.GenProviderRedirectUriRequest
+    type GenProviderRedirectUriResponse = import('@cloudbase/oauth').authModels.GenProviderRedirectUriResponse
+    type ResetPasswordRequest = import('@cloudbase/oauth').authModels.ResetPasswordRequest
+    type DeviceAuthorizeRequest = import('@cloudbase/oauth').authModels.DeviceAuthorizeRequest
+    type DeviceAuthorizeResponse = import('@cloudbase/oauth').authModels.DeviceAuthorizeResponse
+    type SudoRequest = import('@cloudbase/oauth').authModels.SudoRequest
+    type SudoResponse = import('@cloudbase/oauth').authModels.SudoResponse
+    type WithSudoRequest = import('@cloudbase/oauth').authModels.WithSudoRequest
+    type UserProfile = import('@cloudbase/oauth').authModels.UserProfile
+    type UserProfileProvider = import('@cloudbase/oauth').authModels.UserProfileProvider
+    type Credentials = import('@cloudbase/oauth').authModels.Credentials
+    type ProviderSubType = import('@cloudbase/oauth').authModels.ProviderSubType
+    type ModifyPasswordWithoutLoginRequest = import('@cloudbase/oauth').authModels.ModifyPasswordWithoutLoginRequest
+    type GetUserBehaviorLog = import('@cloudbase/oauth').authModels.GetUserBehaviorLog
+    type GetUserBehaviorLogRes = import('@cloudbase/oauth').authModels.GetUserBehaviorLogRes
+    type GetMiniProgramQrCodeRequest = import('@cloudbase/oauth').authModels.GetMiniProgramQrCodeRequest
+    type GetMiniProgramQrCodeResponse = import('@cloudbase/oauth').authModels.GetMiniProgramQrCodeResponse
+    type GetMiniProgramQrCodeStatusRequest = import('@cloudbase/oauth').authModels.GetMiniProgramQrCodeStatusRequest
+    type GetMiniProgramQrCodeStatusResponse = import('@cloudbase/oauth').authModels.GetMiniProgramQrCodeStatusResponse
+    type ToDefaultLoginPage = import('@cloudbase/oauth').authModels.ToDefaultLoginPage
+    type SignoutRequest = import('@cloudbase/oauth').authModels.SignoutRequest
+    type SignoutResponse = import('@cloudbase/oauth').authModels.SignoutResponse
+    type SignInRequest = import('@cloudbase/oauth').authModels.SignInRequest
+    type SignUpRequest = import('@cloudbase/oauth').authModels.SignUpRequest
+  }
+  interface SimpleStorage {
+    getItem: (key: string) => Promise<string | null>
+    removeItem: (key: string) => Promise<void>
+    setItem: (key: string, value: string) => Promise<void>
+    getItemSync: (key: string) => string | null
+    removeItemSync: (key: string) => void
+    setItemSync: (key: string, value: string) => void
+  }
+
+  interface ICloudbaseConfig {
+    /** 是否国际站标记 */
+    intl?: boolean
+    /** 环境 ID，在腾讯云开发控制台 → 环境 → 环境总览中获取 */
+    env?: string
+    /**
+     * 地域信息
+     * @example 'ap-shanghai'
+     */
+    region?: string
+    /** 网络请求超时上限，单位 ms，默认 15000 */
+    timeout?: number
+    /** 本地登录态保留期限 */
+    persistence?: Persistence
+    oauthClient?: any
+    /** 是否开启调试模式 */
+    debug?: boolean
+    _fromApp?: ICloudbase
+    clientId?: string
+    oauthInstance?: any
+    wxCloud?: any
+    i18n?: {
+      t: (text: string) => string
+      LANG_HEADER_KEY: string
+      lang: LANGS
+    }
+    accessKey?: string
+    endPointMode?: EndPointKey
+    lang?: LANGS
+    /**
+     * 认证相关配置
+     * @example
+     * ```typescript
+     * cloudbase.init({
+     *   env: 'your-env-id',
+     *   auth: {
+     *     detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
+     *   }
+     * })
+     * ```
+     */
+    auth?: ICloudbaseAuthConfig
+  }
+
+  /**
+   * 认证相关配置（Web 通用部分）。
+   * Node.js 专属字段（secretId / secretKey / sessionToken / secretType）
+   * 通过 core.node.d.ts 的声明合并追加，仅在 Node.js 入口可见。
+   */
+  interface ICloudbaseAuthConfig {
+    /** 是否自动检测 URL 中的 OAuth 回调参数，默认 false */
+    detectSessionInUrl?: boolean
+  }
+
+  interface ICloudbaseExtension {
+    name: string
+    invoke(opts: any, app: ICloudbase): Promise<any>
+  }
+
+  interface Listeners {
+    [key: string]: Function[]
+  }
+
+  interface ICloudbaseEvent {
+    name: string
+    target: any
+    data: any
+  }
+
+  interface ICloudbaseEventEmitter {
+    on(name: string, listener: Function): this
+    off(name: string, listener: Function): this
+    fire(event: string | ICloudbaseEvent, data?: any): this
+  }
+
+  interface ICloudbaseComponent {
+    name: string
+    entity: any
+    namespace?: string
+    injectEvents?: {
+      bus: ICloudbaseEventEmitter
+      events: string[]
+    }
+    IIFE?: boolean
+  }
+
+  interface ICloudbaseHook {
+    entity: any
+    target: string
+  }
+
+  type EndPointKey = 'CLOUD_API' | 'GATEWAY'
+
+  interface ISetEndPointWithKey {
+    key: EndPointKey
+    url?: string
+    protocol?: 'http' | 'https'
+  }
+
+  /**
+   * 初始化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.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
+  /**
+   * 使用适配器，使用方式参考 {@link https://docs.cloudbase.net/api-reference/webv3/adapter#%E7%AC%AC-1-%E6%AD%A5%E5%AE%89%E8%A3%85%E5%B9%B6%E5%BC%95%E5%85%A5%E9%80%82%E9%85%8D%E5%99%A8}
+   *
+   * @example
+   * ```javascript
+   * cloudbase.useAdapters(adapter); // 使用单个适配器
+   * cloudbase.useAdapters([         // 使用多个适配器
+   *   adapterA,
+   *   adapterB
+   * ]);
+   * ```
+   *
+   * @param adapters 适配器对象，入参可以为单个适配器对象，也可以是多个适配器对象的数组
+   * @param options 适配器参数，可以在genAdapter中获取到该参数
+   */
+  function useAdapters(adapters: CloudbaseAdapter | CloudbaseAdapter[], options?: any): void
+  /**
+   * 注册扩展能力插件，使用方式参考 {@link https://docs.cloudbase.net/extension/abilities/image-examination.html#shi-yong-kuo-zhan}
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerExtension(ext);
+   * ```
+   *
+   * @param ext 扩展能力插件对象
+   */
+  function registerExtension(ext: ICloudbaseExtension): void
+  /**
+   * 【谨慎操作】注册SDK的版本
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerVersion('1.2.1');
+   * ```
+   *
+   * @param version SDK版本
+   */
+  function registerVersion(version: string): void
+  /**
+   * 【谨慎操作】注册SDK的名称
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerSdkName('cloudbase-js-sdk');
+   * ```
+   *
+   * @param name SDK名称
+   */
+  function registerSdkName(name: string): void
+  /**
+   * 【谨慎操作】修改SDK请求的云开发服务地址
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerEndPoint('url','https');
+   * ```
+   *
+   * @param url 服务地址
+   * @param protocol 【可选】强制使用某种协议，默认与主站协议一致
+   */
+  function registerEndPoint(url: string, protocol?: 'http' | 'https'): void
+  /**
+   * 【谨慎操作】修改SDK请求的「云开发/网关」服务地址
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerEndPointWithKey({
+   *   key: "GATEWAY",
+   *   url: "",
+   *   protocol: ""
+   * });
+   * ```
+   *
+   */
+  function registerEndPointWithKey(props: ISetEndPointWithKey): void
+  /**
+   * 一次性设置所有端点，只需传入 host 地址，自动拼接路径
+   * @param host - 主机地址，如 "43.144.98.4" 或 "//43.144.98.4"
+   * @param protocol - 协议，默认 "http"
+   */
+  function registerHost(host: string, protocol?: 'http' | 'https'): void
+  /**
+   * 【谨慎操作】注册功能模块
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerComponent({});
+   * ```
+   *
+   * @param component 功能模块对象
+   */
+  function registerComponent(component: ICloudbaseComponent): void
+  /**
+   * 【谨慎操作】注册hook
+   *
+   * @example
+   * ```javascript
+   * cloudbase.registerHook({});
+   * ```
+   *
+   * @param hook hook对象
+   */
+  function registerHook(hook: ICloudbaseHook): void
+
+  export interface models extends OrmClient, OrmRawQueryClient {}
+}
+/**
+ * instance
+ */
+declare namespace cloudbase.app {
+  interface App {
+    /**
+     * 创建Auth对象
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/authentication#appauth}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * const auth = app.auth({
+     *   persistence: 'local'
+     * });
+     * ```
+     *
+     * @param options Auth初始化配置
+     * @param options.persistence 本地登录态保留期限
+     *
+     * @return {!cloudbase.auth.App} Auth实例
+     */
+    auth: ((options?: { persistence: cloudbase.auth.Persistence }) => cloudbase.auth.App) & cloudbase.auth.App
+    /**
+     * 调用云函数
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/functions#callfunction}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.callFunction({
+     *   name: 'function-name'
+     *   data: {
+     *     a: 1,
+     *     b: 2
+     *   }
+     * }).then(res=>{
+     *   console.log(res.result);
+     * }});
+     * ```
+     *
+     * @param options 被调用的云函数信息
+     * @param options.name 云函数的名称
+     * @param options.data 【可选】云函数的参数，默认为空
+     * @param options.parse 【可选】设置为 `true` 时，当函数返回值为对象时，API 请求会返回解析对象，而不是 JSON 字符串，默认为`false`
+     *
+     * @return Promise-函数执行结果
+     */
+    callFunction(
+      options: cloudbase.functions.ICallFunctionOptions,
+      callback?: Function,
+      customReqOpts?: ICustomReqOpts,
+    ): Promise<cloudbase.functions.ICallFunctionResponse>
+    /**
+     * 调用云托管
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/cloudrun}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app
+     * .callContainer({
+     * name: 'helloworld',
+     * method: 'POST',
+     * path: '/abc',
+     * header:{
+     *   'Content-Type': 'application/json; charset=utf-8'
+     * },
+     * data: {
+     *   key1: 'test value 1',
+     *   key2: 'test value 2'
+     * },
+     * })
+     * .then((res) => {
+     * console.log(res)
+     * });
+     * ```
+     *
+     * @param options 被调用的云托管信息
+     * @param options.name 云托管的名称
+     * @param options.data 【可选】云托管的参数，默认为空
+     *
+     * @return Promise-云托管执行结果
+     */
+    callContainer(
+      options: cloudbase.functions.ICallFunctionOptions,
+      customReqOpts?: ICustomReqOpts,
+    ): Promise<ResponseObject>
+    /**
+     * 云存储-上传文件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/storage#uploadfile}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.uploadFile({
+     *   cloudPath: 'cloudPath',
+     *   filePath: 'filePath',
+     *   method: 'put',
+     *   headers: {
+     *      'Content-MD5': 'xxxxxx'
+     *   }
+     *   onUploadProgress: function(event){}
+     * });
+     * ```
+     *
+     * @param params
+     * @param params.cloudPath 文件上传到云端后的绝对路径，包含文件名
+     * @param params.filePath 被上传的文件对象
+     * @param params.method 上传方法，默认为 put
+     * @param params.headers 自定义头部字段
+     * @param params.onUploadProgress 【可选】上传进度回调函数
+     *
+     * @return Promise-上传结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().upload()`。
+     */
+    uploadFile(
+      params: cloudbase.storage.ICloudbaseUploadFileParams,
+      callback?: Function,
+    ): Promise<cloudbase.storage.ICloudbaseUploadFileResult>
+    /**
+     * 云存储-下载文件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/storage#downloadfile}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.downloadFile({
+     *   fileID: 'cloudPath'
+     * });
+     * ```
+     *
+     * @param params
+     * @param params.fileID 要下载的文件的 `id`，在控制台云存储中查看
+     *
+     * @return Promise-下载结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().download()`。
+     */
+    downloadFile(
+      params: cloudbase.storage.ICloudbaseDownloadFileParams,
+      callback?: Function,
+    ): Promise<cloudbase.storage.ICloudbaseDownloadFileResult>
+    /**
+     * 云存储-批量复制文件
+     *
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.copyFile({
+     *   fileList: [
+     *     {
+     *       srcPath: '源文件的绝对路径，包含文件名。例如 foo/bar.jpg、foo/bar/baz.jpg 等，不能包含除[0-9 , a-z , A-Z]、/、!、-、_、.、、*和中文以外的字符，使用 / 字符来实现类似传统文件系统的层级结构',
+     *       dstPath: '目标文件的绝对路径，包含文件名。例如 foo/bar.jpg、foo/bar/baz.jpg 等，不能包含除[0-9 , a-z , A-Z]、/、!、-、_、.、、*和中文以外的字符，使用 / 字符来实现类似传统文件系统的层级结构',
+     *       overwrite: '当目标文件已经存在时，是否允许覆盖已有文件，默认 true',
+     *       removeOriginal: '复制文件后是否删除源文件，默认 false'
+     *     }
+     *   ]
+     * });
+     * ```
+     *
+     * @param params
+     * @param params.fileList 要复制的文件信息组成的数组
+     *
+     * @return Promise-复制结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().copy()`。
+     */
+    copyFile(
+      params: cloudbase.storage.ICloudbaseCopyFileParams,
+      callback?: Function,
+    ): Promise<cloudbase.storage.ICloudbaseCopyFileResult>
+    /**
+     * 云存储-获取文件的下载链接
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/storage#gettempfileurl}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.getTempFileURL({
+     *   fileList: [
+     *     '文件A的fileID',
+     *     {
+     *       fileID: '文件B的fileID',
+     *       maxAge: 600 // 文件B的链接有效期，单位`ms`
+     *     }
+     *   ]
+     * });
+     * ```
+     *
+     * @param params
+     * @param params.fileList 要下载的文件数组，数组元素可以是`string`或`Object`，如果是`string`代表文件ID，如果是`Object`可配置以下信息
+     * @param params.fileList[].fileID 要下载的文件ID
+     * @param params.fileList[].maxAge 下载链接的有效期，单位`ms`
+     *
+     * @return Promise-文件下载链接
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().createSignedUrl()`。
+     */
+    getTempFileURL(
+      params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
+      callback?: Function,
+    ): Promise<cloudbase.storage.ICloudbaseGetTempFileURLResult>
+    /**
+     * 云存储-删除文件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/storage#deletefile}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * app.deleteFile({
+     *   fileList: [
+     *     '文件A的fileID',
+     *     '文件B的fileID'
+     *   ]
+     * });
+     * ```
+     *
+     * @param params
+     * @param params.fileList 要删除的文件ID数组
+     *
+     * @return Promise-删除结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().remove()`。
+     */
+    deleteFile(
+      params: cloudbase.storage.ICloudbaseDeleteFileParams,
+      callback?: Function,
+    ): Promise<cloudbase.storage.ICloudbaseDeleteFileResult>
+
+    /**
+     * 云存储-获取文件信息
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().info()`。
+     */
+    getFileInfo(
+      params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
+    ): Promise<cloudbase.storage.ICloudbaseGetFileInfoResult>
+    /**
+     * 云存储-获取上传元信息
+     *
+     *
+     * @param params
+     * @param callback
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().createSignedUploadUrl()`。
+     */
+    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.StorageClient
+    /**
+     * 获取数据库实例
+     *
+     * {@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
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * const db = app.database();
+     * ```
+     *
+     * @return 数据库实例
+     */
+    database(dbConfig?: { instance?: string; database?: string }): cloudbase.database.App
+    /**
+     * 调用扩展能力插件功能
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: 'your-envid'
+     * });
+     * // 调用前需要先注册
+     * app.registerExtension(ext);
+     *
+     * app.invokeExtension('扩展能力插件名称'，{
+     *   // ...扩展能力插件的入参
+     * });
+     * ```
+     *
+     * @param name 扩展能力插件的名称
+     * @param opts 【可选】扩展能力插件的参数，根据插件具体需求而定
+     *
+     * @return Promise-扩展能力插件执行结果
+     */
+    invokeExtension(name: string, opts: any): Promise<any>
+
+    eventBus: any
+
+    /**
+     * 调用 数据模型 SDK
+     * 
+     *  {@link https://docs.cloudbase.net/model/sdk-reference/model}
+     * @example 
+     * ```javascript
+        models.<model_name>.create() // 创建单条数据
+        models.<model_name>.createMany()  // 创建多条数据
+        models.<model_name>.update() // 更新单条数据
+        models.<model_name>.updateMany() // 更新多条数据
+        models.<model_name>.delete() // 删除单条数据
+        models.<model_name>.deleteMany() // 删除多条数据
+        models.<model_name>.get() // 查询单条数据
+        models.<model_name>.list() // 查询多条数据
+        models.$runSQL() // 执行原生 SQL 语句
+      * ```
+      */
+    models: OrmClient & OrmRawQueryClient
+
+    /**
+     * MySQL 数据库
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     *
+     * app.mysql().from('todos').select().then((res) => {
+     *   console.log(res.data);
+     * });
+     * ```
+     */
+    mysql: IMySqlClient
+    rdb: IMySqlClient
+
+    ai(options?: { baseUrl?: string }): AI
+
+    apis: ICloudbaseApis
+
+    /**
+     * 一次性设置所有端点，只需传入 host 地址，自动拼接路径
+     * @param host - 主机地址，如 "43.144.98.4" 或 "//43.144.98.4"
+     * @param protocol - 协议，默认 "http"
+     */
+    registerHost(host: string, protocol?: 'http' | 'https'): void
+
+    /**
+     * 获取指定类型的端点信息
+     * @param key - 端点类型
+     */
+    getEndPointWithKey(key: cloudbase.EndPointKey): { BASE_URL: string; PROTOCOL: string }
+
+    /**
+     * 修改SDK请求的云开发服务地址
+     * @param url 服务地址
+     * @param protocol 【可选】强制使用某种协议，默认与主站协议一致
+     */
+    registerEndPoint(url: string, protocol?: 'http' | 'https'): void
+
+    /**
+     * 修改SDK请求的「云开发/网关」服务地址，通过 key 指定
+     */
+    registerEndPointWithKey(props: cloudbase.ISetEndPointWithKey): void
+
+    /**
+     * 解析验证码 URL 参数
+     */
+    parseCaptcha(url: string): any
+  }
+}
+/**
+ * auth
+ */
+declare namespace cloudbase.auth {
+  type Persistence = 'local' | 'session' | 'none'
+
+  interface IAccessTokenInfo {
+    accessToken: string
+    env: string
+  }
+
+  interface ILoginState {
+    /**
+     * 当前登录用户的信息
+     */
+    user: IUser
+  }
+
+  interface ICredential {
+    accessToken?: string
+    accessTokenExpire?: string
+  }
+
+  interface IAuthProvider {
+    signInWithRedirect: () => any
+  }
+
+  /**
+   * 用户信息
+   */
+  interface IUserInfo {
+    uid?: string
+    loginType?: string
+    openid?: string
+    wxOpenId?: string
+    wxPublicId?: string
+    unionId?: string
+    qqMiniOpenId?: string
+    customUserId?: string
+    name?: string
+    displayName?: string
+    gender?: string
+    email?: string
+    username?: string
+    hasPassword?: boolean
+    location?: {
+      country?: string
+      province?: string
+      city?: string
+    }
+    country?: string
+    province?: string
+    city?: string
+  }
+
+  interface IUser extends IUserInfo {
+    /**
+     * 更新用户信息
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/authentication#userupdate}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * const auth = app.auth();
+     * const user = auth.currentUser;
+     * user.update({
+     *   nickName: '新昵称'
+     * }).then(()=>{});
+     * ```
+     *
+     * @param userinfo 用户信息
+     *
+     * @return Promise
+     *
+     */
+    update(userinfo: IUserInfo): Promise<void>
+    /**
+     * 刷新本地用户信息
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/authentication#userrefresh}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * const auth = app.auth();
+     * const user = auth.currentUser;
+     * user.refresh().then(()=>{});
+     * ```
+     *
+     * @return Promise-刷新后的用户信息
+     *
+     */
+    refresh(): Promise<IUserInfo>
+    /**
+     * 同步获取本地用户信息
+     */
+    checkLocalInfo: () => void
+    /**
+     * 异步获取本地用户信息
+     */
+    checkLocalInfoAsync: () => Promise<void>
+    linkWithTicket?: (ticket: string) => Promise<void>
+    linkWithRedirect?: (provider: IAuthProvider) => void
+    getLinkedUidList?: () => Promise<{ hasPrimaryUid: boolean; users: IUserInfo[] }>
+    setPrimaryUid?: (uid: string) => Promise<void>
+    unlink?: (loginType: 'CUSTOM' | 'WECHAT-OPEN' | 'WECHAT-PUBLIC' | 'WECHAT-UNION') => Promise<void>
+  }
+
+  interface App {
+    /**
+     * 获取当前登录的用户信息-同步操作
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authhasloginstate}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * const userInfo = app.auth().currentUser;
+     * ```
+     *
+     * @return 用户信息，如果未登录返回`null`
+     */
+    currentUser: IUser | null
+    /**
+     * 获取当前登录的用户信息-异步操作，文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetcurrentuser}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * app.auth().getCurrentUser().then(userInfo=>{
+     *   // ...
+     * });
+     * ```
+     *
+     * @return Promise-用户信息，如果未登录返回`null`
+     */
+    getCurrentUser(): Promise<IUser | null>
+    /**
+     * 绑定手机号码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authbindphonenumber}
+     *
+     * @param params
+     */
+    bindPhoneNumber(params: authModels.BindPhoneRequest): Promise<void>
+    /**
+     * 绑定邮箱
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authbindemail}
+     *
+     * @param params
+     */
+    bindEmail(params: authModels.BindEmailRequest): Promise<void>
+    /**
+     * 解除三方绑定
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authunbindprovider}
+     *
+     * @param params
+     */
+    unbindProvider(params: authModels.UnbindProviderRequest): Promise<void>
+
+    /**
+     * 验证码验证
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authverify}
+     *
+     * @param params
+     */
+    verify(params: authModels.VerifyRequest): Promise<authModels.VerifyResponse>
+    /**
+     * 获取验证码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetverification}
+     *
+     * @param params
+     * @param options
+     */
+    getVerification(
+      params: authModels.GetVerificationRequest,
+      options?: { withCaptcha: boolean },
+    ): Promise<authModels.GetVerificationResponse>
+    /**
+     * 匿名登录。无需用户注册即可使用应用功能，适合游客模式、临时体验等场景。
+     *
+     * **前置条件**：需要在云开发控制台（环境 → 登录授权 → 身份源列表）开启「匿名登录」。
+     *
+     * **重要**：匿名登录必须在使用 `watch()` 等实时数据库功能**之前**完成，
+     * 否则 WebSocket 连接会因缺少认证信息而失败。
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsigninanonymously}
+     *
+     * @example
+     * ```typescript
+     * import Cloudbase from '@cloudbase/js-sdk';
+     *
+     * const app = Cloudbase.init({
+     *   env: 'your-env-id',
+     *   region: 'ap-shanghai'
+     * });
+     * const auth = app.auth();
+     *
+     * // 匿名登录
+     * const { data, error } = await auth.signInAnonymously();
+     * if (error) {
+     *   console.error('匿名登录失败:', error.message);
+     *   return;
+     * }
+     * console.log('匿名登录成功, 用户ID:', data.user.id);
+     * console.log('是否匿名用户:', data.user.is_anonymous); // true
+     *
+     * // 登录成功后，即可使用 watch() 等实时功能
+     * const db = app.database();
+     * const listener = db.collection('rooms').where({ status: 'active' }).watch({
+     *   onChange: (snapshot) => {
+     *     console.log('数据变化:', snapshot.docs);
+     *   },
+     *   onError: (err) => {
+     *     console.error('监听错误:', err);
+     *   }
+     * });
+     *
+     * // 不再需要时关闭监听
+     * listener.close();
+     * ```
+     *
+     * @param data 可选参数
+     * @param data.provider_token 提供令牌（通常不需要手动传入）
+     * @returns 登录结果，包含 `data.user`（用户信息）和 `data.session`（会话信息），
+     *          或 `error`（登录失败时的错误信息）
+     */
+    signInAnonymously(data?: { provider_token?: string }): Promise<SignInRes>
+    /**
+     * 小程序匿名登录
+     *
+     * @param params
+     */
+    signInAnonymouslyInWx(params?: { useWxCloud?: boolean }): Promise<ILoginState>
+    /**
+     * 小程序绑定OpenID
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authbindopenid}
+     *
+     */
+    bindOpenId(): Promise<void>
+    /**
+     * 小程序unionId静默登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsigninwithunionid}
+     *
+     */
+    signInWithUnionId(): Promise<ILoginState>
+    /**
+     * 短信验证码登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsigninwithsms}
+     *
+     * @param params
+     */
+    signInWithSms(params: {
+      verificationInfo?: { verification_id: string; is_user: boolean }
+      verificationCode?: string
+      phoneNum?: string
+      bindInfo?: any
+    }): Promise<ILoginState>
+    /**
+     * 邮箱验证码登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsigninwithemail}
+     *
+     * @param params
+     */
+    signInWithEmail(params: {
+      verificationInfo?: { verification_id: string; is_user: boolean }
+      verificationCode?: string
+      email?: string
+      bindInfo?: any
+    }): Promise<ILoginState>
+    /**
+     * 设置获取自定义登录 ticket 的函数
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsetcustomsignfunc}
+     *
+     *
+     * @param getTickFn
+     */
+    setCustomSignFunc(getTickFn: authModels.GetCustomSignTicketFn): void
+    /**
+     * 设置密码（已登录状态下，更新用户密码）
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsetpassword}
+     *
+     */
+    setPassword(params: authModels.SetPasswordRequest): Promise<void>
+    /**
+     * 获取用户信息
+     * @deprecated 请使用 getCurrentUser 代替
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetuserinfo}
+     */
+    getUserInfo(): Promise<IUserInfo>
+    /**
+     * 获取微搭插件用户信息
+     *
+     */
+    getWedaUserInfo(): Promise<any>
+    /**
+     * 更新用户基本信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authupdateuserbasicinfo}
+     *
+     * @param params
+     */
+    updateUserBasicInfo(params: authModels.ModifyUserBasicInfoRequest): Promise<void>
+    /**
+     * 获取本地登录态-同步操作
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authhasloginstate}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * const loginState = app.auth().hasLoginState();
+     * ```
+     *
+     * @return 登录态信息，如果未登录返回`null`
+     */
+    hasLoginState(): ILoginState | null
+    /**
+     * 获取本地登录态-异步操作
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv2/authentication.html#auth-getloginstate}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * app.auth().getLoginState().then(loginState=>{
+     *   // ...
+     * });
+     * ```
+     *
+     * @return Promise-登录态信息，如果未登录返回`null`
+     */
+    getLoginState(): Promise<ILoginState | null>
+    /**
+     * @deprecated
+     */
+    getAuthHeader(): {}
+    /**
+     * 为已有账户绑定第三方账户
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authbindwithprovider}
+     */
+    bindWithProvider(params: authModels.BindWithProviderRequest): Promise<void>
+    /**
+     * 查询用户（自定义登录场景和匿名登录场景，不支持使用该接口查询用户信息）
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authqueryuser}
+     *
+     */
+    queryUser(queryObj: authModels.QueryUserProfileRequest): Promise<authModels.QueryUserProfileResponse>
+    /**
+     * 获取当前登录用户的访问凭证
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetaccesstoken}
+     */
+    getAccessToken(): Promise<{ accessToken: string; env: string }>
+    /**
+     * 提供第三方平台登录 token
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgrantprovidertoken}
+     */
+    grantProviderToken(params: authModels.GrantProviderTokenRequest): Promise<authModels.GrantProviderTokenResponse>
+    patchProviderToken(params: authModels.PatchProviderTokenRequest): Promise<authModels.PatchProviderTokenResponse>
+    /**
+     * 第三方平台登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsigninwithprovider}
+     */
+    signInWithProvider(params: authModels.SignInWithProviderRequest): Promise<ILoginState>
+    /**
+     * 微信登录
+     */
+    signInWithWechat(params?: any): Promise<ILoginState>
+    grantToken(params: authModels.GrantTokenRequest): Promise<ILoginState>
+    /**
+     * 生成第三方平台授权 Uri （如微信二维码扫码授权网页）
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgenproviderredirecturi}
+     */
+    genProviderRedirectUri(
+      params: authModels.GenProviderRedirectUriRequest,
+    ): Promise<authModels.GenProviderRedirectUriResponse>
+    /**
+     * 重置密码（用户忘记密码无法登录时，可使用该接口强制设置密码）
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authresetpassword}
+     */
+    resetPassword(params: authModels.ResetPasswordRequest): Promise<void>
+    deviceAuthorize(params: authModels.DeviceAuthorizeRequest): Promise<authModels.DeviceAuthorizeResponse>
+    /**
+     * 通过 sudo 接口获取高级操作权限，如修改用户密码，修改手机号，邮箱等操作
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authsudo}
+     */
+    sudo(params: authModels.SudoRequest): Promise<authModels.SudoResponse>
+    /**
+     * 删除用户
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authdeleteme}
+     */
+    deleteMe(params: authModels.WithSudoRequest): Promise<authModels.UserProfile>
+    /**
+     * 获取第三方绑定列表
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetproviders}
+     */
+    getProviders(): Promise<authModels.UserProfileProvider>
+    /**
+     * 用于查询用户是否为匿名登录状态
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authloginscope}
+     */
+    loginScope(): Promise<string>
+    loginGroups(): Promise<string[]>
+    onLoginStateChanged(callback: Function)
+    createLoginState(
+      params?: { version?: string; query?: any },
+      options?: { asyncRefreshUser?: boolean; userInfo?: any },
+    ): Promise<ILoginState>
+    /**
+     * 强制刷新token
+     *
+     * @param params
+     */
+    refreshTokenForce(params: { version?: string }): Promise<authModels.Credentials>
+    /**
+     * 获取身份信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetcredentials}
+     */
+    getCredentials(): Promise<authModels.Credentials>
+    /**
+     * 写入身份信息
+     *
+     * @param credentials
+     */
+    setCredentials(credentials: authModels.Credentials): Promise<void>
+    /**
+     * 获取身份源类型
+     *
+     */
+    getProviderSubType(): Promise<authModels.ProviderSubType>
+    /**
+     * 创建验证码数据
+     *
+     * @param params
+     */
+    createCaptchaData(params: { state: string; redirect_uri?: string }): Promise<any>
+    /**
+     * 验证验证码数据
+     *
+     * @param params
+     */
+    verifyCaptchaData(params: { token: string; key: string }): Promise<any>
+    /**
+     * 修改密码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authmodifypassword}
+     *
+     * @param params
+     */
+    modifyPassword(params: authModels.ModifyUserBasicInfoRequest): Promise<void>
+    /**
+     * 未登录状态修改密码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authmodifypasswordwithoutlogin}
+     *
+     * @param params
+     */
+    modifyPasswordWithoutLogin(params: authModels.ModifyPasswordWithoutLoginRequest): Promise<void>
+    /**
+     * 获取用户行为日志
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authgetuserbehaviorlog}
+     *
+     * @param params
+     */
+    getUserBehaviorLog(params: authModels.GetUserBehaviorLog): Promise<authModels.GetUserBehaviorLogRes>
+    /**
+     * 检查用户名是否被绑定过
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv2/authentication.html#authisusernameregistered}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * const auth = app.auth();
+     * const username = "your_awesome_username";
+     * auth.isUsernameRegistered(username).then(registered=>{
+     *   // ...
+     * });
+     * ```
+     *
+     * @param username 用户名
+     *
+     * @return Promise-用户是否被绑定
+     */
+    isUsernameRegistered(username: string): Promise<boolean>
+    getMiniProgramQrCode(
+      params: authModels.GetMiniProgramQrCodeRequest,
+    ): Promise<authModels.GetMiniProgramQrCodeResponse>
+    getMiniProgramQrCodeStatus(
+      params: authModels.GetMiniProgramQrCodeStatusRequest,
+    ): Promise<authModels.GetMiniProgramQrCodeStatusResponse>
+    /**
+     * 跳转到默认登录页
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv2/authentication#authtodefaultloginpage}
+     * @param params
+     */
+    toDefaultLoginPage(params?: authModels.ToDefaultLoginPage): Promise<CommonRes>
+
+    /**
+     * 退出登录
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signout}
+     *
+     * @example
+     * ```javascript
+     * const app = cloudbase.init({
+     *   env: "xxxx-yyy"
+     * });
+     * app.auth.signOut().then(()=>{});
+     * ```
+     *
+     * @return Promise
+     */
+    signOut(params?: authModels.SignoutRequest): Promise<void | authModels.SignoutResponse>
+    /**
+     * 使用自定义登录 ticket 登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithcustomticket}
+     *
+     * @param getTickFn
+     */
+    signInWithCustomTicket(getTickFn?: authModels.GetCustomSignTicketFn): Promise<ILoginState>
+    /**
+     * 用户登录，目前支持手机号，邮箱，用户名密码登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signin}
+     */
+    signIn(params: authModels.SignInRequest): Promise<ILoginState>
+    /**
+     * 用户注册，目前支持手机号验证码注册，邮箱验证码注册
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signup}
+     */
+    signUp(params: authModels.SignUpRequest): Promise<SignUpRes>
+    /**
+     * 监听认证状态变化
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#onauthstatechange}
+     *
+     * @param callback
+     */
+    onAuthStateChange(callback: OnAuthStateChangeCallback): {
+      data: { subscription: { id: string; callback: Function; unsubscribe: () => void } }
+    }
+    /**
+     * 使用用户名和密码登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithpassword}
+     *
+     * @param params
+     */
+    signInWithPassword(params: SignInWithPasswordReq): Promise<SignInRes>
+    /**
+     * 使用第三方平台 ID Token 登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithidtoken}
+     *
+     * @param params
+     */
+    signInWithIdToken(params: SignInWithIdTokenReq): Promise<SignInRes>
+    /**
+     * 使用一次性密码（OTP）登录，支持手机号和邮箱两种方式。
+     *
+     * **注意**：手机号验证码登录需要在初始化时设置 `region: 'ap-shanghai'`。
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithotp}
+     *
+     * @example
+     * ```typescript
+     * // 完整的手机号验证码登录流程
+     * import Cloudbase from '@cloudbase/js-sdk';
+     *
+     * // 第一步：初始化（region 必须为 ap-shanghai）
+     * const app = Cloudbase.init({
+     *   env: 'your-env-id',
+     *   region: 'ap-shanghai'
+     * });
+     * const auth = app.auth();
+     *
+     * // 第二步：发送验证码
+     * const { data, error } = await auth.signInWithOtp({ phone: '+8613800138000' });
+     * if (error) {
+     *   console.error('发送验证码失败:', error.message);
+     *   return;
+     * }
+     *
+     * // 第三步：用户输入验证码后，调用 verifyOtp 完成登录
+     * const { data: loginData, error: loginError } = await data.verifyOtp({
+     *   token: userInputCode // 用户输入的验证码
+     * });
+     * if (loginError) {
+     *   console.error('验证失败:', loginError.message);
+     *   return;
+     * }
+     * console.log('登录成功:', loginData.user);
+     * ```
+     *
+     * @param params 登录参数，包含 email 或 phone（二选一）
+     */
+    signInWithOtp(params: SignInWithOtpReq): Promise<SignInWithOtpRes>
+    /**
+     * 校验第三方平台授权登录回调
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#verifyoauth}
+     *
+     * @param params
+     */
+    verifyOAuth(params?: VerifyOAuthReq): Promise<SignInRes>
+    /**
+     * 生成第三方平台授权 Uri
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithoauth}
+     *
+     * @param params
+     */
+    signInWithOAuth(params: SignInWithOAuthReq): Promise<SignInOAuthRes>
+    /**
+     * 获取当前访问令牌中的声明信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#getclaims}
+     */
+    getClaims(): Promise<GetClaimsRes>
+    /**
+     * 通过邮箱重置密码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#resetpasswordforemail}
+     *
+     * @param emailOrPhone
+     * @param options
+     */
+    resetPasswordForEmail(emailOrPhone: string, options?: { redirectTo?: string }): Promise<ResetPasswordForEmailRes>
+    /**
+     * 通过旧密码重置密码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#resetpasswordforold}
+     *
+     * @param params
+     */
+    resetPasswordForOld(params: ResetPasswordForOldReq): Promise<SignInRes>
+    /**
+     * 验证一次性密码（OTP）
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#verifyotp}
+     *
+     * @param params
+     */
+    verifyOtp(params: VerifyOtpReq): Promise<SignInRes>
+    /**
+     * 获取当前会话
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#getsession}
+     */
+    getSession(): Promise<SignInRes>
+    /**
+     * 刷新会话
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#refreshsession}
+     *
+     * @param refresh_token
+     */
+    refreshSession(refresh_token?: string): Promise<SignInRes>
+    /**
+     * 获取当前用户详细信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#getuser}
+     */
+    getUser(): Promise<GetUserRes>
+    /**
+     * 刷新用户信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#refreshuser}
+     */
+    refreshUser(): Promise<CommonRes>
+    /**
+     * 更新用户信息
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#updateuser}
+     *
+     * @param params
+     */
+    updateUser(params: UpdateUserReq): Promise<GetUserRes | UpdateUserWithVerificationRes>
+    /**
+     * 获取已绑定的身份源
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#getuseridentities}
+     */
+    getUserIdentities(): Promise<GetUserIdentitiesRes>
+    /**
+     * 绑定身份源到当前用户
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#linkidentity}
+     *
+     * @param params
+     */
+    linkIdentity(params: LinkIdentityReq): Promise<LinkIdentityRes>
+    /**
+     * 解绑身份源
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#unlinkidentity}
+     *
+     * @param params
+     */
+    unlinkIdentity(params: UnlinkIdentityReq): Promise<CommonRes>
+    /**
+     * 重新认证
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#reauthenticate}
+     */
+    reauthenticate(): Promise<ReauthenticateRes>
+    /**
+     * 重新发送验证码
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#resend}
+     *
+     * @param params
+     */
+    resend(params: ResendReq): Promise<ResendRes>
+    /**
+     * 使用 access_token 和 refresh_token 设置会话
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#setsession}
+     *
+     * @param params
+     */
+    setSession(params: SetSessionReq): Promise<SignInRes>
+    /**
+     * 删除当前用户
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#deleteuser}
+     *
+     * @param params
+     */
+    deleteUser(params: DeleteMeReq): Promise<CommonRes>
+    /**
+     * 小程序 openId 静默登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithopenid}
+     *
+     * @param params
+     */
+    signInWithOpenId(params?: { useWxCloud?: boolean }): Promise<SignInRes>
+    /**
+     * 小程序手机号授权登录
+     *
+     * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithphoneauth}
+     *
+     * @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 此方法仅发送验证码并返回布尔值，不返回 verifyOtp 回调。
+     * 推荐使用 v3 API `auth.signInWithOtp({ phone })` 替代，它会返回包含 `verifyOtp` 方法的对象，
+     * 可直接完成"发送验证码 → 用户输入 → 验证并登录"的完整流程。
+     *
+     * **迁移示例**：
+     * ```typescript
+     * // ❌ 旧方式 (v1)
+     * await auth.sendPhoneCode('+8613800138000');
+     * // 需要单独调用其他 API 验证
+     *
+     * // ✅ 新方式 (v3) - 完整的手机号验证码登录流程
+     * // 注意：初始化时必须设置 region: 'ap-shanghai'
+     * const app = Cloudbase.init({ env: 'your-env-id', region: 'ap-shanghai' });
+     * const auth = app.auth();
+     * const { data, error } = await auth.signInWithOtp({ phone: '+8613800138000' });
+     * if (error) throw error;
+     * // 用户输入验证码后调用 verifyOtp
+     * const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' });
+     * console.log('登录成功', loginData.user);
+     * ```
+     *
+     * @param phoneNumber 手机号（需含国际区号，如 +86）
+     * @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 推荐使用 v3 API 替代：
+     * - 密码登录：`auth.signInWithPassword({ phone, password })`
+     * - 验证码登录：`auth.signInWithOtp({ phone })`
+     *
+     * **迁移示例**：
+     * ```typescript
+     * // ❌ 旧方式 (v1) - 验证码登录
+     * const loginState = await auth.signInWithPhoneCodeOrPassword({
+     *   phoneNumber: '+8613800138000',
+     *   phoneCode: '123456'
+     * });
+     *
+     * // ✅ 新方式 (v3) - 验证码登录
+     * const { data, error } = await auth.signInWithOtp({ phone: '+8613800138000' });
+     * if (error) throw error;
+     * const { data: result } = await data.verifyOtp({ token: '123456' });
+     *
+     * // ✅ 新方式 (v3) - 密码登录
+     * const { data, error } = await auth.signInWithPassword({
+     *   phone: '+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>
+  }
+}
+/**
+ * functions
+ */
+declare namespace cloudbase.functions {
+  interface ICallFunctionOptions {
+    name: string
+    data?: KV<any>
+    query?: KV<any>
+    search?: string
+    parse?: boolean
+    // Used for 云函数2.0 CallContainer
+    type?: string
+    method?: string
+    path?: string
+    header?: KV<any>
+  }
+
+  interface ICallFunctionResponse {
+    requestId: string
+    result: any
+  }
+}
+/**
+ * storage
+ */
+declare namespace cloudbase.storage {
+  interface ICloudbaseUploadFileParams {
+    cloudPath: string
+    filePath?: string
+    method?: 'post' | 'put'
+    headers?: KV<string>
+    onUploadProgress?: Function
+    // 文件内容 Buffer 或 文件可读流, node端使用
+    fileContent?: any
+    customReqOpts?: ICustomReqOpts
+  }
+  interface ICloudbaseUploadFileResult {
+    fileID: string
+    requestId: string
+  }
+  interface ICloudbaseGetUploadMetadataParams {
+    cloudPath: string
+    customReqOpts?: ICustomReqOpts
+  }
+  interface ICloudbaseDeleteFileParams {
+    fileList: string[]
+    customReqOpts?: ICustomReqOpts
+  }
+  interface ICloudbaseDeleteFileResult {
+    code?: string
+    message?: string
+    fileList?: {
+      code?: string
+      fileID: string
+    }[]
+    requestId?: string
+  }
+
+  interface ICloudbaseFileInfo {
+    fileID: string
+    maxAge: number
+  }
+
+  interface ICloudbaseGetTempFileURLParams {
+    fileList: string[] | ICloudbaseFileInfo[]
+    customReqOpts?: ICustomReqOpts
+  }
+
+  interface ICloudbaseGetTempFileURLResult {
+    code?: string
+    message?: string
+    fileList?: {
+      code?: string
+      message?: string
+      fileID: string
+      tempFileURL: string
+      download_url?: string
+    }[]
+    requestId?: string
+  }
+  interface ICloudbaseDownloadFileParams {
+    fileID: string
+    tempFilePath?: string
+    customReqOpts?: ICustomReqOpts
+  }
+  interface ICloudbaseDownloadFileResult {
+    code?: string
+    message?: string
+    fileContent?: any
+    requestId?: string
+  }
+  interface ICloudbaseFileMetaData {
+    url: string
+    token: string
+    authorization: string
+    fileId: string
+    cosFileId: string
+    download_url: string
+  }
+
+  interface ICloudbaseFileMetaDataRes {
+    data: ICloudbaseFileMetaData
+    requestId: string
+  }
+
+  interface ICloudbaseCopyFileParams {
+    fileList: Array<{
+      srcPath: string
+      dstPath: string
+      overwrite?: boolean
+      removeOriginal?: boolean
+    }>
+    customReqOpts?: ICustomReqOpts
+  }
+
+  interface ICloudbaseCopyFileResult {
+    fileList: Array<{
+      fileId?: string
+      code?: string
+      message?: string
+    }>
+    requestId?: string
+  }
+
+  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 ICloudbaseGetFileInfoResult {
+    fileList: ICloudbaseGetFileInfoResultItem[]
+    requestId: string
+  }
+
+  // ---- Supabase-like Storage Types ----
+
+  /** Node.js 风格可读流的最小兼容类型，避免依赖 `@types/node`。 */
+  interface NodeReadableStreamLike {
+    /** 将当前流管道输出到目标流。 */
+    pipe(destination: any, options?: any): any
+  }
+
+  /**
+   * Node.js `Buffer` 的兼容类型。
+   *
+   * 在安装了 `@types/node` 的项目中解析为 `Buffer`，未安装时退化为 `never`，
+   * 从而既能让 Node 端继续显式传入 `Buffer`，又不会让纯浏览器项目因缺少
+   * `@types/node` 而报“找不到名称 Buffer”，避免对 `@types/node` 的硬依赖。
+   */
+  type MaybeNodeBuffer = typeof globalThis extends { Buffer: new (...args: any[]) => infer B } ? B : never
+
+  /**
+   * 可上传的文件内容类型。
+   *
+   * @remarks
+   * - Node.js `Buffer`：通过 `MaybeNodeBuffer` 兼容（装有 `@types/node` 时可直接传入）；
+   *   即便未装 `@types/node`，`Buffer` 仍可作为 `ArrayBufferView` / `Uint8Array` 传入。
+   * - Node.js 可读流（如 `NodeJS.ReadableStream` / `fs.ReadStream`）：可作为 `NodeReadableStreamLike` 传入。
+   */
+  type FileBody =
+    | ArrayBuffer
+    | ArrayBufferView
+    | Blob
+    | File
+    | FormData
+    | MaybeNodeBuffer
+    | NodeReadableStreamLike
+    | ReadableStream<Uint8Array>
+    | URLSearchParams
+    | string
+
+  /** 上传 / 覆盖对象选项。 */
+  interface FileOptions {
+    /** 缓存时间，单位为秒；会转换为 `Cache-Control: max-age=<seconds>`。 */
+    cacheControl?: string
+    /** 文件 MIME 类型；当 `fileBody` 不是 `Blob` / `File` / `FormData` 时建议显式指定。 */
+    contentType?: string
+    /** 是否允许覆盖同名对象。 */
+    upsert?: boolean
+    /** 透传给底层 `fetch` 的 duplex 配置，用于流式请求场景。 */
+    duplex?: string
+    /** 用户自定义元数据。 */
+    metadata?: Record<string, any>
+    /** 额外请求头。 */
+    headers?: Record<string, string>
+  }
+
+  /** 图片转换选项。 */
+  interface TransformOptions {
+    /** 图片宽度，单位为像素。 */
+    width?: number
+    /** 图片高度，单位为像素。 */
+    height?: number
+    /** 缩放模式：`cover` 保持比例裁剪填满；`contain` 保持比例完整适配；`fill` 拉伸填满。 */
+    resize?: 'cover' | 'contain' | 'fill'
+    /** 图片质量，通常取值 20 到 100，数值越大质量越高。 */
+    quality?: number
+    /** 输出格式；`origin` 表示保持原图格式。 */
+    format?: 'origin'
+  }
+
+  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 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 ClassicStorageFileApi {
+    /**
+     * 启用错误抛出模式，而非返回 `{ data: null, error }` 格式
+     */
+    throwOnError(): 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 }
+    >
+  }
+
+  /**
+   * Bucket 管理 API，挂载在 `app.storage` 上。
+   *
+   * @remarks 权限由 `storage.buckets` 的 RLS Policy 决定。暂不提供
+   * `emptyBucket()`、`headBucket()`、Bucket CORS、Bucket ACL 等 COS/S3 风格 Bucket 管理 API。
+   */
+  interface StorageBucketApi {
+    /**
+     * 启用错误抛出模式。开启后请求失败会抛异常；请求成功仍返回 `{ data, error: null }`。
+     * 该设置会传递给 `from()` 返回的客户端。
+     */
+    throwOnError(): this
+
+    /**
+     * 获取 Bucket 列表，支持偏移分页、排序和搜索。
+     *
+     * @param options 查询参数：`limit`、`offset`、`sortColumn`、`sortOrder`、`search`。
+     */
+    listBuckets(options?: ListBucketOptions): Promise<
+      | { data: Bucket[]; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 获取指定 Bucket 详情。
+     *
+     * @param bucketId Bucket ID。
+     */
+    getBucket(bucketId: string): Promise<
+      | { data: Bucket; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 创建 Bucket。
+     *
+     * @param bucketId Bucket ID，同时作为后端 `id` 与 `name` 传入。
+     * @param options 创建参数：`public`、`fileSizeLimit`、`allowedMimeTypes`、`type`。
+     * @remarks `public` 默认 `false`。
+     */
+    createBucket(bucketId: string, options?: CreateBucketOptions): Promise<
+      | { data: { name: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 更新 Bucket 配置。
+     *
+     * @param bucketId Bucket ID。
+     * @param options 更新参数：`public`、`fileSizeLimit`、`allowedMimeTypes`。不支持更新 `type`。
+     */
+    updateBucket(bucketId: string, options: UpdateBucketOptions): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 删除空 Bucket。
+     *
+     * @param bucketId Bucket ID。
+     * @remarks Bucket 非空时后端会返回错误。
+     */
+    deleteBucket(bucketId: string): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+  }
+
+  /**
+   * `app.storage` 命名空间（分流器）。继承 `StorageBucketApi` 的 Bucket 管理能力，并提供 `from()` 分流。
+   *
+   * `from()` 分流到两个**对等且独立**的客户端——`ClassicStorageFileApi`（传统环境）
+   * 与 `StorageFileApi`（针对全新的 Neo 环境）。
+   *
+   * - `from()`：返回 `ClassicStorageFileApi`；
+   * - `from(bucketId)`：返回 `StorageFileApi`。
+   */
+  interface StorageClient extends StorageBucketApi {
+    /**
+     * 进入对象操作客户端。
+     *
+     * - `from()`（不传 bucketId）：返回传统环境对象操作客户端；
+     * - `from(bucketId)`：返回 Neo 环境对象操作（`bucketId + objectName` 语义）客户端。
+     *
+     * @remarks 传入 `bucketId` 时返回的客户端仅 Neo 环境可用。
+     *
+     * @example
+     * ```typescript
+     * // 传统环境
+     * const file = app.storage.from()
+     * // Neo 环境
+     * const avatars = app.storage.from('avatars')
+     * ```
+     */
+    from(): ClassicStorageFileApi
+    from<B extends string>(bucketId: B): StorageFileApi
+  }
+
+  // ==================== Storage 类型 ====================
+  // 以下类型通过 app.storage.from(bucketId) 与 Bucket 管理 API 暴露。
+
+  type BucketType = 'STANDARD'
+
+  /** Bucket 资源（对应 storage.buckets 表记录）。 */
+  interface Bucket {
+    /** Bucket ID。 */
+    id: string
+    /** Bucket 名称。 */
+    name: string
+    /** 创建者用户 ID；可能为空。 */
+    owner_id?: string | null
+    /** 是否为公开 Bucket。 */
+    public: boolean
+    /** Bucket 类型。 */
+    type?: BucketType
+    /** 文件大小限制，单位为字节；`null` 表示不限制。 */
+    file_size_limit?: number | null
+    /** 允许上传的 MIME 类型列表；`null` 表示不限制。 */
+    allowed_mime_types?: string[] | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at: string
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at: string
+  }
+
+  interface ListBucketOptions {
+    /** 返回数量限制。 */
+    limit?: number
+    /** 分页偏移量。 */
+    offset?: number
+    /** 排序字段。 */
+    sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+    /** 排序方向。 */
+    sortOrder?: 'asc' | 'desc'
+    /** 搜索关键词。 */
+    search?: string
+  }
+
+  interface CreateBucketOptions {
+    /** 是否公开，默认 `false`。 */
+    public?: boolean
+    /** 文件大小限制；数字按字节处理，字符串支持如 `100MB`，`null` 表示不限制。 */
+    fileSizeLimit?: number | string | null
+    /** 允许上传的 MIME 类型列表，`null` 表示不限制。 */
+    allowedMimeTypes?: string[] | null
+    /** Bucket 类型，仅创建时可传。 */
+    type?: BucketType
+  }
+
+  interface UpdateBucketOptions {
+    /** 是否公开。 */
+    public?: boolean
+    /** 文件大小限制；数字按字节处理，字符串支持如 `100MB`，`null` 表示不限制。 */
+    fileSizeLimit?: number | string | null
+    /** 允许上传的 MIME 类型列表，`null` 表示不限制。 */
+    allowedMimeTypes?: string[] | null
+  }
+
+  /** 上传选项。 */
+  type UploadOptions = FileOptions
+
+  interface UploadResult {
+    /** 对象 UUID（后端 `Id`）。 */
+    id: string
+    /** Bucket 内相对路径。 */
+    path: string
+    /** 对象完整路径 `bucketId/objectName`（后端 `Key`）。 */
+    fullPath: string
+  }
+
+  interface DownloadOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  interface ListOptions {
+    /** 返回数量限制。 */
+    limit?: number
+    /** 翻页游标，由上一页响应的 `nextCursor` 提供。 */
+    cursor?: string
+    /** 是否使用 `/` 作为分隔符区分文件夹。 */
+    withDelimiter?: boolean
+    /** 排序配置。 */
+    sortBy?: {
+      /** 排序字段。 */
+      column?: 'name' | 'created_at' | 'updated_at'
+      /** 排序方向。 */
+      order?: 'asc' | 'desc'
+    }
+  }
+
+  interface ListObjectsEntry {
+    /** 对象完整 key；文件夹条目可能为空。 */
+    key?: string | null
+    /** 对象名或文件夹名。 */
+    name: string
+    /** 对象 UUID；文件夹条目可能为空。 */
+    id?: string | null
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at?: string | null
+    /** 最后访问时间，ISO 8601 日期时间字符串。 */
+    last_accessed_at?: string | null
+    /** 对象元数据。 */
+    metadata?: Record<string, any> | null
+  }
+
+  interface ListObjectsResponse {
+    /** 当前前缀下的文件夹条目。 */
+    folders: ListObjectsEntry[]
+    /** 当前前缀下的对象条目。 */
+    objects: ListObjectsEntry[]
+    /** 是否还有下一页。 */
+    hasNext: boolean
+    /** 下一页游标。 */
+    nextCursor?: string
+    /** 下一页起始 key。 */
+    nextCursorKey?: string
+  }
+
+  interface ObjectInfo {
+    /** 对象 UUID。 */
+    id: string
+    /** Bucket 内相对路径。 */
+    name: string
+    /** 对象版本标识；可能为空。 */
+    version?: string | null
+    /** 所属 Bucket ID。 */
+    bucketId: string
+    /** 文件大小，单位为字节；可能为空。 */
+    size?: number | null
+    /** 文件 MIME 类型；可能为空。 */
+    contentType?: string | null
+    /** 缓存控制信息；可能为空。 */
+    cacheControl?: string | null
+    /** 对象 ETag；可能为空。 */
+    etag?: string | null
+    /** 用户自定义元数据。 */
+    metadata?: Record<string, any>
+    /** 最后修改时间，ISO 8601 日期时间字符串。 */
+    lastModified?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    createdAt?: string | null
+  }
+
+  interface FullObject {
+    /** Bucket 内相对路径。 */
+    name: string
+    /** 所属 Bucket ID。 */
+    bucket_id: string
+    /** 创建者用户 ID；可能为空。 */
+    owner_id?: string | null
+    /** 对象版本标识；可能为空。 */
+    version?: string | null
+    /** 对象 UUID；可能为空。 */
+    id?: string | null
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at?: string | null
+    /** 最后访问时间，ISO 8601 日期时间字符串。 */
+    last_accessed_at?: string | null
+    /** 系统或对象元数据。 */
+    metadata?: Record<string, any>
+    /** 用户自定义元数据。 */
+    user_metadata?: Record<string, any>
+  }
+
+  interface DestinationOptions {
+    /** 目标 Bucket ID，默认与源相同。 */
+    destinationBucket?: string
+    /** 允许覆盖目标位置已有对象。 */
+    upsert?: boolean
+    /** 是否复制源对象元数据，默认 true。 */
+    copyMetadata?: boolean
+    /** `copyMetadata=false` 时合并到目标对象的用户元数据。 */
+    metadata?: Record<string, any>
+  }
+
+  interface SignedUrlOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  /** 公开 URL 选项。 */
+  interface PublicUrlOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  /**
+   * 请求级 fetch 控制参数（对齐 Supabase `FetchParameters`）。
+   *
+   * 纯客户端能力：`signal` 用于取消请求；`cache` 透传给底层 fetch 的缓存策略
+   * （主要在浏览器 fetch 路径生效，XHR / 部分运行时会忽略）。
+   */
+  interface FetchParameters {
+    /** 请求取消信号。 */
+    signal?: AbortSignal
+    /** 透传给底层 `fetch` 的缓存策略。 */
+    cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached'
+  }
+
+  /**
+   * 流式下载构建器（thenable）。`await` 后 resolve 为 `Result<ReadableStream>`。
+   * 由 `DownloadBuilder.asStream()` 创建。
+   */
+  interface StreamDownloadBuilder extends PromiseLike<
+    | { data: ReadableStream<Uint8Array>; error: null }
+    | { data: null; error: StorageError }
+  > {}
+
+  /**
+   * 下载构建器（thenable）。默认 `await` 得 `Result<Blob>`；`.asStream()` 切换为流式终态。
+   * 惰性执行：请求在 `await` / `.then()` 时才真正发出。
+   */
+  interface DownloadBuilder extends PromiseLike<
+    | { data: Blob; error: null }
+    | { data: null; error: StorageError }
+  > {
+    /** 切换为流式下载终态，返回 `StreamDownloadBuilder`。 */
+    asStream(): StreamDownloadBuilder
+  }
+
+  /**
+   * 单 Bucket 对象操作客户端。通过 `app.storage.from(bucketId)` 获取。
+   *
+   * @remarks 所有 `objectName` 均为 Bucket 内相对路径。
+   */
+  interface StorageFileApi {
+    /** 当前客户端绑定的 Bucket ID。 */
+    readonly bucketId: string
+
+    /**
+     * 启用错误抛出模式。开启后请求失败会抛异常；请求成功仍返回 `{ data, error: null }`。
+     */
+    throwOnError(): this
+
+    /**
+     * 设置自定义请求头（链式）。
+     *
+     * @remarks 设置后对当前实例后续所有请求生效；每个 `from(bucketId)` 返回独立实例，互不影响。
+     * 单次请求内部的功能性头（如上传的 `Content-Type` / `x-upsert`）优先级更高，会覆盖此处同名头。
+     * name 为空或 name/value 含 CR/LF 时抛 `StorageError`。
+     */
+    setHeader(name: string, value: string): this
+
+    /**
+     * 直接上传对象，默认不覆盖同名对象。
+     *
+     * 需要当前用户已登录，权限由 `storage.objects` 的 RLS `INSERT` / `UPDATE` 策略判定。
+     *
+     * 上传行为：
+     * - `options.upsert` 默认 `false`：目标路径已有对象时，上传失败。
+     * - `options.upsert` 设为 `true`：目标路径已有对象时，覆盖写入。
+     * - 成功时返回 `{ id, path, fullPath }`。
+     *
+     * @param path Bucket 内相对路径。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项，如 `contentType`、`cacheControl`、`upsert`、`metadata`。
+     * @see createSignedUploadUrl uploadToSignedUrl
+     */
+    upload(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: UploadResult; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 覆盖更新对象。
+     *
+     * 与 `upload` 共享同一底层，区别：
+     * - 使用 `PUT` 方法（语义为覆盖）。
+     * - 目标路径不存在时也会创建（upsert 行为）。
+     *
+     * @param path Bucket 内相对路径。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项，如 `contentType`、`cacheControl`、`metadata`。
+     */
+    update(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: UploadResult; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 下载对象。返回**下载构建器**（thenable），默认 `await` 得到 `Blob`。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * 两种终态：
+     * - 默认：`await bucket.download(path)` → `{ data: Blob, error }`。
+     * - 流式：`await bucket.download(path).asStream()` → `{ data: ReadableStream, error }`，
+     *   适合 Node 大文件等不希望整体读入内存的场景。
+     *
+     * 两者统一走原生 `fetch` 的 `Response`：流式终态返回 `Response.body`，Blob 终态调 `Response.blob()`。
+     *
+     * 下载行为：
+     * - 惰性执行：请求在 `await` / `.then()` 时才真正发出。
+     * - 返回的 `Blob` 不会自动触发浏览器下载或渲染，需配合 `URL.createObjectURL` 手动处理。
+     * - 支持 `parameters.signal`（AbortSignal）取消进行中的下载。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 下载选项，支持 `download`（触发浏览器下载）、`cacheNonce`（绕过 CDN 缓存）。
+     * @param parameters 请求控制参数，支持 `signal` / `cache`。
+     * @returns `DownloadBuilder`：可 `await` 得 `Blob`，或 `.asStream()` 后得 `ReadableStream`。
+     */
+    download(path: string, options?: DownloadOptions, parameters?: FetchParameters): DownloadBuilder
+
+    /**
+     * 获取对象列表（游标分页）。
+     *
+     * 采用**游标分页**，与 Supabase 的 `listV2` 对应。
+     *
+     * - 首次查询不传 `cursor`，后续用上一页的 `nextCursor` 继续翻页。
+     * - 返回 `{ folders, objects, hasNext, nextCursor }`（区别于 Supabase `list` 的 offset 分页 `FileObject[]`）。
+     * - `path` 不传时列出 Bucket 根目录。
+     * - `options.withDelimiter` 为 `true` 时以 `/` 分隔文件夹和文件。
+     *
+     * @param path 路径前缀，不传表示 Bucket 根目录。
+     * @param options 列表选项，支持 `limit`、`cursor`、`withDelimiter`、`sortBy`。
+     * @param parameters 请求控制参数，支持 `signal` / `cache`。
+     * @remarks 本方法对应 Supabase 的 `listV2`（游标分页），而非 `list`（offset 分页）。
+     */
+    list(path?: string, options?: ListOptions, parameters?: FetchParameters): Promise<
+      | { data: ListObjectsResponse; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 删除一个或多个对象。
+     *
+     * 权限由 `storage.objects` 的 RLS `DELETE` 策略判定。
+     *
+     * - 后端单次最多删除 100 个对象，超出时 SDK 自动分批发送。
+     * - 返回所有被成功删除的对象信息（`FullObject[]`）。
+     *
+     * @param paths Bucket 内相对路径数组。
+     */
+    remove(paths: string[]): Promise<
+      | { data: FullObject[]; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 复制对象，支持跨 Bucket。
+     *
+     * 权限由 `storage.objects` 的 RLS 策略判定：读取源需要 `SELECT`，写入目标需要 `INSERT`。
+     *
+     * - `options.destinationBucket` 不传时在同一 Bucket 内复制。
+     * - `options.upsert` 为 `true` 时，目标路径已有对象则覆盖。
+     * - `options.copyMetadata` 设为 `false` 并传 `options.metadata` 时替换原 metadata。
+     * - 返回目标对象的完整路径。
+     *
+     * @param fromPath 源对象 Bucket 内相对路径。
+     * @param toPath 目标对象相对路径。
+     * @param options 目标 Bucket、覆盖、元数据复制等选项。
+     */
+    copy(fromPath: string, toPath: string, options?: DestinationOptions): Promise<
+      | { data: { path: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 移动对象，支持跨 Bucket；源对象会被删除。
+     *
+     * 语义为"复制到目标 → 删除源"，非原地重命名。
+     * 权限由 `storage.objects` 的 RLS 策略判定：读取源需要 `SELECT`，写入目标需要 `INSERT`，删除源需要 `DELETE`。
+     *
+     * - `options.destinationBucket` 不传时在同一 Bucket 内移动。
+     *
+     * @param fromPath 源对象 Bucket 内相对路径。
+     * @param toPath 目标对象相对路径。
+     * @param options 目标 Bucket 等选项。
+     */
+    move(fromPath: string, toPath: string, options?: DestinationOptions): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 获取对象元信息。
+     *
+     * 返回对象在 `storage.objects` 表中的记录信息，包括 `bucketId`、`version`、`etag`、
+     * `contentType`、`cacheControl`、`metadata`、`lastModified`、`createdAt` 等。
+     *
+     * @param path Bucket 内相对路径。
+     */
+    info(path: string): Promise<
+      | { data: ObjectInfo; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 判断对象是否存在。
+     *
+     * 底层调用 `info` 端点：
+     * - HTTP 200 → 存在（返回 `true`）。
+     * - HTTP 400 或 404 → 不存在（返回 `false`）。
+     * - 其他异常 → 返回 `{ data: null, error }`。
+     *
+     * @param path Bucket 内相对路径。
+     */
+    exists(path: string): Promise<
+      | { data: boolean; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 生成单个对象的签名下载 URL。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * - `expiresIn` 以秒为单位，过期后 URL 不可用。
+     * - 返回的 `fullSignedURL` 是服务端已拼接好的完整 URL，客户端可直接使用（无需再拼 HOST）。
+     * - `options.download` 为 `true` 时追加 `?download`，浏览器访问时自动触发下载。
+     *
+     * @param path Bucket 内相对路径。
+     * @param expiresIn 过期时间，单位为秒。
+     * @param options 签名下载 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    createSignedUrl(path: string, expiresIn: number, options?: SignedUrlOptions): Promise<
+      | { data: { fullSignedURL: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 批量生成对象的签名下载 URL。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * - 后端单次最多 500 个，超出时 SDK 自动分批发送。
+     * - 返回数组中每个元素包含 `path`、`fullSignedURL`（完整 URL，生成失败时为 `null`）、`error`。
+     * - 部分路径生成失败不会影响其他路径。
+     *
+     * @param paths Bucket 内相对路径数组。
+     * @param expiresIn 过期时间，单位为秒。
+     * @param options 签名下载 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    createSignedUrls(paths: string[], expiresIn: number, options?: SignedUrlOptions): Promise<
+      | { data: Array<{ path: string; fullSignedURL: string | null; error: string | null }>; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 两阶段上传（第一阶段）：生成签名上传 URL，需登录态。
+     *
+     * 服务端基于调用者身份 + RLS 策略判断上传权限，生成临时签名 URL 和 token。
+     * 适合的场景：服务端鉴定用户权限后，将 `token` 下发给不受信客户端（如浏览器前端），
+     * 让客户端用 `uploadToSignedUrl` 直接上传文件，无需暴露登录凭证。
+     *
+     * - 返回的 `fullSignedURL` 是服务端已拼接好的完整上传 URL。
+     * - 返回的 `token` 是临时凭证，与 `uploadToSignedUrl` 配合使用。
+     * - `options.upsert` 为 `true` 时允许覆盖同名对象。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 签名上传选项，`upsert=true` 时允许覆盖。
+     * @see uploadToSignedUrl
+     */
+    createSignedUploadUrl(path: string, options?: { upsert?: boolean }): Promise<
+      | { data: { fullSignedURL: string; token: string; path: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 两阶段上传（第二阶段）：使用签名上传 token 上传对象，无需登录态。
+     *
+     * 配合 `createSignedUploadUrl` 完成两阶段上传：
+     * 1. 服务端调用 `createSignedUploadUrl` 生成 token（需登录态）
+     * 2. 客户端调用本方法，凭 token 上传文件（无需登录态）
+     *
+     * - 请求**不携带**登录态，仅凭 `token` 鉴权。
+     * - `path` 和 `token` 必须与 `createSignedUploadUrl` 的返回值对应。
+     *
+     * @param path Bucket 内相对路径，需与 `createSignedUploadUrl` 的 `path` 一致。
+     * @param token `createSignedUploadUrl()` 返回的 `token`。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项。
+     * @see createSignedUploadUrl
+     */
+    uploadToSignedUrl(path: string, token: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: { path: string; fullPath: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 同步获取 public bucket 对象的公开访问 URL；不发请求、不返回 `error`。
+     *
+     * **同步方法**，不发起网络请求，不会抛异常。
+     *
+     * - URL 由客户端直接拼接 `{gateway}/v1/storages/object/public/{bucketId}/{path}` 得到。
+     * - URL 是否可访问取决于 Bucket 的 `public` 属性。
+     * - `options.download` 为 `true` 时追加 `?download`。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 公开 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    getPublicUrl(path: string, options?: PublicUrlOptions): { data: { publicUrl: string } }
+  }
+}
+
+declare namespace cloudbase.database {
+  /**
+   * realtime types
+   */
+  /**
+   * watch() 监听选项
+   */
+  interface IWatchOptions {
+    /**
+     * 数据变化回调。首次建立连接时会触发 `type: 'init'` 的初始化快照，
+     * 后续每次数据变化（增/删/改）都会触发此回调。
+     *
+     * @param snapshot 数据快照，包含当前完整文档列表 `docs` 和本次变化详情 `docChanges`
+     */
+    onChange: (snapshot: ISnapshot) => void
+    /**
+     * 错误回调。在连接失败、token 过期、权限不足等异常时触发。
+     *
+     * **常见错误场景**：
+     * - 未登录或 token 过期：需先调用 `auth.signInAnonymously()` 等方法完成认证
+     * - 权限不足：检查安全规则配置
+     * - 网络中断：SDK 会自动尝试重连，重连失败后触发此回调
+     *
+     * @param error 错误信息
+     */
+    onError: (error: any) => void
+  }
+
+  /**
+   * 实时数据推送监听器。通过 `watch()` 方法返回，用于管理实时监听的生命周期。
+   *
+   * **重要**：在 React 组件卸载或不再需要监听时，务必调用 `close()` 释放资源，
+   * 避免内存泄漏和不必要的网络连接。
+   */
+  interface DBRealtimeListener {
+    /**
+     * 关闭实时推送，释放 WebSocket 连接和相关资源。
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#shu-ju-ku-shi-shi-tui-song}
+     *
+     * @example
+     * ```typescript
+     * // 启动监听
+     * const listener = db
+     *   .collection('messages')
+     *   .where({ roomId: 'room-1' })
+     *   .watch({
+     *     onChange: (snapshot) => {
+     *       console.log('数据更新:', snapshot.docs);
+     *     },
+     *     onError: (error) => {
+     *       console.error('监听异常:', error);
+     *     }
+     *   });
+     *
+     * // 不再需要时关闭监听
+     * listener.close();
+     *
+     * // React 组件中的最佳实践
+     * useEffect(() => {
+     *   const listener = db.collection('xxx').watch({ onChange, onError });
+     *   return () => listener.close(); // 组件卸载时自动清理
+     * }, []);
+     * ```
+     */
+    close: () => void
+  }
+
+  /**
+   * 数据变化类型
+   * - `'init'`：初始化数据（首次连接时返回的完整数据）
+   * - `'update'`：文档被更新
+   * - `'add'`：新增文档
+   * - `'remove'`：文档被删除
+   * - `'replace'`：文档被替换（set 操作）
+   * - `'limit'`：因 limit 限制导致的数据变化
+   */
+  type DataType = 'init' | 'update' | 'add' | 'remove' | 'replace' | 'limit'
+
+  /**
+   * 队列操作类型
+   * - `'init'`：初始化（对应 DataType 的 init）
+   * - `'enqueue'`：文档进入监听结果集（新增或开始匹配查询条件）
+   * - `'dequeue'`：文档离开监听结果集（删除或不再匹配查询条件）
+   * - `'update'`：文档在结果集中被更新
+   */
+  type QueueType = 'init' | 'enqueue' | 'dequeue' | 'update'
+
+  /**
+   * 数据快照，每次 watch 回调都会收到此对象。
+   *
+   * **使用方式**：
+   * - 获取当前完整数据列表：使用 `snapshot.docs`（数组，包含所有匹配文档的最新状态）
+   * - 获取本次变化详情：使用 `snapshot.docChanges`（数组，仅包含本次变化的文档信息）
+   * - 判断是否为初始化数据：检查 `snapshot.type === 'init'`
+   *
+   * @example
+   * ```typescript
+   * onChange: (snapshot) => {
+   *   if (snapshot.type === 'init') {
+   *     // 首次连接，snapshot.docs 包含初始完整数据
+   *     console.log('初始数据:', snapshot.docs);
+   *   } else {
+   *     // 后续变化
+   *     snapshot.docChanges.forEach(change => {
+   *       switch (change.dataType) {
+   *         case 'add':
+   *           console.log('新增文档:', change.doc);
+   *           break;
+   *         case 'update':
+   *           console.log('更新文档:', change.docId, change.updatedFields);
+   *           break;
+   *         case 'remove':
+   *           console.log('删除文档:', change.docId);
+   *           break;
+   *       }
+   *     });
+   *     // snapshot.docs 始终是变化后的完整数据列表
+   *     console.log('当前全部数据:', snapshot.docs);
+   *   }
+   * }
+   * ```
+   */
+  interface ISnapshot {
+    /** 快照序列号，单调递增 */
+    id: number
+    /** 本次变化的文档详情列表 */
+    docChanges: ISingleDBEvent[]
+    /** 当前完整的文档列表（变化后的最新状态） */
+    docs: Record<string, any>[]
+    /** 快照类型，`'init'` 表示初始化数据 */
+    type?: SnapshotType
+  }
+
+  /**
+   * 单个文档变化事件
+   */
+  interface ISingleDBEvent {
+    /** 事件序列号 */
+    id: number
+    /** 数据变化类型：init/add/update/remove/replace/limit */
+    dataType: DataType
+    /** 队列操作类型：init/enqueue/dequeue/update */
+    queueType: QueueType
+    /** 变化文档的 ID */
+    docId: string
+    /** 变化后的完整文档内容（remove 时为删除前的文档） */
+    doc: Record<string, any>
+    /** 被更新的字段及新值（仅 dataType 为 update 时存在） */
+    updatedFields?: any
+    /** 被删除的字段列表（仅 dataType 为 update 时存在） */
+    removedFields?: any
+  }
+
+  /** 快照类型。`'init'` 表示首次连接时返回的初始化数据 */
+  type SnapshotType = 'init'
+
+  interface IWatchable {
+    /**
+     * 开启实时数据推送，监听集合或文档的数据变化。
+     *
+     * **前置条件**：使用 `watch()` 前必须先完成用户认证（如匿名登录），
+     * 否则 WebSocket 连接会因缺少认证信息而失败。
+     *
+     * {@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
+     * ```typescript
+     * // === 完整示例：匿名登录 + watch + React 集成 ===
+     * import Cloudbase from '@cloudbase/js-sdk';
+     * import { useEffect, useState } from 'react';
+     *
+     * const app = Cloudbase.init({ env: 'your-env-id', region: 'ap-shanghai' });
+     *
+     * function RoomList() {
+     *   const [rooms, setRooms] = useState<any[]>([]);
+     *   const [error, setError] = useState<string | null>(null);
+     *
+     *   useEffect(() => {
+     *     let listener: cloudbase.database.DBRealtimeListener | null = null;
+     *
+     *     async function setup() {
+     *       // 第一步：必须先完成认证
+     *       const auth = app.auth();
+     *       const { error: authError } = await auth.signInAnonymously();
+     *       if (authError) {
+     *         setError('登录失败: ' + authError.message);
+     *         return;
+     *       }
+     *
+     *       // 第二步：认证成功后开启 watch
+     *       const db = app.database();
+     *       listener = db.collection('rooms')
+     *         .where({ status: 'active' })
+     *         .watch({
+     *           onChange: (snapshot) => {
+     *             // snapshot.docs 包含当前所有匹配文档
+     *             setRooms(snapshot.docs as any[]);
+     *           },
+     *           onError: (err) => {
+     *             console.error('watch 错误:', err);
+     *             setError('实时同步异常: ' + (err?.message || err));
+     *           }
+     *         });
+     *     }
+     *
+     *     setup();
+     *
+     *     // 第三步：组件卸载时清理监听
+     *     return () => {
+     *       if (listener) listener.close();
+     *     };
+     *   }, []);
+     *
+     *   if (error) return <div>错误: {error}</div>;
+     *   return (
+     *     <ul>
+     *       {rooms.map(room => <li key={room._id}>{room.name}</li>)}
+     *     </ul>
+     *   );
+     * }
+     * ```
+     *
+     * @param options 监听选项
+     * @param options.onChange 数据变化回调，接收 {@link ISnapshot} 快照对象
+     * @param options.onError 错误回调，在连接异常、认证失败等情况下触发
+     *
+     * @returns {@link DBRealtimeListener} 监听器实例，调用 `close()` 可停止监听
+     */
+    watch(options: IWatchOptions): DBRealtimeListener
+  }
+  /**
+   * collection types
+   */
+  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)
+     *
+     * @param data 要新增的数据对象或数据对象数组，支持嵌套对象、数组、地理位置等数据类型
+     *
+     * @return Promise<AddRes> 包含新增文档的 id（单条）或 ids（批量）和 requestId
+     */
+    add(data: Object | Object[]): Promise<AddRes>
+    /**
+     * 获取一条文档的引用
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#record--document}
+     *
+     * @param id 文档ID
+     */
+    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
+   */
+  interface IGeoNearOptions {
+    geometry: IGeo['Point'] // 点的地理位置
+    maxDistance?: number // 选填，最大距离，米为单位
+    minDistance?: number // 选填，最小距离，米为单位
+  }
+  interface IGeoWithinOptions {
+    geometry: IPolygon | IMultiPolygon
+  }
+  interface IGeoIntersectsOptions {
+    geometry: IPoint | ILineString | IMultiPoint | IMultiLineString | IPolygon | IMultiPolygon
+  }
+  interface ICommand {
+    /**
+     * 表示字段等于某个值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#eq}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.eq(10)
+     * })
+     *
+     * @param val 接受一个字面量 (literal)，可以是 `number`, `boolean`, `string`, `object`, `array`
+     *
+     */
+    eq(val: number | string | boolean | Object | any[]): any
+    /**
+     * 表示字段不等于某个值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#neq}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.neq(10)
+     * })
+     *
+     * @param val 接受一个字面量 (literal)，可以是 `number`, `boolean`, `string`, `object`, `array`
+     *
+     */
+    neq(val: number | string | boolean | Object | any[]): any
+    /**
+     * 字段大于指定值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#gt}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.gt(10)
+     * })
+     *
+     * @param val 数字
+     *
+     */
+    gt(val: number): any
+    /**
+     * 字段大于或等于指定值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#neq}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.gte(10)
+     * })
+     *
+     * @param val 数字
+     *
+     */
+    gte(val: number): any
+    /**
+     * 字段小于指定值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#lt}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.lt(10)
+     * })
+     *
+     * @param val 数字
+     *
+     */
+    lt(val: number): any
+    /**
+     * 字段小于或等于指定值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#lte}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.lte(10)
+     * })
+     *
+     * @param val 数字
+     *
+     */
+    lte(val: number): any
+    /**
+     * 字段值在给定的数组中
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#in}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.in([1,2,3])
+     * })
+     *
+     * @param list 数组
+     *
+     */
+    in(list: any[]): any
+    /**
+     * 字段值不在给定的数组中
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#nin}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.nin([1,2,3])
+     * })
+     *
+     * @param list 数组
+     *
+     */
+    nin(list: any[]): any
+    /**
+     * 表示需同时满足指定的两个或以上的条件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#and}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.and(_.gt(4), _.lt(32))
+     * })
+     *
+     * @param args 多个条件
+     *
+     */
+    and(...args: any[]): any
+    /**
+     * 表示需满足所有指定条件中的至少一个
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#or}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   num: _.or(_.gt(4), _.lt(32))
+     * })
+     *
+     * @param args 多个条件
+     *
+     */
+    or(...args: any[]): any
+    /**
+     * 用于设定字段等于指定值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#set}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      data: {
+     *        style: _.set({
+     *          color: "red"
+     *        })
+     *      }
+     *   });
+     *
+     * @param val 被设定的属性对象
+     *
+     */
+    set(val: any): any
+    /**
+     * 用于指示字段自增某个值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#inc}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      count: {
+     *       favorites: _.inc(1)
+     *     }
+     *   });
+     *
+     * @param val 自增的值
+     *
+     */
+    inc(val: number): any
+    /**
+     * 用于指示字段自乘某个值
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#mul}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      count: {
+     *       favorites: _.mul(21)
+     *     }
+     *   });
+     *
+     * @param val 自乘的值
+     *
+     */
+    mul(val: number): any
+    /**
+     * 用于表示删除某个字段
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#remove}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      rating: _.remove()
+     *   });
+     *
+     */
+    remove(): any
+    /**
+     * 向数组尾部追加元素
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#push}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      users: _.push(["aaa", "bbb"])
+     *   });
+     *
+     * @param val 支持传入单个元素或数组
+     */
+    push(val: any): any
+    /**
+     * 删除数组尾部元素
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#pop}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      users: _.pop()
+     *   });
+     *
+     */
+    pop(): any
+    /**
+     * 向数组头部添加元素
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#unshift}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      users: _.unshift(["aaa", "bbb"])
+     *   });
+     *
+     * @param val 支持传入单个元素或数组
+     */
+    unshift(val: any): any
+    /**
+     * 删除数组头部元素
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#shift}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo")
+     *   .doc("doc-id")
+     *   .update({
+     *      users: _.unshift()
+     *   });
+     *
+     */
+    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-next/database#geonear}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   location: _.geoNear({
+     *     geometry: new db.Geo.Point(lngA, latA),
+     *     maxDistance: 1000,
+     *     minDistance: 0
+     *   })
+     * });
+     *
+     * @param options
+     * @param options.geometry 点的地理位置
+     * @param options.maxDistance 【可选】最大距离，米为单位
+     * @param options.minDistance 【可选】最小距离，米为单位
+     */
+    geoNear(options: IGeoNearOptions): any
+    /**
+     * 找出字段值在指定 Polygon / MultiPolygon 内的文档，无排序
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#geowithin}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("demo").where({
+     *   location: _.geoWithin({
+     *     geometry: new Polygon({
+     *       new LineString([...Points])
+     *     }),
+     *   })
+     * });
+     *
+     * @param options
+     * @param options.geometry 地理位置
+     */
+    geoWithin(options: IGeoWithinOptions): any
+    /**
+     * 找出字段值和给定的地理位置图形相交的文档
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#geointersects}
+     *
+     * @example
+     * const _ = db.command;
+     * db.collection("user").where({
+     *   location: _.geoNear({
+     *     geometry: new LineString([new Point(lngA, latA), new Point(lngB, latB)]);
+     *   })
+     * });
+     *
+     * @param options
+     * @param options.geometry 地理位置
+     */
+    geoIntersects(options: IGeoIntersectsOptions): any
+  }
+  /**
+   * document types
+   */
+  interface IDocument extends IWatchable {
+    /**
+     * 设置文档数据，如果文档不存在则创建新文档
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#update-set}
+     *
+     * @example
+     * collection
+     *   .doc('docId')
+     *   .set({name:'cloudbase'})
+     *   .then(res=>{})
+     *
+     * @param data 要设置的数据对象，将完全替换原有文档内容
+     *
+     * @return Promise<SetRes> 包含 updated 或 upsertedId
+     */
+    set(data: Object): Promise<SetRes>
+    /**
+     * 获取文档数据
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#get}
+     *
+     * @example
+     * collection
+     *   .doc('docId')
+     *   .get()
+     *   .then(res=>{ console.log(res.data) })
+     *
+     * @return Promise<GetRes> 包含 data 数组和 requestId
+     */
+    get(): Promise<GetRes>
+    /**
+     * 更新文档数据，如果文档不存在则不做任何操作
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#update--set}
+     *
+     * @example
+     * collection
+     *   .doc('docId')
+     *   .update({completed: true})
+     *   .then(res=>{ console.log(res.updated) })
+     *
+     * @param data 要更新的数据对象，支持操作符
+     *
+     * @return Promise<UpdateRes> 包含 updated 字段
+     */
+    update(data: Object): Promise<UpdateRes>
+    /**
+     * 删除一条文档
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#remove-2}
+     *
+     * @example
+     * collection
+     *   .doc('docId')
+     *   .remove()
+     *   .then(res=>{ console.log(res.deleted) })
+     *
+     * @return Promise<RemoveRes> 包含 deleted 字段
+     */
+    remove(): Promise<RemoveRes>
+    /**
+     * 指定要返回的字段
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#field}
+     *
+     * @param projection 字段投影对象，true 表示返回，false 表示不返回
+     *
+     * @return 文档引用，可继续链式调用 get()
+     */
+    field(projection: Object): IDocument
+  }
+  /**
+   * query types
+   */
+  interface SetRes {
+    code?: string
+    message?: string
+    updated?: number
+    upsertedId?: string
+    requestId: string
+  }
+  interface GetRes {
+    data: any[]
+    requestId: string
+    code?: string
+    message?: string
+  }
+
+  interface UpdateRes {
+    requestId: string
+    updated?: number
+    upsertedId?: string
+    code?: string
+    message?: string
+  }
+
+  interface AddRes {
+    id?: string
+    ids?: string[]
+    insertedIds?: 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'
+  }
+
+  interface QueryOption {
+    // 查询数量
+    limit?: number
+    // 偏移量
+    offset?: number
+    // 指定显示或者不显示哪些字段
+    projection?: Object
+  }
+  interface IQuery extends IWatchable {
+    /**
+     * 获取数据库查询结果
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#get}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .get()
+     *   .then(res=>{})
+     *
+     * @return Promise-查询结果
+     */
+    get(): Promise<GetRes>
+    /**
+     * 更新数据库文档
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#update-set}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .update({
+     *      name: 'newCloudbase'
+     *    })
+     *   .then(res=>{})
+     *
+     * @return Promise-查询结果
+     */
+    update(data: Object): Promise<UpdateRes>
+    /**
+     * 获取数据库查询结果的数目
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#count}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .count()
+     *   .then(res=>{})
+     *
+     * @return Promise<CountRes> 包含 total 字段
+     */
+    count(): Promise<CountRes>
+    /**
+     * 设置过滤条件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#where}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *
+     * @param query 可接收对象作为参数，表示筛选出拥有和传入对象相同的 key-value 的文档
+     *
+     */
+    where(query: Object): ExcludeOf<IQuery, 'where'>
+    /**
+     * 指定查询结果集数量上限
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#limit}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .limit(1)
+     *
+     * @param limit 查询结果数量上限
+     */
+    limit(limit: number): ExcludeOf<IQuery, 'where'>
+    /**
+     * 指定查询返回结果时从指定序列后的结果开始返回，常用于分页
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#skip}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .skip(4)
+     *
+     * @param offset 跳过的条目数量
+     */
+    skip(offset: number): ExcludeOf<IQuery, 'where'>
+    /**
+     * 指定查询排序条件
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#orderby}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .orderBy("name", "asc")
+     *
+     * @param field 排序的字段
+     * @param orderType 排序的顺序，升序(asc) 或 降序(desc)
+     */
+    orderBy(field: string, orderType: 'desc' | 'asc'): ExcludeOf<IQuery, 'where'>
+    /**
+     * 指定返回结果中文档需返回的字段
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#field}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .field({ age: true })
+     *
+     * @param projection 要过滤的字段集合，不返回传 false，返回传 true
+     */
+    field(projection: Object): ExcludeOf<IQuery, 'where'>
+    /**
+     * 删除查询到的结果
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#remove-1}
+     *
+     * @example
+     * collection
+     *   .where({
+     *     name: 'cloudbase'
+     *   })
+     *   .remove()
+     *
+     * @return Promise<RemoveRes> 包含 deleted 字段
+     */
+    remove(): Promise<RemoveRes>
+  }
+  /**
+   * geo types
+   */
+  interface IPoint {}
+  interface ILineString {}
+  interface IPolygon {}
+  interface IMultiPoint {}
+  interface IMultiLineString {}
+  interface IMultiPolygon {}
+  interface IGeo {
+    /**
+     * 用于表示地理位置点
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#point}
+     *
+     * @example
+     * const point = new db.Geo.Point(lng,lat);
+     *
+     * @param longitude 经度
+     * @param latitude 纬度
+     *
+     * @return Point
+     */
+    Point: {
+      new (longitude: number, latitude: number): IPoint
+    }
+    /**
+     * 用于表示地理路径，是由两个或者更多的 Point 组成的线段
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#linestring}
+     *
+     * @example
+     * const point = new db.Geo.LineString([pointA,pointB]);
+     *
+     * @param points Point数组
+     *
+     * @return LineString
+     */
+    LineString: {
+      new (points: IPoint[]): ILineString
+    }
+    /**
+     * 用于表示地理上的一个多边形
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#polygon}
+     *
+     * @example
+     * const point = new db.Geo.Polygon([lineStringA,lineStringB]);
+     *
+     * @param lines LineString数组
+     *
+     * @return Polygon
+     */
+    Polygon: {
+      new (lines: ILineString[]): IPolygon
+    }
+    /**
+     * 用于表示多个点 Point 的集合
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multipoint}
+     *
+     * @example
+     * const point = new db.Geo.MultiPoint([pointA,pointB]);
+     *
+     * @param points Point数组
+     *
+     * @return MultiPoint
+     */
+    MultiPoint: {
+      new (points: IPoint[]): IMultiPoint
+    }
+    /**
+     * 用于表示多个地理路径 LineString 的集合
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multilinestring}
+     *
+     * @example
+     * const point = new db.Geo.MultiLineString([lineA,lineB]);
+     *
+     * @param lines LineString数组
+     *
+     * @return MultiLineString
+     */
+    MultiLineString: {
+      new (lines: ILineString[]): IMultiLineString
+    }
+    /**
+     * 用于表示多个地理多边形 Polygon 的集合
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#multipolygon}
+     *
+     * @example
+     * const point = new db.Geo.MultiPolygon([polygonA,polygonB]);
+     *
+     * @param polygons Polygon数组
+     *
+     * @return MultiPolygon
+     */
+    MultiPolygon: {
+      new (polygons: IPolygon[]): IMultiPolygon
+    }
+  }
+  /**
+   * regexp types
+   */
+  interface IRegExpOptions {
+    regexp: string
+    options?: string
+  }
+  interface IRegExp {
+    (options: IRegExpOptions): any
+  }
+  /**
+   * instance types
+   */
+  interface App {
+    /**
+     * 数据库指令
+     *
+     * {@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-next/database.html#geo-shu-ju-lei-xing}
+     */
+    Geo: IGeo
+    /**
+     * 根据正则表达式进行筛选
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#regexp}
+     *
+     * @example
+     * db.collection('articles').where({
+     *   version: new db.RegExp({
+     *     regexp: '^\\ds'   // 正则表达式为 /^\ds/，转义后变成 '^\\ds'
+     *     options: 'i'    // i表示忽略大小写
+     *   })
+     * })
+     *
+     * @param options
+     * @param options.regexp 正则表达式Pattern
+     * @param options.options 正则表达式Flags
+     */
+    RegExp: IRegExp
+    /**
+     * 创建集合的引用
+     *
+     * {@link https://docs.cloudbase.net/api-reference/webv3-next/database.html#collection}
+     *
+     * @example
+     * const coll = db.collection('demo');
+     *
+     * @param name 集合名称
+     *
+     * @return 集合的引用
+     */
+    collection(name: string): ICollection
+
+    runCommands(params: IRunCommandsReq): Promise<{
+      statusCode: number
+      requestId: string
+      list?: Object[][]
+      code?: string
+      message?: string
+    }>
+  }
+}
+