chatablex-web-sdk 1.0.31 → 1.0.32

package/README.md

@@ -34,6 +34,7 @@ Your WebUI runs inside a WebView. Many capabilities — native dialogs, file pic
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
   - [sdk.auth](#sdkauth)
+  - [sdk.cloud](#sdkcloud)
 - [Events Reference](#events-reference)
 - [Permissions](#permissions)
 - [Host Capability Matrix](#host-capability-matrix)
@@ -586,6 +587,65 @@ if (res.status === 401 && (await sdk.auth.refresh())) {
 
 ---
 
+### `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 |
@@ -630,6 +690,7 @@ SDK methods are thin RPC wrappers. Some host handlers are fully implemented; oth
 | `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

@@ -34,6 +34,7 @@
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
   - [sdk.auth](#sdkauth)
+  - [sdk.cloud](#sdkcloud)
 - [事件参考](#事件参考)
 - [权限声明](#权限声明)
 - [宿主能力矩阵](#宿主能力矩阵)
@@ -585,6 +586,72 @@ if (res.status === 401 && (await sdk.auth.refresh())) {
 
 ---
 
+### `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` 引导用户购买。
+
+---
+
 ## 事件参考
 
 | 事件 | 载荷 | 触发时机 |
@@ -629,6 +696,7 @@ SDK 方法是薄 RPC 封装。部分宿主处理器已完整实现，部分返
 | `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>;
@@ -191,6 +199,68 @@ interface ChatableXAuth {
     /** 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;
@@ -200,6 +270,7 @@ interface ChatableXSDK {
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
     auth: ChatableXAuth;
+    cloud: ChatableXCloud;
 }
 declare global {
     interface Window {
@@ -246,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
  *
@@ -288,4 +386,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, 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>;
@@ -191,6 +199,68 @@ interface ChatableXAuth {
     /** 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;
@@ -200,6 +270,7 @@ interface ChatableXSDK {
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
     auth: ChatableXAuth;
+    cloud: ChatableXCloud;
 }
 declare global {
     interface Window {
@@ -246,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
  *
@@ -288,4 +386,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, 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.js

@@ -22,6 +22,10 @@ var index_exports = {};
 __export(index_exports, {
   Bridge: () => Bridge,
   ChatableX: () => ChatableX,
+  CloudAuthRequiredError: () => CloudAuthRequiredError,
+  CloudError: () => CloudError,
+  CloudQuotaExceededError: () => CloudQuotaExceededError,
+  CloudSubscriptionRequiredError: () => CloudSubscriptionRequiredError,
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(index_exports);
@@ -357,10 +361,188 @@ function createAuthModule(bridge) {
   return new HostAuthProvider(bridge);
 }
 
+// src/modules/cloud.ts
+var CloudError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "CloudError";
+    this.code = code;
+  }
+};
+var CloudAuthRequiredError = class extends CloudError {
+  constructor(message = "cloud storage requires an authenticated session") {
+    super(message, 401);
+    this.name = "CloudAuthRequiredError";
+  }
+};
+var CloudSubscriptionRequiredError = class extends CloudError {
+  constructor(message = "cloud storage requires an active subscription") {
+    super(message, 40302);
+    this.name = "CloudSubscriptionRequiredError";
+  }
+};
+var CloudQuotaExceededError = class extends CloudError {
+  constructor(usedBytes, quotaBytes, message = "storage quota exceeded") {
+    super(message, 40301);
+    this.name = "CloudQuotaExceededError";
+    this.usedBytes = usedBytes;
+    this.quotaBytes = quotaBytes;
+  }
+};
+var DEFAULT_CONTENT_TYPE = "application/octet-stream";
+function normalizeData(data) {
+  if (typeof Blob !== "undefined" && data instanceof Blob) {
+    return { body: data, size: data.size, type: data.type || "" };
+  }
+  if (typeof data === "string") {
+    const blob = new Blob([data]);
+    return { body: blob, size: blob.size, type: "" };
+  }
+  if (data instanceof ArrayBuffer) {
+    return { body: data, size: data.byteLength, type: "" };
+  }
+  if (ArrayBuffer.isView(data)) {
+    return { body: data, size: data.byteLength, type: "" };
+  }
+  throw new CloudError("unsupported upload data type", 400);
+}
+function createCloudModule(bridge, deps) {
+  const { appId, auth } = deps;
+  let resolvedBase = deps.apiBaseUrl ? stripTrailingSlash(deps.apiBaseUrl) : null;
+  function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+  }
+  async function baseUrl() {
+    if (resolvedBase) return resolvedBase;
+    try {
+      const r = await bridge.sendMessage("host.getApiBaseUrl", {}, 5e3);
+      const url = typeof r === "string" ? r : r && typeof r === "object" && typeof r.base_url === "string" ? r.base_url : "";
+      if (url) {
+        resolvedBase = stripTrailingSlash(url);
+        return resolvedBase;
+      }
+    } catch {
+    }
+    throw new CloudError(
+      "cloud API base URL is not configured; pass apiBaseUrl to ChatableX.init()",
+      0
+    );
+  }
+  async function authedFetch(path, init) {
+    const token = await auth.getToken();
+    if (!token) throw new CloudAuthRequiredError();
+    const base = await baseUrl();
+    const url = `${base}${path}`;
+    const build = async () => ({
+      ...init,
+      headers: { ...init.headers ?? {}, ...await auth.getAuthHeaders() }
+    });
+    let res = await fetch(url, await build());
+    if (res.status === 401 && await auth.refresh()) {
+      res = await fetch(url, await build());
+    }
+    return res;
+  }
+  async function callApi(path, init) {
+    const res = await authedFetch(path, init);
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+    }
+    const code = body?.code;
+    const message = body?.message || `HTTP ${res.status}`;
+    if (!res.ok || body?.success === false) {
+      if (code === 40301) {
+        const q = body?.data ?? {};
+        throw new CloudQuotaExceededError(q.used_bytes ?? 0, q.quota_bytes ?? 0, message);
+      }
+      if (code === 40302) throw new CloudSubscriptionRequiredError(message);
+      if (res.status === 401) throw new CloudAuthRequiredError(message);
+      throw new CloudError(message, code ?? res.status);
+    }
+    return body?.data ?? null;
+  }
+  function validateFileKey(fileKey) {
+    if (!fileKey || typeof fileKey !== "string") {
+      throw new CloudError("fileKey is required", 400);
+    }
+  }
+  return {
+    async upload(fileKey, data, options = {}) {
+      validateFileKey(fileKey);
+      const { body, size, type } = normalizeData(data);
+      const contentType = options.contentType || type || DEFAULT_CONTENT_TYPE;
+      const signed = await callApi("/api/storage/upload-url", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: appId,
+          file_key: fileKey,
+          content_type: contentType,
+          size_bytes: size
+        })
+      });
+      const put = await fetch(signed.upload_url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body
+      });
+      if (!put.ok) {
+        throw new CloudError(`OSS upload failed: HTTP ${put.status}`, put.status);
+      }
+      return { fileKey, objectKey: signed.object_key, size, contentType };
+    },
+    async getDownloadUrl(fileKey) {
+      validateFileKey(fileKey);
+      const signed = await callApi("/api/storage/download-url", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ app_id: appId, file_key: fileKey })
+      });
+      return signed.download_url;
+    },
+    async download(fileKey) {
+      const url = await this.getDownloadUrl(fileKey);
+      const res = await fetch(url, { method: "GET" });
+      if (!res.ok) {
+        throw new CloudError(`OSS download failed: HTTP ${res.status}`, res.status);
+      }
+      return res.blob();
+    },
+    async list(options = {}) {
+      const qs = new URLSearchParams({ app_id: appId });
+      if (options.prefix) qs.set("prefix", options.prefix);
+      const data = await callApi(`/api/storage/files?${qs.toString()}`, {
+        method: "GET"
+      });
+      return (data?.files ?? []).map((f) => ({
+        fileKey: f.file_key,
+        size: f.size,
+        lastModified: f.last_modified
+      }));
+    },
+    async delete(fileKey) {
+      validateFileKey(fileKey);
+      const qs = new URLSearchParams({ app_id: appId, file_key: fileKey });
+      await callApi(`/api/storage/files?${qs.toString()}`, { method: "DELETE" });
+    },
+    async usage() {
+      const data = await callApi("/api/storage/usage", { method: "GET" });
+      return {
+        usedBytes: data.used_bytes,
+        quotaBytes: data.quota_bytes,
+        fileCount: data.file_count,
+        reconciledAt: data.reconciled_at
+      };
+    }
+  };
+}
+
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.31",
+  version: "1.0.32",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -452,6 +634,7 @@ var ChatableX = {
     }
     const toolModule = createToolModule(bridge, config.appId);
     if (toolConfig) toolModule._setInfo(toolConfig);
+    const authModule = createAuthModule(bridge);
     const sdk = {
       ai: createAIModule(bridge),
       tools: createToolsModule(bridge),
@@ -460,7 +643,12 @@ var ChatableX = {
       storage: createStorageModule(bridge),
       tool: toolModule,
       platform: createPlatformModule(bridge),
-      auth: createAuthModule(bridge)
+      auth: authModule,
+      cloud: createCloudModule(bridge, {
+        appId: config.appId,
+        auth: authModule,
+        apiBaseUrl: config.apiBaseUrl
+      })
     };
     window.ChatableX = sdk;
     _instance = sdk;
@@ -483,5 +671,9 @@ var ChatableX = {
 0 && (module.exports = {
   Bridge,
   ChatableX,
+  CloudAuthRequiredError,
+  CloudError,
+  CloudQuotaExceededError,
+  CloudSubscriptionRequiredError,
   SDK_VERSION
 });

package/dist/index.mjs

@@ -329,10 +329,188 @@ function createAuthModule(bridge) {
   return new HostAuthProvider(bridge);
 }
 
+// src/modules/cloud.ts
+var CloudError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "CloudError";
+    this.code = code;
+  }
+};
+var CloudAuthRequiredError = class extends CloudError {
+  constructor(message = "cloud storage requires an authenticated session") {
+    super(message, 401);
+    this.name = "CloudAuthRequiredError";
+  }
+};
+var CloudSubscriptionRequiredError = class extends CloudError {
+  constructor(message = "cloud storage requires an active subscription") {
+    super(message, 40302);
+    this.name = "CloudSubscriptionRequiredError";
+  }
+};
+var CloudQuotaExceededError = class extends CloudError {
+  constructor(usedBytes, quotaBytes, message = "storage quota exceeded") {
+    super(message, 40301);
+    this.name = "CloudQuotaExceededError";
+    this.usedBytes = usedBytes;
+    this.quotaBytes = quotaBytes;
+  }
+};
+var DEFAULT_CONTENT_TYPE = "application/octet-stream";
+function normalizeData(data) {
+  if (typeof Blob !== "undefined" && data instanceof Blob) {
+    return { body: data, size: data.size, type: data.type || "" };
+  }
+  if (typeof data === "string") {
+    const blob = new Blob([data]);
+    return { body: blob, size: blob.size, type: "" };
+  }
+  if (data instanceof ArrayBuffer) {
+    return { body: data, size: data.byteLength, type: "" };
+  }
+  if (ArrayBuffer.isView(data)) {
+    return { body: data, size: data.byteLength, type: "" };
+  }
+  throw new CloudError("unsupported upload data type", 400);
+}
+function createCloudModule(bridge, deps) {
+  const { appId, auth } = deps;
+  let resolvedBase = deps.apiBaseUrl ? stripTrailingSlash(deps.apiBaseUrl) : null;
+  function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+  }
+  async function baseUrl() {
+    if (resolvedBase) return resolvedBase;
+    try {
+      const r = await bridge.sendMessage("host.getApiBaseUrl", {}, 5e3);
+      const url = typeof r === "string" ? r : r && typeof r === "object" && typeof r.base_url === "string" ? r.base_url : "";
+      if (url) {
+        resolvedBase = stripTrailingSlash(url);
+        return resolvedBase;
+      }
+    } catch {
+    }
+    throw new CloudError(
+      "cloud API base URL is not configured; pass apiBaseUrl to ChatableX.init()",
+      0
+    );
+  }
+  async function authedFetch(path, init) {
+    const token = await auth.getToken();
+    if (!token) throw new CloudAuthRequiredError();
+    const base = await baseUrl();
+    const url = `${base}${path}`;
+    const build = async () => ({
+      ...init,
+      headers: { ...init.headers ?? {}, ...await auth.getAuthHeaders() }
+    });
+    let res = await fetch(url, await build());
+    if (res.status === 401 && await auth.refresh()) {
+      res = await fetch(url, await build());
+    }
+    return res;
+  }
+  async function callApi(path, init) {
+    const res = await authedFetch(path, init);
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+    }
+    const code = body?.code;
+    const message = body?.message || `HTTP ${res.status}`;
+    if (!res.ok || body?.success === false) {
+      if (code === 40301) {
+        const q = body?.data ?? {};
+        throw new CloudQuotaExceededError(q.used_bytes ?? 0, q.quota_bytes ?? 0, message);
+      }
+      if (code === 40302) throw new CloudSubscriptionRequiredError(message);
+      if (res.status === 401) throw new CloudAuthRequiredError(message);
+      throw new CloudError(message, code ?? res.status);
+    }
+    return body?.data ?? null;
+  }
+  function validateFileKey(fileKey) {
+    if (!fileKey || typeof fileKey !== "string") {
+      throw new CloudError("fileKey is required", 400);
+    }
+  }
+  return {
+    async upload(fileKey, data, options = {}) {
+      validateFileKey(fileKey);
+      const { body, size, type } = normalizeData(data);
+      const contentType = options.contentType || type || DEFAULT_CONTENT_TYPE;
+      const signed = await callApi("/api/storage/upload-url", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: appId,
+          file_key: fileKey,
+          content_type: contentType,
+          size_bytes: size
+        })
+      });
+      const put = await fetch(signed.upload_url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body
+      });
+      if (!put.ok) {
+        throw new CloudError(`OSS upload failed: HTTP ${put.status}`, put.status);
+      }
+      return { fileKey, objectKey: signed.object_key, size, contentType };
+    },
+    async getDownloadUrl(fileKey) {
+      validateFileKey(fileKey);
+      const signed = await callApi("/api/storage/download-url", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ app_id: appId, file_key: fileKey })
+      });
+      return signed.download_url;
+    },
+    async download(fileKey) {
+      const url = await this.getDownloadUrl(fileKey);
+      const res = await fetch(url, { method: "GET" });
+      if (!res.ok) {
+        throw new CloudError(`OSS download failed: HTTP ${res.status}`, res.status);
+      }
+      return res.blob();
+    },
+    async list(options = {}) {
+      const qs = new URLSearchParams({ app_id: appId });
+      if (options.prefix) qs.set("prefix", options.prefix);
+      const data = await callApi(`/api/storage/files?${qs.toString()}`, {
+        method: "GET"
+      });
+      return (data?.files ?? []).map((f) => ({
+        fileKey: f.file_key,
+        size: f.size,
+        lastModified: f.last_modified
+      }));
+    },
+    async delete(fileKey) {
+      validateFileKey(fileKey);
+      const qs = new URLSearchParams({ app_id: appId, file_key: fileKey });
+      await callApi(`/api/storage/files?${qs.toString()}`, { method: "DELETE" });
+    },
+    async usage() {
+      const data = await callApi("/api/storage/usage", { method: "GET" });
+      return {
+        usedBytes: data.used_bytes,
+        quotaBytes: data.quota_bytes,
+        fileCount: data.file_count,
+        reconciledAt: data.reconciled_at
+      };
+    }
+  };
+}
+
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.31",
+  version: "1.0.32",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -424,6 +602,7 @@ var ChatableX = {
     }
     const toolModule = createToolModule(bridge, config.appId);
     if (toolConfig) toolModule._setInfo(toolConfig);
+    const authModule = createAuthModule(bridge);
     const sdk = {
       ai: createAIModule(bridge),
       tools: createToolsModule(bridge),
@@ -432,7 +611,12 @@ var ChatableX = {
       storage: createStorageModule(bridge),
       tool: toolModule,
       platform: createPlatformModule(bridge),
-      auth: createAuthModule(bridge)
+      auth: authModule,
+      cloud: createCloudModule(bridge, {
+        appId: config.appId,
+        auth: authModule,
+        apiBaseUrl: config.apiBaseUrl
+      })
     };
     window.ChatableX = sdk;
     _instance = sdk;
@@ -454,5 +638,9 @@ var ChatableX = {
 export {
   Bridge,
   ChatableX,
+  CloudAuthRequiredError,
+  CloudError,
+  CloudQuotaExceededError,
+  CloudSubscriptionRequiredError,
   SDK_VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatablex-web-sdk",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -27,6 +27,7 @@ import { createStorageModule } from './modules/storage';
 import { createToolsModule } from './modules/tools';
 import { createPlatformModule } from './modules/platform';
 import { createAuthModule } from './modules/auth';
+import { createCloudModule } from './modules/cloud';
 import type { ChatableXSDK, ChatableXInitConfig, ToolInfo } from './types';
 import pkg from '../package.json';
 
@@ -79,6 +80,8 @@ export const ChatableX = {
     const toolModule = createToolModule(bridge, config.appId);
     if (toolConfig) toolModule._setInfo(toolConfig);
 
+    const authModule = createAuthModule(bridge);
+
     const sdk: ChatableXSDK = {
       ai: createAIModule(bridge),
       tools: createToolsModule(bridge),
@@ -87,7 +90,12 @@ export const ChatableX = {
       storage: createStorageModule(bridge),
       tool: toolModule,
       platform: createPlatformModule(bridge),
-      auth: createAuthModule(bridge),
+      auth: authModule,
+      cloud: createCloudModule(bridge, {
+        appId: config.appId,
+        auth: authModule,
+        apiBaseUrl: config.apiBaseUrl,
+      }),
     };
 
     // Expose on window for debugging / Flutter interop
@@ -116,3 +124,9 @@ export const ChatableX = {
 // Re-export all types
 export * from './types';
 export { Bridge } from './bridge';
+export {
+  CloudError,
+  CloudAuthRequiredError,
+  CloudSubscriptionRequiredError,
+  CloudQuotaExceededError,
+} from './modules/cloud';

package/src/modules/cloud.ts

@@ -0,0 +1,297 @@
+import type { Bridge } from '../bridge';
+import type {
+  ChatableXAuth,
+  ChatableXCloud,
+  CloudFileInfo,
+  CloudListOptions,
+  CloudUploadData,
+  CloudUploadOptions,
+  CloudUploadResult,
+  CloudUsage,
+} from '../types';
+
+// ---------------------------------------------------------------------------
+// Errors (instanceof-checkable so apps can branch their UI)
+// ---------------------------------------------------------------------------
+
+/** Base error for all `sdk.cloud` failures. */
+export 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) {
+    super(message);
+    this.name = 'CloudError';
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown when no authenticated session is available. The app should prompt the
+ * user to log in to ChatableX before retrying.
+ */
+export class CloudAuthRequiredError extends CloudError {
+  constructor(message = 'cloud storage requires an authenticated session') {
+    super(message, 401);
+    this.name = 'CloudAuthRequiredError';
+  }
+}
+
+/**
+ * Thrown when the user lacks the entitlement (purchased tool / membership)
+ * required to write to cloud storage. Maps to auth-fc code `40302`.
+ */
+export class CloudSubscriptionRequiredError extends CloudError {
+  constructor(message = 'cloud storage requires an active subscription') {
+    super(message, 40302);
+    this.name = 'CloudSubscriptionRequiredError';
+  }
+}
+
+/** Thrown when the upload would exceed the user's storage quota (code `40301`). */
+export class CloudQuotaExceededError extends CloudError {
+  readonly usedBytes: number;
+  readonly quotaBytes: number;
+  constructor(usedBytes: number, quotaBytes: number, message = 'storage quota exceeded') {
+    super(message, 40301);
+    this.name = 'CloudQuotaExceededError';
+    this.usedBytes = usedBytes;
+    this.quotaBytes = quotaBytes;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+/** auth-fc response envelope: { success, code, message, data }. */
+interface ApiEnvelope<T> {
+  success?: boolean;
+  code?: number;
+  message?: string;
+  data?: T;
+}
+
+interface UploadURLData {
+  upload_url: string;
+  object_key: string;
+  expires_in: number;
+}
+interface DownloadURLData {
+  download_url: string;
+  object_key: string;
+  expires_in: number;
+}
+interface ListFilesData {
+  files: Array<{ file_key: string; size: number; last_modified: string }>;
+  total: number;
+}
+interface UsageData {
+  used_bytes: number;
+  quota_bytes: number;
+  file_count: number;
+  reconciled_at?: string;
+}
+interface QuotaErrorData {
+  used_bytes?: number;
+  quota_bytes?: number;
+}
+
+function normalizeData(data: CloudUploadData): { body: BodyInit; size: number; type: string } {
+  if (typeof Blob !== 'undefined' && data instanceof Blob) {
+    return { body: data, size: data.size, type: data.type || '' };
+  }
+  if (typeof data === 'string') {
+    const blob = new Blob([data]);
+    return { body: blob, size: blob.size, type: '' };
+  }
+  if (data instanceof ArrayBuffer) {
+    return { body: data, size: data.byteLength, type: '' };
+  }
+  if (ArrayBuffer.isView(data)) {
+    return { body: data as unknown as BodyInit, size: data.byteLength, type: '' };
+  }
+  throw new CloudError('unsupported upload data type', 400);
+}
+
+export interface CloudModuleDeps {
+  appId: string;
+  auth: ChatableXAuth;
+  /** Explicit cloud API base URL (overrides the host-provided one). */
+  apiBaseUrl?: string;
+}
+
+export function createCloudModule(bridge: Bridge, deps: CloudModuleDeps): ChatableXCloud {
+  const { appId, auth } = deps;
+  let resolvedBase: string | null = deps.apiBaseUrl ? stripTrailingSlash(deps.apiBaseUrl) : null;
+
+  function stripTrailingSlash(url: string): string {
+    return url.replace(/\/+$/, '');
+  }
+
+  /** Resolve the cloud API base URL: explicit config > host bridge > error. */
+  async function baseUrl(): Promise<string> {
+    if (resolvedBase) return resolvedBase;
+    try {
+      // Short timeout: a hosted-but-unimplemented method shouldn't hang the call.
+      const r = await bridge.sendMessage('host.getApiBaseUrl', {}, 5_000);
+      const url =
+        typeof r === 'string'
+          ? r
+          : r && typeof r === 'object' && typeof (r as { base_url?: unknown }).base_url === 'string'
+            ? (r as { base_url: string }).base_url
+            : '';
+      if (url) {
+        resolvedBase = stripTrailingSlash(url);
+        return resolvedBase;
+      }
+    } catch {
+      // host doesn't implement it / not hosted — fall through to error
+    }
+    throw new CloudError(
+      'cloud API base URL is not configured; pass apiBaseUrl to ChatableX.init()',
+      0,
+    );
+  }
+
+  /**
+   * fetch against auth-fc that injects the host login session and retries once
+   * on 401 after letting `sdk.auth` refresh. Rejects with CloudAuthRequiredError
+   * when there is no valid token (no unauthenticated request is sent).
+   */
+  async function authedFetch(path: string, init: RequestInit): Promise<Response> {
+    const token = await auth.getToken();
+    if (!token) throw new CloudAuthRequiredError();
+
+    const base = await baseUrl();
+    const url = `${base}${path}`;
+
+    const build = async (): Promise<RequestInit> => ({
+      ...init,
+      headers: { ...(init.headers ?? {}), ...(await auth.getAuthHeaders()) },
+    });
+
+    let res = await fetch(url, await build());
+    if (res.status === 401 && (await auth.refresh())) {
+      res = await fetch(url, await build());
+    }
+    return res;
+  }
+
+  /** Call an auth-fc JSON endpoint and unwrap the `data` payload. */
+  async function callApi<T>(path: string, init: RequestInit): Promise<T> {
+    const res = await authedFetch(path, init);
+
+    let body: ApiEnvelope<unknown> | null = null;
+    try {
+      body = (await res.json()) as ApiEnvelope<unknown>;
+    } catch {
+      // non-JSON body
+    }
+
+    const code = body?.code;
+    const message = body?.message || `HTTP ${res.status}`;
+
+    if (!res.ok || body?.success === false) {
+      if (code === 40301) {
+        const q = (body?.data ?? {}) as QuotaErrorData;
+        throw new CloudQuotaExceededError(q.used_bytes ?? 0, q.quota_bytes ?? 0, message);
+      }
+      if (code === 40302) throw new CloudSubscriptionRequiredError(message);
+      if (res.status === 401) throw new CloudAuthRequiredError(message);
+      throw new CloudError(message, code ?? res.status);
+    }
+
+    return (body?.data ?? null) as T;
+  }
+
+  function validateFileKey(fileKey: string): void {
+    if (!fileKey || typeof fileKey !== 'string') {
+      throw new CloudError('fileKey is required', 400);
+    }
+  }
+
+  return {
+    async upload(
+      fileKey: string,
+      data: CloudUploadData,
+      options: CloudUploadOptions = {},
+    ): Promise<CloudUploadResult> {
+      validateFileKey(fileKey);
+      const { body, size, type } = normalizeData(data);
+      const contentType = options.contentType || type || DEFAULT_CONTENT_TYPE;
+
+      const signed = await callApi<UploadURLData>('/api/storage/upload-url', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          app_id: appId,
+          file_key: fileKey,
+          content_type: contentType,
+          size_bytes: size,
+        }),
+      });
+
+      // Direct client → OSS PUT. Content-Type MUST match what was signed.
+      const put = await fetch(signed.upload_url, {
+        method: 'PUT',
+        headers: { 'Content-Type': contentType },
+        body,
+      });
+      if (!put.ok) {
+        throw new CloudError(`OSS upload failed: HTTP ${put.status}`, put.status);
+      }
+
+      return { fileKey, objectKey: signed.object_key, size, contentType };
+    },
+
+    async getDownloadUrl(fileKey: string): Promise<string> {
+      validateFileKey(fileKey);
+      const signed = await callApi<DownloadURLData>('/api/storage/download-url', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ app_id: appId, file_key: fileKey }),
+      });
+      return signed.download_url;
+    },
+
+    async download(fileKey: string): Promise<Blob> {
+      const url = await this.getDownloadUrl(fileKey);
+      const res = await fetch(url, { method: 'GET' });
+      if (!res.ok) {
+        throw new CloudError(`OSS download failed: HTTP ${res.status}`, res.status);
+      }
+      return res.blob();
+    },
+
+    async list(options: CloudListOptions = {}): Promise<CloudFileInfo[]> {
+      const qs = new URLSearchParams({ app_id: appId });
+      if (options.prefix) qs.set('prefix', options.prefix);
+      const data = await callApi<ListFilesData>(`/api/storage/files?${qs.toString()}`, {
+        method: 'GET',
+      });
+      return (data?.files ?? []).map((f) => ({
+        fileKey: f.file_key,
+        size: f.size,
+        lastModified: f.last_modified,
+      }));
+    },
+
+    async delete(fileKey: string): Promise<void> {
+      validateFileKey(fileKey);
+      const qs = new URLSearchParams({ app_id: appId, file_key: fileKey });
+      await callApi<unknown>(`/api/storage/files?${qs.toString()}`, { method: 'DELETE' });
+    },
+
+    async usage(): Promise<CloudUsage> {
+      const data = await callApi<UsageData>('/api/storage/usage', { method: 'GET' });
+      return {
+        usedBytes: data.used_bytes,
+        quotaBytes: data.quota_bytes,
+        fileCount: data.file_count,
+        reconciledAt: data.reconciled_at,
+      };
+    },
+  };
+}

package/src/types.ts

@@ -161,6 +161,14 @@ export 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -251,6 +259,79 @@ export interface ChatableXAuth {
   refresh(): Promise<boolean>;
 }
 
+// ---------------------------------------------------------------------------
+// Cloud Storage
+// ---------------------------------------------------------------------------
+
+/** Binary payload accepted by `sdk.cloud.upload`. */
+export type CloudUploadData = Blob | ArrayBuffer | ArrayBufferView | string;
+
+export 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`. */
+export 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. */
+export interface CloudFileInfo {
+  fileKey: string;
+  size: number;
+  /** ISO-8601 timestamp. */
+  lastModified: string;
+}
+
+export interface CloudListOptions {
+  /** Restrict the listing to keys under this app-relative prefix. */
+  prefix?: string;
+}
+
+/** The user's storage usage / quota for the whole account. */
+export 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`).
+ */
+export 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>;
+}
+
 export interface ChatableXSDK {
   ai: ChatableXAI;
   tools: ChatableXTools;
@@ -260,6 +341,7 @@ export interface ChatableXSDK {
   tool: ChatableXToolModule;
   platform: ChatableXPlatform;
   auth: ChatableXAuth;
+  cloud: ChatableXCloud;
 }
 
 // ---------------------------------------------------------------------------