ibc-ai-web-sdk 2.1.1 → 2.1.2

package/README.md

@@ -84,39 +84,75 @@ AIWebSDK.create({
 | `headers` | object | `{}` | | 附加请求头 |
 | `extendInfo` | object | `{}` | | 随请求发送的扩展信息 |
 
-### Token 刷新
+### Token 管理
 
-提供 `refreshTokenFn` 即可，SDK 会自动处理过期检测和刷新。
+SDK 的 Token 生命周期**应与应用层保持一致**，建议应用层为 SDK 签发的 Token TTL 与自身登录态 TTL 相同。
+
+#### 正常刷新
+
+提供 `refreshTokenFn`，SDK 会在 Token 即将过期时自动刷新（默认提前 60 秒）。
 
 ```js
 createAIChatDialog({
-  token: 'initial-access-token',
-  tokenExpiresAt: Date.now() + 30 * 60 * 1000,  // Token 过期时间戳
-  refreshToken: 'initial-refresh-token',          // 可选
+  token: 'st-xxxx',                             // 由应用后端调 /v1/token/create 签发
+  tokenExpiresAt: Date.now() + 7200 * 1000,     // SDK Token 过期时间戳（毫秒），建议与用户登录态一致
+  refreshToken: 'initial-refresh-token',         // 可选：服务端刷新凭证
 
   refreshTokenFn: async ({ token, refreshToken, userId }) => {
-    const res = await fetch('/api/auth/refresh', {
+    // 调自己的后端接口，后端用 API-Key 调 /v1/token/create 拿新 st- Token
+    const res = await fetch('/api/auth/refresh-sdk-token', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ token, refreshToken, userId })
+      body: JSON.stringify({ userId })
     });
     const data = await res.json();
     return {
-      token: data.accessToken,
+      token: data.token,
       expiresAt: data.expiresAt * 1000
     };
   }
 });
 ```
 
+#### Token 彻底失效
+
+当 Token 过期且刷新失败（如刷新接口返回 401），或未配置 `refreshTokenFn` 时，SDK 会触发 `onAuthExpired` 回调。**应用层应在此回调中引导用户重新登录。**
+
+```js
+createAIChatDialog({
+  token: 'st-xxxx',
+  tokenExpiresAt: Date.now() + 7200 * 1000,
+
+  onAuthExpired: ({ reason, message }) => {
+    console.log('SDK Token 已失效:', reason, message);
+    dialog.destroy();        // 销毁 SDK 实例
+    router.push('/login');   // 引导用户重新登录
+  }
+});
+
+// 登录成功后：重新拿 Token，重新初始化 SDK
+async function afterLogin(userId) {
+  // 1. 调后端通过 API-Key 签新 st- Token
+  const { token, expiresAt } = await fetchNewSdkToken(userId);
+  // 2. 重新初始化 SDK
+  dialog = createAIChatDialog({
+    token,
+    tokenExpiresAt: expiresAt * 1000,
+    onAuthExpired: () => { /* 同上 */ }
+  });
+}
+```
+
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `token` | string | 认证 Token |
-| `tokenExpiresAt` | number | Token 过期时间戳（毫秒） |
-| `refreshToken` | string | refresh token |
+| `token` | string | 认证 Token（由后端用 API-Key 调 `/v1/token/create` 签发） |
+| `tokenExpiresAt` | number | Token 过期时间戳（毫秒）。建议与应用登录态 TTL 一致 |
+| `tokenRefreshBufferMs` | number | 过期前多久提前刷新（毫秒），默认 60000 |
+| `refreshToken` | string | 后端刷新凭证（可选） |
 | `refreshTokenFn` | function | 刷新函数，返回新 token 信息 |
 | `onTokenRefreshed` | function | 刷新成功回调 |
-| `onTokenExpired` | function | 刷新失败回调 |
+| `onAuthExpired` | function | 认证彻底失效回调。**在此处引导用户重新登录** |
+
 ```
 
 ### 高级配置
@@ -431,7 +467,9 @@ data: {"conversationId":"conv_xxx","tokens":{"input":10,"output":15}}
 
 ### 认证
 
-所有请求自动携带 `Authorization: Bearer {token}`。提供 `refreshTokenFn` 后 Token 过期会自动刷新，无需手动处理。
+所有请求自动携带 `Authorization: Bearer {token}`。Token 由应用后端通过 API-Key 调用 `/v1/token/create` 签发，建议 TTL 与应用登录态保持一致。
+
+Token 过期后 SDK 触发 `onAuthExpired` 回调，应用层应引导用户重新登录。登录成功后调用 `updateConfig({ token, tokenExpiresAt, ... })` 或重新初始化 SDK 传入新 Token。
 
 ---
 

package/dist/index.cjs.js

@@ -195,12 +195,19 @@ class AIChatClient {
     silent = false
   } = {}) {
     if (typeof this.config.refreshTokenFn !== 'function') {
-      const error = new Error('Token 已过期且未配置 refreshTokenFn');
+      const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+      authErr._authExpired = true;
+      authErr._authReason = reason;
       if (!silent) {
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
+        this.config.onAuthExpired?.({
+          reason,
+          message: authErr.message,
+          noRefreshFn: true,
+          error: authErr
+        });
       }
-      throw error;
+      throw authErr;
     }
     if (!this.refreshTokenPromise) {
       this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -227,8 +234,17 @@ class AIChatClient {
           return this.config.token || '';
         }
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
-        throw error;
+        const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+        this.config.onAuthExpired?.({
+          reason,
+          message: errMsg,
+          noRefreshFn: false,
+          error
+        });
+        const authErr = new Error(errMsg);
+        authErr._authExpired = true;
+        authErr._authReason = reason;
+        throw authErr;
       }).finally(() => {
         this.refreshTokenPromise = null;
       });
@@ -360,6 +376,9 @@ class AIChatClient {
       }
       return result;
     } catch (error) {
+      if (error && error._authExpired) {
+        return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+      }
       if (error && error.name === 'AbortError') {
         return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
       }
@@ -454,6 +473,11 @@ class AIChatClient {
     try {
       return await this.executeMessageStream(prompt, handlers, options, false);
     } catch (error) {
+      if (error && error._authExpired) {
+        const message = error.message || '登录已过期，请重新登录';
+        handlers.onError?.(message, error);
+        return this.createError(ERROR_CODES.AUTH_FAILED, message);
+      }
       if (error && error.name === 'AbortError') {
         const message = '请求超时或已取消';
         handlers.onError?.(message, error.sseData || error);
@@ -3598,7 +3622,7 @@ class AIChatDialog extends HTMLElement {
       tokenRefreshBufferMs: 60000,
       refreshTokenFn: null,
       onTokenRefreshed: null,
-      onTokenExpired: null,
+      onAuthExpired: null,
       authErrorCodes: [],
       title: 'AI 助手',
       welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -6064,7 +6088,7 @@ class AIChatDialog extends HTMLElement {
     if (!text || typeof text !== 'string') return false;
     if (text === '\n' || text === '\n\n') return false;
     const p = text.trim();
-    if (!p) return true;
+    if (!p) return false;
     return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
   }
   _isEventLike(text) {
@@ -6300,8 +6324,11 @@ class AIChatDialog extends HTMLElement {
   handleError(err) {
     let displayMsg = '抱歉，网络请求失败，请稍后重试';
     const errMsg = err?.message || '';
+    const errCode = err?.code;
     // 按错误类型分类
-    if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+    if (err?._authExpired || errCode === 40301) {
+      displayMsg = '登录已过期，请重新登录后再试';
+    } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
       displayMsg = '网络连接失败，请检查网络后重试';
     } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
       displayMsg = '请求超时，请稍后重试';

package/dist/index.esm.js

@@ -191,12 +191,19 @@ class AIChatClient {
     silent = false
   } = {}) {
     if (typeof this.config.refreshTokenFn !== 'function') {
-      const error = new Error('Token 已过期且未配置 refreshTokenFn');
+      const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+      authErr._authExpired = true;
+      authErr._authReason = reason;
       if (!silent) {
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
+        this.config.onAuthExpired?.({
+          reason,
+          message: authErr.message,
+          noRefreshFn: true,
+          error: authErr
+        });
       }
-      throw error;
+      throw authErr;
     }
     if (!this.refreshTokenPromise) {
       this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -223,8 +230,17 @@ class AIChatClient {
           return this.config.token || '';
         }
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
-        throw error;
+        const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+        this.config.onAuthExpired?.({
+          reason,
+          message: errMsg,
+          noRefreshFn: false,
+          error
+        });
+        const authErr = new Error(errMsg);
+        authErr._authExpired = true;
+        authErr._authReason = reason;
+        throw authErr;
       }).finally(() => {
         this.refreshTokenPromise = null;
       });
@@ -356,6 +372,9 @@ class AIChatClient {
       }
       return result;
     } catch (error) {
+      if (error && error._authExpired) {
+        return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+      }
       if (error && error.name === 'AbortError') {
         return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
       }
@@ -450,6 +469,11 @@ class AIChatClient {
     try {
       return await this.executeMessageStream(prompt, handlers, options, false);
     } catch (error) {
+      if (error && error._authExpired) {
+        const message = error.message || '登录已过期，请重新登录';
+        handlers.onError?.(message, error);
+        return this.createError(ERROR_CODES.AUTH_FAILED, message);
+      }
       if (error && error.name === 'AbortError') {
         const message = '请求超时或已取消';
         handlers.onError?.(message, error.sseData || error);
@@ -3594,7 +3618,7 @@ class AIChatDialog extends HTMLElement {
       tokenRefreshBufferMs: 60000,
       refreshTokenFn: null,
       onTokenRefreshed: null,
-      onTokenExpired: null,
+      onAuthExpired: null,
       authErrorCodes: [],
       title: 'AI 助手',
       welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -6060,7 +6084,7 @@ class AIChatDialog extends HTMLElement {
     if (!text || typeof text !== 'string') return false;
     if (text === '\n' || text === '\n\n') return false;
     const p = text.trim();
-    if (!p) return true;
+    if (!p) return false;
     return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
   }
   _isEventLike(text) {
@@ -6296,8 +6320,11 @@ class AIChatDialog extends HTMLElement {
   handleError(err) {
     let displayMsg = '抱歉，网络请求失败，请稍后重试';
     const errMsg = err?.message || '';
+    const errCode = err?.code;
     // 按错误类型分类
-    if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+    if (err?._authExpired || errCode === 40301) {
+      displayMsg = '登录已过期，请重新登录后再试';
+    } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
       displayMsg = '网络连接失败，请检查网络后重试';
     } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
       displayMsg = '请求超时，请稍后重试';

package/dist/index.umd.js

@@ -197,12 +197,19 @@
         silent = false
       } = {}) {
         if (typeof this.config.refreshTokenFn !== 'function') {
-          const error = new Error('Token 已过期且未配置 refreshTokenFn');
+          const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+          authErr._authExpired = true;
+          authErr._authReason = reason;
           if (!silent) {
             this.stopBackgroundRefresh();
-            this.config.onTokenExpired?.(error);
+            this.config.onAuthExpired?.({
+              reason,
+              message: authErr.message,
+              noRefreshFn: true,
+              error: authErr
+            });
           }
-          throw error;
+          throw authErr;
         }
         if (!this.refreshTokenPromise) {
           this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -229,8 +236,17 @@
               return this.config.token || '';
             }
             this.stopBackgroundRefresh();
-            this.config.onTokenExpired?.(error);
-            throw error;
+            const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+            this.config.onAuthExpired?.({
+              reason,
+              message: errMsg,
+              noRefreshFn: false,
+              error
+            });
+            const authErr = new Error(errMsg);
+            authErr._authExpired = true;
+            authErr._authReason = reason;
+            throw authErr;
           }).finally(() => {
             this.refreshTokenPromise = null;
           });
@@ -362,6 +378,9 @@
           }
           return result;
         } catch (error) {
+          if (error && error._authExpired) {
+            return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+          }
           if (error && error.name === 'AbortError') {
             return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
           }
@@ -456,6 +475,11 @@
         try {
           return await this.executeMessageStream(prompt, handlers, options, false);
         } catch (error) {
+          if (error && error._authExpired) {
+            const message = error.message || '登录已过期，请重新登录';
+            handlers.onError?.(message, error);
+            return this.createError(ERROR_CODES.AUTH_FAILED, message);
+          }
           if (error && error.name === 'AbortError') {
             const message = '请求超时或已取消';
             handlers.onError?.(message, error.sseData || error);
@@ -3600,7 +3624,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
           tokenRefreshBufferMs: 60000,
           refreshTokenFn: null,
           onTokenRefreshed: null,
-          onTokenExpired: null,
+          onAuthExpired: null,
           authErrorCodes: [],
           title: 'AI 助手',
           welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -6066,7 +6090,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
         if (!text || typeof text !== 'string') return false;
         if (text === '\n' || text === '\n\n') return false;
         const p = text.trim();
-        if (!p) return true;
+        if (!p) return false;
         return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
       }
       _isEventLike(text) {
@@ -6302,8 +6326,11 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
       handleError(err) {
         let displayMsg = '抱歉，网络请求失败，请稍后重试';
         const errMsg = err?.message || '';
+        const errCode = err?.code;
         // 按错误类型分类
-        if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+        if (err?._authExpired || errCode === 40301) {
+          displayMsg = '登录已过期，请重新登录后再试';
+        } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
           displayMsg = '网络连接失败，请检查网络后重试';
         } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
           displayMsg = '请求超时，请稍后重试';