appium-remote-debugger 15.2.13 → 15.3.0

package/lib/protocol/{index.js → index.ts}

@@ -1,7 +1,10 @@
+import type { StringRecord } from '@appium/types';
+import type { RemoteCommandOpts, ProtocolCommandOpts } from '../types';
+
 const OBJECT_GROUP = 'console';
 
 // See https://github.com/WebKit/webkit/tree/master/Source/JavaScriptCore/inspector/protocol
-const COMMANDS = /** @type {const} */ ({
+const COMMANDS = {
   // https://github.com/WebKit/WebKit/blob/main/Source/JavaScriptCore/inspector/protocol/Animation.json
   //#region ANIMATION DOMAIN
   'Animation.enable': [], // Enables Canvas domain events
@@ -196,28 +199,39 @@ const COMMANDS = /** @type {const} */ ({
   'Worker.initialized': ['workerId'],
   'Worker.sendMessageToWorker': ['workerId', 'message']
   //#endregion
-});
+} as const;
 
 /**
+ * Generates a protocol command object based on the command name and options.
+ * Extracts only the parameters that are defined for the specific command in the
+ * WebKit Inspector protocol specification.
  *
- * @param {string} id
- * @param {string} method
- * @param {import('../types').RemoteCommandOpts} opts
- * @param {boolean} [direct=false] - if set to false then the resulting command params
- * will be patched with default values
- * @returns {import('../types').ProtocolCommandOpts}
+ * @param id - The command identifier.
+ * @param method - The protocol method name (e.g., 'Page.navigate', 'Runtime.evaluate').
+ * @param opts - Options containing parameters for the command.
+ * @param direct - If false (default), the resulting command params will be patched
+ *                 with default values (objectGroup, includeCommandLineAPI, etc.).
+ *                 If true, only the specified parameters are included.
+ * @returns A ProtocolCommandOpts object with id, method, and params.
+ * @throws Error if the command method is unknown.
  */
-export function getProtocolCommand (id, method, opts, direct = false) {
-  const paramNames = COMMANDS[method];
+export function getProtocolCommand(
+  id: string,
+  method: string,
+  opts: RemoteCommandOpts,
+  direct: boolean = false
+): ProtocolCommandOpts {
+  const paramNames = COMMANDS[method as keyof typeof COMMANDS];
   if (!paramNames) {
     throw new Error(`Unknown command: '${method}'`);
   }
 
-  const params = paramNames.reduce(function (params, name) {
-    params[name] = opts[name];
-    return params;
-  }, {});
-  const result = {
+  const params: StringRecord = (paramNames as readonly string[])
+    .reduce(function (acc: StringRecord, name: string) {
+      acc[name] = opts[name];
+      return acc;
+    }, {} as StringRecord);
+  const result: ProtocolCommandOpts = {
     id,
     method,
     params,
@@ -235,5 +249,3 @@ export function getProtocolCommand (id, method, opts, direct = false) {
   }
   return result;
 }
-
-export default getProtocolCommand;

package/lib/rpc/index.ts

@@ -0,0 +1,2 @@
+export { RpcClientSimulator } from './rpc-client-simulator';
+export { RpcClientRealDevice } from './rpc-client-real-device';

package/lib/rpc/{remote-messages.js → remote-messages.ts}

@@ -1,6 +1,6 @@
 import _ from 'lodash';
 import { getProtocolCommand } from '../protocol';
-
+import type { RawRemoteCommand, RemoteCommandOpts, ProtocolCommandOpts, AppIdKey, PageIdKey, RemoteCommandId } from '../types';
 
 const OBJECT_GROUP = 'console';
 
@@ -10,7 +10,7 @@ const DIRECT_COMMAND = 'getDirectCommand';
 
 // mapping of commands to the function for getting the command
 // defaults to `getMinimalCommand`, so no need to have those listed here
-const COMMANDS = /** @type {const} */ ({
+const COMMANDS = {
   'Page.getCookies': FULL_COMMAND,
   'Page.navigate': FULL_COMMAND,
 
@@ -24,17 +24,23 @@ const COMMANDS = /** @type {const} */ ({
 
   'Timeline.start': FULL_COMMAND,
   'Timeline.stop': FULL_COMMAND,
-});
+} as const;
 
-export class RemoteMessages {
-  // #region Connection functions
+type CommandBuilderFunction = typeof MINIMAL_COMMAND | typeof FULL_COMMAND | typeof DIRECT_COMMAND;
 
+/**
+ * Generates remote commands for communicating with the Web Inspector.
+ * Provides methods for creating various types of commands including connection
+ * setup, application management, and protocol commands.
+ */
+export class RemoteMessages {
   /**
+   * Creates a command to set the connection key for the Web Inspector session.
    *
-   * @param {string} connId
-   * @returns {import('../types').RawRemoteCommand}
+   * @param connId - The connection identifier.
+   * @returns A RawRemoteCommand for setting the connection key.
    */
-  setConnectionKey (connId) {
+  setConnectionKey(connId: string): RawRemoteCommand {
     return {
       __argument: {
         WIRConnectionIdentifierKey: connId
@@ -44,12 +50,13 @@ export class RemoteMessages {
   }
 
   /**
+   * Creates a command to connect to a specific application.
    *
-   * @param {string} connId
-   * @param {import('../types').AppIdKey} appIdKey
-   * @returns {import('../types').RawRemoteCommand}
+   * @param connId - The connection identifier.
+   * @param appIdKey - The application identifier key.
+   * @returns A RawRemoteCommand for connecting to the application.
    */
-  connectToApp (connId, appIdKey) {
+  connectToApp(connId: string, appIdKey: AppIdKey): RawRemoteCommand {
     return {
       __argument: {
         WIRConnectionIdentifierKey: connId,
@@ -60,14 +67,15 @@ export class RemoteMessages {
   }
 
   /**
+   * Creates a command to set the sender key for message routing.
    *
-   * @param {string} connId
-   * @param {string} senderId
-   * @param {import('../types').AppIdKey} appIdKey
-   * @param {import('../types').PageIdKey} [pageIdKey]
-   * @returns {import('../types').RawRemoteCommand}
+   * @param connId - The connection identifier.
+   * @param senderId - The sender identifier.
+   * @param appIdKey - The application identifier key.
+   * @param pageIdKey - Optional page identifier key.
+   * @returns A RawRemoteCommand for setting the sender key.
    */
-  setSenderKey (connId, senderId, appIdKey, pageIdKey) {
+  setSenderKey(connId: string, senderId: string, appIdKey: AppIdKey, pageIdKey?: PageIdKey): RawRemoteCommand {
     return {
       __argument: {
         WIRApplicationIdentifierKey: appIdKey,
@@ -81,14 +89,15 @@ export class RemoteMessages {
   }
 
   /**
+   * Creates a command to indicate web view status.
    *
-   * @param {string} connId
-   * @param {import('../types').AppIdKey} appIdKey
-   * @param {import('../types').PageIdKey} [pageIdKey]
-   * @param {boolean} [enabled]
-   * @returns {import('../types').RawRemoteCommand}
+   * @param connId - The connection identifier.
+   * @param appIdKey - The application identifier key.
+   * @param pageIdKey - Optional page identifier key.
+   * @param enabled - Whether the web view indication is enabled. Defaults to true if not provided.
+   * @returns A RawRemoteCommand for indicating web view status.
    */
-  indicateWebView (connId, appIdKey, pageIdKey, enabled) {
+  indicateWebView(connId: string, appIdKey: AppIdKey, pageIdKey?: PageIdKey, enabled?: boolean): RawRemoteCommand {
     return {
       __argument: {
         WIRApplicationIdentifierKey: appIdKey,
@@ -101,11 +110,12 @@ export class RemoteMessages {
   }
 
   /**
+   * Creates a command to launch an application.
    *
-   * @param {string} bundleId
-   * @returns {import('../types').RawRemoteCommand}
+   * @param bundleId - The bundle identifier of the application to launch.
+   * @returns A RawRemoteCommand for launching the application.
    */
-  launchApplication (bundleId) {
+  launchApplication(bundleId: string): RawRemoteCommand {
     return {
       __argument: {
         WIRApplicationBundleIdentifierKey: bundleId
@@ -115,11 +125,13 @@ export class RemoteMessages {
   }
 
   /**
+   * Creates a full command with all default parameters included.
+   * This includes objectGroup, includeCommandLineAPI, and other runtime options.
    *
-   * @param {import('../types').RemoteCommandOpts & import('../types').ProtocolCommandOpts} opts
-   * @returns {import('../types').RawRemoteCommand}
+   * @param opts - Options combining RemoteCommandOpts and ProtocolCommandOpts.
+   * @returns A RawRemoteCommand with full parameter set.
    */
-  getFullCommand (opts) {
+  getFullCommand(opts: RemoteCommandOpts & ProtocolCommandOpts): RawRemoteCommand {
     const {
       method,
       params,
@@ -143,7 +155,7 @@ export class RemoteMessages {
     const realParams = {
       targetId,
       message: JSON.stringify({
-        id,
+        id: parseInt(id, 10),
         method,
         params: Object.assign({
           objectGroup: OBJECT_GROUP,
@@ -169,23 +181,24 @@ export class RemoteMessages {
       },
       __selector: '_rpc_forwardSocketData:',
     };
-    // @ts-ignore This is ok
-    return _.omitBy(plist, _.isNil);
+    return _.omitBy(plist, _.isNil) as RawRemoteCommand;
   }
 
   /**
+   * Creates a minimal command with only the essential parameters.
+   * This is the default command type for most operations.
    *
-   * @param {import('../types').RemoteCommandOpts & import('../types').ProtocolCommandOpts} opts
-   * @returns {import('../types').RawRemoteCommand}
+   * @param opts - Options combining RemoteCommandOpts and ProtocolCommandOpts.
+   * @returns A RawRemoteCommand with minimal parameter set.
    */
-  getMinimalCommand (opts) {
+  getMinimalCommand(opts: RemoteCommandOpts & ProtocolCommandOpts): RawRemoteCommand {
     const {method, params, connId, senderId, appIdKey, pageIdKey, targetId, id} = opts;
 
     const realMethod = 'Target.sendMessageToTarget';
     const realParams = {
       targetId,
       message: JSON.stringify({
-        id,
+        id: parseInt(id, 10),
         method,
         params,
       }),
@@ -204,22 +217,23 @@ export class RemoteMessages {
       },
       __selector: '_rpc_forwardSocketData:'
     };
-    // @ts-ignore This is ok
-    return _.omitBy(plist, _.isNil);
+    return _.omitBy(plist, _.isNil) as RawRemoteCommand;
   }
 
   /**
+   * Creates a direct command that bypasses the Target.sendMessageToTarget wrapper.
+   * Used for certain Target domain commands.
    *
-   * @param {import('../types').RemoteCommandOpts & import('../types').ProtocolCommandOpts} opts
-   * @returns {import('../types').RawRemoteCommand}
+   * @param opts - Options combining RemoteCommandOpts and ProtocolCommandOpts.
+   * @returns A RawRemoteCommand for direct protocol communication.
    */
-  getDirectCommand (opts) {
+  getDirectCommand(opts: RemoteCommandOpts & ProtocolCommandOpts): RawRemoteCommand {
     const {method, params, connId, senderId, appIdKey, pageIdKey, id} = opts;
 
     const plist = {
       __argument: {
         WIRSocketDataKey: {
-          id,
+          id: parseInt(id, 10),
           method,
           params,
         },
@@ -230,17 +244,19 @@ export class RemoteMessages {
       },
       __selector: '_rpc_forwardSocketData:'
     };
-    // @ts-ignore This is ok
-    return _.omitBy(plist, _.isNil);
+    return _.omitBy(plist, _.isNil) as RawRemoteCommand;
   }
 
   /**
+   * Gets a remote command based on the command name and options.
+   * Handles both Safari Web Inspector commands and WebKit protocol commands.
    *
-   * @param {string} command
-   * @param {import('../types').RemoteCommandOpts} opts
-   * @returns {import('../types').RawRemoteCommand}
+   * @param command - The command name (e.g., 'setConnectionKey', 'Page.navigate').
+   * @param opts - Options for the command.
+   * @returns A RawRemoteCommand appropriate for the given command.
+   * @throws Error if required parameters are missing for specific commands.
    */
-  getRemoteCommand (command, opts) {
+  getRemoteCommand(command: string, opts: RemoteCommandOpts & RemoteCommandId): RawRemoteCommand {
     const {
       id,
       connId,
@@ -280,9 +296,9 @@ export class RemoteMessages {
     }
 
     // deal with WebKit commands
-    const builderFunction = COMMANDS[command] || MINIMAL_COMMAND;
+    const builderFunction = (COMMANDS[command as keyof typeof COMMANDS] || MINIMAL_COMMAND) as CommandBuilderFunction;
     const commonOpts = getProtocolCommand(
-      /** @type {string} */ (id),
+      id,
       command,
       opts,
       isDirectCommand(command),
@@ -296,17 +312,15 @@ export class RemoteMessages {
       targetId,
     });
   }
-
-  // #endregion
 }
 
 /**
+ * Checks if a command should use the direct command format.
+ * Direct commands bypass the Target.sendMessageToTarget wrapper.
  *
- * @param {string} command
- * @returns {boolean}
+ * @param command - The command name to check.
+ * @returns True if the command should use direct format, false otherwise.
  */
-export function isDirectCommand (command) {
-  return COMMANDS[command] === DIRECT_COMMAND;
+export function isDirectCommand(command: string): boolean {
+  return COMMANDS[command as keyof typeof COMMANDS] === DIRECT_COMMAND;
 }
-
-export default RemoteMessages;

package/lib/rpc/rpc-client-real-device.ts

@@ -0,0 +1,68 @@
+import { log } from '../logger';
+import { RpcClient } from './rpc-client';
+import { services } from 'appium-ios-device';
+import type { RemoteCommand } from '../types';
+
+/**
+ * RPC client implementation for real iOS devices.
+ * Extends RpcClient to provide device-specific connection handling.
+ */
+export class RpcClientRealDevice extends RpcClient {
+  protected service?: any;
+
+  /**
+   * Connects to the Web Inspector service on a real iOS device.
+   * Starts the Web Inspector service and sets up message listening.
+   */
+  override async connect(): Promise<void> {
+    this.service = await services.startWebInspectorService(this.udid, {
+      osVersion: this.platformVersion,
+      isSimulator: false,
+      verbose: this.logAllCommunication,
+      verboseHexDump: this.logAllCommunicationHexDump,
+      socketChunkSize: this.socketChunkSize,
+      maxFrameLength: this.webInspectorMaxFrameLength,
+    });
+
+    this.service.listenMessage(this.receive.bind(this));
+    this.isConnected = true;
+  }
+
+  /**
+   * Disconnects from the Web Inspector service on the real device.
+   * Closes the service connection and cleans up resources.
+   */
+  override async disconnect(): Promise<void> {
+    if (!this.isConnected) {
+      return;
+    }
+
+    log.debug('Disconnecting from remote debugger');
+    await super.disconnect();
+    this.service?.close();
+    this.isConnected = false;
+  }
+
+  /**
+   * Sends a command message to the Web Inspector service.
+   *
+   * @param cmd - The command to send to the device.
+   */
+  override async sendMessage(cmd: RemoteCommand): Promise<void> {
+    if (!this.service) {
+      throw new Error('RPC service is not initialized. Is the client connected?');
+    }
+    this.service.sendMessage(cmd);
+  }
+
+  /**
+   * Receives data from the Web Inspector service and handles it.
+   *
+   * @param data - The data received from the service.
+   */
+  override async receive(data: any): Promise<void> {
+    if (this.isConnected) {
+      await this.messageHandler.handleMessage(data);
+    }
+  }
+}

package/lib/rpc/{rpc-client-simulator.js → rpc-client-simulator.ts}

@@ -4,27 +4,26 @@ import B from 'bluebird';
 import net from 'net';
 import { RpcClient } from './rpc-client';
 import { services } from 'appium-ios-device';
+import type { RpcClientOptions, RpcClientSimulatorOptions, RemoteCommand } from '../types';
 
+/**
+ * RPC client implementation for iOS simulators.
+ * Extends RpcClient to provide simulator-specific connection handling
+ * via TCP sockets or Unix domain sockets.
+ */
 export class RpcClientSimulator extends RpcClient {
-  /** @type {string|undefined} */
-  host;
-
-  /** @type {number|undefined} */
-  port;
-
-  /** @type {any} */
-  messageProxy;
-
-  /** @type {import('node:net').Socket|null} */
-  socket;
-
-  /** @type {string|undefined} */
-  socketPath;
+  protected readonly host?: string;
+  protected port?: number;
+  protected readonly messageProxy?: any;
+  protected socket: net.Socket | null;
+  protected readonly socketPath?: string;
+  protected service?: any;
 
   /**
-   * @param {import('./rpc-client').RpcClientOptions & RpcClientSimulatorOptions} [opts={}]
+   * @param opts - Options for configuring the RPC client, including
+   *                simulator-specific options like socketPath, host, and port.
    */
-  constructor (opts = {}) {
+  constructor(opts: RpcClientOptions & RpcClientSimulatorOptions = {}) {
     super(opts);
 
     const {
@@ -44,9 +43,10 @@ export class RpcClientSimulator extends RpcClient {
   }
 
   /**
-   * @override
+   * Connects to the Web Inspector service on an iOS simulator.
+   * Supports both Unix domain sockets and TCP connections, with optional proxy support.
    */
-  async connect () {
+  override async connect(): Promise<void> {
     // create socket and handle its messages
     if (this.socketPath) {
       if (this.messageProxy) {
@@ -57,10 +57,11 @@ export class RpcClientSimulator extends RpcClient {
         // Forward the actual socketPath to the proxy
         this.socket.once('connect', () => {
           log.debug(`Forwarding the actual web inspector socket to the proxy: '${this.socketPath}'`);
-          // @ts-ignore socket must be efined here
-          this.socket.write(JSON.stringify({
-            socketPath: this.socketPath
-          }));
+          if (this.socket) {
+            this.socket.write(JSON.stringify({
+              socketPath: this.socketPath
+            }));
+          }
         });
 
       } else {
@@ -77,7 +78,11 @@ export class RpcClientSimulator extends RpcClient {
       // tcp socket
       log.debug(`Connecting to remote debugger ${this.messageProxy ? 'via proxy ' : ''}through TCP: ${this.host}:${this.port}`);
       this.socket = new net.Socket();
-      this.socket.connect(/** @type {number} */ (this.port), /** @type {String} */ (this.host));
+      if (this.port && this.host) {
+        this.socket.connect(this.port, this.host);
+      } else {
+        throw new Error('Both port and host must be defined for TCP connection');
+      }
     }
 
     this.socket.setNoDelay(true);
@@ -103,16 +108,17 @@ export class RpcClientSimulator extends RpcClient {
     this.service.listenMessage(this.receive.bind(this));
 
     // connect the socket
-    return await new B((resolve, reject) => {
+    return await new B<void>((resolve, reject) => {
       // only resolve this function when we are actually connected
-      // @ts-ignore socket must be defined here
+      if (!this.socket) {
+        return reject(new Error('RPC socket is not connected. Please contact developers'));
+      }
       this.socket.on('connect', () => {
         log.debug(`Debugger socket connected`);
         this.isConnected = true;
 
         resolve();
       });
-      // @ts-ignore socket must be defined here
       this.socket.on('error', (err) => {
         if (this.isConnected) {
           log.error(`Socket error: ${err.message}`);
@@ -126,37 +132,41 @@ export class RpcClientSimulator extends RpcClient {
   }
 
   /**
-   * @override
+   * Disconnects from the Web Inspector service on the simulator.
+   * Closes the socket and service connection, and cleans up resources.
    */
-  async disconnect () {
+  override async disconnect(): Promise<void> {
     if (!this.isConnected) {
       return;
     }
 
     log.debug('Disconnecting from remote debugger');
     await super.disconnect();
-    this.service.close();
+    this.service?.close();
     this.isConnected = false;
   }
 
   /**
-   * @override
+   * Sends a command message to the Web Inspector service via the socket.
+   * Handles socket errors and ensures the socket is available before sending.
+   *
+   * @param cmd - The command to send to the simulator.
    */
-  async sendMessage (cmd) {
-    let onSocketError;
+  override async sendMessage(cmd: RemoteCommand): Promise<void> {
+    let onSocketError: ((err: Error) => void) | undefined;
 
-    return await new B((resolve, reject) => {
+    return await new B<void>((resolve, reject) => {
       // handle socket problems
-      onSocketError = (err) => {
+      onSocketError = (err: Error) => {
         log.error(`Socket error: ${err.message}`);
 
         // the connection was refused, so reject the connect promise
         reject(err);
       };
 
-      if (!this.socket) {
+      if (!this.socket || !this.service) {
         return reject(
-          new Error('The RPC socket is not defined. Have you called `connect()` before sending a message?')
+          new Error('The RPC client is not connected. Have you called `connect()` before sending a message?')
         );
       }
       this.socket.on('error', onSocketError);
@@ -165,22 +175,20 @@ export class RpcClientSimulator extends RpcClient {
     })
     .finally(() => {
       // remove this listener, so we don't exhaust the system
-      try {
-        // @ts-ignore socket must be defined
+      if (this.socket && onSocketError) {
         this.socket.removeListener('error', onSocketError);
-      } catch {}
+      }
     });
   }
 
   /**
-   * @override
+   * Receives data from the Web Inspector service and handles it.
+   * Converts Buffer data to strings for certain message keys.
+   *
+   * @param data - The data received from the service.
    */
-  async receive (data) {
-    if (!this.isConnected) {
-      return;
-    }
-
-    if (!data) {
+  override async receive(data: any): Promise<void> {
+    if (!this.isConnected || !data) {
       return;
     }
 
@@ -189,17 +197,6 @@ export class RpcClientSimulator extends RpcClient {
         data[key] = data[key].toString('utf8');
       }
     }
-    // @ts-ignore messageHandler must be defined
     await this.messageHandler.handleMessage(data);
   }
 }
-
-export default RpcClientSimulator;
-
-/**
- * @typedef {Object} RpcClientSimulatorOptions
- * @property {string} [socketPath]
- * @property {string} [host='::1']
- * @property {number} [port]
- * @property {any} [messageProxy]
- */