@adcp/sdk 14.0.0 → 14.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. package/dist/lib/adapters/implicit-account-store.d.mts +12 -7
  2. package/dist/lib/adapters/implicit-account-store.d.ts +12 -7
  3. package/dist/lib/adapters/implicit-account-store.js +69 -15
  4. package/dist/lib/adapters/implicit-account-store.mjs +69 -15
  5. package/dist/lib/core/AgentClient.d.mts +1 -0
  6. package/dist/lib/core/AgentClient.d.ts +1 -0
  7. package/dist/lib/core/AgentClient.js +3 -0
  8. package/dist/lib/core/AgentClient.mjs +3 -0
  9. package/dist/lib/core/SingleAgentClient.d.mts +35 -2
  10. package/dist/lib/core/SingleAgentClient.d.ts +35 -2
  11. package/dist/lib/core/SingleAgentClient.js +377 -36
  12. package/dist/lib/core/SingleAgentClient.mjs +387 -38
  13. package/dist/lib/core/TaskExecutor.d.mts +3 -1
  14. package/dist/lib/core/TaskExecutor.d.ts +3 -1
  15. package/dist/lib/core/TaskExecutor.js +17 -12
  16. package/dist/lib/core/TaskExecutor.mjs +17 -12
  17. package/dist/lib/core/account-key.d.mts +3 -0
  18. package/dist/lib/core/account-key.d.ts +3 -0
  19. package/dist/lib/core/account-key.js +41 -0
  20. package/dist/lib/core/account-key.mjs +17 -0
  21. package/dist/lib/core/account-resolution.d.mts +2 -0
  22. package/dist/lib/core/account-resolution.d.ts +2 -0
  23. package/dist/lib/core/buyer-account-registry.d.mts +93 -0
  24. package/dist/lib/core/buyer-account-registry.d.ts +93 -0
  25. package/dist/lib/core/buyer-account-registry.js +602 -0
  26. package/dist/lib/core/buyer-account-registry.mjs +578 -0
  27. package/dist/lib/core/product-cache.d.mts +18 -0
  28. package/dist/lib/core/product-cache.d.ts +18 -0
  29. package/dist/lib/core/product-cache.js +137 -0
  30. package/dist/lib/core/product-cache.mjs +112 -0
  31. package/dist/lib/errors/index.d.mts +40 -1
  32. package/dist/lib/errors/index.d.ts +40 -1
  33. package/dist/lib/errors/index.js +69 -3
  34. package/dist/lib/errors/index.mjs +64 -3
  35. package/dist/lib/governance/authorization.d.mts +17 -1
  36. package/dist/lib/governance/authorization.d.ts +17 -1
  37. package/dist/lib/governance/authorization.js +55 -7
  38. package/dist/lib/governance/authorization.mjs +59 -7
  39. package/dist/lib/governance/index.d.mts +2 -2
  40. package/dist/lib/governance/index.d.ts +2 -2
  41. package/dist/lib/governance/index.js +2 -0
  42. package/dist/lib/governance/index.mjs +3 -1
  43. package/dist/lib/index.d.mts +7 -4
  44. package/dist/lib/index.d.ts +7 -4
  45. package/dist/lib/index.js +29 -0
  46. package/dist/lib/index.mjs +31 -1
  47. package/dist/lib/net/agent-transport-fetch.d.mts +4 -0
  48. package/dist/lib/net/agent-transport-fetch.d.ts +4 -0
  49. package/dist/lib/net/agent-transport-fetch.js +18 -5
  50. package/dist/lib/net/agent-transport-fetch.mjs +17 -5
  51. package/dist/lib/protocols/a2a.js +9 -1
  52. package/dist/lib/protocols/a2a.mjs +9 -1
  53. package/dist/lib/protocols/index.js +9 -2
  54. package/dist/lib/protocols/index.mjs +9 -2
  55. package/dist/lib/protocols/mcp-modern.js +2 -1
  56. package/dist/lib/protocols/mcp-modern.mjs +2 -1
  57. package/dist/lib/protocols/mcp.js +5 -2
  58. package/dist/lib/protocols/mcp.mjs +5 -2
  59. package/dist/lib/protocols/rawResponseCapture.d.mts +6 -0
  60. package/dist/lib/protocols/rawResponseCapture.d.ts +6 -0
  61. package/dist/lib/protocols/rawResponseCapture.js +41 -29
  62. package/dist/lib/protocols/rawResponseCapture.mjs +40 -29
  63. package/dist/lib/protocols/signedRequestRejection.d.mts +9 -0
  64. package/dist/lib/protocols/signedRequestRejection.d.ts +9 -0
  65. package/dist/lib/protocols/signedRequestRejection.js +209 -0
  66. package/dist/lib/protocols/signedRequestRejection.mjs +189 -0
  67. package/dist/lib/protocols/transportDiagnostics.d.mts +1 -0
  68. package/dist/lib/protocols/transportDiagnostics.d.ts +1 -0
  69. package/dist/lib/protocols/transportDiagnostics.js +2 -0
  70. package/dist/lib/protocols/transportDiagnostics.mjs +1 -0
  71. package/dist/lib/registry/types.generated.d.mts +112 -45
  72. package/dist/lib/registry/types.generated.d.ts +112 -45
  73. package/dist/lib/schemas-data/v2.5/_provenance.json +1 -1
  74. package/dist/lib/server/account-provisioning.d.mts +2 -0
  75. package/dist/lib/server/account-provisioning.d.ts +2 -0
  76. package/dist/lib/server/account-provisioning.js +30 -0
  77. package/dist/lib/server/account-provisioning.mjs +6 -0
  78. package/dist/lib/server/account-reference-warnings.d.mts +12 -0
  79. package/dist/lib/server/account-reference-warnings.d.ts +12 -0
  80. package/dist/lib/server/account-reference-warnings.js +48 -0
  81. package/dist/lib/server/account-reference-warnings.mjs +23 -0
  82. package/dist/lib/server/auth-signature.js +1 -0
  83. package/dist/lib/server/auth-signature.mjs +1 -0
  84. package/dist/lib/server/create-adcp-server.d.mts +34 -0
  85. package/dist/lib/server/create-adcp-server.d.ts +34 -0
  86. package/dist/lib/server/create-adcp-server.js +225 -14
  87. package/dist/lib/server/create-adcp-server.mjs +225 -14
  88. package/dist/lib/server/decisioning/account.d.mts +2 -0
  89. package/dist/lib/server/decisioning/account.d.ts +2 -0
  90. package/dist/lib/server/decisioning/runtime/from-platform.js +49 -10
  91. package/dist/lib/server/decisioning/runtime/from-platform.mjs +49 -10
  92. package/dist/lib/server/index.d.mts +2 -2
  93. package/dist/lib/server/index.d.ts +2 -2
  94. package/dist/lib/server/index.js +2 -0
  95. package/dist/lib/server/index.mjs +3 -1
  96. package/dist/lib/signing/agent-resolver/consistency.d.mts +6 -13
  97. package/dist/lib/signing/agent-resolver/consistency.d.ts +6 -13
  98. package/dist/lib/signing/agent-resolver/consistency.js +0 -1
  99. package/dist/lib/signing/agent-resolver/consistency.mjs +0 -1
  100. package/dist/lib/signing/agent-resolver/errors.d.mts +3 -1
  101. package/dist/lib/signing/agent-resolver/errors.d.ts +3 -1
  102. package/dist/lib/signing/agent-resolver/errors.js +6 -0
  103. package/dist/lib/signing/agent-resolver/errors.mjs +6 -0
  104. package/dist/lib/signing/agent-resolver/fetch-helpers.d.mts +11 -0
  105. package/dist/lib/signing/agent-resolver/fetch-helpers.d.ts +11 -0
  106. package/dist/lib/signing/agent-resolver/fetch-helpers.js +37 -2
  107. package/dist/lib/signing/agent-resolver/fetch-helpers.mjs +40 -3
  108. package/dist/lib/signing/agent-resolver/jwks-set.js +24 -3
  109. package/dist/lib/signing/agent-resolver/jwks-set.mjs +24 -3
  110. package/dist/lib/signing/agent-resolver/legacy-brand.d.mts +15 -0
  111. package/dist/lib/signing/agent-resolver/legacy-brand.d.ts +15 -0
  112. package/dist/lib/signing/agent-resolver/legacy-brand.js +60 -0
  113. package/dist/lib/signing/agent-resolver/legacy-brand.mjs +36 -0
  114. package/dist/lib/signing/agent-resolver/operator-authorization.d.mts +13 -0
  115. package/dist/lib/signing/agent-resolver/operator-authorization.d.ts +13 -0
  116. package/dist/lib/signing/agent-resolver/operator-authorization.js +108 -0
  117. package/dist/lib/signing/agent-resolver/operator-authorization.mjs +84 -0
  118. package/dist/lib/signing/agent-resolver/resolve-agent.d.mts +14 -4
  119. package/dist/lib/signing/agent-resolver/resolve-agent.d.ts +14 -4
  120. package/dist/lib/signing/agent-resolver/resolve-agent.js +148 -137
  121. package/dist/lib/signing/agent-resolver/resolve-agent.mjs +157 -139
  122. package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.mts +7 -1
  123. package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.ts +7 -1
  124. package/dist/lib/signing/agent-resolver/resolved-agent-jwks.js +50 -17
  125. package/dist/lib/signing/agent-resolver/resolved-agent-jwks.mjs +50 -17
  126. package/dist/lib/signing/agent-resolver/select-agent.d.mts +14 -15
  127. package/dist/lib/signing/agent-resolver/select-agent.d.ts +14 -15
  128. package/dist/lib/signing/agent-resolver/select-agent.js +98 -13
  129. package/dist/lib/signing/agent-resolver/select-agent.mjs +95 -13
  130. package/dist/lib/signing/brand-jwks.d.mts +29 -75
  131. package/dist/lib/signing/brand-jwks.d.ts +29 -75
  132. package/dist/lib/signing/brand-jwks.js +120 -182
  133. package/dist/lib/signing/brand-jwks.mjs +120 -182
  134. package/dist/lib/signing/errors.d.mts +7 -3
  135. package/dist/lib/signing/errors.d.ts +7 -3
  136. package/dist/lib/signing/errors.js +7 -2
  137. package/dist/lib/signing/errors.mjs +7 -2
  138. package/dist/lib/signing/jwks-https.d.mts +7 -0
  139. package/dist/lib/signing/jwks-https.d.ts +7 -0
  140. package/dist/lib/signing/jwks-https.js +31 -8
  141. package/dist/lib/signing/jwks-https.mjs +31 -8
  142. package/dist/lib/signing/jwks.d.mts +8 -0
  143. package/dist/lib/signing/jwks.d.ts +8 -0
  144. package/dist/lib/signing/middleware.js +2 -1
  145. package/dist/lib/signing/middleware.mjs +2 -1
  146. package/dist/lib/signing/publisher-pins.d.mts +11 -0
  147. package/dist/lib/signing/publisher-pins.d.ts +11 -0
  148. package/dist/lib/signing/publisher-pins.js +125 -0
  149. package/dist/lib/signing/publisher-pins.mjs +101 -0
  150. package/dist/lib/signing/server.d.mts +1 -0
  151. package/dist/lib/signing/server.d.ts +1 -0
  152. package/dist/lib/signing/types.d.mts +5 -0
  153. package/dist/lib/signing/types.d.ts +5 -0
  154. package/dist/lib/signing/verifier.js +50 -5
  155. package/dist/lib/signing/verifier.mjs +50 -5
  156. package/dist/lib/signing/webhook-verifier.d.mts +7 -2
  157. package/dist/lib/signing/webhook-verifier.d.ts +7 -2
  158. package/dist/lib/signing/webhook-verifier.js +42 -2
  159. package/dist/lib/signing/webhook-verifier.mjs +42 -2
  160. package/dist/lib/testing/storyboard/account-policy.d.mts +2 -0
  161. package/dist/lib/testing/storyboard/account-policy.d.ts +2 -0
  162. package/dist/lib/testing/storyboard/account-policy.js +35 -0
  163. package/dist/lib/testing/storyboard/account-policy.mjs +11 -0
  164. package/dist/lib/testing/storyboard/context.js +6 -0
  165. package/dist/lib/testing/storyboard/context.mjs +6 -0
  166. package/dist/lib/testing/storyboard/request-builder.js +12 -2
  167. package/dist/lib/testing/storyboard/request-builder.mjs +12 -2
  168. package/dist/lib/testing/storyboard/runner.js +3 -2
  169. package/dist/lib/testing/storyboard/runner.mjs +3 -2
  170. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  171. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  172. package/dist/lib/types/accept-proposal.d.ts +19 -1
  173. package/dist/lib/types/buy-products.d.ts +19 -1
  174. package/dist/lib/types/check-governance.d.ts +19 -1
  175. package/dist/lib/types/comply-test-controller.d.ts +19 -1
  176. package/dist/lib/types/control-media-buy.d.ts +19 -1
  177. package/dist/lib/types/core.generated.d.mts +14 -1
  178. package/dist/lib/types/core.generated.d.ts +14 -1
  179. package/dist/lib/types/create-media-buy.d.ts +14 -1
  180. package/dist/lib/types/get-media-buys.d.ts +14 -1
  181. package/dist/lib/types/get-products.d.ts +19 -1
  182. package/dist/lib/types/list-products.d.ts +19 -1
  183. package/dist/lib/types/refine-proposals.d.ts +19 -1
  184. package/dist/lib/types/request-proposals.d.ts +19 -1
  185. package/dist/lib/types/schemas.generated.d.ts +12 -3
  186. package/dist/lib/types/schemas.generated.js +4 -1
  187. package/dist/lib/types/schemas.generated.mjs +4 -1
  188. package/dist/lib/types/tools.generated.d.mts +14 -1
  189. package/dist/lib/types/tools.generated.d.ts +14 -1
  190. package/dist/lib/types/update-media-buy.d.ts +14 -1
  191. package/dist/lib/version.d.mts +3 -3
  192. package/dist/lib/version.d.ts +3 -3
  193. package/dist/lib/version.js +3 -3
  194. package/dist/lib/version.mjs +3 -3
  195. package/dist/lib/webhooks/index.d.mts +24 -0
  196. package/dist/lib/webhooks/index.d.ts +24 -0
  197. package/dist/lib/webhooks/index.js +50 -24
  198. package/dist/lib/webhooks/index.mjs +49 -24
  199. package/dist/lib/wholesale-feed-sync/index.d.mts +2 -0
  200. package/dist/lib/wholesale-feed-sync/index.d.ts +2 -0
  201. package/dist/lib/wholesale-feed-sync/index.js +7 -0
  202. package/dist/lib/wholesale-feed-sync/index.mjs +4 -0
  203. package/dist/lib/wholesale-feed-sync/mirror.d.mts +97 -0
  204. package/dist/lib/wholesale-feed-sync/mirror.d.ts +97 -0
  205. package/dist/lib/wholesale-feed-sync/mirror.js +350 -0
  206. package/dist/lib/wholesale-feed-sync/mirror.mjs +322 -0
  207. package/dist/lib/wholesale-feed-sync/sync.d.mts +13 -29
  208. package/dist/lib/wholesale-feed-sync/sync.d.ts +13 -29
  209. package/dist/lib/wholesale-feed-sync/sync.js +208 -281
  210. package/dist/lib/wholesale-feed-sync/sync.mjs +213 -281
  211. package/dist/lib/wholesale-feed-sync/types.d.mts +4 -3
  212. package/dist/lib/wholesale-feed-sync/types.d.ts +4 -3
  213. package/docs/README.md +6 -0
  214. package/docs/TYPE-SUMMARY.md +2 -2
  215. package/docs/guides/BUILD-AN-AGENT.md +2 -2
  216. package/docs/guides/BUYER-QUICKSTART-3.2.md +2 -0
  217. package/docs/guides/BUYER-STORAGE.md +3 -0
  218. package/docs/guides/FIRST-CALL-TO-A-SELLER.md +106 -0
  219. package/docs/guides/SIGNING-GUIDE.md +16 -7
  220. package/docs/guides/account-resolution.md +132 -10
  221. package/docs/llms.txt +3 -2
  222. package/docs/migration-14.0-to-14.1.md +85 -0
  223. package/docs/migration-14.x-rc-worksheet.md +4 -4
  224. package/docs/migration-4.x-to-5.x.md +1 -0
  225. package/docs/migration-agent-resolution-3.3.md +125 -0
  226. package/docs/recipes/verifying-inbound-webhooks.md +60 -15
  227. package/package.json +3 -2
  228. package/skills/adcp-brand.previous/SKILL.md +0 -200
  229. package/skills/adcp-creative.previous/SKILL.md +0 -305
  230. package/skills/adcp-governance.previous/SKILL.md +0 -566
  231. package/skills/adcp-measurement.previous/SKILL.md +0 -136
  232. package/skills/adcp-media-buy.previous/SKILL.md +0 -556
  233. package/skills/adcp-si.previous/SKILL.md +0 -206
  234. package/skills/adcp-signals.previous/SKILL.md +0 -204
