@cloudbase/auth 2.27.0 → 2.27.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/auth",
-  "version": "2.27.0",
+  "version": "2.27.2",
   "description": "cloudbase javascript sdk auth componets",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -32,14 +32,14 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@cloudbase/adapter-wx_mp": "^1.3.1",
-    "@cloudbase/oauth": "2.27.0",
-    "@cloudbase/utilities": "2.27.0"
+    "@cloudbase/oauth": "2.27.2",
+    "@cloudbase/utilities": "2.27.2"
   },
   "devDependencies": {
-    "@cloudbase/types": "2.27.0",
+    "@cloudbase/types": "2.27.2",
     "@types/node": "^22.1.0",
     "terser-webpack-plugin": "^3.0.2",
     "webpack-bundle-analyzer": "^4.9.1"
   },
-  "gitHead": "62012d57fc6da621defdadceffa83eede2ed5115"
+  "gitHead": "839944b6a1ebd74b52e357382fa57bbb0e3b0d2c"
 }

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   OAUTH_TYPE,
   weAppJwtDecodeAll,
   AuthError,
+  AuthErrorCategory,
   authModels,
   DEFAULT_NODE_ACCESS_SCOPE,
 } from '@cloudbase/oauth'
@@ -416,7 +417,20 @@ class Auth extends AuthV1Compat {
       // loginState返回是为了兼容v2版本
       return { ...(loginState as any), data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      const authError = new AuthError(error, { method: 'signInAnonymously' })
+      // 匿名登录失败时提供明确指引
+      if (authError.category === AuthErrorCategory.PROVIDER_NOT_ENABLED) {
+        console.error(authError.helpMessage)
+        console.error('[CloudBase Auth] 提示：匿名登录需要在控制台开启「匿名登录」。\n'
+          + '  如果您需要使用用户名密码登录，请改用 auth.signInWithPassword({ username, password })。\n'
+          + '  不要在匿名登录失败后自动回退到密码登录，这两种方式的使用场景不同。',)
+      } else {
+        console.warn(`[CloudBase Auth] signInAnonymously 失败 [${authError.category}]: ${authError.message}`)
+        if (authError.loginMethodHint) {
+          console.warn(authError.loginMethodHint)
+        }
+      }
+      return { data: {}, error: authError }
     }
   }
 
@@ -476,14 +490,14 @@ class Auth extends AuthV1Compat {
 
               return { data: { user: session.user, session }, error: null }
             } catch (error) {
-              return { data: {}, error: new AuthError(error) }
+              return { data: {}, error: new AuthError(error, { method: 'signUp' }) }
             }
           },
         },
         error: null,
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signUp' }) }
     }
   }
 
@@ -507,7 +521,7 @@ class Auth extends AuthV1Compat {
       // res返回是为了兼容v2版本
       return { ...res, data: {}, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signOut' }) }
     }
   }
 
@@ -578,14 +592,19 @@ class Auth extends AuthV1Compat {
 
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      const authError = new AuthError(error)
-      // 优化错误提示：登录失败时提供更友好的排查指引
-      if (authError.message?.includes('密码不正确') || authError.message?.includes('password')) {
-        console.warn('[CloudBase Auth] 登录失败提示：\n'
-          + '  1. 请确认用户名/邮箱/手机号是否正确\n'
-          + '  2. 请确认密码是否正确\n'
-          + '  3. 如果用户不存在，请先通过 auth.signUp() 注册用户，或在云开发控制台手动创建用户\n'
-          + '  4. 确认当前环境已开启对应的登录方式（控制台 → 环境 → 登录授权）',)
+      const authError = new AuthError(error, { method: 'signInWithPassword' })
+      // 根据错误分类输出对应的可操作性指引
+      if (authError.category === AuthErrorCategory.PROVIDER_NOT_ENABLED) {
+        console.error(authError.helpMessage)
+      } else if (authError.category === AuthErrorCategory.INVALID_CREDENTIALS) {
+        console.warn(authError.helpMessage)
+      } else if (authError.category === AuthErrorCategory.USER_NOT_FOUND) {
+        console.warn(authError.helpMessage)
+      } else {
+        console.warn(`[CloudBase Auth] signInWithPassword 失败 [${authError.category}]: ${authError.message}`)
+      }
+      if (authError.loginMethodHint) {
+        console.info(authError.loginMethodHint)
       }
       return { data: {}, error: authError }
     }
@@ -611,7 +630,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithIdToken' }) }
     }
   }
 
