@limrun/api 0.5.2 → 0.7.0

package/resources/tunnel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.mts","sourceRoot":"","sources":["../src/resources/tunnel.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA6FjB"}

package/resources/tunnel.d.ts

@@ -0,0 +1,25 @@
+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 declare function startTcpTunnel(remoteURL: string, token: string, hostname: string, port: number): Promise<Tunnel>;
+//# sourceMappingURL=tunnel.d.ts.map

package/resources/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../src/resources/tunnel.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA6FjB"}

package/resources/tunnel.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startTcpTunnel = startTcpTunnel;
+const tslib_1 = require("../internal/tslib.js");
+const net = tslib_1.__importStar(require("net"));
+const ws_1 = require("ws");
+/**
+ * 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.
+ */
+async function startTcpTunnel(remoteURL, token, hostname, port) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        let ws;
+        let pingInterval;
+        // close helper
+        const close = () => {
+            if (pingInterval) {
+                clearInterval(pingInterval);
+                pingInterval = undefined;
+            }
+            if (ws && ws.readyState === ws_1.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 ws_1.WebSocket(remoteURL, {
+                headers: { Authorization: `Bearer ${token}` },
+                perMessageDeflate: false,
+            });
+            // WebSocket error
+            ws.once('error', (err) => {
+                console.error('WebSocket error:', err);
+                tcpSocket.destroy();
+                close();
+            });
+            ws.once('open', () => {
+                const socket = ws; // non-undefined after open
+                pingInterval = setInterval(() => {
+                    if (socket.readyState === ws_1.WebSocket.OPEN) {
+                        socket.ping();
+                    }
+                }, 30000);
+                // TCP → WS
+                tcpSocket.on('data', (chunk) => {
+                    if (socket.readyState === ws_1.WebSocket.OPEN) {
+                        socket.send(chunk);
+                    }
+                });
+                // WS → TCP
+                socket.on('message', (data) => {
+                    if (!tcpSocket.destroyed) {
+                        tcpSocket.write(data);
+                    }
+                });
+            });
+            // Mutual close
+            tcpSocket.on('close', close);
+            tcpSocket.on('error', (err) => {
+                console.error('TCP socket error:', err);
+                close();
+            });
+            ws.on('close', () => tcpSocket.destroy());
+        });
+        // Start listening
+        server.listen(port, hostname);
+    });
+}
+//# sourceMappingURL=tunnel.js.map

package/resources/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../src/resources/tunnel.ts"],"names":[],"mappings":"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"}

package/resources/tunnel.mjs

@@ -0,0 +1,98 @@
+import * as net from 'net';
+import { WebSocket } from 'ws';
+/**
+ * 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, token, hostname, port) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        let ws;
+        let pingInterval;
+        // 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) => {
+                console.error('WebSocket error:', err);
+                tcpSocket.destroy();
+                close();
+            });
+            ws.once('open', () => {
+                const socket = ws; // non-undefined after open
+                pingInterval = setInterval(() => {
+                    if (socket.readyState === WebSocket.OPEN) {
+                        socket.ping();
+                    }
+                }, 30000);
+                // TCP → WS
+                tcpSocket.on('data', (chunk) => {
+                    if (socket.readyState === WebSocket.OPEN) {
+                        socket.send(chunk);
+                    }
+                });
+                // WS → TCP
+                socket.on('message', (data) => {
+                    if (!tcpSocket.destroyed) {
+                        tcpSocket.write(data);
+                    }
+                });
+            });
+            // Mutual close
+            tcpSocket.on('close', close);
+            tcpSocket.on('error', (err) => {
+                console.error('TCP socket error:', err);
+                close();
+            });
+            ws.on('close', () => tcpSocket.destroy());
+        });
+        // Start listening
+        server.listen(port, hostname);
+    });
+}
+//# sourceMappingURL=tunnel.mjs.map

package/resources/tunnel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.mjs","sourceRoot":"","sources":["../src/resources/tunnel.ts"],"names":[],"mappings":"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"}

package/src/client.ts

@@ -21,17 +21,16 @@ import {
   AndroidInstanceCreateParams,
   AndroidInstanceListParams,
   AndroidInstanceListResponse,
-  AndroidInstanceState,
-  AndroidInstances,
 } from './resources/android-instances';
 import {
   Asset,
   AssetGetOrCreateParams,
   AssetGetOrCreateResponse,
-  AssetGetParams,
   AssetListParams,
   AssetListResponse,
+  AssetGetParams,
 } from './resources/assets';
+import { AndroidInstances } from './resources/android-instances-helpers';
 import { Assets, AssetGetOrUploadParams, AssetGetOrUploadResponse } from './resources/assets-helpers';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
@@ -50,7 +49,7 @@ export interface ClientOptions {
   /**
    * Defaults to process.env['LIM_TOKEN'].
    */
