@adcp/client 4.21.0 → 4.22.1

package/examples/zod-validation-example.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env tsx
+/**
+ * Example: Using Zod Schemas for Runtime Validation
+ *
+ * This example demonstrates how to use the generated Zod schemas to validate
+ * AdCP data structures at runtime. This is particularly useful for:
+ *
+ * - Validating API responses from agents
+ * - Ensuring data integrity before sending requests
+ * - Building forms with runtime validation
+ * - Integrating with zod-form libraries
+ */
+
+import {
+  MediaBuySchema,
+  ProductSchema,
+  GetProductsRequestSchema,
+  GetProductsResponseSchema,
+  CreateMediaBuyRequestSchema,
+  CreateMediaBuyResponseSchema,
+} from '../src/lib/types/schemas.generated';
+
+// Example 1: Validate a media buy structure
+console.log('📦 Example 1: Validating a MediaBuy\n');
+
+const mediaBuy = {
+  media_buy_id: 'mb_12345',
+  status: 'active',
+  promoted_offering: 'Nike Spring Collection 2024',
+  total_budget: 50000,
+  packages: [],
+};
+
+const mediaBuyResult = MediaBuySchema.safeParse(mediaBuy);
+
+if (mediaBuyResult.success) {
+  console.log('✅ MediaBuy is valid!');
+  console.log('Validated data:', mediaBuyResult.data);
+} else {
+  console.log('❌ MediaBuy validation failed:');
+  console.log(mediaBuyResult.error.format());
+}
+
+// Example 2: Validate and catch errors in a product
+console.log('\n📦 Example 2: Validating a Product (with intentional error)\n');
+
+const invalidProduct = {
+  product_id: 'prod_123',
+  // Missing required fields like 'name', 'description', etc.
+};
+
+const productResult = ProductSchema.safeParse(invalidProduct);
+
+if (productResult.success) {
+  console.log('✅ Product is valid!');
+} else {
+  console.log('❌ Product validation failed (as expected):');
+  console.log(
+    'Issues found:',
+    productResult.error.issues.map(issue => ({
+      path: issue.path.join('.'),
+      message: issue.message,
+    }))
+  );
+}
+
+// Example 3: Validate request before sending to agent
+console.log('\n📦 Example 3: Validating a GetProducts Request\n');
+
+const getProductsRequest = {
+  brief: 'Looking for premium display inventory targeting tech professionals',
+  brand_manifest: {
+    brand_name: 'TechCorp',
+    product_catalog: [],
+  },
+};
+
+const requestResult = GetProductsRequestSchema.safeParse(getProductsRequest);
+
+if (requestResult.success) {
+  console.log('✅ Request is valid and ready to send!');
+  console.log('Brief:', requestResult.data.brief);
+} else {
+  console.log('❌ Request validation failed:');
+  console.log(requestResult.error.format());
+}
+
+// Example 4: Validate response from agent
+console.log('\n📦 Example 4: Validating a GetProducts Response\n');
+
+const getProductsResponse = {
+  products: [],
+};
+
+const responseResult = GetProductsResponseSchema.safeParse(getProductsResponse);
+
+if (responseResult.success) {
+  console.log('✅ Response is valid!');
+  console.log('Number of products:', responseResult.data.products.length);
+} else {
+  console.log('❌ Response validation failed:');
+  console.log(responseResult.error.format());
+}
+
+// Example 5: Using parse() instead of safeParse() to throw errors
+console.log('\n📦 Example 5: Using parse() for stricter validation\n');
+
+try {
+  // This will throw a ZodError if validation fails
+  const strictMediaBuy = MediaBuySchema.parse(mediaBuy);
+  console.log('✅ Strict validation passed!');
+} catch (error) {
+  console.log('❌ Strict validation failed and threw an error');
+  console.log(error);
+}
+
+console.log('\n✨ Examples complete!\n');
+
+// Additional use cases:
+console.log('💡 Additional use cases for Zod schemas:\n');
+console.log('1. Form validation with React Hook Form + Zod');
+console.log('2. API middleware for validating requests/responses');
+console.log('3. Testing: Validate mock data matches schema');
+console.log('4. OpenAPI generation with zod-to-openapi');
+console.log('5. Database schema validation before persistence');
+console.log('6. Type-safe transformations with .transform()');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/client",
-  "version": "4.21.0",
+  "version": "4.22.1",
   "description": "AdCP client library with protocol support for MCP and A2A",
   "main": "dist/lib/index.js",
   "types": "dist/lib/index.d.ts",
