chatablex-web-sdk 1.0.31 → 1.0.34

package/src/modules/agentLock.ts

@@ -0,0 +1,255 @@
+import type { Bridge } from '../bridge';
+import type {
+  AgentLockConfig,
+  AgentLockEventType,
+  AgentLockEventData,
+  AgentLockEventHandler,
+  ChatableXAgentLock,
+} from '../types';
+import beeLogo from '../assets/bee.png';
+
+const DEFAULT_CONFIG: Required<AgentLockConfig> = {
+  enabled: true,
+  mode: 'overlay',
+  logoUrl: '',
+  message: 'Agent 正在操作，请稍候…',
+  allowCancel: true,
+  opacity: 0.3,
+  timeout: 30_000,
+  debounceUnlock: 200,
+};
+
+const OVERLAY_ID = '__chatablex_agent_lock_overlay__';
+
+/**
+ * Blocked event types — we intercept these on the overlay to prevent user
+ * interaction from reaching the app underneath.
+ */
+const BLOCKED_EVENTS: string[] = [
+  'mousedown', 'mouseup', 'click', 'dblclick', 'contextmenu',
+  'keydown', 'keyup', 'keypress',
+  'touchstart', 'touchmove', 'touchend',
+  'wheel', 'scroll',
+  'pointerdown', 'pointerup',
+];
+
+const CANCEL_BTN_ID = '__ctx_agent_lock_cancel__';
+
+function blockEvent(e: Event): void {
+  const target = e.target as HTMLElement | null;
+  if (target?.id === CANCEL_BTN_ID) return;
+  e.stopPropagation();
+  e.preventDefault();
+}
+
+export interface AgentLockModule extends ChatableXAgentLock {
+  /**
+   * @internal — called by tool module to lock before dispatch and schedule
+   * unlock after result. Uses ref-counting to support consecutive tools.
+   */
+  _autoLock(requestId: string): void;
+  /** @internal */
+  _autoUnlock(requestId: string): void;
+  /** @internal */
+  _destroy(): void;
+}
+
+export function createAgentLockModule(
+  _bridge: Bridge,
+  userConfig: AgentLockConfig = {},
+): AgentLockModule {
+  const cfg: Required<AgentLockConfig> = { ...DEFAULT_CONFIG, ...userConfig };
+  const logoSrc = cfg.logoUrl || beeLogo;
+
+  const listeners = new Map<AgentLockEventType, Set<AgentLockEventHandler>>();
+  let overlayEl: HTMLDivElement | null = null;
+  let locked = false;
+  let lockCount = 0;
+  let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let currentMessage = cfg.message;
+
+  function emit(event: AgentLockEventType, data: Partial<AgentLockEventData> = {}): void {
+    const payload: AgentLockEventData = { timestamp: Date.now(), ...data };
+    const handlers = listeners.get(event);
+    if (handlers) {
+      for (const fn of handlers) {
+        try { fn(payload); } catch (e) { console.error('[ChatableX AgentLock] event handler error:', e); }
+      }
+    }
+  }
+
+  function injectOverlay(message: string): void {
+    if (typeof document === 'undefined') return;
+    if (document.getElementById(OVERLAY_ID)) return;
+
+    const el = document.createElement('div');
+    el.id = OVERLAY_ID;
+    el.setAttribute('aria-hidden', 'true');
+    el.style.cssText = [
+      'position:fixed', 'inset:0', `z-index:2147483646`,
+      `background:rgba(255,255,255,${cfg.opacity})`,
+      'display:flex', 'flex-direction:column',
+      'align-items:center', 'justify-content:center',
+      'pointer-events:all', 'user-select:none',
+      'backdrop-filter:blur(1px)', '-webkit-backdrop-filter:blur(1px)',
+    ].join(';');
+
+    el.innerHTML = `
+      <img src="${logoSrc}" alt="" style="width:48px;height:48px;animation:__ctx_spin 1.5s linear infinite;" />
+      <p style="margin:12px 0 0;font:14px/1.4 -apple-system,BlinkMacSystemFont,sans-serif;color:#666;">${message}</p>
+      ${cfg.allowCancel ? '<button id="__ctx_agent_lock_cancel__" style="margin-top:16px;background:none;border:none;color:#6366f1;font:13px -apple-system,BlinkMacSystemFont,sans-serif;cursor:pointer;text-decoration:underline;padding:4px 8px;">取消</button>' : ''}
+    `;
+
+    if (!document.getElementById('__ctx_agent_lock_style__')) {
+      const style = document.createElement('style');
+      style.id = '__ctx_agent_lock_style__';
+      style.textContent = '@keyframes __ctx_spin{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}';
+      document.head.appendChild(style);
+    }
+
+    for (const evt of BLOCKED_EVENTS) {
+      el.addEventListener(evt, blockEvent, { capture: true, passive: false });
+    }
+
+    if (cfg.allowCancel) {
+      // Defer binding so the DOM is ready
+      queueMicrotask(() => {
+        const btn = el.querySelector('#__ctx_agent_lock_cancel__');
+        if (btn) {
+          btn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            handleCancel();
+          });
+        }
+      });
+    }
+
+    document.body.appendChild(el);
+    overlayEl = el;
+  }
+
+  function removeOverlay(): void {
+    if (overlayEl) {
+      for (const evt of BLOCKED_EVENTS) {
+        overlayEl.removeEventListener(evt, blockEvent, { capture: true } as EventListenerOptions);
+      }
+      overlayEl.remove();
+      overlayEl = null;
+    }
+    const style = typeof document !== 'undefined' ? document.getElementById('__ctx_agent_lock_style__') : null;
+    if (style) style.remove();
+  }
+
+  function startTimeout(ms: number, requestId?: string): void {
+    clearTimeoutTimer();
+    if (ms <= 0) return;
+    timeoutTimer = setTimeout(() => {
+      console.warn('[ChatableX] Agent lock timeout — auto-unlocking');
+      forceUnlock();
+      emit('timeout', { requestId });
+    }, ms);
+  }
+
+  function clearTimeoutTimer(): void {
+    if (timeoutTimer !== null) {
+      clearTimeout(timeoutTimer);
+      timeoutTimer = null;
+    }
+  }
+
+  function clearDebounceTimer(): void {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+  }
+
+  function doLock(message: string, timeout: number, requestId?: string): void {
+    if (locked) return;
+    locked = true;
+    currentMessage = message;
+
+    if (cfg.mode === 'overlay') {
+      injectOverlay(currentMessage);
+    }
+    startTimeout(timeout, requestId);
+    emit('lock', { requestId });
+  }
+
+  function forceUnlock(requestId?: string): void {
+    if (!locked) return;
+    locked = false;
+    lockCount = 0;
+    clearTimeoutTimer();
+    clearDebounceTimer();
+    if (cfg.mode === 'overlay') {
+      removeOverlay();
+    }
+    emit('unlock', { requestId });
+  }
+
+  function handleCancel(): void {
+    const rid = undefined; // auto mode tracks this externally
+    forceUnlock(rid);
+    emit('cancel', { requestId: rid });
+  }
+
+  // Public API -----------------------------------------------------------------
+
+  function lock(opts?: { message?: string; timeout?: number }): void {
+    if (!cfg.enabled) return;
+    const msg = opts?.message ?? cfg.message;
+    const timeout = opts?.timeout ?? cfg.timeout;
+    doLock(msg, timeout);
+  }
+
+  function unlock(): void {
+    forceUnlock();
+  }
+
+  function isLocked(): boolean {
+    return locked;
+  }
+
+  function on(event: AgentLockEventType, handler: AgentLockEventHandler): () => void {
+    if (!listeners.has(event)) listeners.set(event, new Set());
+    listeners.get(event)!.add(handler);
+    return () => off(event, handler);
+  }
+
+  function off(event: AgentLockEventType, handler: AgentLockEventHandler): void {
+    listeners.get(event)?.delete(handler);
+  }
+
+  // Internal auto-mode API (called by tool module) ----------------------------
+
+  function _autoLock(requestId: string): void {
+    if (!cfg.enabled) return;
+    clearDebounceTimer();
+    lockCount++;
+    if (!locked) {
+      doLock(cfg.message, cfg.timeout, requestId);
+    }
+  }
+
+  function _autoUnlock(requestId: string): void {
+    if (!cfg.enabled) return;
+    lockCount = Math.max(0, lockCount - 1);
+    if (lockCount === 0) {
+      clearDebounceTimer();
+      debounceTimer = setTimeout(() => {
+        if (lockCount === 0) {
+          forceUnlock(requestId);
+        }
+      }, cfg.debounceUnlock);
+    }
+  }
+
+  function _destroy(): void {
+    forceUnlock();
+    listeners.clear();
+  }
+
+  return { lock, unlock, isLocked, on, off, _autoLock, _autoUnlock, _destroy };
+}

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/modules/tool.ts

