shellx-ai 1.0.12 → 1.1.0

package/dist/index.d.ts

@@ -1,39 +1,82 @@
+import { type Logger } from "./logger.js";
 export interface TaskClientConfig {
     timeout: number;
     reconnect: boolean;
     reconnectMaxAttempts: number;
     reconnectInterval: number;
     pingInterval: number;
-    onOpen: () => void;
+    onOpen: (deviceId: string | undefined) => void;
     onClose: (event?: CloseEvent) => void;
-    onError: (error?: Event) => void;
+    onError: (error?: Error | Event) => void;
     onReconnectFailed: () => void;
-    onMessage?: (data: any) => void;
+    onMessage?: (data: unknown) => void;
 }
 export declare const DEFAULT_CONFIG: TaskClientConfig;
-import type { WsClient, ActionSequence, ScreenShotOptions, ElementSelector, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, AppListResponse } from './protocol';
-export interface TaskResponse<T = any> {
+import type { WsClient, ActionSequence, ScreenShotOptions, ElementSelector, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse } from "./protocol.js";
+import type { Buffer } from "buffer";
+/**
+ * WebSocket interface for cross-platform compatibility
+ */
+interface IWebSocket {
+    binaryType?: string;
+    onopen?: ((event: Event) => void) | null;
+    onmessage?: ((event: MessageEvent) => void) | null;
+    onerror?: ((event: Event) => void) | null;
+    onclose?: ((event: CloseEvent) => void) | null;
+    readyState?: number;
+    send(data: ArrayBuffer | Uint8Array | string | Blob | Buffer): void;
+    close(code?: number, reason?: string): void;
+    ping?(data?: ArrayBuffer | string): void;
+}
+/**
+ * Interface for ShellX instance
+ */
+interface IShellXInstance {
+    handleShellOutput: (chunks: [number, number, Uint8Array[]]) => void;
+}
+export interface TaskResponse<T = unknown> {
     taskId?: string;
     success?: boolean;
     data?: T;
-    error?: {
-        message: string;
-    };
+    error?: string;
 }
-export interface PendingTask {
-    resolve: (data: any) => void;
+export interface PendingTask<T = unknown> {
+    resolve: (data: T | PromiseLike<T>) => void;
     reject: (err: Error) => void;
     timer: number;
     type: string;
 }
+export interface AuthenticationResponse {
+    authenticate: string;
+    last_updated: string;
+    machine: string;
+    registered_at: string;
+    status?: "registered" | "not_registered";
+    message?: string;
+}
 /**
- * Enhanced WebSocket Task Client with protocol-aware task methods
+ * Low-level WebSocket Client for direct protocol communication
+ *
+ * @warning This is a low-level API intended for advanced use cases only.
+ * Most users should use the ShellX class instead, which provides a simpler,
+ * more intuitive interface with automatic error handling and retry logic.
+ *
+ * @example
+ * ```typescript
+ * // For most users, use ShellX instead:
+ * import { ShellX } from './shellx';
+ * const shellx = new ShellX({ deviceId: 'your-device-id' });
+ * await shellx.connect();
+ * await shellx.click({ text: 'Submit' });
+ * ```
+ *
+ * @see Use ShellX for a high-level API unless you need low-level WebSocket access
  */
-export declare class ConnectionTaskClient {
+export declare class ConnectionClient {
     private wsUrl;
     private deviceId;
     private config;
-    ws: any;
+    ws: IWebSocket | null;
     private shellxConnected;
     private wsConnected;
     private authenticated;
@@ -43,22 +86,35 @@ export declare class ConnectionTaskClient {
     private pingIntervalId;
     private initializationPromise;
     private shellx;
-    constructor(deviceId: string, config?: Partial<TaskClientConfig>);
+    private executionLogsRef;
+    private logger;
+    constructor(deviceId: string | undefined, config?: Partial<TaskClientConfig>, logger?: Logger);
     private init;
     private authenticateDevice;
-    getFetch(): (url: string, options?: any) => Promise<any>;
+    getFetch(): (url: string, options?: RequestInit) => Promise<unknown>;
     /**
-     * 等待WebSocket初始化完成
+     * Wait for WebSocket initialization complete
      */
     waitForInitialization(): Promise<void>;
     /**
-     * 发送认证消息
+     * Ensure connection is ready before executing device commands
+     * If not connected, wait for connection with timeout
+     *
+     * @param timeout - Timeout in milliseconds (default: 10000ms)
+     * @throws Error if connection timeout or connection failed
+     *
+     * @example
+     * ```typescript
+     * await client.ensureConnected(10000);
+     * console.log('Connection ready');
+     * ```
      */
-    private sendAuthenticationMessage;
+    ensureConnected(timeout?: number): Promise<void>;
     private handleMessage;
     private processServerMessage;
+    private matchResponseByType;
     private handleJsonDataResponse;
-    sendMessage(message: WsClient, taskType?: string, timeout?: number): Promise<any>;
+    sendMessage<T = unknown>(message: WsClient, taskType?: string): Promise<T>;
     /**
      * Find UI elements on the screen
      */
@@ -69,31 +125,34 @@ export declare class ConnectionTaskClient {
     waitElement(selector: ElementSelector, options?: WaitOptions): Promise<WAITElement>;
     /**
      * Take a screenshot
+     * @deprecated Use takeScreenshot() instead for consistency
      */
     screenShot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
+    /**
+     * Take a screenshot
+     */
+    takeScreenshot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
     /**
      * Get screen information
      */
     getScreenInfo(): Promise<ScreenInfoResponse>;
     /**
-     * Get list of installed apps
+     * Get screen information
+     * @deprecated Use wakeScreenAndGetInfo() instead for clarity
      */
-    getAppList(options?: {
-        includeSystemApps?: boolean;
-        includeDisabledApps?: boolean;
-    }): Promise<AppListResponse>;
+    getAndWakeScreen(): Promise<ScreenInfoResponse>;
     /**
-     * Get specific app information
+     * Wake screen and get screen information
      */
-    getAppInfo(packageName: string): Promise<any>;
+    wakeScreenAndGetInfo(): Promise<ScreenInfoResponse>;
     /**
      * Execute an action sequence
      */
-    executeAction(actionSequence: ActionSequence, taskId?: string, timeeout?: number): Promise<any>;
+    executeAction(actionSequence: ActionSequence, taskId?: string, timeout?: number): Promise<unknown>;
     /**
      * Execute promptflow actions
      */
-    executePromptFlow(actionSequence: ActionSequence): Promise<any>;
+    executePromptFlow(actionSequence: ActionSequence): Promise<unknown>;
     /**
      * Listen for display changes
      */
@@ -119,19 +178,43 @@ export declare class ConnectionTaskClient {
      * Send chat message
      */
     sendChat(message: string): Promise<void>;
+    /**
+     * Start ASR (Automatic Speech Recognition)
+     */
+    startAsr(): Promise<void>;
+    /**
+     * Stop ASR (Automatic Speech Recognition)
+     */
+    stopAsr(): Promise<void>;
+    /**
+     * Speak text using TTS (Text-to-Speech)
+     */
+    speak(text: string): Promise<void>;
+    /**
+     * Stop TTS (Text-to-Speech)
+     */
+    stopTts(): Promise<void>;
     /**
      * Send raw message (for custom integrations)
      */
     sendRawMessage(message: WsClient): Promise<void>;
     /**
-     * 发送消息并返回 taskId，允许手动控制任务完成
-     * @param message 要发送的消息
-     * @param taskType 任务类型
-     * @returns Promise<{taskId: string, promise: Promise<any>}>
+     * Detect task type from message content
+     */
+    private detectTaskType;
+    /**
+     * Send message and return taskId
+     * @param message Message to send
+     * @param taskType Task type
+     * @param options Optional parameters { timeout, taskId }
+     * @returns Promise<{taskId: string, promise: Promise<T>>}
      */
-    sendMessageWithTaskId(message: WsClient, taskType: string, definedTaskId?: string, timeout?: number): Promise<{
+    sendMessageWithTaskId<T = unknown>(message: WsClient, taskType: string, options?: {
+        timeout?: number;
+        taskId?: string;
+    }): Promise<{
         taskId: string;
-        promise: Promise<any>;
+        promise: Promise<T>;
     }>;
     private startPing;
     private stopPing;
@@ -141,42 +224,68 @@ export declare class ConnectionTaskClient {
     get isConnected(): boolean;
     get isWebSocketConnected(): boolean;
     get isAuthenticated(): boolean;
+    /**
+     * Get the authenticated device ID (UUID)
+     */
+    getDeviceId(): string | undefined;
     get pendingTaskCount(): number;
     get queuedMessageCount(): number;
     /**
-     * 设置关联的 ShellX 实例
+     * Get current execution log
+     */
+    getExecutionLogs(): string[];
+    /**
+     * Clear current execution log
+     */
+    clearExecutionLogs(): void;
+    /**
+     * Manually append an execution log
+     */
+    appendExecutionLog(log: string): void;
+    /**
+     * Set associated ShellX instance
+     */
+    setShellX(shellx: IShellXInstance): void;
+    /**
+     * Create a timeout result object based on task type
+     * @param taskType Type of the task that timed out
+     * @param timeoutMs Timeout duration in milliseconds
+     * @returns A result object with success: false
      */
-    setShellX(shellx: any): void;
+    private createTimeoutResult;
     /**
-     * 获取关联的 ShellX 实例
+     * Get associated ShellX instance
      */
-    getShellX(): any;
+    getShellX(): IShellXInstance | null;
     /**
-     * 手动完成指定 taskId 的任务
-     * @param taskId 任务ID
-     * @param result 任务结果
-     * @param success 是否成功
+     * Manually complete task by taskId
+     * @param taskId Task ID
+     * @param result Task result
+     * @param success Success status
      */
-    completeTask(taskId: string, result?: any, success?: boolean): boolean;
+    completeTask(taskId: string, result?: unknown, success?: boolean): boolean;
     /**
-     * 获取所有待处理任务的ID列表
+     * Get all pending task IDs
      */
     getPendingTaskIds(): string[];
     /**
-     * 获取指定任务的信息
+     * Get task info by taskId
      */
     getTaskInfo(taskId: string): {
         type: string;
     } | null;
     /**
-     * 批量完成指定类型的任务
-     * @param taskType 任务类型
-     * @param result 任务结果
-     * @param success 是否成功
+     * Batch complete tasks by type
+     * @param taskType Task type
+     * @param result Task result
+     * @param success Success status
      */
-    completeTasksByType(taskType: string, result?: any, success?: boolean): number;
+    completeTasksByType(taskType: string, result?: unknown, success?: boolean): number;
 }
-export default ConnectionTaskClient;
-export type { UIElement, ElementSelector, ActionSequence, WsClient, WsServer, ScreenShotOptions, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, AppListResponse } from './protocol';
-export type { Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, ActionResult, Element, FindResult, CommandResult, Action, Actions, } from './types';
-export { createShellXWithShellMonitoring, ShellX } from './shellx';
+export default ConnectionClient;
+export type { UIElement, ElementSelector, ActionSequence, WsClient, WsServer, ScreenShotOptions, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, } from "./protocol.js";
+export type { Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, BaseResult, Element, FindResult, CommandResult, Action, Clipboard, Actions, ClickResult, InputResult, SwipeResult, KeyResult, WaitResult, ClipboardResult, AppInfoResult, ScreenshotResult, ScreenInfoResult, ExecuteActionsResult, OperationResult, } from "./types.js";
+export { ShellX, type ShellXOptions } from "./shellx.js";
+export { type ErrorResponse, type BaseOperationResult, createErrorResponse, createOperationResult, ErrorCode, ShellXError, ConnectionError, OperationError, ElementError, ValidationError, } from "./errors.js";
+export { extractErrorMessage, createErrorResult, createSuccessResult, handleOperation, handleOperationWithRetry, validateRequired, validateOneOfRequired, wrapErrorWithContext, type ErrorHandlerOptions, type ErrorHandlerResult, } from "./error-handler.js";
+export { buildDeviceApiUrl, buildDeviceConfigUrl, buildDeviceRegisterUrl, buildTokenVerifyUrl, buildTokenRefreshUrl, getApiBaseUrl, getWsServerUrl, getCurrentDomainInfo, createDomainConfig, isChineseUser, type DomainConfig, } from "./domain-manager.js";