@adcp/sdk 16.5.0 → 16.6.0

package/docs/guides/TYPED-CLIENT-TOOLS.md

@@ -0,0 +1,49 @@
+# Typed client tools
+
+`SingleAgentClient` and `AgentClient` expose a camelCase method for every tool
+in the bundled AdCP manifest. Each method uses the normal request validation,
+idempotency-key generation, and per-client version negotiation. `executeTask`
+also has typed request and response mappings for every tool.
+
+```ts
+const result = await client.getTaskStatus({ task_id: sellerTaskId, include_result: true });
+if (result.success) console.log(result.data.status, result.data.result);
+
+const tasks = await client.listTasks({}); // Queries the seller's list_tasks tool.
+```
+
+`getTaskStatus({ task_id })` returns the protocol response inside `TaskResult`.
+The observed task's `status` and `error` remain data: querying a failed or working
+task completes the query without resubmitting or following that task.
+
+For compatibility, `getTaskStatus(taskId)` still returns mapped `TaskInfo`, and
+`listTasks()` with no arguments still lists locally tracked tasks. Use
+`trackTask()` or a submitted result's `waitForCompletion()` to observe completion.
+The object overload calls `get_task_status` directly and requires a seller that
+supports that tool. Use the string overload or task tracking for negotiated
+compatibility with older sellers.
+The typed response preserves the seller's `task_id`; callers should compare it
+with the requested ID. The string overload and completion tracking enforce that
+identity check automatically. Discovery and authorization failures are surfaced
+rather than treated as evidence that only the legacy tool is supported.
+
+SDK polling chooses `get_task_status` when advertised by the seller, falling back
+to `tasks_get` for MCP or `tasks/get` for A2A otherwise.
+
+The supported tools `listCreativeFormats`, `buildCreative`, `listTransformers`,
+`getContentStandards`, `listContentStandards`, `calibrateContent`, and
+`validateContentDelivery` have ordinary typed methods. Their existing `*Legacy`
+aliases remain available. These tool methods return their protocol wire shapes;
+the SDK's canonical creative discovery and delivery helpers remain available too.
+On the SDK 16 line these are the AdCP 3.2 wire shapes, including any legacy
+`format_id` fields the protocol still supports. Generic `preview_creative`
+execution uses the canonical preview helper; use `previewCreativeLegacy` for
+raw named-format requests.
+
+Direct `SingleAgentClient.syncPlans` and `getPlanAuditLogs` calls use the
+configured governance agent when present. Without one, the client requires its
+own agent to advertise the governance tool before sending the request.
+
+`complyTestController` is typed for conformance testing against a seller that
+advertises it. Its availability does not imply that a production seller enables
+test controls.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-25
-> Library: @adcp/sdk v16.5.0
+> Generated at: 2026-10-27
+> Library: @adcp/sdk v16.6.0
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -13,7 +13,7 @@ AdCP is an open protocol for AI agents to buy, manage, and optimize advertising
 
 ## Start here: AdCP 3.2
 
-The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@16.5`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
+The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@16.6`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
 
 The SDK is compact-lifecycle first: `list_products → buy_products → control_media_buy`, with `request_proposals → refine_proposals → accept_proposal` when terms need negotiation.
 

package/docs/migration-14.x-rc-worksheet.md

@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@16.5.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.5.0 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@16.6.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.6.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.7` |
 | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@16.5.0'
-npm view '@adcp/sdk@16.5.0' dist.integrity
+npm install --save-exact '@adcp/sdk@16.6.0'
+npm view '@adcp/sdk@16.6.0' dist.integrity
 ```
 
 ### Required and optional peers

package/docs/migration-6.6-to-6.7.md

@@ -1061,6 +1061,20 @@ paths produce a value. The store fills the gap for adopters who
 hadn't wired echo yet (the canonical silent-storyboard-failure for
 `media_buy_seller/inventory_list_targeting/get_after_create`).
 