@@ -1,11 +1,16 @@
 import type { Bridge } from '../bridge';
 import type { ToolInfo, ToolExecuteHandler, ChatableXToolModule } from '../types';
+import type { AgentLockModule } from './agentLock';
 
 /**
  * Creates the `sdk.tool` module — the primary interface for LLM-driven
  * tool execution in a ChatableX WebUI app.
  */
-export function createToolModule(bridge: Bridge, appId: string): ChatableXToolModule & { _setInfo(info: Partial<ToolInfo>): void } {
+export function createToolModule(
+  bridge: Bridge,
+  appId: string,
+  agentLock?: AgentLockModule,
+): ChatableXToolModule & { _setInfo(info: Partial<ToolInfo>): void } {
   let _info: ToolInfo = { id: appId, name: appId, version: '1.0.0', description: '' };
   let _handler: ToolExecuteHandler | null = null;
 
@@ -30,13 +35,19 @@ export function createToolModule(bridge: Bridge, appId: string): ChatableXToolMo
   bridge.addEventListener('toolExecution', async (data) => {
     const params = data as Record<string, unknown>;
     const requestId = params._requestId as string | undefined;
+
+    if (requestId && agentLock) agentLock._autoLock(requestId);
+
     const result = await dispatch(params);
+
     if (requestId && window.ChatableXBridge) {
       window.ChatableXBridge.postMessage(JSON.stringify({
         method: 'tool.executeResult',
         params: { _requestId: requestId, ...result },
       }));
     }
+
+    if (requestId && agentLock) agentLock._autoUnlock(requestId);
   });
 
   return {