@adcp/client 4.20.0 → 4.22.0

package/examples/signals-agent.ts

@@ -0,0 +1,162 @@
+/**
+ * Example: Signals Agent (Server)
+ *
+ * Demonstrates building an AdCP signals agent that serves audience segments
+ * via the get_signals tool. Uses createTaskCapableServer for MCP task support
+ * and generated Zod schemas for type-safe input validation.
+ *
+ * Run with:
+ *
+ *   npx tsx examples/signals-agent.ts
+ *
+ * Then test with:
+ *
+ *   npx @adcp/client http://localhost:3001/mcp
+ *   npx @adcp/client http://localhost:3001/mcp get_signals '{"signal_spec":"audience segments"}'
+ *   npx @adcp/client http://localhost:3001/mcp get_signals '{"signal_spec":"shoppers"}'
+ *   npx @adcp/client http://localhost:3001/mcp get_signals '{"filters":{"catalog_types":["marketplace"]}}'
+ */
+
+import { createTaskCapableServer, taskToolResponse, serve, GetSignalsRequestSchema } from '@adcp/client';
+import type { GetSignalsResponse } from '@adcp/client';
+
+// ---------------------------------------------------------------------------
+// Audience segment catalog — typed to match the AdCP signals response schema
+// ---------------------------------------------------------------------------
+type Signal = GetSignalsResponse['signals'][number];
+
+const SEGMENTS: Signal[] = [
+  {
+    signal_agent_segment_id: 'high_intent_shoppers',
+    signal_id: {
+      source: 'catalog',
+      data_provider_domain: 'example-signals.com',
+      id: 'high_intent_shoppers',
+    },
+    name: 'High Intent Shoppers',
+    description: 'Users who visited product pages 3+ times in the last 7 days without purchasing.',
+    value_type: 'binary',
+    signal_type: 'owned',
+    data_provider: 'Example Signals Agent',
+    coverage_percentage: 12,
+    deployments: [],
+    pricing_options: [
+      {
+        pricing_option_id: 'po_high_intent_cpm',
+        model: 'cpm',
+        currency: 'USD',
+        cpm: 6,
+      },
+    ],
+  },
+  {
+    signal_agent_segment_id: 'lapsed_subscribers',
+    signal_id: {
+      source: 'catalog',
+      data_provider_domain: 'example-signals.com',
+      id: 'lapsed_subscribers',
+    },
+    name: 'Lapsed Subscribers',
+    description: 'Email subscribers who have not opened in 90+ days but previously had high engagement.',
+    value_type: 'binary',
+    signal_type: 'custom',
+    data_provider: 'Example Signals Agent',
+    coverage_percentage: 8,
+    deployments: [],
+    pricing_options: [
+      {
+        pricing_option_id: 'po_lapsed_cpm',
+        model: 'cpm',
+        currency: 'USD',
+        cpm: 3,
+      },
+    ],
+  },
+  {
+    signal_agent_segment_id: 'geo_urban_commuters',
+    signal_id: {
+      source: 'catalog',
+      data_provider_domain: 'example-signals.com',
+      id: 'geo_urban_commuters',
+    },
+    name: 'Urban Commuters',
+    description: 'Users whose location data indicates daily commute patterns through major metro areas.',
+    value_type: 'binary',
+    signal_type: 'marketplace',
+    data_provider: 'Example Signals Agent',
+    coverage_percentage: 22,
+    deployments: [],
+    pricing_options: [
+      {
+        pricing_option_id: 'po_urban_cpm',
+        model: 'cpm',
+        currency: 'USD',
+        cpm: 5,
+      },
+    ],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Query logic — filters segments by spec, IDs, and catalog type
+// ---------------------------------------------------------------------------
+function querySegments(args: {
+  signal_spec?: string | null;
+  signal_ids?: Array<{ id: string }> | null;
+  catalog_types?: string[] | null;
+  max_results?: number | null;
+}): Signal[] {
+  let results = [...SEGMENTS];
+
+  if (args.signal_ids?.length) {
+    const ids = new Set(args.signal_ids.map(s => s.id));
+    results = results.filter(s => ids.has(s.signal_agent_segment_id));
+  }
+
+  if (args.catalog_types?.length) {
+    results = results.filter(s => args.catalog_types!.includes(s.signal_type));
+  }
+
+  if (args.signal_spec) {
+    const spec = args.signal_spec.toLowerCase();
+    results = results.filter(s => s.name.toLowerCase().includes(spec) || s.description.toLowerCase().includes(spec));
+  }
+
+  if (args.max_results) {
+    results = results.slice(0, args.max_results);
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+function createSignalsAgent() {
+  const server = createTaskCapableServer('Example Signals Agent', '1.0.0', {
+    instructions: 'Signals agent providing audience segment discovery via get_signals.',
+  });
+
+  server.tool(
+    'get_signals',
+    'Discover audience segments. Supports natural language discovery via signal_spec or exact lookup via signal_ids.',
+    GetSignalsRequestSchema.shape,
+    async args => {
+      const signals = querySegments({
+        signal_spec: args.signal_spec,
+        signal_ids: args.signal_ids,
+        catalog_types: args.filters?.catalog_types,
+        max_results: args.max_results,
+      });
+
+      return taskToolResponse({ signals, sandbox: true }, `Found ${signals.length} audience segment(s)`);
+    }
+  );
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Start the server
+// ---------------------------------------------------------------------------
+serve(createSignalsAgent);

package/examples/simple-getting-started.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env tsx
+// Simple Getting Started Example - Your First ADCP Client
+// This example shows the absolute simplest way to use the ADCP client library
+
+import { ADCPMultiAgentClient, createFieldHandler, type AgentConfig } from '../src/lib';
+
+/**
+ * Example 1: Absolute Simplest Usage
+ * This shows how to make your first ADCP call with minimal setup
+ */
+async function gettingStarted() {
+  console.log('🚀 ADCP Client Library - Getting Started');
+  console.log('=====================================\n');
+
+  // Step 1: Configure your ADCP agent
+  console.log('Step 1: Setting up your ADCP agent...');
+
+  const agents: AgentConfig[] = [
+    {
+      id: 'demo-agent',
+      name: 'Demo Advertising Agent',
+      agent_uri: 'https://demo-agent.adcontextprotocol.org', // This would be your real agent URL
+      protocol: 'mcp',
+    },
+  ];
+
+  const client = new ADCPMultiAgentClient(agents);
+  console.log(`✅ Connected to ${client.agentCount} agent(s)\n`);
+
+  // Step 2: Make your first ADCP call
+  console.log('Step 2: Asking for advertising products...');
+
+  try {
+    const agent = client.agent('demo-agent');
+
+    // This is the simplest possible ADCP call
+    const result = await agent.getProducts({
+      brief: 'Coffee subscription service targeting busy professionals',
+      promoted_offering: 'Premium monthly coffee deliveries',
+    });
+
+    if (result.success) {
+      console.log(`✅ Success! Found ${result.data.products?.length || 0} advertising products`);
+      console.log(`   Response time: ${result.metadata.responseTimeMs}ms`);
+
+      // Show first few products
+      result.data.products?.slice(0, 3).forEach((product, i) => {
+        console.log(`   ${i + 1}. ${product.name} - ${product.publisher}`);
+      });
+    } else {
+      console.log(`❌ Error: ${result.error}`);
+    }
+  } catch (error) {
+    console.log(`❌ Network error: ${error.message}`);
+    console.log("\n💡 This is expected with demo URLs. In real usage, you'd use actual agent endpoints.");
+  }
+
+  console.log("\n🎉 That's it! You've made your first ADCP call.\n");
+}
+
+/**
+ * Example 2: Adding Smart Responses
+ * This shows how to handle agent clarifications automatically
+ */
+async function withSmartHandler() {
+  console.log('📚 Example 2: Adding Smart Clarification Handling');
+  console.log('===============================================\n');
+
+  const client = new ADCPMultiAgentClient([
+    {
+      id: 'fashion-agent',
+      name: 'Fashion Network Agent',
+      agent_uri: 'https://fashion-network.example.com',
+      protocol: 'mcp',
+    },
+  ]);
+
+  // Create a handler for common agent questions
+  const smartHandler = createFieldHandler({
+    budget: 25000, // Auto-answer budget questions
+    targeting: ['US', 'CA', 'UK'], // Auto-answer geographic targeting
+    approval: true, // Auto-approve when asked
+    timeframe: '30 days', // Campaign duration
+  });
+
+  console.log('✨ Created smart handler for automatic responses');
+  console.log('   - Budget questions → $25,000');
+  console.log('   - Targeting questions → US, CA, UK');
+  console.log('   - Approval questions → Yes');
+  console.log('   - Timeframe questions → 30 days\n');
+
+  try {
+    const agent = client.agent('fashion-agent');
+
+    console.log('🎯 Requesting products with smart handler...');
+    const result = await agent.getProducts(
+      {
+        brief: 'Sustainable fashion brands for environmentally conscious millennials',
+        promoted_offering: 'Eco-friendly clothing and accessories',
+      },
+      smartHandler
+    ); // <-- Handler will auto-respond to agent clarifications
+
+    if (result.success) {
+      console.log(
+        `✅ Smart handler success! ${result.metadata.clarificationRounds} clarifications handled automatically`
+      );
+      console.log(`   Found ${result.data.products?.length || 0} products`);
+    }
+  } catch (error) {
+    console.log(`❌ Expected error with demo URL: ${error.message}`);
+  }
+
+  console.log('\n💡 In production, the agent might ask clarifying questions like:');
+  console.log('   "What\'s your budget for this campaign?"');
+  console.log('   "Which geographic regions should we target?"');
+  console.log('   "Do you approve this targeting strategy?"');
+  console.log('   → Your handler automatically provides the answers!\n');
+}
+
+/**
+ * Example 3: Real-World Workflow
+ * This shows a complete campaign planning workflow
+ */
+async function campaignWorkflow() {
+  console.log('🏗️  Example 3: Complete Campaign Planning Workflow');
+  console.log('================================================\n');
+
+  const client = new ADCPMultiAgentClient([
+    {
+      id: 'travel-agent',
+      name: 'Travel Industry Agent',
+      agent_uri: 'https://travel-ads.example.com',
+      protocol: 'mcp',
+    },
+  ]);
+
+  const handler = createFieldHandler({
+    budget: 75000,
+    targeting: ['US', 'CA', 'UK', 'AU'],
+    approval: true,
+    objectives: ['brand_awareness', 'conversions'],
+  });
+
+  console.log('🎯 Planning a travel campaign...');
+
+  try {
+    const agent = client.agent('travel-agent');
+
+    // Step 1: Discover available advertising products
+    console.log('\n1️⃣  Discovering available advertising products...');
+    const products = await agent.getProducts(
+      {
+        brief: 'Luxury European vacation packages for affluent travelers',
+        promoted_offering: 'Premium guided tours and boutique accommodations',
+      },
+      handler
+    );
+
+    console.log(`   Found ${products.data?.products?.length || 0} advertising products`);
+
+    // Step 2: Check available creative formats
+    console.log('\n2️⃣  Checking creative format options...');
+    const formats = await agent.listCreativeFormats(
+      {
+        type: 'video',
+      },
+      handler
+    );
+
+    console.log(`   Found ${formats.data?.formats?.length || 0} video format options`);
+
+    // Step 3: Continue the conversation to refine
+    console.log('\n3️⃣  Refining search based on initial results...');
+    const refined = await agent.continueConversation(
+      'Focus on Mediterranean destinations, budget-friendly options under $3000 per person'
+    );
+
+    console.log(`   Refined search completed in ${refined.metadata.responseTimeMs}ms`);
+
+    // Step 4: Show conversation history
+    const history = agent.getHistory();
+    console.log(`\n📜 Conversation summary:`);
+    console.log(`   Total messages exchanged: ${history?.length || 0}`);
+    console.log(`   Clarifications handled: ${products.metadata.clarificationRounds}`);
+
+    console.log('\n✅ Campaign planning workflow completed!');
+  } catch (error) {
+    console.log(`❌ Expected error with demo URL: ${error.message}`);
+  }
+
+  console.log('\n💡 In a real scenario, you would:');
+  console.log('   → Use actual ADCP agent endpoints');
+  console.log('   → Create media buys from the discovered products');
+  console.log('   → Monitor campaign performance');
+  console.log('   → Optimize based on results\n');
+}
+
+/**
+ * Main function - run all examples
+ */
+async function main() {
+  console.log('🎯 ADCP TypeScript Client Library');
+  console.log('Simple Getting Started Examples');
+  console.log('================================\n');
+
+  await gettingStarted();
+  await withSmartHandler();
+  await campaignWorkflow();
+
+  console.log('🎓 Next Steps:');
+  console.log('   1. Get ADCP agent credentials from your advertising partner');
+  console.log('   2. Replace demo URLs with real agent endpoints');
+  console.log('   3. Customize input handlers for your specific needs');
+  console.log('   4. Explore multi-agent operations for price comparison');
+  console.log('   5. Add error handling and logging for production use');
+  console.log('\n📚 Learn more: Check the README.md for complete documentation');
+}
+
+// Run examples if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { gettingStarted, withSmartHandler, campaignWorkflow };

package/examples/simple-protocol-demo.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Simple Protocol Detection Demo
+ *
+ * Shows how easy it is to detect input requests with ADCP spec PR #77
+ */
+
+import { ProtocolResponseParser, ADCP_STATUS } from '../src/lib/index';
+
+function main() {
+  console.log('🎯 Simple ADCP Protocol Detection\n');
+
+  const parser = new ProtocolResponseParser();
+
+  // Test cases showing the simplicity
+  const testCases = [
+    {
+      name: 'ADCP Standard: input-required',
+      response: {
+        status: 'input-required',
+        message: 'What is your budget?',
+      },
+      expected: true,
+    },
+
+    {
+      name: 'ADCP Standard: completed',
+      response: {
+        status: 'completed',
+        result: { products: ['Product A'] },
+      },
+      expected: false,
+    },
+
+    {
+      name: 'Legacy fallback',
+      response: {
+        type: 'input_request',
+        question: 'Select a format',
+      },
+      expected: true,
+    },
+  ];
+
+  console.log('📊 Testing simplified detection:\n');
+
+  testCases.forEach(testCase => {
+    console.log(`🧪 ${testCase.name}`);
+    console.log(`   Response: ${JSON.stringify(testCase.response, null, 4)}`);
+
+    const needsInput = parser.isInputRequest(testCase.response);
+    const status = parser.getStatus(testCase.response);
+
+    console.log(`   ✅ Needs Input: ${needsInput} (expected: ${testCase.expected})`);
+    console.log(`   📋 ADCP Status: ${status || 'null'}`);
+
+    if (needsInput) {
+      const parsed = parser.parseInputRequest(testCase.response);
+      console.log(`   📝 Question: "${parsed.question}"`);
+    }
+    console.log('');
+  });
+
+  console.log('🎉 Key Takeaway: Just check status === "input-required"!');
+  console.log('');
+  console.log('ADCP Status Values:');
+  Object.entries(ADCP_STATUS).forEach(([key, value]) => {
+    console.log(`  • ${key}: "${value}"`);
+  });
+}
+
+if (require.main === module) {
+  main();
+}

package/examples/test-helpers-demo.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env tsx
+// Test Helpers Demo - Using Pre-configured Test Agents
+// This example shows how to use the built-in test helpers for quick testing and examples
+
+import { testAgent, testAgentA2A, testAgentClient, createTestAgent, AdCPClient } from '../src/lib';
+
+/**
+ * Example 1: Simplest Possible Usage
+ * Use the pre-configured test agent directly - no setup needed!
+ */
+async function simplestExample() {
+  console.log('🎯 Example 1: Simplest Usage with testAgent');
+  console.log('===========================================\n');
+
+  try {
+    // Just import and use - that's it!
+    const result = await testAgent.getProducts({
+      brief: 'Premium coffee subscription service',
+      promoted_offering: 'Artisan coffee deliveries',
+    });
+
+    if (result.success) {
+      console.log(`✅ Success! Found ${result.data.products?.length || 0} products`);
+      console.log(`   Response time: ${result.metadata.responseTimeMs}ms`);
+      console.log(`   Protocol: MCP\n`);
+    } else {
+      console.log(`❌ Error: ${result.error}\n`);
+    }
+  } catch (error: any) {
+    console.log(`❌ Network error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Example 2: Testing Both Protocols
+ * Use both A2A and MCP test agents to compare behavior
+ */
+async function protocolComparison() {
+  console.log('🔄 Example 2: Protocol Comparison (A2A vs MCP)');
+  console.log('==============================================\n');
+
+  const request = {
+    brief: 'Sustainable fashion brands',
+    promoted_offering: 'Eco-friendly clothing',
+  };
+
+  try {
+    console.log('Testing MCP protocol...');
+    const mcpResult = await testAgent.getProducts(request);
+    console.log(`  MCP: ${mcpResult.success ? '✅' : '❌'} ${mcpResult.metadata.responseTimeMs}ms`);
+
+    console.log('Testing A2A protocol...');
+    const a2aResult = await testAgentA2A.getProducts(request);
+    console.log(`  A2A: ${a2aResult.success ? '✅' : '❌'} ${a2aResult.metadata.responseTimeMs}ms\n`);
+  } catch (error: any) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Example 3: Multi-Agent Testing
+ * Use the testAgentClient for parallel operations
+ */
+async function multiAgentExample() {
+  console.log('🌐 Example 3: Multi-Agent Operations');
+  console.log('====================================\n');
+
+  try {
+    console.log(`Testing with ${testAgentClient.agentCount} agents in parallel...`);
+
+    // Run the same query on both agents in parallel
+    const results = await testAgentClient.allAgents().getProducts({
+      brief: 'Tech gadgets for remote work',
+      promoted_offering: 'Ergonomic workspace solutions',
+    });
+
+    console.log('\nResults:');
+    results.forEach((result, i) => {
+      console.log(`  ${i + 1}. ${result.success ? '✅' : '❌'} ${result.metadata.responseTimeMs}ms`);
+    });
+    console.log();
+  } catch (error: any) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Example 4: AI Test Orchestration
+ * Use natural language instructions to control test behavior
+ */
+async function aiTestOrchestration() {
+  console.log('🤖 Example 4: AI Test Orchestration');
+  console.log('===================================\n');
+
+  try {
+    // Test with a delay instruction
+    console.log('Testing delayed response...');
+    const delayResult = await testAgent.createMediaBuy({
+      brief: 'Test campaign',
+      promoted_offering: 'Wait 10 seconds before responding', // AI understands this!
+      products: ['prod_test_001'],
+      budget: 10000,
+    });
+
+    console.log(`  Result: ${delayResult.success ? '✅ Success' : '❌ Failed'}`);
+    console.log(`  Time: ${delayResult.metadata.responseTimeMs}ms`);
+
+    // Test with a rejection instruction
+    console.log('\nTesting rejection scenario...');
+    const rejectResult = await testAgent.createMediaBuy({
+      brief: 'Test campaign',
+      promoted_offering: 'Reject this media buy with reason: Budget exceeds inventory',
+      products: ['prod_test_001'],
+      budget: 999999,
+    });
+
+    console.log(`  Result: ${rejectResult.success ? '✅ Success' : '❌ Failed'}`);
+    if (!rejectResult.success) {
+      console.log(`  Reason: ${rejectResult.error}`);
+    }
+    console.log();
+  } catch (error: any) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Example 5: Custom Test Agent Configuration
+ * Create a custom test agent with modifications
+ */
+async function customTestAgent() {
+  console.log('⚙️  Example 5: Custom Test Agent Configuration');
+  console.log('==============================================\n');
+
+  // Create a custom config with your own ID
+  const customConfig = createTestAgent({
+    id: 'my-custom-test',
+    name: 'My Custom Test Agent',
+  });
+
+  console.log('Created custom config:');
+  console.log(`  ID: ${customConfig.id}`);
+  console.log(`  Name: ${customConfig.name}`);
+  console.log(`  Protocol: ${customConfig.protocol}`);
+  console.log(`  URI: ${customConfig.agent_uri}\n`);
+
+  // Use it with a client
+  const client = new AdCPClient([customConfig]);
+  const agent = client.agent('my-custom-test');
+
+  try {
+    const result = await agent.getProducts({
+      brief: 'Travel packages',
+      promoted_offering: 'European vacations',
+    });
+
+    console.log(`Result: ${result.success ? '✅ Success' : '❌ Failed'}`);
+    console.log();
+  } catch (error: any) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Example 6: Testing Different Operations
+ * Show various ADCP operations with test agents
+ */
+async function variousOperations() {
+  console.log('🎬 Example 6: Various ADCP Operations');
+  console.log('=====================================\n');
+
+  try {
+    // Get products
+    console.log('1. Getting products...');
+    const products = await testAgent.getProducts({
+      brief: 'Coffee brands',
+      promoted_offering: 'Premium coffee',
+    });
+    console.log(`   ${products.success ? '✅' : '❌'} Products: ${products.data.products?.length || 0}`);
+
+    // List creative formats
+    console.log('2. Listing creative formats...');
+    const formats = await testAgent.listCreativeFormats({});
+    console.log(`   ${formats.success ? '✅' : '❌'} Formats: ${formats.data.formats?.length || 0}`);
+
+    // Create a media buy
+    console.log('3. Creating media buy...');
+    const mediaBuy = await testAgent.createMediaBuy({
+      brief: 'Test campaign',
+      promoted_offering: 'Test offering',
+      products: ['prod_test_001'],
+      budget: 5000,
+    });
+    console.log(`   ${mediaBuy.success ? '✅' : '❌'} Media buy: ${mediaBuy.data.media_buy_id || 'none'}`);
+
+    console.log();
+  } catch (error: any) {
+    console.log(`❌ Error: ${error.message}\n`);
+  }
+}
+
+/**
+ * Main function - run all examples
+ */
+async function main() {
+  console.log('\n📚 ADCP Test Helpers - Demo Examples');
+  console.log('=====================================');
+  console.log('These examples show how to use pre-configured test agents\n');
+
+  await simplestExample();
+  await protocolComparison();
+  await multiAgentExample();
+  await aiTestOrchestration();
+  await customTestAgent();
+  await variousOperations();
+
+  console.log('💡 Key Takeaways:');
+  console.log('   • testAgent = Pre-configured MCP test agent (ready to use!)');
+  console.log('   • testAgentA2A = Pre-configured A2A test agent');
+  console.log('   • testAgentClient = Multi-agent client with both protocols');
+  console.log('   • createTestAgent() = Create custom test configurations');
+  console.log('   • Perfect for examples, docs, and quick testing');
+  console.log('\n⚠️  Remember: Test agents are rate-limited and for testing only!');
+  console.log('   DO NOT use in production applications.\n');
+}
+
+// Run examples if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export {
+  simplestExample,
+  protocolComparison,
+  multiAgentExample,
+  aiTestOrchestration,
+  customTestAgent,
+  variousOperations,
+};