@@ -622,7 +641,7 @@ class Auth extends AuthV1Compat {
    * @returns Promise<SignInWithOtpRes>
    */
   async signInWithOtp(params: SignInWithOtpReq): Promise<SignInWithOtpRes> {
-    if (params.options?.shouldCreateUser === undefined || !!params.options?.shouldCreateUser) {
+    if (!params.options?.emailRedirectTo && (params.options?.shouldCreateUser === undefined || !!params.options?.shouldCreateUser)) {
       return this.signUp({
         email: params.email,
         phone: params.phone,
@@ -634,7 +653,10 @@ class Auth extends AuthV1Compat {
       this.validateAtLeastOne(params, [['email'], ['phone']], 'You must provide either an email or phone number')
 
       // 第一步：发送验证码并存储 verificationInfo
-      const verificationInfo = await this.getVerification(params.email ? { email: params.email } : { phone_number: this.formatPhone(params.phone) },)
+      const verificationInfo = await this.getVerification({
+        email_redirect_to: params.options?.emailRedirectTo,
+        ...(params.email ? { email: params.email } : { phone_number: this.formatPhone(params.phone) }),
+      })
 
       return {
         data: {
@@ -651,7 +673,7 @@ class Auth extends AuthV1Compat {
         error: null,
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithOtp' }) }
     }
   }
 
@@ -715,7 +737,7 @@ class Auth extends AuthV1Compat {
 
       return res
     } catch (error) {
-      return { data, error: new AuthError(error) }
+      return { data, error: new AuthError(error, { method: 'verifyOAuth' }) }
     }
   }
 
@@ -774,7 +796,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { url: finalUri, provider: params.provider }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithOAuth' }) }
     }
   }
 
@@ -785,7 +807,7 @@ class Auth extends AuthV1Compat {
       const parsedToken = weAppJwtDecodeAll(accessToken)
       return { data: parsedToken, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'getClaims' }) }
     }
   }
 
@@ -863,14 +885,14 @@ class Auth extends AuthV1Compat {
 
               return res
             } catch (error) {
-              return { data: {}, error: new AuthError(error) }
+              return { data: {}, error: new AuthError(error, { method: 'resetPasswordForEmail' }) }
             }
           },
         },
         error: null,
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'resetPasswordForEmail' }) }
     }
   }
 
@@ -891,7 +913,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'resetPasswordForOld' }) }
     }
   }
 
@@ -928,7 +950,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'verifyOtp' }) }
     }
   }
 
@@ -949,7 +971,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { session: { ...credentials, user }, user }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'getSession' }) }
     }
   }
 
@@ -968,7 +990,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user, session: { ...newTokens, user } }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'refreshSession' }) }
     }
   }
 
@@ -982,7 +1004,7 @@ class Auth extends AuthV1Compat {
       const user = this.convertToUser(await this.getCurrentUser())
       return { data: { user }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'getUser' }) }
     }
   }
 
@@ -997,7 +1019,7 @@ class Auth extends AuthV1Compat {
       const { data: { session } = {} } = await this.getSession()
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'refreshUser' }) }
     }
   }
 
@@ -1084,7 +1106,7 @@ class Auth extends AuthV1Compat {
 
               return { data: { user }, error: null }
             } catch (error) {
-              return { data: {}, error: new AuthError(error) }
+              return { data: {}, error: new AuthError(error, { method: 'updateUser' }) }
             }
           },
         }
@@ -1099,7 +1121,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user, ...extraRes }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'updateUser' }) }
     }
   }
 
@@ -1119,7 +1141,7 @@ class Auth extends AuthV1Compat {
         error: null,
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'getUserIdentities' }) }
     }
   }
 
@@ -1145,7 +1167,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { provider: params.provider }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'linkIdentity' }) }
     }
   }
 
@@ -1166,7 +1188,7 @@ class Auth extends AuthV1Compat {
 
       return { data: {}, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'unlinkIdentity' }) }
     }
   }
 
@@ -1224,14 +1246,14 @@ class Auth extends AuthV1Compat {
 
               return { data: { user: session.user, session }, error: null }
             } catch (error) {
-              return { data: {}, error: new AuthError(error) }
+              return { data: {}, error: new AuthError(error, { method: 'reauthenticate' }) }
             }
           },
         },
         error: null,
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'reauthenticate' }) }
     }
   }
 
@@ -1266,7 +1288,7 @@ class Auth extends AuthV1Compat {
     } catch (error: any) {
       return {
         data: {},
-        error: new AuthError(error),
+        error: new AuthError(error, { method: 'resend' }),
       }
     }
   }
@@ -1292,7 +1314,7 @@ class Auth extends AuthV1Compat {
 
       return { data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'setSession' }) }
     }
   }
 
@@ -1318,7 +1340,7 @@ class Auth extends AuthV1Compat {
 
       return { data: {}, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'deleteUser' }) }
     }
   }
 
@@ -1346,7 +1368,7 @@ class Auth extends AuthV1Compat {
       }
       return { data: {}, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'toDefaultLoginPage' }) }
     }
   }
 
@@ -1369,7 +1391,7 @@ class Auth extends AuthV1Compat {
       // loginState返回是为了兼容v2版本
       return { ...(loginState as any), data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithCustomTicket' }) }
     }
   }
 
@@ -1445,7 +1467,7 @@ class Auth extends AuthV1Compat {
       // loginState返回是为了兼容v2版本
       return { ...(loginState as any), data: { user: session.user, session }, error: null }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithOpenId' }) }
     }
   }
 