@@ -1,566 +0,0 @@
1
- ---
2
- name: adcp-governance
3
- description: Execute AdCP Governance Protocol operations with governance agents - manage property lists, collection lists, content standards, and campaign governance (plans, checks, outcomes, audit trail). Use when users want to create include/exclude lists, set up brand safety rules, validate content delivery, register campaign plans, validate actions against policy, or produce internal/shareable audit trails.
4
- ---
5
-
6
- # AdCP Governance Protocol
7
-
8
- This skill enables you to execute the AdCP Governance Protocol with governance agents. Covers four areas: property lists (site-level targeting), collection lists (program-level targeting), content standards (brand safety rules), and campaign governance (plans, checks, outcomes, audit trail).
9
-
10
- > **Buyer-side basics** — idempotency replay, `oneOf` variants, async `status:'submitted'` polling, error recovery from `adcp_error.issues[]` — live in `skills/call-adcp-agent/SKILL.md`. This skill covers per-task semantics only.
11
-
12
- ## Overview
13
-
14
- The Governance Protocol provides 21 standardized tasks across four areas:
15
-
16
- ### Property Lists
17
- | Task | Purpose | Response Time |
18
- |------|---------|---------------|
19
- | `create_property_list` | Create include/exclude list | ~1s |
20
- | `update_property_list` | Modify list filters/properties | ~1s |
21
- | `get_property_list` | Retrieve list with optional resolution | ~1-5s |
22
- | `list_property_lists` | List all accessible lists | ~1s |
23
- | `delete_property_list` | Delete a list | ~1s |
24
-
25
- ### Collection Lists
26
- | Task | Purpose | Response Time |
27
- |------|---------|---------------|
28
- | `create_collection_list` | Create program-level list | ~1s |
29
- | `update_collection_list` | Modify list | ~1s |
30
- | `get_collection_list` | Retrieve with optional resolution | ~1-5s |
31
- | `list_collection_lists` | List all accessible lists | ~1s |
32
- | `delete_collection_list` | Delete a list | ~1s |
33
-
34
- ### Content Standards
35
- | Task | Purpose | Response Time |
36
- |------|---------|---------------|
37
- | `create_content_standards` | Create brand safety rules | ~1s |
38
- | `get_content_standards` | Retrieve standards by ID | ~1s |
39
- | `update_content_standards` | Modify rules | ~1s |
40
- | `list_content_standards` | List all accessible standards | ~1s |
41
- | `calibrate_content` | Test content against standards | ~5-30s |
42
- | `get_media_buy_artifacts` | Get creatives for compliance review | ~5s |
43
- | `validate_content_delivery` | Audit delivery compliance | ~10-60s |
44
-
45
- ### Campaign Governance
46
- | Task | Purpose | Response Time |
47
- |------|---------|---------------|
48
- | `sync_plans` | Push or update a campaign plan with budget authority and policies | ~1s |
49
- | `check_governance` | Validate an action (intent or execution) against the plan | ~1-5s |
50
- | `report_plan_outcome` | Report a completed action so plan budget state advances | ~1s |
51
- | `get_plan_audit_logs` | Retrieve governance state, budget tracking, and audit trail | ~1-5s |
52
-
53
- > **Experimental in 3.0.** Campaign governance may change between 3.x releases with at least 6 weeks' notice. Sellers MUST declare `governance.campaign` in `experimental_features` to participate. See [experimental status](/docs/reference/experimental-status).
54
-
55
- ## Typical Workflow
56
-
57
- ### Property Lists (site-level)
58
- 1. **Create list**: `create_property_list` with base properties and filters
59
- 2. **Resolve**: `get_property_list` with `resolve: true` to see matched properties
60
- 3. **Refine**: `update_property_list` to adjust filters
61
- 4. **Apply**: Reference `list_id` in `create_media_buy` targeting
62
-
63
- ### Collection Lists (program-level, CTV)
64
- 1. **Create list**: `create_collection_list` with distribution IDs or genre filters
65
- 2. **Resolve**: `get_collection_list` with `resolve: true` to see matched programs
66
- 3. **Apply**: Reference in campaign targeting for CTV brand safety
67
-
68
- ### Content Standards
69
- 1. **Create standards**: `create_content_standards` with rules
70
- 2. **Calibrate**: `calibrate_content` with test samples to validate configuration
71
- 3. **Monitor**: `get_media_buy_artifacts` + `validate_content_delivery` for ongoing compliance
72
-
73
- ### Campaign Governance
74
- 1. **Sync governance agents** to seller accounts via `sync_governance` (lives in the Accounts protocol)
75
- 2. **Register the plan**: `sync_plans` with budget authority, channel allocation, and resolved policy IDs
76
- 3. **Validate actions**: `check_governance` on intent (pre-discovery) and execution (pre-buy). Returns an opaque `governance_context` token the seller echoes on subsequent checks.
77
- 4. **Report outcomes**: `report_plan_outcome` so committed/remaining budget advances
78
- 5. **Audit and produce shareable views**: `get_plan_audit_logs` filtered by `governance_contexts` for the requesting party. See [audit trail: internal vs shareable views](/docs/governance/campaign/audit-trail).
79
-
80
- ---
81
-
82
- ## Task Reference
83
-
84
- ### create_property_list
85
-
86
- Create a property list for brand safety and inventory targeting.
87
-
88
- **Request:**
89
- ```json
90
- {
91
- "name": "Premium News Properties",
92
- "description": "Tier 1 news publishers for brand campaigns",
93
- "base_properties": [
94
- {
95
- "selection_type": "publisher_tags",
96
- "publisher_domain": "publisher.com",
97
- "tags": ["premium", "news"]
98
- }
99
- ],
100
- "filters": {
101
- "countries_all": ["US", "GB"],
102
- "channels_any": ["display", "video"]
103
- },
104
- "brand": {
105
- "domain": "acmecorp.com"
106
- }
107
- }
108
- ```
109
-
110
- **Key fields:**
111
- - `name` (string, required): Human-readable name
112
- - `description` (string, optional): Purpose of the list
113
- - `base_properties` (array, optional): Property sources — `publisher_tags`, `publisher_ids`, or `identifiers`
114
- - `filters` (object, optional): Resolution filters — `countries_all`, `channels_any`, `property_types`, `feature_requirements`, `exclude_identifiers`
115
- - `brand` (object, optional): Brand reference for automatic rule inference
116
-
117
- ---
118
-
119
- ### update_property_list
120
-
121
- Modify an existing property list.
122
-
123
- **Request:**
124
- ```json
125
- {
126
- "list_id": "pl_abc123",
127
- "filters": {
128
- "countries_all": ["US", "GB", "DE"],
129
- "channels_any": ["display", "video", "ctv"]
130
- }
131
- }
132
- ```
133
-
134
- **Key fields:**
135
- - `list_id` (string, required): Property list identifier
136
- - `name`, `description` (string, optional): Update metadata
137
- - `base_properties` (array, optional): Replace property sources
138
- - `filters` (object, optional): Replace filter configuration
139
-
140
- ---
141
-
142
- ### get_property_list
143
-
144
- Retrieve a property list with optional resolution.
145
-
146
- **Request:**
147
- ```json
148
- {
149
- "list_id": "pl_abc123",
150
- "resolve": true,
151
- "max_results": 50
152
- }
153
- ```
154
-
155
- **Key fields:**
156
- - `list_id` (string, required): Property list identifier
157
- - `resolve` (boolean, optional): Resolve filters and return property identifiers (default: false)
158
- - `max_results` (number, optional): Max properties when resolved
159
-
160
- ---
161
-
162
- ### list_property_lists
163
-
164
- List all property lists accessible to the authenticated principal.
165
-
166
- **Request:**
167
- ```json
168
- {
169
- "name_contains": "premium"
170
- }
171
- ```
172
-
173
- **Key fields:**
174
- - `name_contains` (string, optional): Filter by name substring
175
- - `max_results` (number, optional): Max results
176
-
177
- ---
178
-
179
- ### delete_property_list
180
-
181
- Delete a property list.
182
-
183
- **Request:**
184
- ```json
185
- {
186
- "list_id": "pl_abc123"
187
- }
188
- ```
189
-
190
- **Key fields:**
191
- - `list_id` (string, required): Property list identifier to delete
192
-
193
- ---
194
-
195
- ### create_collection_list
196
-
197
- Create a collection list for program-level brand safety (CTV, podcast, streaming).
198
-
199
- **Request:**
200
- ```json
201
- {
202
- "name": "Family-Safe CTV Programs",
203
- "description": "Programs suitable for family brand campaigns",
204
- "base_collections": [
205
- {
206
- "selection_type": "publisher_genres",
207
- "publisher_domain": "ctv-publisher.com",
208
- "genres": ["family", "comedy"],
209
- "genre_taxonomy": "iab_content_taxonomy_3.0"
210
- }
211
- ],
212
- "filters": {
213
- "content_ratings_exclude": [
214
- { "system": "us_tv", "rating": "TV-MA" }
215
- ],
216
- "kinds": ["series"]
217
- },
218
- "brand": {
219
- "domain": "familybrand.com"
220
- }
221
- }
222
- ```
223
-
224
- **Key fields:**
225
- - `name` (string, required): Human-readable name
226
- - `base_collections` (array, optional): Collection sources — `distribution_ids`, `publisher_collections`, or `publisher_genres`
227
- - `filters` (object, optional): `content_ratings_exclude`, `content_ratings_include`, `genres_exclude`, `genres_include`, `kinds`, `production_quality`
228
- - `brand` (object, optional): Brand reference
229
-
230
- **Distribution identifier types:** `imdb_id`, `gracenote_id`, `eidr_id`
231
-
232
- ---
233
-
234
- ### update_collection_list
235
-
236
- Modify an existing collection list.
237
-
238
- **Request:**
239
- ```json
240
- {
241
- "list_id": "cl_abc123",
242
- "filters": {
243
- "content_ratings_exclude": [
244
- { "system": "us_tv", "rating": "TV-MA" },
245
- { "system": "us_tv", "rating": "TV-14" }
246
- ]
247
- }
248
- }
249
- ```
250
-
251
- **Key fields:**
252
- - `list_id` (string, required): Collection list identifier
253
- - `base_collections`, `filters` (optional): Replace configuration
254
-
255
- ---
256
-
257
- ### get_collection_list
258
-
259
- Retrieve a collection list with optional resolution.
260
-
261
- **Request:**
262
- ```json
263
- {
264
- "list_id": "cl_abc123",
265
- "resolve": true
266
- }
267
- ```
268
-
269
- **Key fields:**
270
- - `list_id` (string, required): Collection list identifier
271
- - `resolve` (boolean, optional): Resolve and return collection entries
272
- - `max_results` (number, optional): Max collections when resolved
273
-
274
- ---
275
-
276
- ### list_collection_lists
277
-
278
- List all collection lists accessible to the authenticated principal.
279
-
280
- **Request:**
281
- ```json
282
- {
283
- "name_contains": "family"
284
- }
285
- ```
286
-
287
- ---
288
-
289
- ### delete_collection_list
290
-
291
- Delete a collection list.
292
-
293
- **Request:**
294
- ```json
295
- {
296
- "list_id": "cl_abc123"
297
- }
298
- ```
299
-
300
- ---
301
-
302
- ### create_content_standards
303
-
304
- Create content standards (brand safety rules) for campaign compliance.
305
-
306
- **Request:**
307
- ```json
308
- {
309
- "name": "Automotive Brand Safety",
310
- "description": "Content rules for automotive brand campaigns",
311
- "rules": [
312
- { "rule_type": "category", "action": "block", "value": "violence", "severity": "critical" },
313
- { "rule_type": "category", "action": "block", "value": "adult", "severity": "critical" },
314
- { "rule_type": "keyword", "action": "flag", "value": "accident", "severity": "medium" }
315
- ],
316
- "brand": {
317
- "domain": "automaker.com"
318
- }
319
- }
320
- ```
321
-
322
- **Key fields:**
323
- - `name` (string, required): Human-readable name
324
- - `rules` (array, optional): Content rules — `rule_type`, `action` (allow/block/flag), `value`, `severity`
325
- - `brand` (object, optional): Brand reference for automatic rule inference
326
-
327
- ---
328
-
329
- ### get_content_standards
330
-
331
- Retrieve content standards by ID.
332
-
333
- **Request:**
334
- ```json
335
- {
336
- "standards_id": "cs_abc123"
337
- }
338
- ```
339
-
340
- ---
341
-
342
- ### update_content_standards
343
-
344
- Modify existing content standards.
345
-
346
- **Request:**
347
- ```json
348
- {
349
- "standards_id": "cs_abc123",
350
- "rules": [
351
- { "rule_type": "category", "action": "block", "value": "violence", "severity": "critical" }
352
- ]
353
- }
354
- ```
355
-
356
- ---
357
-
358
- ### list_content_standards
359
-
360
- List all content standards accessible to the authenticated principal.
361
-
362
- **Request:**
363
- ```json
364
- {
365
- "name_contains": "automotive"
366
- }
367
- ```
368
-
369
- ---
370
-
371
- ### calibrate_content
372
-
373
- Test content samples against content standards to validate configuration.
374
-
375
- **Request:**
376
- ```json
377
- {
378
- "standards_id": "cs_abc123",
379
- "samples": [
380
- { "url": "https://example.com/article1", "expected_result": "allow" },
381
- { "url": "https://example.com/article2", "expected_result": "block" },
382
- { "text": "Car crash injures three people", "expected_result": "block" }
383
- ]
384
- }
385
- ```
386
-
387
- **Key fields:**
388
- - `standards_id` (string, required): Content standards to calibrate against
389
- - `samples` (array, required): Content samples with `url` and/or `text`, and optional `expected_result`
390
-
391
- ---
392
-
393
- ### get_media_buy_artifacts
394
-
395
- Get creative artifacts from a media buy for compliance review.
396
-
397
- **Request:**
398
- ```json
399
- {
400
- "media_buy_id": "mb_abc123",
401
- "sales_agent_url": "https://sales.publisher.com"
402
- }
403
- ```
404
-
405
- **Key fields:**
406
- - `media_buy_id` (string, required): Media buy identifier
407
- - `sales_agent_url` (string, required): Sales agent that owns the media buy
408
-
409
- ---
410
-
411
- ### validate_content_delivery
412
-
413
- Validate delivered content against content standards.
414
-
415
- **Request:**
416
- ```json
417
- {
418
- "standards_id": "cs_abc123",
419
- "media_buy_id": "mb_abc123",
420
- "sales_agent_url": "https://sales.publisher.com",
421
- "date_range": {
422
- "start": "2025-01-01",
423
- "end": "2025-01-31"
424
- }
425
- }
426
- ```
427
-
428
- **Key fields:**
429
- - `standards_id` (string, required): Content standards to validate against
430
- - `media_buy_id` (string, required): Media buy identifier
431
- - `sales_agent_url` (string, required): Sales agent URL
432
- - `date_range` (object, optional): Filter by delivery date range
433
-
434
- ---
435
-
436
- ### sync_plans
437
-
438
- Register or update a campaign plan that defines authorized parameters (budget, channels, policies) for an orchestrator's autonomous action.
439
-
440
- **Request:**
441
- ```json
442
- {
443
- "plan_id": "plan_q1_2026_launch",
444
- "plan_version": 1,
445
- "budget": { "authorized": 500000, "currency": "USD" },
446
- "channel_allocation": { "olv": 0.55, "display": 0.30, "audio": 0.15 },
447
- "policies": ["us_coppa", "alcohol_advertising"],
448
- "human_review_required": false
449
- }
450
- ```
451
-
452
- **Key fields:**
453
- - `plan_id` (string, required): Stable plan identifier
454
- - `plan_version` (integer, required): Increment on every modification — checks bind to a version
455
- - `budget.authorized` (number, required): Total spend authority across all governed actions on this plan
456
- - `policies` (array, optional): Registry policy IDs that govern this plan. Inline `custom_policies` may add restrictions but cannot relax registry policies.
457
- - `human_review_required` (boolean, optional): Force human review on all actions. Auto-set true when any resolved policy has `requires_human_review: true`.
458
-
459
- ---
460
-
461
- ### check_governance
462
-
463
- Validate an action against the plan. Called twice in the lifecycle: once on intent (pre-discovery), once on execution (pre-buy). Sellers MUST call execution checks independently using credentials synced via `sync_governance`.
464
-
465
- **Request (execution check):**
466
- ```json
467
- {
468
- "plan_id": "plan_q1_2026_launch",
469
- "plan_version": 1,
470
- "purchase_type": "media_buy",
471
- "tool": "create_media_buy",
472
- "payload": { "...": "the create_media_buy request body" },
473
- "governance_context": "gc_mb_seller_456"
474
- }
475
- ```
476
-
477
- **Key fields:**
478
- - `purchase_type` (enum, required): `media_buy`, `rights_license`, `signal_activation`, or `creative_services`
479
- - `governance_context` (string, optional): Echoed on subsequent checks for the same governed action. The agent issues this on the first check and the buyer attaches it to the action envelope.
480
- - `tool` (string, required): Which AdCP tool is being authorized
481
- - `payload` (object, required): The full request body the orchestrator/seller would otherwise send
482
-
483
- **Response status:** `approved`, `denied`, or `conditions`. On `denied`, read `governance_context.findings[]` to locate the failed rule and correct the payload.
484
-
485
- ---
486
-
487
- ### report_plan_outcome
488
-
489
- Report the result of a governed action so plan budget and state advance.
490
-
491
- **Request:**
492
- ```json
493
- {
494
- "plan_id": "plan_q1_2026_launch",
495
- "governance_context": "gc_mb_seller_456",
496
- "outcome": "completed",
497
- "committed_budget": 150000
498
- }
499
- ```
500
-
501
- **Key fields:**
502
- - `governance_context` (string, required): The token issued on the original check
503
- - `outcome` (enum, required): `completed`, `cancelled`, `failed`, or `delivery` (for ongoing pacing reports)
504
- - `committed_budget` (number, required for `completed`): Net budget committed by this action
505
-
506
- ---
507
-
508
- ### get_plan_audit_logs
509
-
510
- Retrieve governance state, budget tracking, and audit trail for one or more plans.
511
-
512
- **Request:**
513
- ```json
514
- {
515
- "plan_ids": ["plan_q1_2026_launch"],
516
- "governance_contexts": ["gc_mb_seller_456"],
517
- "include_entries": true
518
- }
519
- ```
520
-
521
- **Key fields:**
522
- - `plan_ids` / `portfolio_plan_ids` / `governance_contexts` (at least one required): Scope the query
523
- - `include_entries` (boolean, optional): Return the full audit trail. Default `false` returns summary only.
524
-
525
- **Producing a shareable view:** filter `governance_contexts` to the requesting party's actions and strip plan-level aggregates (`budget.*`, `channel_allocation.*`, `summary.drift_metrics`) before forwarding. See [audit trail: internal vs shareable views](/docs/governance/campaign/audit-trail).
526
-
527
- ---
528
-
529
- ## Key Concepts
530
-
531
- ### Property Lists vs Collection Lists
532
-
533
- - **Property Lists**: Site-level targeting. Operates on publisher domains and properties (websites, apps, CTV apps). Use for "where" the ad appears.
534
- - **Collection Lists**: Program-level targeting. Operates on shows, series, and content programs using distribution identifiers (IMDb, Gracenote, EIDR). Use for "what content" the ad appears alongside (primarily CTV).
535
-
536
- ### Content Standards vs Property/Collection Lists
537
-
538
- - **Content Standards**: Rules-based evaluation of content quality, topics, and safety. Evaluates content dynamically.
539
- - **Property/Collection Lists**: Pre-computed sets of approved or excluded inventory. Static targeting applied at campaign setup.
540
-
541
- ### Filter Resolution
542
-
543
- Property and collection lists combine static selections with dynamic filters. Use `resolve: true` on get operations to see the final resolved set of properties or collections.
544
-
545
- ### Three invariants for audit and disclosure decisions
546
-
547
- These three properties of campaign governance shape what an orchestrator can disclose, can rely on a counterparty having, and cannot work around. Surface them when audit-trail design or counterparty disclosure decisions come up.
548
-
549
- 1. **Inline policies are additive-only over registry policies.** A buyer's bespoke `custom_policies` (or inline `policy` entries on a plan) may add restrictions on top of registry-sourced policies. They MUST NOT relax, override, or disable registry policies. Counterparties who see `policies_evaluated: ["us_coppa"]` can trust the registry version of `us_coppa` was applied at its declared `enforcement` level.
550
- 2. **`governance_context` is the seller-visible correlation token; full plan/budget data is buyer-side.** The seller sees the opaque token they were issued and the entries scoped to it. Plan-level totals (`budget.authorized`, `channel_allocation`, `drift_metrics`) belong to the buyer's internal view and are never shared by default.
551
- 3. **`plan_hash` is the cryptographic attestation surface.** `base64url_no_pad(SHA-256(JCS(plan_payload)))` over the plan revision the check evaluated. Any party with the plan revision can recompute and byte-compare. This is what makes a four-field shareable attestation (`governance_context`, `status`, `plan_hash`, `policies_evaluated`) cryptographically meaningful — counterparties don't have to trust the buyer's summary.
552
-
553
- > A related working-group adoption pattern — `effective_date` enabling informational-before-enforcement of new policies — lives in [Policy Registry](/docs/governance/policy-registry); it shapes registry rollout rather than per-check disclosure decisions.
554
-
555
- ---
556
-
557
- ## Error Handling
558
-
559
- Common error codes:
560
-
561
- - `LIST_NOT_FOUND`: Invalid list_id
562
- - `STANDARDS_NOT_FOUND`: Invalid standards_id
563
- - `UNAUTHORIZED`: Not authorized to access this resource
564
- - `VALIDATION_ERROR`: Invalid filter or rule configuration
565
- - `PLAN_NOT_FOUND`: No plan with this ID, or the principal is not authorized for it. Returned indistinguishably from the unauthorized case to prevent plan-ID enumeration.
566
- - `GOVERNANCE_DENIED`: `check_governance` rejected the action. Read `governance_context.findings[]` to identify the failed rule, correct the payload, and retry.
@@ -1,136 +0,0 @@
1
- ---
2
- name: adcp-measurement
3
- description: Operate as or integrate with an AdCP measurement agent through a buyer-controlled orchestrator gateway - publish a metric catalog, receive authorized cross-seller delivery, and return compact feedback for orchestrator-controlled seller fan-out. Use when connecting measurement providers or routing provider results into seller optimization.
4
- ---
5
-
6
- # AdCP Measurement Agents
7
-
8
- Measurement agents are first-class provider identities without requiring AdCP to become a universal measurement-data transport.
9
-
10
- > **Calling basics** — authentication, idempotency, error recovery, and account resolution live in `skills/call-adcp-agent/SKILL.md`. This skill covers measurement-specific semantics.
11
-
12
- ## Role
13
-
14
- A measurement agent can:
15
-
16
- 1. publish the metrics it computes through `get_adcp_capabilities.measurement.metrics[]`;
17
- 2. declare `measurement.produces_performance_feedback: true` when it produces optimizer-ready assertions;
18
- 3. obtain buyer-approved data from an orchestrator through its `get_media_buy_delivery` task; and
19
- 4. return compact assertions through its `provide_performance_feedback` task, after which the orchestrator decides what to send to each seller.
20
-
21
- The measurement agent never needs seller credentials. The orchestrator controls cohort consistency, seller-ID mapping, normalization, and disclosure. `report_usage` is a vendor-service consumption and billing task, not general measurement interchange.
22
-
23
- ## Discovery
24
-
25
- Publish an agent entry with `type: "measurement"` in the provider's `brand.json`. The agent's `get_adcp_capabilities` response includes:
26
-
27
- ```json
28
- {
29
- "supported_protocols": ["measurement"],
30
- "experimental_features": ["measurement.core"],
31
- "measurement": {
32
- "produces_performance_feedback": true,
33
- "metrics": [
34
- {
35
- "metric_id": "incremental_revenue_index",
36
- "unit": "index",
37
- "description": "Incremental revenue relative to a buyer-defined control.",
38
- "methodology_url": "https://measurement.example/methodology",
39
- "methodology_version": "2026-08"
40
- }
41
- ]
42
- }
43
- }
44
- ```
45
-
46
- Metric identity is `(provider BrandRef, metric_id)`. Do not assume vendor metric IDs are globally unique.
47
-
48
- The first experimental gateway tier fixes the interchange tasks rather than negotiating method arrays.
49
-
50
- ## Orchestrator gateway and authorization
51
-
52
- The buyer orchestrator's experimental `measurement_gateway` capability means it exposes the task boundary; it does not grant access by itself. The orchestrator provisions the provider on an orchestrator account. Sellers are not part of this provider authorization.
53
-
54
- The provider's authenticated principal receives the two first-tier gateway tasks on its orchestrator account:
55
-
56
- ```json
57
- {
58
- "allowed_tasks": ["get_media_buy_delivery", "provide_performance_feedback"],
59
- "read_only": false
60
- }
61
- ```
62
-
63
- Use an orchestrator-defined `custom:` scope name if desired. The task list is normative; the custom name is not.
64
-
65
- Webhook and offline interchange are not part of this tier; they require explicit registration, credentials, payload, and receipt contracts before they can be advertised as interoperable AdCP paths.
66
-
67
- The orchestrator exposes measurement-facing media-buy, package, and creative IDs to the provider and retains their mapping to every seller-local ID.
68
-
69
- ## Producing feedback
70
-
71
- Submit one assertion per task call:
72
-
73
- ```json
74
- {
75
- "idempotency_key": "f7a3e291-4c58-4d6b-9012-a3e9b27c5f08",
76
- "media_buy_id": "mb_123",
77
- "package_id": "pkg_video",
78
- "measurement_period": {
79
- "start": "2026-07-01T00:00:00Z",
80
- "end": "2026-07-31T23:59:59Z"
81
- },
82
- "metric": {
83
- "scope": "vendor",
84
- "vendor": { "domain": "measurement.example" },
85
- "metric_id": "incremental_revenue_index"
86
- },
87
- "performance_index": 1.35,
88
- "baseline": "control_group",
89
- "producer": { "domain": "measurement.example" },
90
- "methodology": "geo_incrementality",
91
- "methodology_version": "2026-08",
92
- "study_ref": "study_42",
93
- "evidence_ref": "https://measurement.example/results/study_42",
94
- "final": true
95
- }
96
- ```
97
-
98
- Rules:
99
-
100
- - `1.0` equals the named baseline. Compact-contract producers (baseline present) MUST use observed/baseline for higher-is-better ratios and baseline/observed for lower-is-better ratios such as CPA.
101
- - `producer` must match authenticated provider identity at the orchestrator gateway.
102
- - `study_ref` is correlation only; it never asks a seller to construct experiment arms.
103
- - Keep raw logs, model coefficients, identity paths, and full study datasets outside the feedback payload.
104
- - A revision is a new assertion with a fresh idempotency key and `supersedes_feedback_id` from the earlier receipt.
105
-
106
- ## Reading receipts
107
-
108
- ```json
109
- {
110
- "status": "completed",
111
- "success": true,
112
- "feedback_id": "fb_01J5Y5KQ2T8B2M8P0A4E6R3C9D",
113
- "application_status": "accepted",
114
- "received_at": "2026-08-04T12:00:02Z"
115
- }
116
- ```
117
-
118
- - A gateway receipt identifies the assertion stored by the orchestrator. It should normally report `accepted`; it is not proof that any seller used the signal.
119
- - Each seller returns a separate receipt to the orchestrator. A seller's `applied` means the signal entered that seller's optimizer inputs.
120
- - `not_applied` means the receiving endpoint evaluated but did not incorporate the assertion; inspect `status_reason`.
121
-
122
- Do not claim causal delivery impact from `applied`. It means the seller consumed the signal, not that the signal caused a specific bid or allocation change.
123
-
124
- ## End-to-end flow
125
-
126
- ### 1. Orchestrator supplies data
127
-
128
- The provider calls the orchestrator's `get_media_buy_delivery` task for buyer-approved data. The orchestrator applies the same user or geographic cohort definition across sellers before measurement.
129
-
130
- ### 2. Provider returns feedback
131
-
132
- The provider calls the orchestrator gateway's `provide_performance_feedback` task. Authenticated provider identity binds `producer`; raw logs, model coefficients, and identity paths remain outside the payload.
133
-
134
- ### 3. Orchestrator fans out
135
-
136
- The orchestrator validates and normalizes the result, chooses what each seller should receive, maps to seller-local IDs, and calls each seller's `provide_performance_feedback` under the buyer's identity. It retains the mapping between provider and seller receipts for audit.