@adcp/client 4.0.2 → 4.2.0

package/dist/lib/utils/deprecation.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Deprecation warning utility for backward-compat shims.
+ *
+ * Each key is warned once per process lifetime to avoid log spam.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnOnce = warnOnce;
+exports.resetWarnings = resetWarnings;
+const warned = new Set();
+function warnOnce(key, message) {
+    if (!warned.has(key)) {
+        warned.add(key);
+        console.warn(`[@adcp/client] DEPRECATED: ${message}`);
+    }
+}
+/**
+ * Reset all deprecation warnings. Only useful in tests.
+ */
+function resetWarnings() {
+    warned.clear();
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/lib/utils/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","sourceRoot":"","sources":["../../../src/lib/utils/deprecation.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAIH,4BAKC;AAKD,sCAEC;AAdD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;AAEjC,SAAgB,QAAQ,CAAC,GAAW,EAAE,OAAe;IACnD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}

package/dist/lib/utils/request-normalizer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Request parameter normalization for backward compatibility.
+ *
+ * Converts deprecated field names and shapes so callers written against
+ * earlier schema versions keep working. Each conversion emits a one-time
+ * deprecation warning via warnOnce().
+ */
+/**
+ * Normalize a single package's params for backward compatibility.
+ *
+ * Handles:
+ * - optimization_goal (scalar) → optimization_goals (array)
+ * - catalog (scalar object) → catalogs (array)
+ */
+export declare function normalizePackageParams(pkg: any): any;
+/**
+ * Normalize request params for backward compatibility.
+ *
+ * Infers missing fields that can be derived from deprecated params so callers
+ * written against older schema versions keep working.
+ */
+export declare function normalizeRequestParams(taskType: string, params: any): any;
+//# sourceMappingURL=request-normalizer.d.ts.map

package/dist/lib/utils/request-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-normalizer.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/request-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAuBpD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,CAqFzE"}

