@limrun/api 0.5.2 → 0.6.2

package/src/resources/android-instances-helpers.ts

@@ -1,159 +1,350 @@
-import { exec } from 'child_process';
-import * as net from 'net';
-import { WebSocket } from 'ws';
+import { WebSocket, Data } from 'ws';
+import { exec } from 'node:child_process';
 
-import { AndroidInstance } from './android-instances';
+import { startTcpTunnel } from './tunnel.js';
+import type { Tunnel } from './tunnel.js';
+export type { Tunnel } from './tunnel.js';
+import { AndroidInstance } from './android-instances.js';
 
 /**
- * Opens a WebSocket TCP proxy for the ADB port and connects the local adb
- * client to it.
+ * A client for interacting with a Limbar instance
  */
-export const startAdbTunnel = async (
-  androidInstance: AndroidInstance,
-  hostname?: string,
-  port?: number,
-): Promise<Proxy> => {
-  if (!androidInstance.status.adbWebSocketUrl) {
-    throw new Error('ADB WebSocket URL is not available');
-  }
-  const { address, close } = await startTcpProxy(
-    androidInstance.status.adbWebSocketUrl,
-    androidInstance.status.token,
-    hostname ?? '127.0.0.1',
-    port ?? 0,
-  );
-  try {
-    await new Promise<void>((resolve, reject) => {
-      exec(`adb connect ${address.address}:${address.port}`, (err) => {
-        if (err) return reject(err);
-        resolve();
-      });
-    });
-  } catch (err) {
-    close();
-    throw err;
-  }
-  return { address, close };
+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>;
 };
 
-/** Returned by `startTcpProxy` – holds the chosen localhost port and a close callback. */
-export interface Proxy {
-  address: net.AddressInfo;
-  close: () => void;
-}
+/**
+ * Controls the verbosity of logging in the client
+ */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
 
 /**
- * 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 `startTcpProxy` 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.
+ * Configuration options for creating an Instance API client
  */
-export async function startTcpProxy(
-  remoteURL: string,
-  token: string,
-  hostname: string,
-  port: number,
-): Promise<Proxy> {
-  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();
-      }
-    };
+export type InstanceClientOptions = {
+  /**
+   * Path to the ADB executable.
+   * @default 'adb'
+   */
+  adbPath?: string;
+  /**
+   * Controls logging verbosity
+   * @default 'info'
+   */
+  logLevel?: LogLevel;
+};
 
-    // No AbortController support – proxy can be closed via the returned handle
+type ScreenshotRequest = {
+  type: 'screenshot';
+  id: string;
+};
 
-    // TCP server error
-    server.once('error', (err) => {
-      close();
-      reject(new Error(`TCP server error: ${err.message}`));
-    });
+type ScreenshotResponse = {
+  type: 'screenshot';
+  dataUri: string;
+  id: string;
+};
 
-    // Listening
-    server.once('listening', () => {
-      const address = server.address();
-      if (!address || typeof address === 'string') {
-        close();
-        return reject(new Error('Failed to obtain listening address'));
+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;
       }
-      resolve({ address, close });
-    });
 
-    // On first TCP connection
-    server.on('connection', (tcpSocket) => {
-      // Single-connection proxy
-      server.close();
+      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);
 
-      ws = new WebSocket(remoteURL, {
-        headers: { Authorization: `Bearer ${token}` },
-        perMessageDeflate: false,
-      });
+          if (!request) {
+            logger.warn(
+              `Received screenshot data for unknown or already handled session: ${screenshotMessage.id}`,
+            );
+            break;
+          }
 
-      // WebSocket error
-      ws.once('error', (err) => {
-        console.error('WebSocket error:', err);
-        tcpSocket.destroy();
-        close();
-      });
+          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);
 
-      ws.once('open', () => {
-        const socket = ws as WebSocket; // non-undefined after open
+          if (!request) {
+            logger.warn(
+              `Received screenshot error for unknown or already handled session: ${errorMessage.id}`,
+            );
+            break;
+          }
 
-        pingInterval = setInterval(() => {
-          if (socket.readyState === WebSocket.OPEN) {
-            (socket as any).ping();
+          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;
           }
-        }, 30_000);
+          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,
+      };
 
-        // TCP → WS
-        tcpSocket.on('data', (chunk) => {
-          if (socket.readyState === WebSocket.OPEN) {
-            socket.send(chunk);
+      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);
           }
         });
 
-        // WS → TCP
-        socket.on('message', (data) => {
-          if (!tcpSocket.destroyed) {
-            tcpSocket.write(data as Buffer);
+        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);
+          },
         });
       });
+    };
 
-      // Mutual close
-      tcpSocket.on('close', close);
-      tcpSocket.on('error', (err) => {
-        console.error('TCP socket error:', err);
+    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 };
+    };
 
-      ws.on('close', () => tcpSocket.destroy());
+    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,
+      });
     });
-
-    // Start listening
-    server.listen(port, hostname);
   });
 }

package/src/resources/android-instances.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
-import * as AndroidInstancesAPI from './android-instances';
 import { APIPromise } from '../core/api-promise';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
@@ -77,8 +76,7 @@ export namespace AndroidInstance {
 
     /**
      * The region where the instance will be created. If not given, will be decided
-     * based on which region the client is closest to, scheduling clues and
-     * availability.
+     * based on scheduling clues and availability.
      */
     region: string;
 
@@ -92,7 +90,7 @@ export namespace AndroidInstance {
   export interface Status {
     token: string;
 
-    state: AndroidInstancesAPI.AndroidInstanceState;
+    state: 'unknown' | 'creating' | 'ready' | 'terminated';
 
     adbWebSocketUrl?: string;
 
@@ -100,8 +98,6 @@ export namespace AndroidInstance {
   }
 }
 
-export type AndroidInstanceState = 'unknown' | 'creating' | 'ready' | 'terminated';
-
 export type AndroidInstanceListResponse = Array<AndroidInstance>;
 
 export interface AndroidInstanceCreateParams {
@@ -187,13 +183,12 @@ export interface AndroidInstanceListParams {
   /**
    * State filter to apply to Android instances to return.
    */
-  state?: AndroidInstanceState;
+  state?: 'unknown' | 'creating' | 'ready' | 'terminated';
 }
 
 export declare namespace AndroidInstances {
   export {
     type AndroidInstance as AndroidInstance,
-    type AndroidInstanceState as AndroidInstanceState,
     type AndroidInstanceListResponse as AndroidInstanceListResponse,
     type AndroidInstanceCreateParams as AndroidInstanceCreateParams,
     type AndroidInstanceListParams as AndroidInstanceListParams,

package/src/resources/index.ts

@@ -3,7 +3,6 @@
 export {
   AndroidInstances,
   type AndroidInstance,
-  type AndroidInstanceState,
   type AndroidInstanceListResponse,
   type AndroidInstanceCreateParams,
   type AndroidInstanceListParams,

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.6.2'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.2";
+export declare const VERSION = "0.6.2";
 //# 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.6.2";
 //# 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.6.2'; // x-release-please-version
 //# sourceMappingURL=version.js.map