chatablex-web-sdk 1.0.3 → 1.0.32

package/README.md

@@ -1,5 +1,11 @@
 # ChatableX Web SDK
 
+[![license](https://img.shields.io/npm/l/chatablex-web-sdk.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/blob/main/package.json)
+[![npm version](https://img.shields.io/npm/v/chatablex-web-sdk.svg?style=flat-square)](https://www.npmjs.com/package/chatablex-web-sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/chatablex/chatablex-web-sdk/ci.yml?branch=main&label=Build%20%26%20Test&logo=github)](https://github.com/chatablex/chatablex-web-sdk/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/pulls)
+
 English | [**简体中文**](README.zh-CN.md)
 
 **Runtime SDK for building ChatableX AI App WebUI extensions.**
@@ -27,6 +33,8 @@ Your WebUI runs inside a WebView. Many capabilities — native dialogs, file pic
   - [sdk.storage](#sdkstorage)
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
+  - [sdk.auth](#sdkauth)
+  - [sdk.cloud](#sdkcloud)
 - [Events Reference](#events-reference)
 - [Permissions](#permissions)
 - [Host Capability Matrix](#host-capability-matrix)
@@ -533,6 +541,111 @@ Throws if `targetUrl` is empty or whitespace-only.
 
 ---
 
+### `sdk.auth`
+
+Unified authentication for **every** WebUI app. In a hosted (Flutter WebView)
+environment it transparently reuses the desktop login session — your app writes
+**zero** login/token code. Just call `getAuthHeaders()` and attach it to your
+`fetch`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getToken` | `() => Promise<AuthTokenData \| null>` | Get a valid token (cached, refreshed on demand). `null` when not authenticated. |
+| `getAuthHeaders` | `() => Promise<Record<string,string>>` | `{ Authorization: "Bearer <token>" }`, or `{}` when not authenticated. |
+| `getUserId` | `() => string \| null` | Authenticated user id (sync, cache only). |
+| `isAuthenticated` | `() => boolean` | Whether a valid token is cached (sync). |
+| `refresh` | `() => Promise<boolean>` | Force a refresh via the host. Concurrent calls are merged (single-flight). |
+
+```ts
+// Attach the host login session to any authenticated request — no login code.
+const res = await fetch('https://api.example.com/scenes', {
+  headers: {
+    'Content-Type': 'application/json',
+    ...(await sdk.auth.getAuthHeaders()),
+  },
+});
+
+if (!sdk.auth.isAuthenticated()) {
+  // not logged in / not hosted — disable features that need auth
+}
+
+// On a 401 from your backend, force a refresh and retry once:
+if (res.status === 401 && (await sdk.auth.refresh())) {
+  // retry with await sdk.auth.getAuthHeaders()
+}
+```
+
+**Behavior & guarantees**
+
+- **Token is in-memory only.** The `refresh_token` never crosses the bridge.
+- **Pre-emptive refresh.** The host refreshes the `access_token` before sending
+  when it is expired or near expiry, so you normally never see an expired token.
+- **Safe degradation.** Outside a WebView, or when the host is logged out,
+  `getAuthHeaders()` resolves to `{}` and never throws.
+- **Pluggable provider.** Today only `HostAuthProvider` (WebView) is wired up; a
+  future browser/unified-login provider will slot in without changing your code.
+
+---
+
+### `sdk.cloud`
+
+Unified cloud storage for **all** WebUI apps — keep user files saved across
+devices without losing them. The SDK handles uploads, downloads, and retries;
+you just call the methods. The `appId` (from `ChatableX.init`) is added
+automatically, and each app's data is isolated so files never get mixed up.
+
+> Requires: (1) the user is signed in (`sdk.auth`); (2) a configured cloud
+> storage URL — pass `ChatableX.init({ apiBaseUrl })` (in a hosted environment
+> ChatableX can also provide it automatically). Uploading is a **paid
+> capability**: the user must purchase the corresponding tool before uploading,
+> otherwise the upload is rejected.
+
+| Method | Signature | Notes |
+|--------|-----------|-------|
+| `upload` | `(fileKey, data, opts?) => Promise<CloudUploadResult>` | Upload (overwrite). `data` accepts `Blob`/`ArrayBuffer`/`TypedArray`/`string`. |
+| `download` | `(fileKey) => Promise<Blob>` | Download a file's bytes. |
+| `getDownloadUrl` | `(fileKey) => Promise<string>` | Short-lived download URL (e.g. for `<img src>`). |
+| `list` | `(opts?) => Promise<CloudFileInfo[]>` | List this app's files for the user; filter by `prefix`. |
+| `delete` | `(fileKey) => Promise<void>` | Delete a file. |
+| `usage` | `() => Promise<CloudUsage>` | Read the account's storage usage / quota. |
+
+```ts
+const sdk = await ChatableX.init({
+  appId: 'math-studio',
+  apiBaseUrl: import.meta.env.VITE_CHATABLEX_API_BASE,
+});
+
+await sdk.cloud.upload('scenes/abc/scene.json.gz', blob, { contentType: 'application/gzip' });
+const files = await sdk.cloud.list({ prefix: 'scenes/' });
+const bytes = await sdk.cloud.download('scenes/abc/scene.json.gz');
+await sdk.cloud.delete('scenes/abc/scene.json.gz');
+const { usedBytes, quotaBytes } = await sdk.cloud.usage();
+```
+
+**Error handling** (all `instanceof`-checkable, exported from the package root):
+
+```ts
+import {
+  CloudAuthRequiredError,         // not logged in
+  CloudSubscriptionRequiredError, // tool not purchased — prompt the user to buy it
+  CloudQuotaExceededError,        // over storage quota; has usedBytes / quotaBytes
+  CloudError,                     // other cloud errors; has code
+} from 'chatablex-web-sdk';
+```
+
+**Behavior & guarantees**
+
+- **Transparent auth.** Reuses `sdk.auth` internally; an expired session is
+  refreshed automatically and the request retried once. When the user is not
+  signed in it throws `CloudAuthRequiredError` and sends no request.
+- **Data isolation.** Each user's and each app's data is isolated; apps and
+  users can never read each other's files.
+- **Paid capability.** Uploading requires the user to have purchased the
+  corresponding tool; catch `CloudSubscriptionRequiredError` to drive a purchase
+  prompt.
+
+---
+
 ## Events Reference
 
 | Event | Payload | When fired |
@@ -576,6 +689,8 @@ SDK methods are thin RPC wrappers. Some host handlers are fully implemented; oth
 | `sdk.ui.pickFile` | **Production** | Requires `file_access` |
 | `sdk.ui.updateState` | **Production** | Delegates to host |
 | `sdk.platform.openInBrowser` | **Production** | Auth handoff |
+| `sdk.auth.*` | **Production** | Hosted: reuses desktop login via `host.getAuthToken` (pre-refresh) |
+| `sdk.cloud.*` | **Production** | Cloud file storage; needs `apiBaseUrl`, uploading requires purchasing the tool |
 | `sdk.ai.chat` | **Production** | Requires `ai_chat` + delegate |
 | `sdk.ai.getContext` | **Partial** | Returns minimal context |
 | `sdk.ai.chatStream` | **Partial** | Returns `{ streaming: true }`; tokens via events |

package/README.zh-CN.md

@@ -1,5 +1,11 @@
 # ChatableX Web SDK
 
+[![license](https://img.shields.io/npm/l/chatablex-web-sdk.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/blob/main/package.json)
+[![npm version](https://img.shields.io/npm/v/chatablex-web-sdk.svg?style=flat-square)](https://www.npmjs.com/package/chatablex-web-sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/chatablex/chatablex-web-sdk/ci.yml?branch=main&label=Build%20%26%20Test&logo=github)](https://github.com/chatablex/chatablex-web-sdk/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/pulls)
+
 **[English](README.md)** | 简体中文
 
 **用于构建 ChatableX AI App WebUI 扩展的官方运行时 SDK。**
@@ -27,6 +33,8 @@
   - [sdk.storage](#sdkstorage)
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
+  - [sdk.auth](#sdkauth)
+  - [sdk.cloud](#sdkcloud)
 - [事件参考](#事件参考)
 - [权限声明](#权限声明)
 - [宿主能力矩阵](#宿主能力矩阵)
@@ -533,6 +541,117 @@ await sdk.platform.openInBrowser('https://docs.example.com/guide');
 
 ---
 
+### `sdk.auth`
+
+面向**所有** WebUI 应用的统一鉴权入口。在宿主（Flutter WebView）环境下，它会
+透明复用桌面端的登录态——你的应用**无需编写任何登录/Token 代码**，只需调用
+`getAuthHeaders()` 并附加到 `fetch` 即可。
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `getToken` | `() => Promise<AuthTokenData \| null>` | 取有效 Token（内存缓存，按需刷新）；未登录返回 `null`。 |
+| `getAuthHeaders` | `() => Promise<Record<string,string>>` | 返回 `{ Authorization: "Bearer <token>" }`，未登录则返回 `{}`。 |
+| `getUserId` | `() => string \| null` | 当前登录用户 id（同步，仅读缓存）。 |
+| `isAuthenticated` | `() => boolean` | 是否已缓存有效 Token（同步）。 |
+| `refresh` | `() => Promise<boolean>` | 强制经宿主刷新；并发调用合并为一次（single-flight）。 |
+
+```ts
+// 给任意需要鉴权的请求附加宿主登录态——无需任何登录代码。
+const res = await fetch('https://api.example.com/scenes', {
+  headers: {
+    'Content-Type': 'application/json',
+    ...(await sdk.auth.getAuthHeaders()),
+  },
+});
+
+if (!sdk.auth.isAuthenticated()) {
+  // 未登录 / 非 WebView——禁用需要鉴权的功能
+}
+
+// 后端返回 401 时，强制刷新并重试一次：
+if (res.status === 401 && (await sdk.auth.refresh())) {
+  // 用 await sdk.auth.getAuthHeaders() 重试
+}
+```
+
+**行为与保证**
+
+- **Token 仅存内存。** `refresh_token` 永不经过 bridge。
+- **下发前刷新。** 宿主在 Token 过期或临近过期时会先刷新再下发，正常情况下你
+  不会拿到过期 Token。
+- **安全降级。** 在非 WebView 或宿主未登录时，`getAuthHeaders()` 返回 `{}` 且
+  不抛异常。
+- **Provider 可插拔。** 目前仅接入 `HostAuthProvider`（WebView）；未来的浏览器/
+  统一登录 provider 可无缝替换，消费方代码无需改动。
+
+---
+
+### `sdk.cloud`
+
+面向**所有** WebUI 应用的统一云存储，让用户文件跨设备保存、不丢失。上传、下载、
+重试等细节都由 SDK 处理，你只管调方法。`appId`（来自 `ChatableX.init`）会自动带上，
+每个应用的数据互相隔离，不会串。
+
+> 需要：(1) 用户已登录（`sdk.auth`）；(2) 已配置云存储服务地址——在
+> `ChatableX.init({ apiBaseUrl })` 传入（宿主环境下也可由 ChatableX 自动提供）。
+> 上传是**付费能力**：用户需购买对应工具后才能上传，未购买时上传会被拒绝。
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `upload` | `(fileKey, data, opts?) => Promise<CloudUploadResult>` | 上传（覆盖写）。`data` 支持 `Blob`/`ArrayBuffer`/`TypedArray`/`string`。 |
+| `download` | `(fileKey) => Promise<Blob>` | 下载文件字节。 |
+| `getDownloadUrl` | `(fileKey) => Promise<string>` | 获取短期有效的下载链接（如喂给 `<img src>`）。 |
+| `list` | `(opts?) => Promise<CloudFileInfo[]>` | 列出当前应用在该用户下的文件，可按 `prefix` 过滤。 |
+| `delete` | `(fileKey) => Promise<void>` | 删除文件。 |
+| `usage` | `() => Promise<CloudUsage>` | 读取账户存储用量/配额。 |
+
+```ts
+const sdk = await ChatableX.init({
+  appId: 'math-studio',
+  apiBaseUrl: import.meta.env.VITE_CHATABLEX_API_BASE,
+});
+
+// 上传（app_id 自动注入，无需手动传）
+await sdk.cloud.upload('scenes/abc/scene.json.gz', blob, { contentType: 'application/gzip' });
+
+// 列表 / 下载 / 删除 / 用量
+const files = await sdk.cloud.list({ prefix: 'scenes/' });
+const bytes = await sdk.cloud.download('scenes/abc/scene.json.gz');
+await sdk.cloud.delete('scenes/abc/scene.json.gz');
+const { usedBytes, quotaBytes } = await sdk.cloud.usage();
+```
+
+**错误处理**（均可 `instanceof` 判断，从包根导出）：
+
+```ts
+import {
+  CloudAuthRequiredError,        // 未登录：提示登录 ChatableX
+  CloudSubscriptionRequiredError, // 未购买：引导用户购买工具
+  CloudQuotaExceededError,        // 超出存储配额，含 usedBytes / quotaBytes
+  CloudError,                     // 其他云存储错误，含 code
+} from 'chatablex-web-sdk';
+
+try {
+  await sdk.cloud.upload('big.bin', buf);
+} catch (e) {
+  if (e instanceof CloudSubscriptionRequiredError) {/* 弹出购买引导 */}
+  else if (e instanceof CloudQuotaExceededError) {/* 提示清理 / 升级，e.usedBytes/e.quotaBytes */}
+  else if (e instanceof CloudAuthRequiredError) {/* 提示登录 */}
+  else throw e;
+}
+```
+
+**行为与保证**
+
+- **鉴权透明。** 内部复用 `sdk.auth`，登录态过期会自动刷新并重试一次；用户未登录
+  时直接抛 `CloudAuthRequiredError`，不会发出无效请求。
+- **数据隔离。** 每个用户、每个应用的数据互相隔离，应用之间、用户之间都不会读到
+  对方的文件。
+- **付费能力。** 上传需用户已购买对应工具；通过捕获
+  `CloudSubscriptionRequiredError` 引导用户购买。
+
+---
+
 ## 事件参考
 
 | 事件 | 载荷 | 触发时机 |
@@ -576,6 +695,8 @@ SDK 方法是薄 RPC 封装。部分宿主处理器已完整实现，部分返
 | `sdk.ui.pickFile` | **生产可用** | 需要 `file_access` |
 | `sdk.ui.updateState` | **生产可用** | 委托给宿主 |
 | `sdk.platform.openInBrowser` | **生产可用** | 鉴权传递 |
+| `sdk.auth.*` | **生产可用** | 宿主态：经 `host.getAuthToken` 复用桌面登录（下发前刷新） |
+| `sdk.cloud.*` | **生产可用** | 云端文件存储；需配置 `apiBaseUrl`，上传需购买对应工具 |
 | `sdk.ai.chat` | **生产可用** | 需要 `ai_chat` + delegate |
 | `sdk.ai.getContext` | **部分实现** | 返回最小上下文 |
 | `sdk.ai.chatStream` | **部分实现** | 返回 `{ streaming: true }`；token 走事件 |

package/dist/index.d.mts

@@ -119,6 +119,14 @@ interface ChatableXInitConfig {
     debug?: boolean;
     /** Timeout in ms for the handshake with Flutter (default: 10000) */
     timeout?: number;
+    /**
+     * Base URL of the ChatableX cloud API (auth-fc), e.g.
+     * `https://chatabl-fc-prod-xxxx.cn-hangzhou.fcapp.run`. Required for
+     * `sdk.cloud` to work. When omitted, the SDK best-effort asks the host via
+     * the `host.getApiBaseUrl` bridge call; if that is also unavailable, cloud
+     * calls reject with a clear error.
+     */
+    apiBaseUrl?: string;
 }
 interface ChatableXAI {
     chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
@@ -156,6 +164,103 @@ interface ChatableXPlatform {
     /** Open URL in system browser with auth handoff (WebView only; implemented by Flutter host). */
     openInBrowser(targetUrl: string): Promise<void>;
 }
+/** Token payload returned by the host (never includes the refresh_token). */
+interface AuthTokenData {
+    /** Bearer access token to put in the Authorization header. */
+    access_token: string;
+    /** Access token expiry, epoch milliseconds. */
+    expires_at: number;
+    /** Authenticated user id. */
+    user_id: string;
+}
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+interface ChatableXAuth {
+    /**
+     * Get a valid access token. Returns the in-memory cached token when still
+     * valid, otherwise fetches a fresh one from the host. Returns `null` when
+     * not authenticated / not hosted.
+     */
+    getToken(): Promise<AuthTokenData | null>;
+    /**
+     * Build auth headers ready to spread into a `fetch`. Returns
+     * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+    getUserId(): string | null;
+    /** Whether a valid token is currently cached. Synchronous (cache only). */
+    isAuthenticated(): boolean;
+    /** Force a token refresh via the host. Resolves `true` on success. */
+    refresh(): Promise<boolean>;
+}
+/** Binary payload accepted by `sdk.cloud.upload`. */
+type CloudUploadData = Blob | ArrayBuffer | ArrayBufferView | string;
+interface CloudUploadOptions {
+    /**
+     * MIME type to store the object as. Defaults to the `Blob.type` when a Blob
+     * is given, otherwise `application/octet-stream`. Must be one allowed by the
+     * server's content-type whitelist.
+     */
+    contentType?: string;
+}
+/** Result of a successful `sdk.cloud.upload`. */
+interface CloudUploadResult {
+    /** App-relative key (the same `fileKey` passed to `upload`). */
+    fileKey: string;
+    /** Fully-qualified OSS object key (`user-data/{user_id}/{app_id}/{fileKey}`). */
+    objectKey: string;
+    /** Bytes uploaded. */
+    size: number;
+    /** MIME type the object was stored as. */
+    contentType: string;
+}
+/** A single file in the user's cloud storage for this app. */
+interface CloudFileInfo {
+    fileKey: string;
+    size: number;
+    /** ISO-8601 timestamp. */
+    lastModified: string;
+}
+interface CloudListOptions {
+    /** Restrict the listing to keys under this app-relative prefix. */
+    prefix?: string;
+}
+/** The user's storage usage / quota for the whole account. */
+interface CloudUsage {
+    usedBytes: number;
+    quotaBytes: number;
+    fileCount: number;
+    /** ISO-8601 timestamp of the last server-side reconciliation, if any. */
+    reconciledAt?: string;
+}
+/**
+ * Cloud storage for WebUI apps. Backed by auth-fc presigned OSS URLs; the
+ * app's `appId` (from `ChatableX.init`) is injected automatically so every key
+ * is namespaced to `{user}/{app}` and apps cannot reach into each other's data.
+ *
+ * Requires an authenticated session (`sdk.auth`) and a configured cloud API
+ * base URL (see `ChatableXInitConfig.apiBaseUrl`).
+ */
+interface ChatableXCloud {
+    /** Upload (overwrite) a file. Resolves once the bytes are stored in OSS. */
+    upload(fileKey: string, data: CloudUploadData, options?: CloudUploadOptions): Promise<CloudUploadResult>;
+    /** Download a file's bytes as a Blob. */
+    download(fileKey: string): Promise<Blob>;
+    /** Get a short-lived presigned GET URL (e.g. to feed an `<img src>`). */
+    getDownloadUrl(fileKey: string): Promise<string>;
+    /** List the current app's files for this user. */
+    list(options?: CloudListOptions): Promise<CloudFileInfo[]>;
+    /** Delete a file. Resolves even if the object did not exist. */
+    delete(fileKey: string): Promise<void>;
+    /** Read the account's storage usage / quota. */
+    usage(): Promise<CloudUsage>;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -164,6 +269,8 @@ interface ChatableXSDK {
     storage: ChatableXStorage;
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
+    auth: ChatableXAuth;
+    cloud: ChatableXCloud;
 }
 declare global {
     interface Window {
@@ -210,6 +317,33 @@ declare class Bridge {
     destroy(): void;
 }
 
+/** Base error for all `sdk.cloud` failures. */
+declare class CloudError extends Error {
+    /** Business code from auth-fc (or the HTTP status when none was returned). */
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/**
+ * Thrown when no authenticated session is available. The app should prompt the
+ * user to log in to ChatableX before retrying.
+ */
+declare class CloudAuthRequiredError extends CloudError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the user lacks the entitlement (purchased tool / membership)
+ * required to write to cloud storage. Maps to auth-fc code `40302`.
+ */
+declare class CloudSubscriptionRequiredError extends CloudError {
+    constructor(message?: string);
+}
+/** Thrown when the upload would exceed the user's storage quota (code `40301`). */
+declare class CloudQuotaExceededError extends CloudError {
+    readonly usedBytes: number;
+    readonly quotaBytes: number;
+    constructor(usedBytes: number, quotaBytes: number, message?: string);
+}
+
 /**
  * chatablex-web-sdk
  *
@@ -252,4 +386,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };
+export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, type ChatableXCloud, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, CloudAuthRequiredError, CloudError, type CloudFileInfo, type CloudListOptions, CloudQuotaExceededError, CloudSubscriptionRequiredError, type CloudUploadData, type CloudUploadOptions, type CloudUploadResult, type CloudUsage, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };

package/dist/index.d.ts

@@ -119,6 +119,14 @@ interface ChatableXInitConfig {
     debug?: boolean;
     /** Timeout in ms for the handshake with Flutter (default: 10000) */
     timeout?: number;
+    /**
+     * Base URL of the ChatableX cloud API (auth-fc), e.g.
+     * `https://chatabl-fc-prod-xxxx.cn-hangzhou.fcapp.run`. Required for
+     * `sdk.cloud` to work. When omitted, the SDK best-effort asks the host via
+     * the `host.getApiBaseUrl` bridge call; if that is also unavailable, cloud
+     * calls reject with a clear error.
+     */
+    apiBaseUrl?: string;
 }
 interface ChatableXAI {
     chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
@@ -156,6 +164,103 @@ interface ChatableXPlatform {
     /** Open URL in system browser with auth handoff (WebView only; implemented by Flutter host). */
     openInBrowser(targetUrl: string): Promise<void>;
 }
+/** Token payload returned by the host (never includes the refresh_token). */
+interface AuthTokenData {
+    /** Bearer access token to put in the Authorization header. */
+    access_token: string;
+    /** Access token expiry, epoch milliseconds. */
+    expires_at: number;
+    /** Authenticated user id. */
+    user_id: string;
+}
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+interface ChatableXAuth {
+    /**
+     * Get a valid access token. Returns the in-memory cached token when still
+     * valid, otherwise fetches a fresh one from the host. Returns `null` when
+     * not authenticated / not hosted.
+     */
+    getToken(): Promise<AuthTokenData | null>;
+    /**
+     * Build auth headers ready to spread into a `fetch`. Returns
+     * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+    getUserId(): string | null;
+    /** Whether a valid token is currently cached. Synchronous (cache only). */
+    isAuthenticated(): boolean;
+    /** Force a token refresh via the host. Resolves `true` on success. */
+    refresh(): Promise<boolean>;
+}
+/** Binary payload accepted by `sdk.cloud.upload`. */
+type CloudUploadData = Blob | ArrayBuffer | ArrayBufferView | string;
+interface CloudUploadOptions {
+    /**
+     * MIME type to store the object as. Defaults to the `Blob.type` when a Blob
+     * is given, otherwise `application/octet-stream`. Must be one allowed by the
+     * server's content-type whitelist.
+     */
+    contentType?: string;
+}
+/** Result of a successful `sdk.cloud.upload`. */
+interface CloudUploadResult {
+    /** App-relative key (the same `fileKey` passed to `upload`). */
+    fileKey: string;
+    /** Fully-qualified OSS object key (`user-data/{user_id}/{app_id}/{fileKey}`). */
+    objectKey: string;
+    /** Bytes uploaded. */
+    size: number;
+    /** MIME type the object was stored as. */
+    contentType: string;
+}
+/** A single file in the user's cloud storage for this app. */
+interface CloudFileInfo {
+    fileKey: string;
+    size: number;
+    /** ISO-8601 timestamp. */
+    lastModified: string;
+}
+interface CloudListOptions {
+    /** Restrict the listing to keys under this app-relative prefix. */
+    prefix?: string;
+}
+/** The user's storage usage / quota for the whole account. */
+interface CloudUsage {
+    usedBytes: number;
+    quotaBytes: number;
+    fileCount: number;
+    /** ISO-8601 timestamp of the last server-side reconciliation, if any. */
+    reconciledAt?: string;
+}
+/**
+ * Cloud storage for WebUI apps. Backed by auth-fc presigned OSS URLs; the
+ * app's `appId` (from `ChatableX.init`) is injected automatically so every key
+ * is namespaced to `{user}/{app}` and apps cannot reach into each other's data.
+ *
+ * Requires an authenticated session (`sdk.auth`) and a configured cloud API
+ * base URL (see `ChatableXInitConfig.apiBaseUrl`).
+ */
+interface ChatableXCloud {
+    /** Upload (overwrite) a file. Resolves once the bytes are stored in OSS. */
+    upload(fileKey: string, data: CloudUploadData, options?: CloudUploadOptions): Promise<CloudUploadResult>;
+    /** Download a file's bytes as a Blob. */
+    download(fileKey: string): Promise<Blob>;
+    /** Get a short-lived presigned GET URL (e.g. to feed an `<img src>`). */
+    getDownloadUrl(fileKey: string): Promise<string>;
+    /** List the current app's files for this user. */
+    list(options?: CloudListOptions): Promise<CloudFileInfo[]>;
+    /** Delete a file. Resolves even if the object did not exist. */
+    delete(fileKey: string): Promise<void>;
+    /** Read the account's storage usage / quota. */
+    usage(): Promise<CloudUsage>;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -164,6 +269,8 @@ interface ChatableXSDK {
     storage: ChatableXStorage;
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
+    auth: ChatableXAuth;
+    cloud: ChatableXCloud;
 }
 declare global {
     interface Window {
@@ -210,6 +317,33 @@ declare class Bridge {
     destroy(): void;
 }
 
+/** Base error for all `sdk.cloud` failures. */
+declare class CloudError extends Error {
+    /** Business code from auth-fc (or the HTTP status when none was returned). */
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/**
+ * Thrown when no authenticated session is available. The app should prompt the
+ * user to log in to ChatableX before retrying.
+ */
+declare class CloudAuthRequiredError extends CloudError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the user lacks the entitlement (purchased tool / membership)
+ * required to write to cloud storage. Maps to auth-fc code `40302`.
+ */
+declare class CloudSubscriptionRequiredError extends CloudError {
+    constructor(message?: string);
+}
+/** Thrown when the upload would exceed the user's storage quota (code `40301`). */
+declare class CloudQuotaExceededError extends CloudError {
+    readonly usedBytes: number;
+    readonly quotaBytes: number;
+    constructor(usedBytes: number, quotaBytes: number, message?: string);
+}
+
 /**
  * chatablex-web-sdk
  *
@@ -252,4 +386,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };
+export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, type ChatableXCloud, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, CloudAuthRequiredError, CloudError, type CloudFileInfo, type CloudListOptions, CloudQuotaExceededError, CloudSubscriptionRequiredError, type CloudUploadData, type CloudUploadOptions, type CloudUploadResult, type CloudUsage, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };