@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.23

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 (223) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/adapters/version/index.d.mts +1 -1
  3. package/dist/lib/adapters/version/index.d.ts +1 -1
  4. package/dist/lib/adapters/version/index.js +2 -0
  5. package/dist/lib/adapters/version/index.mjs +2 -0
  6. package/dist/lib/adapters/version/negotiate.d.mts +13 -0
  7. package/dist/lib/adapters/version/negotiate.d.ts +13 -0
  8. package/dist/lib/adapters/version/negotiate.js +6 -0
  9. package/dist/lib/adapters/version/negotiate.mjs +5 -0
  10. package/dist/lib/client/core.d.mts +4 -0
  11. package/dist/lib/client/core.d.ts +4 -0
  12. package/dist/lib/client/core.js +13 -0
  13. package/dist/lib/client/core.mjs +12 -0
  14. package/dist/lib/conformance/property-lists.d.mts +1 -1
  15. package/dist/lib/conformance/property-lists.d.ts +1 -1
  16. package/dist/lib/conformance/property-lists.js +1 -1
  17. package/dist/lib/conformance/property-lists.mjs +1 -1
  18. package/dist/lib/core/SingleAgentClient.d.mts +23 -1
  19. package/dist/lib/core/SingleAgentClient.d.ts +23 -1
  20. package/dist/lib/core/SingleAgentClient.js +102 -18
  21. package/dist/lib/core/SingleAgentClient.mjs +108 -18
  22. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  23. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  24. package/dist/lib/core/targeting-helpers.js +412 -0
  25. package/dist/lib/core/targeting-helpers.mjs +370 -0
  26. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  27. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  28. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  29. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  30. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  31. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  32. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  33. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  34. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  35. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  36. package/dist/lib/entrypoints/discovery.js +72 -0
  37. package/dist/lib/entrypoints/discovery.mjs +56 -0
  38. package/dist/lib/entrypoints/errors.d.mts +11 -0
  39. package/dist/lib/entrypoints/errors.d.ts +11 -0
  40. package/dist/lib/entrypoints/errors.js +159 -0
  41. package/dist/lib/entrypoints/errors.mjs +132 -0
  42. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  43. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  44. package/dist/lib/entrypoints/media-buy.js +119 -0
  45. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  46. package/dist/lib/entrypoints/registry.d.mts +5 -0
  47. package/dist/lib/entrypoints/registry.d.ts +5 -0
  48. package/dist/lib/entrypoints/registry.js +61 -0
  49. package/dist/lib/entrypoints/registry.mjs +40 -0
  50. package/dist/lib/entrypoints/utils.d.mts +7 -0
  51. package/dist/lib/entrypoints/utils.d.ts +7 -0
  52. package/dist/lib/entrypoints/utils.js +100 -0
  53. package/dist/lib/entrypoints/utils.mjs +72 -0
  54. package/dist/lib/entrypoints/version.d.mts +3 -0
  55. package/dist/lib/entrypoints/version.d.ts +3 -0
  56. package/dist/lib/entrypoints/version.js +57 -0
  57. package/dist/lib/entrypoints/version.mjs +36 -0
  58. package/dist/lib/index.d.mts +1 -1
  59. package/dist/lib/index.d.ts +1 -1
  60. package/dist/lib/media-buy/action-contracts.js +3 -3
  61. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  62. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  63. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  64. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  65. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  66. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  67. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  68. package/dist/lib/media-buy/valid-actions.js +42 -0
  69. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  70. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  71. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  72. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  73. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  74. package/dist/lib/protocols/mcp-modern.js +20 -4
  75. package/dist/lib/protocols/mcp-modern.mjs +20 -4
  76. package/dist/lib/registry/types.generated.d.ts +224 -3
  77. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  78. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  79. package/dist/lib/reporting/ledger/index.js +3 -1
  80. package/dist/lib/reporting/ledger/index.mjs +1 -0
  81. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  82. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  83. package/dist/lib/reporting/ledger/instant.js +10 -0
  84. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  85. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  86. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  87. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  88. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  89. package/dist/lib/reporting/service/index.d.mts +36 -1
  90. package/dist/lib/reporting/service/index.d.ts +36 -1
  91. package/dist/lib/reporting/service/index.js +51 -1
  92. package/dist/lib/reporting/service/index.mjs +52 -2
  93. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  94. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  95. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  96. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  97. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  98. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  99. package/dist/lib/server/capabilities-release-projection.js +128 -0
  100. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  101. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  102. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  103. package/dist/lib/server/create-adcp-server.js +97 -24
  104. package/dist/lib/server/create-adcp-server.mjs +108 -23
  105. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  106. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  107. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  108. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  109. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  110. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  111. package/dist/lib/server/declared-input-schema.js +167 -0
  112. package/dist/lib/server/declared-input-schema.mjs +137 -0
  113. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  114. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  115. package/dist/lib/server/envelope-allowlist.js +3 -79
  116. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  117. package/dist/lib/server/errors.d.mts +1 -186
  118. package/dist/lib/server/errors.d.ts +1 -186
  119. package/dist/lib/server/errors.js +3 -98
  120. package/dist/lib/server/errors.mjs +1 -94
  121. package/dist/lib/server/index.d.mts +1 -1
  122. package/dist/lib/server/index.d.ts +1 -1
  123. package/dist/lib/server/mcp-modern-server.js +21 -4
  124. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  125. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  126. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  127. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  128. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  129. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  130. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  131. package/dist/lib/server/media-buy-helpers.js +3 -23
  132. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  133. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  134. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  135. package/dist/lib/server/pick-safe-details.js +3 -61
  136. package/dist/lib/server/pick-safe-details.mjs +1 -56
  137. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  138. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  139. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  140. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  141. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  142. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  143. package/dist/lib/server/targeting-helpers.js +3 -393
  144. package/dist/lib/server/targeting-helpers.mjs +1 -370
  145. package/dist/lib/server/test-controller.js +7 -3
  146. package/dist/lib/server/test-controller.mjs +7 -3
  147. package/dist/lib/storage/memory-ledger.js +219 -1
  148. package/dist/lib/storage/memory-ledger.mjs +223 -1
  149. package/dist/lib/testing/client.js +26 -5
  150. package/dist/lib/testing/client.mjs +24 -5
  151. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  152. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  153. package/dist/lib/testing/comply-controller.js +7 -2
  154. package/dist/lib/testing/comply-controller.mjs +7 -2
  155. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  156. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  157. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  158. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  159. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  160. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  161. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  162. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  163. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  164. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  165. package/dist/lib/testing/storyboard/runner.js +4 -4
  166. package/dist/lib/testing/storyboard/runner.mjs +4 -4
  167. package/dist/lib/testing/storyboard/task-map.js +4 -1
  168. package/dist/lib/testing/storyboard/task-map.mjs +4 -1
  169. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  170. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  171. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  172. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  173. package/dist/lib/utils/adcp-error-response.js +118 -0
  174. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  175. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  176. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  177. package/dist/lib/utils/capabilities.d.mts +6 -0
  178. package/dist/lib/utils/capabilities.d.ts +6 -0
  179. package/dist/lib/utils/capabilities.js +6 -2
  180. package/dist/lib/utils/capabilities.mjs +6 -2
  181. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  182. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  183. package/dist/lib/utils/envelope-allowlist.js +98 -0
  184. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  185. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  186. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  187. package/dist/lib/utils/pick-safe-details.js +80 -0
  188. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  189. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  190. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  191. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  192. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  193. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  194. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  195. package/dist/lib/v2/projection/index.d.mts +2 -2
  196. package/dist/lib/v2/projection/index.d.ts +2 -2
  197. package/dist/lib/v2/projection/index.js +4 -0
  198. package/dist/lib/v2/projection/index.mjs +5 -1
  199. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  200. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  201. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  202. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  203. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  204. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  205. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  206. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  207. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  208. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  209. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  210. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  211. package/dist/lib/version.d.mts +3 -3
  212. package/dist/lib/version.d.ts +3 -3
  213. package/dist/lib/version.js +3 -3
  214. package/dist/lib/version.mjs +3 -3
  215. package/docs/TYPE-SUMMARY.md +2 -2
  216. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  217. package/docs/guides/REPORTING-LEDGER.md +121 -0
  218. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  219. package/docs/llms.txt +2 -2
  220. package/docs/migration-14.x-rc-worksheet.md +4 -4
  221. package/docs/migration-16-to-17.md +149 -0
  222. package/docs/migration-reporting-storage-package.md +10 -0
  223. package/package.json +106 -1
@@ -50,6 +50,7 @@ var import_adcp = require('../types/adcp.js');
50
50
  var import_version = require('../version.js');
51
51
  var import_adcp_version_config = require('../utils/adcp-version-config.js');
52
52
  var import_reporting_version = require('../media-buy/reporting-version.js');
53
+ var import_creative_start_policy = require('../media-buy/creative-start-policy.js');
53
54
  var import_version2 = require('../adapters/version/index.js');
54
55
  var import_schema_loader2 = require('../validation/schema-loader.js');
55
56
  var import_idempotency = require('../utils/idempotency.js');
@@ -90,7 +91,7 @@ var import_global_async_local_storage = require('../utils/global-async-local-sto
90
91
  var import_validate_user_agent = require('../utils/validate-user-agent.js');
91
92
  var import_webhook_url = require('./webhook-url.js');
92
93
  var import_property_policy = require('../media-buy/property-policy.js');
93
- var import_targeting_helpers = require('../server/targeting-helpers.js');
94
+ var import_targeting_helpers = require('./targeting-helpers.js');
94
95
  var import_creative_delivery = require('../v2/projection/creative-delivery.js');
95
96
  var import_legacy_routes = require('../v2/projection/legacy-routes.js');
96
97
  var import_catalog_snapshot = require('../v2/projection/catalog-snapshot.js');
@@ -3742,6 +3743,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
3742
3743
  serverVersion,
3743
3744
  negotiatedRelease
3744
3745
  );
3746
+ this.assertCreativeStartPolicyDeclared(
3747
+ taskType,
3748
+ normalizedParams,
3749
+ capabilityDiscoveryContext.capabilities,
3750
+ negotiatedRelease?.version ?? options?.wireAdcpVersion ?? this.getWireAdcpVersion()
3751
+ );
3745
3752
  const { options: webhookOptions, driftLog: webhookDriftLog } = this.suppressPre31DiscoveryWebhook(
3746
3753
  taskType,
3747
3754
  options,
@@ -5547,11 +5554,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5547
5554
  if (hasCreativeFormatData) {
5548
5555
  this.validateBeforeCreativeCapabilityProbe("create_media_buy", params, taskOptions);
5549
5556
  }
5557
+ const wireRelease = {};
5550
5558
  const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
5551
5559
  "create_media_buy",
5552
5560
  taskOptions,
5553
5561
  true,
5554
- () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options)
5562
+ () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options),
5563
+ wireRelease
5555
5564
  ) : "canonical";
5556
5565
  const wireParams = params;
5557
5566
  const result = await this.executeAndHandle(
@@ -5564,7 +5573,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5564
5573
  "create_media_buy",
5565
5574
  effectiveLegacyFormatConverter,
5566
5575
  effectiveCanonicalFormatLegacyResolver,
5567
- creativeFormatProjection?.legacyFormatDefinitions
5576
+ creativeFormatProjection?.legacyFormatDefinitions,
5577
+ wireRelease.formatOptionRefs === true
5568
5578
  ),
5569
5579
  "create_media_buy",
5570
5580
  wireMode,
@@ -5650,11 +5660,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5650
5660
  if (hasCreativeFormatData) {
5651
5661
  this.validateBeforeCreativeCapabilityProbe("update_media_buy", params, taskOptions);
5652
5662
  }
5663
+ const wireRelease = {};
5653
5664
  const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
5654
5665
  "update_media_buy",
5655
5666
  taskOptions,
5656
5667
  true,
5657
- () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options)
5668
+ () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options),
5669
+ wireRelease
5658
5670
  ) : "canonical";
5659
5671
  const result = await this.executeAndHandle(
5660
5672
  "update_media_buy",
@@ -5666,7 +5678,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5666
5678
  "update_media_buy",
5667
5679
  effectiveLegacyFormatConverter,
5668
5680
  effectiveCanonicalFormatLegacyResolver,
5669
- creativeFormatProjection?.legacyFormatDefinitions
5681
+ creativeFormatProjection?.legacyFormatDefinitions,
5682
+ wireRelease.formatOptionRefs === true
5670
5683
  ),
5671
5684
  "update_media_buy",
5672
5685
  wireMode,
@@ -5822,7 +5835,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5822
5835
  async resolveCreativeFormatWireMode(taskType, options) {
5823
5836
  return this.resolveCreativeWireMode(taskType, options, true);
5824
5837
  }
5825
- async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions) {
5838
+ async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions, releaseContext) {
5826
5839
  const discoveryContext = {};
5827
5840
  const capabilities = await this.getCapabilities({
5828
5841
  ...options,
@@ -5832,6 +5845,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5832
5845
  const toolSchemas = discoveryContext.toolSchemas ?? (usesScopedFetch ? void 0 : this.cachedToolSchemas);
5833
5846
  const wireRelease = this.config.wireAdcpVersion ?? this.resolvedAdcpVersion;
5834
5847
  const declared = (0, import_creative_delivery.resolveCreativeFormatWireMode)(capabilities, wireRelease);
5848
+ if (releaseContext) {
5849
+ releaseContext.formatOptionRefs = (0, import_creative_delivery.releaseCarriesPackageFormatOptionRefs)(capabilities, wireRelease);
5850
+ }
5835
5851
  const document = toolSchemas && toolInputSchemasByProperties.get(toolSchemas)?.get(taskType);
5836
5852
  const { creativeSchemaSupport } = await import("./creative-schema-support.js");
5837
5853
  (0, import_abort2.throwIfAborted)(options?.signal);
@@ -5850,7 +5866,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5850
5866
  if (resolved === "unknown" && canonicalRequiredByBuyerPin) {
5851
5867
  if (canRediscover && !usesScopedFetch && this.normalizedAgent.protocol === "mcp" && this.capabilitiesFromSharedCache && toolSchemas?.has(taskType) && !toolInputSchemasByProperties.has(toolSchemas)) {
5852
5868
  await this.invalidateDiscoveryCache(options);
5853
- return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions);
5869
+ return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions, releaseContext);
5854
5870
  }
5855
5871
  throw new import_creative_delivery.CreativeFormatCapabilityError(
5856
5872
  `Cannot prove which AdCP release the seller serves for ${taskType}; a 3.2+ client will not guess a legacy creative wire shape`
@@ -6695,12 +6711,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
6695
6711
  const scopeKey = this.config._reuseConfiguredDiscovery?.() ? this.getCapabilityEvidenceScope().scopeKey : void 0;
6696
6712
  const agent = await this.ensureEndpointDiscovered(options);
6697
6713
  this.executor.validateRequest("get_adcp_capabilities", params);
6698
- const result = await this.executor.executeTask(
6714
+ const result = await this.executeCapabilityDiscovery(
6699
6715
  agent,
6700
- "get_adcp_capabilities",
6701
6716
  params,
6702
6717
  inputHandler,
6703
- options
6718
+ options,
6719
+ options.versionEnvelope ?? this.config.versionEnvelope
6704
6720
  );
6705
6721
  if (this.config._reuseConfiguredDiscovery?.() && !this.usesScopedDiscoveryTransport(options) && scopeKey === this.getCapabilityEvidenceScope().scopeKey && Object.keys(params).length === 0 && this.runAgentInfo !== void 0 && result.success && result.data && (0, import_capabilities.looksLikeV3Capabilities)(result.data)) {
6706
6722
  const capabilities = (0, import_capabilities.parseCapabilitiesResponse)(structuredClone(result.data));
@@ -6710,6 +6726,42 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
6710
6726
  }
6711
6727
  return result;
6712
6728
  }
6729
+ /**
6730
+ * Dispatch `get_adcp_capabilities` under the discovery version rule.
6731
+ *
6732
+ * A preview pin goes out unpinned (see {@link capabilityDiscoveryEnvelope}),
6733
+ * and a pinned discovery the seller refuses with `VERSION_UNSUPPORTED` is
6734
+ * retried once unpinned. Neither applies when the caller chose the pin, with
6735
+ * version fields in `params` or an `explicitEnvelope`: the seller's refusal,
6736
+ * carrying its `supported_versions` in `adcpError.details`, is the answer.
6737
+ * A caller `operationId` also skips the retry, which would need an id of its
6738
+ * own. Only a successful retry replaces the pinned refusal, whose diagnostics
6739
+ * name the release actually sent.
6740
+ */
6741
+ async executeCapabilityDiscovery(agent, params, inputHandler, options, explicitEnvelope) {
6742
+ const requested = params;
6743
+ const callerPinned = explicitEnvelope !== void 0 || requested.adcp_version !== void 0 || requested.adcp_major_version !== void 0;
6744
+ const envelope = (0, import_version2.capabilityDiscoveryEnvelope)(
6745
+ explicitEnvelope,
6746
+ options.wireAdcpVersion ?? this.config.wireAdcpVersion ?? this.resolvedAdcpVersion
6747
+ );
6748
+ const result = await this.executor.executeTask(
6749
+ agent,
6750
+ "get_adcp_capabilities",
6751
+ params,
6752
+ inputHandler,
6753
+ envelope === void 0 ? options : { ...options, versionEnvelope: envelope }
6754
+ );
6755
+ if (callerPinned || envelope === "none" || options.operationId !== void 0 || result.success || result.adcpError?.code !== "VERSION_UNSUPPORTED") {
6756
+ return result;
6757
+ }
6758
+ (0, import_abort2.throwIfAborted)(options.signal);
6759
+ const unpinned = await this.executor.executeTask(agent, "get_adcp_capabilities", params, inputHandler, {
6760
+ ...(0, import_task_deadline.childTaskOptions)(options),
6761
+ versionEnvelope: "none"
6762
+ });
6763
+ return unpinned.success ? unpinned : result;
6764
+ }
6713
6765
  // ====== CREATIVE BUILD TASKS ======
6714
6766
  /**
6715
6767
  * Build a creative through the legacy named-format protocol.
@@ -7338,6 +7390,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
7338
7390
  serverVersion,
7339
7391
  negotiatedRelease
7340
7392
  );
7393
+ this.assertCreativeStartPolicyDeclared(
7394
+ taskName,
7395
+ normalizedParams,
7396
+ capabilityDiscoveryContext.capabilities,
7397
+ negotiatedRelease?.version ?? options?.wireAdcpVersion ?? this.getWireAdcpVersion()
7398
+ );
7341
7399
  const { options: webhookOptions, driftLog: webhookDriftLog } = this.suppressPre31DiscoveryWebhook(
7342
7400
  taskName,
7343
7401
  options,
@@ -8239,15 +8297,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
8239
8297
  try {
8240
8298
  const agent = await this.ensureEndpointDiscovered(options);
8241
8299
  const callerOptions = options;
8242
- const isPreview = !!(0, import_version2.parseAdcpRelease)(this.resolvedAdcpVersion)?.prerelease;
8300
+ const isPreview = (0, import_version2.capabilityDiscoveryEnvelope)(void 0, this.config.wireAdcpVersion ?? this.resolvedAdcpVersion) === "none";
8243
8301
  const probeOptions = {
8244
8302
  // Discover the seller's release window before claiming a preview
8245
8303
  // older sellers may reject. Ordinary calls still negotiate exact
8246
8304
  // preview evidence or a maintained stable downgrade afterwards.
8247
- ...isPreview && {
8248
- versionEnvelope: callerOptions?.versionEnvelope ?? this.config.versionEnvelope ?? "none",
8249
- disableWebhook: true
8250
- },
8305
+ ...isPreview && { disableWebhook: true },
8251
8306
  ...options?.signal !== void 0 && { signal: options.signal },
8252
8307
  ...options?.transport !== void 0 && { transport: options.transport },
8253
8308
  ...callerOptions?.disableWebhook !== void 0 && !isPreview && {
@@ -8257,12 +8312,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
8257
8312
  delegatedOperatorAuthorization: { ...callerOptions.delegatedOperatorAuthorization }
8258
8313
  }
8259
8314
  };
8260
- const result = await this.executor.executeTask(
8315
+ const result = await this.executeCapabilityDiscovery(
8261
8316
  agent,
8262
- "get_adcp_capabilities",
8263
8317
  {},
8264
8318
  void 0,
8265
- probeOptions
8319
+ probeOptions,
8320
+ // The operation's own envelope steers only a preview probe; a stable
8321
+ // probe keeps the client's configured envelope.
8322
+ (isPreview ? callerOptions?.versionEnvelope : void 0) ?? this.config.versionEnvelope
8266
8323
  );
8267
8324
  (0, import_abort2.throwIfAborted)(options?.signal);
8268
8325
  const requestTimeoutMs = (0, import_abort2.resolveRequestTimeoutMs)(
@@ -9079,6 +9136,33 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
9079
9136
  }
9080
9137
  };
9081
9138
  }
9139
+ /**
9140
+ * AdCP 3.3: buyers MUST NOT send `packages[].start_requires_all_creatives_approved:
9141
+ * true` on `control_media_buy` to a seller that does not declare
9142
+ * `media_buy.features.creative_start_policy: true` (#3649). Refuses only when
9143
+ * discovery is authoritative; with synthetic or missing capabilities the
9144
+ * request is sent and the seller decides. `false`, omission and calls below
9145
+ * 3.3 are unaffected. The vocabulary matches the seller's own refusal.
9146
+ */
9147
+ assertCreativeStartPolicyDeclared(taskName, params, capabilities, targetVersion) {
9148
+ if (taskName !== "control_media_buy") return;
9149
+ const fields = (0, import_creative_start_policy.creativeStartPolicyOptInFields)(params);
9150
+ if (fields.length === 0 || capabilities?._synthetic !== false) return;
9151
+ if (!(0, import_adcp_version_config.isAdcpVersionAtLeast)(targetVersion, "3.3.0-beta.0")) return;
9152
+ if ((0, import_capabilities.resolveFeature)(capabilities, "creative_start_policy")) return;
9153
+ const suggestion = `Omit ${import_creative_start_policy.CREATIVE_START_POLICY_FIELD} or send false; check ${import_creative_start_policy.CREATIVE_START_POLICY_FEATURE} in get_adcp_capabilities before opting in.`;
9154
+ throw new import_errors.ProtocolFeatureUnsupportedError(
9155
+ ["creative_start_policy"],
9156
+ (0, import_capabilities.listDeclaredFeatures)(capabilities),
9157
+ this.agent.agent_uri,
9158
+ {
9159
+ message: `${taskName} ${fields.join(", ")}: true ${fields.length === 1 ? "requires" : "require"} ${import_creative_start_policy.CREATIVE_START_POLICY_FEATURE}, which this seller does not declare. No request was sent. ${suggestion}`,
9160
+ field: fields[0],
9161
+ suggestion,
9162
+ details: { feature: import_creative_start_policy.CREATIVE_START_POLICY_FEATURE, fields }
9163
+ }
9164
+ );
9165
+ }
9082
9166
  /**
9083
9167
  * Reject shape-changing 3.1 requests after seller capability discovery.
9084
9168
  * This second gate covers a modern client talking to a 3.0 seller on the
@@ -50,6 +50,12 @@ import {
50
50
  } from "../utils/adcp-version-config.mjs";
51
51
  import { beta6ReportingRequestIssue } from "../media-buy/reporting-version.mjs";
52
52
  import {
53
+ CREATIVE_START_POLICY_FEATURE,
54
+ CREATIVE_START_POLICY_FIELD,
55
+ creativeStartPolicyOptInFields
56
+ } from "../media-buy/creative-start-policy.mjs";
57
+ import {
58
+ capabilityDiscoveryEnvelope,
53
59
  convertRequest,
54
60
  convertResponse,
55
61
  getVersionAdapter,
@@ -204,7 +210,7 @@ import {
204
210
  isSupportedPropertyIdentifierType,
205
211
  normalizeDomainForPropertyPolicy
206
212
  } from "../media-buy/property-policy.mjs";
207
- import { resolvePropertyList } from "../server/targeting-helpers.mjs";
213
+ import { resolvePropertyList } from "./targeting-helpers.mjs";
208
214
  import {
209
215
  CreativeFormatCapabilityError,
210
216
  CreativeFormatProjectionError,
@@ -216,6 +222,7 @@ import {
216
222
  syncCreativeAssignmentTargets,
217
223
  projectUndeclaredFormatOptionSelectors,
218
224
  resolveCreativeFormatWireMode,
225
+ releaseCarriesPackageFormatOptionRefs,
219
226
  stripLegacyCreativeIdentity
220
227
  } from "../v2/projection/creative-delivery.mjs";
221
228
  import {
@@ -3861,6 +3868,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
3861
3868
  serverVersion,
3862
3869
  negotiatedRelease
3863
3870
  );
3871
+ this.assertCreativeStartPolicyDeclared(
3872
+ taskType,
3873
+ normalizedParams,
3874
+ capabilityDiscoveryContext.capabilities,
3875
+ negotiatedRelease?.version ?? options?.wireAdcpVersion ?? this.getWireAdcpVersion()
3876
+ );
3864
3877
  const { options: webhookOptions, driftLog: webhookDriftLog } = this.suppressPre31DiscoveryWebhook(
3865
3878
  taskType,
3866
3879
  options,
@@ -5666,11 +5679,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5666
5679
  if (hasCreativeFormatData) {
5667
5680
  this.validateBeforeCreativeCapabilityProbe("create_media_buy", params, taskOptions);
5668
5681
  }
5682
+ const wireRelease = {};
5669
5683
  const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
5670
5684
  "create_media_buy",
5671
5685
  taskOptions,
5672
5686
  true,
5673
- () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options)
5687
+ () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options),
5688
+ wireRelease
5674
5689
  ) : "canonical";
5675
5690
  const wireParams = params;
5676
5691
  const result = await this.executeAndHandle(
@@ -5683,7 +5698,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5683
5698
  "create_media_buy",
5684
5699
  effectiveLegacyFormatConverter,
5685
5700
  effectiveCanonicalFormatLegacyResolver,
5686
- creativeFormatProjection?.legacyFormatDefinitions
5701
+ creativeFormatProjection?.legacyFormatDefinitions,
5702
+ wireRelease.formatOptionRefs === true
5687
5703
  ),
5688
5704
  "create_media_buy",
5689
5705
  wireMode,
@@ -5769,11 +5785,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5769
5785
  if (hasCreativeFormatData) {
5770
5786
  this.validateBeforeCreativeCapabilityProbe("update_media_buy", params, taskOptions);
5771
5787
  }
5788
+ const wireRelease = {};
5772
5789
  const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
5773
5790
  "update_media_buy",
5774
5791
  taskOptions,
5775
5792
  true,
5776
- () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options)
5793
+ () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options),
5794
+ wireRelease
5777
5795
  ) : "canonical";
5778
5796
  const result = await this.executeAndHandle(
5779
5797
  "update_media_buy",
@@ -5785,7 +5803,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5785
5803
  "update_media_buy",
5786
5804
  effectiveLegacyFormatConverter,
5787
5805
  effectiveCanonicalFormatLegacyResolver,
5788
- creativeFormatProjection?.legacyFormatDefinitions
5806
+ creativeFormatProjection?.legacyFormatDefinitions,
5807
+ wireRelease.formatOptionRefs === true
5789
5808
  ),
5790
5809
  "update_media_buy",
5791
5810
  wireMode,
@@ -5941,7 +5960,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5941
5960
  async resolveCreativeFormatWireMode(taskType, options) {
5942
5961
  return this.resolveCreativeWireMode(taskType, options, true);
5943
5962
  }
5944
- async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions) {
5963
+ async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions, releaseContext) {
5945
5964
  const discoveryContext = {};
5946
5965
  const capabilities = await this.getCapabilities({
5947
5966
  ...options,
@@ -5951,6 +5970,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5951
5970
  const toolSchemas = discoveryContext.toolSchemas ?? (usesScopedFetch ? void 0 : this.cachedToolSchemas);
5952
5971
  const wireRelease = this.config.wireAdcpVersion ?? this.resolvedAdcpVersion;
5953
5972
  const declared = resolveCreativeFormatWireMode(capabilities, wireRelease);
5973
+ if (releaseContext) {
5974
+ releaseContext.formatOptionRefs = releaseCarriesPackageFormatOptionRefs(capabilities, wireRelease);
5975
+ }
5954
5976
  const document = toolSchemas && toolInputSchemasByProperties.get(toolSchemas)?.get(taskType);
5955
5977
  const { creativeSchemaSupport } = await import("./creative-schema-support.mjs");
5956
5978
  throwIfAborted(options?.signal);
@@ -5969,7 +5991,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
5969
5991
  if (resolved === "unknown" && canonicalRequiredByBuyerPin) {
5970
5992
  if (canRediscover && !usesScopedFetch && this.normalizedAgent.protocol === "mcp" && this.capabilitiesFromSharedCache && toolSchemas?.has(taskType) && !toolInputSchemasByProperties.has(toolSchemas)) {
5971
5993
  await this.invalidateDiscoveryCache(options);
5972
- return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions);
5994
+ return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions, releaseContext);
5973
5995
  }
5974
5996
  throw new CreativeFormatCapabilityError(
5975
5997
  `Cannot prove which AdCP release the seller serves for ${taskType}; a 3.2+ client will not guess a legacy creative wire shape`
@@ -6814,12 +6836,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
6814
6836
  const scopeKey = this.config._reuseConfiguredDiscovery?.() ? this.getCapabilityEvidenceScope().scopeKey : void 0;
6815
6837
  const agent = await this.ensureEndpointDiscovered(options);
6816
6838
  this.executor.validateRequest("get_adcp_capabilities", params);
6817
- const result = await this.executor.executeTask(
6839
+ const result = await this.executeCapabilityDiscovery(
6818
6840
  agent,
6819
- "get_adcp_capabilities",
6820
6841
  params,
6821
6842
  inputHandler,
6822
- options
6843
+ options,
6844
+ options.versionEnvelope ?? this.config.versionEnvelope
6823
6845
  );
6824
6846
  if (this.config._reuseConfiguredDiscovery?.() && !this.usesScopedDiscoveryTransport(options) && scopeKey === this.getCapabilityEvidenceScope().scopeKey && Object.keys(params).length === 0 && this.runAgentInfo !== void 0 && result.success && result.data && looksLikeV3Capabilities(result.data)) {
6825
6847
  const capabilities = parseCapabilitiesResponse(structuredClone(result.data));
@@ -6829,6 +6851,42 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
6829
6851
  }
6830
6852
  return result;
6831
6853
  }
6854
+ /**
6855
+ * Dispatch `get_adcp_capabilities` under the discovery version rule.
6856
+ *
6857
+ * A preview pin goes out unpinned (see {@link capabilityDiscoveryEnvelope}),
6858
+ * and a pinned discovery the seller refuses with `VERSION_UNSUPPORTED` is
6859
+ * retried once unpinned. Neither applies when the caller chose the pin, with
6860
+ * version fields in `params` or an `explicitEnvelope`: the seller's refusal,
6861
+ * carrying its `supported_versions` in `adcpError.details`, is the answer.
6862
+ * A caller `operationId` also skips the retry, which would need an id of its
6863
+ * own. Only a successful retry replaces the pinned refusal, whose diagnostics
6864
+ * name the release actually sent.
6865
+ */
6866
+ async executeCapabilityDiscovery(agent, params, inputHandler, options, explicitEnvelope) {
6867
+ const requested = params;
6868
+ const callerPinned = explicitEnvelope !== void 0 || requested.adcp_version !== void 0 || requested.adcp_major_version !== void 0;
6869
+ const envelope = capabilityDiscoveryEnvelope(
6870
+ explicitEnvelope,
6871
+ options.wireAdcpVersion ?? this.config.wireAdcpVersion ?? this.resolvedAdcpVersion
6872
+ );
6873
+ const result = await this.executor.executeTask(
6874
+ agent,
6875
+ "get_adcp_capabilities",
6876
+ params,
6877
+ inputHandler,
6878
+ envelope === void 0 ? options : { ...options, versionEnvelope: envelope }
6879
+ );
6880
+ if (callerPinned || envelope === "none" || options.operationId !== void 0 || result.success || result.adcpError?.code !== "VERSION_UNSUPPORTED") {
6881
+ return result;
6882
+ }
6883
+ throwIfAborted(options.signal);
6884
+ const unpinned = await this.executor.executeTask(agent, "get_adcp_capabilities", params, inputHandler, {
6885
+ ...childTaskOptions(options),
6886
+ versionEnvelope: "none"
6887
+ });
6888
+ return unpinned.success ? unpinned : result;
6889
+ }
6832
6890
  // ====== CREATIVE BUILD TASKS ======
6833
6891
  /**
6834
6892
  * Build a creative through the legacy named-format protocol.
@@ -7457,6 +7515,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
7457
7515
  serverVersion,
7458
7516
  negotiatedRelease
7459
7517
  );
7518
+ this.assertCreativeStartPolicyDeclared(
7519
+ taskName,
7520
+ normalizedParams,
7521
+ capabilityDiscoveryContext.capabilities,
7522
+ negotiatedRelease?.version ?? options?.wireAdcpVersion ?? this.getWireAdcpVersion()
7523
+ );
7460
7524
  const { options: webhookOptions, driftLog: webhookDriftLog } = this.suppressPre31DiscoveryWebhook(
7461
7525
  taskName,
7462
7526
  options,
@@ -8358,15 +8422,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
8358
8422
  try {
8359
8423
  const agent = await this.ensureEndpointDiscovered(options);
8360
8424
  const callerOptions = options;
8361
- const isPreview = !!parseAdcpRelease(this.resolvedAdcpVersion)?.prerelease;
8425
+ const isPreview = capabilityDiscoveryEnvelope(void 0, this.config.wireAdcpVersion ?? this.resolvedAdcpVersion) === "none";
8362
8426
  const probeOptions = {
8363
8427
  // Discover the seller's release window before claiming a preview
8364
8428
  // older sellers may reject. Ordinary calls still negotiate exact
8365
8429
  // preview evidence or a maintained stable downgrade afterwards.
8366
- ...isPreview && {
8367
- versionEnvelope: callerOptions?.versionEnvelope ?? this.config.versionEnvelope ?? "none",
8368
- disableWebhook: true
8369
- },
8430
+ ...isPreview && { disableWebhook: true },
8370
8431
  ...options?.signal !== void 0 && { signal: options.signal },
8371
8432
  ...options?.transport !== void 0 && { transport: options.transport },
8372
8433
  ...callerOptions?.disableWebhook !== void 0 && !isPreview && {
@@ -8376,12 +8437,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
8376
8437
  delegatedOperatorAuthorization: { ...callerOptions.delegatedOperatorAuthorization }
8377
8438
  }
8378
8439
  };
8379
- const result = await this.executor.executeTask(
8440
+ const result = await this.executeCapabilityDiscovery(
8380
8441
  agent,
8381
- "get_adcp_capabilities",
8382
8442
  {},
8383
8443
  void 0,
8384
- probeOptions
8444
+ probeOptions,
8445
+ // The operation's own envelope steers only a preview probe; a stable
8446
+ // probe keeps the client's configured envelope.
8447
+ (isPreview ? callerOptions?.versionEnvelope : void 0) ?? this.config.versionEnvelope
8385
8448
  );
8386
8449
  throwIfAborted(options?.signal);
8387
8450
  const requestTimeoutMs = resolveRequestTimeoutMs(
@@ -9198,6 +9261,33 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
9198
9261
  }
9199
9262
  };
9200
9263
  }
9264
+ /**
9265
+ * AdCP 3.3: buyers MUST NOT send `packages[].start_requires_all_creatives_approved:
9266
+ * true` on `control_media_buy` to a seller that does not declare
9267
+ * `media_buy.features.creative_start_policy: true` (#3649). Refuses only when
9268
+ * discovery is authoritative; with synthetic or missing capabilities the
9269
+ * request is sent and the seller decides. `false`, omission and calls below
9270
+ * 3.3 are unaffected. The vocabulary matches the seller's own refusal.
9271
+ */
9272
+ assertCreativeStartPolicyDeclared(taskName, params, capabilities, targetVersion) {
9273
+ if (taskName !== "control_media_buy") return;
9274
+ const fields = creativeStartPolicyOptInFields(params);
9275
+ if (fields.length === 0 || capabilities?._synthetic !== false) return;
9276
+ if (!isAdcpVersionAtLeast(targetVersion, "3.3.0-beta.0")) return;
9277
+ if (resolveFeature(capabilities, "creative_start_policy")) return;
9278
+ const suggestion = `Omit ${CREATIVE_START_POLICY_FIELD} or send false; check ${CREATIVE_START_POLICY_FEATURE} in get_adcp_capabilities before opting in.`;
9279
+ throw new ProtocolFeatureUnsupportedError(
9280
+ ["creative_start_policy"],
9281
+ listDeclaredFeatures(capabilities),
9282
+ this.agent.agent_uri,
9283
+ {
9284
+ message: `${taskName} ${fields.join(", ")}: true ${fields.length === 1 ? "requires" : "require"} ${CREATIVE_START_POLICY_FEATURE}, which this seller does not declare. No request was sent. ${suggestion}`,
9285
+ field: fields[0],
9286
+ suggestion,
9287
+ details: { feature: CREATIVE_START_POLICY_FEATURE, fields }
9288
+ }
9289
+ );
9290
+ }
9201
9291
  /**
9202
9292
  * Reject shape-changing 3.1 requests after seller capability discovery.
9203
9293
  * This second gate covers a modern client talking to a 3.0 seller on the
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Inventory list targeting helpers for AdCP sellers.
3
+ *
4
+ * AdCP 3.0 carries property and collection targeting as references to
5
+ * externally-managed lists (`PropertyListReference`, `CollectionListReference`).
6
+ * The seller resolves those references at serve time and filters its own
7
+ * inventory against the resolved contents.
8
+ *
9
+ * These helpers let a seller handler do that in one line:
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * import { resolvePropertyList, matchesPropertyList } from '@adcp/sdk/server';
14
+ *
15
+ * if (targeting.property_list) {
16
+ * const list = await resolvePropertyList(targeting.property_list);
17
+ * inventory = inventory.filter(p => matchesPropertyList(p.identifier, list));
18
+ * }
19
+ * ```
20
+ *
21
+ * Resolution goes through MCP (`get_property_list` / `get_collection_list`) on
22
+ * the referenced agent — the same contract a buyer agent uses to fetch the list.
23
+ * Matching follows the identifier and distribution-id semantics defined by the
24
+ * AdCP property and collection specs.
25
+ */
26
+ import type { PropertyListReference, CollectionListReference, GetCollectionListResponse, Identifier } from '../types/tools.generated.mjs';
27
+ export interface ResolvedPropertyList {
28
+ listId: string;
29
+ agentUrl: string;
30
+ identifiers: Identifier[];
31
+ cacheValidUntil?: string;
32
+ }
33
+ /** A collection entry as returned by get_collection_list. */
34
+ export type ResolvedCollection = NonNullable<GetCollectionListResponse['collections']>[number];
35
+ export interface ResolvedCollectionList {
36
+ listId: string;
37
+ agentUrl: string;
38
+ collections: ResolvedCollection[];
39
+ cacheValidUntil?: string;
40
+ }
41
+ export type ResolvedListKind = 'property' | 'collection';
42
+ export type ResolvedListCacheValue = ResolvedPropertyList | ResolvedCollectionList;
43
+ export declare const DEFAULT_RESOLVE_LIST_PAGE_SIZE = 1000;
44
+ export interface ResolvedListCacheEntry<TValue extends ResolvedListCacheValue = ResolvedListCacheValue> {
45
+ value: TValue;
46
+ expiresAtMs: number;
47
+ }
48
+ export interface ResolvedListCache {
49
+ get<TValue extends ResolvedListCacheValue>(key: string, nowMs?: number): TValue | undefined;
50
+ set<TValue extends ResolvedListCacheValue>(key: string, entry: ResolvedListCacheEntry<TValue>): void;
51
+ delete(key: string): boolean;
52
+ clear(): void;
53
+ }
54
+ export declare function createResolvedListCache(): ResolvedListCache;
55
+ export declare const defaultResolvedListCache: ResolvedListCache;
56
+ export declare function clearDefaultResolvedListCache(): void;
57
+ export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
58
+ export interface ResolveListOptions {
59
+ /** Require schema-valid list pages with resolved items. Used for certification. */
60
+ strictResponseValidation?: boolean;
61
+ /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
62
+ pageSize?: number;
63
+ /** Maximum number of pages to walk before treating pagination as unsafe. Defaults to 100. */
64
+ maxPages?: number;
65
+ /** Cache for resolved list contents. Defaults to the process-local SDK cache. Pass false to disable caching. */
66
+ cache?: ResolvedListCache | false;
67
+ /**
68
+ * Tenant/principal/auth-context fingerprint for cache scoping when the list
69
+ * reference does not carry an auth_token. Shared caching is disabled without
70
+ * either auth_token or this explicit scope.
71
+ */
72
+ cacheScopeKey?: string;
73
+ /** Clock hook for testing cache expiry. */
74
+ now?: () => Date | number;
75
+ /** MCP call hook for testing/custom transports. */
76
+ callTool?: ResolveListCallTool;
77
+ }
78
+ /**
79
+ * Resolve a PropertyListReference to the concrete identifiers it contains.
80
+ *
81
+ * Calls `get_property_list` on the referenced agent with `resolve: true`.
82
+ * Honors `auth_token` on the reference if present.
83
+ */
84
+ export declare function resolvePropertyList(ref: PropertyListReference, options?: ResolveListOptions): Promise<ResolvedPropertyList>;
85
+ /**
86
+ * Resolve a CollectionListReference to the concrete collections it contains.
87
+ *
88
+ * Calls `get_collection_list` on the referenced agent with `resolve: true`.
89
+ * Honors `auth_token` on the reference if present.
90
+ */
91
+ export declare function resolveCollectionList(ref: CollectionListReference, options?: ResolveListOptions): Promise<ResolvedCollectionList>;
92
+ export declare function resolvedListCacheKey(kind: ResolvedListKind, ref: Pick<PropertyListReference | CollectionListReference, 'agent_url' | 'list_id' | 'auth_token'>, options?: Pick<ResolveListOptions, 'pageSize' | 'cacheScopeKey'>): string | undefined;
93
+ /**
94
+ * Return true if `property` matches any identifier in the resolved list.
95
+ *
96
+ * Domain matching rules (from the AdCP property spec):
97
+ * - Exact match on the identifier value is always accepted.
98
+ * - A `domain` entry of `example.com` also matches `www.example.com` and
99
+ * `m.example.com` — the two canonical aliases for a base domain.
100
+ * - A `domain` entry of `*.example.com` matches every subdomain but NOT the
101
+ * base domain itself.
102
+ * - Non-domain identifier types (ios_bundle, network_id, etc.) use exact
103
+ * string match on both `type` and `value`.
104
+ */
105
+ export declare function matchesPropertyList(property: Identifier, list: ResolvedPropertyList): boolean;
106
+ /**
107
+ * Return true if `collection` matches any entry in the resolved list.
108
+ *
109
+ * Matching modes:
110
+ * - Collections match when `collection_rid` is set on both sides and equal.
111
+ * - Otherwise, they match when they share at least one `distribution_ids`
112
+ * entry with the same `type` and `value`.
113
+ *
114
+ * A collection with no collection_rid and no distribution_ids cannot match —
115
+ * the seller has nothing to match against.
116
+ */
117
+ export declare function matchesCollectionList(collection: {
118
+ collection_rid?: string;
119
+ distribution_ids?: {
120
+ type: string;
121
+ value: string;
122
+ }[];
123
+ }, list: ResolvedCollectionList): boolean;