@55387.ai/uniauth-client 1.2.2 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +89 -160
  2. package/package.json +2 -3
  3. package/INTEGRATION.md +0 -1273
package/README.md CHANGED
@@ -1,16 +1,20 @@
1
1
  # @55387.ai/uniauth-client
2
2
 
3
- UniAuth 前端 SDK，支持手机、邮箱、社交登录和跨域 SSO。
3
+ > UniAuth Frontend SDK — Phone, Email, Social & SSO login for browser apps.
4
+ >
5
+ > UniAuth 前端 SDK — 支持手机、邮箱、社交登录和跨域 SSO。
6
+
7
+ **Version / 版本:** 1.2.2
4
8
 
5
- ## 安装
9
+ ## Install / 安装
6
10
 
7
11
  ```bash
8
12
  npm install @55387.ai/uniauth-client
9
- # or
13
+ # or / 或
10
14
  pnpm add @55387.ai/uniauth-client
11
15
  ```
12
16
 
13
- ## 快速开始
17
+ ## Quick Start / 快速开始
14
18
 
15
19
  ```typescript
16
20
  import { UniAuthClient } from '@55387.ai/uniauth-client';
@@ -19,200 +23,130 @@ const auth = new UniAuthClient({
19
23
  baseUrl: 'https://sso.55387.xyz',
20
24
  });
21
25
 
22
- // 发送验证码
26
+ // Phone login / 手机登录
23
27
  await auth.sendCode('+8613800138000');
24
-
25
- // 验证码登录
26
28
  const result = await auth.loginWithCode('+8613800138000', '123456');
27
29
 
28
- // 检查登录状态
30
+ // Email login / 邮箱登录
31
+ const result = await auth.loginWithEmail('user@example.com', 'password');
32
+
33
+ // Check auth / 检查状态
29
34
  if (auth.isAuthenticated()) {
30
35
  const user = await auth.getCurrentUser();
31
- console.log('已登录:', user);
32
36
  }
33
37
  ```
34
38
 
35
- ## SSO 跨域登录
39
+ ## Login Methods / 登录方式
36
40
 
37
- ### 配置
41
+ ### 📱 Phone / 手机号
38
42
 
39
43
  ```typescript
40
- auth.configureSso({
41
- ssoUrl: 'https://sso.55387.xyz',
42
- clientId: 'ua_xxxxxxxxxxxx',
43
- redirectUri: window.location.origin + '/callback',
44
- scope: 'openid profile email phone', // 可选，默认 'openid profile email'
45
- });
44
+ await auth.sendCode('+8613800138000');
45
+ const result = await auth.loginWithCode('+8613800138000', '123456');
46
46
  ```
47
47
 
48
- ### 触发登录
48
+ ### 📧 Email / 邮箱
49
49
 
50
50
  ```typescript
51
- // 基础用法
52
- auth.loginWithSSO();
51
+ // Password / 密码登录
52
+ await auth.loginWithEmail('user@example.com', 'password');
53
53
 
54
- // 使用 PKCE（需要 SSO 服务端支持）
55
- auth.loginWithSSO({ usePKCE: true });
56
- ```
54
+ // Passwordless / 无密码
55
+ await auth.sendEmailCode('user@example.com');
56
+ await auth.loginWithEmailCode('user@example.com', '123456');
57
57
 
58
- ### 处理回调
58
+ // Register / 注册
59
+ await auth.registerWithEmail('user@example.com', 'password', 'Nickname');
60
+ ```
59
61
 
60
- 在回调页面（如 `/callback`）处理 SSO 响应：
62
+ ### 🌐 Social Login / 社交登录
61
63
 
62
64
  ```typescript
63
- // React 示例
64
- function Callback() {
65
- useEffect(() => {
66
- const handleCallback = async () => {
67
- if (auth.isSSOCallback()) {
68
- try {
69
- const result = await auth.handleSSOCallback();
70
- if (result) {
71
- // 保存 Token
72
- localStorage.setItem('access_token', result.access_token);
73
- if (result.refresh_token) {
74
- localStorage.setItem('refresh_token', result.refresh_token);
75
- }
76
- window.location.href = '/';
77
- }
78
- } catch (error) {
79
- console.error('SSO callback error:', error);
80
- }
81
- }
82
- };
83
- handleCallback();
84
- }, []);
85
-
86
- return <div>登录中...</div>;
87
- }
65
+ const providers = await auth.getOAuthProviders(); // ['google', 'github', 'wechat']
66
+ auth.startSocialLogin('google');
88
67
  ```
89
68
 
90
- ### 返回值
91
-
92
- `handleSSOCallback()` 成功时返回：
69
+ ### 🔐 SSO / 单点登录
93
70
 
94
71
  ```typescript
