@tacoreai/web-sdk 1.22.0 → 1.22.1-beta.0

package/README.md

@@ -17,52 +17,63 @@ npm install @tacoreai/web-sdk
 ### AppsClient (Data & AI)
 示例略（保持原有章节）
 
+### AppsClient (Events)
+
+应用自定义埋点应使用事件日志接口，不要把高频事件写入通用数据模型。
+应用代码不要直接请求 `/plat` 平台接口，也不要读取平台登录 token；写入和读取都应通过 `AppsClient.invoke(...)` 走 `/apps/events/*`。事件日志不新增 WebSDK 专用方法，apiName 直接和后端 path 对齐。
+
+```js
+const tracked = await client.invoke('events/track', {
+  eventName: 'signup_click',
+  properties: { plan: 'pro' },
+  visitorId: localStorage.getItem('visitor_id'),
+  sessionId: sessionStorage.getItem('session_id'),
+  path: window.location.pathname,
+});
+
+// 以下读取接口仅适用于已登录且具备 app owner/admin 角色的应用管理界面。
+const event = await client.invoke('events/read', {
+  eventId: tracked?.data?.eventId,
+});
+
+const page = await client.invoke('events/query', {
+  day: '2026-05-14',
+  eventName: 'signup_click',
+  limit: 50,
+});
+```
+
+可用接口包括 `events/track`、`events/batch-track`、`events/read`、`events/batch-read`、`events/query`。写入接口由后端校验应用部署域名或自定义域名来源；所有读取接口都要求 Apps 登录态且当前用户为应用 `owner/admin`。平台通用查看/搜索由平台工作视图承接。
+
 ---
 
-## 文件存储 API（CloudBase 通道）
+## 文件存储 API（R2 / GCS）
 
 先确保已通过 AppsAuthManager 登录，并使用 AppsClient 初始化时提供 appId。以下接口均作用于 /apps 路由，需携带 Authorization。
 
-1) 上传文件（<=20MB）
+1) 上传文件到 R2（公开访问 / 前端展示）
 
 import { AppsClient } from '@tacoreai/web-sdk'
 const client = new AppsClient('YOUR_APP_ID')
 
 const input = document.querySelector('#fileInput')
 const file = input.files[0]
-const result = await client.uploadFile(file, { expires: 3600 })
-// result.data => { fileID, url, path, mimeType, size, expiresIn }
+const result = await client.uploadFile(file)
+// result => { success: true, url, key }
 
-2) 获取临时下载 URL
+2) 下载 R2 文件
 
-const { data } = await client.getFileUrl('<fileID>', 1800)
-// data.url 为可直接访问的签名地址（有效期30分钟）
+const response = await client.downloadFromR2('<key>')
+const blob = await response.blob()
 
-3) 批量删除文件
+3) 删除 R2 文件
 
-await client.deleteFiles(['<fileID1>', '<fileID2>'])
+await client.deleteFromR2('<key>')
 
-4) 下载文件为 Blob（用于预览或保存）
+4) 上传文件到 GCS（Gemini / 多模态分析输入）
 
-const blob = await client.downloadFile('<fileID>')
-// 例如：保存为本地文件
-const a = document.createElement('a')
-a.href = URL.createObjectURL(blob)
-a.download = 'download.bin'
-a.click()
-URL.revokeObjectURL(a.href)
-
----
-
-## [新增] 文件上传与分析
-
-此接口用于上传文件（如 PDF、图片）以供 AI 进行深度分析或作为图片编辑的输入。
-
-### `uploadFileForAnalysis(file)`
-- **功能**: 将文件上传至 Google 的专用存储，并返回一个可供 AI 模型引用的 `fileUri`。
-- **参数**:
-  - `file` (File): 从文件输入框获取的 File 对象。
-- **返回值**: `Promise<{fileUri: string, mimeType: string, ...}>`
+const gcsResult = await client.uploadToGCS(file)
+// gcsResult.fileUri => gs://... ，供 Gemini 等模型使用
 
 ---
 
@@ -111,12 +122,12 @@ const imageUri = result.data.uri;
 - **返回**: `Promise<Object>` (后端响应对象，包含 `data.uri` 或 `data.images`)
 
 ### 核心流程
-1.  **上传图片**: 所有源图片（包括底图、叠加图、掩膜图）都**必须**先通过 `uploadFileForAnalysis(file)` 上传，获取 `fileUri` 和 `mimeType`。
+1.  **上传图片**: Google / Gemini 链路下，所有源图片（包括底图、叠加图、掩膜图）都应先通过 `uploadToGCS(file)` 获取 `gs://` 形式的 `fileUri`。
 2.  **调用编辑**: 使用获取到的 `fileUri` 和 `mimeType`，通过 `editImage` 方法并采用**简化的 `prompt + inputs` 模式**进行调用。
 
 ### 前置要求
 - **必须先登录** (AppsAuthManager)
-- `uploadFileForAnalysis`
+- `uploadToGCS`
 
 ### 1. 简化调用 (prompt + inputs 模式，推荐)
 SDK 会自动将 `prompt` 和 `inputs` 数组组合成标准的多模态 `messages`。
