@tacoreai/web-sdk 1.18.0 → 1.20.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();
     }
   }
 
@@ -31,8 +142,8 @@ export class AppsAuthManager extends BaseAppsClient {
       'verifyRegistration': ({ email, token }) => this.verifyRegistration(email, token),
       'loginWithPassword': ({ email, password }) => this.loginWithPassword(email, password),
       'loginWithWechatH5': ({ code, scope }) => this.loginWithWechatH5(code, scope),
-      'forgotPassword': ({ email, redirectTo }) => this.forgotPassword(email, redirectTo),
-      'updatePassword': ({ accessToken, newPassword }) => this.updatePassword(accessToken, newPassword),
+      'auth/forgot-password': ({ email }) => this.forgotPassword(email),
+      'auth/reset-password': ({ email, token, newPassword }) => this.resetPassword(email, token, newPassword),
       'logout': () => this.logout(),
       'getCurrentUser': () => this.getCurrentUser(),
       'getSession': () => this.getSession(),
@@ -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,41 +362,104 @@ 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 });
+  }
+
   /**
-   * 请求发送密码重置邮件
+   * 请求发送密码重置邮件（包含 recovery 验证码）
    * @param {string} email - 用户的邮箱
-   * @param {string} redirectTo - 用户点击邮件链接后重定向到的前端页面URL
    * @returns {Promise<Object>}
    */
