@liveport/agent-sdk 0.1.1 → 0.1.2

package/README.md

@@ -66,7 +66,7 @@ new LivePortAgent(config: LivePortAgentConfig)
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `key` | string | ✅ | - | Bridge key for authentication |
-| `apiUrl` | string | ❌ | `https://app.liveport.dev` | API base URL |
+| `apiUrl` | string | ❌ | `https://liveport.dev` | API base URL |
 | `timeout` | number | ❌ | `30000` | Default timeout in milliseconds |
 
 **Example:**
@@ -74,7 +74,7 @@ new LivePortAgent(config: LivePortAgentConfig)
 ```typescript
 const agent = new LivePortAgent({
   key: 'lpk_abc123...',
-  apiUrl: 'https://app.liveport.dev',
+  apiUrl: 'https://liveport.dev',
   timeout: 60000
 });
 ```

package/dist/index.d.mts

@@ -1,15 +1,36 @@
-export { Tunnel } from '@liveport/shared';
-
 /**
  * LivePort Agent SDK
  *
  * TypeScript SDK for AI agents to wait for and access localhost tunnels.
  */
+/**
+ * Tunnel record as stored in the database.
+ *
+ * TODO: Remove this duplicate once @liveport/shared is published to npm
+ * and agent-sdk can depend on it directly. Until then, keep in sync with
+ * the Tunnel type in packages/shared/src/types/index.ts.
+ */
+interface Tunnel {
+    id: string;
+    userId: string;
+    bridgeKeyId?: string;
+    subdomain: string;
+    name?: string;
+    localPort: number;
+    publicUrl: string;
+    region: string;
+    connectedAt: Date;
+    disconnectedAt?: Date;
+    requestCount: number;
+    bytesTransferred: number;
+}
 interface LivePortAgentConfig {
     /** Bridge key for authentication */
     key: string;
-    /** API base URL (default: https://app.liveport.dev) */
+    /** API base URL (default: https://liveport.dev) */
     apiUrl?: string;
+    /** Tunnel server URL for connect() (default: https://tunnel.liveport.online) */
+    tunnelUrl?: string;
     /** Default timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
@@ -19,6 +40,20 @@ interface WaitForTunnelOptions {
     /** Poll interval in milliseconds (default: 1000) */
     pollInterval?: number;
 }