@@ -125,13 +136,13 @@ import { AppsClient } from '@tacoreai/web-sdk'
 const client = new AppsClient('YOUR_APP_ID')
 
 // 1. 上传源文件
-const baseFile = await client.uploadFileForAnalysis(file);
+const baseFile = await client.uploadToGCS(file);
 
 // 2. 调用编辑接口
 const result = await client.editImage({
   prompt: '仅移除图中叠加的文字，保持其他区域不变，输出高清。',
   inputs: [
-    { type: 'uploaded_file', fileUri: baseFile.fileUri, mimeType: baseFile.mimeType }
+    { type: 'uploaded_file', fileUri: baseFile.fileUri, mimeType: file.type }
   ]
 });
 // 获取图片 URI (兼容不同后端返回结构)
@@ -142,41 +153,41 @@ const editedBase64 = result.data.uri || (result.data.images && result.data.image
 
 - **场景 A：单图编辑（去字/去水印/局部替换）**
 
-const base = await client.uploadFileForAnalysis(file);
+const base = await client.uploadToGCS(file);
 const result = await client.editImage({
   prompt: '移除叠加文字，其他区域完全保持不变。',
   inputs: [
-    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType }
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: file.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
 
 - **场景 B：双图融合（将服装穿到模特身上）**
 
-const garment = await client.uploadFileForAnalysis(garmentFile);
-const modelPhoto = await client.uploadFileForAnalysis(modelFile);
+const garment = await client.uploadToGCS(garmentFile);
+const modelPhoto = await client.uploadToGCS(modelFile);
 
 const result = await client.editImage({
   prompt: '将服装自然替换到模特身上，保持姿态与光照；去除服装图背景；保持背景不变；不改变面部和发型。',
   inputs: [
     // 建议顺序：底图（模特）放前，叠加/融合图（服装）放后
-    { type: 'uploaded_file', fileUri: modelPhoto.fileUri, mimeType: modelPhoto.mimeType },
-    { type: 'uploaded_file', fileUri: garment.fileUri, mimeType: garment.mimeType }
+    { type: 'uploaded_file', fileUri: modelPhoto.fileUri, mimeType: modelFile.type },
+    { type: 'uploaded_file', fileUri: garment.fileUri, mimeType: garmentFile.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
 
 - **场景 C：掩膜修复/扩展（Inpainting / Outpainting）**
 
-const base = await client.uploadFileForAnalysis(baseFile);
-const mask = await client.uploadFileForAnalysis(maskFile); // 掩膜语义按后端约定
+const base = await client.uploadToGCS(baseFile);
+const mask = await client.uploadToGCS(maskFile); // 掩膜语义按后端约定
 
 const result = await client.editImage({
   prompt: '在掩膜区域进行修复，移除水印并保持纹理一致；不要改变未掩膜区域。',
   inputs: [
     // 建议顺序：底图 -> 掩膜
-    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType },
-    { type: 'uploaded_file', fileUri: mask.fileUri, mimeType: mask.mimeType }
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: baseFile.type },
+    { type: 'uploaded_file', fileUri: mask.fileUri, mimeType: maskFile.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
@@ -184,7 +195,7 @@ const base64 = result.data.uri || result.data.images?.[0]?.uri;
 ### 3. 高级模式 (messages 透传)
 用于完全控制请求结构，不推荐常规使用。
 
-const base = await client.uploadFileForAnalysis(file)
+const base = await client.uploadToGCS(file)
 
 const result = await client.editImage({
   model: 'gemini-2.5-flash-image-preview',
@@ -193,7 +204,7 @@ const result = await client.editImage({
       role: 'user',
       content: [
         { type: 'text', text: '移除图中叠加的文字...' },
-        { type: 'uploaded_file', uploaded_file: { fileUri: base.fileUri, mimeType: base.mimeType } }
+        { type: 'uploaded_file', uploaded_file: { fileUri: base.fileUri, mimeType: file.type } }
       ]
     }
   ]

package/database/core/apps/AppServerRuntime.js

@@ -31,12 +31,25 @@ const getRequestSource = (isPlatformProxyRequest, isSchedulerRequest) => {
 };
 
 const createRequestScopedAppsClient = (env, options = {}) => {
-  const { accessToken = null, previewAppServerApiKey = null } = options;
+  const {
+    accessToken = null,
+    previewAppServerApiKey = null,
+    enableAppServerServiceAuth = false,
+  } = options;
   const config = {
     ...env,
     accessToken: accessToken || null,
+    enableAppServerServiceAuth,
   };
 
+  if (enableAppServerServiceAuth) {
+    config.appServerOwnerAppId = env.appId;
+    config.tacoreAppServerServiceToken =
+      env.tacoreAppServerServiceToken ||
+      process.env.TACORE_APP_SERVER_SERVICE_TOKEN ||
+      null;
+  }
+
   if (previewAppServerApiKey) {
     config.previewAppServerApiKey = previewAppServerApiKey;
   }
@@ -274,6 +287,7 @@ export const createAppServerRuntime = async (options = {}) => {
     );
     const requestSource = getRequestSource(isPlatformProxyRequest, isSchedulerRequest);
     let previewAppServerApiKey = null;
+    let isExternalApiKeyRequest = false;
 
     console.log(`[AppServer] invoke api="${apiName}" source="${requestSource}"`);
 
@@ -318,6 +332,8 @@ export const createAppServerRuntime = async (options = {}) => {
         });
       }
 
+      isExternalApiKeyRequest = true;
+
       if (isPreviewMode() && !requestAccessToken) {
         previewAppServerApiKey = requestApiKey;
       }
@@ -330,17 +346,21 @@ export const createAppServerRuntime = async (options = {}) => {
         hasRequestApiKey: Boolean(requestApiKey),
         hasPlatformInteropHeader: Boolean(platformInteropHeader),
         hasSchedulerInteropHeader: Boolean(schedulerInteropHeader),
+        isExternalApiKeyRequest,
         willForwardPreviewAppServerApiKey: Boolean(previewAppServerApiKey),
       });
 
       const appsClient = createRequestScopedAppsClient(env, {
         accessToken: requestAccessToken || null,
         previewAppServerApiKey,
+        enableAppServerServiceAuth: Boolean((isSchedulerRequest || isExternalApiKeyRequest) && !requestAccessToken),
       });
       console.log(`[AppServer Debug] scoped AppsClient api="${apiName}"`, {
         hasAccessToken: Boolean(appsClient.getAccessToken()),
         hasPreviewAppServerApiKey: Boolean(appsClient.config.previewAppServerApiKey),
         hasInteropKey: Boolean(appsClient.config.tacoreServerInteropAppServerApiKey),
+        serviceAuthEnabled: appsClient.config.enableAppServerServiceAuth === true,
+        hasServiceToken: Boolean(appsClient.config.tacoreAppServerServiceToken),
       });
       const data = await appsClient.invokeAppServerAPI(apiName, payload, {
         appsClient,

package/database/core/apps/BaseAppsClient.js

@@ -2,6 +2,8 @@ import { getAppsApiBaseUrl, isBrowser, isBackend, isSSR, getGlobalOptions } from
 
 const ACCESS_TOKEN_STORAGE_KEY = "tacoreai_apps_access_token";
 const PREVIEW_APPSERVER_API_KEY_HEADER = "x-tacore-preview-app-server-api-key";
+const APP_SERVER_SERVICE_TOKEN_HEADER = "x-tacore-app-server-service-token";
+const APP_SERVER_OWNER_APP_ID_HEADER = "x-tacore-app-server-owner-app-id";
 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.";
 
@@ -85,6 +87,14 @@ export class BaseAppsClient {
     if (isBackend && !isSSR && !this.config.tacoreServerInteropAppServerApiKey) {
       this.config.tacoreServerInteropAppServerApiKey = process.env.TACORE_SERVER_INTEROP_APP_SERVER_API_KEY;
     }
+    if (
+      isBackend &&
+      !isSSR &&
+      this.config.enableAppServerServiceAuth === true &&
+      !this.config.tacoreAppServerServiceToken
+    ) {
+      this.config.tacoreAppServerServiceToken = process.env.TACORE_APP_SERVER_SERVICE_TOKEN;
+    }
 
     if (shouldRequireInteropAppServerApiKey() && !this.config.tacoreServerInteropAppServerApiKey) {
       throw new Error(INTEROP_APP_SERVER_API_KEY_REQUIRED_ERROR);
@@ -186,8 +196,17 @@ export class BaseAppsClient {
       headers["Authorization"] = `Bearer ${token}`;
     }
 
-    if (isBackend && !isSSR && this.config.tacoreServerInteropAppServerApiKey) {
+    if (
+      isBackend &&
+      !isSSR &&
+      !token &&
+      this.config.enableAppServerServiceAuth === true &&
+      this.config.tacoreServerInteropAppServerApiKey &&
+      this.config.tacoreAppServerServiceToken
+    ) {
       headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
+      headers[APP_SERVER_SERVICE_TOKEN_HEADER] = this.config.tacoreAppServerServiceToken;
+      headers[APP_SERVER_OWNER_APP_ID_HEADER] = this.config.appServerOwnerAppId || this.config.appId || process.env.APP_ID || this.appId;
     } else if (
       isBackendPreviewMode() &&
       !token &&

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.22.0",
+  "version": "1.22.1-beta.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -13,6 +13,7 @@
     "./app-server-runtime": "./database/core/apps/AppServerRuntime.js"
   },
   "scripts": {
-    "release": "npm version minor && git commit -am \"web-sdk update version\" && npm publish"
+    "release": "npm version minor && git commit -am \"web-sdk update version\" && git push && npm publish",
+    "release:beta": "npm version prerelease --preid beta --no-git-tag-version && git commit -am \"web-sdk update beta version\" && npm publish --tag beta"
   }
 }