@adcp/client 4.21.0 → 4.22.0

package/examples/README.md

@@ -0,0 +1,106 @@
+# AdCP Client Examples
+
+This directory contains practical examples of how to use the `@adcp/client` library.
+
+## Examples
+
+### Basic Usage
+
+- **`basic-mcp.ts`** - Simple MCP protocol client usage
+- **`basic-a2a.ts`** - Simple A2A protocol client usage with multi-agent testing
+- **`env-config.ts`** - Loading agent configuration from environment variables
+- **`conversation-client.ts`** - Conversation-aware client with input handlers
+
+### Running Examples
+
+```bash
+# Install dependencies
+npm install
+
+# Set up environment variables
+export A2A_AUTH_TOKEN=your-token
+export MCP_AUTH_TOKEN=your-token
+
+# Run TypeScript examples directly
+npx tsx examples/basic-mcp.ts
+npx tsx examples/basic-a2a.ts
+npx tsx examples/env-config.ts
+npx tsx examples/conversation-client.ts
+```
+
+## Environment Configuration
+
+The library supports loading agent configurations from environment variables. Set `ADCP_AGENTS_CONFIG` (or `SALES_AGENTS_CONFIG`):
+
+```bash
+ADCP_AGENTS_CONFIG='[{"id":"test-agent","name":"Test Agent","agent_uri":"https://test-agent.example.com","protocol":"mcp","auth_token":"your-token"}]'
+```
+
+## Library Usage Patterns
+
+### 1. Multi-Agent Client
+
+```typescript
+import { ADCPMultiAgentClient, type AgentConfig } from '@adcp/client';
+
+const agents: AgentConfig[] = [/* your agents */];
+const client = new ADCPMultiAgentClient(agents);
+
+// Single agent operation
+const agent = client.agent('agent-id');
+const result = await agent.getProducts({ brief: '...' });
+
+// Multi-agent parallel operation
+const results = await client.agents(['id1', 'id2']).getProducts({ brief: '...' });
+```
+
+### 2. Environment-based Configuration
+
+```typescript
+import { ADCPMultiAgentClient } from '@adcp/client';
+
+// Auto-discover from env vars and config files
+const client = ADCPMultiAgentClient.fromConfig();
+
+// Or from environment only
+const client = ADCPMultiAgentClient.fromEnv();
+```
+
+## Available Tools
+
+AdCP tools available on `AgentClient`:
+
+- `getProducts()` - Discover advertising products
+- `listCreativeFormats()` - Get supported creative formats
+- `createMediaBuy()` - Create a media buy
+- `updateMediaBuy()` - Update a media buy
+- `syncCreatives()` - Sync creative assets
+- `listCreatives()` - List creative assets
+- `getMediaBuyDelivery()` - Get delivery performance
+- `getSignals()` - Get audience signals
+- `activateSignal()` - Activate audience signals
+- `providePerformanceFeedback()` - Send performance feedback
+- `getAdcpCapabilities()` - Get agent capabilities (v3)
+
+## Error Handling
+
+```typescript
+const result = await agent.getProducts({ brief: 'test' });
+
+if (result.success && result.status === 'completed') {
+  console.log('Data:', result.data);
+} else {
+  console.log('Error:', result.error);
+}
+```
+
+## Testing Framework
+
+This package also includes a complete testing framework. To run the testing UI:
+
+```bash
+npm run dev
+# Open http://localhost:8080
+```
+
+See the main README for full testing framework documentation.

package/examples/adcp.config.json

@@ -0,0 +1,30 @@
+{
+  "agents": [
+    {
+      "id": "premium-network",
+      "name": "Premium Ad Network",
+      "agent_uri": "https://premium-ads.example.com/mcp/",
+      "protocol": "mcp",
+      "auth_token": "your-premium-token-here"
+    },
+    {
+      "id": "budget-network",
+      "name": "Budget Ad Network",
+      "agent_uri": "https://budget-ads.example.com/a2a/",
+      "protocol": "a2a"
+    },
+    {
+      "id": "social-network",
+      "name": "Social Media Ad Network",
+      "agent_uri": "https://social-ads.example.com/mcp/",
+      "protocol": "mcp",
+      "auth_token": "your-social-token-here"
+    }
+  ],
+  "defaults": {
+    "protocol": "mcp",
+    "timeout": 30000,
+    "maxClarifications": 3,
+    "debug": false
+  }
+}

