@adcp/client 0.3.0 → 0.4.0

package/README.md

@@ -3,9 +3,18 @@
 [![npm version](https://badge.fury.io/js/@adcp%2Fclient.svg)](https://badge.fury.io/js/@adcp%2Fclient)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://your-org.github.io/adcp-client/)
 
-Official TypeScript/JavaScript client for the **Ad Context Protocol (AdCP)**. Seamlessly communicate with advertising agents using MCP and A2A protocols.
+Official TypeScript/JavaScript client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
+
+## The Core Concept
+
+AdCP operations are **distributed and asynchronous by default**. An agent might:
+- Complete your request **immediately** (synchronous)
+- Need time to process and **send results via webhook** (asynchronous)
+- Ask for **clarifications** before proceeding
+- Send periodic **status updates** as work progresses
+
+**Your code stays the same.** You write handlers once, and they work for both sync completions and webhook deliveries.
 
 ## Installation
 
@@ -13,239 +22,426 @@ Official TypeScript/JavaScript client for the **Ad Context Protocol (AdCP)**. Se
 npm install @adcp/client
 ```
 
-### Requirements
-
-- **Node.js**: Version 18.0.0 or higher (specified in `.nvmrc`)
-- **TypeScript**: 5.3.0+ for full type safety
-- **Peer Dependencies**: `@a2a-js/sdk` and `@modelcontextprotocol/sdk`
-
-## Quick Start
+## Quick Start: Distributed Operations
 
 ```typescript
 import { ADCPMultiAgentClient } from '@adcp/client';
 
-// Multi-agent setup with type safety
-const client = new ADCPMultiAgentClient([{
-  id: 'premium-agent',
-  name: 'Premium Ad Agent', 
-  agent_uri: 'https://agent.example.com/mcp/',
-  protocol: 'mcp',
-  auth_token_env: 'PREMIUM_AGENT_TOKEN' // Secure: references environment variable
-}]);
-
-const agent = client.agent('premium-agent');
-
-// ✅ TYPE-SAFE: Full IntelliSense and compile-time checking
-const result = await agent.getProducts({
-  brief: 'Looking for premium coffee advertising',
-  promoted_offering: 'Artisan coffee blends'
+// Configure agents and handlers
+const client = new ADCPMultiAgentClient([
+  {
+    id: 'agent_x',
+    agent_uri: 'https://agent-x.com',
+    protocol: 'a2a'
+  },
+  {
+    id: 'agent_y',
+    agent_uri: 'https://agent-y.com/mcp/',
+    protocol: 'mcp'
+  }
+], {
+  // Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
+  webhookUrlTemplate: 'https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}',
+
+  // Activity callback - fires for ALL events (requests, responses, status changes, webhooks)
+  onActivity: (activity) => {
+    console.log(`[${activity.type}] ${activity.task_type} - ${activity.operation_id}`);
+    // Log to monitoring, update UI, etc.
+  },
+
+  // Status change handlers - called for ALL status changes (completed, failed, needs_input, working, etc)
+  handlers: {
+    onGetProductsStatusChange: (response, metadata) => {
+      // Called for sync completion, async webhook, AND status changes
+      console.log(`[${metadata.status}] Got products for ${metadata.operation_id}`);
+
+      if (metadata.status === 'completed') {
+        db.saveProducts(metadata.operation_id, response.products);
+      } else if (metadata.status === 'failed') {
+        db.markFailed(metadata.operation_id, metadata.error);
+      } else if (metadata.status === 'needs_input') {
+        // Handle clarification needed
+        console.log('Needs input:', response.message);
+      }
+    }
+  }
 });
-// result is TaskResult<GetProductsResponse> with known properties
 
-if (result.success) {
-  console.log('Products:', result.data.products); // Fully typed!
-} else {
-  console.error('Error:', result.error);
+// Execute operation - library handles operation IDs, webhook URLs, context management
+const agent = client.agent('agent_x');
+const result = await agent.getProducts({ brief: 'Coffee brands' });
+
+// onActivity fired: protocol_request
+// onActivity fired: protocol_response
+
+// Check result
+if (result.status === 'completed') {
+  // Agent completed synchronously!
+  console.log('✅ Sync completion:', result.data.products.length, 'products');
+  // onGetProductsStatusChange handler ALREADY fired with status='completed' ✓
+}
+
+if (result.status === 'submitted') {
+  // Agent will send webhook when complete
+  console.log('⏳ Async - webhook registered at:', result.submitted?.webhookUrl);
+  // onGetProductsStatusChange handler will fire when webhook arrives ✓
 }
 ```
 
-## 🔧 Easy Configuration
+### Handling Clarifications (needs_input)
 
-### Environment-based Setup (Recommended)
-Set your agent configuration once and auto-discover everywhere:
+When an agent needs more information, you can continue the conversation:
 
-```bash
-# .env file - NEVER commit real tokens to version control
-ADCP_AGENTS='[{"id":"agent1","name":"My Agent","agent_uri":"https://agent.example.com","protocol":"mcp","auth_token_env":"MY_AGENT_TOKEN"}]'
-MY_AGENT_TOKEN=your_actual_token_here
+```typescript
+const result = await agent.getProducts({ brief: 'Coffee brands' });
+
+if (result.status === 'needs_input') {
+  console.log('❓ Agent needs clarification:', result.needs_input?.message);
+  // onActivity fired: status_change (needs_input)
+
+  // Continue the conversation with the same agent
+  const refined = await agent.continueConversation('Only premium brands above $50');
+  // onActivity fired: protocol_request
+  // onActivity fired: protocol_response
+
+  if (refined.status === 'completed') {
+    console.log('✅ Got refined results:', refined.data.products.length);
+    // onGetProductsStatusChange handler fired ✓
+  }
+}
 ```
 
-**Security Best Practices:**
-- Use `auth_token_env` to reference environment variables instead of hardcoding tokens
-- Add `.env` files to `.gitignore`
-- Rotate tokens regularly
-- Use different tokens for different environments
+## Webhook Pattern
+
+All webhooks (task completions AND notifications) use one endpoint with flexible URL templates.
+
+### Configure Your Webhook URL Structure
 
 ```typescript
-// Auto-discover agents from environment
-const client = ADCPMultiAgentClient.fromEnv();
-console.log(`Found ${client.agentCount} agents`); // Auto-discovered!
+const client = new ADCPMultiAgentClient(agents, {
+  // Path-based (default pattern)
+  webhookUrlTemplate: 'https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}',
 
-// Or manually configure
-const client = new ADCPMultiAgentClient([
-  { id: 'agent1', agent_uri: 'https://...', protocol: 'mcp' }
-]);
+  // OR query string
+  webhookUrlTemplate: 'https://myapp.com/webhook?agent={agent_id}&op={operation_id}&type={task_type}',
+
+  // OR custom path
+  webhookUrlTemplate: 'https://myapp.com/api/v1/adcp/{agent_id}?operation={operation_id}',
+
+  // OR namespace to avoid conflicts
+  webhookUrlTemplate: 'https://myapp.com/adcp-webhooks/{agent_id}/{task_type}/{operation_id}'
+});
 ```
 
-### Multiple Agents Made Simple
+### Single Webhook Endpoint
+
 ```typescript
-const client = new ADCPMultiAgentClient([
-  { id: 'premium', agent_uri: 'https://premium.example.com', protocol: 'mcp' },
-  { id: 'budget', agent_uri: 'https://budget.example.com', protocol: 'a2a' }
-]);
+// Handles ALL webhooks (task completions and notifications)
+app.post('/webhook/:task_type/:agent_id/:operation_id', async (req, res) => {
+  const { task_type, agent_id, operation_id } = req.params;
+
+  // Inject URL parameters into payload
+  const payload = {
+    ...req.body,
+    task_type,
+    operation_id
+  };
+
+  // Route to agent client - handlers fire automatically
+  const agent = client.agent(agent_id);
+  await agent.handleWebhook(payload, req.headers['x-adcp-signature']);
+
+  res.json({ received: true });
+});
+```
 
-// Work with specific agents
-const premium = client.agent('premium');
-const budget = client.agent('budget');
+### URL Generation is Automatic
 
-// Or run across all agents in parallel
-const allResults = await client.getProducts(params); // TaskResult<GetProductsResponse>[]
+```typescript
+const operationId = createOperationId();
+const webhookUrl = agent.getWebhookUrl('sync_creatives', operationId);
+// Returns: https://myapp.com/webhook/sync_creatives/agent_x/op_123
+// (or whatever your template generates)
 ```
 
-## 🛡️ Type Safety
+## Activity Events
 
-Get **full TypeScript support** with compile-time checking and IntelliSense:
+Get observability into everything happening:
 
 ```typescript
-const agent = client.agent('agent-id');
-
-// ✅ TYPE-SAFE METHODS: Full IntelliSense, compile-time checking
-await agent.getProducts(params);           // TaskResult<GetProductsResponse>
-await agent.createMediaBuy(params);       // TaskResult<CreateMediaBuyResponse>
-await agent.listCreativeFormats(params);  // TaskResult<ListCreativeFormatsResponse>
+const client = new ADCPMultiAgentClient(agents, {
+  onActivity: (activity) => {
+    console.log({
+      type: activity.type,              // 'protocol_request', 'webhook_received', etc.
+      operation_id: activity.operation_id,
+      agent_id: activity.agent_id,
+      status: activity.status
+    });
+
+    // Stream to UI, save to database, send to monitoring
+    eventStream.send(activity);
+  }
+});
+```
 
-// ✅ GENERIC METHOD WITH AUTO TYPE INFERENCE: No casting needed!
-const result = await agent.executeTask('get_products', params);
-// result is TaskResult<GetProductsResponse> - TypeScript knows the return type!
+Activity types:
+- `protocol_request` - Request sent to agent
+- `protocol_response` - Response received from agent
+- `webhook_received` - Webhook received from agent
+- `handler_called` - Completion handler fired
 
-// ✅ CUSTOM TYPES: For non-standard tasks
-const customResult = await agent.executeTask<MyCustomResponse>('custom_task', params);
+## Notifications (Agent-Initiated)
 
-// ✅ BOTH support async patterns & input handlers!
-const withHandler = await agent.getProducts(
-  { brief: "Premium inventory" },
-  async (inputRequest) => ({ approve: true })
-);
-```
+**Mental Model**: Notifications are operations that get set up when you create a media buy. The agent sends periodic updates (like delivery reports) to the webhook URL you configured during media buy creation.
 
-## Key Features
+```typescript
+// When creating a media buy, agent registers for delivery notifications
+const result = await agent.createMediaBuy({
+  campaign_id: 'camp_123',
+  budget: { amount: 10000, currency: 'USD' }
+  // Agent internally sets up recurring delivery_report notifications
+});
 
-- **🔗 Unified Interface** - Single API for MCP and A2A protocols
-- **⚡ Async Support** - Handle long-running tasks with webhooks and deferrals  
-- **🔐 Built-in Auth** - Bearer tokens and API key support with environment variable security
-- **🛡️ Type Safe** - Full TypeScript with comprehensive types
-- **📊 Production Ready** - Circuit breakers, retries, and validation
-- **🔒 Security-First** - No hardcoded tokens, SSRF protection, secure defaults
-- **🧪 Protocol Compliance** - 100% A2A and MCP specification compliance
-- **🌐 Cross-Platform** - Works with Node.js 18+ and modern JavaScript environments
+// Later, agent sends notifications to your webhook
+const client = new ADCPMultiAgentClient(agents, {
+  handlers: {
+    onMediaBuyDeliveryNotification: (notification, metadata) => {
+      console.log(`Report #${metadata.sequence_number}: ${metadata.notification_type}`);
 
-## Async Execution Model
+      // notification_type indicates progress:
+      // 'scheduled' → Progress update (like status: 'working')
+      // 'final' → Operation complete (like status: 'completed')
+      // 'delayed' → Still waiting (extended timeline)
 
-Handle complex async patterns with ease:
+      db.saveDeliveryUpdate(metadata.operation_id, notification);
 
-```typescript
-// Configure input handler for interactive tasks
-const client = ADCPClient.simple('https://agent.example.com', {
-  authToken: 'token',
-  inputHandler: async (request) => {
-    // Handle 'input-required' status
-    if (request.type === 'user_approval') {
-      const approved = await getUserApproval(request.data);
-      return { approved };
+      if (metadata.notification_type === 'final') {
+        db.markOperationComplete(metadata.operation_id);
+      }
     }
-    // Defer for human review
-    return { defer: true };
   }
 });
+```
 
-// Long-running server task (returns immediately)
-const result = await client.executeTask('analyze_campaign', {
-  campaign_id: '12345'
-});
+Notifications use the **same webhook URL pattern** as regular operations:
+```
+POST https://myapp.com/webhook/media_buy_delivery/agent_x/delivery_report_agent_x_2025-10
+```
 
-if (result.status === 'submitted') {
-  // Task running on server, will notify via webhook
-  console.log('Task ID:', result.submitted.taskId);
-  console.log('Webhook:', result.submitted.webhookUrl);
+The `operation_id` is lazily generated from agent + month: `delivery_report_{agent_id}_{YYYY-MM}`
+
+All intermediate reports for the same agent + month → same `operation_id`
+
+## Type Safety
+
+Full TypeScript support with IntelliSense:
+
+```typescript
+// All responses are fully typed
+const result = await agent.getProducts(params);
+// result: TaskResult<GetProductsResponse>
+
+if (result.success) {
+  result.data.products.forEach(p => {
+    console.log(p.name, p.price); // Full autocomplete!
+  });
 }
 
-// Client-deferred task (needs human input)
-if (result.status === 'deferred') {
-  // Save continuation for later
-  const continuation = result.deferred;
-  
-  // ... later, after human provides input ...
-  const finalResult = await client.resumeDeferredTask(
-    continuation,
-    { approved: true, budget: 50000 }
-  );
+// Handlers receive typed responses
+handlers: {
+  onCreateMediaBuyComplete: (response, metadata) => {
+    // response: CreateMediaBuyResponse
+    // metadata: WebhookMetadata
+    const buyId = response.media_buy_id; // Typed!
+  }
 }
 ```
 
-## Multi-Agent Support
+## Multi-Agent Operations
+
+Execute across multiple agents simultaneously:
 
 ```typescript
-import { ADCPMultiAgentClient } from '@adcp/client';
+const client = new ADCPMultiAgentClient([agentX, agentY, agentZ]);
 
-const client = new ADCPMultiAgentClient([
-  { 
-    id: 'agent1',
-    name: 'MCP Agent',
-    agent_uri: 'https://agent1.example.com/mcp/',
-    protocol: 'mcp',
-    requiresAuth: true,
-    auth_token_env: 'AGENT1_TOKEN'
-  },
-  {
-    id: 'agent2', 
-    name: 'A2A Agent',
-    agent_uri: 'https://agent2.example.com',
-    protocol: 'a2a'
+// Parallel execution across all agents
+const results = await client.getProducts({ brief: 'Coffee brands' });
+// results: TaskResult<GetProductsResponse>[]
+
+results.forEach((result, i) => {
+  const agentId = client.agentIds[i];
+  console.log(`${agentId}: ${result.status}`);
+
+  if (result.status === 'completed') {
+    console.log(`  Sync: ${result.data.products?.length} products`);
+  } else if (result.status === 'submitted') {
+    console.log(`  Async: webhook to ${result.submitted?.webhookUrl}`);
   }
-]);
+});
+```
+
+## Security
 
-// Execute on specific agent
-const result = await client.executeTask('agent1', 'get_products', params);
+### Webhook Signature Verification
+
+```typescript
+const client = new ADCPMultiAgentClient(agents, {
+  webhookSecret: process.env.WEBHOOK_SECRET
+});
 
-// Execute on all agents in parallel
-const results = await client.executeTaskOnAll('get_products', params);
+// Signatures verified automatically on handleWebhook()
+// Returns 401 if signature invalid
 ```
 
-## Documentation
+### Authentication
 
-- 📚 **[Full Documentation](https://your-org.github.io/adcp-client/)** - Complete guides and API reference
-- 🚀 **[Getting Started Guide](https://your-org.github.io/adcp-client/getting-started)** - Step-by-step tutorial
-- 🔄 **[Async Patterns](https://your-org.github.io/adcp-client/async-patterns)** - Handle complex async flows
-- 📖 **[API Reference](https://your-org.github.io/adcp-client/api)** - Generated from TypeDoc
-- 💡 **[Examples](./examples/)** - Real-world usage examples
+```typescript
+const agents = [{
+  id: 'agent_x',
+  agent_uri: 'https://agent-x.com',
+  protocol: 'a2a',
+  auth_token_env: process.env.AGENT_X_TOKEN, // ✅ Secure
+  requiresAuth: true
+}];
+```
 
-## Examples
+## Environment Configuration
 
 ```bash
-# Clone for full examples
-git clone https://github.com/your-org/adcp-client
-cd adcp-client/examples
+# .env
+WEBHOOK_URL_TEMPLATE="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
+WEBHOOK_SECRET="your-webhook-secret"
 
-# Run examples
-npx tsx basic-usage.ts
-npx tsx async-patterns.ts
-npx tsx multi-agent.ts
+ADCP_AGENTS='[
+  {
+    "id": "agent_x",
+    "agent_uri": "https://agent-x.com",
+    "protocol": "a2a",
+    "auth_token_env": "AGENT_X_TOKEN"
+  }
+]'
+AGENT_X_TOKEN="actual-token-here"
 ```
 
-## Testing UI
+```typescript
+// Auto-discover from environment
+const client = ADCPMultiAgentClient.fromEnv();
+```
+
+## Available Tools
+
+All AdCP tools with full type safety:
+
+**Media Buy Lifecycle:**
+- `getProducts()` - Discover advertising products
+- `listCreativeFormats()` - Get supported creative formats
+- `createMediaBuy()` - Create new media buy
+- `updateMediaBuy()` - Update existing media buy
+- `syncCreatives()` - Upload/sync creative assets
+- `listCreatives()` - List creative assets
+- `getMediaBuyDelivery()` - Get delivery performance
+
+**Audience & Targeting:**
+- `listAuthorizedProperties()` - Get authorized properties
+- `getSignals()` - Get audience signals
+- `activateSignal()` - Activate audience signals
+- `providePerformanceFeedback()` - Send performance feedback
+
+## Database Schema
+
+Simple unified event log for all operations:
+
+```sql
+CREATE TABLE webhook_events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  operation_id TEXT NOT NULL,        -- Groups related events
+  agent_id TEXT NOT NULL,
+  task_type TEXT NOT NULL,           -- 'sync_creatives', 'media_buy_delivery', etc.
+  status TEXT,                       -- For tasks: 'submitted', 'working', 'completed'
+  notification_type TEXT,            -- For notifications: 'scheduled', 'final', 'delayed'
+  sequence_number INTEGER,           -- For notifications: report sequence
+  payload JSONB NOT NULL,
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_events_operation ON webhook_events(operation_id);
+CREATE INDEX idx_events_agent ON webhook_events(agent_id);
+CREATE INDEX idx_events_timestamp ON webhook_events(timestamp DESC);
+
+-- Query all events for an operation
+SELECT * FROM webhook_events
+WHERE operation_id = 'op_123'
+ORDER BY timestamp;
+
+-- Get all delivery reports for agent + month
+SELECT * FROM webhook_events
+WHERE operation_id = 'delivery_report_agent_x_2025-10'
+ORDER BY sequence_number;
+```
 
-The package includes an interactive testing framework:
+## Testing
+
+Try the live testing UI at `http://localhost:8080` when running the server:
 
 ```bash
-# Install and run locally
-git clone https://github.com/your-org/adcp-client
-cd adcp-client
-npm install
-npm run dev
+npm start
+```
+
+Features:
+- Configure multiple agents (test agents + your own)
+- Execute ONE operation across all agents
+- See live activity stream (protocol requests, webhooks, handlers)
+- View sync vs async completions side-by-side
+- Test different scenarios (clarifications, errors, timeouts)
+
+## Examples
+
+### Basic Operation
+```typescript
+const result = await agent.getProducts({ brief: 'Coffee brands' });
+```
+
+### With Clarification Handler
+```typescript
+const result = await agent.createMediaBuy(
+  { brief: 'Coffee campaign' },
+  (context) => {
+    // Agent needs more info
+    if (context.inputRequest.field === 'budget') {
+      return 50000; // Provide programmatically
+    }
+    return context.deferToHuman(); // Or defer to human
+  }
+);
+```
+
+### With Webhook for Long-Running Operations
+```typescript
+const operationId = createOperationId();
+
+const result = await agent.syncCreatives(
+  { creatives: largeCreativeList },
+  null, // No clarification handler = webhook mode
+  {
+    contextId: operationId,
+    webhookUrl: agent.getWebhookUrl('sync_creatives', operationId)
+  }
+);
 
-# Open http://localhost:8080
+// Result will be 'submitted', webhook arrives later
+// Handler fires when webhook received
 ```
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT - see [LICENSE](./LICENSE) for details.
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Links
+## Support
 
-- [AdCP Specification](https://adcontextprotocol.org)
-- [Issue Tracker](https://github.com/your-org/adcp-client/issues)
-- [npm Package](https://www.npmjs.com/package/@adcp/client)
+- **Documentation**: [GitHub Pages](https://your-org.github.io/adcp-client/)
+- **Issues**: [GitHub Issues](https://github.com/your-org/adcp-client/issues)
+- **Protocol Spec**: [AdCP Specification](https://github.com/adcontextprotocol/adcp)