-  async forgotPassword(email, redirectTo) {
-    if (!email || !redirectTo) {
-      throw new Error("Email and redirectTo URL are required.");
+  async forgotPassword(email) {
+    if (!email) {
+      throw new Error("Email is required.");
     }
     return this._apiRequest("/apps/auth/forgot-password", {
       method: "POST",
-      body: JSON.stringify({ email, redirectTo }),
+      body: JSON.stringify({ email }),
     });
   }
 
   /**
-   * 使用令牌更新用户密码
-   * @param {string} accessToken - 从重定向URL中获取的访问令牌
+   * 使用邮箱验证码更新用户密码
+   * @param {string} email - 用户邮箱
+   * @param {string} token - 邮箱收到的 recovery OTP
    * @param {string} newPassword - 用户输入的新密码
    * @returns {Promise<Object>}
    */
-  async updatePassword(accessToken, newPassword) {
-    if (!accessToken || !newPassword) {
-      throw new Error("Access token and new password are required.");
+  async resetPassword(email, token, newPassword) {
+    if (!email || !token || !newPassword) {
+      throw new Error("Email, token and new password are required.");
     }
-    return this._apiRequest("/apps/auth/update-password", {
+    return this._apiRequest("/apps/auth/reset-password", {
       method: "POST",
-      body: JSON.stringify({ accessToken, newPassword }),
+      body: JSON.stringify({ email, token, newPassword }),
     });
   }
 
@@ -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.Users.js

@@ -46,4 +46,20 @@ export const appsClientUserMethods = {
       role: role,
     });
   },
+
+  /**
+   * [新增] 更新或重置一个用户在当前应用中的登录密码
+   * @param {Object} params { userId: string, password: string }
+   * @returns {Promise<{success: boolean, data: {userId: string, appId: string}}>}
+   */
+  async updateUserPassword({ userId, password }) {
+    if (!userId || !password) {
+      throw new Error("userId and password are required.");
+    }
+    return this._post("/apps/users/update-password", {
+      appId: this.appId,
+      targetUserId: userId,
+      password,
+    });
+  },
 };

package/database/core/apps/AppsClient.Wechat.js

@@ -0,0 +1,155 @@
+import { isBrowser } from "../../../utils/index.js";
+
+const appendWechatFileToForm = (form, file) => {
+  if (!file) {
+    throw new Error("file is required");
+  }
+
+  if (isBrowser) {
+    if (file instanceof File || file instanceof Blob) {
+      form.append("file", file, file.name || "file");
+      return;
+    }
+
+    throw new Error("Invalid file input in browser. Provide a File or Blob object.");
+  }
+
+  if (typeof file === "object" && file?.data && file?.encoding === "base64" && file?.name) {
+    const buffer = Buffer.from(file.data, "base64");
+    const blob = new Blob([buffer], {
+      type: file.type || file.mimeType || "application/octet-stream",
+    });
+    form.append("file", blob, file.name);
+    return;
+  }
+
+  if (file instanceof Blob) {
+    form.append("file", file, file.name || "file");
+    return;
+  }
+
+  throw new Error(
+    "Invalid file input in Node.js. Provide { data: base64_string, encoding: 'base64', name: string } or a Blob."
+  );
+};
+
+const postWechatMultipart = async function(endpoint, form) {
+  const headers = this._getRequestHeaders();
+  delete headers["Content-Type"];
+  delete headers["content-type"];
+
+  const response = await fetch(`${this.config.apiBaseUrl}${endpoint}`, {
+    method: "POST",
+    headers,
+    body: form,
+  });
+
+  const result = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(result.message || result.error || `HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  if (typeof this._validateResponse === "function") {
+    this._validateResponse(result);
+  }
+
+  return result;
+};
+
+export const appsClientWechatMethods = {
+  async wechatGetCapabilities(options = {}) {
+    return this._post("/apps/wechat/capabilities", options);
+  },
+
+  async wechatUploadArticleImage({ file }) {
+    const form = new FormData();
+    form.append("appId", this.appId);
+    appendWechatFileToForm(form, file);
+    return await postWechatMultipart.call(this, "/apps/wechat/official-account/materials/upload-article-image", form);
+  },
+
+  async wechatUploadTemporaryMaterial({ file, type }) {
+    if (!type) {
+      throw new Error("type is required for wechatUploadTemporaryMaterial");
+    }
+
+    const form = new FormData();
+    form.append("appId", this.appId);
+    form.append("type", type);
+    appendWechatFileToForm(form, file);
+    return await postWechatMultipart.call(this, "/apps/wechat/official-account/materials/upload-temporary", form);
+  },
+
+  async wechatUploadPermanentMaterial({ file, type, title, introduction }) {
+    if (!type) {
+      throw new Error("type is required for wechatUploadPermanentMaterial");
+    }
+
+    const form = new FormData();
+    form.append("appId", this.appId);
+    form.append("type", type);
+    if (title) form.append("title", title);
+    if (introduction) form.append("introduction", introduction);
+    appendWechatFileToForm(form, file);
+    return await postWechatMultipart.call(this, "/apps/wechat/official-account/materials/upload-permanent", form);
+  },
+
+  async wechatGetPermanentMaterialCount() {
+    return this._post("/apps/wechat/official-account/materials/count", {});
+  },
+
+  async wechatListPermanentMaterials(options = {}) {
+    return this._post("/apps/wechat/official-account/materials/list", options);
+  },
+
+  async wechatDeletePermanentMaterial({ mediaId }) {
+    return this._post("/apps/wechat/official-account/materials/delete", { mediaId });
+  },
+
+  async wechatCreateDraft({ articles }) {
+    return this._post("/apps/wechat/official-account/drafts/add", { articles });
+  },
+
+  async wechatUpdateDraft({ mediaId, index = 0, article }) {
+    return this._post("/apps/wechat/official-account/drafts/update", {
+      mediaId,
+      index,
+      article,
+    });
+  },
+
+  async wechatGetDraft({ mediaId }) {
+    return this._post("/apps/wechat/official-account/drafts/get", { mediaId });
+  },
+
+  async wechatListDrafts(options = {}) {
+    return this._post("/apps/wechat/official-account/drafts/list", options);
+  },
+
+  async wechatDeleteDraft({ mediaId }) {
+    return this._post("/apps/wechat/official-account/drafts/delete", { mediaId });
+  },
+
+  async wechatPublishDraft({ mediaId }) {
+    return this._post("/apps/wechat/official-account/publish/submit", { mediaId });
+  },
+
+  async wechatGetPublishStatus({ publishId }) {
+    return this._post("/apps/wechat/official-account/publish/status", { publishId });
+  },
+
+  async wechatGetPublishedArticle({ articleId }) {
+    return this._post("/apps/wechat/official-account/publish/get-article", { articleId });
+  },
+
+  async wechatListPublishedArticles(options = {}) {
+    return this._post("/apps/wechat/official-account/publish/list", options);
+  },
+
+  async wechatDeletePublishedArticle({ articleId, index }) {
+    return this._post("/apps/wechat/official-account/publish/delete-article", {
+      articleId,
+      index,
+    });
+  },
+};

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";
@@ -17,6 +17,7 @@ import { appsClientTextInMethods } from "./AppsClient.TextIn.js";
 import { appsClientToolsMethods } from "./AppsClient.Tools.js";
 import { appsClientDebugMethods } from "./AppsClient.Debug.js";
 import { appsClientCrawlerMethods } from "./AppsClient.Crawler.js";
+import { appsClientWechatMethods } from "./AppsClient.Wechat.js";
 
 const instanceMap = new Map();
 /**
@@ -41,14 +42,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);
 
     // 用于本地实时数据模式的订阅者管理
@@ -109,6 +102,7 @@ class AppsClient extends BaseAppsClient {
       // === 用户与角色 ===
       "createRole": params => this.createRole(params),
       "updateUserRole": params => this.updateUserRole(params),
+      "users/update-password": params => this.updateUserPassword(params),
       "listAppUsers": params => this.listAppUsers(params),
 
       // === 文件存储 ===
@@ -218,7 +212,8 @@ Object.assign(
   appsClientTextInMethods,
   appsClientToolsMethods,
   appsClientDebugMethods,
-  appsClientCrawlerMethods
+  appsClientCrawlerMethods,
+  appsClientWechatMethods
 );
 
-export { AppsClient };
+export { AppsClient };

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() &&
@@ -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.18.0",
+  "version": "1.20.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,11 +49,6 @@ export function getRouterBasename() {
 }
 
 export function getAppsApiBaseUrl() {
-  const isSSR = !!(
-    (typeof import.meta !== 'undefined' && import.meta.env?.SSR) || 
-    (typeof window === 'undefined')
-  );
-  // stone手动: 标准构建 ssr 环境，直接返回生产环境地址
   if (isSSR) {
     return `https://api.tacore.chat`;
   }