@adcp/client 4.21.0 → 4.22.0

package/examples/conversation-client.ts

@@ -0,0 +1,291 @@
+#!/usr/bin/env tsx
+// Example: Using the new conversation-aware ADCP client library
+
+import {
+  ADCPMultiAgentClient,
+  AgentClient,
+  createFieldHandler,
+  createConditionalHandler,
+  autoApproveHandler,
+  deferAllHandler,
+  type AgentConfig,
+  type InputHandler,
+  type ConversationContext,
+} from '@adcp/client';
+
+// Example agent configurations
+const agents: AgentConfig[] = [
+  {
+    id: 'premium-agent',
+    name: 'Premium Ad Agent',
+    agent_uri: 'https://premium-agent.example.com/mcp/',
+    protocol: 'mcp',
+    auth_token: process.env.PREMIUM_AGENT_TOKEN,
+  },
+  {
+    id: 'budget-agent',
+    name: 'Budget Ad Agent',
+    agent_uri: 'https://budget-agent.example.com/a2a/',
+    protocol: 'a2a',
+  },
+];
+
+/**
+ * Example 1: Single agent with conversation context
+ */
+async function singleAgentExample() {
+  console.log('\n=== Single Agent Example ===');
+
+  const client = new ADCPMultiAgentClient(agents);
+  const agent = client.agent('premium-agent');
+
+  // Create a smart input handler that can handle different fields
+  const smartHandler: InputHandler = createFieldHandler(
+    {
+      budget: 50000,
+      targeting: ['US', 'CA', 'UK'],
+      approval: (context: ConversationContext) => {
+        // Auto-approve on first attempt, defer on subsequent attempts
+        return context.attempt === 1 ? true : context.deferToHuman();
+      },
+    },
+    deferAllHandler
+  ); // Default to defer for unmapped fields
+
+  try {
+    // Initial request
+    console.log('🔍 Getting products...');
+    const products = await agent.getProducts(
+      {
+        brief: 'Premium coffee brands for millennials',
+        promoted_offering: 'Artisan coffee blends',
+      },
+      smartHandler
+    );
+
+    if (products.success) {
+      console.log(`✅ Found ${products.data.products?.length || 0} products`);
+      console.log(`⏱️  Response time: ${products.metadata.responseTimeMs}ms`);
+      console.log(`🔄 Clarification rounds: ${products.metadata.clarificationRounds}`);
+
+      // Continue the conversation
+      console.log('\n💬 Continuing conversation...');
+      const refined = await agent.continueConversation(
+        'Focus only on premium organic brands with sustainability certifications',
+        smartHandler
+      );
+
+      if (refined.success) {
+        console.log(`✅ Refined search returned ${refined.data.products?.length || 0} products`);
+      }
+    } else {
+      console.error(`❌ Error: ${products.error}`);
+    }
+  } catch (error) {
+    console.error('❌ Failed:', error.message);
+  }
+}
+
+/**
+ * Example 2: Multi-agent parallel execution
+ */
+async function multiAgentExample() {
+  console.log('\n=== Multi-Agent Example ===');
+
+  const client = new ADCPMultiAgentClient(agents);
+
+  // Simple auto-approve handler for bulk operations
+  const autoHandler: InputHandler = context => {
+    console.log(`🤖 Auto-responding to ${context.agent.name}: ${context.inputRequest.question}`);
+
+    // Use suggestions if available, otherwise use sensible defaults
+    if (context.inputRequest.suggestions?.length) {
+      return context.inputRequest.suggestions[0];
+    }
+
+    // Field-specific defaults
+    switch (context.inputRequest.field) {
+      case 'budget':
+        return 25000;
+      case 'targeting':
+        return ['US'];
+      case 'approval':
+        return true;
+      default:
+        return true;
+    }
+  };
+
+  try {
+    console.log('🚀 Querying all agents in parallel...');
+    const results = await client.allAgents().getProducts(
+      {
+        brief: 'Tech gadgets for remote work',
+        promoted_offering: 'Productivity tools and accessories',
+      },
+      autoHandler
+    );
+
+    console.log(`📊 Got ${results.length} responses:`);
+    results.forEach(result => {
+      if (result.success) {
+        console.log(
+          `  ✅ ${result.metadata.agent.name}: ${result.data.products?.length || 0} products (${
+            result.metadata.responseTimeMs
+          }ms)`
+        );
+      } else {
+        console.log(`  ❌ ${result.metadata.agent.name}: ${result.error}`);
+      }
+    });
+
+    // Find the best result
+    const successful = results.filter(r => r.success);
+    if (successful.length > 0) {
+      const best = successful.sort((a, b) => (b.data.products?.length || 0) - (a.data.products?.length || 0))[0];
+      console.log(`🏆 Best result: ${best.metadata.agent.name} with ${best.data.products?.length || 0} products`);
+    }
+  } catch (error) {
+    console.error('❌ Multi-agent query failed:', error.message);
+  }
+}
+
+/**
+ * Example 3: Advanced input handling patterns
+ */
+async function advancedHandlersExample() {
+  console.log('\n=== Advanced Input Handlers Example ===');
+
+  const client = new ADCPMultiAgentClient(agents);
+  const agent = client.agent('premium-agent');
+
+  // Conditional handler based on agent type and context
+  const conditionalHandler = createConditionalHandler(
+    [
+      {
+        condition: ctx => ctx.agent.name.includes('Premium'),
+        handler: createFieldHandler({
+          budget: 100000, // Higher budget for premium agents
+          targeting: ['US', 'CA', 'UK', 'AU'],
+          approval: true,
+        }),
+      },
+      {
+        condition: ctx => ctx.attempt > 2,
+        handler: deferAllHandler, // Defer if too many clarifications
+      },
+    ],
+    autoApproveHandler
+  );
+
+  try {
+    console.log('🎯 Testing advanced input handling...');
+    const result = await agent.listCreativeFormats(
+      {
+        type: 'video',
+      },
+      conditionalHandler
+    );
+
+    if (result.success) {
+      console.log(`✅ Got ${result.data.formats?.length || 0} video formats`);
+      console.log(`🔄 Clarifications: ${result.metadata.clarificationRounds}`);
+    } else {
+      console.log(`❌ Error: ${result.error}`);
+    }
+  } catch (error) {
+    console.error('❌ Advanced handler failed:', error.message);
+  }
+}
+
+/**
+ * Example 4: Conversation history and context management
+ */
+async function conversationHistoryExample() {
+  console.log('\n=== Conversation History Example ===');
+
+  const client = new ADCPMultiAgentClient(agents);
+  const agent = client.agent('budget-agent');
+
+  // Handler that uses conversation history
+  const historyAwareHandler: InputHandler = context => {
+    console.log(`📜 Conversation has ${context.messages.length} messages`);
+
+    // Check if budget was previously discussed
+    if (context.wasFieldDiscussed('budget')) {
+      const previousBudget = context.getPreviousResponse('budget');
+      console.log(`💰 Previously discussed budget: ${previousBudget}`);
+      return previousBudget;
+    }
+
+    return context.inputRequest.field === 'budget' ? 15000 : true;
+  };
+
+  try {
+    console.log('📖 Starting conversation with history tracking...');
+
+    // First request
+    await agent.getProducts(
+      {
+        brief: 'Affordable marketing tools',
+      },
+      historyAwareHandler
+    );
+
+    console.log('📝 Conversation history:');
+    const history = agent.getHistory();
+    history?.forEach((msg, i) => {
+      console.log(`  ${i + 1}. ${msg.role}: ${JSON.stringify(msg.content).slice(0, 100)}...`);
+    });
+
+    // Second request in same conversation
+    await agent.listCreativeFormats(
+      {
+        type: 'display',
+      },
+      historyAwareHandler
+    );
+
+    console.log(`📊 Total messages in conversation: ${agent.getHistory()?.length || 0}`);
+  } catch (error) {
+    console.error('❌ History example failed:', error.message);
+  }
+}
+
+/**
+ * Main example runner
+ */
+async function main() {
+  console.log('🎯 ADCP Conversation-Aware Client Library Examples');
+  console.log('================================================');
+
+  // Note: These examples will fail with real network calls since we're using example URLs
+  // In a real scenario, you'd have actual agent endpoints
+
+  try {
+    await singleAgentExample();
+    await multiAgentExample();
+    await advancedHandlersExample();
+    await conversationHistoryExample();
+  } catch (error) {
+    console.log('\n💡 Note: Examples use mock URLs and will fail with real network calls');
+    console.log('   In production, configure with real agent endpoints');
+    console.log(`   Error: ${error.message}`);
+  }
+
+  console.log('\n✨ Examples completed! Check the source code for implementation details.');
+  console.log('\n📚 Key Features Demonstrated:');
+  console.log('   • Conversation-aware single agent operations');
+  console.log('   • Parallel multi-agent execution');
+  console.log('   • Smart input handlers with field mapping');
+  console.log('   • Conditional logic and retry patterns');
+  console.log('   • Conversation history and context preservation');
+  console.log('   • Type-safe task execution with full IntelliSense');
+}
+
+// Run examples if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { singleAgentExample, multiAgentExample, advancedHandlersExample, conversationHistoryExample };

