@tacoreai/web-sdk 1.16.0 → 1.19.0

package/database/core/apps/AppsAuthManager.js

@@ -1,6 +1,117 @@
-import { isBrowser, isBackend } from "../../../utils/index.js";
+import { isBrowser } from "../../../utils/index.js";
 import { BaseAppsClient } from "./BaseAppsClient.js";
 
+const REFRESH_TOKEN_STORAGE_KEY = "tacoreai_apps_refresh_token";
+const ACCESS_TOKEN_EXPIRES_AT_STORAGE_KEY = "tacoreai_apps_access_token_expires_at";
+const LEGACY_EXPIRES_AT_STORAGE_KEY = "tacoreai_apps_expires_at";
+const REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
+const REFRESH_RETRY_DELAY_MS = 60 * 1000;
+const MIN_TIMER_DELAY_MS = 1000;
+
+const normalizeText = (value) => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed || null;
+};
+
+const readStorageValue = (key) => {
+  if (!isBrowser) {
+    return null;
+  }
+
+  try {
+    return normalizeText(localStorage.getItem(key));
+  } catch (error) {
+    console.error(`[AppsAuthManager] Failed to read ${key} from localStorage:`, error);
+    return null;
+  }
+};
+
+const writeStorageValue = (key, value) => {
+  if (!isBrowser) {
+    return;
+  }
+
+  try {
+    if (value) {
+      localStorage.setItem(key, value);
+      return;
+    }
+    localStorage.removeItem(key);
+  } catch (error) {
+    console.error(`[AppsAuthManager] Failed to persist ${key}:`, error);
+  }
+};
+
+const parseExpiresAtMs = (value) => {
+  if (value === null || value === undefined || value === "") {
+    return null;
+  }
+
+  const numericValue = Number(value);
+  if (!Number.isFinite(numericValue) || numericValue <= 0) {
+    return null;
+  }
+
+  if (numericValue >= 1e12) {
+    return Math.trunc(numericValue);
+  }
+
+  return Math.trunc(numericValue * 1000);
+};
+
+const decodeJwtPayload = (token) => {
+  const normalizedToken = normalizeText(token);
+  if (!normalizedToken) {
+    return null;
+  }
+
+  const parts = normalizedToken.split(".");
+  if (parts.length < 2) {
+    return null;
+  }
+
+  try {
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4 || 4)) % 4);
+
+    if (typeof atob === "function") {
+      return JSON.parse(atob(padded));
+    }
+
+    if (typeof Buffer !== "undefined") {
+      return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    }
+  } catch (error) {
+    console.error("[AppsAuthManager] Failed to decode JWT payload:", error);
+  }
+
+  return null;
+};
+
+const resolveExpiresAtMs = ({ accessToken, expiresAt, expiresIn }) => {
+  const normalizedExpiresAt = parseExpiresAtMs(expiresAt);
+  if (normalizedExpiresAt) {
+    return normalizedExpiresAt;
+  }
+
+  const numericExpiresIn = Number(expiresIn);
+  if (Number.isFinite(numericExpiresIn) && numericExpiresIn > 0) {
+    return Date.now() + Math.trunc(numericExpiresIn * 1000);
+  }
+
+  const payload = decodeJwtPayload(accessToken);
+  return parseExpiresAtMs(payload?.exp);
+};
+
+const resolveTokenSubject = (token) => {
+  const payload = decodeJwtPayload(token);
+  return normalizeText(payload?.sub);
+};
+
 /**
  * AI应用认证管理器
  * 负责AI应用的用户认证、会话管理
@@ -9,15 +120,15 @@ import { BaseAppsClient } from "./BaseAppsClient.js";
 export class AppsAuthManager extends BaseAppsClient {
   constructor(appId, config = {}) {
     super(appId, config);
-    const isPreviewMode = isBackend && process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
-
-    if (isBackend && !isPreviewMode && !this.config.tacoreServerInteropAppServerApiKey) {
-      throw new Error("tacoreServerInteropAppServerApiKey is required for backend environment. Provide it in config or via TACORE_SERVER_INTEROP_APP_SERVER_API_KEY env var.");
-    }
+    this.refreshToken = normalizeText(config.refreshToken);
+    this.expiresAt = parseExpiresAtMs(config.expiresAt);
+    this._refreshPromise = null;
+    this._refreshTimer = null;
     
     // 自动检测 URL 中的 token (用于小程序 WebView 静默登录)
     if (isBrowser) {
       this._checkUrlToken();
+      this._ensureRefreshTimer();
     }
   }
 
@@ -46,25 +157,133 @@ export class AppsAuthManager extends BaseAppsClient {
   _checkUrlToken() {
     try {
       const urlParams = new URLSearchParams(window.location.search);
-      // 更新：从小程序传递的特定参数名获取 Token
-      const token = urlParams.get('tacoreai_mp_access_token');
+      const token = normalizeText(urlParams.get("tacoreai_mp_access_token"));
+      const refreshToken = normalizeText(urlParams.get("tacoreai_mp_refresh_token"));
+      const expiresAt = parseExpiresAtMs(urlParams.get("tacoreai_mp_expires_at"));
       
       if (token) {
-        console.log('[AppsAuthManager] Found token in URL, performing silent login...');
-        this.setAccessToken(token);
+        const currentAccessToken = this.getAccessToken({ fallbackToStorage: true });
+        const currentRefreshToken = this.getRefreshToken({ fallbackToStorage: true });
+        const currentExpiresAt =
+          this.getExpiresAt({ fallbackToStorage: true }) ||
+          resolveExpiresAtMs({
+            accessToken: currentAccessToken,
+          });
+        const isDifferentUser =
+          Boolean(currentAccessToken) &&
+          Boolean(resolveTokenSubject(currentAccessToken)) &&
+          Boolean(resolveTokenSubject(token)) &&
+          resolveTokenSubject(currentAccessToken) !== resolveTokenSubject(token);
+        const shouldReplaceExistingSession =
+          !currentAccessToken ||
+          !currentExpiresAt ||
+          !currentRefreshToken ||
+          isDifferentUser ||
+          Boolean(refreshToken && expiresAt && expiresAt >= currentExpiresAt);
+
+        if (shouldReplaceExistingSession) {
+          console.log("[AppsAuthManager] Found token in URL, performing silent login...");
+
+          if (refreshToken) {
+            this.setSession({
+              accessToken: token,
+              refreshToken,
+              expiresAt,
+            });
+          } else {
+            this.setAccessToken(token);
+          }
+        }
         
         // 清除 URL 中的 token 参数，避免分享泄露
         const newUrl = window.location.protocol + "//" + window.location.host + window.location.pathname;
         // 保留其他参数
-        urlParams.delete('tacoreai_mp_access_token');
+        urlParams.delete("tacoreai_mp_access_token");
+        urlParams.delete("tacoreai_mp_refresh_token");
+        urlParams.delete("tacoreai_mp_expires_at");
         const remainingParams = urlParams.toString();
         const finalUrl = remainingParams ? `${newUrl}?${remainingParams}` : newUrl;
         
-        window.history.replaceState({ path: finalUrl }, '', finalUrl);
+        window.history.replaceState({ path: finalUrl }, "", finalUrl);
       }
     } catch (e) {
-      console.error('[AppsAuthManager] Failed to parse URL token:', e);
+      console.error("[AppsAuthManager] Failed to parse URL token:", e);
+    }
+  }
+
+  _clearRefreshTimer() {
+    if (this._refreshTimer) {
+      clearTimeout(this._refreshTimer);
+      this._refreshTimer = null;
+    }
+  }
+
+  _scheduleRefreshRetry() {
+    if (!isBrowser || !this.getRefreshToken({ fallbackToStorage: true })) {
+      return;
+    }
+
+    this._clearRefreshTimer();
+    this._refreshTimer = setTimeout(() => {
+      this.refreshSessionIfNeeded({ force: true }).catch((error) => {
+        console.error("[AppsAuthManager] Retry session refresh failed:", error);
+      });
+    }, REFRESH_RETRY_DELAY_MS);
+  }
+
+  _ensureRefreshTimer() {
+    if (!isBrowser) {
+      return;
+    }
+
+    this._clearRefreshTimer();
+
+    const refreshToken = this.getRefreshToken({ fallbackToStorage: true });
+    const accessToken = this.getAccessToken({ fallbackToStorage: true });
+    if (!refreshToken || !accessToken) {
+      return;
     }
+
+    let expiresAt = this.getExpiresAt({ fallbackToStorage: true });
+    if (!expiresAt) {
+      expiresAt = resolveExpiresAtMs({ accessToken });
+      if (expiresAt) {
+        this.setExpiresAt(expiresAt, { persist: true });
+      }
+    }
+
+    if (!expiresAt) {
+      return;
+    }
+
+    const delayMs = Math.max(MIN_TIMER_DELAY_MS, expiresAt - Date.now() - REFRESH_THRESHOLD_MS);
+    this._refreshTimer = setTimeout(() => {
+      this.refreshSessionIfNeeded({ force: true }).catch((error) => {
+        console.error("[AppsAuthManager] Automatic session refresh failed:", error);
+      });
+    }, delayMs);
+  }
+
+  _shouldRefreshSession(thresholdMs = REFRESH_THRESHOLD_MS) {
+    const accessToken = this.getAccessToken({ fallbackToStorage: true });
+    const refreshToken = this.getRefreshToken({ fallbackToStorage: true });
+    if (!accessToken || !refreshToken) {
+      return false;
+    }
+
+    let expiresAt = this.getExpiresAt({ fallbackToStorage: true });
+    if (!expiresAt) {
+      expiresAt = resolveExpiresAtMs({ accessToken });
+      if (expiresAt) {
+        this.setExpiresAt(expiresAt, { persist: true });
+      }
+    }
+
+    if (!expiresAt) {
+      return false;
+    }
+
+    return expiresAt - Date.now() <= thresholdMs;
   }
 
   /**
@@ -103,9 +322,8 @@ export class AppsAuthManager extends BaseAppsClient {
       body: JSON.stringify({ email, token, appId: this.appId }),
     });
 
-    // 成功验证后，后端会返回会话信息
     if (result.accessToken) {
-      this.setAccessToken(result.accessToken);
+      this.setSession(result);
     }
 
     return result;
@@ -125,7 +343,7 @@ export class AppsAuthManager extends BaseAppsClient {
     });
 
     if (result.accessToken) {
-      this.setAccessToken(result.accessToken);
+      this.setSession(result);
     }
 
     return result;
@@ -144,12 +362,75 @@ export class AppsAuthManager extends BaseAppsClient {
     });
 
     if (result.accessToken) {
-      this.setAccessToken(result.accessToken);
+      this.setSession(result);
     }
 
     return result;
   }
 
+  async refreshSession(options = {}) {
+    const { force = false } = options;
+    const refreshToken = this.getRefreshToken({ fallbackToStorage: isBrowser });
+
+    if (!refreshToken) {
+      return null;
+    }
+
+    if (!force && !this._shouldRefreshSession()) {
+      this._ensureRefreshTimer();
+      return this.getSessionSnapshot();
+    }
+
+    if (this._refreshPromise) {
+      return this._refreshPromise;
+    }
+
+    this._clearRefreshTimer();
+    this._refreshPromise = (async () => {
+      try {
+        const result = await this._apiRequest("/apps/auth/refresh", {
+          method: "POST",
+          body: JSON.stringify({ refreshToken, appId: this.appId }),
+        });
+
+        if (result?.accessToken) {
+          this.setSession(result);
+        }
+
+        return result;
+      } catch (error) {
+        if (error?.status === 401) {
+          this.clearSession();
+        } else {
+          this._scheduleRefreshRetry();
+        }
+        throw error;
+      } finally {
+        this._refreshPromise = null;
+      }
+    })();
+
+    return this._refreshPromise;
+  }
+
+  async refreshSessionIfNeeded(options = {}) {
+    const { force = false, thresholdMs = REFRESH_THRESHOLD_MS } = options;
+    const accessToken = this.getAccessToken({ fallbackToStorage: isBrowser });
+    const refreshToken = this.getRefreshToken({ fallbackToStorage: isBrowser });
+
+    if (!accessToken || !refreshToken) {
+      this._ensureRefreshTimer();
+      return this.getSessionSnapshot();
+    }
+
+    if (!force && !this._shouldRefreshSession(thresholdMs)) {
+      this._ensureRefreshTimer();
+      return this.getSessionSnapshot();
+    }
+
+    return this.refreshSession({ force: true });
+  }
+
   /**
    * 请求发送密码重置邮件
    * @param {string} email - 用户的邮箱
@@ -192,7 +473,7 @@ export class AppsAuthManager extends BaseAppsClient {
         method: "POST",
       });
     } finally {
-      this.clearAccessToken();
+      this.clearSession();
     }
   }
 
@@ -202,9 +483,13 @@ export class AppsAuthManager extends BaseAppsClient {
    */
   async getCurrentUser() {
     try {
+      await this.refreshSessionIfNeeded();
       const result = await this._apiRequest(`/apps/auth/profile?appId=${this.appId}`);
       return result.user;
     } catch (error) {
+      if (error?.status === 401) {
+        this.clearSession();
+      }
       return null;
     }
   }