package/dist/lib/utils/request-normalizer.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Request parameter normalization for backward compatibility.
+ *
+ * Converts deprecated field names and shapes so callers written against
+ * earlier schema versions keep working. Each conversion emits a one-time
+ * deprecation warning via warnOnce().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePackageParams = normalizePackageParams;
+exports.normalizeRequestParams = normalizeRequestParams;
+const compat_1 = require("../types/compat");
+const deprecation_1 = require("./deprecation");
+/**
+ * Normalize a single package's params for backward compatibility.
+ *
+ * Handles:
+ * - optimization_goal (scalar) → optimization_goals (array)
+ * - catalog (scalar object) → catalogs (array)
+ */
+function normalizePackageParams(pkg) {
+    if (!pkg || typeof pkg !== 'object')
+        return pkg;
+    const normalized = { ...pkg };
+    // optimization_goal (scalar) → optimization_goals (array)
+    if (normalized.optimization_goal && !normalized.optimization_goals?.length) {
+        (0, deprecation_1.warnOnce)('optimization_goal', 'PackageRequest.optimization_goal is deprecated. Use optimization_goals (array) instead.');
+        normalized.optimization_goals = [normalized.optimization_goal];
+    }
+    delete normalized.optimization_goal;
+    // catalog (scalar) → catalogs (array)
+    if (normalized.catalog && !normalized.catalogs?.length) {
+        (0, deprecation_1.warnOnce)('catalog', 'PackageRequest.catalog is deprecated. Use catalogs (array) instead.');
+        normalized.catalogs = [normalized.catalog];
+    }
+    delete normalized.catalog;
+    return normalized;
+}
+/**
+ * Normalize request params for backward compatibility.
+ *
+ * Infers missing fields that can be derived from deprecated params so callers
+ * written against older schema versions keep working.
+ */
+function normalizeRequestParams(taskType, params) {
+    if (!params) {
+        return params;
+    }
+    let normalized = { ...params };
+    // ── Universal shims (all tools) ──
+    // Always delete deprecated fields, even when the new field already exists,
+    // to prevent Zod strict validation failures on unknown keys.
+    // account_id (bare string) → account: { account_id }
+    if (typeof normalized.account_id === 'string' && !normalized.account) {
+        (0, deprecation_1.warnOnce)('account_id', 'account_id is deprecated. Use account: { account_id } instead.');
+        normalized.account = { account_id: normalized.account_id };
+    }
+    delete normalized.account_id;
+    // campaign_ref → buyer_campaign_ref
+    if (normalized.campaign_ref && !normalized.buyer_campaign_ref) {
+        (0, deprecation_1.warnOnce)('campaign_ref', 'campaign_ref is deprecated. Use buyer_campaign_ref instead.');
+        normalized.buyer_campaign_ref = normalized.campaign_ref;
+    }
+    delete normalized.campaign_ref;
+    // ── brand_manifest → brand (get_products, create_media_buy) ──
+    // update_media_buy has no brand field in either v2 or v3 — excluded deliberately.
+    // brand takes precedence if both are supplied.
+    if (taskType === 'get_products' || taskType === 'create_media_buy') {
+        if (normalized.brand_manifest && !normalized.brand) {
+            const brand = (0, compat_1.brandManifestToBrandReference)(normalized.brand_manifest);
+            if (brand) {
+                normalized.brand = brand;
+            }
+        }
+        delete normalized.brand_manifest;
+    }
+    // ── Package normalization (create_media_buy, update_media_buy) ──
+    if ((taskType === 'create_media_buy' || taskType === 'update_media_buy') && Array.isArray(normalized.packages)) {
+        normalized.packages = normalized.packages.map(normalizePackageParams);
+    }
+    // ── activate_signal: deployments → destinations ──
+    if (taskType === 'activate_signal') {
+        if (normalized.deployments && !normalized.destinations) {
+            (0, deprecation_1.warnOnce)('deployments', 'deployments is deprecated. Use destinations instead.');
+            normalized.destinations = normalized.deployments;
+        }
+        delete normalized.deployments;
+    }
+    // ── get_signals: deliver_to → destinations ──
+    if (taskType === 'get_signals') {
+        if (normalized.deliver_to && !normalized.destinations) {
+            (0, deprecation_1.warnOnce)('deliver_to', 'deliver_to is deprecated. Use destinations and countries instead.');
+            normalized.destinations = normalized.deliver_to;
+        }
+        delete normalized.deliver_to;
+    }
+    // ── get_products-specific normalization ──
+    if (taskType === 'get_products') {
+        // Infer buying_mode from brief presence if not supplied
+        if (!normalized.buying_mode) {
+            normalized.buying_mode = normalized.brief ? 'brief' : 'wholesale';
+        }
+        // Strip removed v2 fields that would fail strict validation
+        for (const removed of ['feedback', 'product_ids', 'proposal_id']) {
+            if (removed in normalized) {
+                (0, deprecation_1.warnOnce)(`get_products.${removed}`, `GetProductsRequest.${removed} has been removed in v3.`);
+                delete normalized[removed];
+            }
+        }
+        // Convert legacy product_selectors (v3 beta / v2 era) → catalog so strict validation passes.
+        // catalog takes precedence if both are supplied.
+        if (normalized.product_selectors && !normalized.catalog) {
+            normalized.catalog = (0, compat_1.promotedProductsToCatalog)(normalized.product_selectors);
+        }
+        delete normalized.product_selectors;
+    }
+    return normalized;
+}
+//# sourceMappingURL=request-normalizer.js.map

package/dist/lib/utils/request-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-normalizer.js","sourceRoot":"","sources":["../../../src/lib/utils/request-normalizer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/client",
-  "version": "4.0.2",
+  "version": "4.2.0",
   "description": "AdCP client library with protocol support for MCP and A2A, includes testing framework",
   "main": "dist/lib/index.js",
   "types": "dist/lib/index.d.ts",
@@ -36,6 +36,8 @@
   "files": [
     "dist/lib/**/*",
     "bin/**/*.js",
+    "skills/**/*",
+    ".claude-plugin/**/*",
     "README.md",
     "LICENSE"
   ],

