@limrun/api 0.5.2 → 0.7.0

package/src/resources/instance-client.ts

@@ -0,0 +1,350 @@
+import { WebSocket, Data } from 'ws';
+import { exec } from 'node:child_process';
+
+import { startTcpTunnel } from './tunnel.js';
+import type { Tunnel } from './tunnel.js';
+export type { Tunnel } from './tunnel.js';
+import { AndroidInstance } from './android-instances.js';
+
+/**
+ * A client for interacting with a Limbar instance
+ */
+export type InstanceClient = {
+  /**
+   * Take a screenshot of the current screen
+   * @returns A promise that resolves to the screenshot data
+   */
+  screenshot: () => Promise<ScreenshotData>;
+  /**
+   * Disconnect from the Limbar instance
+   */
+  disconnect: () => void;
+
+  /**
+   * Establish an ADB tunnel to the instance.
+   * Returns the local TCP port and a cleanup function.
+   */
+  startAdbTunnel: () => Promise<Tunnel>;
+  /**
+   * Send an asset URL to the instance. The instance will download the asset
+   * and process it (currently APK install is supported). Resolves on success,
+   * rejects with an Error on failure.
+   */
+  sendAsset: (url: string) => Promise<void>;
+};
+
+/**
+ * Controls the verbosity of logging in the client
+ */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+/**
+ * Configuration options for creating an Instance API client
+ */
+export type InstanceClientOptions = {
+  /**
+   * Path to the ADB executable.
+   * @default 'adb'
+   */
+  adbPath?: string;
+  /**
+   * Controls logging verbosity
+   * @default 'info'
+   */
+  logLevel?: LogLevel;
+};
+
+type ScreenshotRequest = {
+  type: 'screenshot';
+  id: string;
+};
+
+type ScreenshotResponse = {
+  type: 'screenshot';
+  dataUri: string;
+  id: string;
+};
+
+type ScreenshotData = {
+  dataUri: string;
+};
+
+type ScreenshotErrorResponse = {
+  type: 'screenshotError';
+  message: string;
+  id: string;
+};
+
+type AssetRequest = {
+  type: 'asset';
+  url: string;
+};
+
+type AssetResultResponse = {
+  type: 'assetResult';
+  result: 'success' | 'failure' | string;
+  url: string;
+  message?: string;
+};
+
+type ServerMessage =
+  | ScreenshotResponse
+  | ScreenshotErrorResponse
+  | AssetResultResponse
+  | { type: string; [key: string]: unknown };
+
+/**
+ * Creates a client for interacting with a Limbar instance
+ * @param options Configuration options including webrtcUrl, token and log level
+ * @returns An InstanceClient for controlling the instance
+ */
+export async function createInstanceClient(
+  androidInstance: AndroidInstance,
+  options: InstanceClientOptions = {
+    adbPath: 'adb',
+    logLevel: 'info',
+  },
+): Promise<InstanceClient> {
+  const token = androidInstance.status.token;
+  const serverAddress = `${androidInstance.status.endpointWebSocketUrl}?token=${token}`;
+  const logLevel = options.logLevel ?? 'info';
+  let ws: WebSocket | undefined = undefined;
+
+  const screenshotRequests: Map<
+    string,
+    {
+      resolver: (value: ScreenshotData | PromiseLike<ScreenshotData>) => void;
+      rejecter: (reason?: any) => void;
+    }
+  > = new Map();
+
+  const assetRequests: Map<
+    string,
+    {
+      resolver: (value: void | PromiseLike<void>) => void;
+      rejecter: (reason?: any) => void;
+    }
+  > = new Map();
+
+  // Logger functions
+  const logger = {
+    debug: (...args: any[]) => {
+      if (logLevel === 'debug') console.log(...args);
+    },
+    info: (...args: any[]) => {
+      if (logLevel === 'info' || logLevel === 'debug') console.log(...args);
+    },
+    warn: (...args: any[]) => {
+      if (logLevel === 'warn' || logLevel === 'info' || logLevel === 'debug') console.warn(...args);
+    },
+    error: (...args: any[]) => {
+      if (logLevel !== 'none') console.error(...args);
+    },
+  };
+
+  return new Promise<InstanceClient>((resolveConnection, rejectConnection) => {
+    logger.debug(`Attempting to connect to WebSocket server at ${serverAddress}...`);
+    ws = new WebSocket(serverAddress);
+    ws.on('message', (data: Data) => {
+      let message: ServerMessage;
+      try {
+        message = JSON.parse(data.toString());
+      } catch (e) {
+        logger.error({ data, error: e }, 'Failed to parse JSON message');
+        return;
+      }
+
+      switch (message.type) {
+        case 'screenshot': {
+          if (!('dataUri' in message) || typeof message.dataUri !== 'string' || !('id' in message)) {
+            logger.warn('Received invalid screenshot message:', message);
+            break;
+          }
+
+          const screenshotMessage = message as ScreenshotResponse;
+          const request = screenshotRequests.get(screenshotMessage.id);
+
+          if (!request) {
+            logger.warn(
+              `Received screenshot data for unknown or already handled session: ${screenshotMessage.id}`,
+            );
+            break;
+          }
+
+          logger.debug(`Received screenshot data URI for session ${screenshotMessage.id}.`);
+          request.resolver({ dataUri: screenshotMessage.dataUri });
+          screenshotRequests.delete(screenshotMessage.id);
+          break;
+        }
+        case 'screenshotError': {
+          if (!('message' in message) || !('id' in message)) {
+            logger.warn('Received invalid screenshot error message:', message);
+            break;
+          }
+
+          const errorMessage = message as ScreenshotErrorResponse;
+          const request = screenshotRequests.get(errorMessage.id);
+
+          if (!request) {
+            logger.warn(
+              `Received screenshot error for unknown or already handled session: ${errorMessage.id}`,
+            );
+            break;
+          }
+
+          logger.error(
+            `Server reported an error capturing screenshot for session ${errorMessage.id}:`,
+            errorMessage.message,
+          );
+          request.rejecter(new Error(errorMessage.message));
+          screenshotRequests.delete(errorMessage.id);
+          break;
+        }
+        case 'assetResult': {
+          logger.debug('Received assetResult:', message);
+          const request = assetRequests.get(message.url as string);
+          if (!request) {
+            logger.warn(`Received assetResult for unknown or already handled url: ${message.url}`);
+            break;
+          }
+          if (message.result === 'success') {
+            logger.debug('Asset result is success');
+            request.resolver();
+            assetRequests.delete(message.url as string);
+            break;
+          }
+          const errorMessage =
+            typeof message.message === 'string' && message.message ?
+              message.message
+            : `Asset processing failed: ${JSON.stringify(message)}`;
+          logger.debug('Asset result is failure', errorMessage);
+          request.rejecter(new Error(errorMessage));
+          assetRequests.delete(message.url as string);
+          break;
+        }
+        default:
+          logger.warn(`Received unexpected message type: ${message.type}`);
+          break;
+      }
+    });
+
+    ws.on('error', (err: Error) => {
+      logger.error('WebSocket error:', err.message);
+      if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) {
+        rejectConnection(err);
+      }
+      screenshotRequests.forEach((request) => request.rejecter(err));
+    });
+
+    ws.on('close', () => {
+      logger.debug('Disconnected from server.');
+      screenshotRequests.forEach((request) => request.rejecter('Disconnected from server'));
+    });
+
+    const screenshot = async (): Promise<ScreenshotData> => {
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return Promise.reject(new Error('WebSocket is not connected or connection is not open.'));
+      }
+
+      const id = 'ts-client-' + Date.now();
+      const screenshotRequest: ScreenshotRequest = {
+        type: 'screenshot',
+        id,
+      };
+
+      return new Promise<ScreenshotData>((resolve, reject) => {
+        logger.debug('Sending screenshot request:', screenshotRequest);
+        ws!.send(JSON.stringify(screenshotRequest), (err?: Error) => {
+          if (err) {
+            logger.error('Failed to send screenshot request:', err);
+            reject(err);
+          }
+        });
+
+        const timeout = setTimeout(() => {
+          if (screenshotRequests.has(id)) {
+            logger.error(`Screenshot request timed out for session ${id}`);
+            screenshotRequests.get(id)?.rejecter(new Error('Screenshot request timed out'));
+            screenshotRequests.delete(id);
+          }
+        }, 30000);
+        screenshotRequests.set(id, {
+          resolver: (value: ScreenshotData | PromiseLike<ScreenshotData>) => {
+            clearTimeout(timeout);
+            resolve(value);
+            screenshotRequests.delete(id);
+          },
+          rejecter: (reason?: any) => {
+            clearTimeout(timeout);
+            reject(reason);
+            screenshotRequests.delete(id);
+          },
+        });
+      });
+    };
+
+    const disconnect = (): void => {
+      if (ws) {
+        logger.debug('Closing WebSocket connection.');
+        ws.close();
+      }
+      screenshotRequests.forEach((request) => request.rejecter('Websocket connection closed'));
+    };
+
+    /**
+     * Opens a WebSocket TCP proxy for the ADB port and connects the local adb
+     * client to it.
+     */
+    const startAdbTunnel = async (): Promise<Tunnel> => {
+      if (!androidInstance.status.adbWebSocketUrl) {
+        return Promise.reject(new Error('ADB WebSocket URL is not set'));
+      }
+      const { address, close } = await startTcpTunnel(
+        androidInstance.status.adbWebSocketUrl,
+        token,
+        '127.0.0.1',
+        0,
+      );
+      try {
+        await new Promise<void>((resolve, reject) => {
+          exec(`${options.adbPath ?? 'adb'} connect ${address.address}:${address.port}`, (err) => {
+            if (err) return reject(err);
+            resolve();
+          });
+        });
+        logger.debug(`ADB connected on ${address.address}`);
+      } catch (err) {
+        close();
+        throw err;
+      }
+      return { address, close };
+    };
+
+    const sendAsset = async (url: string): Promise<void> => {
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return Promise.reject(new Error('WebSocket is not connected or connection is not open.'));
+      }
+      const assetRequest: AssetRequest = {
+        type: 'asset',
+        url,
+      };
+      ws.send(JSON.stringify(assetRequest), (err?: Error) => {
+        if (err) {
+          logger.error('Failed to send asset request:', err);
+        }
+      });
+      return new Promise<void>((resolve, reject) => {
+        assetRequests.set(url, { resolver: resolve, rejecter: reject });
+      });
+    };
+    ws.on('open', () => {
+      logger.debug(`Connected to ${serverAddress}`);
+      resolveConnection({
+        screenshot,
+        disconnect,
+        startAdbTunnel,
+        sendAsset,
+      });
+    });
+  });
+}