+interface ConnectOptions {
+    /** Tunnel server URL (overrides tunnelUrl from config) */
+    serverUrl?: string;
+    /** Connection timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface WaitForReadyOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Poll interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+    /** Health check path (default: "/") */
+    healthPath?: string;
+}
 interface AgentTunnel {
     tunnelId: string;
     subdomain: string;
@@ -37,10 +72,14 @@ declare class ApiError extends Error {
     readonly code: string;
     constructor(statusCode: number, code: string, message: string);
 }
+/** Error thrown when WebSocket connection fails */
+declare class ConnectionError extends Error {
+    constructor(message: string);
+}
 /**
  * LivePort Agent SDK
  *
- * Allows AI agents to wait for and access localhost tunnels.
+ * Allows AI agents to wait for, connect to, and access localhost tunnels.
  *
  * @example
  * ```typescript
@@ -50,9 +89,12 @@ declare class ApiError extends Error {
  *   key: process.env.LIVEPORT_BRIDGE_KEY!
  * });
  *
- * // Wait for a tunnel to become available
- * const tunnel = await agent.waitForTunnel({ timeout: 30000 });
- * console.log(`Testing at: ${tunnel.url}`);
+ * // Create a tunnel to local port 3000
+ * const tunnel = await agent.connect(3000);
+ * console.log(`Tunnel URL: ${tunnel.url}`);
+ *
+ * // Wait for the local server to be reachable through the tunnel
+ * await agent.waitForReady(tunnel);
  *
  * // Run your tests against tunnel.url
  *
@@ -63,8 +105,33 @@ declare class ApiError extends Error {
 declare class LivePortAgent {
     private config;
     private abortController;
-    private waitInProgress;
+    private wsConnection;
     constructor(config: LivePortAgentConfig);
+    /**
+     * Connect to the tunnel server and create a tunnel for the given local port.
+     *
+     * Opens a WebSocket to the tunnel server, authenticates with the bridge key,
+     * and waits for a tunnel assignment. Incoming HTTP requests from the tunnel
+     * are forwarded to localhost:<port>.
+     *
+     * @param port - The local port to tunnel
+     * @param options - Connection options
+     * @returns The tunnel info once connected
+     * @throws ConnectionError if the connection fails or times out
+     */
+    connect(port: number, options?: ConnectOptions): Promise<AgentTunnel>;
+    /**
+     * Wait for the tunnel's public URL to become reachable.
+     *
+     * Polls the tunnel's public URL (not localhost) with HTTP GET requests
+     * until a 2xx response is received, or the timeout is exceeded. This
+     * validates the full tunnel path end-to-end.
+     *
+     * @param tunnel - The tunnel to check
+     * @param options - Wait options
+     * @throws TunnelTimeoutError if the tunnel is not ready within timeout
+     */
+    waitForReady(tunnel: AgentTunnel, options?: WaitForReadyOptions): Promise<void>;
     /**
      * Wait for a tunnel to become available
      *
@@ -86,9 +153,22 @@ declare class LivePortAgent {
     /**
      * Disconnect and clean up
      *
-     * Cancels any pending waitForTunnel calls.
+     * Cancels any pending waitForTunnel calls and closes any WebSocket
+     * connection created by connect().
      */
     disconnect(): Promise<void>;
+    /**
+     * Build WebSocket URL from server URL
+     */
+    private buildWebSocketUrl;
+    /**
+     * Handle incoming WebSocket messages from the tunnel server
+     */
+    private handleWsMessage;
+    /**
+     * Forward an HTTP request from the tunnel server to localhost
+     */
+    private handleHttpRequest;
     /**
      * Make an authenticated API request
      */
@@ -103,4 +183,4 @@ declare class LivePortAgent {
     private sleep;
 }
 
-export { type AgentTunnel, ApiError, LivePortAgent, type LivePortAgentConfig, TunnelTimeoutError, type WaitForTunnelOptions };
+export { type AgentTunnel, ApiError, type ConnectOptions, ConnectionError, LivePortAgent, type LivePortAgentConfig, type Tunnel, TunnelTimeoutError, type WaitForReadyOptions, type WaitForTunnelOptions };

package/dist/index.d.ts

@@ -1,15 +1,36 @@
-export { Tunnel } from '@liveport/shared';
-
 /**
  * LivePort Agent SDK
  *
  * TypeScript SDK for AI agents to wait for and access localhost tunnels.
  */
+/**
+ * Tunnel record as stored in the database.
+ *
+ * TODO: Remove this duplicate once @liveport/shared is published to npm
+ * and agent-sdk can depend on it directly. Until then, keep in sync with
+ * the Tunnel type in packages/shared/src/types/index.ts.
+ */
+interface Tunnel {
+    id: string;
+    userId: string;
+    bridgeKeyId?: string;
+    subdomain: string;
+    name?: string;
+    localPort: number;
+    publicUrl: string;
+    region: string;
+    connectedAt: Date;
+    disconnectedAt?: Date;
+    requestCount: number;
+    bytesTransferred: number;
+}
 interface LivePortAgentConfig {
     /** Bridge key for authentication */
     key: string;
-    /** API base URL (default: https://app.liveport.dev) */
+    /** API base URL (default: https://liveport.dev) */
     apiUrl?: string;
+    /** Tunnel server URL for connect() (default: https://tunnel.liveport.online) */
+    tunnelUrl?: string;
     /** Default timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
@@ -19,6 +40,20 @@ interface WaitForTunnelOptions {
     /** Poll interval in milliseconds (default: 1000) */
     pollInterval?: number;
 }
+interface ConnectOptions {
+    /** Tunnel server URL (overrides tunnelUrl from config) */
+    serverUrl?: string;
+    /** Connection timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface WaitForReadyOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Poll interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+    /** Health check path (default: "/") */
+    healthPath?: string;
+}
 interface AgentTunnel {
     tunnelId: string;
     subdomain: string;
@@ -37,10 +72,14 @@ declare class ApiError extends Error {
     readonly code: string;
     constructor(statusCode: number, code: string, message: string);
 }
+/** Error thrown when WebSocket connection fails */
+declare class ConnectionError extends Error {
+    constructor(message: string);
+}
 /**
  * LivePort Agent SDK
  *
- * Allows AI agents to wait for and access localhost tunnels.
+ * Allows AI agents to wait for, connect to, and access localhost tunnels.
  *
  * @example
  * ```typescript
@@ -50,9 +89,12 @@ declare class ApiError extends Error {
  *   key: process.env.LIVEPORT_BRIDGE_KEY!
  * });
  *
- * // Wait for a tunnel to become available
- * const tunnel = await agent.waitForTunnel({ timeout: 30000 });
- * console.log(`Testing at: ${tunnel.url}`);
+ * // Create a tunnel to local port 3000
+ * const tunnel = await agent.connect(3000);
+ * console.log(`Tunnel URL: ${tunnel.url}`);
+ *
+ * // Wait for the local server to be reachable through the tunnel
+ * await agent.waitForReady(tunnel);
  *
  * // Run your tests against tunnel.url
  *
@@ -63,8 +105,33 @@ declare class ApiError extends Error {
 declare class LivePortAgent {
     private config;
     private abortController;
-    private waitInProgress;
+    private wsConnection;
     constructor(config: LivePortAgentConfig);
+    /**
+     * Connect to the tunnel server and create a tunnel for the given local port.
+     *
+     * Opens a WebSocket to the tunnel server, authenticates with the bridge key,
+     * and waits for a tunnel assignment. Incoming HTTP requests from the tunnel
+     * are forwarded to localhost:<port>.
+     *
+     * @param port - The local port to tunnel
+     * @param options - Connection options
+     * @returns The tunnel info once connected
+     * @throws ConnectionError if the connection fails or times out
+     */
+    connect(port: number, options?: ConnectOptions): Promise<AgentTunnel>;
+    /**
+     * Wait for the tunnel's public URL to become reachable.
+     *
+     * Polls the tunnel's public URL (not localhost) with HTTP GET requests
+     * until a 2xx response is received, or the timeout is exceeded. This
+     * validates the full tunnel path end-to-end.
+     *
+     * @param tunnel - The tunnel to check
+     * @param options - Wait options
+     * @throws TunnelTimeoutError if the tunnel is not ready within timeout
+     */
+    waitForReady(tunnel: AgentTunnel, options?: WaitForReadyOptions): Promise<void>;
     /**
      * Wait for a tunnel to become available
      *
@@ -86,9 +153,22 @@ declare class LivePortAgent {
     /**
      * Disconnect and clean up
      *
-     * Cancels any pending waitForTunnel calls.
+     * Cancels any pending waitForTunnel calls and closes any WebSocket
+     * connection created by connect().
      */
     disconnect(): Promise<void>;
+    /**
+     * Build WebSocket URL from server URL
+     */
+    private buildWebSocketUrl;
+    /**
+     * Handle incoming WebSocket messages from the tunnel server
+     */
+    private handleWsMessage;
+    /**
+     * Forward an HTTP request from the tunnel server to localhost
+     */
+    private handleHttpRequest;
     /**
      * Make an authenticated API request
      */
@@ -103,4 +183,4 @@ declare class LivePortAgent {
     private sleep;
 }
 
-export { type AgentTunnel, ApiError, LivePortAgent, type LivePortAgentConfig, TunnelTimeoutError, type WaitForTunnelOptions };
+export { type AgentTunnel, ApiError, type ConnectOptions, ConnectionError, LivePortAgent, type LivePortAgentConfig, type Tunnel, TunnelTimeoutError, type WaitForReadyOptions, type WaitForTunnelOptions };