@liveport/agent-sdk 0.1.1 → 0.1.2

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/index.ts
+import WebSocket from "ws";
 var TunnelTimeoutError = class extends Error {
   constructor(timeout) {
     super(`Tunnel not available within ${timeout}ms timeout`);
@@ -15,23 +16,150 @@ var ApiError = class extends Error {
     this.code = code;
   }
 };
+var ConnectionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionError";
+  }
+};
 var LivePortAgent = class {
   config;
   abortController = null;
-  waitInProgress = false;
+  wsConnection = null;
   constructor(config) {
     if (!config.key) {
       throw new Error("Bridge key is required");
     }
-    if (config.timeout !== void 0 && config.timeout <= 0) {
-      throw new Error("Timeout must be greater than 0");
-    }
     this.config = {
       key: config.key,
-      apiUrl: config.apiUrl || "https://app.liveport.dev",
+      apiUrl: config.apiUrl || "https://liveport.dev",
+      tunnelUrl: config.tunnelUrl || "https://tunnel.liveport.online",
       timeout: config.timeout || 3e4
     };
   }
+  /**
+   * 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
+   */
+  async connect(port, options) {
+    if (this.wsConnection) {
+      throw new ConnectionError("Already connected \u2014 call disconnect() first");
+    }
+    const serverUrl = options?.serverUrl || this.config.tunnelUrl;
+    const timeout = options?.timeout ?? this.config.timeout;
+    const WS = options?._WebSocketClass ?? WebSocket;
+    return new Promise((resolve, reject) => {
+      const wsUrl = this.buildWebSocketUrl(serverUrl);
+      const headers = {
+        "X-Bridge-Key": this.config.key,
+        "X-Local-Port": String(port)
+      };
+      const socket = new WS(wsUrl, {
+        headers,
+        perMessageDeflate: false
+      });
+      this.wsConnection = socket;
+      let settled = false;
+      const connectTimeout = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          socket.close();
+          reject(new ConnectionError("Connection timeout"));
+        }
+      }, timeout);
+      socket.on("open", () => {
+      });
+      socket.on("message", (data) => {
+        try {
+          const message = JSON.parse(data.toString());
+          this.handleWsMessage(message, port, socket);
+          if (message.type === "connected" && !settled) {
+            clearTimeout(connectTimeout);
+            settled = true;
+            const payload = message.payload;
+            const tunnel = {
+              tunnelId: payload.tunnelId,
+              subdomain: payload.subdomain,
+              url: payload.url,
+              localPort: port,
+              // Use server-provided createdAt if the server sends it; fall back to client time
+              // (ConnectedPayload doesn't include createdAt today, but may in a future server version)
+              createdAt: payload.createdAt ? new Date(payload.createdAt) : /* @__PURE__ */ new Date(),
+              expiresAt: new Date(payload.expiresAt)
+            };
+            resolve(tunnel);
+          } else if (message.type === "error" && message.payload?.fatal && !settled) {
+            clearTimeout(connectTimeout);
+            settled = true;
+            reject(new ConnectionError(message.payload.message));
+          }
+        } catch {
+        }
+      });
+      socket.on("close", () => {
+        clearTimeout(connectTimeout);
+        if (!settled) {
+          settled = true;
+          reject(new ConnectionError("Connection closed before tunnel was established"));
+        }
+        if (this.wsConnection === socket) {
+          this.wsConnection = null;
+        }
+      });
+      socket.on("error", (err) => {
+        clearTimeout(connectTimeout);
+        if (!settled) {
+          settled = true;
+          if (this.wsConnection === socket) {
+            this.wsConnection = null;
+          }
+          reject(new ConnectionError(err.message));
+        }
+      });
+    });
+  }
+  /**
+   * 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
+   */
+  async waitForReady(tunnel, options) {
+    const timeout = options?.timeout ?? this.config.timeout;
+    const pollInterval = options?.pollInterval ?? 1e3;
+    const healthPath = options?.healthPath ?? "/";
+    const url = tunnel.url + healthPath;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      try {
+        const response = await fetch(url, {
+          method: "GET",
+          signal: AbortSignal.timeout(Math.max(1, Math.min(5e3, timeout - (Date.now() - startTime))))
+        });
+        if (response.ok) {
+          return;
+        }
+      } catch {
+      }
+      const remaining = timeout - (Date.now() - startTime);
+      if (remaining <= 0) break;
+      await this.sleep(Math.min(pollInterval, remaining));
+    }
+    throw new TunnelTimeoutError(timeout);
+  }
   /**
    * Wait for a tunnel to become available
    *
@@ -43,54 +171,35 @@ var LivePortAgent = class {
    * @throws ApiError if the API request fails
    */
   async waitForTunnel(options) {
-    if (this.waitInProgress) {
-      throw new Error(
-        "Wait already in progress. Call disconnect() first or wait for the current operation to complete."
-      );
-    }
     const timeout = options?.timeout ?? this.config.timeout;
     const pollInterval = options?.pollInterval ?? 1e3;
-    if (timeout <= 0) {
-      throw new Error("Timeout must be greater than 0");
-    }
-    if (pollInterval <= 0) {
-      throw new Error("Poll interval must be greater than 0");
-    }
-    if (pollInterval > timeout) {
-      throw new Error("Poll interval cannot exceed timeout");
-    }
-    this.waitInProgress = true;
     this.abortController = new AbortController();
     const startTime = Date.now();
-    try {
-      while (Date.now() - startTime < timeout) {
-        try {
-          const response = await this.makeRequest(
-            `/api/agent/tunnels/wait?timeout=${Math.min(pollInterval * 5, timeout - (Date.now() - startTime))}`,
-            { signal: this.abortController.signal }
-          );
-          if (response.ok) {
-            const data = await response.json();
-            if (data.tunnel) {
-              return this.parseTunnel(data.tunnel);
-            }
-          } else if (response.status === 408) {
-          } else {
-            const error = await response.json().catch(() => ({ code: "UNKNOWN", message: "Request failed" }));
-            throw new ApiError(response.status, error.code, error.message);
-          }
-        } catch (err) {
-          if (err instanceof ApiError) throw err;
-          if (err.name === "AbortError") {
-            throw new Error("Wait cancelled");
+    while (Date.now() - startTime < timeout) {
+      try {
+        const response = await this.makeRequest(
+          `/api/agent/tunnels/wait?timeout=${Math.min(pollInterval * 5, timeout - (Date.now() - startTime))}`,
+          { signal: this.abortController.signal }
+        );
+        if (response.ok) {
+          const data = await response.json();
+          if (data.tunnel) {
+            return this.parseTunnel(data.tunnel);
           }
+        } else if (response.status === 408) {
+        } else {
+          const error = await response.json().catch(() => ({ code: "UNKNOWN", message: "Request failed" }));
+          throw new ApiError(response.status, error.code, error.message);
+        }
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        if (err.name === "AbortError") {
+          throw new Error("Wait cancelled");
         }
-        await this.sleep(pollInterval);
       }
-      throw new TunnelTimeoutError(timeout);
-    } finally {
-      this.waitInProgress = false;
+      await this.sleep(pollInterval);
     }
+    throw new TunnelTimeoutError(timeout);
   }
   /**
    * List all active tunnels for this bridge key
@@ -110,13 +219,115 @@ var LivePortAgent = class {
   /**
    * Disconnect and clean up
    *
-   * Cancels any pending waitForTunnel calls.
+   * Cancels any pending waitForTunnel calls and closes any WebSocket
+   * connection created by connect().
    */
   async disconnect() {
     if (this.abortController) {
       this.abortController.abort();
       this.abortController = null;
     }
+    if (this.wsConnection) {
+      const ws = this.wsConnection;
+      this.wsConnection = null;
+      if (ws.readyState === 1 || ws.readyState === 0) {
+        ws.close(1e3, "Agent disconnect");
+      }
+    }
+  }
+  /**
+   * Build WebSocket URL from server URL
+   */
+  buildWebSocketUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = "/connect";
+    return url.toString();
+  }
+  /**
+   * Handle incoming WebSocket messages from the tunnel server
+   */
+  handleWsMessage(message, localPort, socket) {
+    switch (message.type) {
+      case "http_request":
+        void this.handleHttpRequest(message, localPort, socket).catch(() => {
+        });
+        break;
+      case "heartbeat":
+        if (socket.readyState === 1) {
+          socket.send(JSON.stringify({
+            type: "heartbeat_ack",
+            timestamp: Date.now()
+          }));
+        }
+        break;
+    }
+  }
+  /**
+   * Forward an HTTP request from the tunnel server to localhost
+   */
+  async handleHttpRequest(message, localPort, socket) {
+    const payload = message.payload;
+    try {
+      const safePath = payload.path?.startsWith("/") ? payload.path : `/${payload.path || ""}`;
+      const url = `http://localhost:${localPort}${safePath}`;
+      const HOP_BY_HOP = /* @__PURE__ */ new Set([
+        "host",
+        "connection",
+        "transfer-encoding",
+        "te",
+        "trailer",
+        "upgrade",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization"
+      ]);
+      const safeHeaders = Object.fromEntries(
+        Object.entries(payload.headers || {}).filter(([k]) => !HOP_BY_HOP.has(k.toLowerCase()))
+      );
+      const requestInit = {
+        method: payload.method,
+        headers: safeHeaders
+      };
+      if (payload.body) {
+        requestInit.body = Buffer.from(payload.body, "base64");
+      }
+      const response = await fetch(url, requestInit);
+      const responseBody = await response.arrayBuffer();
+      const responseHeaders = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+      const responseMessage = {
+        type: "http_response",
+        id: message.id,
+        timestamp: Date.now(),
+        payload: {
+          status: response.status,
+          headers: responseHeaders,
+          body: responseBody.byteLength > 0 ? Buffer.from(responseBody).toString("base64") : void 0
+        }
+      };
+      if (socket.readyState === 1) {
+        socket.send(JSON.stringify(responseMessage));
+      }
+    } catch (err) {
+      const errorResponse = {
+        type: "http_response",
+        id: message.id,
+        timestamp: Date.now(),
+        payload: {
+          status: 502,
+          headers: { "Content-Type": "text/plain" },
+          body: Buffer.from(
+            `Error connecting to local server: ${err.message}`
+          ).toString("base64")
+        }
+      };
+      if (socket.readyState === 1) {
+        socket.send(JSON.stringify(errorResponse));
+      }
+    }
   }
   /**
    * Make an authenticated API request
@@ -136,45 +347,25 @@ var LivePortAgent = class {
    * Parse tunnel response into AgentTunnel
    */
   parseTunnel(data) {
-    const tunnelId = data.tunnelId || data.id;
+    const tunnelId = data.tunnelId ?? data.id;
     const subdomain = data.subdomain;
     const url = data.url;
     const localPort = data.localPort;
-    const createdAt = data.createdAt;
-    const expiresAt = data.expiresAt;
-    if (!tunnelId || typeof tunnelId !== "string") {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid tunnelId in response");
-    }
-    if (!subdomain || typeof subdomain !== "string") {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid subdomain in response");
-    }
-    if (!url || typeof url !== "string") {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid url in response");
-    }
-    if (typeof localPort !== "number" || localPort <= 0 || localPort > 65535) {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid localPort in response");
-    }
-    if (!createdAt || typeof createdAt !== "string") {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid createdAt in response");
-    }
-    if (!expiresAt || typeof expiresAt !== "string") {
-      throw new ApiError(500, "INVALID_RESPONSE", "Missing or invalid expiresAt in response");
-    }
-    const createdAtDate = new Date(createdAt);
-    const expiresAtDate = new Date(expiresAt);
-    if (isNaN(createdAtDate.getTime())) {
-      throw new ApiError(500, "INVALID_RESPONSE", "Invalid createdAt date format");
+    if (!tunnelId || !subdomain || !url || localPort == null || typeof localPort !== "number") {
+      throw new Error(
+        `parseTunnel: missing required fields in API response (tunnelId=${tunnelId}, subdomain=${subdomain}, url=${url}, localPort=${localPort})`
+      );
     }
-    if (isNaN(expiresAtDate.getTime())) {
-      throw new ApiError(500, "INVALID_RESPONSE", "Invalid expiresAt date format");
+    if (!data.expiresAt) {
+      throw new Error("parseTunnel: missing expiresAt in API response");
     }
     return {
       tunnelId,
       subdomain,
       url,
       localPort,
-      createdAt: createdAtDate,
-      expiresAt: expiresAtDate
+      createdAt: data.createdAt ? new Date(data.createdAt) : /* @__PURE__ */ new Date(),
+      expiresAt: new Date(data.expiresAt)
     };
   }
   /**
@@ -186,6 +377,7 @@ var LivePortAgent = class {
 };
 export {
   ApiError,
+  ConnectionError,
   LivePortAgent,
   TunnelTimeoutError
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * LivePort Agent SDK\n *\n * TypeScript SDK for AI agents to wait for and access localhost tunnels.\n */\n\nimport type { Tunnel } from \"@liveport/shared\";\n\nexport interface LivePortAgentConfig {\n  /** Bridge key for authentication */\n  key: string;\n  /** API base URL (default: https://app.liveport.dev) */\n  apiUrl?: string;\n  /** Default timeout in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\nexport interface WaitForTunnelOptions {\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Poll interval in milliseconds (default: 1000) */\n  pollInterval?: number;\n}\n\nexport interface AgentTunnel {\n  tunnelId: string;\n  subdomain: string;\n  url: string;\n  localPort: number;\n  createdAt: Date;\n  expiresAt: Date;\n}\n\n/** Error thrown when tunnel wait times out */\nexport class TunnelTimeoutError extends Error {\n  constructor(timeout: number) {\n    super(`Tunnel not available within ${timeout}ms timeout`);\n    this.name = \"TunnelTimeoutError\";\n  }\n}\n\n/** Error thrown when API request fails */\nexport class ApiError extends Error {\n  public readonly statusCode: number;\n  public readonly code: string;\n\n  constructor(statusCode: number, code: string, message: string) {\n    super(message);\n    this.name = \"ApiError\";\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/**\n * LivePort Agent SDK\n *\n * Allows AI agents to wait for and access localhost tunnels.\n *\n * @example\n * ```typescript\n * import { LivePortAgent } from '@liveport/agent-sdk';\n *\n * const agent = new LivePortAgent({\n *   key: process.env.LIVEPORT_BRIDGE_KEY!\n * });\n *\n * // Wait for a tunnel to become available\n * const tunnel = await agent.waitForTunnel({ timeout: 30000 });\n * console.log(`Testing at: ${tunnel.url}`);\n *\n * // Run your tests against tunnel.url\n *\n * // Clean up when done\n * await agent.disconnect();\n * ```\n */\nexport class LivePortAgent {\n  private config: Required<LivePortAgentConfig>;\n  private abortController: AbortController | null = null;\n  private waitInProgress = false;\n\n  constructor(config: LivePortAgentConfig) {\n    if (!config.key) {\n      throw new Error(\"Bridge key is required\");\n    }\n\n    // Validate timeout before applying default\n    if (config.timeout !== undefined && config.timeout <= 0) {\n      throw new Error(\"Timeout must be greater than 0\");\n    }\n\n    this.config = {\n      key: config.key,\n      apiUrl: config.apiUrl || \"https://app.liveport.dev\",\n      timeout: config.timeout || 30000,\n    };\n  }\n\n  /**\n   * Wait for a tunnel to become available\n   *\n   * Long-polls the API until a tunnel is ready or timeout is reached.\n   *\n   * @param options - Wait options\n   * @returns The tunnel info once available\n   * @throws TunnelTimeoutError if no tunnel becomes available within timeout\n   * @throws ApiError if the API request fails\n   */\n  async waitForTunnel(options?: WaitForTunnelOptions): Promise<AgentTunnel> {\n    // Prevent concurrent calls\n    if (this.waitInProgress) {\n      throw new Error(\n        \"Wait already in progress. Call disconnect() first or wait for the current operation to complete.\"\n      );\n    }\n\n    const timeout = options?.timeout ?? this.config.timeout;\n    const pollInterval = options?.pollInterval ?? 1000;\n\n    // Validate options\n    if (timeout <= 0) {\n      throw new Error(\"Timeout must be greater than 0\");\n    }\n    if (pollInterval <= 0) {\n      throw new Error(\"Poll interval must be greater than 0\");\n    }\n    if (pollInterval > timeout) {\n      throw new Error(\"Poll interval cannot exceed timeout\");\n    }\n\n    this.waitInProgress = true;\n    this.abortController = new AbortController();\n    const startTime = Date.now();\n\n    try {\n      while (Date.now() - startTime < timeout) {\n      try {\n        const response = await this.makeRequest(\n          `/api/agent/tunnels/wait?timeout=${Math.min(pollInterval * 5, timeout - (Date.now() - startTime))}`,\n          { signal: this.abortController.signal }\n        );\n\n        if (response.ok) {\n          const data = await response.json() as { tunnel?: Record<string, unknown> };\n          if (data.tunnel) {\n            return this.parseTunnel(data.tunnel);\n          }\n        } else if (response.status === 408) {\n          // Timeout from server, continue polling\n        } else {\n          const error = await response.json().catch(() => ({ code: \"UNKNOWN\", message: \"Request failed\" })) as { code: string; message: string };\n          throw new ApiError(response.status, error.code, error.message);\n        }\n      } catch (err) {\n        if (err instanceof ApiError) throw err;\n        if ((err as Error).name === \"AbortError\") {\n          throw new Error(\"Wait cancelled\");\n        }\n        // Network error, wait and retry\n      }\n\n        // Wait before next poll\n        await this.sleep(pollInterval);\n      }\n\n      throw new TunnelTimeoutError(timeout);\n    } finally {\n      this.waitInProgress = false;\n    }\n  }\n\n  /**\n   * List all active tunnels for this bridge key\n   *\n   * @returns Array of active tunnels\n   * @throws ApiError if the API request fails\n   */\n  async listTunnels(): Promise<AgentTunnel[]> {\n    const response = await this.makeRequest(\"/api/agent/tunnels\");\n\n    if (!response.ok) {\n      const error = await response.json().catch(() => ({ code: \"UNKNOWN\", message: \"Request failed\" })) as { code: string; message: string };\n      throw new ApiError(response.status, error.code, error.message);\n    }\n\n    const data = await response.json() as { tunnels?: Record<string, unknown>[] };\n    return (data.tunnels || []).map((t) => this.parseTunnel(t));\n  }\n\n  /**\n   * Disconnect and clean up\n   *\n   * Cancels any pending waitForTunnel calls.\n   */\n  async disconnect(): Promise<void> {\n    if (this.abortController) {\n      this.abortController.abort();\n      this.abortController = null;\n    }\n  }\n\n  /**\n   * Make an authenticated API request\n   */\n  private async makeRequest(\n    path: string,\n    options: RequestInit = {}\n  ): Promise<Response> {\n    const url = `${this.config.apiUrl}${path}`;\n\n    return fetch(url, {\n      ...options,\n      headers: {\n        \"Authorization\": `Bearer ${this.config.key}`,\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n    });\n  }\n\n  /**\n   * Parse tunnel response into AgentTunnel\n   */\n  private parseTunnel(data: Record<string, unknown>): AgentTunnel {\n    const tunnelId = (data.tunnelId || data.id) as string;\n    const subdomain = data.subdomain as string;\n    const url = data.url as string;\n    const localPort = data.localPort as number;\n    const createdAt = data.createdAt as string;\n    const expiresAt = data.expiresAt as string;\n\n    // Validate required fields\n    if (!tunnelId || typeof tunnelId !== \"string\") {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid tunnelId in response\");\n    }\n    if (!subdomain || typeof subdomain !== \"string\") {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid subdomain in response\");\n    }\n    if (!url || typeof url !== \"string\") {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid url in response\");\n    }\n    if (typeof localPort !== \"number\" || localPort <= 0 || localPort > 65535) {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid localPort in response\");\n    }\n    if (!createdAt || typeof createdAt !== \"string\") {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid createdAt in response\");\n    }\n    if (!expiresAt || typeof expiresAt !== \"string\") {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Missing or invalid expiresAt in response\");\n    }\n\n    const createdAtDate = new Date(createdAt);\n    const expiresAtDate = new Date(expiresAt);\n\n    // Validate dates are valid\n    if (isNaN(createdAtDate.getTime())) {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Invalid createdAt date format\");\n    }\n    if (isNaN(expiresAtDate.getTime())) {\n      throw new ApiError(500, \"INVALID_RESPONSE\", \"Invalid expiresAt date format\");\n    }\n\n    return {\n      tunnelId,\n      subdomain,\n      url,\n      localPort,\n      createdAt: createdAtDate,\n      expiresAt: expiresAtDate,\n    };\n  }\n\n  /**\n   * Sleep helper\n   */\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n// Re-export types\nexport type { Tunnel } from \"@liveport/shared\";\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * LivePort Agent SDK\n *\n * TypeScript SDK for AI agents to wait for and access localhost tunnels.\n */\n\nimport WebSocket from \"ws\";\n\n/**\n * Tunnel record as stored in the database.\n *\n * TODO: Remove this duplicate once @liveport/shared is published to npm\n * and agent-sdk can depend on it directly. Until then, keep in sync with\n * the Tunnel type in packages/shared/src/types/index.ts.\n */\nexport interface Tunnel {\n  id: string;\n  userId: string;\n  bridgeKeyId?: string;\n  subdomain: string;\n  name?: string;\n  localPort: number;\n  publicUrl: string;\n  region: string;\n  connectedAt: Date;\n  disconnectedAt?: Date;\n  requestCount: number;\n  bytesTransferred: number;\n}\n\nexport interface LivePortAgentConfig {\n  /** Bridge key for authentication */\n  key: string;\n  /** API base URL (default: https://liveport.dev) */\n  apiUrl?: string;\n  /** Tunnel server URL for connect() (default: https://tunnel.liveport.online) */\n  tunnelUrl?: string;\n  /** Default timeout in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\nexport interface WaitForTunnelOptions {\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Poll interval in milliseconds (default: 1000) */\n  pollInterval?: number;\n}\n\nexport interface ConnectOptions {\n  /** Tunnel server URL (overrides tunnelUrl from config) */\n  serverUrl?: string;\n  /** Connection timeout in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/** @internal Extended connect options with injectable WebSocket class for testing */\ninterface InternalConnectOptions extends ConnectOptions {\n  _WebSocketClass?: typeof WebSocket;\n}\n\nexport interface WaitForReadyOptions {\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Poll interval in milliseconds (default: 1000) */\n  pollInterval?: number;\n  /** Health check path (default: \"/\") */\n  healthPath?: string;\n}\n\nexport interface AgentTunnel {\n  tunnelId: string;\n  subdomain: string;\n  url: string;\n  localPort: number;\n  createdAt: Date;\n  expiresAt: Date;\n}\n\n/** Error thrown when tunnel wait times out */\nexport class TunnelTimeoutError extends Error {\n  constructor(timeout: number) {\n    super(`Tunnel not available within ${timeout}ms timeout`);\n    this.name = \"TunnelTimeoutError\";\n  }\n}\n\n/** Error thrown when API request fails */\nexport class ApiError extends Error {\n  public readonly statusCode: number;\n  public readonly code: string;\n\n  constructor(statusCode: number, code: string, message: string) {\n    super(message);\n    this.name = \"ApiError\";\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/** Error thrown when WebSocket connection fails */\nexport class ConnectionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ConnectionError\";\n  }\n}\n\n/**\n * LivePort Agent SDK\n *\n * Allows AI agents to wait for, connect to, and access localhost tunnels.\n *\n * @example\n * ```typescript\n * import { LivePortAgent } from '@liveport/agent-sdk';\n *\n * const agent = new LivePortAgent({\n *   key: process.env.LIVEPORT_BRIDGE_KEY!\n * });\n *\n * // Create a tunnel to local port 3000\n * const tunnel = await agent.connect(3000);\n * console.log(`Tunnel URL: ${tunnel.url}`);\n *\n * // Wait for the local server to be reachable through the tunnel\n * await agent.waitForReady(tunnel);\n *\n * // Run your tests against tunnel.url\n *\n * // Clean up when done\n * await agent.disconnect();\n * ```\n */\nexport class LivePortAgent {\n  private config: Required<LivePortAgentConfig>;\n  private abortController: AbortController | null = null;\n  private wsConnection: WebSocket | null = null;\n\n  constructor(config: LivePortAgentConfig) {\n    if (!config.key) {\n      throw new Error(\"Bridge key is required\");\n    }\n\n    this.config = {\n      key: config.key,\n      apiUrl: config.apiUrl || \"https://liveport.dev\",\n      tunnelUrl: config.tunnelUrl || \"https://tunnel.liveport.online\",\n      timeout: config.timeout || 30000,\n    };\n  }\n\n  /**\n   * Connect to the tunnel server and create a tunnel for the given local port.\n   *\n   * Opens a WebSocket to the tunnel server, authenticates with the bridge key,\n   * and waits for a tunnel assignment. Incoming HTTP requests from the tunnel\n   * are forwarded to localhost:<port>.\n   *\n   * @param port - The local port to tunnel\n   * @param options - Connection options\n   * @returns The tunnel info once connected\n   * @throws ConnectionError if the connection fails or times out\n   */\n  async connect(port: number, options?: ConnectOptions): Promise<AgentTunnel> {\n    if (this.wsConnection) {\n      throw new ConnectionError(\"Already connected — call disconnect() first\");\n    }\n\n    const serverUrl = options?.serverUrl || this.config.tunnelUrl;\n    const timeout = options?.timeout ?? this.config.timeout;\n    const WS = (options as InternalConnectOptions)?._WebSocketClass ?? WebSocket;\n\n    return new Promise<AgentTunnel>((resolve, reject) => {\n      const wsUrl = this.buildWebSocketUrl(serverUrl);\n\n      const headers: Record<string, string> = {\n        \"X-Bridge-Key\": this.config.key,\n        \"X-Local-Port\": String(port),\n      };\n\n      const socket = new WS(wsUrl, {\n        headers,\n        perMessageDeflate: false,\n      });\n\n      this.wsConnection = socket;\n\n      let settled = false;\n\n      const connectTimeout = setTimeout(() => {\n        if (!settled) {\n          settled = true;\n          socket.close();\n          reject(new ConnectionError(\"Connection timeout\"));\n        }\n      }, timeout);\n\n      socket.on(\"open\", () => {\n        // Waiting for \"connected\" message from server\n      });\n\n      socket.on(\"message\", (data: Buffer | string) => {\n        try {\n          const message = JSON.parse(data.toString());\n          this.handleWsMessage(message, port, socket);\n\n          if (message.type === \"connected\" && !settled) {\n            clearTimeout(connectTimeout);\n            settled = true;\n            const payload = message.payload;\n            const tunnel: AgentTunnel = {\n              tunnelId: payload.tunnelId,\n              subdomain: payload.subdomain,\n              url: payload.url,\n              localPort: port,\n              // Use server-provided createdAt if the server sends it; fall back to client time\n              // (ConnectedPayload doesn't include createdAt today, but may in a future server version)\n              createdAt: payload.createdAt ? new Date(payload.createdAt as string | number) : new Date(),\n              expiresAt: new Date(payload.expiresAt),\n            };\n            resolve(tunnel);\n          } else if (message.type === \"error\" && message.payload?.fatal && !settled) {\n            clearTimeout(connectTimeout);\n            settled = true;\n            reject(new ConnectionError(message.payload.message));\n          }\n        } catch {\n          // Non-JSON messages (e.g. binary frames, malformed data) are\n          // silently dropped. The connect timeout will fire if the\n          // \"connected\" message never arrives.\n        }\n      });\n\n      socket.on(\"close\", () => {\n        clearTimeout(connectTimeout);\n        if (!settled) {\n          settled = true;\n          reject(new ConnectionError(\"Connection closed before tunnel was established\"));\n        }\n        // Only null wsConnection if it's still this socket (avoid clobbering\n        // a new connection created after disconnect() + connect())\n        if (this.wsConnection === socket) {\n          this.wsConnection = null;\n        }\n      });\n\n      socket.on(\"error\", (err: Error) => {\n        clearTimeout(connectTimeout);\n        if (!settled) {\n          settled = true;\n          // Clear wsConnection on error so a new connect() call can proceed\n          if (this.wsConnection === socket) {\n            this.wsConnection = null;\n          }\n          reject(new ConnectionError(err.message));\n        }\n      });\n    });\n  }\n\n  /**\n   * Wait for the tunnel's public URL to become reachable.\n   *\n   * Polls the tunnel's public URL (not localhost) with HTTP GET requests\n   * until a 2xx response is received, or the timeout is exceeded. This\n   * validates the full tunnel path end-to-end.\n   *\n   * @param tunnel - The tunnel to check\n   * @param options - Wait options\n   * @throws TunnelTimeoutError if the tunnel is not ready within timeout\n   */\n  async waitForReady(tunnel: AgentTunnel, options?: WaitForReadyOptions): Promise<void> {\n    const timeout = options?.timeout ?? this.config.timeout;\n    const pollInterval = options?.pollInterval ?? 1000;\n    const healthPath = options?.healthPath ?? \"/\";\n\n    const url = tunnel.url + healthPath;\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      try {\n        const response = await fetch(url, {\n          method: \"GET\",\n          signal: AbortSignal.timeout(Math.max(1, Math.min(5000, timeout - (Date.now() - startTime)))),\n        });\n        if (response.ok) {\n          return;\n        }\n      } catch {\n        // Network error or timeout, continue polling\n      }\n\n      const remaining = timeout - (Date.now() - startTime);\n      if (remaining <= 0) break;\n      await this.sleep(Math.min(pollInterval, remaining));\n    }\n\n    throw new TunnelTimeoutError(timeout);\n  }\n\n  /**\n   * Wait for a tunnel to become available\n   *\n   * Long-polls the API until a tunnel is ready or timeout is reached.\n   *\n   * @param options - Wait options\n   * @returns The tunnel info once available\n   * @throws TunnelTimeoutError if no tunnel becomes available within timeout\n   * @throws ApiError if the API request fails\n   */\n  async waitForTunnel(options?: WaitForTunnelOptions): Promise<AgentTunnel> {\n    const timeout = options?.timeout ?? this.config.timeout;\n    const pollInterval = options?.pollInterval ?? 1000;\n\n    this.abortController = new AbortController();\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      try {\n        const response = await this.makeRequest(\n          `/api/agent/tunnels/wait?timeout=${Math.min(pollInterval * 5, timeout - (Date.now() - startTime))}`,\n          { signal: this.abortController.signal }\n        );\n\n        if (response.ok) {\n          const data = await response.json() as { tunnel?: Record<string, unknown> };\n          if (data.tunnel) {\n            return this.parseTunnel(data.tunnel);\n          }\n        } else if (response.status === 408) {\n          // Timeout from server, continue polling\n        } else {\n          const error = await response.json().catch(() => ({ code: \"UNKNOWN\", message: \"Request failed\" })) as { code: string; message: string };\n          throw new ApiError(response.status, error.code, error.message);\n        }\n      } catch (err) {\n        if (err instanceof ApiError) throw err;\n        if ((err as Error).name === \"AbortError\") {\n          throw new Error(\"Wait cancelled\");\n        }\n        // Network error, wait and retry\n      }\n\n      // Wait before next poll\n      await this.sleep(pollInterval);\n    }\n\n    throw new TunnelTimeoutError(timeout);\n  }\n\n  /**\n   * List all active tunnels for this bridge key\n   *\n   * @returns Array of active tunnels\n   * @throws ApiError if the API request fails\n   */\n  async listTunnels(): Promise<AgentTunnel[]> {\n    const response = await this.makeRequest(\"/api/agent/tunnels\");\n\n    if (!response.ok) {\n      const error = await response.json().catch(() => ({ code: \"UNKNOWN\", message: \"Request failed\" })) as { code: string; message: string };\n      throw new ApiError(response.status, error.code, error.message);\n    }\n\n    const data = await response.json() as { tunnels?: Record<string, unknown>[] };\n    return (data.tunnels || []).map((t) => this.parseTunnel(t));\n  }\n\n  /**\n   * Disconnect and clean up\n   *\n   * Cancels any pending waitForTunnel calls and closes any WebSocket\n   * connection created by connect().\n   */\n  async disconnect(): Promise<void> {\n    if (this.abortController) {\n      this.abortController.abort();\n      this.abortController = null;\n    }\n\n    if (this.wsConnection) {\n      const ws = this.wsConnection;\n      this.wsConnection = null; // Clear reference first so connect() can be called after\n\n      // Use numeric constants (OPEN=1, CONNECTING=0) to avoid coupling to\n      // the imported WebSocket class, which may differ from the injected one\n      if (ws.readyState === 1 || ws.readyState === 0) {\n        ws.close(1000, \"Agent disconnect\");\n      }\n    }\n  }\n\n  /**\n   * Build WebSocket URL from server URL\n   */\n  private buildWebSocketUrl(serverUrl: string): string {\n    const url = new URL(serverUrl);\n    url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n    url.pathname = \"/connect\";\n    return url.toString();\n  }\n\n  /**\n   * Handle incoming WebSocket messages from the tunnel server\n   */\n  private handleWsMessage(\n    message: { type: string; id?: string; payload?: Record<string, unknown> },\n    localPort: number,\n    socket: WebSocket\n  ): void {\n    switch (message.type) {\n      case \"http_request\":\n        void this.handleHttpRequest(message, localPort, socket).catch(() => {\n          // Errors are handled inside handleHttpRequest (sends 502 response)\n        });\n        break;\n\n      case \"heartbeat\":\n        // Respond with heartbeat_ack\n        if (socket.readyState === 1 /* OPEN */) {\n          socket.send(JSON.stringify({\n            type: \"heartbeat_ack\",\n            timestamp: Date.now(),\n          }));\n        }\n        break;\n\n      // connected and error are handled in the connect() promise\n      // Other message types can be extended in the future\n    }\n  }\n\n  /**\n   * Forward an HTTP request from the tunnel server to localhost\n   */\n  private async handleHttpRequest(\n    message: { type: string; id?: string; payload?: Record<string, unknown> },\n    localPort: number,\n    socket: WebSocket\n  ): Promise<void> {\n    const payload = message.payload as {\n      method: string;\n      path: string;\n      headers: Record<string, string>;\n      body?: string;\n    };\n\n    try {\n      // Validate path to prevent injection (e.g. path traversal or host override)\n      const safePath = payload.path?.startsWith(\"/\") ? payload.path : `/${payload.path || \"\"}`;\n      const url = `http://localhost:${localPort}${safePath}`;\n\n      // Strip hop-by-hop headers that could cause request smuggling or\n      // confuse the local server when forwarded from the tunnel\n      const HOP_BY_HOP = new Set([\n        \"host\", \"connection\", \"transfer-encoding\", \"te\", \"trailer\",\n        \"upgrade\", \"keep-alive\", \"proxy-authenticate\", \"proxy-authorization\",\n      ]);\n      const safeHeaders = Object.fromEntries(\n        Object.entries(payload.headers || {}).filter(([k]) => !HOP_BY_HOP.has(k.toLowerCase()))\n      );\n\n      const requestInit: RequestInit = {\n        method: payload.method,\n        headers: safeHeaders,\n      };\n\n      if (payload.body) {\n        requestInit.body = Buffer.from(payload.body, \"base64\");\n      }\n\n      const response = await fetch(url, requestInit);\n      const responseBody = await response.arrayBuffer();\n\n      const responseHeaders: Record<string, string> = {};\n      response.headers.forEach((value, key) => {\n        responseHeaders[key] = value;\n      });\n\n      const responseMessage = {\n        type: \"http_response\",\n        id: message.id,\n        timestamp: Date.now(),\n        payload: {\n          status: response.status,\n          headers: responseHeaders,\n          body: responseBody.byteLength > 0\n            ? Buffer.from(responseBody).toString(\"base64\")\n            : undefined,\n        },\n      };\n\n      if (socket.readyState === 1 /* OPEN */) {\n        socket.send(JSON.stringify(responseMessage));\n      }\n    } catch (err) {\n      const errorResponse = {\n        type: \"http_response\",\n        id: message.id,\n        timestamp: Date.now(),\n        payload: {\n          status: 502,\n          headers: { \"Content-Type\": \"text/plain\" },\n          body: Buffer.from(\n            `Error connecting to local server: ${(err as Error).message}`\n          ).toString(\"base64\"),\n        },\n      };\n\n      if (socket.readyState === 1 /* OPEN */) {\n        socket.send(JSON.stringify(errorResponse));\n      }\n    }\n  }\n\n  /**\n   * Make an authenticated API request\n   */\n  private async makeRequest(\n    path: string,\n    options: RequestInit = {}\n  ): Promise<Response> {\n    const url = `${this.config.apiUrl}${path}`;\n\n    return fetch(url, {\n      ...options,\n      headers: {\n        \"Authorization\": `Bearer ${this.config.key}`,\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n    });\n  }\n\n  /**\n   * Parse tunnel response into AgentTunnel\n   */\n  private parseTunnel(data: Record<string, unknown>): AgentTunnel {\n    // Accept both tunnelId (new API shape) and id (legacy shape) for backward compatibility\n    const tunnelId = (data.tunnelId ?? data.id) as string;\n    const subdomain = data.subdomain as string;\n    const url = data.url as string;\n    const localPort = data.localPort as number;\n\n    if (!tunnelId || !subdomain || !url || localPort == null || typeof localPort !== \"number\") {\n      throw new Error(\n        `parseTunnel: missing required fields in API response (tunnelId=${tunnelId}, subdomain=${subdomain}, url=${url}, localPort=${localPort})`\n      );\n    }\n\n    if (!data.expiresAt) {\n      throw new Error(\"parseTunnel: missing expiresAt in API response\");\n    }\n\n    return {\n      tunnelId,\n      subdomain,\n      url,\n      localPort,\n      createdAt: data.createdAt ? new Date(data.createdAt as string | number) : new Date(),\n      expiresAt: new Date(data.expiresAt as string | number),\n    };\n  }\n\n  /**\n   * Sleep helper\n   */\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveport/agent-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript SDK for AI agents to access LivePort tunnels",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,13 +14,12 @@
   },
   "files": [
     "dist",
-    "examples",
     "README.md"
   ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "lint": "eslint src/",
+    "lint": "echo 'Skipping lint - ESLint not configured' && exit 0",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "clean": "rm -rf dist",
@@ -45,7 +44,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dundas/liveport-private.git",
+    "url": "git+https://github.com/dundas/liveport.git",
     "directory": "packages/agent-sdk"
   },
   "publishConfig": {
@@ -56,11 +55,12 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@types/ws": "^8.5.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0"
   },
   "dependencies": {
-    "@liveport/shared": "workspace:*"
+    "ws": "^8.18.0"
   }
 }

package/examples/01-basic-usage.ts

@@ -1,40 +0,0 @@
-/**
- * Basic Usage Example
- *
- * This example shows the simplest way to use the LivePort Agent SDK
- * to wait for a tunnel and access a local development server.
- */
-
-import { LivePortAgent } from "@liveport/agent-sdk";
-
-async function main() {
-  // Create agent instance with your bridge key
-  const agent = new LivePortAgent({
-    key: process.env.LIVEPORT_KEY || "lpk_your_bridge_key_here",
-  });
-
-  console.log("Waiting for tunnel to become available...");
-
-  try {
-    // Wait for tunnel (default 30 second timeout)
-    const tunnel = await agent.waitForTunnel();
-
-    console.log("✓ Tunnel established!");
-    console.log(`  URL: ${tunnel.url}`);
-    console.log(`  Local Port: ${tunnel.localPort}`);
-    console.log(`  Subdomain: ${tunnel.subdomain}`);
-
-    // Now you can make requests to the tunnel URL
-    const response = await fetch(`${tunnel.url}/api/health`);
-    const data = await response.json();
-
-    console.log("Health check response:", data);
-  } catch (error) {
-    console.error("Failed to get tunnel:", error);
-  } finally {
-    // Clean up
-    await agent.disconnect();
-  }
-}
-
-main();

package/examples/02-testing-integration.ts

@@ -1,75 +0,0 @@
-/**
- * Testing Integration Example
- *
- * This example shows how to integrate LivePort Agent SDK
- * into your automated test suite (Vitest, Jest, etc.)
- */
-
-import { LivePortAgent, TunnelTimeoutError } from "@liveport/agent-sdk";
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-
-describe("API Integration Tests", () => {
-  let agent: LivePortAgent;
-  let tunnelUrl: string;
-
-  beforeAll(async () => {
-    // Initialize agent
-    agent = new LivePortAgent({
-      key: process.env.LIVEPORT_KEY!,
-      timeout: 60000, // 60 second timeout
-    });
-
-    try {
-      // Wait for developer to start their local server
-      console.log("⏳ Waiting for tunnel...");
-      const tunnel = await agent.waitForTunnel({ timeout: 60000 });
-      tunnelUrl = tunnel.url;
-      console.log(`✓ Connected to ${tunnelUrl}`);
-    } catch (error) {
-      if (error instanceof TunnelTimeoutError) {
-        throw new Error(
-          "Tunnel not available. Make sure the developer has started " +
-          "'liveport connect <port>' before running tests."
-        );
-      }
-      throw error;
-    }
-  });
-
-  afterAll(async () => {
-    await agent?.disconnect();
-  });
-
-  it("should return healthy status", async () => {
-    const response = await fetch(`${tunnelUrl}/api/health`);
-    expect(response.ok).toBe(true);
-
-    const data = await response.json();
-    expect(data.status).toBe("healthy");
-  });
-
-  it("should list users", async () => {
-    const response = await fetch(`${tunnelUrl}/api/users`);
-    expect(response.ok).toBe(true);
-
-    const users = await response.json();
-    expect(Array.isArray(users)).toBe(true);
-  });
-
-  it("should create a new user", async () => {
-    const response = await fetch(`${tunnelUrl}/api/users`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        name: "Test User",
-        email: "test@example.com",
-      }),
-    });
-
-    expect(response.status).toBe(201);
-
-    const user = await response.json();
-    expect(user.name).toBe("Test User");
-    expect(user.email).toBe("test@example.com");
-  });
-});