@@ -214,6 +499,8 @@ export class AppsAuthManager extends BaseAppsClient {
    * @returns {Promise<Object|null>}
    */
   async getSession() {
+    await this.refreshSessionIfNeeded();
+
     const token = this.getAccessToken({ fallbackToStorage: isBrowser });
     if (!token) {
       return null;
@@ -223,9 +510,14 @@ export class AppsAuthManager extends BaseAppsClient {
       const result = await this._apiRequest(`/apps/auth/profile?appId=${this.appId}`);
       return {
         access_token: token,
+        refresh_token: this.getRefreshToken({ fallbackToStorage: isBrowser }),
+        expires_at: this.getExpiresAt({ fallbackToStorage: isBrowser }),
         user: result.user,
       };
     } catch (error) {
+      if (error?.status === 401) {
+        this.clearSession();
+      }
       return null;
     }
   }
@@ -239,10 +531,13 @@ export class AppsAuthManager extends BaseAppsClient {
     if (!token) return false;
 
     try {
-      await this.getCurrentUser();
+      const user = await this.getCurrentUser();
+      if (!user) {
+        this.clearSession();
+        return false;
+      }
       return true;
     } catch (error) {
-      this.clearAccessToken();
       return false;
     }
   }
@@ -257,6 +552,8 @@ export class AppsAuthManager extends BaseAppsClient {
     this.isAuthenticated().then((isAuth) => {
       callback(isAuth ? "SIGNED_IN" : "SIGNED_OUT", {
         access_token: this.getAccessToken({ fallbackToStorage: isBrowser }),
+        refresh_token: this.getRefreshToken({ fallbackToStorage: isBrowser }),
+        expires_at: this.getExpiresAt({ fallbackToStorage: isBrowser }),
       });
     });
 
@@ -270,6 +567,7 @@ export class AppsAuthManager extends BaseAppsClient {
    */
   async autoAuth() {
     try {
+      await this.refreshSessionIfNeeded();
       const isAuth = await this.isAuthenticated();
       if (isAuth) {
         const user = await this.getCurrentUser();
@@ -307,10 +605,124 @@ export class AppsAuthManager extends BaseAppsClient {
     });
   }
 
+  setRefreshToken(token, options = {}) {
+    const { persist = isBrowser } = options;
+    const normalizedToken = normalizeText(token);
+    this.refreshToken = normalizedToken;
+
+    if (persist) {
+      writeStorageValue(REFRESH_TOKEN_STORAGE_KEY, normalizedToken);
+    }
+
+    return normalizedToken;
+  }
+
+  getRefreshToken(options = {}) {
+    const { fallbackToStorage = isBrowser } = options;
+    if (this.refreshToken) {
+      return this.refreshToken;
+    }
+
+    if (!fallbackToStorage) {
+      return null;
+    }
+
+    return readStorageValue(REFRESH_TOKEN_STORAGE_KEY);
+  }
+
+  clearRefreshToken(options = {}) {
+    const { persist = isBrowser } = options;
+    this.refreshToken = null;
+
+    if (persist) {
+      writeStorageValue(REFRESH_TOKEN_STORAGE_KEY, null);
+    }
+  }
+
+  setExpiresAt(value, options = {}) {
+    const { persist = isBrowser } = options;
+    const normalizedExpiresAt = parseExpiresAtMs(value);
+    this.expiresAt = normalizedExpiresAt;
+
+    if (persist) {
+      writeStorageValue(
+        ACCESS_TOKEN_EXPIRES_AT_STORAGE_KEY,
+        normalizedExpiresAt ? String(normalizedExpiresAt) : null
+      );
+      writeStorageValue(LEGACY_EXPIRES_AT_STORAGE_KEY, null);
+    }
+
+    return normalizedExpiresAt;
+  }
+
+  getExpiresAt(options = {}) {
+    const { fallbackToStorage = isBrowser } = options;
+    if (this.expiresAt) {
+      return this.expiresAt;
+    }
+
+    if (!fallbackToStorage) {
+      return null;
+    }
+
+    return parseExpiresAtMs(readStorageValue(ACCESS_TOKEN_EXPIRES_AT_STORAGE_KEY))
+      || parseExpiresAtMs(readStorageValue(LEGACY_EXPIRES_AT_STORAGE_KEY));
+  }
+
+  clearExpiresAt(options = {}) {
+    const { persist = isBrowser } = options;
+    this.expiresAt = null;
+
+    if (persist) {
+      writeStorageValue(ACCESS_TOKEN_EXPIRES_AT_STORAGE_KEY, null);
+      writeStorageValue(LEGACY_EXPIRES_AT_STORAGE_KEY, null);
+    }
+  }
+
+  setSession(session = {}, options = {}) {
+    const { persist = isBrowser, syncConfig = true } = options;
+    const accessToken = super.setAccessToken(session.accessToken, {
+      persist,
+      syncConfig,
+    });
+    const refreshToken = this.setRefreshToken(session.refreshToken, { persist });
+    const expiresAt = this.setExpiresAt(
+      resolveExpiresAtMs({
+        accessToken,
+        expiresAt: session.expiresAt,
+        expiresIn: session.expiresIn,
+      }),
+      { persist }
+    );
+
+    this._ensureRefreshTimer();
+
+    return {
+      accessToken,
+      refreshToken,
+      expiresAt,
+    };
+  }
+
+  getSessionSnapshot() {
+    return {
+      accessToken: this.getAccessToken({ fallbackToStorage: isBrowser }),
+      refreshToken: this.getRefreshToken({ fallbackToStorage: isBrowser }),
+      expiresAt: this.getExpiresAt({ fallbackToStorage: isBrowser }),
+    };
+  }
+
+  clearSession(options = {}) {
+    this._clearRefreshTimer();
+    super.clearAccessToken(options);
+    this.clearRefreshToken(options);
+    this.clearExpiresAt(options);
+  }
+
   /**
    * 清除访问令牌
    */
   clearAccessToken(options = {}) {
-    super.clearAccessToken(options);
+    this.clearSession(options);
   }
 }

package/database/core/apps/AppsClient.js

@@ -1,4 +1,4 @@
-import { isBrowser, isBackend } from "../../../utils/index.js";
+import { isBrowser } from "../../../utils/index.js";
 import { BaseAppsClient } from "./BaseAppsClient.js";
 import { VolcengineImpl } from "./AppsClient.Volcengine.js";
 import { appsClientAppServerMethods } from "./AppsClient.AppServer.js";
@@ -41,14 +41,6 @@ class AppsClient extends BaseAppsClient {
 
   constructor(appId, config = {}) {
     super(appId, config);
-    const isPreviewMode = isBackend && process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
-
-    if (isBackend && !isPreviewMode && !this.config.tacoreServerInteropAppServerApiKey) {
-      throw new Error(
-        "tacoreServerInteropAppServerApiKey is required for backend environment. Provide it in config or via TACORE_SERVER_INTEROP_APP_SERVER_API_KEY env var."
-      );
-    }
-
     instanceMap.set(appId, this);
 
     // 用于本地实时数据模式的订阅者管理
@@ -221,4 +213,4 @@ Object.assign(
   appsClientCrawlerMethods
 );
 
-export { AppsClient };
+export { AppsClient };

package/database/core/apps/AppsPublicClient.js

@@ -20,8 +20,16 @@ export class AppsPublicClient extends BaseAppsClient {
   get adapters() {
     return {
       'submitPublicData': ({ modelName, data }) => this.submitPublicData(modelName, data),
-      'readConfiguredPublicData': (params) => {
-        const { modelName, ...rest } = params;
+      'readConfiguredPublicData': (params = {}) => {
+        const { modelName, query, ...rest } = params;
+
+        // 新版约定：invoke('readConfiguredPublicData', { modelName, query })
+        // 其中 query 可以是 wyID 字符串，也可以是分页/过滤对象。
+        if (query !== undefined) {
+          return this.readConfiguredPublicData(modelName, query);
+        }
+
+        // 兼容旧版平铺参数：invoke('readConfiguredPublicData', { modelName, wyID })
         if (rest.wyID && Object.keys(rest).length === 1) {
           return this.readConfiguredPublicData(modelName, rest.wyID);
         }
@@ -104,4 +112,4 @@ export class AppsPublicClient extends BaseAppsClient {
       throw error;
     }
   }
-}
+}

package/database/core/apps/BaseAppsClient.js

@@ -1,7 +1,9 @@
-import { getAppsApiBaseUrl, isBrowser, isBackend, getGlobalOptions } from "../../../utils/index.js";
+import { getAppsApiBaseUrl, isBrowser, isBackend, isSSR, getGlobalOptions } from "../../../utils/index.js";
 
 const ACCESS_TOKEN_STORAGE_KEY = "tacoreai_apps_access_token";
 const PREVIEW_APPSERVER_API_KEY_HEADER = "x-tacore-preview-app-server-api-key";
+const INTEROP_APP_SERVER_API_KEY_REQUIRED_ERROR =
+  "tacoreServerInteropAppServerApiKey is required for backend environment. Provide it in config or via TACORE_SERVER_INTEROP_APP_SERVER_API_KEY env var.";
 
 const normalizeAccessToken = (value) => {
   if (typeof value !== "string") {
@@ -46,6 +48,7 @@ const writePersistedAccessToken = (token) => {
 };
 
 const isBackendPreviewMode = () => isBackend && process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
+const shouldRequireInteropAppServerApiKey = () => isBackend && !isSSR && !isBackendPreviewMode();
 
 /**
  * Apps SDK 基类
@@ -79,9 +82,13 @@ export class BaseAppsClient {
     }
 
     // 后端环境通用逻辑：尝试从环境变量加载 API Key
-    if (isBackend && !this.config.tacoreServerInteropAppServerApiKey) {
+    if (isBackend && !isSSR && !this.config.tacoreServerInteropAppServerApiKey) {
       this.config.tacoreServerInteropAppServerApiKey = process.env.TACORE_SERVER_INTEROP_APP_SERVER_API_KEY;
     }
+
+    if (shouldRequireInteropAppServerApiKey() && !this.config.tacoreServerInteropAppServerApiKey) {
+      throw new Error(INTEROP_APP_SERVER_API_KEY_REQUIRED_ERROR);
+    }
   }
 
   /**
@@ -179,7 +186,7 @@ export class BaseAppsClient {
       headers["Authorization"] = `Bearer ${token}`;
     }
 
-    if (isBackend && this.config.tacoreServerInteropAppServerApiKey) {
+    if (isBackend && !isSSR && this.config.tacoreServerInteropAppServerApiKey) {
       headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
     } else if (
       isBackendPreviewMode() &&
@@ -200,13 +207,13 @@ export class BaseAppsClient {
     const url = `${this.config.apiBaseUrl}${endpoint}`;
     const headers = this._getRequestHeaders(options.headers);
 
-    if (isBackendPreviewMode()) {
-      console.log(`[BaseAppsClient Debug][${this.appId}] endpoint="${endpoint}"`, {
-        hasAuthorization: Boolean(headers.Authorization || headers.authorization),
-        hasInteropHeader: Boolean(headers["x-tacore-server-interop-app-server-api-key"]),
-        hasPreviewAppServerApiKeyHeader: Boolean(headers[PREVIEW_APPSERVER_API_KEY_HEADER]),
-      });
-    }
+    // if (isBackendPreviewMode()) {
+    //   console.log(`[BaseAppsClient Debug][${this.appId}] endpoint="${endpoint}"`, {
+    //     hasAuthorization: Boolean(headers.Authorization || headers.authorization),
+    //     hasInteropHeader: Boolean(headers["x-tacore-server-interop-app-server-api-key"]),
+    //     hasPreviewAppServerApiKeyHeader: Boolean(headers[PREVIEW_APPSERVER_API_KEY_HEADER]),
+    //   });
+    // }
 
     const response = await fetch(url, {
       ...options,
@@ -216,7 +223,10 @@ export class BaseAppsClient {
     if (!response.ok) {
       const errorData = await response.json().catch(() => ({ error: "Network error" }));
       console.error(`[SDK][${this.appId}] API request failed: ${response.status} ${response.statusText}`, errorData);
-      throw new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+      const error = new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+      error.status = response.status;
+      error.responseData = errorData;
+      throw error;
     }
 
     const result = await response.json();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tacoreai/web-sdk",
   "description": "This file is for app server package, not the real npm package",
-  "version": "1.16.0",
+  "version": "1.19.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/utils/index.js

@@ -15,6 +15,8 @@ export function getGlobalOptions() {
 
 // 新增：环境判断
 export const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+// 仅将 Vite SSR 识别为 SSR，避免把普通 Node 后端和 SSR 混在一起。
+export const isSSR = !isBrowser && typeof import.meta !== "undefined" && Boolean(import.meta.env?.SSR);
 // 后端环境 (Node.js) 为 'backend', 浏览器环境根据全局变量判断，默认为 'development'
 export const env = isBrowser ? (window.__TACORE_APP_ENV__ || 'development') : 'backend';
 
@@ -47,8 +49,7 @@ export function getRouterBasename() {
 }
 
 export function getAppsApiBaseUrl() {
-  // stone手动: 标准构建 ssr 环境，直接返回生产环境地址
-  if (process.env.MODE === 'production' && process.env.SSR === 'true') {
+  if (isSSR) {
     return `https://api.tacore.chat`;
   }
   // 后端环境逻辑