@cloudbase/js-sdk 3.3.4 → 3.3.6

package/index.d.ts

@@ -714,6 +714,7 @@ declare namespace cloudbase.auth {
     qqMiniOpenId?: string
     customUserId?: string
     name?: string
+    displayName?: string
     gender?: string
     email?: string
     username?: string
@@ -865,11 +866,53 @@ declare namespace cloudbase.auth {
       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>
     /**
@@ -1231,11 +1274,43 @@ declare namespace cloudbase.auth {
      */
     signInWithIdToken(params: SignInWithIdTokenReq): Promise<SignInRes>
     /**
-     * 使用一次性密码（OTP）登录
+     * 使用一次性密码（OTP）登录，支持手机号和邮箱两种方式。
+     *
+     * **注意**：手机号验证码登录需要在初始化时设置 `region: 'ap-shanghai'`。
      *
      * 文档 {@link https://docs.cloudbase.net/api-reference/webv3/authentication#signinwithotp}
      *
-     * @param params
+     * @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>
     /**
@@ -1502,14 +1577,28 @@ declare namespace cloudbase.auth {
     /**
      * v1 API: 发送手机验证码
      *
-     * @deprecated 建议使用 auth.signInWithOtp({ phone }) 或 auth.getVerification({ phone_number }) 替代。
+     * @deprecated 此方法仅发送验证码并返回布尔值，不返回 verifyOtp 回调。
+     * 推荐使用 v3 API `auth.signInWithOtp({ phone })` 替代，它会返回包含 `verifyOtp` 方法的对象，
+     * 可直接完成"发送验证码 → 用户输入 → 验证并登录"的完整流程。
      *
-     * @example
-     * ```javascript
-     * const success = await auth.sendPhoneCode('+8613800138000');
+     * **迁移示例**：
+     * ```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 手机号
+     * @param phoneNumber 手机号（需含国际区号，如 +86）
      * @returns 是否发送成功
      */
     sendPhoneCode(phoneNumber: string): Promise<boolean>
@@ -1533,20 +1622,26 @@ declare namespace cloudbase.auth {
     /**
      * v1 API: 手机号登录（支持短信验证码 or 密码方式）
      *
-     * @deprecated 密码方式建议使用 auth.signInWithPassword({ phone, password }) 替代；
-     * 验证码方式建议使用 auth.signInWithOtp({ phone }) 替代。
+     * @deprecated 推荐使用 v3 API 替代：
+     * - 密码登录：`auth.signInWithPassword({ phone, password })`
+     * - 验证码登录：`auth.signInWithOtp({ phone })`
      *
-     * @example
-     * ```javascript
-     * // 验证码登录
+     * **迁移示例**：
+     * ```typescript
+     * // ❌ 旧方式 (v1) - 验证码登录
      * const loginState = await auth.signInWithPhoneCodeOrPassword({
      *   phoneNumber: '+8613800138000',
      *   phoneCode: '123456'
      * });
      *
-     * // 密码登录
-     * const loginState = await auth.signInWithPhoneCodeOrPassword({
-     *   phoneNumber: '+8613800138000',
+     * // ✅ 新方式 (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'
      * });
      * ```
@@ -2162,80 +2257,230 @@ declare namespace cloudbase.database {
   /**
    * realtime types
    */
+  /**
+   * watch() 监听选项
+   */
   interface IWatchOptions {
-    // server realtime data init & change event
+    /**
+     * 数据变化回调。首次建立连接时会触发 `type: 'init'` 的初始化快照，
+     * 后续每次数据变化（增/删/改）都会触发此回调。
+     *
+     * @param snapshot 数据快照，包含当前完整文档列表 `docs` 和本次变化详情 `docChanges`
+     */
     onChange: (snapshot: ISnapshot) => void
-    // error while connecting / listening
+    /**
+     * 错误回调。在连接失败、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 ref = db
-     *   .collection("collName")
-     *   .where({ test: _.gt(0) })
+     * const listener = db
+     *   .collection('messages')
+     *   .where({ roomId: 'room-1' })
      *   .watch({
      *     onChange: (snapshot) => {
-     *       console.log("收到snapshot**********", snapshot);
+     *       console.log('数据更新:', snapshot.docs);
      *     },
      *     onError: (error) => {
-     *       console.log("收到error**********", error);
+     *       console.error('监听异常:', error);
      *     }
      *   });
-     * // 关闭监听
-     * ref.close();
+     *
+     * // 不再需要时关闭监听
+     * 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>
+    /** 当前完整的文档列表（变化后的最新状态） */
+    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
-     * const ref = db
-     *   .collection("collName")
-     *   .where({ test: _.gt(0) })
-     *   .watch({
-     *     onChange: (snapshot) => {
-     *       console.log("收到snapshot**********", snapshot);
-     *     },
-     *     onError: (error) => {
-     *       console.log("收到error**********", error);
+     * ```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));
+     *           }
+     *         });
      *     }
-     *   });
-     * @param options
-     * @param options.onChange 监听数据变化的回调函数
-     * @param options.onError 监听出现错误的回调函数
      *
-     * @return 实时推送进程实例
+     *     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
   }
@@ -2255,11 +2500,11 @@ declare namespace cloudbase.database {
      * })
      * console.log('新增成功，文档 ID:', result.id)
      *
-     * @param data 要新增的数据对象，支持嵌套对象、数组、地理位置等数据类型
+     * @param data 要新增的数据对象或数据对象数组，支持嵌套对象、数组、地理位置等数据类型
      *
-     * @return Promise<AddRes> 包含新增文档的 id 和 requestId
+     * @return Promise<AddRes> 包含新增文档的 id（单条）或 ids（批量）和 requestId
      */
-    add(data: Object): Promise<AddRes>
+    add(data: Object | Object[]): Promise<AddRes>
     /**
      * 获取一条文档的引用
      *
@@ -2881,7 +3126,9 @@ declare namespace cloudbase.database {
   }
 
   interface AddRes {
-    id: string
+    id?: string
+    ids?: string[]
+    insertedIds?: string[]
     requestId: string
     code?: string
     message?: string