package/skills/adcp/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: adcp
+description: Interact with AdCP (Ad Context Protocol) advertising agents over MCP or A2A protocols. Use when the user wants to call AdCP tools (get_products, create_media_buy, sync_creatives, etc.), discover an agent's capabilities, run protocol compliance tests, look up brands or properties in the AdCP registry, manage saved agent aliases, or debug agent responses. NOT for general HTTP/REST API calls. Requires @adcp/client (npm).
+argument-hint: "<agent> [tool] [payload] | test <agent> [scenario] | registry <command>"
+allowed-tools: Bash, Read
+---
+
+# AdCP CLI
+
+Use `adcp` (or `npx @adcp/client`) to interact with AdCP advertising agents, run compliance tests, and query the AdCP registry.
+
+## Quick start — zero config
+
+Built-in test agents work immediately with no setup:
+
+```bash
+# Try AdCP right now
+adcp test-mcp                                          # List tools on the MCP test agent
+adcp test-mcp get_products '{"brief":"coffee brands"}' # Call a tool
+adcp test-a2a get_products '{"brief":"coffee brands"}' # Same thing over A2A
+
+# Run compliance tests
+adcp test test-mcp discovery                           # Test tool discovery
+adcp test test-mcp full_sales_flow                     # Full media buy lifecycle
+```
+
+Built-in aliases (no setup needed):
+- `test-mcp` — Public test agent via MCP (pre-authenticated)
+- `test-a2a` — Public test agent via A2A (pre-authenticated)
+- `test-no-auth` — MCP without auth (demonstrates auth errors)
+- `test-a2a-no-auth` — A2A without auth
+- `creative` — Official creative agent (MCP, requires `--auth` or `ADCP_AUTH_TOKEN`)
+
+## Calling agent tools
+
+```bash
+adcp <alias|url> [tool-name] [payload] [options]
+```
+
+### Discover tools (omit tool name)
+```bash
+adcp https://agent.example.com
+adcp my-alias
+```
+
+### Call a tool
+```bash
+adcp https://agent.example.com get_products '{"brief":"coffee brands"}'
+adcp https://agent.example.com create_media_buy @payload.json
+echo '{"brief":"travel"}' | adcp https://agent.example.com get_products -
+```
+
+### Authentication (priority order)
+```bash
+adcp my-alias get_products '{}'                                         # 1. Saved config
+adcp https://agent.example.com get_products '{}' --auth $TOKEN          # 2. Flag
+export ADCP_AUTH_TOKEN=your-token && adcp https://agent.example.com get_products '{}' # 3. Env
+adcp https://agent.example.com/mcp --oauth                              # 4. OAuth (MCP only)
+```
+
+### Output modes
+```bash
+adcp test-mcp get_products '{"brief":"test"}'          # Pretty print (default)
+adcp test-mcp get_products '{"brief":"test"}' --json   # Raw JSON for scripting
+adcp test-mcp get_products '{"brief":"test"}' --debug  # Connection diagnostics
+```
+
+### Force protocol (default is auto-detect)
+```bash
+adcp https://agent.example.com get_products '{}' --protocol mcp
+adcp https://agent.example.com get_products '{}' --protocol a2a
+```
+
+## Test runner
+
+Run protocol compliance tests against any AdCP agent. 19 built-in scenarios.
+
+```bash
+adcp test <agent> [scenario] [options]
+adcp test --list-scenarios
+```
+
+### Scenarios (run `adcp test --list-scenarios` for all 19 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_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 |
+| `behavior_analysis` | Auth, brief relevance, filtering behavior |
+| `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 |
+
+### Examples
+```bash
+adcp test test-mcp discovery                           # Quick check
+adcp test test-mcp full_sales_flow --json              # CI-friendly JSON output
+adcp test https://my-agent.com validation --protocol mcp
+adcp test my-alias create_media_buy --no-dry-run       # Real operations (careful!)
+```
+
+### Test options
+- `--json` — Machine-readable output for CI
+- `--debug` — Verbose logging
+- `--protocol mcp|a2a` — Force protocol
+- `--no-dry-run` — Execute real operations (default is dry-run)
+- `--brief "text"` — Custom brief for product discovery tests
+
+## Registry
+
+Look up brands, properties, agents, and publishers in the AdCP registry.
+
+```bash
+adcp registry <command> [args] [options]
+```
+
+### Lookups
+```bash
+adcp registry brand nike.com
+adcp registry brands nike.com adidas.com --json
+adcp registry property nytimes.com
+adcp registry enrich-brand nike.com
+```
+
+### Discovery and validation
+```bash
+adcp registry discover https://agent.example.com
+adcp registry validate nytimes.com
+adcp registry validate-publisher nytimes.com
+adcp registry lookup nytimes.com
+adcp registry check-auth https://agent.com domain nytimes.com
+```
+
+### Listing and search
+```bash
+adcp registry agents --type sales --health
+adcp registry search nike --json
+adcp registry publishers
+adcp registry stats
+```
+
+### Save operations (requires --auth or ADCP_REGISTRY_API_KEY)
+```bash
+adcp registry save-brand acme.com "Acme Corp" --auth $KEY
+adcp registry save-property example.com https://agent.com --auth $KEY
+```
+
+## Agent management
+
+```bash
+adcp --save-auth prod https://prod-agent.com           # Interactive setup
+adcp --save-auth prod https://agent.com --auth $TOKEN  # With token
+adcp --save-auth prod https://agent.com --no-auth      # No auth
+adcp --save-auth prod https://agent.com/mcp --oauth    # OAuth (MCP only)
+adcp --list-agents
+adcp --remove-agent prod
+adcp --show-config
+```
+
+Config stored at `~/.adcp/config.json`.
+
+## Async/webhook support
+
+For long-running operations (e.g. create_media_buy with human-in-the-loop approval):
+
+```bash
+adcp https://agent.example.com create_media_buy @payload.json --auth $TOKEN --wait
+adcp http://localhost:3000/mcp create_media_buy @payload.json --wait --local
+```
+
+- `--wait` — Start webhook listener, wait for async response
+- `--local` — Local webhook without ngrok (for localhost agents)
+- `--timeout MS` — Webhook timeout (default: 300000 = 5 min)
+
+Remote `--wait` requires ngrok: `brew install ngrok`
+
+## Exit codes
+
+- `0` — Success
+- `1` — Network or JSON error
+- `2` — Invalid arguments
+- `3` — Agent error (auth failure, task failed, webhook timeout)
+
+## Task: $ARGUMENTS
+
+### Step 1: Check installation
+```bash
+which adcp 2>/dev/null && echo "installed" || echo "use npx @adcp/client"
+```
+If not installed, prefix all commands with `npx @adcp/client`. Requires Node.js 18+.
+
+### Step 2: Route the request
+
+- **"try AdCP" / "show me how it works" / no specific agent** — Use built-in `test-mcp`
+- **"what tools" / "discover" / "list tools"** — `adcp <agent>` with no tool name
+- **"test" / "run tests" / "compliance" / "validate agent"** — `adcp test <agent> [scenario]`
+- **"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
+
+### Step 3: Handle authentication
+
+1. Built-in aliases `test-mcp` and `test-a2a` have auth included — use for demos
+2. `creative` alias has no auth bundled — user must provide `--auth` or `ADCP_AUTH_TOKEN`
+3. Saved aliases may have auth — check with `adcp --list-agents`
+4. `--auth $TOKEN` flag or `ADCP_AUTH_TOKEN` env var
+5. `--oauth` for MCP agents using OAuth (opens browser, saves tokens to alias)
+6. If no auth and agent requires it, ask the user
+
+### Step 4: Choose output format
+
+- Default (pretty print) for exploration and debugging
+- `--json` when piping, parsing, or running in CI
+- `--debug` when troubleshooting connection or protocol issues
+
+### Step 5: Run and interpret
+
+- Run the command
+- Exit code 1: network/parsing error — suggest `--debug`
+- Exit code 2: bad arguments — check syntax
+- Exit code 3: agent error — check auth token, try `--debug`, verify agent is reachable
+- Empty results are valid — do not fabricate data
+- For `--json` output, parse and summarize the key fields for the user