package/examples/basic-a2a.ts

@@ -0,0 +1,76 @@
+// Basic A2A Client Example
+import { AdCPClient, type AgentConfig } from '@adcp/client';
+
+// Using AdCPClient with A2A protocol (recommended)
+async function configuredA2AExample() {
+  const agent: AgentConfig = {
+    id: 'test-a2a-agent',
+    name: 'Test A2A Agent',
+    agent_uri: 'https://test-agent.adcontextprotocol.org',
+    protocol: 'a2a',
+    auth_token: process.env.A2A_AUTH_TOKEN,
+  };
+
+  const client = new AdCPClient([agent]);
+
+  try {
+    const agentClient = client.agent('test-a2a-agent');
+    const result = await agentClient.getProducts({
+      brief: 'Sustainable fashion brands',
+      promoted_offering: 'Eco-friendly clothing',
+    });
+
+    console.log('Test Result:', result);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Multi-agent testing
+async function multiAgentExample() {
+  const agents: AgentConfig[] = [
+    {
+      id: 'mcp-agent',
+      name: 'MCP Test Agent',
+      agent_uri: 'https://test-agent.adcontextprotocol.org/mcp/',
+      protocol: 'mcp',
+      auth_token: process.env.MCP_AUTH_TOKEN,
+    },
+    {
+      id: 'a2a-agent',
+      name: 'A2A Test Agent',
+      agent_uri: 'https://test-agent.adcontextprotocol.org',
+      protocol: 'a2a',
+      auth_token: process.env.A2A_AUTH_TOKEN,
+    },
+  ];
+
+  const client = new AdCPClient(agents);
+
+  try {
+    const agentCollection = client.agents(['mcp-agent', 'a2a-agent']);
+    const results = await agentCollection.getProducts({
+      brief: 'Tech gadgets for remote work',
+      promoted_offering: 'Ergonomic workspace solutions',
+    });
+
+    console.log('Results from both agents:', results);
+    results.forEach(result => {
+      if (result.status === 'completed') {
+        console.log(`${result.metadata.agent.name}: Success`);
+        console.log('  Data:', result.data);
+      } else {
+        console.log(`${result.metadata.agent.name}: Failed`);
+        console.log('  Error:', result.error);
+      }
+    });
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Run examples
+if (require.main === module) {
+  configuredA2AExample();
+  multiAgentExample();
+}

package/examples/basic-mcp.ts

@@ -0,0 +1,50 @@
+// Basic MCP Client Example
+import { createMCPClient, type AgentConfig } from '@adcp/client';
+
+async function basicMCPExample() {
+  // Simple MCP client usage
+  const client = createMCPClient('https://test-agent.adcontextprotocol.org/mcp/', 'your-auth-token');
+
+  try {
+    const result = await client.callTool('get_products', {
+      brief: 'Looking for premium coffee brands',
+      promoted_offering: 'Artisan coffee blends',
+    });
+
+    console.log('Products:', result);
+  } catch (error) {
+    console.error('Error calling MCP agent:', error);
+  }
+}
+
+// Using AgentConfig with AdCPClient
+import { AdCPClient } from '@adcp/client';
+
+async function configuredMCPExample() {
+  const agent: AgentConfig = {
+    id: 'test-mcp-agent',
+    name: 'Test MCP Agent',
+    agent_uri: 'https://test-agent.adcontextprotocol.org/mcp/',
+    protocol: 'mcp',
+    auth_token: process.env.MCP_AUTH_TOKEN,
+  };
+
+  const client = new AdCPClient([agent]);
+
+  try {
+    const agentClient = client.agent('test-mcp-agent');
+    const result = await agentClient.getProducts({
+      brief: 'Sustainable fashion brands',
+    });
+
+    console.log('Test Result:', result);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Run examples
+if (require.main === module) {
+  basicMCPExample();
+  configuredMCPExample();
+}

package/examples/batch-preview-test.ts

@@ -0,0 +1,266 @@
+#!/usr/bin/env tsx
+
+/**
+ * Test batch preview functionality with creative agent
+ *
+ * This example demonstrates:
+ * 1. Creating mock products/formats with product_card/format_card manifests
+ * 2. Using batchPreviewProducts/batchPreviewFormats to render cards
+ * 3. Caching behavior
+ */
+
+import { AdCPClient } from '../src/lib/core/AdCPClient';
+import { batchPreviewProducts, batchPreviewFormats, clearPreviewCache } from '../src/lib/utils/preview-utils';
+import type { Product, Format } from '../src/lib/types/tools.generated';
+
+// Configuration
+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('🧪 Testing Batch Preview Functionality\n');
+
+  // Create AdCPClient for creative agent
+  const creativeAgent = new AdCPClient({
+    id: 'creative_agent',
+    name: 'Creative Agent',
+    agent_uri: CREATIVE_AGENT_URL,
+    protocol: CREATIVE_AGENT_PROTOCOL,
+  });
+
+  console.log(`📡 Connected to creative agent: ${CREATIVE_AGENT_URL}`);
+  console.log(`🔌 Using protocol: ${CREATIVE_AGENT_PROTOCOL}\n`);
+
+  // Test 1: Batch preview products with product_card
+  console.log('═══════════════════════════════════════════════════════════');
+  console.log('Test 1: Batch Preview Products');
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  const testProducts: Product[] = [
+    {
+      product_id: 'test_product_1',
+      name: 'Premium Display Package',
+      description: 'High-visibility display advertising',
+      product_card: {
+        format_id: {
+          agent_url: CREATIVE_AGENT_URL.replace('/mcp', ''),
+          id: 'product_card_standard',
+        },
+        manifest: {
+          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 across our network.',
+          },
+          pricing_model: {
+            content: 'CPM',
+          },
+          pricing_amount: {
+            content: '$5,000/month',
+          },
+          pricing_currency: {
+            content: 'USD',
+          },
+          delivery_type: {
+            content: 'Guaranteed',
+          },
+          primary_asset_type: {
+            content: 'Display',
+          },
+        } as any,
+      },
+    },
+    {
+      product_id: 'test_product_2',
+      name: 'Video Advertising',
+      description: 'Engaging video ad placements',
+      product_card: {
+        format_id: {
+          agent_url: CREATIVE_AGENT_URL.replace('/mcp', ''),
+          id: 'product_card_standard',
+        },
+        manifest: {
+          product_image: {
+            url: 'https://images.unsplash.com/photo-1536240478700-b869070f9279?w=400&h=300',
+          },
+          product_name: {
+            content: 'Video Advertising',
+          },
+          product_description: {
+            content: 'Pre-roll and mid-roll video inventory with 15s and 30s spots in HD quality.',
+          },
+          pricing_model: {
+            content: 'CPCV',
+          },
+          pricing_amount: {
+            content: '$10,000/month',
+          },
+          pricing_currency: {
+            content: 'USD',
+          },
+          delivery_type: {
+            content: 'Standard',
+          },
+          primary_asset_type: {
+            content: 'Video',
+          },
+        } as any,
+      },
+    },
+    {
+      product_id: 'test_product_3',
+      name: 'Sponsored Content',
+      description: 'Native advertising opportunities',
+      // No product_card - should return without preview
+    },
+  ];
+
+  try {
+    console.log(`📦 Testing with ${testProducts.length} products...`);
+    const startTime = Date.now();
+
+    const productPreviews = await batchPreviewProducts(testProducts, creativeAgent);
+
+    const elapsed = Date.now() - startTime;
+    console.log(`✅ Batch preview completed in ${elapsed}ms\n`);
+
+    console.log('Results:');
+    productPreviews.forEach((preview, index) => {
+      const product = preview.item as Product;
+      console.log(`\n  Product ${index + 1}: ${product.name}`);
+      if (preview.previewUrl) {
+        console.log(`    ✅ Preview URL: ${preview.previewUrl}`);
+        console.log(`    📝 Preview ID: ${preview.previewId}`);
+      } else if (preview.error) {
+        console.log(`    ❌ Error: ${preview.error}`);
+      } else {
+        console.log(`    ⚠️  No product_card provided`);
+      }
+    });
+
+    // Test caching
+    console.log('\n─────────────────────────────────────────────────────────');
+    console.log('Testing cache...\n');
+
+    const cacheStartTime = Date.now();
+    const cachedPreviews = await batchPreviewProducts(testProducts, creativeAgent);
+    const cacheElapsed = Date.now() - cacheStartTime;
+
+    console.log(`✅ Cached preview completed in ${cacheElapsed}ms`);
+    console.log(`⚡ Speed improvement: ${Math.round((elapsed / cacheElapsed) * 100) / 100}x faster\n`);
+  } catch (error) {
+    console.error('❌ Product preview test failed:', error);
+  }
+
+  // Test 2: Batch preview formats with format_card
+  console.log('\n═══════════════════════════════════════════════════════════');
+  console.log('Test 2: Batch Preview Formats');
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  const format1 = {
+    format_id: {
+      agent_url: 'https://example.com',
+      id: 'display_300x250',
+    },
+    name: 'Medium Rectangle',
+    description: '300x250 display banner',
+    type: 'display' as const,
+  };
+
+  const format2 = {
+    format_id: {
+      agent_url: 'https://example.com',
+      id: 'video_1920x1080',
+    },
+    name: 'HD Video',
+    description: '1920x1080 video format',
+    type: 'video' as const,
+  };
+
+  const testFormats: Format[] = [
+    {
+      ...format1,
+      format_card: {
+        format_id: {
+          agent_url: CREATIVE_AGENT_URL.replace('/mcp', ''),
+          id: 'format_card_standard',
+        },
+        manifest: {
+          format: {
+            content: JSON.stringify(format1),
+          },
+        } as any,
+      },
+    },
+    {
+      ...format2,
+      format_card: {
+        format_id: {
+          agent_url: CREATIVE_AGENT_URL.replace('/mcp', ''),
+          id: 'format_card_standard',
+        },
+        manifest: {
+          format: {
+            content: JSON.stringify(format2),
+          },
+        } as any,
+      },
+    },
+  ];
+
+  try {
+    console.log(`📦 Testing with ${testFormats.length} formats...`);
+    const startTime = Date.now();
+
+    const formatPreviews = await batchPreviewFormats(testFormats, creativeAgent);
+
+    const elapsed = Date.now() - startTime;
+    console.log(`✅ Batch preview completed in ${elapsed}ms\n`);
+
+    console.log('Results:');
+    formatPreviews.forEach((preview, index) => {
+      const format = preview.item as Format;
+      console.log(`\n  Format ${index + 1}: ${format.name}`);
+      if (preview.previewUrl) {
+        console.log(`    ✅ Preview URL: ${preview.previewUrl}`);
+        console.log(`    📝 Preview ID: ${preview.previewId}`);
+      } else if (preview.error) {
+        console.log(`    ❌ Error: ${preview.error}`);
+      } else {
+        console.log(`    ⚠️  No format_card provided`);
+      }
+    });
+  } catch (error) {
+    console.error('❌ Format preview test failed:', error);
+  }
+
+  // Test 3: Cache clearing
+  console.log('\n═══════════════════════════════════════════════════════════');
+  console.log('Test 3: Cache Management');
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  console.log('🗑️  Clearing preview cache...');
+  clearPreviewCache();
+  console.log('✅ Cache cleared\n');
+
+  console.log('📦 Re-fetching products (should be slower now)...');
+  const noCacheStartTime = Date.now();
+  await batchPreviewProducts(testProducts.slice(0, 2), creativeAgent);
+  const noCacheElapsed = Date.now() - noCacheStartTime;
+  console.log(`✅ Completed in ${noCacheElapsed}ms (cache was cleared)\n`);
+
+  console.log('═══════════════════════════════════════════════════════════');
+  console.log('✅ All tests completed!');
+  console.log('═══════════════════════════════════════════════════════════\n');
+}
+
+// Run tests
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});