@liveport/agent-sdk 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -63,6 +63,7 @@ declare class ApiError extends Error {
 declare class LivePortAgent {
     private config;
     private abortController;
+    private waitInProgress;
     constructor(config: LivePortAgentConfig);
     /**
      * Wait for a tunnel to become available

package/dist/index.d.ts

@@ -63,6 +63,7 @@ declare class ApiError extends Error {
 declare class LivePortAgent {
     private config;
     private abortController;
+    private waitInProgress;
     constructor(config: LivePortAgentConfig);
     /**
      * Wait for a tunnel to become available

package/dist/index.js

@@ -44,10 +44,14 @@ var ApiError = class extends Error {
 var LivePortAgent = class {
   config;
   abortController = null;
+  waitInProgress = false;
   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",
@@ -65,35 +69,54 @@ 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();
-    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);
+    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");
           }
-        } 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);
       }
-      await this.sleep(pollInterval);
+      throw new TunnelTimeoutError(timeout);
+    } finally {
+      this.waitInProgress = false;
     }
-    throw new TunnelTimeoutError(timeout);
   }
   /**
    * List all active tunnels for this bridge key
@@ -139,13 +162,45 @@ var LivePortAgent = class {
    * Parse tunnel response into AgentTunnel
    */
   parseTunnel(data) {
+    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 (isNaN(expiresAtDate.getTime())) {
+      throw new ApiError(500, "INVALID_RESPONSE", "Invalid expiresAt date format");
+    }
     return {
-      tunnelId: data.tunnelId || data.id,
-      subdomain: data.subdomain,
-      url: data.url,
-      localPort: data.localPort,
-      createdAt: new Date(data.createdAt),
-      expiresAt: new Date(data.expiresAt)
+      tunnelId,
+      subdomain,
+      url,
+      localPort,
+      createdAt: createdAtDate,
+      expiresAt: expiresAtDate
     };
   }
   /**

package/dist/index.js.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\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://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    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.\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    return {\n      tunnelId: data.tunnelId as string || data.id as string,\n      subdomain: data.subdomain as string,\n      url: data.url as string,\n      localPort: data.localPort as number,\n      createdAt: new Date(data.createdAt as string),\n      expiresAt: new Date(data.expiresAt as string),\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 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":[]}

package/dist/index.mjs

@@ -18,10 +18,14 @@ var ApiError = class extends Error {
 var LivePortAgent = class {
   config;
   abortController = null;
+  waitInProgress = false;
   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",
@@ -39,35 +43,54 @@ 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();
-    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);
+    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");
           }
-        } 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);
       }
-      await this.sleep(pollInterval);
+      throw new TunnelTimeoutError(timeout);
+    } finally {
+      this.waitInProgress = false;
     }
-    throw new TunnelTimeoutError(timeout);
   }
   /**
    * List all active tunnels for this bridge key
@@ -113,13 +136,45 @@ var LivePortAgent = class {
    * Parse tunnel response into AgentTunnel
    */
   parseTunnel(data) {
+    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 (isNaN(expiresAtDate.getTime())) {
+      throw new ApiError(500, "INVALID_RESPONSE", "Invalid expiresAt date format");
+    }
     return {
-      tunnelId: data.tunnelId || data.id,
-      subdomain: data.subdomain,
-      url: data.url,
-      localPort: data.localPort,
-      createdAt: new Date(data.createdAt),
-      expiresAt: new Date(data.expiresAt)
+      tunnelId,
+      subdomain,
+      url,
+      localPort,
+      createdAt: createdAtDate,
+      expiresAt: expiresAtDate
     };
   }
   /**

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\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://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    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.\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    return {\n      tunnelId: data.tunnelId as string || data.id as string,\n      subdomain: data.subdomain as string,\n      url: data.url as string,\n      localPort: data.localPort as number,\n      createdAt: new Date(data.createdAt as string),\n      expiresAt: new Date(data.expiresAt as string),\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 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":[]}

package/examples/01-basic-usage.ts

@@ -0,0 +1,40 @@
+/**
+ * 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

@@ -0,0 +1,75 @@
+/**
+ * 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");
+  });
+});

package/examples/03-ai-agent-workflow.ts

@@ -0,0 +1,175 @@
+/**
+ * AI Agent Workflow Example
+ *
+ * This example demonstrates how an AI agent might use the SDK
+ * to interact with a developer's local application.
+ */
+
+import { LivePortAgent, ApiError } from "@liveport/agent-sdk";
+
+interface TestResult {
+  endpoint: string;
+  status: "pass" | "fail";
+  responseTime: number;
+  statusCode?: number;
+  error?: string;
+}
+
+class AIAgentTester {
+  private agent: LivePortAgent;
+  private results: TestResult[] = [];
+
+  constructor(bridgeKey: string) {
+    this.agent = new LivePortAgent({
+      key: bridgeKey,
+      timeout: 120000, // 2 minute timeout for tunnel
+    });
+  }
+
+  async run(): Promise<void> {
+    console.log("🤖 AI Agent Test Runner Starting...\n");
+
+    try {
+      // Step 1: Wait for tunnel
+      console.log("⏳ Waiting for developer to start tunnel...");
+      const tunnel = await this.agent.waitForTunnel({
+        timeout: 120000,
+      });
+
+      console.log(`✓ Tunnel established: ${tunnel.url}`);
+      console.log(`  Port: ${tunnel.localPort}`);
+      console.log(`  Expires: ${tunnel.expiresAt.toLocaleString()}\n`);
+
+      // Step 2: Discover available endpoints
+      console.log("🔍 Discovering API endpoints...");
+      const baseUrl = tunnel.url;
+
+      // Test common endpoints
+      const endpoints = [
+        "/",
+        "/api/health",
+        "/api/users",
+        "/api/products",
+        "/api/auth/login",
+      ];
+
+      // Step 3: Test each endpoint
+      for (const endpoint of endpoints) {
+        await this.testEndpoint(baseUrl, endpoint);
+      }
+
+      // Step 4: Report results
+      this.printResults();
+
+      // Step 5: Analyze and provide recommendations
+      this.analyzeResults();
+    } catch (error) {
+      if (error instanceof ApiError) {
+        console.error(`❌ API Error [${error.code}]: ${error.message}`);
+      } else {
+        console.error("❌ Error:", error);
+      }
+    } finally {
+      await this.agent.disconnect();
+    }
+  }
+
+  private async testEndpoint(
+    baseUrl: string,
+    endpoint: string
+  ): Promise<void> {
+    const start = Date.now();
+
+    try {
+      const response = await fetch(`${baseUrl}${endpoint}`, {
+        signal: AbortSignal.timeout(5000), // 5 second timeout per request
+      });
+
+      const responseTime = Date.now() - start;
+
+      this.results.push({
+        endpoint,
+        status: response.ok ? "pass" : "fail",
+        responseTime,
+        statusCode: response.status,
+      });
+
+      const emoji = response.ok ? "✓" : "✗";
+      console.log(
+        `  ${emoji} ${endpoint.padEnd(20)} [${response.status}] ${responseTime}ms`
+      );
+    } catch (error) {
+      const responseTime = Date.now() - start;
+
+      this.results.push({
+        endpoint,
+        status: "fail",
+        responseTime,
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
+
+      console.log(`  ✗ ${endpoint.padEnd(20)} [ERROR] ${error}`);
+    }
+  }
+
+  private printResults(): void {
+    console.log("\n📊 Test Results Summary");
+    console.log("=" .repeat(50));
+
+    const passed = this.results.filter((r) => r.status === "pass").length;
+    const failed = this.results.filter((r) => r.status === "fail").length;
+    const avgTime =
+      this.results.reduce((sum, r) => sum + r.responseTime, 0) /
+      this.results.length;
+
+    console.log(`Total Endpoints: ${this.results.length}`);
+    console.log(`Passed: ${passed}`);
+    console.log(`Failed: ${failed}`);
+    console.log(`Average Response Time: ${avgTime.toFixed(0)}ms`);
+  }
+
+  private analyzeResults(): void {
+    console.log("\n💡 AI Analysis & Recommendations");
+    console.log("=" .repeat(50));
+
+    const slowEndpoints = this.results.filter((r) => r.responseTime > 1000);
+    if (slowEndpoints.length > 0) {
+      console.log("\n⚠️  Slow Endpoints (>1000ms):");
+      slowEndpoints.forEach((r) => {
+        console.log(`  - ${r.endpoint}: ${r.responseTime}ms`);
+      });
+      console.log("  💡 Consider optimizing database queries or adding caching");
+    }
+
+    const failedEndpoints = this.results.filter((r) => r.status === "fail");
+    if (failedEndpoints.length > 0) {
+      console.log("\n❌ Failed Endpoints:");
+      failedEndpoints.forEach((r) => {
+        console.log(`  - ${r.endpoint}: ${r.statusCode || r.error}`);
+      });
+      console.log("  💡 Review error handling and endpoint implementations");
+    }
+
+    const avgTime =
+      this.results.reduce((sum, r) => sum + r.responseTime, 0) /
+      this.results.length;
+    if (avgTime < 100) {
+      console.log("\n✨ Great performance! All endpoints responding quickly.");
+    }
+  }
+}
+
+// Run the AI agent
+async function main() {
+  const bridgeKey = process.env.LIVEPORT_KEY;
+
+  if (!bridgeKey) {
+    console.error("Error: LIVEPORT_KEY environment variable not set");
+    process.exit(1);
+  }
+
+  const tester = new AIAgentTester(bridgeKey);
+  await tester.run();
+}
+
+main();

package/examples/04-multiple-tunnels.ts

@@ -0,0 +1,84 @@
+/**
+ * Multiple Tunnels Example
+ *
+ * This example shows how to work with multiple tunnels
+ * when testing microservices or multi-service architectures.
+ */
+
+import { LivePortAgent } from "@liveport/agent-sdk";
+
+async function main() {
+  const agent = new LivePortAgent({
+    key: process.env.LIVEPORT_KEY!,
+  });
+
+  console.log("🔍 Checking for available tunnels...\n");
+
+  try {
+    // List all active tunnels for this bridge key
+    const tunnels = await agent.listTunnels();
+
+    if (tunnels.length === 0) {
+      console.log("No tunnels available.");
+      console.log("Start one or more tunnels with:");
+      console.log("  liveport connect 3000  # API server");
+      console.log("  liveport connect 3001  # Web server");
+      console.log("  liveport connect 5432  # Database");
+      return;
+    }
+
+    console.log(`Found ${tunnels.length} active tunnel(s):\n`);
+
+    // Display tunnel information
+    for (const tunnel of tunnels) {
+      console.log(`📍 ${tunnel.subdomain}`);
+      console.log(`   URL: ${tunnel.url}`);
+      console.log(`   Local Port: ${tunnel.localPort}`);
+      console.log(`   Created: ${tunnel.createdAt.toLocaleString()}`);
+      console.log(`   Expires: ${tunnel.expiresAt.toLocaleString()}`);
+      console.log();
+    }
+
+    // Example: Test each tunnel
+    console.log("Testing each tunnel...\n");
+
+    for (const tunnel of tunnels) {
+      try {
+        const response = await fetch(tunnel.url, {
+          signal: AbortSignal.timeout(5000),
+        });
+
+        console.log(
+          `✓ ${tunnel.subdomain.padEnd(30)} [${response.status}] ${response.statusText}`
+        );
+      } catch (error) {
+        console.log(`✗ ${tunnel.subdomain.padEnd(30)} [ERROR] ${error}`);
+      }
+    }
+
+    // Example: Find specific service by port
+    const apiTunnel = tunnels.find((t) => t.localPort === 3000);
+    if (apiTunnel) {
+      console.log(`\n🎯 Found API server at ${apiTunnel.url}`);
+
+      // Run API-specific tests
+      const health = await fetch(`${apiTunnel.url}/health`);
+      console.log(`   Health check: ${health.status}`);
+    }
+
+    const webTunnel = tunnels.find((t) => t.localPort === 3001);
+    if (webTunnel) {
+      console.log(`\n🎯 Found web server at ${webTunnel.url}`);
+
+      // Run web-specific tests
+      const homepage = await fetch(webTunnel.url);
+      console.log(`   Homepage: ${homepage.status}`);
+    }
+  } catch (error) {
+    console.error("Error:", error);
+  } finally {
+    await agent.disconnect();
+  }
+}
+
+main();

package/examples/05-error-handling.ts

@@ -0,0 +1,148 @@
+/**
+ * Error Handling Example
+ *
+ * This example demonstrates proper error handling patterns
+ * when using the LivePort Agent SDK.
+ */
+
+import {
+  LivePortAgent,
+  TunnelTimeoutError,
+  ApiError,
+} from "@liveport/agent-sdk";
+
+async function robustTunnelAccess() {
+  const agent = new LivePortAgent({
+    key: process.env.LIVEPORT_KEY!,
+    timeout: 30000,
+  });
+
+  try {
+    console.log("⏳ Waiting for tunnel...");
+
+    const tunnel = await agent.waitForTunnel({
+      timeout: 30000,
+      pollInterval: 2000,
+    });
+
+    console.log(`✓ Connected to ${tunnel.url}`);
+
+    // Your application logic here
+    await runTests(tunnel.url);
+  } catch (error) {
+    // Handle specific error types
+    if (error instanceof TunnelTimeoutError) {
+      console.error("\n❌ Tunnel Timeout");
+      console.error("   No tunnel became available within the timeout period.");
+      console.error("\n💡 Make sure to:");
+      console.error("   1. Start your local server (e.g., npm run dev)");
+      console.error("   2. Run: liveport connect <port>");
+      console.error("   3. Wait for tunnel URL to appear");
+      console.error("   4. Then run this script again");
+      process.exit(1);
+    } else if (error instanceof ApiError) {
+      console.error(`\n❌ API Error [${error.code}]`);
+      console.error(`   ${error.message}`);
+      console.error(`   Status: ${error.statusCode}`);
+
+      // Handle specific error codes
+      switch (error.code) {
+        case "INVALID_KEY":
+          console.error("\n💡 Your bridge key is invalid or expired.");
+          console.error("   Get a new key at: https://liveport.dev/keys");
+          break;
+
+        case "EXPIRED_KEY":
+          console.error("\n💡 Your bridge key has expired.");
+          console.error("   Create a new key at: https://liveport.dev/keys");
+          break;
+
+        case "REVOKED_KEY":
+          console.error("\n💡 Your bridge key has been revoked.");
+          console.error("   Create a new key at: https://liveport.dev/keys");
+          break;
+
+        case "USAGE_LIMIT_EXCEEDED":
+          console.error("\n💡 Your bridge key has exceeded its usage limit.");
+          console.error("   Create a new key or increase the limit at:");
+          console.error("   https://liveport.dev/keys");
+          break;
+
+        case "RATE_LIMIT_EXCEEDED":
+          console.error("\n💡 Too many requests. Please wait and try again.");
+          break;
+
+        default:
+          console.error("\n💡 Please check your configuration and try again.");
+      }
+
+      process.exit(1);
+    } else if (error instanceof Error) {
+      console.error("\n❌ Unexpected Error");
+      console.error(`   ${error.message}`);
+      console.error("\n💡 Please report this issue at:");
+      console.error("   https://github.com/dundas/liveport/issues");
+      process.exit(1);
+    } else {
+      console.error("\n❌ Unknown Error");
+      console.error(error);
+      process.exit(1);
+    }
+  } finally {
+    // Always clean up
+    await agent.disconnect();
+  }
+}
+
+async function runTests(tunnelUrl: string) {
+  console.log("\n🧪 Running tests...");
+
+  try {
+    // Example test with retry logic
+    const response = await fetchWithRetry(`${tunnelUrl}/api/health`, {
+      maxRetries: 3,
+      retryDelay: 1000,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Health check failed: ${response.status}`);
+    }
+
+    console.log("✓ Health check passed");
+
+    // More tests...
+    console.log("✓ All tests passed!");
+  } catch (error) {
+    console.error("✗ Tests failed:", error);
+    throw error;
+  }
+}
+
+async function fetchWithRetry(
+  url: string,
+  options: { maxRetries?: number; retryDelay?: number } = {}
+): Promise<Response> {
+  const { maxRetries = 3, retryDelay = 1000 } = options;
+
+  for (let i = 0; i <= maxRetries; i++) {
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(5000),
+      });
+
+      return response;
+    } catch (error) {
+      if (i === maxRetries) {
+        throw error;
+      }
+
+      console.log(`   Retry ${i + 1}/${maxRetries} after ${retryDelay}ms...`);
+      await new Promise((resolve) => setTimeout(resolve, retryDelay));
+    }
+  }
+
+  throw new Error("Max retries exceeded");
+}
+
+// Run with proper error handling
+robustTunnelAccess();

package/examples/README.md

@@ -0,0 +1,172 @@
+# LivePort Agent SDK Examples
+
+This directory contains practical examples demonstrating different use cases for the LivePort Agent SDK.
+
+## Running the Examples
+
+1. **Install dependencies:**
+   ```bash
+   pnpm install
+   ```
+
+2. **Set your bridge key:**
+   ```bash
+   export LIVEPORT_KEY=lpk_your_bridge_key_here
+   ```
+
+3. **Start a local tunnel:**
+   ```bash
+   # In a separate terminal
+   liveport connect 3000
+   ```
+
+4. **Run an example:**
+   ```bash
+   npx tsx examples/01-basic-usage.ts
+   ```
+
+## Examples Overview
+
+### `01-basic-usage.ts`
+**Simplest example** showing how to wait for a tunnel and make a request.
+
+**Use case:** Quick start, proof of concept
+
+**Key concepts:**
+- Creating an agent instance
+- Waiting for tunnel
+- Making HTTP requests
+- Basic error handling
+
+---
+
+### `02-testing-integration.ts`
+**Testing framework integration** using Vitest (works with Jest too).
+
+**Use case:** Automated testing, CI/CD pipelines
+
+**Key concepts:**
+- beforeAll/afterAll hooks
+- Multiple test cases
+- Sharing tunnel across tests
+- Timeout configuration
+
+---
+
+### `03-ai-agent-workflow.ts`
+**Complete AI agent workflow** that discovers, tests, and analyzes endpoints.
+
+**Use case:** AI-powered testing, endpoint discovery, performance analysis
+
+**Key concepts:**
+- Endpoint discovery
+- Performance measurement
+- Result analysis
+- AI recommendations
+
+---
+
+### `04-multiple-tunnels.ts`
+**Working with multiple tunnels** for microservices testing.
+
+**Use case:** Multi-service architectures, microservices
+
+**Key concepts:**
+- Listing all tunnels
+- Finding tunnels by port
+- Testing multiple services
+- Service-specific logic
+
+---
+
+### `05-error-handling.ts`
+**Comprehensive error handling** patterns and best practices.
+
+**Use case:** Production applications, robust error handling
+
+**Key concepts:**
+- Specific error types
+- User-friendly error messages
+- Retry logic
+- Cleanup and recovery
+
+---
+
+## Common Patterns
+
+### Pattern 1: Wait with Timeout
+
+```typescript
+const agent = new LivePortAgent({ key: "lpk_..." });
+
+try {
+  const tunnel = await agent.waitForTunnel({ timeout: 60000 });
+  // Use tunnel.url
+} catch (error) {
+  if (error instanceof TunnelTimeoutError) {
+    console.log("No tunnel available");
+  }
+}
+```
+
+### Pattern 2: Test Suite Integration
+
+```typescript
+let tunnelUrl: string;
+
+beforeAll(async () => {
+  const agent = new LivePortAgent({ key: process.env.LIVEPORT_KEY! });
+  const tunnel = await agent.waitForTunnel();
+  tunnelUrl = tunnel.url;
+});
+
+test("API test", async () => {
+  const response = await fetch(`${tunnelUrl}/api/endpoint`);
+  // assertions...
+});
+```
+
+### Pattern 3: Multiple Services
+
+```typescript
+const agent = new LivePortAgent({ key: "lpk_..." });
+const tunnels = await agent.listTunnels();
+
+const apiTunnel = tunnels.find(t => t.localPort === 3000);
+const webTunnel = tunnels.find(t => t.localPort === 3001);
+
+// Test API
+await fetch(`${apiTunnel.url}/health`);
+
+// Test Web
+await fetch(`${webTunnel.url}/`);
+```
+
+## Tips
+
+1. **Always set a timeout** - Use reasonable timeouts to avoid hanging indefinitely
+2. **Handle errors gracefully** - Provide helpful error messages for users
+3. **Clean up resources** - Always call `agent.disconnect()` in finally blocks
+4. **Use environment variables** - Never hardcode bridge keys
+5. **Add retry logic** - Network requests can fail, especially in CI/CD
+
+## Environment Variables
+
+All examples support these environment variables:
+
+- `LIVEPORT_KEY` - Your bridge key (required)
+- `LIVEPORT_API_URL` - Custom API URL (optional)
+
+## Next Steps
+
+After trying these examples, check out:
+
+- [API Documentation](../README.md)
+- [CLI Documentation](../../cli/README.md)
+- [Dashboard](https://liveport.dev/dashboard)
+
+## Need Help?
+
+- 📚 [Full Documentation](https://liveport.dev/docs)
+- 🐛 [Report Issues](https://github.com/dundas/liveport/issues)
+- 💬 [Community Support](https://liveport.dev/support)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveport/agent-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for AI agents to access LivePort tunnels",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "examples",
     "README.md"
   ],
   "scripts": {
@@ -44,7 +45,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dundas/liveport.git",
+    "url": "git+https://github.com/dundas/liveport-private.git",
     "directory": "packages/agent-sdk"
   },
   "publishConfig": {