@liveport/agent-sdk 0.1.1 → 0.1.2

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

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

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

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

@@ -1,172 +0,0 @@
-# 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)