@@ -56,6 +56,11 @@
     "bin/**/*.js",
     "skills/**/*",
     ".claude-plugin/**/*",
+    "storyboards/**/*",
+    "docs/llms.txt",
+    "docs/guides/BUILD-AN-AGENT.md",
+    "examples/**/*",
+    "AGENTS.md",
     "README.md",
     "LICENSE"
   ],
@@ -81,6 +86,7 @@
     "generate-types": "tsx scripts/generate-types.ts",
     "generate-registry-types": "tsx scripts/generate-registry-types.ts",
     "generate-zod-schemas": "tsx scripts/generate-zod-from-ts.ts",
+    "generate-agent-docs": "tsx scripts/generate-agent-docs.ts",
     "sync-version": "tsx scripts/sync-version.ts",
     "validate-schemas": "tsx scripts/validate-schemas.ts",
     "lint": "eslint 'src/lib/testing/**/*.ts'",
@@ -94,6 +100,7 @@
     "ci:validate": "node scripts/ci-validate.js",
     "ci:quick": "npm run format:check && npm run typecheck && npm run build:lib && npm test",
     "ci:schema-check": "npm run sync-schemas && npm run generate-types && npm run generate-registry-types && git diff --exit-code src/lib/types/ src/lib/agents/ src/lib/registry/types.generated.ts schemas/registry/registry.yaml || (echo '⚠️  Generated files are out of sync. Run: npm run sync-schemas && npm run generate-types && npm run generate-registry-types' && exit 1)",
+    "ci:docs-check": "npm run generate-agent-docs && git diff --exit-code -I '> Generated at:' docs/llms.txt docs/TYPE-SUMMARY.md || (echo '⚠️  Agent docs are out of sync. Run: npm run generate-agent-docs' && exit 1)",
     "ci:pre-push": "npm run ci:schema-check && npm run ci:quick",
     "hooks:install": "node scripts/install-hooks.js",
     "hooks:uninstall": "rm -f .git/hooks/pre-push",
@@ -129,6 +136,9 @@
     "url": "https://github.com/adcontextprotocol/adcp-client/issues",
     "email": "bugs@adcontextprotocol.org"
   },
