@adcp/client 4.20.0 → 4.22.0

package/examples/env-config.ts

@@ -0,0 +1,51 @@
+// Environment Configuration Example
+import { AdCPClient } from '@adcp/client';
+
+async function envConfigExample() {
+  // Load agents from environment using factory method
+  // Set ADCP_AGENTS_CONFIG (or SALES_AGENTS_CONFIG) in your .env file like:
+  // ADCP_AGENTS_CONFIG='[{"id":"test-agent","name":"Test Agent","agent_uri":"https://test-agent.example.com","protocol":"mcp","auth_token":"your-token"}]'
+
+  const client = AdCPClient.fromEnv();
+
+  if (client.agentCount === 0) {
+    console.log('No agents configured. Set ADCP_AGENTS_CONFIG environment variable.');
+    return;
+  }
+
+  console.log(`Loaded ${client.agentCount} agents from environment:`);
+  client.getAgentConfigs().forEach(agent => {
+    console.log(`  - ${agent.name} (${agent.protocol.toUpperCase()}) at ${agent.agent_uri}`);
+  });
+
+  // Test all agents
+  try {
+    const agentCollection = client.allAgents();
+    const results = await agentCollection.getProducts({
+      brief: 'Looking for advertising inventory for Q4 campaigns',
+      promoted_offering: 'Holiday season promotions',
+    });
+
+    console.log('\nTest Results:');
+    results.forEach(result => {
+      if (result.status === 'completed') {
+        console.log(`${result.metadata.agent.name}: ✅ (${result.data?.products?.length || 0} products)`);
+      } else {
+        console.log(`${result.metadata.agent.name}: ❌ Error: ${result.error || 'Unknown error'}`);
+      }
+    });
+
+    // Summary
+    const successful = results.filter(r => r.status === 'completed').length;
+    const failed = results.length - successful;
+
+    console.log(`\nSummary: ${successful} successful, ${failed} failed`);
+  } catch (error) {
+    console.error('Error testing agents:', error);
+  }
+}
+
+// Run example
+if (require.main === module) {
+  envConfigExample();
+}

package/examples/error-compliant-server.ts

