@adcp/sdk 5.23.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "adcp",
+  "owner": {
+    "name": "AdCP Community",
+    "email": "maintainers@adcontextprotocol.org"
+  },
+  "metadata": {
+    "description": "Plugins for the Ad Context Protocol (AdCP) ecosystem"
+  },
+  "plugins": [
+    {
+      "name": "adcp-client",
+      "source": "./",
+      "description": "Call AdCP advertising agent tools over MCP or A2A, run protocol compliance scenarios, and query the AdCP registry. Includes built-in test agents for zero-config use."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "adcp-client",
+  "npm": "@adcp/sdk",
+  "description": "Adds the /adcp skill for calling AdCP advertising agent tools over MCP or A2A, running protocol compliance scenarios, and querying the AdCP registry. Includes built-in test agents for zero-config use. Backed by the `@adcp/sdk` npm package (formerly `@adcp/client`).",
+  "author": {
+    "name": "AdCP Community",
+    "email": "maintainers@adcontextprotocol.org"
+  },
+  "homepage": "https://github.com/adcontextprotocol/adcp-client",
+  "repository": "https://github.com/adcontextprotocol/adcp-client",
+  "license": "Apache-2.0",
+  "keywords": [
+    "adcp",
+    "advertising",
+    "mcp",
+    "a2a",
+    "protocol",
+    "adtech",
+    "programmatic",
+    "testing",
+    "compliance",
+    "registry",
+    "media-buy"
+  ]
+}

package/ADCP_VERSION

@@ -0,0 +1 @@
+3.0.1

package/AGENTS.md

@@ -0,0 +1,282 @@
+# AI Coding Assistant Instructions for AdCP Client
+
+This document contains essential guidelines for AI coding assistants (Claude, Copilot, etc.) working on the AdCP Client project.
+
+## Start Here
+
+**Protocol overview** — Read `docs/llms.txt` for a single-file summary of AdCP: all 46 tools, key types, error codes, common flows, and test scenarios. Also available at https://adcontextprotocol.github.io/adcp-client/llms.txt
+
+**Type reference** — Read `docs/TYPE-SUMMARY.md` for curated type signatures (AgentConfig, TaskResult, ConversationContext, and all tool request/response shapes).
+
+**Do NOT read these files** — they are large generated files that waste context:
+- `src/lib/types/tools.generated.ts` (~13,000 lines) — use TYPE-SUMMARY.md instead
+- `src/lib/types/core.generated.ts` (~2,000 lines) — use TYPE-SUMMARY.md instead
+- `src/lib/types/schemas.generated.ts` (~8,000 lines) — Zod runtime schemas, rarely needed directly
+- `src/lib/agents/index.generated.ts` — generated Agent classes, use the client API instead
+
+**Building a server-side agent?** — Read `docs/guides/BUILD-AN-AGENT.md` and the published compliance storyboards at `https://adcontextprotocol.org/compliance/{version}/` (mirrored locally in `compliance/cache/{version}/` after `npm run sync-schemas`).
+
+**Testing an agent for conformance?** — Read `docs/guides/CONFORMANCE.md` and call `runConformance(agentUrl, opts)` from `@adcp/sdk/conformance`. Property-based fuzzing against the bundled JSON schemas; stateless tier covers 11 discovery tools across every protocol.
+
+## Project Overview
+
+**@adcp/sdk** is the official TypeScript client library for the Ad Context Protocol (AdCP), documented at [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org/docs/).
+
+**Components:**
+
+1. **Library** (`src/lib/`) - NPM package for AdCP agent communication
+2. **CLI** (`bin/`) - Command-line tooling for testing agents
+
+## 🚨 CRITICAL REQUIREMENTS - MUST FOLLOW 🚨
+
+### 1. ALWAYS USE OFFICIAL PROTOCOL CLIENTS
+
+- **A2A Protocol**: ALWAYS use the official `@a2a-js/sdk` client
+- **MCP Protocol**: ALWAYS use the official `@modelcontextprotocol/sdk` client
+- **NEVER** implement custom HTTP fallbacks or protocol implementations
+- **NEVER** parse SSE responses manually
+- **NEVER** make direct fetch() calls to agent endpoints
+- If an official client fails to import, FIX THE IMPORT - don't create workarounds
+
+### 2. NEVER USE MOCK DATA
+
+- **NEVER** inject mock products, formats, or any other fake data
+- **NEVER** provide fallback data when agents return empty responses
+- **ALWAYS** return exactly what the agents provide
+- If an agent returns empty arrays or errors, show that to the user
+- Real data only - no exceptions
+
+### 3. MCP CLIENT AUTHENTICATION - CRITICAL
+
+The MCP SDK automatically handles initialization. Authentication must be provided via headers:
+
+```javascript
+const transport = new StreamableHTTPClientTransport(url, {
+  requestInit: {
+    headers: {
+      'x-adcp-auth': authToken,
+    },
+  },
+});
+await client.connect(transport); // This automatically calls initialize internally
+```
+
+## Critical Architecture Patterns
+
+### Protocol Abstraction Layer
+
+The library supports both **A2A** and **MCP** protocols via unified interface:
+
+```typescript
+import { ProtocolClient } from './src/lib/protocols';
+// Routes to: callA2ATool() or callMCPTool() based on agent.protocol
+```
+
+**🚨 CRITICAL: A2A Protocol Implementation Requirements**
+
+The A2A protocol has specific implementation requirements that differ from MCP:
+
+**1. Artifact Field Names**
+
+A2A artifacts use `artifactId` per @a2a-js/sdk Artifact interface, NOT `name`:
+
+```typescript
+// Correct (per @a2a-js/sdk)
+if (!artifact.artifactId) {
+  warnings.push('A2A artifact missing artifactId field');
+}
+
+// Incorrect - 'name' doesn't exist in A2A SDK
+if (!artifact.name) { ... }
+```
+
+**2. Two Types of Webhooks - Do Not Confuse!**
+
+**1. `push_notification_config` - For Async Task Status Updates**
+
+Used for receiving task completion/progress notifications. Placement differs by protocol:
+
+- **A2A Protocol**: Goes in `params.configuration.pushNotificationConfig` (camelCase)
+
+  ```typescript
+  await a2aClient.sendMessage({
+    message: { /* task content */ },
+    configuration: {
+      pushNotificationConfig: {  // ← For async task status
+        url: webhookUrl,
+        token?: clientToken,
+        authentication: { schemes: ['HMAC-SHA256'], credentials: secret }
+      }
+    }
+  });
+  ```
+
+- **MCP Protocol**: Goes in tool arguments as `push_notification_config` (snake_case)
+  ```typescript
+  await mcpClient.callTool('create_media_buy', {
+    buyer_ref: '...',
+    packages: [...],
+    push_notification_config: {  // ← For async task status
+      url: webhookUrl,
+      token?: clientToken,
+      authentication: { schemes: ['HMAC-SHA256'], credentials: secret }
+    }
+  });
+  ```
+
+**2. `reporting_webhook` - For Reporting Data Delivery**
+
+Used for receiving periodic performance metrics. **Always stays in skill parameters** (both A2A and MCP):
+
+```typescript
+// Both protocols - reporting_webhook in skill parameters
+{
+  buyer_ref: '...',
+  packages: [...],
+  reporting_webhook: {  // ← Stays in parameters for BOTH protocols
+    url: reportingUrl,
+    token?: clientToken,
+    authentication: { schemes: ['HMAC-SHA256'], credentials: secret },
+    reporting_frequency: 'daily',  // Additional fields specific to reporting
+    requested_metrics: ['impressions', 'spend', 'clicks']
+  }
+}
+```
+
+Schema: https://adcontextprotocol.org/schemas/v1/core/push-notification-config.json
+
+The `ProtocolClient.callTool()` method in `src/lib/protocols/index.ts` handles this routing automatically.
+
+### Async Operation Patterns (AdCP PR 78)
+
+All operations follow 5 status patterns based on agent response:
+
+- `completed` - Sync completion with result
+- `working` - Long-running, poll with `tasks/get`
+- `submitted` - Webhook delivery required
+- `input_required` - Agent needs clarification via input handlers
+- `deferred` - Client defers decision to human/external system
+
+```typescript
+// Core flow in src/lib/core/TaskExecutor.ts
+const result = await executor.executeTask(agent, 'get_products', params, inputHandler);
+// Status determines next steps: polling, webhook wait, or input handling
+```
+
+### Conversation-Aware Input Handling
+
+Agents may need clarifications during execution. Use input handlers:
+
+```typescript
+const client = new AdCPClient(agent, {
+  handlers: {
+    onGetProductsStatusChange: (response, metadata) => {
+      // Fires for ALL status changes: sync completion, webhook delivery, etc.
+    },
+  },
+});
+
+// Input handler pattern for clarifications
+const handler = async context => {
+  return context.inputRequest.field === 'budget' ? 50000 : context.deferToHuman();
+};
+```
+
+## Build & Release Process
+
+### Changesets-Based Releases
+
+**🚨 NEVER manually edit `package.json` version** - Use changesets:
+
+```bash
+npm run changeset          # Create changeset for changes
+# Merge PR to main → Auto Release PR created
+# Merge Release PR → Auto publish to npm
+```
+
+**The correct separation:**
+
+- `package.json` version = **Library version** (managed by changesets)
+- `src/lib/version.ts` ADCP_VERSION = **AdCP schema version** (can differ from library version)
+
+### Schema Generation Workflow
+
+Library types auto-generated from AdCP schemas:
+
+```bash
+npm run sync-schemas       # Download from protocol repo
+npm run generate-types     # Generate TypeScript types
+npm run generate-zod-schemas  # Generate runtime validation
+```
+
+## Testing Strategies
+
+### Protocol-Level Mocking
+
+Test TaskExecutor patterns by mocking `ProtocolClient.callTool()`:
+
+```javascript
+ProtocolClient.callTool = mock.fn(async (agent, taskName, params) => {
+  if (taskName === 'tasks/get') return { task: { status: 'working' } };
+  return { status: 'submitted' };
+});
+```
+
+### Test Commands
+
+```bash
+npm test                   # Unit tests
+npm run test:protocols     # Protocol compliance tests
+npm run test:e2e          # End-to-end against live server
+npm run test:all          # Full test suite
+```
+
+Tests run under `--test-timeout=60000`. If a test hangs indefinitely (high CPU, no output) rather than timing out, send `SIGQUIT` to dump the V8 stack before killing — see [CONTRIBUTING.md § Debugging a hung test](./CONTRIBUTING.md#debugging-a-hung-test).
+
+## File Organization
+
+- `docs/llms.txt` - **Start here**: protocol overview, all tools, types, flows (generated)
+- `docs/TYPE-SUMMARY.md` - Curated type reference (generated)
+- `src/lib/core/` - Main client classes (AdCPClient, TaskExecutor)
+- `src/lib/protocols/` - A2A/MCP protocol implementations
+- `src/lib/types/` - Generated TypeScript types from schemas (prefer TYPE-SUMMARY.md)
+- `compliance/cache/` - Storyboards pulled from `adcontextprotocol.org/compliance/{version}/` (gitignored; populated by `npm run sync-schemas`)
+- `test/lib/` - Library unit tests
+- `test/e2e/` - Integration tests
+- `examples/` - Usage examples and demos
+
+## Backwards Compatibility
+
+**This is a published npm library. Callers on older versions must not break when we add new required fields.**
+
+When adding a new required field to a request schema:
+
+1. **Infer it from existing fields** in `SingleAgentClient.normalizeRequestParams()` so callers that don't send it still work
+2. **Update all internal callers** (testing scenarios) to send the field explicitly
+3. **Add tests** verifying the inference works and that explicit values are preserved
+
+Example: `buying_mode` was added as required on `get_products`. The client infers it from `brief` presence — callers that only sent `{ brief: '...' }` keep working.
+
+The pattern:
+
+- `normalizeRequestParams()` runs before validation, filling in derivable fields
+- `validateRequest()` runs Zod schemas after normalization
+- `adaptRequestForServerVersion()` handles v3→v2 downgrades for older servers
+
+**Never add a required field without a backwards-compatible default or inference path.**
+
+## Common Gotchas
+
+1. **Protocol clients**: Always use official `@a2a-js/sdk` and `@modelcontextprotocol/sdk`
+2. **Mock data**: Never inject fallback data when agents return empty responses
+3. **Version management**: Let changesets handle package.json, edit ADCP_VERSION separately
+4. **Backwards compatibility**: New required schema fields need inference in `normalizeRequestParams()`
+
+## References
+
+- [Protocol overview (llms.txt)](https://adcontextprotocol.github.io/adcp-client/llms.txt)
+- [API Documentation](https://adcontextprotocol.github.io/adcp-client/api/index.html)
+- [AdCP Specification](https://adcontextprotocol.org)
+- [A2A SDK](https://github.com/a2a/a2a-js-sdk)
+- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Changesets Documentation](https://github.com/changesets/changesets)

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 AgenticAdvertising.Org
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.