+  "dependencies": {
+    "yaml": "^2.7.1"
+  },
   "peerDependencies": {
     "@a2a-js/sdk": "^0.3.4",
     "@modelcontextprotocol/sdk": "^1.17.5",
@@ -144,7 +154,7 @@
     "@changesets/cli": "^2.29.7",
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
-    "@modelcontextprotocol/sdk": "^1.24.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.0",
     "@types/node": "^20.19.13",
     "eslint": "^10.0.3",

package/skills/adcp/SKILL.md

@@ -73,30 +73,40 @@ adcp https://agent.example.com get_products '{}' --protocol a2a
 
 ## Test runner
 
-Run protocol compliance tests against any AdCP agent. 20 built-in scenarios.
+Run protocol compliance tests against any AdCP agent. 24 built-in scenarios.
 
 ```bash
 adcp test <agent> [scenario] [options]
 adcp test --list-scenarios
 ```
 
-### Scenarios (run `adcp test --list-scenarios` for all 20 with descriptions)
+### Scenarios (run `adcp test --list-scenarios` for all 24 with descriptions)
 | Scenario | What it tests |
 |----------|---------------|
 | `health_check` | Basic connectivity |
 | `discovery` | get_products, list_creative_formats, list_authorized_properties |
 | `create_media_buy` | Discovery + create a media buy (dry-run by default) |
 | `full_sales_flow` | Full lifecycle: discovery, create, update, delivery |
+| `creative_sync` | Test sync_creatives flow |
+| `creative_inline` | Test inline creatives in create_media_buy |
 | `creative_flow` | Creative agent: list_formats, build, preview |
 | `signals_flow` | Signals: get_signals, activate |
 | `validation` | Schema validation (invalid inputs should be rejected) |
 | `error_handling` | Verify proper error responses |
 | `pricing_edge_cases` | Auction vs fixed pricing, min spend, bid_price |
+| `temporal_validation` | Date/time ordering and format validation |
 | `behavior_analysis` | Auth, brief relevance, filtering behavior |
+| `response_consistency` | Schema errors, pagination bugs, data mismatches |
 | `capability_discovery` | v3: get_adcp_capabilities |
 | `governance_property_lists` | v3: property list CRUD |
 | `governance_content_standards` | v3: content standards listing and calibration |
 | `si_session_lifecycle` | v3: structured interaction sessions |
+| `si_availability` | v3: SI offering availability check |
+| `campaign_governance` | v3: full governance lifecycle: sync_plans → check → execute → report |
+| `campaign_governance_denied` | v3: denied flow: over-budget, unauthorized market |
+| `campaign_governance_conditions` | v3: apply conditions → re-check |
+| `campaign_governance_delivery` | v3: delivery monitoring with drift detection |
+| `seller_governance_context` | v3: verify seller persists governance_context |
 
 ### Examples
 ```bash
@@ -204,6 +214,7 @@ If not installed, prefix all commands with `npx @adcp/client`. Requires Node.js
 - **"brand" / "property" / "registry" / "look up" / "validate domain"** — `adcp registry <command>`
 - **Specific tool name mentioned** — `adcp <agent> <tool> '<payload>'`
 - **"compare protocols"** — Run same call with `--protocol mcp` then `--protocol a2a`, diff results
+- **"build an agent" / "implement AdCP" / "server side"** — Read `docs/guides/BUILD-AN-AGENT.md` for server setup, and `storyboards/` for expected tool call sequences. Use `docs/llms.txt` for the protocol overview.
 
 ### Step 3: Handle authentication
 

package/storyboards/audience_sync.yaml

@@ -0,0 +1,199 @@
+id: audience_sync
+version: "1.0.0"
+title: "Audience sync"
+category: audiences
+summary: "Tests sync_audiences: account discovery, audience creation with hashed identifiers, and audience deletion."
+track: audiences
+required_tools:
+  - sync_audiences
+platform_types:
+  - display_ad_server
+  - social_platform
+  - retail_media
+  - dsp
+  - pmax_platform
+
+narrative: |
+  You support audience syncing via the sync_audiences task. Buyers push first-party
+  audience segments to your platform using hashed identifiers (emails, phones). Your
+  platform matches those identifiers against your user graph and returns match rates.
+
+  This storyboard verifies the full audience lifecycle: discover an account to sync
+  against, create a test audience with hashed identifiers, and clean up by deleting it.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_audiences
+  examples:
+    - "Retail media networks"
+    - "Social platforms"
+    - "DSPs with audience onboarding"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs an active account on the seller platform. The account_setup phase
+    discovers or creates the account relationship before syncing audiences.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      Before syncing audiences, the buyer needs an account on the seller platform.
+      This phase discovers an existing account via list_accounts or establishes one
+      via sync_accounts.
+
+    steps:
+      - id: discover_account
+        title: "Discover or create account"
+        narrative: |
+          List existing accounts to find one suitable for audience sync. If no accounts
+          exist, sync_accounts creates one. The account_id is captured for use in
+          subsequent audience operations.
+        task: list_accounts
+        schema_ref: "account/list-accounts-request.json"
+        response_schema_ref: "account/list-accounts-response.json"
+        doc_ref: "/accounts/tasks/list_accounts"
+        comply_scenario: account_setup
+        stateful: false
+        context_outputs:
+          - name: account_id
+            path: "accounts[0].account_id"
+          - name: account_ref
+            path: "accounts[0]"
+        expected: |
+          Return at least one account with:
+          - account_id: platform-assigned identifier
+          - status: active (required for audience sync)
+
+        sample_request: {}
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "At least one account exists with an account_id"
+
+  - id: audience_sync
+    title: "Audience sync"
+    narrative: |
+      The buyer syncs a test audience containing hashed email and phone identifiers.
+      The seller platform matches those identifiers and returns per-audience results
+      including action (created/updated), status, and match rates.
+
+      After verifying creation, the test audience is deleted to clean up.
+
+    steps:
+      - id: discover_audiences
+        title: "Discover existing audiences"
+        narrative: |
+          Call sync_audiences with no audiences array to discover what audiences
+          already exist on the platform for this account. This is a read-only
+          discovery call.
+        task: sync_audiences
+        schema_ref: "audience/sync-audiences-request.json"
+        response_schema_ref: "audience/sync-audiences-response.json"
+        doc_ref: "/audiences/tasks/sync_audiences"
+        comply_scenario: audience_sync
+        stateful: false
+        context_outputs:
+          - name: existing_audience_count
+            path: "audiences.length"
+        expected: |
+          Return existing audiences for the account (may be empty).
+          Each audience should have an audience_id and status.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-audiences-response.json schema"
+
+      - id: create_audience
+        title: "Create test audience"
+        narrative: |
+          Push a test audience with hashed email and phone identifiers. The seller
+          matches identifiers against their user graph and returns the audience with
+          action: created, match counts, and match rate.
+        task: sync_audiences
+        schema_ref: "audience/sync-audiences-request.json"
+        response_schema_ref: "audience/sync-audiences-response.json"
+        doc_ref: "/audiences/tasks/sync_audiences"
+        comply_scenario: audience_sync
+        stateful: true
+        context_outputs:
+          - name: test_audience_id
+            path: "audiences[0].audience_id"
+        expected: |
+          Accept the audience and return:
+          - audience_id: matches the submitted ID
+          - action: created
+          - status: active or processing
+          - uploaded_count: number of identifiers received
+          - matched_count: number of identifiers matched
+          - effective_match_rate: ratio of matched to uploaded
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          audiences:
+            - audience_id: "adcp-test-audience-001"
+              name: "AdCP E2E Test Audience"
+              add:
+                - hashed_email: "a000000000000000000000000000000000000000000000000000000000000000"
+                - hashed_phone: "b000000000000000000000000000000000000000000000000000000000000000"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-audiences-response.json schema"
+          - check: field_present
+            path: "audiences[0].audience_id"
+            description: "Audience has an audience_id"
+          - check: field_present
+            path: "audiences[0].action"
+            description: "Audience has an action (created or updated)"
+
+      - id: delete_audience
+        title: "Delete test audience"
+        narrative: |
+          Clean up by deleting the test audience. The seller should acknowledge the
+          deletion with action: deleted.
+        task: sync_audiences
+        schema_ref: "audience/sync-audiences-request.json"
+        response_schema_ref: "audience/sync-audiences-response.json"
+        doc_ref: "/audiences/tasks/sync_audiences"
+        comply_scenario: audience_sync
+        stateful: true
+        expected: |
+          Delete the test audience and return:
+          - audience_id: matches the test audience
+          - action: deleted
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          audiences:
+            - audience_id: "adcp-test-audience-001"
+              delete: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-audiences-response.json schema"
+          - check: field_present
+            path: "audiences[0].action"
+            description: "Audience deletion acknowledged with action field"

package/storyboards/behavioral_analysis.yaml

@@ -0,0 +1,244 @@
+id: behavioral_analysis
+version: "1.0.0"
+title: "Behavioral analysis"
+category: products
+summary: "Validates product discovery behavior, response consistency, and pricing edge cases."
+track: products
+required_tools:
+  - get_products
+platform_types:
+  - display_ad_server
+  - video_ad_server
+  - social_platform
+  - retail_media
+  - search_platform
+  - audio_platform
+  - linear_tv_platform
+  - dsp
+  - pmax_platform
+  - ai_ad_network
+  - ai_platform
+  - generative_dsp
+
+narrative: |
+  You expose a get_products task that accepts natural-language briefs and returns structured
+  product listings with pricing, delivery forecasts, and targeting. This storyboard verifies
+  three properties of that task:
+
+  1. Behavior analysis — do results change when the brief changes? Does the agent filter
+     products by brief content or return a static catalog?
+  2. Response consistency — given the same brief twice, does the agent return the same
+     product IDs? Deterministic responses are expected for identical inputs.
+  3. Pricing edge cases — do products declare valid pricing_options structures with
+     recognized delivery_type values (guaranteed or non_guaranteed)?
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+  examples:
+    - "Yahoo"
+    - "Retail media networks"
+    - "Publisher platforms"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity for product discovery requests.
+    The test kit provides a sample brand (Acme Outdoor) with campaign parameters.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: behavior_analysis
+    title: "Behavior analysis"
+    narrative: |
+      Tests whether the agent filters products based on the brief content. Two different
+      briefs are sent — one narrow (podcast audio only) and one broad (all products across
+      all channels). If the agent interprets briefs, the narrow brief should return fewer
+      products than the broad brief.
+
+    steps:
+      - id: get_products_narrow
+        title: "Get products with narrow brief"
+        narrative: |
+          Send a narrow brief requesting only podcast audio advertising. Capture the
+          returned product IDs so they can be compared with a broader request.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: behavior_analysis
+        stateful: false
+        context_outputs:
+          - name: narrow_product_ids
+            path: "products[*].product_id"
+          - name: narrow_product_count
+            path: "products.length"
+        expected: |
+          Return products matching the narrow brief. The result set should be scoped
+          to audio/podcast inventory if the agent performs brief filtering.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Looking specifically for podcast audio advertising only"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+
+      - id: get_products_broad
+        title: "Get products with broad brief"
+        narrative: |
+          Send a broad brief requesting all products across all channels. Compare the
+          result count against the narrow brief to determine whether the agent filters
+          by brief content.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: behavior_analysis
+        stateful: false
+        expected: |
+          Return all available products. If the agent performs brief filtering, this
+          response should contain more products than the narrow brief response.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Show all products across all channels and formats"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+          - check: compare_context
+            description: "Broad brief returns >= narrow brief product count"
+            context_ref: narrow_product_count
+            comparison: ">="
+
+  - id: response_consistency
+    title: "Response consistency"
+    narrative: |
+      Calls get_products twice with the identical brief and brand. The agent should
+      return the same product IDs both times. Non-deterministic responses indicate
+      randomness in product selection or caching issues.
+
+    steps:
+      - id: get_products_first
+        title: "First call with fixed brief"
+        narrative: |
+          Send a specific brief and capture the returned product IDs for comparison.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: response_consistency
+        stateful: false
+        context_outputs:
+          - name: first_call_product_ids
+            path: "products[*].product_id"
+        expected: |
+          Return products matching the brief. Product IDs are captured for comparison
+          with a second identical call.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "At least one product returned with a product_id"
+
+      - id: get_products_second
+        title: "Second call with identical brief"
+        narrative: |
+          Repeat the exact same request. The returned product IDs should match
+          those from the first call.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: response_consistency
+        stateful: false
+        expected: |
+          Return the same product IDs as the first call. Consistent responses
+          for identical inputs are expected.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: match_context
+            description: "Product IDs match the first call"
+            context_ref: first_call_product_ids
+            path: "products[*].product_id"
+
+  - id: pricing_edge_cases
+    title: "Pricing edge cases"
+    narrative: |
+      Validates the structure of pricing_options on returned products. Each product
+      should declare a delivery_type (guaranteed or non_guaranteed) and well-formed
+      pricing options with recognized fields.
+
+    steps:
+      - id: get_products_pricing
+        title: "Fetch products for pricing analysis"
+        narrative: |
+          Request all products with pricing details. Validate that each product has
+          a valid delivery_type and that pricing_options contain recognized fields
+          (fixed_price, floor_price, price_guidance, min_spend_per_package).
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: pricing_edge_cases
+        stateful: false
+        expected: |
+          Return products with well-formed pricing structures:
+          - Each product has a delivery_type: guaranteed or non_guaranteed
+          - Each pricing_option has a pricing_option_id
+          - Pricing fields are valid (no negative values, recognized pricing models)
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Show all products with pricing details"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains products array"
+          - check: field_present
+            path: "products[0].delivery_type"
+            description: "Each product declares guaranteed or non_guaranteed delivery"
+          - check: field_value
+            path: "products[*].delivery_type"
+            allowed_values:
+              - "guaranteed"
+              - "non_guaranteed"
+            description: "delivery_type is a recognized value"