@@ -0,0 +1,237 @@
+/**
+ * Example: AdCP-Compliant MCP Server
+ *
+ * Demonstrates building a server using @adcp/client response builders
+ * for type-safe responses. Run with:
+ *
+ *   npx tsx examples/error-compliant-server.ts
+ *
+ * Then test with:
+ *
+ *   npx @adcp/client comply http://localhost:3456/mcp
+ */
+
+import {
+  createTaskCapableServer,
+  adcpError,
+  capabilitiesResponse,
+  productsResponse,
+  mediaBuyResponse,
+  deliveryResponse,
+  serve,
+  GetProductsRequestSchema,
+  CreateMediaBuyRequestSchema,
+  GetMediaBuyDeliveryRequestSchema,
+} from '@adcp/client';
+import type { Product, GetAdCPCapabilitiesResponse } from '@adcp/client';
+
+// CreateMediaBuyRequestSchema requires account/brand per spec, but a lenient
+// version lets intentionally-incomplete requests reach the handler so it can
+// return proper AdCP structured errors instead of generic MCP validation errors.
+const LenientCreateMediaBuyInput = CreateMediaBuyRequestSchema.extend({
+  account: CreateMediaBuyRequestSchema.shape.account.optional(),
+  brand: CreateMediaBuyRequestSchema.shape.brand.optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Product catalog — typed as Product[] so the compiler enforces the schema
+// ---------------------------------------------------------------------------
+const PRODUCTS: Product[] = [
+  {
+    product_id: 'prod_display_300x250',
+    name: 'Display Banner 300x250',
+    description: 'Standard IAB display banner ad unit served across premium news and lifestyle sites.',
+    publisher_properties: [{ publisher_domain: 'example-publisher.com', selection_type: 'all' }],
+    channels: ['display'],
+    format_ids: [
+      { agent_url: 'https://creatives.adcontextprotocol.org', id: 'display_static', width: 300, height: 250 },
+    ],
+    delivery_type: 'non_guaranteed',
+    pricing_options: [
+      {
+        pricing_option_id: 'po_cpm',
+        pricing_model: 'cpm',
+        fixed_price: 5.0,
+        currency: 'USD',
+        min_spend_per_package: 500,
+      },
+    ],
+  },
+  {
+    product_id: 'prod_video_pre_roll',
+    name: 'Pre-Roll Video 15s',
+    description: 'Skippable pre-roll video ads served on premium video content.',
+    publisher_properties: [{ publisher_domain: 'example-publisher.com', selection_type: 'all' }],
+    channels: ['olv'],
+    format_ids: [{ agent_url: 'https://creatives.adcontextprotocol.org', id: 'video_hosted' }],
+    delivery_type: 'non_guaranteed',
+    pricing_options: [
+      {
+        pricing_option_id: 'po_cpm',
+        pricing_model: 'cpm',
+        fixed_price: 12.0,
+        currency: 'USD',
+        min_spend_per_package: 1000,
+      },
+    ],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Rate limit state (module-scoped — persists across per-request server instances)
+// ---------------------------------------------------------------------------
+let requestCount = 0;
+const RATE_LIMIT = 50;
+const RATE_WINDOW_MS = 60_000;
+let windowStart = Date.now();
+
+function checkRateLimit() {
+  const now = Date.now();
+  if (now - windowStart > RATE_WINDOW_MS) {
+    requestCount = 0;
+    windowStart = now;
+  }
+  requestCount++;
+  if (requestCount > RATE_LIMIT) {
+    return adcpError('RATE_LIMITED', {
+      message: 'Request rate exceeded',
+      retry_after: Math.ceil((windowStart + RATE_WINDOW_MS - now) / 1000),
+      details: { limit: RATE_LIMIT, remaining: 0, window_seconds: RATE_WINDOW_MS / 1000, scope: 'global' },
+    });
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Server factory (McpServer.connect() can only be called once per instance)
+// ---------------------------------------------------------------------------
+function createAgentServer() {
+  const server = createTaskCapableServer('Example AdCP Agent', '1.0.0');
+
+  // --- get_adcp_capabilities ---
+  server.tool('get_adcp_capabilities', {}, async () => {
+    const limited = checkRateLimit();
+    if (limited) return limited;
+
+    const capabilities: GetAdCPCapabilitiesResponse = {
+      adcp: { major_versions: [3] },
+      supported_protocols: ['media_buy'],
+      media_buy: {
+        features: {
+          inline_creative_management: false,
+          property_list_filtering: false,
+          content_standards: false,
+        },
+      },
+    };
+    return capabilitiesResponse(capabilities);
+  });
+
+  // --- get_products ---
+  server.tool('get_products', GetProductsRequestSchema.shape, async () => {
+    const limited = checkRateLimit();
+    if (limited) return limited;
+
+    return productsResponse({ products: PRODUCTS });
+  });
+
+  // --- create_media_buy ---
+  server.tool(
+    'create_media_buy',
+    LenientCreateMediaBuyInput.shape,
+    async ({ buyer_ref, start_time, end_time, packages }) => {
+      const limited = checkRateLimit();
+      if (limited) return limited;
+
+      if (new Date(end_time) <= new Date(start_time)) {
+        return adcpError('INVALID_REQUEST', {
+          message: 'end_time must be after start_time',
+          field: 'end_time',
+          suggestion: 'Set end_time to a date after start_time',
+        });
+      }
+
+      if (packages) {
+        for (let i = 0; i < packages.length; i++) {
+          const pkg = packages[i]!;
+
+          if (pkg.budget < 0) {
+            return adcpError('INVALID_REQUEST', {
+              message: 'Budget must be non-negative',
+              field: `packages[${i}].budget`,
+              suggestion: 'Set budget to 0 or greater',
+            });
+          }
+
+          const product = PRODUCTS.find(p => p.product_id === pkg.product_id);
+          if (!product) {
+            return adcpError('PRODUCT_NOT_FOUND', {
+              message: `Product '${pkg.product_id}' not found`,
+              field: `packages[${i}].product_id`,
+              suggestion: 'Use get_products to discover available products',
+            });
+          }
+
+          const pricing = product.pricing_options.find(po => po.pricing_option_id === pkg.pricing_option_id);
+          if (
+            pricing &&
+            'min_spend_per_package' in pricing &&
+            pricing.min_spend_per_package != null &&
+            pkg.budget < pricing.min_spend_per_package
+          ) {
+            return adcpError('BUDGET_TOO_LOW', {
+              message: `Budget ${pkg.budget} is below minimum ${pricing.min_spend_per_package} for ${product.name}`,
+              field: `packages[${i}].budget`,
+              suggestion: `Increase budget to at least ${pricing.min_spend_per_package}`,
+              details: { minimum_budget: pricing.min_spend_per_package, currency: 'USD' },
+            });
+          }
+        }
+      }
+
+      const mediaBuyId = `mb_${Date.now()}`;
+
+      return mediaBuyResponse({
+        media_buy_id: mediaBuyId,
+        buyer_ref,
+        packages: (packages ?? []).map((pkg, i) => ({
+          package_id: `pkg_${i}_${Date.now()}`,
+          buyer_ref: pkg.buyer_ref,
+          product_id: pkg.product_id,
+          pricing_option_id: pkg.pricing_option_id,
+          budget: pkg.budget,
+        })),
+      });
+    }
+  );
+
+  // --- get_media_buy_delivery ---
+  server.tool('get_media_buy_delivery', GetMediaBuyDeliveryRequestSchema.shape, async ({ media_buy_ids }) => {
+    const limited = checkRateLimit();
+    if (limited) return limited;
+
+    const ids = media_buy_ids ?? [];
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 86400000);
+
+    return deliveryResponse({
+      reporting_period: {
+        start: yesterday.toISOString(),
+        end: now.toISOString(),
+      },
+      media_buy_deliveries: ids.map(id => ({
+        media_buy_id: id,
+        status: 'active' as const,
+        totals: { impressions: 0, spend: 0 },
+        by_package: [],
+      })),
+    });
+  });
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Start the server
+// ---------------------------------------------------------------------------
+serve(createAgentServer, { port: 3456 });

package/examples/generative-creative-demo.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env tsx
+// Demonstrates the new generative creative format support introduced in AdCP v1.7.0
+// This example shows how to use the new format_id and assets structure for both
+// static and generative creative workflows
+
+import { ADCPMultiAgentClient, type SyncCreativesRequest } from '../src/lib';
+
+async function demonstrateGenerativeCreatives() {
+  console.log('🎨 Generative Creative Format Demo');
+  console.log('===================================\n');
+
+  // Initialize client from environment config
+  const client = ADCPMultiAgentClient.fromEnv();
+
+  // Get first available agent (just for demo purposes)
+  const agentIds = client.getAgentIds();
+  if (agentIds.length === 0) {
+    throw new Error('No agents configured. Please set SALES_AGENTS_CONFIG environment variable.');
+  }
+
+  const agent = client.agent(agentIds[0]);
+  console.log(`✅ Using agent: ${agent.config.name}`);
+  console.log(`   URI: ${agent.config.agent_uri}`);
+  console.log(`   Protocol: ${agent.config.protocol}\n`);
+
+  // Example 1: Traditional static creative with new format
+  console.log('📝 Example 1: Static Creative with new format_id structure\n');
+
+  const staticCreativeRequest: SyncCreativesRequest = {
+    creatives: [
+      {
+        creative_id: `static_banner_${Date.now()}`,
+        name: 'Static Display Banner 300x250',
+        format_id: {
+          agent_url: 'https://creative.adcontextprotocol.org',
+          id: 'display_300x250',
+        },
+        assets: {
+          image: {
+            asset_type: 'image',
+            url: 'https://example.com/banner-300x250.jpg',
+            width: 300,
+            height: 250,
+            alt_text: 'Summer sale banner',
+          },
+          click_url: {
+            asset_type: 'url',
+            url: 'https://example.com/summer-sale',
+            description: 'Landing page for summer sale campaign',
+          },
+        },
+        tags: ['display', 'static', 'summer-sale'],
+      },
+    ],
+  };
+
+  console.log('Static Creative Structure:');
+  console.log(JSON.stringify(staticCreativeRequest, null, 2));
+  console.log('\n' + '-'.repeat(50) + '\n');
+
+  // Example 2: Generative creative with brand context
+  console.log('📝 Example 2: Generative Creative with brand_manifest\n');
+
+  const generativeCreativeRequest: SyncCreativesRequest = {
+    creatives: [
+      {
+        creative_id: `gen_banner_${Date.now()}`,
+        name: 'AI-Generated Display Banner',
+        format_id: {
+          agent_url: 'https://creative.adcontextprotocol.org',
+          id: 'display_300x250_generative',
+        },
+        assets: {
+          brand_context: {
+            asset_type: 'url',
+            url: 'https://example.com',
+            description: 'Brand website for context extraction',
+          },
+          generation_prompt: {
+            asset_type: 'text',
+            content: 'Create a vibrant summer sale banner highlighting 30% off outdoor furniture',
+          },
+          logo: {
+            asset_type: 'image',
+            url: 'https://example.com/logo.png',
+            width: 100,
+            height: 100,
+          },
+        },
+        inputs: [
+          {
+            name: 'Desktop View',
+            macros: {
+              DEVICE_TYPE: 'desktop',
+            },
+            context_description: 'Preview for desktop browsers at 1920x1080',
+          },
+          {
+            name: 'Mobile View',
+            macros: {
+              DEVICE_TYPE: 'mobile',
+            },
+            context_description: 'Preview for mobile devices at 375x667',
+          },
+        ],
+        tags: ['display', 'generative', 'ai', 'summer-sale'],
+      },
+    ],
+  };
+
+  console.log('Generative Creative Structure:');
+  console.log(JSON.stringify(generativeCreativeRequest, null, 2));
+  console.log('\n' + '-'.repeat(50) + '\n');
+
+  // Example 3: Approval workflow for generative creative
+  console.log('📝 Example 3: Approving a Generative Creative\n');
+
+  const approvalRequest: SyncCreativesRequest = {
+    creatives: [
+      {
+        creative_id: 'gen_banner_12345', // Existing creative ID from previous sync
+        name: 'AI-Generated Display Banner',
+        format_id: {
+          agent_url: 'https://creative.adcontextprotocol.org',
+          id: 'display_300x250_generative',
+        },
+        assets: {
+          brand_context: {
+            asset_type: 'url',
+            url: 'https://example.com',
+            description: 'Brand website for context extraction',
+          },
+          generation_prompt: {
+            asset_type: 'text',
+            content: 'Create a vibrant summer sale banner highlighting 30% off outdoor furniture',
+          },
+        },
+        approved: true, // Approve the generated preview
+      },
+    ],
+    patch: true, // Only update the approval status
+  };
+
+  console.log('Approval Request Structure:');
+  console.log(JSON.stringify(approvalRequest, null, 2));
+  console.log('\n' + '-'.repeat(50) + '\n');
+
+  // Example 4: Request regeneration with updated prompt
+  console.log('📝 Example 4: Request Regeneration\n');
+
+  const regenerationRequest: SyncCreativesRequest = {
+    creatives: [
+      {
+        creative_id: 'gen_banner_12345',
+        name: 'AI-Generated Display Banner',
+        format_id: {
+          agent_url: 'https://creative.adcontextprotocol.org',
+          id: 'display_300x250_generative',
+        },
+        assets: {
+          brand_context: {
+            asset_type: 'url',
+            url: 'https://example.com',
+            description: 'Brand website for context extraction',
+          },
+          generation_prompt: {
+            asset_type: 'text',
+            content:
+              'Create a warm, inviting summer sale banner with emphasis on comfort and quality. Show 30% off outdoor furniture with natural colors.',
+          },
+        },
+        approved: false, // Request regeneration with updated prompt
+      },
+    ],
+    patch: true,
+  };
+
+  console.log('Regeneration Request Structure:');
+  console.log(JSON.stringify(regenerationRequest, null, 2));
+  console.log('\n' + '-'.repeat(50) + '\n');
+
+  console.log('🎉 Demo complete!');
+  console.log('\n📚 Key Changes in AdCP v1.7.0:');
+  console.log('   ✓ format_id is now an object with agent_url and id');
+  console.log('   ✓ assets is now a flexible object keyed by asset_role');
+  console.log('   ✓ New asset types: url and brand_manifest');
+  console.log('   ✓ inputs array for defining preview contexts');
+  console.log('   ✓ approved field for generative creative workflows');
+  console.log('   ✓ context_description for AI-generated content guidance');
+}
+
+// Run the demo
+if (require.main === module) {
+  demonstrateGenerativeCreatives()
+    .then(() => {
+      console.log('\n✨ Done!');
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('Fatal error:', error);
+      process.exit(1);
+    });
+}
+
+export { demonstrateGenerativeCreatives };

package/examples/inspect-card-formats.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env tsx
+
+/**
+ * Inspect card format definitions from creative agent
+ *
+ * This will help us understand:
+ * 1. What format IDs are available for cards (product_card, format_card)
+ * 2. What assets those formats expect (using new `assets` field or deprecated `assets_required`)
+ * 3. How to properly structure creative_manifest for cards
+ */
+
+import { AdCPClient } from '../src/lib/core/AdCPClient';
+import { getFormatAssets, getRequiredAssets, getOptionalAssets, usesDeprecatedAssetsField } from '../src/lib';
+
+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('🔍 Inspecting Card Format Definitions\n');
+
+  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_URL}\n`);
+
+  // List all formats
+  console.log('📋 Fetching all creative formats...');
+  const result = await creativeAgent.listCreativeFormats({});
+
+  if (!result.success || !result.data) {
+    console.error('❌ Failed to fetch formats:', result.error);
+    process.exit(1);
+  }
+
+  const formats = result.data.formats || [];
+  console.log(`✅ Found ${formats.length} formats\n`);
+
+  // Look for card formats
+  const cardFormats = formats.filter(
+    f =>
+      f.format_id.id.includes('card') ||
+      f.name?.toLowerCase().includes('card') ||
+      f.description?.toLowerCase().includes('card')
+  );
+
+  if (cardFormats.length === 0) {
+    console.log('⚠️  No formats with "card" in name/description found');
+    console.log('\n📋 All available format IDs:');
+    formats.forEach(f => {
+      console.log(`  - ${f.format_id.id}: ${f.name || 'Unnamed'}`);
+    });
+  } else {
+    console.log('═══════════════════════════════════════════════════════════');
+    console.log('CARD FORMATS FOUND');
+    console.log('═══════════════════════════════════════════════════════════\n');
+
+    cardFormats.forEach((format, index) => {
+      console.log(`\n${'═'.repeat(60)}`);
+      console.log(`Format ${index + 1}: ${format.name || 'Unnamed'}`);
+      console.log('─'.repeat(60));
+      console.log(`Format ID: ${format.format_id.id}`);
+      console.log(`Agent URL: ${format.format_id.agent_url}`);
+      console.log(`Type: ${format.type || 'N/A'}`);
+      console.log(`Description: ${format.description || 'N/A'}`);
+
+      const assets = getFormatAssets(format);
+      if (assets.length > 0) {
+        const requiredAssets = getRequiredAssets(format);
+        const optionalAssets = getOptionalAssets(format);
+        console.log(
+          `\n📦 Assets: ${assets.length} total (${requiredAssets.length} required, ${optionalAssets.length} optional)`
+        );
+        if (usesDeprecatedAssetsField(format)) {
+          console.log('   ⚠️  Using deprecated assets_required field');
+        }
+        assets.forEach(asset => {
+          if (asset.item_type === 'individual') {
+            console.log(`\n  Asset: ${asset.asset_id}`);
+            console.log(`  Type: ${asset.asset_type}`);
+            console.log(`  Required: ${asset.required ? 'yes' : 'no'}`);
+            if ((asset as any).description) {
+              console.log(`  Description: ${(asset as any).description}`);
+            }
+            if ((asset as any).default_value) {
+              console.log(`  Default: ${JSON.stringify((asset as any).default_value)}`);
+            }
+          } else {
+            console.log(`\n  Asset Group: ${asset.asset_group_id}`);
+            console.log(`  Required: ${asset.required ? 'yes' : 'no'}`);
+            console.log(`  Count: ${asset.min_count}-${asset.max_count}`);
+          }
+        });
+      } else {
+        console.log('\n⚠️  No assets defined (flexible format)');
+      }
+
+      if (format.preview_image) {
+        console.log(`\n🖼️  Preview Image: ${format.preview_image}`);
+      }
+
+      if (format.format_card) {
+        console.log('\n🎴 This format has its own format_card:');
+        console.log(`  Format ID: ${format.format_card.format_id.agent_url}/${format.format_card.format_id.id}`);
+        console.log(`  Manifest: ${JSON.stringify(format.format_card.manifest, null, 2)}`);
+      }
+    });
+  }
+
+  // Also show what a typical format looks like
+  console.log('\n\n═══════════════════════════════════════════════════════════');
+  console.log('EXAMPLE: Standard Display Format (for reference)');
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  const displayFormat = formats.find(f => f.format_id.id.includes('display') && f.format_id.id.includes('300x250'));
+
+  if (displayFormat) {
+    console.log(`Format ID: ${displayFormat.format_id.id}`);
+    console.log(`Name: ${displayFormat.name || 'Unnamed'}`);
+    console.log(`Type: ${displayFormat.type || 'N/A'}`);
+
+    const displayAssets = getFormatAssets(displayFormat);
+    if (displayAssets.length > 0) {
+      const requiredAssets = getRequiredAssets(displayFormat);
+      const optionalAssets = getOptionalAssets(displayFormat);
+      console.log(
+        `\n📦 Assets: ${displayAssets.length} total (${requiredAssets.length} required, ${optionalAssets.length} optional)`
+      );
+      if (usesDeprecatedAssetsField(displayFormat)) {
+        console.log('   ⚠️  Using deprecated assets_required field');
+      }
+      displayAssets.forEach(asset => {
+        if (asset.item_type === 'individual') {
+          console.log(`  - ${asset.asset_id} (${asset.asset_type})${asset.required ? ' *required*' : ' (optional)'}`);
+        } else {
+          console.log(
+            `  - [Group] ${asset.asset_group_id} (${asset.min_count}-${asset.max_count})${asset.required ? ' *required*' : ' (optional)'}`
+          );
+        }
+      });
+    }
+  } else {
+    console.log('⚠️  No standard 300x250 display format found');
+  }
+
+  console.log('\n\n💡 Key Insights:');
+  console.log('─'.repeat(60));
+  console.log('1. Formats define their assets using `assets` field (v2.6+) or deprecated `assets_required`');
+  console.log('2. Use getFormatAssets() helper to access assets with backward compatibility');
+  console.log('3. creative_manifest.assets should map asset_id -> asset object');
+  console.log("4. Each asset_id must match the format's assets definition");
+  console.log('5. Asset types (ImageAsset, TextAsset, etc) depend on asset_type\n');
+}
+
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});