@liveport/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,609 @@
+# @liveport/agent-sdk
+
+> TypeScript SDK for AI agents to discover and access LivePort tunnels
+
+Enable AI agents and automated testing frameworks to seamlessly access localhost applications through secure LivePort tunnels. Perfect for E2E testing, AI-powered development tools, and automated workflows.
+
+[![npm version](https://img.shields.io/npm/v/@liveport/agent-sdk.svg)](https://www.npmjs.com/package/@liveport/agent-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **🔍 Auto-Discovery** - Wait for tunnels to become available automatically
+- **🤖 AI-First Design** - Built specifically for AI agents and automation
+- **⏱️ Configurable Timeouts** - Fine-tune waiting and polling behavior
+- **🔐 Secure Authentication** - Bridge key-based authentication
+- **📊 Multiple Tunnels** - List and manage multiple active tunnels
+- **🧪 Testing Ready** - Perfect for CI/CD and automated testing
+- **TypeScript Native** - Full type safety and IntelliSense support
+
+## Installation
+
+```bash
+npm install @liveport/agent-sdk
+# or
+pnpm add @liveport/agent-sdk
+# or
+yarn add @liveport/agent-sdk
+```
+
+## Quick Start
+
+```typescript
+import { LivePortAgent } from '@liveport/agent-sdk';
+
+// Create agent instance
+const agent = new LivePortAgent({
+  key: process.env.LIVEPORT_KEY!
+});
+
+// Wait for tunnel to become available
+const tunnel = await agent.waitForTunnel({ timeout: 30000 });
+console.log(`Testing at: ${tunnel.url}`);
+
+// Run your tests against tunnel.url
+const response = await fetch(`${tunnel.url}/api/health`);
+console.log(await response.json());
+
+// Clean up when done
+await agent.disconnect();
+```
+
+## API Reference
+
+### `LivePortAgent`
+
+Main SDK class for interacting with LivePort tunnels.
+
+#### Constructor
+
+```typescript
+new LivePortAgent(config: LivePortAgentConfig)
+```
+
+**Config options:**
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `key` | string | ✅ | - | Bridge key for authentication |
+| `apiUrl` | string | ❌ | `https://app.liveport.dev` | API base URL |
+| `timeout` | number | ❌ | `30000` | Default timeout in milliseconds |
+
+**Example:**
+
+```typescript
+const agent = new LivePortAgent({
+  key: 'lpk_abc123...',
+  apiUrl: 'https://app.liveport.dev',
+  timeout: 60000
+});
+```
+
+---
+
+#### `waitForTunnel(options?)`
+
+Wait for a tunnel to become available. Long-polls the API until a tunnel is ready or timeout is reached.
+
+```typescript
+async waitForTunnel(options?: WaitForTunnelOptions): Promise<AgentTunnel>
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | `30000` | Maximum wait time in milliseconds |
+| `pollInterval` | number | `1000` | Poll interval in milliseconds |
+
+**Returns:** `Promise<AgentTunnel>`
+
+**Throws:**
+- `TunnelTimeoutError` - If no tunnel becomes available within timeout
+- `ApiError` - If the API request fails
+
+**Example:**
+
+```typescript
+try {
+  const tunnel = await agent.waitForTunnel({
+    timeout: 60000,      // Wait up to 60 seconds
+    pollInterval: 2000   // Check every 2 seconds
+  });
+
+  console.log(`Tunnel available at: ${tunnel.url}`);
+} catch (error) {
+  if (error instanceof TunnelTimeoutError) {
+    console.log('No tunnel available yet');
+  }
+}
+```
+
+---
+
+#### `listTunnels()`
+
+List all active tunnels for this bridge key.
+
+```typescript
+async listTunnels(): Promise<AgentTunnel[]>
+```
+
+**Returns:** `Promise<AgentTunnel[]>` - Array of active tunnels
+
+**Throws:** `ApiError` - If the API request fails
+
+**Example:**
+
+```typescript
+const tunnels = await agent.listTunnels();
+
+for (const tunnel of tunnels) {
+  console.log(`${tunnel.subdomain}: ${tunnel.url} (port ${tunnel.localPort})`);
+}
+
+// Find specific tunnel by port
+const apiTunnel = tunnels.find(t => t.localPort === 3000);
+if (apiTunnel) {
+  console.log(`API server at: ${apiTunnel.url}`);
+}
+```
+
+---
+
+#### `disconnect()`
+
+Disconnect and clean up. Cancels any pending `waitForTunnel` calls.
+
+```typescript
+async disconnect(): Promise<void>
+```
+
+**Example:**
+
+```typescript
+// Always clean up in a finally block
+try {
+  const tunnel = await agent.waitForTunnel();
+  // Use tunnel...
+} finally {
+  await agent.disconnect();
+}
+```
+
+---
+
+### Types
+
+#### `AgentTunnel`
+
+Represents a tunnel connection.
+
+```typescript
+interface AgentTunnel {
+  tunnelId: string;      // Unique tunnel identifier
+  subdomain: string;     // Subdomain (e.g., "swift-fox-a7x2")
+  url: string;           // Full public URL
+  localPort: number;     // Local port being tunneled
+  createdAt: Date;       // When tunnel was created
+  expiresAt: Date;       // When tunnel will expire
+}
+```
+
+#### `TunnelTimeoutError`
+
+Thrown when `waitForTunnel` times out.
+
+```typescript
+class TunnelTimeoutError extends Error {
+  constructor(timeout: number);
+}
+```
+
+#### `ApiError`
+
+Thrown when an API request fails.
+
+```typescript
+class ApiError extends Error {
+  statusCode: number;     // HTTP status code
+  code: string;           // Error code (e.g., "INVALID_KEY")
+
+  constructor(statusCode: number, code: string, message: string);
+}
+```
+
+**Error Codes:**
+- `INVALID_KEY` - Bridge key is invalid
+- `EXPIRED_KEY` - Bridge key has expired
+- `REVOKED_KEY` - Bridge key was revoked
+- `USAGE_LIMIT_EXCEEDED` - Key usage limit reached
+- `RATE_LIMIT_EXCEEDED` - Too many requests
+- `TIMEOUT` - Server timeout
+- `TUNNEL_SERVER_ERROR` - Tunnel server error
+- `INTERNAL_ERROR` - Internal server error
+
+---
+
+## Use Cases
+
+### 1. Automated Testing
+
+```typescript
+import { LivePortAgent } from '@liveport/agent-sdk';
+import { test, expect } from 'vitest';
+
+let tunnelUrl: string;
+
+beforeAll(async () => {
+  const agent = new LivePortAgent({ key: process.env.LIVEPORT_KEY! });
+  const tunnel = await agent.waitForTunnel({ timeout: 60000 });
+  tunnelUrl = tunnel.url;
+});
+
+test('API returns 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');
+});
+```
+
+### 2. AI Agent Workflow
+
+```typescript
+import { LivePortAgent } from '@liveport/agent-sdk';
+
+async function runAITests(bridgeKey: string) {
+  const agent = new LivePortAgent({ key: bridgeKey, timeout: 120000 });
+
+  console.log('Waiting for developer to start tunnel...');
+  const tunnel = await agent.waitForTunnel();
+
+  console.log(`Connected to ${tunnel.url}`);
+
+  // AI agent can now interact with the local application
+  await discoverEndpoints(tunnel.url);
+  await runPerformanceTests(tunnel.url);
+  await analyzeAPIs(tunnel.url);
+  await generateDocumentation(tunnel.url);
+
+  await agent.disconnect();
+}
+```
+
+### 3. CI/CD Integration
+
+```typescript
+// tests/setup.ts
+import { LivePortAgent } from '@liveport/agent-sdk';
+
+export async function setupTunnel() {
+  const agent = new LivePortAgent({
+    key: process.env.CI_LIVEPORT_KEY!,
+    timeout: 60000
+  });
+
+  // Wait for tunnel (developer must start it before running tests)
+  const tunnel = await agent.waitForTunnel();
+
+  // Make tunnel URL available to tests
+  process.env.TEST_BASE_URL = tunnel.url;
+
+  return { agent, tunnel };
+}
+
+export async function teardownTunnel(agent: LivePortAgent) {
+  await agent.disconnect();
+}
+```
+
+### 4. Multi-Service Testing
+
+```typescript
+import { LivePortAgent } from '@liveport/agent-sdk';
+
+async function testMicroservices() {
+  const agent = new LivePortAgent({ key: process.env.LIVEPORT_KEY! });
+
+  // List all available tunnels
+  const tunnels = await agent.listTunnels();
+
+  // Find specific services by port
+  const api = tunnels.find(t => t.localPort === 3000);
+  const web = tunnels.find(t => t.localPort === 3001);
+  const db = tunnels.find(t => t.localPort === 5432);
+
+  if (!api || !web) {
+    throw new Error('Required services not available');
+  }
+
+  // Test API
+  const apiHealth = await fetch(`${api.url}/health`);
+  console.log(`API: ${apiHealth.status}`);
+
+  // Test Web
+  const webHome = await fetch(web.url);
+  console.log(`Web: ${webHome.status}`);
+
+  await agent.disconnect();
+}
+```
+
+### 5. Webhook Testing
+
+```typescript
+import { LivePortAgent } from '@liveport/agent-sdk';
+
+async function testWebhooks() {
+  const agent = new LivePortAgent({ key: process.env.LIVEPORT_KEY! });
+  const tunnel = await agent.waitForTunnel();
+
+  // Register webhook with external service
+  await registerWebhook(`${tunnel.url}/webhooks/stripe`);
+
+  // Trigger webhook event
+  await triggerTestEvent();
+
+  // Verify webhook was received
+  const response = await fetch(`${tunnel.url}/webhooks/verify`);
+  const result = await response.json();
+
+  expect(result.received).toBe(true);
+
+  await agent.disconnect();
+}
+```
+
+---
+
+## Error Handling
+
+### Handling Timeouts
+
+```typescript
+import { LivePortAgent, TunnelTimeoutError } from '@liveport/agent-sdk';
+
+try {
+  const tunnel = await agent.waitForTunnel({ timeout: 30000 });
+} catch (error) {
+  if (error instanceof TunnelTimeoutError) {
+    console.error('No tunnel available. Did you forget to run:');
+    console.error('  liveport connect <port>');
+    process.exit(1);
+  }
+  throw error;
+}
+```
+
+### Handling API Errors
+
+```typescript
+import { ApiError } from '@liveport/agent-sdk';
+
+try {
+  const tunnels = await agent.listTunnels();
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.error(`API Error [${error.code}]: ${error.message}`);
+    console.error(`Status: ${error.statusCode}`);
+
+    if (error.code === 'INVALID_KEY') {
+      console.error('Get a new key at: https://liveport.dev/keys');
+    }
+  }
+  throw error;
+}
+```
+
+### Robust Error Handling Pattern
+
+```typescript
+async function robustTunnelAccess() {
+  const agent = new LivePortAgent({ key: process.env.LIVEPORT_KEY! });
+
+  try {
+    const tunnel = await agent.waitForTunnel({ timeout: 60000 });
+
+    // Your logic here
+    await runTests(tunnel.url);
+
+  } catch (error) {
+    if (error instanceof TunnelTimeoutError) {
+      console.error('Timeout waiting for tunnel');
+      process.exit(1);
+    } else if (error instanceof ApiError) {
+      console.error(`API Error: ${error.message}`);
+      process.exit(1);
+    } else {
+      console.error('Unexpected error:', error);
+      process.exit(1);
+    }
+  } finally {
+    await agent.disconnect();
+  }
+}
+```
+
+---
+
+## Examples
+
+Comprehensive examples are available in the [`examples/`](./examples/) directory:
+
+- **[01-basic-usage.ts](./examples/01-basic-usage.ts)** - Simple tunnel connection
+- **[02-testing-integration.ts](./examples/02-testing-integration.ts)** - Vitest integration
+- **[03-ai-agent-workflow.ts](./examples/03-ai-agent-workflow.ts)** - AI agent implementation
+- **[04-multiple-tunnels.ts](./examples/04-multiple-tunnels.ts)** - Multi-service testing
+- **[05-error-handling.ts](./examples/05-error-handling.ts)** - Robust error handling
+
+Run examples:
+
+```bash
+# Set your bridge key
+export LIVEPORT_KEY=lpk_your_key_here
+
+# Start a tunnel in another terminal
+liveport connect 3000
+
+# Run an example
+npx tsx examples/01-basic-usage.ts
+```
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+1. **Set reasonable timeouts**
+   ```typescript
+   // Good: 60 second timeout for CI
+   const tunnel = await agent.waitForTunnel({ timeout: 60000 });
+   ```
+
+2. **Always clean up**
+   ```typescript
+   try {
+     const tunnel = await agent.waitForTunnel();
+     // Use tunnel...
+   } finally {
+     await agent.disconnect(); // Always cleanup
+   }
+   ```
+
+3. **Handle specific errors**
+   ```typescript
+   try {
+     const tunnel = await agent.waitForTunnel();
+   } catch (error) {
+     if (error instanceof TunnelTimeoutError) {
+       // Provide helpful message
+     }
+   }
+   ```
+
+4. **Use environment variables**
+   ```typescript
+   // Good
+   const agent = new LivePortAgent({
+     key: process.env.LIVEPORT_KEY!
+   });
+
+   // Bad - never hardcode keys
+   const agent = new LivePortAgent({ key: 'lpk_...' });
+   ```
+
+5. **Configure appropriate timeouts**
+   ```typescript
+   // Local development: short timeout
+   const tunnel = await agent.waitForTunnel({ timeout: 10000 });
+
+   // CI/CD: longer timeout
+   const tunnel = await agent.waitForTunnel({ timeout: 120000 });
+   ```
+
+### ❌ Don'ts
+
+1. **Don't commit bridge keys**
+   ```bash
+   # Use .env.local (git-ignored)
+   LIVEPORT_KEY=lpk_your_key_here
+   ```
+
+2. **Don't forget to disconnect**
+   ```typescript
+   // Bad - missing cleanup
+   const tunnel = await agent.waitForTunnel();
+   // ... tests ...
+   // Missing: await agent.disconnect()
+   ```
+
+3. **Don't ignore errors**
+   ```typescript
+   // Bad - swallowing errors
+   try {
+     const tunnel = await agent.waitForTunnel();
+   } catch (error) {
+     // Silent failure
+   }
+   ```
+
+4. **Don't use production keys in tests**
+   ```bash
+   # Separate keys for different environments
+   LIVEPORT_DEV_KEY=lpk_dev_...
+   LIVEPORT_CI_KEY=lpk_ci_...
+   LIVEPORT_PROD_KEY=lpk_prod_...
+   ```
+
+---
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions.
+
+```typescript
+import type {
+  LivePortAgent,
+  LivePortAgentConfig,
+  AgentTunnel,
+  WaitForTunnelOptions,
+  TunnelTimeoutError,
+  ApiError
+} from '@liveport/agent-sdk';
+
+// Full IntelliSense support
+const config: LivePortAgentConfig = {
+  key: 'lpk_...',
+  timeout: 30000
+};
+
+const agent: LivePortAgent = new LivePortAgent(config);
+const tunnel: AgentTunnel = await agent.waitForTunnel();
+```
+
+---
+
+## Testing
+
+The SDK includes comprehensive tests. Run them with:
+
+```bash
+pnpm test
+```
+
+---
+
+## Related Packages
+
+- **[@liveport/cli](https://www.npmjs.com/package/@liveport/cli)** - CLI for creating tunnels
+- **[Dashboard](https://liveport.dev/dashboard)** - Web interface for managing keys and tunnels
+
+---
+
+## Resources
+
+- **Documentation**: [liveport.dev/docs](https://liveport.dev/docs)
+- **API Reference**: [liveport.dev/docs](https://liveport.dev/docs)
+- **Dashboard**: [liveport.dev/dashboard](https://liveport.dev/dashboard)
+- **Examples**: [examples/](./examples/)
+- **Support**: [GitHub Issues](https://github.com/dundas/liveport/issues)
+- **Website**: [liveport.dev](https://liveport.dev)
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) first.
+
+---
+
+## License
+
+MIT © LivePort
+
+---
+
+**Built with ❤️ for AI agents and developers**

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+export { Tunnel } from '@liveport/shared';
+
+/**
+ * LivePort Agent SDK
+ *
+ * TypeScript SDK for AI agents to wait for and access localhost tunnels.
+ */
+interface LivePortAgentConfig {
+    /** Bridge key for authentication */
+    key: string;
+    /** API base URL (default: https://app.liveport.dev) */
+    apiUrl?: string;
+    /** Default timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface WaitForTunnelOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Poll interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+}
+interface AgentTunnel {
+    tunnelId: string;
+    subdomain: string;
+    url: string;
+    localPort: number;
+    createdAt: Date;
+    expiresAt: Date;
+}
+/** Error thrown when tunnel wait times out */
+declare class TunnelTimeoutError extends Error {
+    constructor(timeout: number);
+}
+/** Error thrown when API request fails */
+declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+/**
+ * LivePort Agent SDK
+ *
+ * Allows AI agents to wait for and access localhost tunnels.
+ *
+ * @example
+ * ```typescript
+ * import { LivePortAgent } from '@liveport/agent-sdk';
+ *
+ * const agent = new LivePortAgent({
+ *   key: process.env.LIVEPORT_BRIDGE_KEY!
+ * });
+ *
+ * // Wait for a tunnel to become available
+ * const tunnel = await agent.waitForTunnel({ timeout: 30000 });
+ * console.log(`Testing at: ${tunnel.url}`);
+ *
+ * // Run your tests against tunnel.url
+ *
+ * // Clean up when done
+ * await agent.disconnect();
+ * ```
+ */
+declare class LivePortAgent {
+    private config;
+    private abortController;
+    constructor(config: LivePortAgentConfig);
+    /**
+     * Wait for a tunnel to become available
+     *
+     * Long-polls the API until a tunnel is ready or timeout is reached.
+     *
+     * @param options - Wait options
+     * @returns The tunnel info once available
+     * @throws TunnelTimeoutError if no tunnel becomes available within timeout
+     * @throws ApiError if the API request fails
+     */
+    waitForTunnel(options?: WaitForTunnelOptions): Promise<AgentTunnel>;
+    /**
+     * List all active tunnels for this bridge key
+     *
+     * @returns Array of active tunnels
+     * @throws ApiError if the API request fails
+     */
+    listTunnels(): Promise<AgentTunnel[]>;
+    /**
+     * Disconnect and clean up
+     *
+     * Cancels any pending waitForTunnel calls.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Make an authenticated API request
+     */
+    private makeRequest;
+    /**
+     * Parse tunnel response into AgentTunnel
+     */
+    private parseTunnel;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+
+export { type AgentTunnel, ApiError, LivePortAgent, type LivePortAgentConfig, TunnelTimeoutError, type WaitForTunnelOptions };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export { Tunnel } from '@liveport/shared';
+
+/**
+ * LivePort Agent SDK
+ *
+ * TypeScript SDK for AI agents to wait for and access localhost tunnels.
+ */
+interface LivePortAgentConfig {
+    /** Bridge key for authentication */
+    key: string;
+    /** API base URL (default: https://app.liveport.dev) */
+    apiUrl?: string;
+    /** Default timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface WaitForTunnelOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Poll interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+}
+interface AgentTunnel {
+    tunnelId: string;
+    subdomain: string;
+    url: string;
+    localPort: number;
+    createdAt: Date;
+    expiresAt: Date;
+}
+/** Error thrown when tunnel wait times out */
+declare class TunnelTimeoutError extends Error {
+    constructor(timeout: number);
+}
+/** Error thrown when API request fails */
+declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+/**
+ * LivePort Agent SDK
+ *
+ * Allows AI agents to wait for and access localhost tunnels.
+ *
+ * @example
+ * ```typescript
+ * import { LivePortAgent } from '@liveport/agent-sdk';
+ *
+ * const agent = new LivePortAgent({
+ *   key: process.env.LIVEPORT_BRIDGE_KEY!
+ * });
+ *
+ * // Wait for a tunnel to become available
+ * const tunnel = await agent.waitForTunnel({ timeout: 30000 });
+ * console.log(`Testing at: ${tunnel.url}`);
+ *
+ * // Run your tests against tunnel.url
+ *
+ * // Clean up when done
+ * await agent.disconnect();
+ * ```
+ */
+declare class LivePortAgent {
+    private config;
+    private abortController;
+    constructor(config: LivePortAgentConfig);
+    /**
+     * Wait for a tunnel to become available
+     *
+     * Long-polls the API until a tunnel is ready or timeout is reached.
+     *
+     * @param options - Wait options
+     * @returns The tunnel info once available
+     * @throws TunnelTimeoutError if no tunnel becomes available within timeout
+     * @throws ApiError if the API request fails
+     */
+    waitForTunnel(options?: WaitForTunnelOptions): Promise<AgentTunnel>;
+    /**
+     * List all active tunnels for this bridge key
+     *
+     * @returns Array of active tunnels
+     * @throws ApiError if the API request fails
+     */
+    listTunnels(): Promise<AgentTunnel[]>;
+    /**
+     * Disconnect and clean up
+     *
+     * Cancels any pending waitForTunnel calls.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Make an authenticated API request
+     */
+    private makeRequest;
+    /**
+     * Parse tunnel response into AgentTunnel
+     */
+    private parseTunnel;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+
+export { type AgentTunnel, ApiError, LivePortAgent, type LivePortAgentConfig, TunnelTimeoutError, type WaitForTunnelOptions };

package/dist/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  LivePortAgent: () => LivePortAgent,
+  TunnelTimeoutError: () => TunnelTimeoutError
+});
+module.exports = __toCommonJS(index_exports);
+var TunnelTimeoutError = class extends Error {
+  constructor(timeout) {
+    super(`Tunnel not available within ${timeout}ms timeout`);
+    this.name = "TunnelTimeoutError";
+  }
+};
+var ApiError = class extends Error {
+  statusCode;
+  code;
+  constructor(statusCode, code, message) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+var LivePortAgent = class {
+  config;
+  abortController = null;
+  constructor(config) {
+    if (!config.key) {
+      throw new Error("Bridge key is required");
+    }
+    this.config = {
+      key: config.key,
+      apiUrl: config.apiUrl || "https://app.liveport.dev",
+      timeout: config.timeout || 3e4
+    };
+  }
+  /**
+   * Wait for a tunnel to become available
+   *
+   * Long-polls the API until a tunnel is ready or timeout is reached.
+   *
+   * @param options - Wait options
+   * @returns The tunnel info once available
+   * @throws TunnelTimeoutError if no tunnel becomes available within timeout
+   * @throws ApiError if the API request fails
+   */
+  async waitForTunnel(options) {
+    const timeout = options?.timeout ?? this.config.timeout;
+    const pollInterval = options?.pollInterval ?? 1e3;
+    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);
+          }
+        } 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);
+  }
+  /**
+   * List all active tunnels for this bridge key
+   *
+   * @returns Array of active tunnels
+   * @throws ApiError if the API request fails
+   */
+  async listTunnels() {
+    const response = await this.makeRequest("/api/agent/tunnels");
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ code: "UNKNOWN", message: "Request failed" }));
+      throw new ApiError(response.status, error.code, error.message);
+    }
+    const data = await response.json();
+    return (data.tunnels || []).map((t) => this.parseTunnel(t));
+  }
+  /**
+   * Disconnect and clean up
+   *
+   * Cancels any pending waitForTunnel calls.
+   */
+  async disconnect() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async makeRequest(path, options = {}) {
+    const url = `${this.config.apiUrl}${path}`;
+    return fetch(url, {
+      ...options,
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+  }
+  /**
+   * Parse tunnel response into AgentTunnel
+   */
+  parseTunnel(data) {
+    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)
+    };
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  LivePortAgent,
+  TunnelTimeoutError
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/dist/index.mjs

@@ -0,0 +1,137 @@
+// src/index.ts
+var TunnelTimeoutError = class extends Error {
+  constructor(timeout) {
+    super(`Tunnel not available within ${timeout}ms timeout`);
+    this.name = "TunnelTimeoutError";
+  }
+};
+var ApiError = class extends Error {
+  statusCode;
+  code;
+  constructor(statusCode, code, message) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+var LivePortAgent = class {
+  config;
+  abortController = null;
+  constructor(config) {
+    if (!config.key) {
+      throw new Error("Bridge key is required");
+    }
+    this.config = {
+      key: config.key,
+      apiUrl: config.apiUrl || "https://app.liveport.dev",
+      timeout: config.timeout || 3e4
+    };
+  }
+  /**
+   * Wait for a tunnel to become available
+   *
+   * Long-polls the API until a tunnel is ready or timeout is reached.
+   *
+   * @param options - Wait options
+   * @returns The tunnel info once available
+   * @throws TunnelTimeoutError if no tunnel becomes available within timeout
+   * @throws ApiError if the API request fails
+   */
+  async waitForTunnel(options) {
+    const timeout = options?.timeout ?? this.config.timeout;
+    const pollInterval = options?.pollInterval ?? 1e3;
+    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);
+          }
+        } 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);
+  }
+  /**
+   * List all active tunnels for this bridge key
+   *
+   * @returns Array of active tunnels
+   * @throws ApiError if the API request fails
+   */
+  async listTunnels() {
+    const response = await this.makeRequest("/api/agent/tunnels");
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ code: "UNKNOWN", message: "Request failed" }));
+      throw new ApiError(response.status, error.code, error.message);
+    }
+    const data = await response.json();
+    return (data.tunnels || []).map((t) => this.parseTunnel(t));
+  }
+  /**
+   * Disconnect and clean up
+   *
+   * Cancels any pending waitForTunnel calls.
+   */
+  async disconnect() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async makeRequest(path, options = {}) {
+    const url = `${this.config.apiUrl}${path}`;
+    return fetch(url, {
+      ...options,
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+  }
+  /**
+   * Parse tunnel response into AgentTunnel
+   */
+  parseTunnel(data) {
+    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)
+    };
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  ApiError,
+  LivePortAgent,
+  TunnelTimeoutError
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@liveport/agent-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for AI agents to access LivePort tunnels",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "sdk",
+    "ai-agents",
+    "tunnel",
+    "localhost",
+    "liveport",
+    "testing",
+    "claude",
+    "gpt",
+    "automation"
+  ],
+  "author": "LivePort",
+  "license": "MIT",
+  "homepage": "https://liveport.dev",
+  "bugs": {
+    "url": "https://github.com/dundas/liveport/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dundas/liveport.git",
+    "directory": "packages/agent-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "@liveport/shared": "workspace:*"
+  }
+}