chatablex-web-sdk 1.0.31 → 1.0.34

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,16 @@ 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;
+    /** Agent lock configuration — blocks user input during tool execution. */
+    agentLock?: AgentLockConfig;
 }
 interface ChatableXAI {
     chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
@@ -191,6 +201,110 @@ 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 AgentLockConfig {
+    /** Enable the agent lock feature (default: true). */
+    enabled?: boolean;
+    /**
+     * `"overlay"` — SDK renders a built-in transparent overlay (default).
+     * `"events-only"` — SDK only emits lock/unlock events; no overlay injected.
+     */
+    mode?: 'overlay' | 'events-only';
+    /** URL of the logo displayed in the overlay centre. Defaults to built-in Chatablex SVG. */
+    logoUrl?: string;
+    /** Message shown below the logo (default: "Agent 正在操作，请稍候…"). */
+    message?: string;
+    /** Show a cancel button on the overlay (default: true). */
+    allowCancel?: boolean;
+    /** Overlay background opacity, 0–1 (default: 0.3). */
+    opacity?: number;
+    /** Auto-unlock timeout in ms (default: 30000). 0 disables. */
+    timeout?: number;
+    /** Delay before actually removing the overlay after unlock, to avoid flicker between consecutive tools (default: 200ms). */
+    debounceUnlock?: number;
+}
+type AgentLockEventType = 'lock' | 'unlock' | 'cancel' | 'timeout';
+interface AgentLockEventData {
+    requestId?: string;
+    timestamp: number;
+}
+type AgentLockEventHandler = (data: AgentLockEventData) => void;
+interface ChatableXAgentLock {
+    /** Manually lock user interaction with an optional custom message / timeout. */
+    lock(opts?: {
+        message?: string;
+        timeout?: number;
+    }): void;
+    /** Manually unlock. Safe to call when already unlocked. */
+    unlock(): void;
+    /** Whether the overlay is currently active. */
+    isLocked(): boolean;
+    /** Subscribe to lock lifecycle events. Returns an unsubscribe function. */
+    on(event: AgentLockEventType, handler: AgentLockEventHandler): () => void;
+    /** Remove a previously registered handler. */
+    off(event: AgentLockEventType, handler: AgentLockEventHandler): void;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -200,6 +314,8 @@ interface ChatableXSDK {
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
     auth: ChatableXAuth;
+    cloud: ChatableXCloud;
+    agentLock: ChatableXAgentLock;
 }
 declare global {
     interface Window {
@@ -246,6 +362,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 +431,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 AgentLockConfig, type AgentLockEventData, type AgentLockEventHandler, type AgentLockEventType, type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAgentLock, 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,16 @@ 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;
+    /** Agent lock configuration — blocks user input during tool execution. */
+    agentLock?: AgentLockConfig;
 }
 interface ChatableXAI {
     chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
@@ -191,6 +201,110 @@ 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 AgentLockConfig {
+    /** Enable the agent lock feature (default: true). */
+    enabled?: boolean;
+    /**
+     * `"overlay"` — SDK renders a built-in transparent overlay (default).
+     * `"events-only"` — SDK only emits lock/unlock events; no overlay injected.
+     */
+    mode?: 'overlay' | 'events-only';
+    /** URL of the logo displayed in the overlay centre. Defaults to built-in Chatablex SVG. */
+    logoUrl?: string;
+    /** Message shown below the logo (default: "Agent 正在操作，请稍候…"). */
+    message?: string;
+    /** Show a cancel button on the overlay (default: true). */
+    allowCancel?: boolean;
+    /** Overlay background opacity, 0–1 (default: 0.3). */
+    opacity?: number;
+    /** Auto-unlock timeout in ms (default: 30000). 0 disables. */
+    timeout?: number;
+    /** Delay before actually removing the overlay after unlock, to avoid flicker between consecutive tools (default: 200ms). */
+    debounceUnlock?: number;
+}
+type AgentLockEventType = 'lock' | 'unlock' | 'cancel' | 'timeout';
+interface AgentLockEventData {
+    requestId?: string;
+    timestamp: number;
+}
+type AgentLockEventHandler = (data: AgentLockEventData) => void;
+interface ChatableXAgentLock {
+    /** Manually lock user interaction with an optional custom message / timeout. */
+    lock(opts?: {
+        message?: string;
+        timeout?: number;
+    }): void;
+    /** Manually unlock. Safe to call when already unlocked. */
+    unlock(): void;
+    /** Whether the overlay is currently active. */
+    isLocked(): boolean;
+    /** Subscribe to lock lifecycle events. Returns an unsubscribe function. */
+    on(event: AgentLockEventType, handler: AgentLockEventHandler): () => void;
+    /** Remove a previously registered handler. */
+    off(event: AgentLockEventType, handler: AgentLockEventHandler): void;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -200,6 +314,8 @@ interface ChatableXSDK {
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
     auth: ChatableXAuth;
+    cloud: ChatableXCloud;
+    agentLock: ChatableXAgentLock;
 }
 declare global {
     interface Window {
@@ -246,6 +362,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 +431,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 AgentLockConfig, type AgentLockEventData, type AgentLockEventHandler, type AgentLockEventType, type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAgentLock, 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 };