@cloudbase/js-sdk 3.1.8 → 3.1.9

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # 更新日志
 
+## [3.1.9] 2026-03-13
+- [Added] 增强类型声明以及错误提示
+
 ## [3.1.8] 2026-03-12
 - [Fixed] 增加 storage 类型定义
 

package/dist/index.cjs.js

@@ -14,7 +14,7 @@ var cloudrun_1 = require("@cloudbase/cloudrun");
 var mysql_1 = require("@cloudbase/mysql");
 var apis_1 = require("@cloudbase/apis");
 var database_1 = require("./../database");
-var version = "3.1.8";
+var version = "3.1.9";
 app_1.default.registerVersion(version);
 try {
     (0, auth_1.registerAuth)(app_1.default);

package/dist/index.esm.js

@@ -10,7 +10,7 @@ import { registerCloudrun } from '@cloudbase/cloudrun';
 import { registerMySQL } from '@cloudbase/mysql';
 import { registerApis } from '@cloudbase/apis';
 import { registerDatabase } from './../database';
-var version = "3.1.8";
+var version = "3.1.9";
 cloudbase.registerVersion(version);
 try {
     registerAuth(cloudbase);

package/index.d.ts

@@ -78,11 +78,19 @@ declare namespace cloudbase {
   }
 
   interface ICloudbaseConfig {
+    /** 环境 ID，在腾讯云开发控制台 → 环境 → 环境总览中获取 */
     env: string
+    /**
+     * 地域信息
+     * @example 'ap-shanghai'
+     */
     region?: string
+    /** 网络请求超时上限，单位 ms，默认 15000 */
     timeout?: number
+    /** 本地登录态保留期限 */
     persistence?: Persistence
     oauthClient?: any
+    /** 是否开启调试模式 */
     debug?: boolean
     _fromApp?: ICloudbase
     clientId?: string
@@ -95,7 +103,31 @@ declare namespace cloudbase {
     }
     accessKey?: string
     endPointMode?: EndPointKey
-    lang?: LANGS 
+    lang?: LANGS
+    /**
+     * 认证相关配置
+     * @example
+     * ```typescript
+     * cloudbase.init({
+     *   env: 'your-env-id',
+     *   auth: {
+     *     detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
+     *   }
+     * })
+     * ```
+     */
+    auth?: {
+      /** 是否自动检测 URL 中的 OAuth 回调参数，默认 false */
+      detectSessionInUrl?: boolean
+      /** 密钥 ID（Node.js 端使用） */
+      secretId?: string
+      /** 密钥（Node.js 端使用） */
+      secretKey?: string
+      /** 临时会话 Token（Node.js 端使用） */
+      sessionToken?: string
+      /** 密钥类型 */
+      secretType?: 'SESSION_SECRET' | 'SECRET'
+    }
   }
 
   interface ICloudbaseExtension {
@@ -148,20 +180,49 @@ declare namespace cloudbase {
    *
    * @example
    * ```javascript
+   * // 基本用法
    * const app = cloudbase.init({
    *   env: 'your-envid',
    *   timeout: 15000
    * });
+   *
+   * // 推荐：从环境变量读取环境 ID
+   * const app = cloudbase.init({
+   *   env: process.env.CLOUDBASE_ENV || import.meta.env.VITE_CLOUDBASE_ENV || 'your-envid'
+   * });
+   *
+   * // 使用认证配置
+   * const app = cloudbase.init({
+   *   env: 'your-envid',
+   *   auth: {
+   *     detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
+   *   }
+   * });
    * ```
    *
    * @param config 初始化配置
-   * @param config.env 环境ID
+   * @param config.env 环境ID，在腾讯云开发控制台 → 环境 → 环境总览中获取
    * @param config.timeout 【可选】网络请求超时上限，单位`ms`，默认值`15000`
+   * @param config.auth 【可选】认证相关配置
    *
    * @return {!cloudbase.app.App} 初始化成功的Cloudbase实例
    */
   function init(config: ICloudbaseConfig): cloudbase.app.App
 
+  /**
+   * 检查 Cloudbase 实例是否已完成初始化
+   *
+   * @example
+   * ```javascript
+   * if (!cloudbase.isInitialized()) {
+   *   cloudbase.init({ env: 'your-envid' });
+   * }
+   * ```
+   *
+   * @returns 是否已初始化
+   */
+  function isInitialized(): boolean
+
   function updateConfig(config: ICloudbaseUpgradedConfig): void
 
   function updateLang(lang: LANGS): void
@@ -1318,6 +1379,296 @@ declare namespace cloudbase.auth {
      * @param params
      */
     signInWithPhoneAuth(params: { phoneCode: string }): Promise<SignInRes>
+
+    // ========== v1 兼容 API ==========
+
+    /**
+     * v1 API: 获取用于微信登录的 WeixinAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInWithOAuth({ provider: appid }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.weixinAuthProvider({ appid: 'wx-appid', scope: 'snsapi_login' });
+     * provider.signInWithRedirect();
+     * ```
+     *
+     * @param options
+     * @param options.appid 微信 AppID
+     * @param options.scope 微信授权范围
+     */
+    weixinAuthProvider(options: { appid: string; scope: string }): cloudbase.auth.WeixinAuthProvider
+
+    /**
+     * v1 API: 获取用于自定义登录的 CustomAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.customAuthProvider();
+     * await provider.signIn(ticket);
+     * ```
+     */
+    customAuthProvider(): cloudbase.auth.CustomAuthProvider
+
+    /**
+     * v1 API: 获取用于匿名登录的 AnonymousAuthProvider
+     *
+     * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+     *
+     * @example
+     * ```javascript
+     * const provider = auth.anonymousAuthProvider();
+     * await provider.signIn();
+     * ```
+     */
+    anonymousAuthProvider(): cloudbase.auth.AnonymousAuthProvider
+
+    /**
+     * v1 API: 使用邮箱和密码注册云开发账户
+     *
+     * @deprecated 建议使用 auth.signUp({ email, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * await auth.signUpWithEmailAndPassword('user@example.com', 'password123');
+     * ```
+     *
+     * @param email 邮箱
+     * @param password 密码
+     */
+    signUpWithEmailAndPassword(email: string, password: string): Promise<SignUpRes>
+
+    /**
+     * v1 API: 使用邮箱和密码登录云开发（支持两种调用方式）
+     *
+     * @deprecated 建议使用 auth.signInWithPassword({ email, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * // 方式一（v1 风格）：
+     * await auth.signInWithEmailAndPassword('user@example.com', 'password123');
+     *
+     * // 方式二（v3 风格）：
+     * const { data, error } = await auth.signInWithEmailAndPassword({
+     *   email: 'user@example.com',
+     *   password: 'password123'
+     * });
+     * ```
+     *
+     * @param emailOrParams - 邮箱字符串（v1）或包含 email 和 password 的对象（v3）
+     * @param password - 密码（仅 v1 风格时使用）
+     */
+    signInWithEmailAndPassword(emailOrParams: string | { email: string; password: string; is_encrypt?: boolean }, password?: string): Promise<SignInRes | ILoginState>
+
+    /**
+     * v1 API: 发送重置密码的邮件
+     *
+     * @deprecated 建议使用 auth.resetPasswordForEmail(email) 替代。
+     *
+     * @example
+     * ```javascript
+     * await auth.sendPasswordResetEmail('user@example.com');
+     * ```
+     *
+     * @param email 邮箱
+     */
+    sendPasswordResetEmail(email: string): Promise<void>
+
+    /**
+     * v1 API: 使用用户名和密码登录云开发
+     *
+     * @deprecated 建议使用 auth.signInWithPassword({ username, password }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.signInWithUsernameAndPassword('username', 'password123');
+     * ```
+     *
+     * @param username 用户名
+     * @param password 密码
+     */
+    signInWithUsernameAndPassword(username: string, password: string): Promise<ILoginState>
+
+    /**
+     * v1 API: 发送手机验证码
+     *
+     * @deprecated 建议使用 auth.signInWithOtp({ phone }) 或 auth.getVerification({ phone_number }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const success = await auth.sendPhoneCode('+8613800138000');
+     * ```
+     *
+     * @param phoneNumber 手机号
+     * @returns 是否发送成功
+     */
+    sendPhoneCode(phoneNumber: string): Promise<boolean>
+
+    /**
+     * v1 API: 手机号注册（支持短信验证码+密码方式）
+     *
+     * @deprecated 建议使用 auth.signUp({ phone_number, verification_code, password? }) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.signUpWithPhoneCode('+8613800138000', '123456', 'password');
+     * ```
+     *
+     * @param phoneNumber 手机号
+     * @param phoneCode 验证码
+     * @param password 可选密码
+     */
+    signUpWithPhoneCode(phoneNumber: string, phoneCode: string, password?: string): Promise<ILoginState>
+
+    /**
+     * v1 API: 手机号登录（支持短信验证码 or 密码方式）
+     *
+     * @deprecated 密码方式建议使用 auth.signInWithPassword({ phone, password }) 替代；
+     * 验证码方式建议使用 auth.signInWithOtp({ phone }) 替代。
+     *
+     * @example
+     * ```javascript
+     * // 验证码登录
+     * const loginState = await auth.signInWithPhoneCodeOrPassword({
+     *   phoneNumber: '+8613800138000',
+     *   phoneCode: '123456'
+     * });
+     *
+     * // 密码登录
+     * const loginState = await auth.signInWithPhoneCodeOrPassword({
+     *   phoneNumber: '+8613800138000',
+     *   password: 'password123'
+     * });
+     * ```
+     *
+     * @param params
+     */
+    signInWithPhoneCodeOrPassword(params: {
+      phoneNumber: string
+      phoneCode?: string
+      password?: string
+    }): Promise<ILoginState>
+
+    /**
+     * v1 API: 手机号强制重置密码
+     *
+     * @deprecated 建议使用 auth.resetPasswordForEmail(phoneNumber) 替代。
+     *
+     * @example
+     * ```javascript
+     * const loginState = await auth.forceResetPwdByPhoneCode({
+     *   phoneNumber: '+8613800138000',
+     *   phoneCode: '123456',
+     *   password: 'newPassword'
+     * });
+     * ```
+     *
+     * @param params
+     */
+    forceResetPwdByPhoneCode(params: {
+      phoneNumber: string
+      phoneCode: string
+      password: string
+    }): Promise<ILoginState>
+
+    /**
+     * v1 API: 接收一个回调函数，在刷新短期访问令牌前调用，根据返回值决定是否刷新
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 监听 TOKEN_REFRESHED 事件替代。
+     *
+     * @param callback 回调函数，返回 true 则刷新，返回 false 则不刷新
+     */
+    shouldRefreshAccessToken(callback: () => boolean): void
+
+    /**
+     * v1 API: 接收一个回调函数，在登录状态过期时调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_OUT 事件。
+     *
+     * @param callback 登录态过期回调
+     */
+    onLoginStateExpired(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在短期访问令牌刷新后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 TOKEN_REFRESHED 事件。
+     *
+     * @param callback 令牌刷新回调
+     */
+    onAccessTokenRefreshed(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在匿名登录状态被转换后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_IN 事件。
+     *
+     * @param callback 匿名转正回调
+     */
+    onAnonymousConverted(callback: Function): void
+
+    /**
+     * v1 API: 接收一个回调函数，在登录类型发生变化后调用
+     *
+     * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代，监听 SIGNED_IN / SIGNED_OUT 事件。
+     *
+     * @param callback 登录类型变化回调
+     */
+    onLoginTypeChanged(callback: Function): void
+  }
+
+  // ========== v1 兼容 Provider 类 ==========
+
+  /**
+   * v1 微信登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInWithOAuth({ provider }) 替代。
+   */
+  interface WeixinAuthProvider {
+    /**
+     * 跳转微信授权页面进行登录
+     * @deprecated 建议使用 auth.signInWithOAuth({ provider: 'providerId' }) 替代。
+     */
+    signInWithRedirect(): void
+    /**
+     * 获取微信授权重定向结果
+     * @deprecated 建议使用 auth.verifyOAuth({ code, state, provider }) 替代。
+     */
+    getRedirectResult(options?: { createUser?: boolean; syncUserInfo?: boolean }): Promise<any>
+    /**
+     * 获取微信绑定重定向结果
+     * @deprecated 建议使用 auth.linkIdentity({ provider: 'providerId' }) 替代。
+     */
+    getLinkRedirectResult(options?: { withUnionId?: boolean }): Promise<void>
+  }
+
+  /**
+   * v1 自定义登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+   */
+  interface CustomAuthProvider {
+    /**
+     * 使用自定义登录凭据 ticket 登录云开发
+     * @param ticket 自定义登录 ticket
+     * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
+     */
+    signIn(ticket: string): Promise<void>
+  }
+
+  /**
+   * v1 匿名登录 Provider
+   *
+   * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+   */
+  interface AnonymousAuthProvider {
+    /**
+     * 匿名登录云开发
+     * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
+     */
+    signIn(): Promise<void>
   }
 }
 /**
@@ -3009,10 +3360,19 @@ declare namespace cloudbase.database {
     /**
      * 创建集合
      *
+     * **⚠️ 权限说明**：此方法通常需要管理员权限，客户端 SDK（Web/小程序）在默认安全规则下
+     * 可能无权限调用此方法。如果调用失败，请通过以下方式创建集合：
+     * 1. 登录[腾讯云开发控制台](https://console.cloud.tencent.com/tcb/database)手动创建
+     * 2. 在云函数中使用管理端 SDK 创建
+     * 3. 使用 CLI 工具创建：`tcb service:collection-create <collName>`
+     *
      * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#createcollection}
      *
      * @example
+     * ```javascript
+     * // 管理端 SDK 或具有管理员权限时可用
      * const result = await db.createCollection('new-collection')
+     * ```
      *
      * @param collName 集合名称
      *
@@ -3085,5 +3445,5 @@ declare namespace cloudbase.database {
   }
 }
 
-export default cloudbase
+export = cloudbase
 export as namespace cloudbase