package/src/resources/tunnel.ts

@@ -0,0 +1,126 @@
+import * as net from 'net';
+import { WebSocket } from 'ws';
+
+export interface Tunnel {
+  address: {
+    address: string;
+    port: number;
+  };
+  close: () => void;
+}
+
+/**
+ * Starts a one-shot TCP → WebSocket proxy.
+ *
+ * The function creates a local TCP server that listens on an ephemeral port on
+ * 127.0.0.1.  As soon as the **first** TCP client connects the server stops
+ * accepting further connections and forwards all traffic between that client
+ * and `remoteURL` through an authenticated WebSocket.  If you need to proxy
+ * more than one TCP connection, call `startTcpTunnel` again to create a new
+ * proxy instance.
+ *
+ * @param remoteURL Remote WebSocket endpoint (e.g. wss://example.com/instance)
+ * @param token     Bearer token sent as `Authorization` header
+ * @param hostname  Optional IP address to listen on. Default is 127.0.0.1
+ * @param port      Optional port number to listen on. Default is to ask Node.js
+ *                  to find an available non-privileged port.
+ */
+export async function startTcpTunnel(
+  remoteURL: string,
+  token: string,
+  hostname: string,
+  port: number,
+): Promise<Tunnel> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+
+    let ws: WebSocket | undefined;
+    let pingInterval: NodeJS.Timeout | undefined;
+
+    // close helper
+    const close = () => {
+      if (pingInterval) {
+        clearInterval(pingInterval);
+        pingInterval = undefined;
+      }
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.close(1000, 'close');
+      }
+      if (server.listening) {
+        server.close();
+      }
+    };
+
+    // No AbortController support – proxy can be closed via the returned handle
+
+    // TCP server error
+    server.once('error', (err) => {
+      close();
+      reject(new Error(`TCP server error: ${err.message}`));
+    });
+
+    // Listening
+    server.once('listening', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        close();
+        return reject(new Error('Failed to obtain listening address'));
+      }
+      resolve({ address, close });
+    });
+
+    // On first TCP connection
+    server.on('connection', (tcpSocket) => {
+      // Single-connection proxy
+      server.close();
+
+      ws = new WebSocket(remoteURL, {
+        headers: { Authorization: `Bearer ${token}` },
+        perMessageDeflate: false,
+      });
+
+      // WebSocket error
+      ws.once('error', (err: any) => {
+        console.error('WebSocket error:', err);
+        tcpSocket.destroy();
+        close();
+      });
+
+      ws.once('open', () => {
+        const socket = ws as WebSocket; // non-undefined after open
+
+        pingInterval = setInterval(() => {
+          if (socket.readyState === WebSocket.OPEN) {
+            (socket as any).ping();
+          }
+        }, 30_000);
+
+        // TCP → WS
+        tcpSocket.on('data', (chunk) => {
+          if (socket.readyState === WebSocket.OPEN) {
+            socket.send(chunk);
+          }
+        });
+
+        // WS → TCP
+        socket.on('message', (data: any) => {
+          if (!tcpSocket.destroyed) {
+            tcpSocket.write(data as Buffer);
+          }
+        });
+      });
+
+      // Mutual close
+      tcpSocket.on('close', close);
+      tcpSocket.on('error', (err: any) => {
+        console.error('TCP socket error:', err);
+        close();
+      });
+
+      ws.on('close', () => tcpSocket.destroy());
+    });
+
+    // Start listening
+    server.listen(port, hostname);
+  });
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.5.2'; // x-release-please-version
+export const VERSION = '0.7.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.2";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.2";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.5.2'; // x-release-please-version
+exports.VERSION = '0.7.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.5.2'; // x-release-please-version
+export const VERSION = '0.7.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map