@tbox-claw/bridge-sdk 1.0.0 → 1.0.1

package/README.md

@@ -95,6 +95,12 @@ interface BridgeResponse<T = unknown> {
 |-----|------|:--------------:|
 | [`getGatewayStatus()`](./docs/api/getGatewayStatus.md) | 查询 Gateway 运行状态，判断对话类 API 是否可用 | `1.2.1` |
 
+### 自定义登录
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:-------:|
+| [`loginSuccess(params)`](./docs/api/loginSuccess.md) | 三方登录页面调用，将 OAuth 授权码传给桌面端完成登录 | `1.2.5` |
+
 ---
 
 ## 工具函数
@@ -184,13 +190,14 @@ const user = await bridge.getUserInfo(); // 完整类型推导
 import type {
   TboxClawBridge,            // Bridge 接口定义
   BridgeResponse,            // { ok, data?, error? }
-  UserInfo,                  // { userId, name, avatar }
+  UserInfo,                  // { userId, name, avatar, loginType?, extra? }
   ClientInfo,                // { platform, osVersion, clientVersion }
   SendNotificationOptions,   // { title, body, silent? }
   SendChatMessageOptions,    // { message, sessionKey? }
   GetChatHistoryOptions,     // { sessionKey?, limit? }
   ChatMessage,               // { role, content, timestamp?, id? }
   GatewayStatusInfo,         // { state, ready }
+  LoginSuccessParams,        // { authCode }
 } from '@tbox-claw/bridge-sdk';
 ```
 

package/dist/index.d.mts

@@ -64,6 +64,11 @@ interface ChatMessage {
     /** Message unique identifier */
     id?: string;
 }
+/** Parameters for loginSuccess — third-party login page provides the OAuth auth code */
+interface LoginSuccessParams {
+    /** OAuth authorization code obtained from the SSO provider (e.g. Alipay auth_code) */
+    authCode: string;
+}
 /** Gateway runtime status */
 interface GatewayStatusInfo {
     /** Current lifecycle state */
@@ -87,6 +92,15 @@ interface TboxClawBridge {
     getChatHistory(options?: GetChatHistoryOptions): Promise<BridgeResponse<ChatMessage[]>>;
     /** Check whether the Gateway is running and ready */
     getGatewayStatus(): Promise<BridgeResponse<GatewayStatusInfo>>;
+    /**
+     * Notify the desktop app that login has completed successfully.
+     * Call this after the third-party OAuth flow finishes with the obtained auth code.
+     * The desktop app will exchange the auth code for a session via the backend oauth/login API.
+     * Returns user info on success.
+     *
+     * @param params - Must include the OAuth authorization code (authCode)
+     */
+    loginSuccess(params: LoginSuccessParams): Promise<BridgeResponse<UserInfo>>;
 }
 
 /** Check if currently running inside TboxClaw embedded environment */
@@ -99,4 +113,4 @@ declare function getBridge(): TboxClawBridge;
  */
 declare function safeBridgeCall<T>(apiFn: (bridge: TboxClawBridge) => Promise<T>, fallback: T): Promise<T>;
 
-export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };
+export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type LoginSuccessParams, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };

package/dist/index.d.ts

@@ -64,6 +64,11 @@ interface ChatMessage {
     /** Message unique identifier */
     id?: string;
 }
+/** Parameters for loginSuccess — third-party login page provides the OAuth auth code */
+interface LoginSuccessParams {
+    /** OAuth authorization code obtained from the SSO provider (e.g. Alipay auth_code) */
+    authCode: string;
+}
 /** Gateway runtime status */
 interface GatewayStatusInfo {
     /** Current lifecycle state */
@@ -87,6 +92,15 @@ interface TboxClawBridge {
     getChatHistory(options?: GetChatHistoryOptions): Promise<BridgeResponse<ChatMessage[]>>;
     /** Check whether the Gateway is running and ready */
     getGatewayStatus(): Promise<BridgeResponse<GatewayStatusInfo>>;
+    /**
+     * Notify the desktop app that login has completed successfully.
+     * Call this after the third-party OAuth flow finishes with the obtained auth code.
+     * The desktop app will exchange the auth code for a session via the backend oauth/login API.
+     * Returns user info on success.
+     *
+     * @param params - Must include the OAuth authorization code (authCode)
+     */
+    loginSuccess(params: LoginSuccessParams): Promise<BridgeResponse<UserInfo>>;
 }
 
 /** Check if currently running inside TboxClaw embedded environment */
@@ -99,4 +113,4 @@ declare function getBridge(): TboxClawBridge;
  */
 declare function safeBridgeCall<T>(apiFn: (bridge: TboxClawBridge) => Promise<T>, fallback: T): Promise<T>;
 
-export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };
+export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type LoginSuccessParams, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };

package/docs/api/loginSuccess.md

@@ -0,0 +1,151 @@
+## loginSuccess(params)
+
+通知桌面端第三方 OAuth 登录已完成。三方登录页面在完成 SSO 授权后，将获取到的 `authCode` 传入此 API，桌面端会自动用该授权码换取会话并完成登录。
+
+| 属性 | 值                                             |
+|------|-----------------------------------------------|
+| **最小客户端版本** | `1.2.5`                                       |
+| **分类** | 自定义登录                                         |
+| **需要权限** | `loginSuccess` 需在页面 `bridge.allowedApis` 白名单中 |
+| **适用场景** | 仅限 `WebContentsView` 模式的自定义登录页面               |
+
+---
+
+### 签名
+
+```typescript
+loginSuccess(params: LoginSuccessParams): Promise<BridgeResponse<UserInfo>>
+```
+
+### 参数
+
+**`LoginSuccessParams` 类型定义**：
+
+```typescript
+interface LoginSuccessParams {
+  /** OAuth 授权码，由 SSO 提供方返回（如支付宝的 auth_code） */
+  authCode: string;
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `authCode` | `string` | ✅ | SSO 授权码 |
+
+### 返回值
+
+`Promise<BridgeResponse<UserInfo>>`
+
+登录成功后返回用户信息。
+
+**`UserInfo` 类型定义**：
+
+```typescript
+interface UserInfo {
+  /** 用户 ID */
+  userId: string;
+  /** 用户昵称 */
+  name: string;
+  /** 头像 URL */
+  avatar: string;
+  /** 登录渠道（如 'tuma'、'alipay'） */
+  loginType?: string;
+  /** 服务端扩展信息 */
+  extra?: Record<string, unknown>;
+}
+```
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+
+// 假设已从 SSO 回调中获取到 authCode
+const authCode = 'abc123def456';
+
+const result = await bridge.loginSuccess({ authCode });
+
+if (result.ok) {
+  console.log('登录成功！');
+  console.log('用户：', result.data.name);
+  console.log('头像：', result.data.avatar);
+} else {
+  console.error('登录失败：', result.error);
+}
+```
+
+### 典型用法（WebContentsView 自定义登录页面）
+
+```html
+<script>
+  // 在 SSO 重定向回来后，从 URL 中提取 auth_code
+  const params = new URLSearchParams(window.location.search);
+  const authCode = params.get('auth_code');
+
+  if (authCode && window.tboxClawBridge) {
+    window.tboxClawBridge.loginSuccess({ authCode })
+      .then(result => {
+        if (result.ok) {
+          // 登录成功，桌面端会自动关闭登录页面并跳转到主界面
+          console.log('登录成功', result.data);
+        } else {
+          alert('登录失败: ' + result.error);
+        }
+      });
+  }
+</script>
+```
+
+### 流程说明
+
+1. 桌面端打开自定义登录页面（WebContentsView 模式）
+2. 用户在登录页面完成 SSO 授权，页面获取到 `authCode`
+3. 登录页面调用 `tboxClawBridge.loginSuccess({ authCode })`
+4. 桌面端在后台执行：
+   - 用 `authCode` 调用后端 OAuth 接口换取 session
+   - 验证 session 有效性
+   - 持久化登录状态
+5. 返回用户信息，桌面端自动关闭登录页面
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `authCode is required` | 未提供 `authCode` 参数 |
+| `OAuth login failed: ...` | 授权码换取 session 失败（码无效或已过期） |
+| `Session verification failed: ...` | session 验证失败 |
+| `API "loginSuccess" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "userId": "12345",
+    "name": "张三",
+    "avatar": "https://example.com/avatar.png",
+    "loginType": "tuma",
+    "extra": {}
+  }
+}
+```
+
+**失败（授权码无效）**：
+
+```json
+{
+  "ok": false,
+  "error": "OAuth login failed: invalid auth code"
+}
+```
+
+### 注意事项
+
+- 此 API **仅在 `WebContentsView` 模式的自定义登录页面中可用**。`webview` 模式的登录页面通过 URL 重定向拦截自动提取 authCode，不需要调用此 API。
+- 登录成功后，桌面端会自动关闭登录视图，无需登录页面手动处理。
+- 每个 `authCode` 只能使用一次，重复调用会返回错误。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox-claw/bridge-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Bridge SDK for developing embedded pages in TboxClaw desktop app",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",