package/examples/debug-preview-response.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+
+/**
+ * Debug: Inspect actual preview_creative response
+ */
+
+import { AdCPClient } from '../src/lib/core/AdCPClient';
+
+const CREATIVE_AGENT_URL = process.env.CREATIVE_AGENT_URL || 'https://creative.adcontextprotocol.org/mcp';
+const CREATIVE_AGENT_PROTOCOL = (process.env.CREATIVE_AGENT_PROTOCOL || 'mcp') as 'mcp' | 'a2a';
+
+async function main() {
+  console.log('🐛 Debugging Preview Creative Response\n');
+
+  const creativeAgent = new AdCPClient({
+    id: 'creative_agent',
+    name: 'Creative Agent',
+    agent_uri: CREATIVE_AGENT_URL,
+    protocol: CREATIVE_AGENT_PROTOCOL,
+  });
+
+  // Simple preview_creative request
+  // Note: Using type assertion to bypass strict TypeScript validation
+  // The actual creative agent expects plain strings for text assets
+  const response = await creativeAgent.previewCreative({
+    format_id: {
+      agent_url: 'https://creative.adcontextprotocol.org/',
+      id: 'product_card_standard',
+    },
+    creative_manifest: {
+      format_id: {
+        agent_url: 'https://creative.adcontextprotocol.org/',
+        id: 'product_card_standard',
+      },
+      assets: {
+        product_image: {
+          url: 'https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=400&h=300',
+        },
+        product_name: {
+          content: 'Premium Display Package',
+        },
+        product_description: {
+          content: 'High-visibility display advertising with guaranteed impressions and premium placements',
+        },
+        pricing_model: {
+          content: 'CPM',
+        },
+        pricing_amount: {
+          content: '5,000',
+        },
+        pricing_currency: {
+          content: 'USD',
+        },
+        delivery_type: {
+          content: 'Guaranteed',
+        },
+        primary_asset_type: {
+          content: 'Display Banners',
+        },
+      },
+    },
+  } as any);
+
+  console.log('Response success:', response.success);
+  console.log('Response error:', response.error);
+  console.log('\nFull response data:');
+  console.log(JSON.stringify(response.data, null, 2));
+}
+
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/examples/debug-preview-with-logging.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env tsx
+
+/**
+ * Debug with detailed logging
+ */
+
+import { AdCPClient } from '../src/lib/core/AdCPClient';
+import { batchPreviewProducts } from '../src/lib/utils/preview-utils';
+import type { Product } from '../src/lib/types/tools.generated';
+
+const CREATIVE_AGENT_URL = process.env.CREATIVE_AGENT_URL || 'https://creative.adcontextprotocol.org/mcp';
+
+async function main() {
+  const creativeAgent = new AdCPClient({
+    id: 'creative_agent',
+    name: 'Creative Agent',
+    agent_uri: CREATIVE_AGENT_URL,
+    protocol: 'mcp',
+  });
+
+  const testProduct: Product = {
+    product_id: 'test1',
+    name: 'Test Product',
+    product_card: {
+      format_id: {
+        agent_url: 'https://creative.adcontextprotocol.org/',
+        id: 'product_card_standard',
+      },
+      manifest: {
+        product_image: {
+          url: 'https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=400&h=300',
+        },
+        product_name: {
+          content: 'Test Product',
+        },
+        product_description: {
+          content: 'A test product for debugging',
+        },
+      } as any,
+    },
+  };
+
+  console.log('📦 Calling batchPreviewProducts...\n');
+  const results = await batchPreviewProducts([testProduct], creativeAgent);
+
+  console.log('\n📊 Results:');
+  console.log(JSON.stringify(results, null, 2));
+}
+
+main().catch(console.error);