+The current store also persists buy-level and package-level `context` from
+`create_media_buy`, including empty objects and null-valued keys. It fills
+missing resource context on `get_media_buys`; seller-provided echoes and the
+read request's top-level context take precedence. Targeting updates retain
+creation context. Context for packages added by `update_media_buy` remains
+adapter-owned.
+
+Package context follows unambiguous echoed identities (`product_id`,
+`package_id`, or legacy `buyer_ref`). Positional matching requires equal
+package counts and no contradictory identities. If pairing is ambiguous,
+only context echoed on the create response is retained for that package.
+Existing targeting-only records need no migration; creation context cannot
+be recovered retroactively from those records.
+
 ### 16. **breaking** — drop `customTools["update_rights"]`; wire `BrandRightsPlatform.updateRights`
 
 `update_rights` is now a framework-registered first-class tool (PR

package/docs/migration-account-change-feed.md

@@ -262,3 +262,22 @@ status-change record and webhook, so the subsequent authoritative
 creative library needed by the scenario's applicability check. Those training
 seller changes belong upstream; they do not introduce buyer durable storage or
 a persistent subscription runtime into the SDK.
+
+### Validating older feed releases
+
+`streamAccountChanges` uses negotiated response metadata, the served-version echo,
+or the client's configured AdCP version to select the page schema. For a custom
+reader without SDK metadata, pass `adcpVersion: '3.2.7'` in the stream options and
+send the same release in your reader's requests. AdCP 3.3 requires nonempty
+`changed_paths` on seller-originated changes; AdCP 3.2 does not.
+
+SDK 16.6 also provides the signature-agnostic delivery receiver parser described
+in [Parsing media-buy delivery webhooks](./guides/DELIVERY-WEBHOOK-PARSING.md).
+The stable parser accepts the bundled AdCP 3.0, 3.1, and 3.2 reporting contracts.
+
+When available, `metadata.wireAdcpVersion` records the trusted SDK-selected wire
+release, independently of the seller echo. Drains prefer negotiated/wire
+metadata, then a custom reader's explicit `adcpVersion`, then the echo and
+configured client pin. An older echo cannot weaken a known wire contract.
+Sellers without authoritative release metadata keep the echo/client fallback;
+use an explicit validation pin for a custom reader when its release is known.

package/docs/releases/sdk-16.6-adoption-fixes.md

@@ -0,0 +1,33 @@
+# SDK 16 stable adoption fixes
+
+The SDK keeps its AdCP 3.2.7 pin and existing legacy HTML mapping. New APIs are
+additive: `parseMediaBuyDeliveryWebhook`, the shared delivery report body/schema,
+canonical `AssetVariant` exports, and targeting overlay key arrays. The standalone
+parser accepts authenticated bytes and validates the trusted caller-selected
+release; existing `verifyAndParseWebhook` return contracts are unchanged.
+
+Account-sync results retain `account`, `operator_unit`, `revision`,
+`identity_change`, `identity_change_preview`, `currency`, and `timezone`.
+`SyncAccountsResultRow` remains an interface with required legacy
+`brand`/`operator`/`status` fields, so existing extending interfaces and read-side
+wrappers keep compiling. A 3.2 `account` reference takes precedence over the flat
+wire anchor; 3.0 and 3.1 retain the flat fields. The modern account-only result
+union is an SDK 17 migration. Adopters serving multiple releases should select
+result identity using `ctx.servedAdcpVersion`.
+
+The entire `destination_billing_entity` is request-only. Its name and tax data
+are stripped along with bank details and framework auth/context metadata before
+responses or replay caching. Nested account and operator identity objects use
+closed protocol schemas and are emitted as detached validated snapshots.
+
+Global daypart-union and nonempty Zod output tightening stays on SDK 17.
+AssetVariant alone restores reachable protocol minItems and shallow output
+typing, fixing the published TypeScript repro while preserving union options. The
+shared stable report body reflects the existing tolerant poll Zod output;
+version-aware delivery parsing uses strict authoritative JSON schemas.
+
+Asset bounds also apply when the shared catalog, provenance, inline-markup,
+tag/redirect and tracker schemas are used outside AssetVariant. Direct Zod
+consumers now reject those protocol-invalid empty arrays consistently with the
+existing authoritative wire schemas. Typed input and per-branch union helpers
+remain available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.5.0",
+  "version": "16.6.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -645,7 +645,7 @@
     "sync-registry-schemas": "tsx scripts/generate-registry-types.ts --sync",
     "schemas:ensure": "tsx scripts/schemas-ensure.ts",
     "schema-diff": "tsx scripts/schema-diff.ts",
-    "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts && tsx scripts/generate-inline-enum-arrays.ts && tsx scripts/generate-manifest-derived.ts && tsx scripts/generate-entity-hydration.ts && tsx scripts/generate-media-buy-update-fields.ts && tsx scripts/generate-media-buy-action-metadata.ts",
+    "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts && tsx scripts/generate-targeting-keys.ts && tsx scripts/generate-inline-enum-arrays.ts && tsx scripts/generate-manifest-derived.ts && tsx scripts/generate-entity-hydration.ts && tsx scripts/generate-media-buy-update-fields.ts && tsx scripts/generate-media-buy-action-metadata.ts",
     "generate-manifest-derived": "tsx scripts/generate-manifest-derived.ts",
     "generate-entity-hydration": "tsx scripts/generate-entity-hydration.ts",
     "generate-types:all": "npm run generate-types",