@adcp/client 4.21.0 → 4.22.1

package/examples/logger-usage.ts

@@ -0,0 +1,165 @@
+/**
+ * Logger Usage Examples
+ *
+ * Demonstrates how to use the structured logger in AdCP Client
+ */
+
+import { logger, createLogger } from '../src/lib/utils/logger';
+
+// ====== BASIC USAGE ======
+
+console.log('\n=== Basic Usage ===\n');
+
+logger.debug('Debugging info (only visible if LOG_LEVEL=debug)');
+logger.info('General information');
+logger.warn('Warning message');
+logger.error('Error message');
+
+// ====== LOGGING WITH METADATA ======
+
+console.log('\n=== Logging with Metadata ===\n');
+
+logger.info('Task completed', {
+  taskId: 'task_123',
+  duration: 1250,
+  status: 'success',
+});
+
+logger.error('Connection failed', {
+  agentId: 'agent_xyz',
+  error: 'ECONNREFUSED',
+  retryCount: 3,
+});
+
+// ====== CONTEXT-AWARE LOGGING ======
+
+console.log('\n=== Context-Aware Logging ===\n');
+
+// Create protocol-specific logger
+const mcpLogger = logger.child('MCP');
+mcpLogger.info('Connecting to agent', { url: 'https://agent.example.com' });
+mcpLogger.debug('Sending initialize request');
+
+// Create nested context
+const toolLogger = mcpLogger.child('get_products');
+toolLogger.info('Calling tool', { params: { brief: 'Coffee products' } });
+toolLogger.debug('Parsing response');
+
+// ====== CUSTOM LOGGER INSTANCES ======
+
+console.log('\n=== Custom Logger Instances ===\n');
+
+// Create a debug-level logger for development
+const devLogger = createLogger({
+  level: 'debug',
+  enabled: true,
+});
+
+devLogger.debug('This message is visible with debug level');
+devLogger.info('Standard info message');
+
+// Create a production logger (warn level only)
+const prodLogger = createLogger({
+  level: 'warn',
+  enabled: true,
+});
+
+prodLogger.debug('This will NOT be logged');
+prodLogger.info('This will NOT be logged');
+prodLogger.warn('This WILL be logged');
+prodLogger.error('This WILL be logged');
+
+// ====== CUSTOM LOG HANDLERS ======
+
+console.log('\n=== Custom Log Handlers ===\n');
+
+// Example: Send logs to external service
+const externalLogger = createLogger({
+  level: 'info',
+  handler: {
+    debug: (msg, meta) => console.log(`[EXT-DEBUG] ${msg}`, meta || ''),
+    info: (msg, meta) => console.log(`[EXT-INFO] ${msg}`, meta || ''),
+    warn: (msg, meta) => console.log(`[EXT-WARN] ${msg}`, meta || ''),
+    error: (msg, meta) => console.log(`[EXT-ERROR] ${msg}`, meta || ''),
+  },
+});
+
+externalLogger.info('Using custom handler', { service: 'external' });
+
+// ====== RUNTIME CONFIGURATION ======
+
+console.log('\n=== Runtime Configuration ===\n');
+
+// Start with info level
+logger.configure({ level: 'info' });
+logger.debug('This will NOT be logged');
+logger.info('This will be logged');
+
+// Change to debug level
+logger.configure({ level: 'debug' });
+logger.debug('Now this WILL be logged');
+
+// Disable logging temporarily
+logger.configure({ enabled: false });
+logger.error('This will NOT be logged (disabled)');
+
+// Re-enable
+logger.configure({ enabled: true });
+logger.info('Logging re-enabled');
+
+// ====== PRACTICAL EXAMPLES ======
+
+console.log('\n=== Practical Examples ===\n');
+
+// Example 1: Component-specific logging
+class MediaBuyService {
+  private logger = logger.child('MediaBuyService');
+
+  async createMediaBuy(params: any) {
+    this.logger.info('Creating media buy', { params });
+
+    try {
+      // Simulate API call
+      this.logger.debug('Calling agent API');
+      // ...
+      this.logger.info('Media buy created', { buyId: 'mb_123' });
+    } catch (error) {
+      this.logger.error('Failed to create media buy', {
+        error: error instanceof Error ? error.message : String(error),
+        params,
+      });
+      throw error;
+    }
+  }
+}
+
+const service = new MediaBuyService();
+service.createMediaBuy({ brief: 'Coffee campaign' });
+
+// Example 2: Protocol client logging
+class ProtocolClient {
+  private logger = logger.child('ProtocolClient');
+
+  async connect(protocol: string, url: string) {
+    const protocolLogger = this.logger.child(protocol.toUpperCase());
+
+    protocolLogger.info('Connecting to agent', { url });
+
+    try {
+      // Simulate connection
+      protocolLogger.debug('Sending initialize request');
+      protocolLogger.info('Connected successfully');
+    } catch (error) {
+      protocolLogger.error('Connection failed', {
+        url,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+}
+
+const client = new ProtocolClient();
+client.connect('mcp', 'https://agent.example.com');
+
+console.log('\n=== Examples Complete ===\n');

package/examples/oauth-cli-example.ts

@@ -0,0 +1,154 @@
+/**
+ * Example: Using OAuth with the ADCP client
+ *
+ * OAuth tokens are stored directly in the AgentConfig,
+ * same place as static auth tokens.
+ */
+
+import { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import {
+  createCLIOAuthProvider,
+  hasValidOAuthTokens,
+  clearOAuthTokens,
+  getEffectiveAuthToken,
+} from '../src/lib/auth/oauth';
+import type { AgentConfig } from '../src/lib/types/adcp';
+
+// Example: Agent configured for OAuth
+const agent: AgentConfig = {
+  id: 'scope3-snapadcp',
+  name: 'Scope3 SnapAdCP',
+  agent_uri: process.argv[2] || 'https://snapadcp.scope3.com/mcp',
+  protocol: 'mcp',
+  // Static token alternative (uncomment to use instead of OAuth):
+  // auth_token: 'your-api-key-here',
+  //
+  // After OAuth flow completes, these fields are populated:
+  // oauth_tokens: { access_token: '...', refresh_token: '...' }
+  // oauth_client: { client_id: '...' }
+};
+
+async function main() {
+  console.log('ADCP OAuth Example');
+  console.log('==================');
+  console.log(`Agent: ${agent.name}`);
+  console.log(`URI: ${agent.agent_uri}`);
+  console.log(`Has OAuth tokens: ${hasValidOAuthTokens(agent)}`);
+  console.log(`Has static token: ${!!agent.auth_token}`);
+  console.log('');
+
+  // Create OAuth provider - tokens stored in agent config
+  const provider = createCLIOAuthProvider(agent);
+
+  // Create MCP client
+  const client = new MCPClient({
+    name: 'adcp-oauth-example',
+    version: '1.0.0',
+  });
+
+  // Helper to create transport with OAuth provider
+  const createTransport = () =>
+    new StreamableHTTPClientTransport(new URL(agent.agent_uri), {
+      authProvider: provider,
+    });
+
+  let transport = createTransport();
+
+  try {
+    console.log('Connecting...');
+    await client.connect(transport);
+    console.log('Connected!');
+  } catch (error) {
+    if (error instanceof UnauthorizedError) {
+      console.log('');
+      console.log('OAuth authorization required.');
+      console.log('Opening browser...');
+
+      try {
+        // Wait for user to complete OAuth in browser
+        const code = await provider.waitForCallback();
+        console.log('Authorization received!');
+
+        // Finish OAuth flow to exchange code for tokens
+        await transport.finishAuth(code);
+
+        // Show that tokens are now in agent config
+        console.log('');
+        console.log('OAuth tokens saved to agent config:');
+        console.log(`  access_token: ${agent.oauth_tokens?.access_token ? '***' : 'none'}`);
+        console.log(`  refresh_token: ${agent.oauth_tokens?.refresh_token ? '***' : 'none'}`);
+        console.log(`  expires_at: ${agent.oauth_tokens?.expires_at || 'unknown'}`);
+
+        // Create new transport and reconnect (tokens are now available)
+        console.log('');
+        console.log('Reconnecting with tokens...');
+        transport = createTransport();
+        await client.connect(transport);
+        console.log('Connected!');
+      } catch (authError) {
+        console.error('OAuth failed:', authError);
+        await provider.cleanup();
+        process.exit(1);
+      }
+    } else {
+      console.error('Connection failed:', error);
+      await provider.cleanup();
+      process.exit(1);
+    }
+  }
+
+  // List available tools
+  try {
+    console.log('');
+    console.log('Listing tools...');
+    const result = await client.request({ method: 'tools/list', params: {} }, { tools: [] } as any);
+
+    console.log('Available tools:');
+    for (const tool of (result as any).tools || []) {
+      console.log(`  - ${tool.name}`);
+    }
+  } catch (error) {
+    console.error('Failed to list tools:', error);
+  }
+
+  // Clean up
+  await provider.cleanup();
+  await client.close();
+
+  // Show final agent config (for saving to file/db)
+  console.log('');
+  console.log('Final agent config (save this to persist OAuth tokens):');
+  console.log(JSON.stringify(agent, null, 2));
+}
+
+// Utility: clear tokens and re-auth
+async function clearAndReauth() {
+  console.log('Clearing OAuth tokens...');
+  clearOAuthTokens(agent);
+  console.log('Tokens cleared. Run again to re-authenticate.');
+}
+
+// Entry point
+const command = process.argv[2];
+if (command === '--clear') {
+  clearAndReauth();
+} else if (command === '--help' || command === '-h') {
+  console.log(`
+Usage: npx ts-node examples/oauth-cli-example.ts [options] [server-url]
+
+Options:
+  <server-url>   Connect to a specific MCP server (default: https://snapadcp.scope3.com/mcp)
+  --clear        Clear OAuth tokens and exit
+  --help, -h     Show this help
+
+The OAuth flow:
+1. Browser opens for authorization
+2. User logs in and approves
+3. Tokens are saved to agent.oauth_tokens
+4. Save agent config to persist tokens for future use
+`);
+} else {
+  main().catch(console.error);
+}

package/examples/pr78-async-patterns-demo.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+/**
+ * PR #78 Async Patterns Demo
+ *
+ * Demonstrates the new handler-controlled async execution patterns
+ * that align with ADCP spec PR #78
+ */
+
+import {
+  ADCPMultiAgentClient,
+  ADCP_STATUS,
+  autoApproveHandler,
+  deferAllHandler,
+  createFieldHandler,
+  InputRequiredError,
+  type TaskResult,
+  type DeferredContinuation,
+  type SubmittedContinuation,
+} from '../src/lib/index';
+
+async function main() {
+  console.log('🚀 PR #78 Async Patterns Demo\n');
+
+  // Example 1: Immediate completion (status: completed)
+  console.log('📋 Example 1: Immediate Task Completion');
+  console.log('─'.repeat(50));
+
+  const client = ADCPMultiAgentClient.simple('https://demo.example.com', {
+    agentId: 'demo-agent',
+    agentName: 'Demo Agent',
+    protocol: 'mcp',
+  });
+
+  // Simulate immediate completion
+  console.log('• Calling getProducts with auto-approve handler...');
+  try {
+    // This would complete immediately if server returns status: 'completed'
+    const result = await simulateTaskResult('completed', {
+      products: ['Product A', 'Product B', 'Product C'],
+    });
+
+    console.log('✅ Task completed immediately!');
+    console.log(`   Status: ${result.status}`);
+    console.log(`   Products: ${JSON.stringify(result.data?.products || [])}`);
+  } catch (error) {
+    console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+  }
+
+  console.log('\n📋 Example 2: Working Status (keep connection open)');
+  console.log('─'.repeat(50));
+
+  // Simulate server processing (status: working)
+  console.log('• Server is processing (working status)...');
+  console.log('• Client keeps connection open for up to 120 seconds');
+  try {
+    const result = await simulateWorkingTask();
+    console.log('✅ Task completed after server processing!');
+    console.log(`   Status: ${result.status}`);
+  } catch (error) {
+    console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+  }
+
+  console.log('\n📋 Example 3: Input Required with Handler');
+  console.log('─'.repeat(50));
+
+  // Handler provides input immediately
+  const fieldHandler = createFieldHandler({
+    budget: 50000,
+    targeting: ['US', 'CA'],
+    approval: true,
+  });
+
+  console.log('• Server needs input, handler provides it...');
+  try {
+    const result = await simulateInputRequired(fieldHandler);
+    console.log('✅ Handler provided input, task continued!');
+    console.log(`   Status: ${result.status}`);
+  } catch (error) {
+    console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+  }
+
+  console.log('\n📋 Example 4: Input Required without Handler (ERROR)');
+  console.log('─'.repeat(50));
+
+  console.log('• Server needs input, but no handler provided...');
+  try {
+    const result = await simulateInputRequired(); // No handler
+    console.log('❌ This should not happen');
+  } catch (error) {
+    if (error instanceof InputRequiredError) {
+      console.log('✅ Correctly threw InputRequiredError!');
+      console.log(`   Error: ${error.message}`);
+    } else {
+      console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+    }
+  }
+
+  console.log('\n📋 Example 5: Client Deferral (Human-in-the-Loop)');
+  console.log('─'.repeat(50));
+
+  // Handler chooses to defer for human approval
+  const humanApprovalHandler = (context: any) => {
+    if (context.inputRequest.field === 'final_approval') {
+      console.log('• Handler choosing to defer for human approval...');
+      return { defer: true, token: `approval-${Date.now()}` };
+    }
+    return 'auto-approved';
+  };
+
+  try {
+    const result = await simulateClientDeferral(humanApprovalHandler);
+
+    if (result.status === 'deferred' && result.deferred) {
+      console.log('✅ Task successfully deferred!');
+      console.log(`   Token: ${result.deferred.token}`);
+      console.log(`   Question: ${result.deferred.question}`);
+
+      // Later, when human provides input...
+      console.log('• Human provides approval, resuming task...');
+      const finalResult = await result.deferred.resume('APPROVED');
+      console.log('✅ Task resumed and completed!');
+      console.log(`   Final status: ${finalResult.status}`);
+    }
+  } catch (error) {
+    console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+  }
+
+  console.log('\n📋 Example 6: Server Async (Submitted Status)');
+  console.log('─'.repeat(50));
+
+  // Server says task will take hours/days
+  console.log('• Server submitting long-running task...');
+  try {
+    const result = await simulateSubmittedTask();
+
+    if (result.status === 'submitted' && result.submitted) {
+      console.log('✅ Task submitted for async processing!');
+      console.log(`   Task ID: ${result.submitted.taskId}`);
+      console.log(`   Webhook: ${result.submitted.webhookUrl || 'not provided'}`);
+
+      // User can track progress
+      console.log('• Tracking task progress...');
+      const status = await result.submitted.track();
+      console.log(`   Current status: ${status.status}`);
+
+      // Or wait for completion (with polling)
+      console.log('• Waiting for completion (polling every 30s)...');
+      // In real usage: const final = await result.submitted.waitForCompletion(30000);
+      console.log('   (Would poll until completed)');
+    }
+  } catch (error) {
+    console.log(`ℹ️  Note: ${error.message} (expected in demo)`);
+  }
+
+  console.log('\n🎯 Key Takeaways:');
+  console.log('─'.repeat(50));
+  console.log('• ✅ Working status: Client keeps connection open (≤120s)');
+  console.log('• ✅ Input-required: Handler is MANDATORY');
+  console.log('• ✅ Client deferral: Handler returns { defer: true, token }');
+  console.log('• ✅ Server async: Returns { status: "submitted", submitted: { ... } }');
+  console.log('• ✅ Completed: Returns { success: true, data: ... }');
+  console.log('• ✅ No complex config needed - handler controls the flow!');
+
+  console.log('\n🎉 Demo Complete!');
+}
+
+// Demo helper functions (simulate different response patterns)
+
+async function simulateTaskResult(status: string, data: any): Promise<TaskResult<any>> {
+  // In real usage, this would be a real agent call
+  throw new Error('Demo simulation - would call real agent');
+}
+
+async function simulateWorkingTask(): Promise<TaskResult<any>> {
+  throw new Error('Demo simulation - would poll tasks/get endpoint');
+}
+
+async function simulateInputRequired(handler?: any): Promise<TaskResult<any>> {
+  if (!handler) {
+    throw new InputRequiredError('What is your budget for this campaign?');
+  }
+  throw new Error('Demo simulation - would call handler and continue');
+}
+
+async function simulateClientDeferral(handler: any): Promise<TaskResult<any>> {
+  // Simulate the handler being called and choosing to defer
+  const mockContext = {
+    inputRequest: {
+      field: 'final_approval',
+      question: 'Do you approve this $50,000 media buy?',
+    },
+  };
+
+  const response = handler(mockContext);
+
+  if (response.defer) {
+    return {
+      success: false,
+      status: 'deferred',
+      deferred: {
+        token: response.token,
+        question: mockContext.inputRequest.question,
+        resume: async (input: any) => {
+          console.log(`   Resumed with input: ${input}`);
+          return {
+            success: true,
+            status: 'completed',
+            data: { approved: input === 'APPROVED' },
+          };
+        },
+      },
+    };
+  }
+
+  throw new Error('Demo simulation - handler did not defer');
+}
+
+async function simulateSubmittedTask(): Promise<TaskResult<any>> {
+  return {
+    success: false,
+    status: 'submitted',
+    submitted: {
+      taskId: `task-${Date.now()}`,
+      webhookUrl: 'https://yourapp.com/webhooks/adcp/xyz123',
+      track: async () => ({
+        taskId: `task-${Date.now()}`,
+        status: 'working',
+        taskType: 'create_media_buy',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      }),
+      waitForCompletion: async (pollInterval = 60000) => {
+        console.log(`   Polling every ${pollInterval}ms...`);
+        return {
+          success: true,
+          status: 'completed',
+          data: { mediaBuyId: 'mb-12345' },
+        };
+      },
+    },
+  };
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}