openclaw-client 1.1.0 → 2.0.0

package/src/client.ts

@@ -2,6 +2,10 @@ import type {
   AgentIdentityParams,
   AgentIdentityResult,
   AgentParams,
+  AgentsCreateParams,
+  AgentsCreateResult,
+  AgentsDeleteParams,
+  AgentsDeleteResult,
   AgentsFilesGetParams,
   AgentsFilesGetResult,
   AgentsFilesListParams,
@@ -10,6 +14,8 @@ import type {
   AgentsFilesSetResult,
   AgentsListParams,
   AgentsListResult,
+  AgentsUpdateParams,
+  AgentsUpdateResult,
   AgentWaitParams,
   ChannelsLogoutParams,
   ChannelsStatusParams,
@@ -37,6 +43,7 @@ import type {
   DevicePairApproveParams,
   DevicePairListParams,
   DevicePairRejectParams,
+  DevicePairRemoveParams,
   DeviceTokenRevokeParams,
   DeviceTokenRotateParams,
   EventFrame,
@@ -62,6 +69,8 @@ import type {
   NodePairVerifyParams,
   NodeRenameParams,
   PollParams,
+  PushTestParams,
+  PushTestResult,
   RequestFrame,
   ResponseFrame,
   SendParams,
@@ -72,11 +81,14 @@ import type {
   SessionsPreviewParams,
   SessionsResetParams,
   SessionsResolveParams,
+  SessionsUsageParams,
   SkillsBinsParams,
   SkillsBinsResult,
   SkillsInstallParams,
   SkillsStatusParams,
   SkillsUpdateParams,
+  TalkConfigParams,
+  TalkConfigResult,
   TalkModeParams,
   UpdateRunParams,
   WakeParams,
@@ -98,6 +110,14 @@ export interface OpenClawClientConfig {
   clientVersion?: string;
   platform?: string;
   mode?: ConnectParams['client']['mode'];
+  /** Timeout in ms for the connect handshake (default: 120000).
+   *  Set this higher if device approval may take a while. */
+  connectTimeoutMs?: number;
+  /** Timeout in ms for regular RPC requests (default: 30000). */
+  requestTimeoutMs?: number;
+  /** Additional ConnectParams fields to merge into the handshake request
+   *  (e.g. `device` for device identity, `caps`, `commands`). */
+  connectParams?: Partial<ConnectParams>;
 }
 
 export type EventListener = (event: EventFrame) => void;
@@ -130,7 +150,13 @@ export class OpenClawClient {
   }
 
   /**
-   * Connect to the OpenClaw Gateway and perform handshake
+   * Connect to the OpenClaw Gateway and perform handshake.
+   *
+   * The protocol flow is:
+   * 1. Open WebSocket connection
+   * 2. Gateway sends a `connect.challenge` event with a nonce
+   * 3. Client responds with a `connect` request (including auth token)
+   * 4. Gateway replies with `hello-ok` containing server info and snapshot
    */
   async connect(): Promise<HelloOk> {
     if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
@@ -141,26 +167,49 @@ export class OpenClawClient {
     const WS = getWebSocketConstructor();
     this.ws = new WS(this.config.gatewayUrl);
 
-    // Wait for connection to open
-    await new Promise<void>((resolve, reject) => {
+    // Wait for connection to open and receive the challenge event
+    const challenge = await new Promise<{ nonce: string; ts: number }>((resolve, reject) => {
       if (!this.ws) {
         reject(new Error('WebSocket not initialized'));
         return;
       }
 
-      this.ws.onopen = () => resolve();
-      this.ws.onerror = (error) => reject(error);
+      const timeout = setTimeout(() => {
+        reject(new Error('Connection timeout: no challenge received'));
+      }, 15000);
+
+      this.ws.onerror = (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const frame = JSON.parse(event.data);
+          if (frame.type === 'event' && frame.event === 'connect.challenge') {
+            clearTimeout(timeout);
+            resolve(frame.payload);
+          }
+        } catch (error) {
+          clearTimeout(timeout);
+          reject(new Error('Failed to parse challenge frame'));
+        }
+      };
+
+      this.ws.onopen = () => {
+        // Wait for the challenge event after connection opens
+      };
     });
 
-    // Set up message handler
+    // Set up message handler for subsequent messages
     if (this.ws) {
       this.ws.onmessage = (event) => this.handleMessage(event);
       this.ws.onclose = () => this.handleClose();
       this.ws.onerror = (error) => this.handleError(error);
     }
 
-    // Perform handshake
-    const result = await this.handshake();
+    // Perform handshake (send connect request after receiving challenge)
+    const result = await this.handshake(challenge);
     this.connected = true;
     this.connectionId = result.server.connId;
     return result;
@@ -212,9 +261,10 @@ export class OpenClawClient {
   }
 
   /**
-   * Perform the connection handshake
+   * Perform the connection handshake after receiving the challenge.
+   * Uses connectTimeoutMs (default 120s) since device approval may take a while.
    */
-  private async handshake(): Promise<HelloOk> {
+  private async handshake(_challenge: { nonce: string; ts: number }): Promise<HelloOk> {
     const params: ConnectParams = {
       minProtocol: 3,
       maxProtocol: 3,
@@ -229,15 +279,17 @@ export class OpenClawClient {
       auth: {
         token: this.config.token,
       },
+      ...this.config.connectParams,
     };
 
-    return this.request<HelloOk>('connect', params);
+    const connectTimeout = this.config.connectTimeoutMs ?? 120000;
+    return this.request<HelloOk>('connect', params, connectTimeout);
   }
 
   /**
    * Send a request and wait for response
    */
-  private async request<T = any>(method: string, params?: any): Promise<T> {
+  private async request<T = any>(method: string, params?: any, timeoutMs?: number): Promise<T> {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       throw new Error('Not connected');
     }
@@ -253,11 +305,11 @@ export class OpenClawClient {
     return new Promise((resolve, reject) => {
       this.pending.set(id, { resolve, reject });
 
-      // Set timeout for request (30 seconds)
+      const effectiveTimeout = timeoutMs ?? this.config.requestTimeoutMs ?? 30000;
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`Request timeout: ${method}`));
-      }, 30000);
+      }, effectiveTimeout);
 
       // Clear timeout when promise settles
       const originalResolve = resolve;
@@ -413,6 +465,27 @@ export class OpenClawClient {
     return this.request<AgentsListResult>('agents.list', params);
   }
 
+  /**
+   * Create agent
+   */
+  async createAgent(params: AgentsCreateParams): Promise<AgentsCreateResult> {
+    return this.request<AgentsCreateResult>('agents.create', params);
+  }
+
+  /**
+   * Update agent
+   */
+  async updateAgent(params: AgentsUpdateParams): Promise<AgentsUpdateResult> {
+    return this.request<AgentsUpdateResult>('agents.update', params);
+  }
+
+  /**
+   * Delete agent
+   */
+  async deleteAgent(params: AgentsDeleteParams): Promise<AgentsDeleteResult> {
+    return this.request<AgentsDeleteResult>('agents.delete', params);
+  }
+
   /**
    * Get agent identity
    */
@@ -483,6 +556,13 @@ export class OpenClawClient {
     return this.request('sessions.compact', params);
   }
 
+  /**
+   * Get session usage
+   */
+  async getSessionsUsage(params: SessionsUsageParams = {}): Promise<any> {
+    return this.request('sessions.usage', params);
+  }
+
   /**
    * Send a message to agent
    */
@@ -553,6 +633,13 @@ export class OpenClawClient {
     return this.request('talk.mode', params);
   }
 
+  /**
+   * Get talk config
+   */
+  async getTalkConfig(params: TalkConfigParams = {}): Promise<TalkConfigResult> {
+    return this.request<TalkConfigResult>('talk.config', params);
+  }
+
   /**
    * Get channels status
    */
@@ -721,6 +808,13 @@ export class OpenClawClient {
     return this.request('device.pair.reject', params);
   }
 
+  /**
+   * Remove paired device
+   */
+  async removeDevicePairing(params: DevicePairRemoveParams): Promise<any> {
+    return this.request('device.pair.remove', params);
+  }
+
   /**
    * Rotate device token
    */
@@ -826,6 +920,13 @@ export class OpenClawClient {
     return this.request('node.invoke', params);
   }
 
+  /**
+   * Test push notification to node
+   */
+  async testPush(params: PushTestParams): Promise<PushTestResult> {
+    return this.request<PushTestResult>('push.test', params);
+  }
+
   /**
    * Update and run
    */