-  apiKey?: string | undefined;
+  apiKey?: string | null | undefined;
 
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
@@ -125,7 +124,7 @@ export interface ClientOptions {
  * API Client for interfacing with the Limrun API.
  */
 export class Limrun {
-  apiKey: string;
+  apiKey: string | null;
 
   baseURL: string;
   maxRetries: number;
@@ -142,7 +141,7 @@ export class Limrun {
   /**
    * API Client for interfacing with the Limrun API.
    *
-   * @param {string | undefined} [opts.apiKey=process.env['LIM_TOKEN'] ?? undefined]
+   * @param {string | null | undefined} [opts.apiKey=process.env['LIM_TOKEN'] ?? null]
    * @param {string} [opts.baseURL=process.env['LIMRUN_BASE_URL'] ?? https://api.limrun.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
@@ -153,15 +152,9 @@ export class Limrun {
    */
   constructor({
     baseURL = readEnv('LIMRUN_BASE_URL'),
-    apiKey = readEnv('LIM_TOKEN'),
+    apiKey = readEnv('LIM_TOKEN') ?? null,
     ...opts
   }: ClientOptions = {}) {
-    if (apiKey === undefined) {
-      throw new Errors.LimrunError(
-        "The LIM_TOKEN environment variable is missing or empty; either provide it, or instantiate the Limrun client with an apiKey option, like new Limrun({ apiKey: 'My API Key' }).",
-      );
-    }
-
     const options: ClientOptions = {
       apiKey,
       ...opts,
@@ -219,10 +212,22 @@ export class Limrun {
   }
 
   protected validateHeaders({ values, nulls }: NullableHeaders) {
-    return;
+    if (this.apiKey && values.get('authorization')) {
+      return;
+    }
+    if (nulls.has('authorization')) {
+      return;
+    }
+
+    throw new Error(
+      'Could not resolve authentication method. Expected the apiKey to be set. Or for the "Authorization" headers to be explicitly omitted',
+    );
   }
 
   protected async authHeaders(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
+    if (this.apiKey == null) {
+      return undefined;
+    }
     return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
   }
 
@@ -743,7 +748,6 @@ export declare namespace Limrun {
   export {
     AndroidInstances as AndroidInstances,
     type AndroidInstance as AndroidInstance,
-    type AndroidInstanceState as AndroidInstanceState,
     type AndroidInstanceListResponse as AndroidInstanceListResponse,
     type AndroidInstanceCreateParams as AndroidInstanceCreateParams,
     type AndroidInstanceListParams as AndroidInstanceListParams,

package/src/index.ts

@@ -20,5 +20,3 @@ export {
   PermissionDeniedError,
   UnprocessableEntityError,
 } from './core/error';
-
-export * from './resources/android-instances-helpers';

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

@@ -1,159 +1,27 @@
-import { exec } from 'child_process';
-import * as net from 'net';
-import { WebSocket } from 'ws';
-
-import { AndroidInstance } from './android-instances';
-
-/**
- * Opens a WebSocket TCP proxy for the ADB port and connects the local adb
- * client to it.
- */
-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;
+import { RequestOptions } from '../internal/request-options';
+import {
+  AndroidInstance,
+  AndroidInstanceCreateParams,
+  AndroidInstances as GeneratedAndroidInstances,
+} from './android-instances';
+
+export class AndroidInstances extends GeneratedAndroidInstances {
+  async getOrCreate(params: AndroidInstanceCreateParams, options?: RequestOptions): Promise<AndroidInstance> {
+    if (!params.metadata || !params.metadata.labels || Object.keys(params.metadata.labels).length === 0) {
+      return Promise.reject(new Error('At least one label is required for getOrCreate operation'));
+    }
+    const instances = await super.list(
+      {
+        labelSelector: Object.entries(params.metadata.labels)
+          .map(([key, value]) => `${key}=${value}`)
+          .join(','),
+        state: 'ready',
+      },
+      options,
+    );
+    if (instances && instances.length > 0) {
+      return instances[0]!;
+    }
+    return super.create(params, options);
   }
-  return { address, close };
-};
-
-/** Returned by `startTcpProxy` – holds the chosen localhost port and a close callback. */
-export interface Proxy {
-  address: net.AddressInfo;
-  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 `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.
- */
-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();
-      }
-    };
-
-    // 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) => {
-        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) => {
-          if (!tcpSocket.destroyed) {
-            tcpSocket.write(data as Buffer);
-          }
-        });
-      });
-
-      // Mutual close
-      tcpSocket.on('close', close);
-      tcpSocket.on('error', (err) => {
-        console.error('TCP socket error:', err);
-        close();
-      });
-
-      ws.on('close', () => tcpSocket.destroy());
-    });
-
-    // 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

@@ -1,9 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export {
-  AndroidInstances,
   type AndroidInstance,
-  type AndroidInstanceState,
   type AndroidInstanceListResponse,
   type AndroidInstanceCreateParams,
   type AndroidInstanceListParams,
@@ -17,4 +15,6 @@ export {
   type AssetGetOrCreateParams,
 } from './assets';
 
+export { AndroidInstances } from './android-instances-helpers';
+
 export { Assets, AssetGetOrUploadParams, AssetGetOrUploadResponse } from './assets-helpers';