package/examples/easy-config-demo.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env tsx
+// Easy Configuration Demo - Show how simple it is to configure ADCP agents
+
+import { ADCPMultiAgentClient, ConfigurationManager, createFieldHandler } from '../src/lib';
+
+/**
+ * Demo 1: Environment Variable Configuration
+ */
+async function envConfigDemo() {
+  console.log('🌍 Environment Variable Configuration Demo');
+  console.log('==========================================\n');
+
+  // In real usage, you'd set this in your shell or .env file:
+  // export SALES_AGENTS_CONFIG='{"agents":[{"id":"demo","name":"Demo Agent","agent_uri":"https://demo.example.com","protocol":"mcp"}]}'
+
+  // For demo purposes, set it programmatically
+  process.env.SALES_AGENTS_CONFIG = JSON.stringify({
+    agents: [
+      {
+        id: 'demo-env-agent',
+        name: 'Demo Environment Agent',
+        agent_uri: 'https://demo-env.example.com',
+        protocol: 'mcp',
+      },
+    ],
+  });
+
+  try {
+    // Super simple - just one line!
+    console.log('🚀 Creating client from environment...');
+    const client = ADCPMultiAgentClient.fromEnv();
+
+    console.log(`✅ Success! Loaded ${client.agentCount} agent(s)`);
+    console.log(`   Available agents: ${client.getAgentIds().join(', ')}`);
+
+    // Use the agent
+    const agent = client.agent('demo-env-agent');
+    console.log(`   Agent name: ${agent.getAgentName()}`);
+    console.log(`   Protocol: ${agent.getProtocol()}\n`);
+  } catch (error) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Demo 2: One-Liner Simple Setup
+ */
+async function simpleConfigDemo() {
+  console.log('⚡ One-Liner Simple Configuration Demo');
+  console.log('====================================\n');
+
+  try {
+    // Simplest possible setup
+    console.log('🚀 Creating client with one-liner...');
+    const client = ADCPMultiAgentClient.simple('https://simple-agent.example.com');
+
+    console.log(`✅ Success! Created client with default agent`);
+    console.log(`   Agent ID: ${client.getAgentIds()[0]}`);
+    console.log(`   Agent count: ${client.agentCount}`);
+
+    // Access the default agent
+    const agent = client.agent('default-agent');
+    console.log(`   Agent name: ${agent.getAgentName()}`);
+    console.log(`   Protocol: ${agent.getProtocol()} (default)\n`);
+  } catch (error) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Demo 3: Simple Setup with Options
+ */
+async function simpleWithOptionsDemo() {
+  console.log('🔧 Simple Setup with Custom Options');
+  console.log('=================================\n');
+
+  try {
+    console.log('🚀 Creating client with custom options...');
+    const client = ADCPMultiAgentClient.simple('https://custom-agent.example.com', {
+      agentId: 'my-custom-agent',
+      agentName: 'My Custom Agent',
+      protocol: 'a2a',
+      requiresAuth: true,
+      authTokenEnv: 'MY_AGENT_TOKEN',
+      debug: true,
+      timeout: 45000,
+    });
+
+    console.log(`✅ Success! Created customized client`);
+    console.log(`   Agent ID: ${client.getAgentIds()[0]}`);
+
+    const agent = client.agent('my-custom-agent');
+    console.log(`   Agent name: ${agent.getAgentName()}`);
+    console.log(`   Protocol: ${agent.getProtocol()}`);
+    console.log(`   Requires auth: true`);
+    console.log(`   Debug enabled: true\n`);
+  } catch (error) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Demo 4: Configuration Help
+ */
+async function configHelpDemo() {
+  console.log('📚 Configuration Help Demo');
+  console.log('=========================\n');
+
+  console.log('💡 Configuration options available:');
+  console.log('   Environment variables:', ConfigurationManager.getEnvVars().join(', '));
+  console.log(
+    '   Config files:',
+    ConfigurationManager.getConfigPaths()
+      .map(p => p.split('/').pop())
+      .join(', ')
+  );
+
+  console.log('\n📖 Full configuration help:');
+  console.log(ConfigurationManager.getConfigurationHelp());
+}
+
+/**
+ * Demo 5: Configuration Validation
+ */
+async function validationDemo() {
+  console.log('🛡️  Configuration Validation Demo');
+  console.log('================================\n');
+
+  // Test invalid configuration
+  try {
+    console.log('🧪 Testing invalid agent configuration...');
+    const client = ADCPMultiAgentClient.simple('not-a-valid-url');
+  } catch (error) {
+    console.log(`✅ Validation caught error: ${error.message}\n`);
+  }
+
+  // Test duplicate agent IDs
+  try {
+    console.log('🧪 Testing duplicate agent IDs...');
+    const client = new ADCPMultiAgentClient([
+      { id: 'agent1', name: 'Agent 1', agent_uri: 'https://agent1.example.com', protocol: 'mcp' },
+      { id: 'agent1', name: 'Agent 1 Duplicate', agent_uri: 'https://agent1-dup.example.com', protocol: 'mcp' },
+    ]);
+  } catch (error) {
+    console.log(`✅ Validation caught duplicate ID: ${error.message}\n`);
+  }
+
+  // Test missing required fields
+  try {
+    console.log('🧪 Testing missing required fields...');
+    const client = new ADCPMultiAgentClient([{ id: 'incomplete', name: 'Incomplete Agent' } as any]);
+  } catch (error) {
+    console.log(`✅ Validation caught missing field: ${error.message}\n`);
+  }
+}
+
+/**
+ * Demo 6: Real-World Usage Pattern
+ */
+async function realWorldDemo() {
+  console.log('🌟 Real-World Usage Pattern Demo');
+  console.log('===============================\n');
+
+  // This is how you'd typically use it in production
+  try {
+    console.log('🏭 Production-style setup...');
+
+    // Option 1: Environment-based (recommended for production)
+    let client;
+    try {
+      client = ADCPMultiAgentClient.fromConfig(); // Auto-discovers env or config file
+      console.log('✅ Loaded configuration automatically');
+    } catch (error) {
+      // Fallback to simple setup for development
+      console.log('⚠️  No configuration found, using development fallback');
+      client = ADCPMultiAgentClient.simple(process.env.ADCP_AGENT_URL || 'https://dev-agent.example.com', {
+        agentName: 'Development Agent',
+        debug: true,
+      });
+    }
+
+    console.log(`📊 Client stats:`);
+    console.log(`   Agent count: ${client.agentCount}`);
+    console.log(`   Agent IDs: ${client.getAgentIds().join(', ')}`);
+
+    // Create a smart handler for production use
+    const handler = createFieldHandler({
+      budget: parseInt(process.env.DEFAULT_BUDGET || '25000'),
+      targeting: (process.env.DEFAULT_TARGETING || 'US,CA').split(','),
+      approval: process.env.AUTO_APPROVE === 'true',
+    });
+
+    console.log(`🎯 Created production-ready handler with defaults`);
+
+    // Use the first available agent
+    const agentId = client.getAgentIds()[0];
+    const agent = client.agent(agentId);
+
+    console.log(`🚀 Ready to use agent: ${agent.getAgentName()}`);
+    console.log(`   Protocol: ${agent.getProtocol()}`);
+
+    // In real usage, you'd make actual calls here:
+    // const products = await agent.getProducts({ brief: 'Coffee brands' }, handler);
+  } catch (error) {
+    console.log(`❌ Setup failed: ${error.message}`);
+  }
+
+  console.log('\n🎉 Production setup complete!\n');
+}
+
+/**
+ * Main demo runner
+ */
+async function main() {
+  console.log('🎯 ADCP Easy Configuration Demo');
+  console.log('===============================\n');
+
+  console.log('This demo shows how easy it is to configure ADCP agents using the new configuration methods.\n');
+
+  await envConfigDemo();
+  await simpleConfigDemo();
+  await simpleWithOptionsDemo();
+  await configHelpDemo();
+  await validationDemo();
+  await realWorldDemo();
+
+  console.log('🎓 Key Takeaways:');
+  console.log('   • ADCPMultiAgentClient.fromConfig() - Auto-discovers configuration');
+  console.log('   • ADCPMultiAgentClient.fromEnv() - Loads from environment variables');
+  console.log('   • ADCPMultiAgentClient.simple(url) - One-liner setup');
+  console.log('   • Automatic validation prevents configuration errors');
+  console.log('   • Multiple configuration sources (env, files, programmatic)');
+  console.log('   • Production-ready with fallback strategies');
+  console.log('\n📚 See the README for more configuration examples!');
+}
+
+// Run demo if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { envConfigDemo, simpleConfigDemo, simpleWithOptionsDemo, configHelpDemo, validationDemo, realWorldDemo };