chatablex-web-sdk 1.0.31 → 1.0.34

package/src/types.ts

@@ -161,6 +161,16 @@ 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;
+  /** Agent lock configuration — blocks user input during tool execution. */
+  agentLock?: AgentLockConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -251,6 +261,127 @@ 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>;
+}
+
+// ---------------------------------------------------------------------------
+// Agent Lock
+// ---------------------------------------------------------------------------
+
+export 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;
+}
+
+export type AgentLockEventType = 'lock' | 'unlock' | 'cancel' | 'timeout';
+
+export interface AgentLockEventData {
+  requestId?: string;
+  timestamp: number;
+}
+
+export type AgentLockEventHandler = (data: AgentLockEventData) => void;
+
+export 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;
+}
+
 export interface ChatableXSDK {
   ai: ChatableXAI;
   tools: ChatableXTools;
@@ -260,6 +391,8 @@ export interface ChatableXSDK {
   tool: ChatableXToolModule;
   platform: ChatableXPlatform;
   auth: ChatableXAuth;
+  cloud: ChatableXCloud;
+  agentLock: ChatableXAgentLock;
 }
 
 // ---------------------------------------------------------------------------