95
- interface SSOResult {
96
- access_token: string; // 访问令牌
97
- refresh_token?: string; // 刷新令牌（可选）
98
- expires_in?: number; // 过期时间（秒）
99
- token_type: string; // 令牌类型，通常为 "Bearer"
100
- id_token?: string; // OpenID Connect ID Token
72
+ // Configure / 配置
73
+ auth.configureSso({
74
+ ssoUrl: 'https://sso.55387.xyz',
75
+ clientId: 'ua_xxxxxxxxxxxx',
76
+ redirectUri: window.location.origin + '/callback',
77
+ scope: 'openid profile email phone',
78
+ });
79
+
80
+ // Login / 登录
81
+ auth.loginWithSSO(); // Basic
82
+ auth.loginWithSSO({ usePKCE: true }); // Recommended for SPAs
83
+
84
+ // Callback page / 回调页处理
85
+ if (auth.isSSOCallback()) {
86
+ const result = await auth.handleSSOCallback();
87
+ // result: { access_token, refresh_token?, token_type, id_token? }
101
88
  }
102
89
  ```
103
90
 
104
- ### 注意事项
105
-
106
- > **重要**：如果应用配置为 **Confidential Client**（机密客户端），前端 SDK 直接调用 Token 端点会因缺少 `client_secret` 而失败。
91
+ > ⚠️ **Confidential Clients** must exchange tokens on the backend. See [AI Integration Guide](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client).
107
92
  >
108
- > 此时需要使用后端代理登录流程，参考 [SSO 集成指南](https://github.com/55387/uniauth/blob/main/docs/SSO_INTEGRATION_GUIDE.md)。
109
-
110
- ### SSO API 端点
111
-
112
- | 端点 | URL |
113
- |------|-----|
114
- | 授权端点 | `https://sso.55387.xyz/api/v1/oauth2/authorize` |
115
- | Token 端点 | `https://sso.55387.xyz/api/v1/oauth2/token` |
116
- | 用户信息端点 | `https://sso.55387.xyz/api/v1/oauth2/userinfo` |
93
+ > ⚠️ **机密客户端** 需在后端完成 Token 交换，参见 [集成指南](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client)。
117
94
 
118
-
119
- ## MFA 多因素认证
95
+ ### 🔑 MFA / 多因素认证
120
96
 
121
97
  ```typescript
122
98
  const result = await auth.loginWithCode(phone, code);
123
-
124
99
  if (result.mfa_required) {
125
- const mfaCode = prompt('请输入验证器应用中的验证码:');
126
- const finalResult = await auth.verifyMFA(result.mfa_token!, mfaCode);
100
+ await auth.verifyMFA(result.mfa_token!, '123456');
127
101
  }
128
102
  ```
129
103
 
130
- ## 社交登录
131
-
132
- ```typescript
133
- // 获取可用的 OAuth 提供商
134
- const providers = await auth.getOAuthProviders();
135
-
136
- // 发起社交登录
137
- auth.startSocialLogin('google');
138
- ```
139
-
140
- ## 认证状态监听
141
-
142
- ```typescript
143
- const unsubscribe = auth.onAuthStateChange((user, isAuthenticated) => {
144
- if (isAuthenticated) {
145
- console.log('用户已登录:', user);
146
- } else {
147
- console.log('用户已登出');
148
- }
149
- });
150
-
151
- // 取消监听
152
- unsubscribe();
153
- ```
154
-
155
- ## API 参考
104
+ ## API Reference / API 参考
156
105
 
157
- ### 初始化选项
106
+ ### Config / 配置
158
107
 
159
108
  ```typescript
160
109
  interface UniAuthConfig {
161
- baseUrl: string; // API 地址
162
- appKey?: string; // 应用密钥
163
- clientId?: string; // OAuth 客户端 ID
110
+ baseUrl: string; // API base URL
111
+ appKey?: string; // App key (optional)
112
+ clientId?: string; // OAuth client ID
164
113
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
165
114
  onTokenRefresh?: (tokens) => void;
166
115
  onAuthError?: (error) => void;
167
- enableRetry?: boolean; // 启用重试 (默认 true)
168
- timeout?: number; // 请求超时 (默认 30000ms)
116
+ enableRetry?: boolean; // Default: true
117
+ timeout?: number; // Default: 30000
169
118
  }
170
119
  ```
171
120
 
172
- ### 核心方法
173
-
174
- | 方法 | 说明 |
175
- |------|------|
176
- | `sendCode(phone, type?)` | 发送手机验证码 |
177
- | `sendEmailCode(email, type?)` | 发送邮箱验证码 |
178
- | `loginWithCode(phone, code)` | 手机验证码登录 |
179
- | `loginWithEmailCode(email, code)` | 邮箱验证码登录 |
180
- | `loginWithEmail(email, password)` | 邮箱密码登录 |
181
- | `registerWithEmail(email, password, nickname?)` | 邮箱注册 |
182
- | `verifyMFA(mfaToken, code)` | MFA 验证 |
183
- | `getCurrentUser()` | 获取当前用户 |
184
- | `updateProfile(updates)` | 更新用户资料 |
185
- | `logout()` | 登出 |
186
- | `logoutAll()` | 全设备登出 |
187
-
188
- ### SSO 方法
189
-
190
- | 方法 | 说明 |
191
- |------|------|
192
- | `configureSso(config)` | 配置 SSO |
193
- | `loginWithSSO(options?)` | 发起 SSO 登录 |
194
- | `isSSOCallback()` | 检测是否为 SSO 回调 |
195
- | `handleSSOCallback()` | 处理 SSO 回调 |
196
-
197
- ### 社交登录方法
198
-
199
- | 方法 | 说明 |
200
- |------|------|
201
- | `getOAuthProviders()` | 获取 OAuth 提供商列表 |
202
- | `startSocialLogin(provider, redirectUri?)` | 发起社交登录 |
203
-
204
- ### 状态方法
205
-
206
- | 方法 | 说明 |
207
- |------|------|
208
- | `isAuthenticated()` | 检查是否已登录 |
209
- | `isTokenValid()` | 检查 Token 是否有效 |
210
- | `getAccessToken()` | 获取 Token (异步，自动刷新) |
211
- | `getAccessTokenSync()` | 获取 Token (同步) |
212
- | `getCachedUser()` | 获取缓存的用户信息 |
213
- | `onAuthStateChange(callback)` | 监听认证状态变更 |
214
-
215
- ## 错误处理
121
+ ### Methods / 方法
122
+
123
+ | Method | Description / 说明 |
124
+ |--------|-----------|
125
+ | `sendCode(phone, type?)` | Send SMS code / 发送短信验证码 |
126
+ | `sendEmailCode(email, type?)` | Send email code / 发送邮箱验证码 |
127
+ | `loginWithCode(phone, code)` | Phone code login / 手机验证码登录 |
128
+ | `loginWithEmailCode(email, code)` | Email code login / 邮箱验证码登录 |
129
+ | `loginWithEmail(email, password)` | Email password login / 邮箱密码登录 |
130
+ | `registerWithEmail(email, password, nickname?)` | Email register / 邮箱注册 |
131
+ | `verifyMFA(mfaToken, code)` | MFA verification / MFA 验证 |
132
+ | `getCurrentUser()` | Get current user / 获取当前用户 |
133
+ | `updateProfile(updates)` | Update profile / 更新资料 |
134
+ | `isAuthenticated()` | Check login status / 检查登录状态 |
135
+ | `isTokenValid()` | Check token validity / 检查令牌有效性 |
136
+ | `getAccessToken()` | Get token (auto-refresh) / 获取令牌(自动刷新) |
137
+ | `getAccessTokenSync()` | Get token (sync) / 获取令牌(同步) |
138
+ | `getCachedUser()` | Get cached user / 获取缓存用户 |
139
+ | `onAuthStateChange(cb)` | Auth state listener / 认证状态监听 |
140
+ | `logout()` | Logout / 登出 |
141
+ | `logoutAll()` | Logout all devices / 全设备登出 |
142
+ | `configureSso(config)` | Configure SSO / 配置 SSO |
143
+ | `loginWithSSO(options?)` | Start SSO login / 发起 SSO 登录 |
144
+ | `isSSOCallback()` | Detect SSO callback / 检测 SSO 回调 |
145
+ | `handleSSOCallback()` | Handle SSO callback / 处理 SSO 回调 |
146
+ | `getOAuthProviders()` | List OAuth providers / 获取 OAuth 提供商 |
147
+ | `startSocialLogin(provider)` | Start social login / 发起社交登录 |
148
+
149
+ ## Error Handling / 错误处理
216
150
 
217
151
  ```typescript
218
152
  import { UniAuthError, AuthErrorCode } from '@55387.ai/uniauth-client';
@@ -222,14 +156,9 @@ try {
222
156
  } catch (error) {
223
157
  if (error instanceof UniAuthError) {
224
158
  switch (error.code) {
225
- case AuthErrorCode.MFA_REQUIRED:
226
- // 需要 MFA 验证
227
- break;
228
- case AuthErrorCode.VERIFY_FAILED:
229
- // 验证码错误
230
- break;
231
- default:
232
- console.error(error.message);
159
+ case AuthErrorCode.MFA_REQUIRED: // Need MFA / 需要 MFA
160
+ case AuthErrorCode.VERIFY_FAILED: // Wrong code / 验证码错误
161
+ case AuthErrorCode.RATE_LIMITED: // Rate limited / 频率限制
233
162
  }
234
163
  }
235
164
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@55387.ai/uniauth-client",
3
- "version": "1.2.2",
3
+ "version": "1.2.3",
4
4
  "description": "UniAuth Frontend SDK - Phone, Email, SSO login for browser",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -8,8 +8,7 @@
8
8
  "types": "./dist/index.d.ts",
9
9
  "files": [
10
10
  "dist",
11
- "README.md",
12
- "INTEGRATION.md"
11
+ "README.md"
13
12
  ],
14
13
  "exports": {
15
14
  ".": {