@@ -1481,7 +1503,7 @@ class Auth extends AuthV1Compat {
         throw signInRes
       }
     } catch (error) {
-      return { data: {}, error: new AuthError(error) }
+      return { data: {}, error: new AuthError(error, { method: 'signInWithPhoneAuth' }) }
     }
 
     const loginState = await this.createLoginState()
@@ -2773,6 +2795,8 @@ try {
 } catch (e) {}
 
 export { UserInfo, Auth, WeixinAuthProvider, CustomAuthProvider, AnonymousAuthProvider }
+// 导出错误分类枚举和 AuthError，方便开发者进行错误分类处理
+export { AuthErrorCategory, AuthError } from '@cloudbase/oauth'
 /**
  * @api 手动注册至cloudbase app
  */

package/src/type.ts

@@ -1,7 +1,22 @@
 import type { authModels, OAUTH_TYPE } from '@cloudbase/oauth'
-import { AuthError } from '@cloudbase/oauth'
+import { AuthError, AuthErrorCategory } from '@cloudbase/oauth'
 
+export { AuthErrorCategory }
 
+
+/**
+ * signInAnonymously 请求参数
+ *
+ * **前置条件**：使用此方法前，请确保已在云开发控制台（环境 → 登录授权 → 身份源列表）开启「匿名登录」。
+ *
+ * **使用场景**：
+ * - 无需用户注册即可使用应用功能
+ * - 临时访问或快速体验场景
+ * - 测试/自动化环境中不需要真实用户凭据时
+ *
+ * **注意**：匿名登录与密码登录是两种独立的登录方式，不要在匿名登录失败后自动回退到密码登录。
+ * 如果匿名登录返回 PROVIDER_NOT_ENABLED 错误，说明需要在控制台开启匿名登录功能。
+ */
 export interface SignInAnonymouslyReq {
   provider_token?: string // 提供令牌
 }
@@ -48,6 +63,24 @@ export declare type Session = {
   user: User // 用户信息
 }
 
+/**
+ * signInWithPassword 请求参数
+ *
+ * **重要提示**：使用此方法前，请确保已在云开发控制台（环境 → 登录授权 → 身份源列表）
+ * 开启「用户名密码登录」方式。如未开启，登录时会返回 AuthErrorCategory.PROVIDER_NOT_ENABLED 错误。
+ *
+ * **凭据来源**：
+ * - 用户手动输入（交互式场景）
+ * - 环境变量 ENV_ID / USER_NAME / PASSWORD（自动化/agent 场景）
+ * - 请确保凭据对应的用户已在目标 envId 环境中注册
+ *
+ * **常见错误**：
+ * - `invalid_username_or_password`：用户名或密码错误，请核实凭据
+ * - `PROVIDER_NOT_ENABLED`：用户名密码登录未开启，需在控制台配置
+ * - `not_found`：用户不存在，需先注册
+ *
+ * **注意**：不同云开发环境的用户库是隔离的，请确认 envId 与凭据匹配。
+ */
 export interface SignInWithPasswordReq {
   username?: string // 用户名称（可选，与邮箱、手机号三选一），长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文
   email?: string // 邮箱（可选，与用户名、手机号三选一）
@@ -62,6 +95,35 @@ export interface CommonRes {
   error: AuthError | null // 错误信息，成功时为null
 }
 
+/**
+ * 登录操作响应类型
+ *
+ * 当 error 不为 null 时，error 对象包含：
+ * - `category`: 错误分类（AuthErrorCategory 枚举），可用于程序化判断错误类型
+ * - `helpMessage`: 可操作性指引信息，包含排查步骤和解决方案
+ * - `loginMethodHint`: 登录方式选择建议，帮助选择正确的登录方法
+ * - `code`: 服务端返回的错误码（如 'invalid_username_or_password'、'invalid_password'）
+ * - `message`: 错误描述
+ *
+ * 示例：
+ * ```typescript
+ * const { data, error } = await auth.signInWithPassword({ username: 'test', password: '123' })
+ * if (error) {
+ *   if (error.category === AuthErrorCategory.PROVIDER_NOT_ENABLED) {
+ *     // 身份源未开启，引导用户或管理员开启
+ *     console.log(error.helpMessage)
+ *   } else if (error.category === AuthErrorCategory.INVALID_CREDENTIALS) {
+ *     // 凭据错误（包括 invalid_username_or_password），提示用户检查密码
+ *     console.log(error.helpMessage)
+ *   }
+ * }
+ * ```
+ *
+ * **agent/自动化场景注意**：
+ * - 不要在 signInAnonymously() 失败后自动回退到 signInWithPassword()
+ * - 两种登录方式的适用场景不同，应根据任务需求明确选择
+ * - 使用 error.loginMethodHint 获取当前登录方式的使用建议
+ */
 export interface SignInRes {
   data: {
     user?: User // 用户信息
@@ -229,6 +291,7 @@ export interface SignInWithOtpReq {
   phone?: string // 手机号（可选，与邮箱二选一）
   options?: {
     shouldCreateUser?: boolean // 如果用户不存在是否创建用户，默认为true
+    emailRedirectTo?: string // 邮箱登录回调地址，填写后则会发送认证链接至邮箱，否则发送验证码
   }
 }