@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
@@ -0,0 +1,56 @@
1
+ const DEFAULT_OPTIONS = {
2
+ maxDepth: 2,
3
+ maxSizeBytes: 2048
4
+ };
5
+ function pickSafeDetails(input, allowlist, opts) {
6
+ if (!isPlainObject(input)) return void 0;
7
+ if (allowlist.length === 0) return void 0;
8
+ const maxDepth = opts?.maxDepth ?? DEFAULT_OPTIONS.maxDepth;
9
+ const maxSize = opts?.maxSizeBytes ?? DEFAULT_OPTIONS.maxSizeBytes;
10
+ const allowSet = new Set(allowlist);
11
+ const result = filterByAllowlist(input, allowSet, maxDepth);
12
+ if (result == null || Object.keys(result).length === 0) return void 0;
13
+ let serialized;
14
+ try {
15
+ serialized = JSON.stringify(result);
16
+ } catch {
17
+ return void 0;
18
+ }
19
+ if (serialized.length > maxSize) return void 0;
20
+ return result;
21
+ }
22
+ function filterByAllowlist(obj, allow, remainingDepth) {
23
+ const out = {};
24
+ for (const key of Object.keys(obj)) {
25
+ if (!allow.has(key)) continue;
26
+ const value = obj[key];
27
+ const safe = sanitizeValue(value, allow, remainingDepth - 1);
28
+ if (safe !== void 0) out[key] = safe;
29
+ }
30
+ return Object.keys(out).length === 0 ? null : out;
31
+ }
32
+ function sanitizeValue(value, allow, remainingDepth) {
33
+ if (value === null) return null;
34
+ const t = typeof value;
35
+ if (t === "string" || t === "number" || t === "boolean") return value;
36
+ if (t === "function" || t === "symbol" || t === "undefined" || t === "bigint") return void 0;
37
+ if (Array.isArray(value)) {
38
+ const mapped = value.map((v) => sanitizeValue(v, allow, remainingDepth));
39
+ return mapped.filter((v) => v !== void 0);
40
+ }
41
+ if (isPlainObject(value)) {
42
+ if (remainingDepth <= 0) return void 0;
43
+ const filtered = filterByAllowlist(value, allow, remainingDepth);
44
+ return filtered ?? void 0;
45
+ }
46
+ return void 0;
47
+ }
48
+ function isPlainObject(value) {
49
+ if (value === null || typeof value !== "object") return false;
50
+ if (Array.isArray(value)) return false;
51
+ const proto = Object.getPrototypeOf(value);
52
+ return proto === Object.prototype || proto === null;
53
+ }
54
+ export {
55
+ pickSafeDetails
56
+ };
@@ -132,6 +132,10 @@ export declare function toCanonicalFormatOptionsWithRoutes(productId: string, fo
132
132
  * before being forwarded to a legacy seller. Rebuild the write-side resolver
133
133
  * with `canonicalFormatLegacyResolverFromRoutes(restoredRoutes)`.
134
134
  *
135
+ * A legacy id at a seller's own agent URL may be projected by a guess from its
136
+ * name (`display_300x250` read as `image`). Its route carries
137
+ * `inferred_from_id: true`; pass `authoritativeOnly: true` to skip guesses.
138
+ *
135
139
  * @throws TypeError when a canonical declaration uses a direct legacy identity
136
140
  * alias such as `agent_url` or `agentUrl` instead of `v1_format_ref`.
137
141
  */
@@ -132,6 +132,10 @@ export declare function toCanonicalFormatOptionsWithRoutes(productId: string, fo
132
132
  * before being forwarded to a legacy seller. Rebuild the write-side resolver
133
133
  * with `canonicalFormatLegacyResolverFromRoutes(restoredRoutes)`.
134
134
  *
135
+ * A legacy id at a seller's own agent URL may be projected by a guess from its
136
+ * name (`display_300x250` read as `image`). Its route carries
137
+ * `inferred_from_id: true`; pass `authoritativeOnly: true` to skip guesses.
138
+ *
135
139
  * @throws TypeError when a canonical declaration uses a direct legacy identity
136
140
  * alias such as `agent_url` or `agentUrl` instead of `v1_format_ref`.
137
141
  */
@@ -346,9 +346,17 @@ export declare class CreativeFormatCapabilityError extends Error {
346
346
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode?: 'canonical', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T>;
347
347
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: 'legacy' | 'unknown', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): LegacyProjectedCreative<T>;
348
348
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: CreativeFormatWireMode, operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T> | LegacyProjectedCreative<T>;
349
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
350
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
351
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
349
+ /**
350
+ * Project a create/update media-buy request's packages and creatives to the
351
+ * seller's creative wire. On the legacy wire, pass `formatOptionRefsOnWire`
352
+ * when the seller's release defines package `format_option_refs` (AdCP 3.1;
353
+ * see {@link releaseCarriesPackageFormatOptionRefs}): selections with no
354
+ * legacy `format_ids` are then sent as `format_option_refs` instead of
355
+ * throwing. Selections that do map are still rewritten to `format_ids`.
356
+ */
357
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
358
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
359
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
352
360
  export interface CreativePackageFit {
353
361
  package_id: string;
354
362
  verdict: CreativeFitVerdict;
@@ -413,3 +421,12 @@ export type UndeclaredFormatOptionLookup = (ref: FormatOptionReference, productI
413
421
  */
414
422
  export declare function projectUndeclaredFormatOptionSelectors<T>(request: T, operation: 'create_media_buy' | 'update_media_buy' | 'sync_creatives', lookup: UndeclaredFormatOptionLookup): T;
415
423
  export declare function resolveCreativeFormatWireMode(capabilities: unknown, negotiatedVersion?: string): CreativeFormatWireMode;
424
+ /**
425
+ * Whether the seller's advertised `supported_versions` prove a mutually served
426
+ * release whose package request defines `format_option_refs` (AdCP 3.1 and
427
+ * later). AdCP 3.0 does not define the field, and a release that cannot be
428
+ * proven is treated as 3.0, so a selection is never silently dropped. Throws
429
+ * `CreativeFormatCapabilityError` for the same release contradictions as
430
+ * {@link resolveCreativeFormatWireMode}.
431
+ */
432
+ export declare function releaseCarriesPackageFormatOptionRefs(capabilities: unknown, requestedVersion: string): boolean;
@@ -346,9 +346,17 @@ export declare class CreativeFormatCapabilityError extends Error {
346
346
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode?: 'canonical', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T>;
347
347
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: 'legacy' | 'unknown', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): LegacyProjectedCreative<T>;
348
348
  export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: CreativeFormatWireMode, operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T> | LegacyProjectedCreative<T>;
349
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
350
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
351
- export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
349
+ /**
350
+ * Project a create/update media-buy request's packages and creatives to the
351
+ * seller's creative wire. On the legacy wire, pass `formatOptionRefsOnWire`
352
+ * when the seller's release defines package `format_option_refs` (AdCP 3.1;
353
+ * see {@link releaseCarriesPackageFormatOptionRefs}): selections with no
354
+ * legacy `format_ids` are then sent as `format_option_refs` instead of
355
+ * throwing. Selections that do map are still rewritten to `format_ids`.
356
+ */
357
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
358
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
359
+ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
352
360
  export interface CreativePackageFit {
353
361
  package_id: string;
354
362
  verdict: CreativeFitVerdict;
@@ -413,3 +421,12 @@ export type UndeclaredFormatOptionLookup = (ref: FormatOptionReference, productI
413
421
  */
414
422
  export declare function projectUndeclaredFormatOptionSelectors<T>(request: T, operation: 'create_media_buy' | 'update_media_buy' | 'sync_creatives', lookup: UndeclaredFormatOptionLookup): T;
415
423
  export declare function resolveCreativeFormatWireMode(capabilities: unknown, negotiatedVersion?: string): CreativeFormatWireMode;
424
+ /**
425
+ * Whether the seller's advertised `supported_versions` prove a mutually served
426
+ * release whose package request defines `format_option_refs` (AdCP 3.1 and
427
+ * later). AdCP 3.0 does not define the field, and a release that cannot be
428
+ * proven is treated as 3.0, so a selection is never silently dropped. Throws
429
+ * `CreativeFormatCapabilityError` for the same release contradictions as
430
+ * {@link resolveCreativeFormatWireMode}.
431
+ */
432
+ export declare function releaseCarriesPackageFormatOptionRefs(capabilities: unknown, requestedVersion: string): boolean;
@@ -26,6 +26,7 @@ __export(creative_delivery_exports, {
26
26
  projectMediaBuyCreativesForDelivery: () => projectMediaBuyCreativesForDelivery,
27
27
  projectSyncCreativesForDelivery: () => projectSyncCreativesForDelivery,
28
28
  projectUndeclaredFormatOptionSelectors: () => projectUndeclaredFormatOptionSelectors,
29
+ releaseCarriesPackageFormatOptionRefs: () => releaseCarriesPackageFormatOptionRefs,
29
30
  resolveCreativeFormatWireMode: () => resolveCreativeFormatWireMode,
30
31
  stripLegacyCreativeIdentity: () => stripLegacyCreativeIdentity,
31
32
  syncCreativeAssignmentTargets: () => syncCreativeAssignmentTargets
@@ -909,7 +910,7 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
909
910
  function dedupeLegacyRefs(refs) {
910
911
  return [...new Map(refs.map((ref) => [candidateKey({ ref }), { ...ref }])).values()];
911
912
  }
912
- function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter, canonicalFormatLegacyResolver) {
913
+ function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter, canonicalFormatLegacyResolver, formatOptionRefsOnWire = false) {
913
914
  const next = { ...pkg };
914
915
  const optionRefs = Array.isArray(pkg.format_option_refs) ? pkg.format_option_refs.flatMap((value) => {
915
916
  const ref = optionReference(value);
@@ -985,6 +986,12 @@ function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter
985
986
  );
986
987
  }
987
988
  if (!resolved) {
989
+ if (formatOptionRefsOnWire) {
990
+ next.format_option_refs = optionRefs.map((ref) => ({ ...ref }));
991
+ delete next.format_kind;
992
+ delete next.params;
993
+ return next;
994
+ }
988
995
  throw new CreativeFormatProjectionError(
989
996
  operation,
990
997
  "(package selector)",
@@ -1276,7 +1283,7 @@ function describeUnmatchedLegacyCandidates(creative, allCandidates) {
1276
1283
  }
1277
1284
  return generic;
1278
1285
  }
1279
- function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
1286
+ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions, formatOptionRefsOnWire = false) {
1280
1287
  const requestRecord = record(request);
1281
1288
  if (!requestRecord) return request;
1282
1289
  let changed = false;
@@ -1307,7 +1314,10 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
1307
1314
  wireMode,
1308
1315
  operation,
1309
1316
  legacyFormatConverter,
1310
- canonicalFormatLegacyResolver
1317
+ canonicalFormatLegacyResolver,
1318
+ // update_media_buy `packages` are package updates, which never carry
1319
+ // a format selector; `new_packages` are package requests.
1320
+ formatOptionRefsOnWire && (operation === "create_media_buy" || key === "new_packages")
1311
1321
  );
1312
1322
  if (projectedPackage !== packageValue) changed = true;
1313
1323
  return creatives ? { ...projectedPackage, creatives } : projectedPackage;
@@ -1932,7 +1942,7 @@ function evaluateLegacyFormatFit(facts, value, container, legacyFormatConverter,
1932
1942
  name: "Legacy creative fit",
1933
1943
  format_ids: [raw]
1934
1944
  },
1935
- { _authoritativeOnly: true, legacyFormatConverter }
1945
+ { authoritativeOnly: true, legacyFormatConverter }
1936
1946
  ).v2.format_options[0] : void 0;
1937
1947
  if (sourceDeclaration) {
1938
1948
  const contract = (value2) => {
@@ -2621,6 +2631,11 @@ function canUseProductOptionsForCreativeWire(capabilities, requestedVersion) {
2621
2631
  const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
2622
2632
  return negotiated?.major === 3 && negotiated.minor === 1;
2623
2633
  }
2634
+ function releaseCarriesPackageFormatOptionRefs(capabilities, requestedVersion) {
2635
+ const caps = record(capabilities);
2636
+ const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
2637
+ return negotiated !== void 0 && (negotiated.major > 3 || negotiated.major === 3 && negotiated.minor >= 1);
2638
+ }
2624
2639
  // Annotate the CommonJS export names for ESM import in node:
2625
2640
  0 && (module.exports = {
2626
2641
  CreativeFormatCapabilityError,
@@ -2631,6 +2646,7 @@ function canUseProductOptionsForCreativeWire(capabilities, requestedVersion) {
2631
2646
  projectMediaBuyCreativesForDelivery,
2632
2647
  projectSyncCreativesForDelivery,
2633
2648
  projectUndeclaredFormatOptionSelectors,
2649
+ releaseCarriesPackageFormatOptionRefs,
2634
2650
  resolveCreativeFormatWireMode,
2635
2651
  stripLegacyCreativeIdentity,
2636
2652
  syncCreativeAssignmentTargets
@@ -897,7 +897,7 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
897
897
  function dedupeLegacyRefs(refs) {
898
898
  return [...new Map(refs.map((ref) => [candidateKey({ ref }), { ...ref }])).values()];
899
899
  }
900
- function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter, canonicalFormatLegacyResolver) {
900
+ function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter, canonicalFormatLegacyResolver, formatOptionRefsOnWire = false) {
901
901
  const next = { ...pkg };
902
902
  const optionRefs = Array.isArray(pkg.format_option_refs) ? pkg.format_option_refs.flatMap((value) => {
903
903
  const ref = optionReference(value);
@@ -973,6 +973,12 @@ function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter
973
973
  );
974
974
  }
975
975
  if (!resolved) {
976
+ if (formatOptionRefsOnWire) {
977
+ next.format_option_refs = optionRefs.map((ref) => ({ ...ref }));
978
+ delete next.format_kind;
979
+ delete next.params;
980
+ return next;
981
+ }
976
982
  throw new CreativeFormatProjectionError(
977
983
  operation,
978
984
  "(package selector)",
@@ -1264,7 +1270,7 @@ function describeUnmatchedLegacyCandidates(creative, allCandidates) {
1264
1270
  }
1265
1271
  return generic;
1266
1272
  }
1267
- function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
1273
+ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions, formatOptionRefsOnWire = false) {
1268
1274
  const requestRecord = record(request);
1269
1275
  if (!requestRecord) return request;
1270
1276
  let changed = false;
@@ -1295,7 +1301,10 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
1295
1301
  wireMode,
1296
1302
  operation,
1297
1303
  legacyFormatConverter,
1298
- canonicalFormatLegacyResolver
1304
+ canonicalFormatLegacyResolver,
1305
+ // update_media_buy `packages` are package updates, which never carry
1306
+ // a format selector; `new_packages` are package requests.
1307
+ formatOptionRefsOnWire && (operation === "create_media_buy" || key === "new_packages")
1299
1308
  );
1300
1309
  if (projectedPackage !== packageValue) changed = true;
1301
1310
  return creatives ? { ...projectedPackage, creatives } : projectedPackage;
@@ -1920,7 +1929,7 @@ function evaluateLegacyFormatFit(facts, value, container, legacyFormatConverter,
1920
1929
  name: "Legacy creative fit",
1921
1930
  format_ids: [raw]
1922
1931
  },
1923
- { _authoritativeOnly: true, legacyFormatConverter }
1932
+ { authoritativeOnly: true, legacyFormatConverter }
1924
1933
  ).v2.format_options[0] : void 0;
1925
1934
  if (sourceDeclaration) {
1926
1935
  const contract = (value2) => {
@@ -2609,6 +2618,11 @@ function canUseProductOptionsForCreativeWire(capabilities, requestedVersion) {
2609
2618
  const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
2610
2619
  return negotiated?.major === 3 && negotiated.minor === 1;
2611
2620
  }
2621
+ function releaseCarriesPackageFormatOptionRefs(capabilities, requestedVersion) {
2622
+ const caps = record(capabilities);
2623
+ const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
2624
+ return negotiated !== void 0 && (negotiated.major > 3 || negotiated.major === 3 && negotiated.minor >= 1);
2625
+ }
2612
2626
  export {
2613
2627
  CreativeFormatCapabilityError,
2614
2628
  CreativeFormatProjectionError,
@@ -2618,6 +2632,7 @@ export {
2618
2632
  projectMediaBuyCreativesForDelivery,
2619
2633
  projectSyncCreativesForDelivery,
2620
2634
  projectUndeclaredFormatOptionSelectors,
2635
+ releaseCarriesPackageFormatOptionRefs,
2621
2636
  resolveCreativeFormatWireMode,
2622
2637
  stripLegacyCreativeIdentity,
2623
2638
  syncCreativeAssignmentTargets
@@ -51,8 +51,8 @@ export { getCreativeDeliveryDiagnostics } from './legacy-metadata.mjs';
51
51
  export type { V1FormatId, V2ProductFormatDeclaration, V2ProductInput, V2Product, V1ProductInput, V1Product, ProjectionProductInput, ProjectionDiagnostic, } from './types.mjs';
52
52
  export { isProjectionProductInput } from './types.mjs';
53
53
  export { legacyFormatConverterFromCatalogSnapshots, canonicalFormatLegacyResolverFromCatalogSnapshots, projectionAdaptersFromCatalogSnapshots, type ProjectionCatalogAdapters, type ProjectionCatalogSnapshot, type ProjectionCatalogSource, } from './catalog-snapshot.mjs';
54
- export { loadCatalog, lookupV1Format, findCatalogEntryByCanonicalAndSize, parseSizedIdTemplate, _resetCatalogCache, type V1FormatDefinition, type CanonicalProjectionRef, } from './catalog.mjs';
54
+ export { isAaoAgentUrl, loadCatalog, lookupV1Format, findCatalogEntryByCanonicalAndSize, parseSizedIdTemplate, _resetCatalogCache, type V1FormatDefinition, type CanonicalProjectionRef, } from './catalog.mjs';
55
55
  export { isCanonicalV1Translatable } from './canonical-properties.mjs';
56
56
  export { normalizeLegacyGetProductsResponse } from './legacy-normalization.mjs';
57
57
  export type { LegacyProductNormalizationInput, NormalizedLegacyProduct } from './legacy-normalization.mjs';
58
- export { CreativeFormatProjectionError, fitCreativeToPackages, type CreativePackageFit, type CreativePackageFitOptions, type CreativePackageFitResult, type CreativeFitVerdict, type CreativeFitReason, type CreativePrimaryAssetFacts, type CreativeVastInlineFacts, CreativeFormatCapabilityError, projectCreativeForDelivery, projectMediaBuyCreativesForDelivery, projectSyncCreativesForDelivery, stripLegacyCreativeIdentity, resolveCreativeFormatWireMode, type CreativeFormatSelectorContainer, type CanonicalCreativeFormatSelectorContainer, type CreativeFormatWireMode, type CanonicalCreativeAsset, type CanonicalSyncCreativeAsset, type CanonicalCreativeResponse, type CanonicalGetProductsResponse, type CanonicalGetProductsRequest, type CanonicalCreateMediaBuyInput, type CanonicalCreateMediaBuyRequest, type CanonicalCreateMediaBuyResponse, type CanonicalCreativeFilters, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalGetCreativeDeliveryResponse, type CanonicalGetMediaBuyDeliveryResponse, type CanonicalGetMediaBuysResponse, type CanonicalListedCreative, type CanonicalPackageRequest, type CanonicalPackageUpdate, type CanonicalPackage, type CanonicalPlacement, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalProduct, type CanonicalProjectedCreative, type CanonicalSyncCreativesRequest, type CanonicalSyncCreativesResponse, type CanonicalUpdateMediaBuyRequest, type CanonicalUpdateMediaBuyResponse, type LegacyCreativeAsset, type LegacyProjectedCreative, type ProjectedMediaBuyCreativeRequest, type ProjectedSyncCreativeRequest, type SyncCreativeFormatProjection, } from './creative-delivery.mjs';
58
+ export { CreativeFormatProjectionError, fitCreativeToPackages, type CreativePackageFit, type CreativePackageFitOptions, type CreativePackageFitResult, type CreativeFitVerdict, type CreativeFitReason, type CreativePrimaryAssetFacts, type CreativeVastInlineFacts, CreativeFormatCapabilityError, projectCreativeForDelivery, projectMediaBuyCreativesForDelivery, projectSyncCreativesForDelivery, stripLegacyCreativeIdentity, resolveCreativeFormatWireMode, releaseCarriesPackageFormatOptionRefs, type CreativeFormatSelectorContainer, type CanonicalCreativeFormatSelectorContainer, type CreativeFormatWireMode, type CanonicalCreativeAsset, type CanonicalSyncCreativeAsset, type CanonicalCreativeResponse, type CanonicalGetProductsResponse, type CanonicalGetProductsRequest, type CanonicalCreateMediaBuyInput, type CanonicalCreateMediaBuyRequest, type CanonicalCreateMediaBuyResponse, type CanonicalCreativeFilters, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalGetCreativeDeliveryResponse, type CanonicalGetMediaBuyDeliveryResponse, type CanonicalGetMediaBuysResponse, type CanonicalListedCreative, type CanonicalPackageRequest, type CanonicalPackageUpdate, type CanonicalPackage, type CanonicalPlacement, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalProduct, type CanonicalProjectedCreative, type CanonicalSyncCreativesRequest, type CanonicalSyncCreativesResponse, type CanonicalUpdateMediaBuyRequest, type CanonicalUpdateMediaBuyResponse, type LegacyCreativeAsset, type LegacyProjectedCreative, type ProjectedMediaBuyCreativeRequest, type ProjectedSyncCreativeRequest, type SyncCreativeFormatProjection, } from './creative-delivery.mjs';
@@ -51,8 +51,8 @@ export { getCreativeDeliveryDiagnostics } from './legacy-metadata';
51
51
  export type { V1FormatId, V2ProductFormatDeclaration, V2ProductInput, V2Product, V1ProductInput, V1Product, ProjectionProductInput, ProjectionDiagnostic, } from './types';
52
52
  export { isProjectionProductInput } from './types';
53
53
  export { legacyFormatConverterFromCatalogSnapshots, canonicalFormatLegacyResolverFromCatalogSnapshots, projectionAdaptersFromCatalogSnapshots, type ProjectionCatalogAdapters, type ProjectionCatalogSnapshot, type ProjectionCatalogSource, } from './catalog-snapshot';
54
- export { loadCatalog, lookupV1Format, findCatalogEntryByCanonicalAndSize, parseSizedIdTemplate, _resetCatalogCache, type V1FormatDefinition, type CanonicalProjectionRef, } from './catalog';
54
+ export { isAaoAgentUrl, loadCatalog, lookupV1Format, findCatalogEntryByCanonicalAndSize, parseSizedIdTemplate, _resetCatalogCache, type V1FormatDefinition, type CanonicalProjectionRef, } from './catalog';
55
55
  export { isCanonicalV1Translatable } from './canonical-properties';
56
56
  export { normalizeLegacyGetProductsResponse } from './legacy-normalization';
57
57
  export type { LegacyProductNormalizationInput, NormalizedLegacyProduct } from './legacy-normalization';
58
- export { CreativeFormatProjectionError, fitCreativeToPackages, type CreativePackageFit, type CreativePackageFitOptions, type CreativePackageFitResult, type CreativeFitVerdict, type CreativeFitReason, type CreativePrimaryAssetFacts, type CreativeVastInlineFacts, CreativeFormatCapabilityError, projectCreativeForDelivery, projectMediaBuyCreativesForDelivery, projectSyncCreativesForDelivery, stripLegacyCreativeIdentity, resolveCreativeFormatWireMode, type CreativeFormatSelectorContainer, type CanonicalCreativeFormatSelectorContainer, type CreativeFormatWireMode, type CanonicalCreativeAsset, type CanonicalSyncCreativeAsset, type CanonicalCreativeResponse, type CanonicalGetProductsResponse, type CanonicalGetProductsRequest, type CanonicalCreateMediaBuyInput, type CanonicalCreateMediaBuyRequest, type CanonicalCreateMediaBuyResponse, type CanonicalCreativeFilters, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalGetCreativeDeliveryResponse, type CanonicalGetMediaBuyDeliveryResponse, type CanonicalGetMediaBuysResponse, type CanonicalListedCreative, type CanonicalPackageRequest, type CanonicalPackageUpdate, type CanonicalPackage, type CanonicalPlacement, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalProduct, type CanonicalProjectedCreative, type CanonicalSyncCreativesRequest, type CanonicalSyncCreativesResponse, type CanonicalUpdateMediaBuyRequest, type CanonicalUpdateMediaBuyResponse, type LegacyCreativeAsset, type LegacyProjectedCreative, type ProjectedMediaBuyCreativeRequest, type ProjectedSyncCreativeRequest, type SyncCreativeFormatProjection, } from './creative-delivery';
58
+ export { CreativeFormatProjectionError, fitCreativeToPackages, type CreativePackageFit, type CreativePackageFitOptions, type CreativePackageFitResult, type CreativeFitVerdict, type CreativeFitReason, type CreativePrimaryAssetFacts, type CreativeVastInlineFacts, CreativeFormatCapabilityError, projectCreativeForDelivery, projectMediaBuyCreativesForDelivery, projectSyncCreativesForDelivery, stripLegacyCreativeIdentity, resolveCreativeFormatWireMode, releaseCarriesPackageFormatOptionRefs, type CreativeFormatSelectorContainer, type CanonicalCreativeFormatSelectorContainer, type CreativeFormatWireMode, type CanonicalCreativeAsset, type CanonicalSyncCreativeAsset, type CanonicalCreativeResponse, type CanonicalGetProductsResponse, type CanonicalGetProductsRequest, type CanonicalCreateMediaBuyInput, type CanonicalCreateMediaBuyRequest, type CanonicalCreateMediaBuyResponse, type CanonicalCreativeFilters, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalGetCreativeDeliveryResponse, type CanonicalGetMediaBuyDeliveryResponse, type CanonicalGetMediaBuysResponse, type CanonicalListedCreative, type CanonicalPackageRequest, type CanonicalPackageUpdate, type CanonicalPackage, type CanonicalPlacement, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalProduct, type CanonicalProjectedCreative, type CanonicalSyncCreativesRequest, type CanonicalSyncCreativesResponse, type CanonicalUpdateMediaBuyRequest, type CanonicalUpdateMediaBuyResponse, type LegacyCreativeAsset, type LegacyProjectedCreative, type ProjectedMediaBuyCreativeRequest, type ProjectedSyncCreativeRequest, type SyncCreativeFormatProjection, } from './creative-delivery';
@@ -43,6 +43,7 @@ __export(projection_exports, {
43
43
  html5FormatDeclaration: () => import_builders.html5FormatDeclaration,
44
44
  imageCarouselFormatDeclaration: () => import_builders.imageCarouselFormatDeclaration,
45
45
  imageFormatDeclaration: () => import_builders.imageFormatDeclaration,
46
+ isAaoAgentUrl: () => import_catalog.isAaoAgentUrl,
46
47
  isCanonicalV1Translatable: () => import_canonical_properties.isCanonicalV1Translatable,
47
48
  isProjectionProductInput: () => import_types.isProjectionProductInput,
48
49
  legacyFormatConverterFromCatalogSnapshots: () => import_catalog_snapshot.legacyFormatConverterFromCatalogSnapshots,
@@ -68,6 +69,7 @@ __export(projection_exports, {
68
69
  projectV1ProductToV2: () => import_v1_to_v2.projectV1ProductToV2,
69
70
  projectV2ProductToV1: () => import_v2_to_v1.projectV2ProductToV1,
70
71
  projectionAdaptersFromCatalogSnapshots: () => import_catalog_snapshot.projectionAdaptersFromCatalogSnapshots,
72
+ releaseCarriesPackageFormatOptionRefs: () => import_creative_delivery.releaseCarriesPackageFormatOptionRefs,
71
73
  resolveCanonicalFormatKind: () => import_v1_to_v2.resolveCanonicalFormatKind,
72
74
  resolveCreativeFormatWireMode: () => import_creative_delivery.resolveCreativeFormatWireMode,
73
75
  responsiveCreativeFormatDeclaration: () => import_builders.responsiveCreativeFormatDeclaration,
@@ -125,6 +127,7 @@ var import_creative_delivery = require('./creative-delivery.js');
125
127
  html5FormatDeclaration,
126
128
  imageCarouselFormatDeclaration,
127
129
  imageFormatDeclaration,
130
+ isAaoAgentUrl,
128
131
  isCanonicalV1Translatable,
129
132
  isProjectionProductInput,
130
133
  legacyFormatConverterFromCatalogSnapshots,
@@ -150,6 +153,7 @@ var import_creative_delivery = require('./creative-delivery.js');
150
153
  projectV1ProductToV2,
151
154
  projectV2ProductToV1,
152
155
  projectionAdaptersFromCatalogSnapshots,
156
+ releaseCarriesPackageFormatOptionRefs,
153
157
  resolveCanonicalFormatKind,
154
158
  resolveCreativeFormatWireMode,
155
159
  responsiveCreativeFormatDeclaration,
@@ -57,6 +57,7 @@ import {
57
57
  projectionAdaptersFromCatalogSnapshots
58
58
  } from "./catalog-snapshot.mjs";
59
59
  import {
60
+ isAaoAgentUrl,
60
61
  loadCatalog,
61
62
  lookupV1Format,
62
63
  findCatalogEntryByCanonicalAndSize,
@@ -73,7 +74,8 @@ import {
73
74
  projectMediaBuyCreativesForDelivery,
74
75
  projectSyncCreativesForDelivery,
75
76
  stripLegacyCreativeIdentity,
76
- resolveCreativeFormatWireMode
77
+ resolveCreativeFormatWireMode,
78
+ releaseCarriesPackageFormatOptionRefs
77
79
  } from "./creative-delivery.mjs";
78
80
  export {
79
81
  CanonicalFormat,
@@ -101,6 +103,7 @@ export {
101
103
  html5FormatDeclaration,
102
104
  imageCarouselFormatDeclaration,
103
105
  imageFormatDeclaration,
106
+ isAaoAgentUrl,
104
107
  isCanonicalV1Translatable,
105
108
  isProjectionProductInput,
106
109
  legacyFormatConverterFromCatalogSnapshots,
@@ -126,6 +129,7 @@ export {
126
129
  projectV1ProductToV2,
127
130
  projectV2ProductToV1,
128
131
  projectionAdaptersFromCatalogSnapshots,
132
+ releaseCarriesPackageFormatOptionRefs,
129
133
  resolveCanonicalFormatKind,
130
134
  resolveCreativeFormatWireMode,
131
135
  responsiveCreativeFormatDeclaration,
@@ -46,6 +46,13 @@ export declare function sellerDeclaredFormatOption(declaration: object): boolean
46
46
  /** A pure legacy projection cannot establish what the original seller advertised. */
47
47
  export declare function rememberSynthesizedFormatOption(declaration: object): void;
48
48
  export declare function isSynthesizedFormatOption(declaration: object): boolean;
49
+ /**
50
+ * The projector guessed this option's kind and params from the AAO naming
51
+ * conventions applied to an id at another agent's URL. No catalog entry or
52
+ * converter declared it.
53
+ */
54
+ export declare function rememberInferredFromIdFormatOption(declaration: object): void;
55
+ export declare function isInferredFromIdFormatOption(declaration: object): boolean;
49
56
  export declare function concealLegacyFormatRefs(declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration): DeclarationWithMetadata;
50
57
  export declare function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[];
51
58
  export declare function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[];
@@ -46,6 +46,13 @@ export declare function sellerDeclaredFormatOption(declaration: object): boolean
46
46
  /** A pure legacy projection cannot establish what the original seller advertised. */
47
47
  export declare function rememberSynthesizedFormatOption(declaration: object): void;
48
48
  export declare function isSynthesizedFormatOption(declaration: object): boolean;
49
+ /**
50
+ * The projector guessed this option's kind and params from the AAO naming
51
+ * conventions applied to an id at another agent's URL. No catalog entry or
52
+ * converter declared it.
53
+ */
54
+ export declare function rememberInferredFromIdFormatOption(declaration: object): void;
55
+ export declare function isInferredFromIdFormatOption(declaration: object): boolean;
49
56
  export declare function concealLegacyFormatRefs(declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration): DeclarationWithMetadata;
50
57
  export declare function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[];
51
58
  export declare function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[];
@@ -22,10 +22,12 @@ __export(legacy_metadata_exports, {
22
22
  concealSelectedFormatOptions: () => concealSelectedFormatOptions,
23
23
  downgradePixelTracker: () => downgradePixelTracker,
24
24
  getCreativeDeliveryDiagnostics: () => getCreativeDeliveryDiagnostics,
25
+ isInferredFromIdFormatOption: () => isInferredFromIdFormatOption,
25
26
  isSynthesizedFormatOption: () => isSynthesizedFormatOption,
26
27
  legacyFormatRefsForDeclaration: () => legacyFormatRefsForDeclaration,
27
28
  pixelTrackerDrift: () => pixelTrackerDrift,
28
29
  rememberCreativeDeliveryDiagnostics: () => rememberCreativeDeliveryDiagnostics,
30
+ rememberInferredFromIdFormatOption: () => rememberInferredFromIdFormatOption,
29
31
  rememberSellerDeclaredFormatOption: () => rememberSellerDeclaredFormatOption,
30
32
  rememberSellerFormatEvidence: () => rememberSellerFormatEvidence,
31
33
  rememberSynthesizedFormatOption: () => rememberSynthesizedFormatOption,
@@ -120,6 +122,7 @@ function getCreativeDeliveryDiagnostics(value) {
120
122
  const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
121
123
  const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
122
124
  const sellerDeclaredByDeclaration = /* @__PURE__ */ new WeakMap();
125
+ const inferredFromIdDeclarations = /* @__PURE__ */ new WeakSet();
123
126
  const sellerEvidenceByDeclaration = /* @__PURE__ */ new WeakMap();
124
127
  function rememberSellerFormatEvidence(declaration, evidence) {
125
128
  try {
@@ -151,12 +154,19 @@ function rememberSynthesizedFormatOption(declaration) {
151
154
  function isSynthesizedFormatOption(declaration) {
152
155
  return sellerDeclaredByDeclaration.get(declaration) === "synthesized";
153
156
  }
157
+ function rememberInferredFromIdFormatOption(declaration) {
158
+ inferredFromIdDeclarations.add(declaration);
159
+ }
160
+ function isInferredFromIdFormatOption(declaration) {
161
+ return inferredFromIdDeclarations.has(declaration);
162
+ }
154
163
  function concealLegacyFormatRefs(declaration) {
155
164
  const { v1_format_ref: refs, ...canonical } = declaration;
156
165
  const existingHidden = legacyRefsByDeclaration.get(declaration);
157
166
  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
158
167
  const declared = sellerDeclaredByDeclaration.get(declaration);
159
168
  if (declared !== void 0) sellerDeclaredByDeclaration.set(canonical, declared);
169
+ if (inferredFromIdDeclarations.has(declaration)) inferredFromIdDeclarations.add(canonical);
160
170
  const evidence = sellerEvidenceByDeclaration.get(declaration);
161
171
  if (evidence) sellerEvidenceByDeclaration.set(canonical, evidence);
162
172
  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
@@ -192,6 +202,7 @@ function transferLegacyCreativeMetadata(source, target) {
192
202
  if (selected) selectedOptionsByRefs.set(target, selected);
193
203
  const declared = sellerDeclaredByDeclaration.get(source);
194
204
  if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
205
+ if (inferredFromIdDeclarations.has(source)) inferredFromIdDeclarations.add(target);
195
206
  const evidence = sellerEvidenceByDeclaration.get(source);
196
207
  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
197
208
  }
@@ -202,6 +213,7 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
202
213
  transferCreativeDeliveryDiagnostics(source, target);
203
214
  const declared = sellerDeclaredByDeclaration.get(source);
204
215
  if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
216
+ if (inferredFromIdDeclarations.has(source)) inferredFromIdDeclarations.add(target);
205
217
  const evidence = sellerEvidenceByDeclaration.get(source);
206
218
  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
207
219
  const refs = legacyRefsByDeclaration.get(source);
@@ -243,10 +255,12 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
243
255
  concealSelectedFormatOptions,
244
256
  downgradePixelTracker,
245
257
  getCreativeDeliveryDiagnostics,
258
+ isInferredFromIdFormatOption,
246
259
  isSynthesizedFormatOption,
247
260
  legacyFormatRefsForDeclaration,
248
261
  pixelTrackerDrift,
249
262
  rememberCreativeDeliveryDiagnostics,
263
+ rememberInferredFromIdFormatOption,
250
264
  rememberSellerDeclaredFormatOption,
251
265
  rememberSellerFormatEvidence,
252
266
  rememberSynthesizedFormatOption,
@@ -81,6 +81,7 @@ function getCreativeDeliveryDiagnostics(value) {
81
81
  const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
82
82
  const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
83
83
  const sellerDeclaredByDeclaration = /* @__PURE__ */ new WeakMap();
84
+ const inferredFromIdDeclarations = /* @__PURE__ */ new WeakSet();
84
85
  const sellerEvidenceByDeclaration = /* @__PURE__ */ new WeakMap();
85
86
  function rememberSellerFormatEvidence(declaration, evidence) {
86
87
  try {
@@ -112,12 +113,19 @@ function rememberSynthesizedFormatOption(declaration) {
112
113
  function isSynthesizedFormatOption(declaration) {
113
114
  return sellerDeclaredByDeclaration.get(declaration) === "synthesized";
114
115
  }
116
+ function rememberInferredFromIdFormatOption(declaration) {
117
+ inferredFromIdDeclarations.add(declaration);
118
+ }
119
+ function isInferredFromIdFormatOption(declaration) {
120
+ return inferredFromIdDeclarations.has(declaration);
121
+ }
115
122
  function concealLegacyFormatRefs(declaration) {
116
123
  const { v1_format_ref: refs, ...canonical } = declaration;
117
124
  const existingHidden = legacyRefsByDeclaration.get(declaration);
118
125
  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
119
126
  const declared = sellerDeclaredByDeclaration.get(declaration);
120
127
  if (declared !== void 0) sellerDeclaredByDeclaration.set(canonical, declared);
128
+ if (inferredFromIdDeclarations.has(declaration)) inferredFromIdDeclarations.add(canonical);
121
129
  const evidence = sellerEvidenceByDeclaration.get(declaration);
122
130
  if (evidence) sellerEvidenceByDeclaration.set(canonical, evidence);
123
131
  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
@@ -153,6 +161,7 @@ function transferLegacyCreativeMetadata(source, target) {
153
161
  if (selected) selectedOptionsByRefs.set(target, selected);
154
162
  const declared = sellerDeclaredByDeclaration.get(source);
155
163
  if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
164
+ if (inferredFromIdDeclarations.has(source)) inferredFromIdDeclarations.add(target);
156
165
  const evidence = sellerEvidenceByDeclaration.get(source);
157
166
  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
158
167
  }
@@ -163,6 +172,7 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
163
172
  transferCreativeDeliveryDiagnostics(source, target);
164
173
  const declared = sellerDeclaredByDeclaration.get(source);
165
174
  if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
175
+ if (inferredFromIdDeclarations.has(source)) inferredFromIdDeclarations.add(target);
166
176
  const evidence = sellerEvidenceByDeclaration.get(source);
167
177
  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
168
178
  const refs = legacyRefsByDeclaration.get(source);
@@ -203,10 +213,12 @@ export {
203
213
  concealSelectedFormatOptions,
204
214
  downgradePixelTracker,
205
215
  getCreativeDeliveryDiagnostics,
216
+ isInferredFromIdFormatOption,
206
217
  isSynthesizedFormatOption,
207
218
  legacyFormatRefsForDeclaration,
208
219
  pixelTrackerDrift,
209
220
  rememberCreativeDeliveryDiagnostics,
221
+ rememberInferredFromIdFormatOption,
210
222
  rememberSellerDeclaredFormatOption,
211
223
  rememberSellerFormatEvidence,
212
224
  rememberSynthesizedFormatOption,
@@ -31,6 +31,17 @@ export interface CanonicalFormatLegacyRoute {
31
31
  format_kind: string;
32
32
  params?: unknown;
33
33
  };
34
+ /**
35
+ * `true` when the SDK guessed this option's `format_kind` and `params` from
36
+ * the legacy id's name (an AAO id alias or a registry id glob) at an agent
37
+ * URL other than the AAO reference creative agent. That agent owns its ids,
38
+ * so the guess may be wrong: `display_300x250` can be a third-party tag, not
39
+ * an image. Absent when a catalog entry, catalog snapshot or
40
+ * `legacyFormatConverter` declared the option. Compare a guessed option
41
+ * against the seller's own `format_options[]` only as a hint, or project
42
+ * with `authoritativeOnly: true` to skip guesses.
43
+ */
44
+ inferred_from_id?: true;
34
45
  }
35
46
  /** The direct canonical selector for a format option the seller did not declare. */
36
47
  export interface UndeclaredFormatOptionSelector {
@@ -31,6 +31,17 @@ export interface CanonicalFormatLegacyRoute {
31
31
  format_kind: string;
32
32
  params?: unknown;
33
33
  };
34
+ /**
35
+ * `true` when the SDK guessed this option's `format_kind` and `params` from
36
+ * the legacy id's name (an AAO id alias or a registry id glob) at an agent
37
+ * URL other than the AAO reference creative agent. That agent owns its ids,
38
+ * so the guess may be wrong: `display_300x250` can be a third-party tag, not
39
+ * an image. Absent when a catalog entry, catalog snapshot or
40
+ * `legacyFormatConverter` declared the option. Compare a guessed option
41
+ * against the seller's own `format_options[]` only as a hint, or project
42
+ * with `authoritativeOnly: true` to skip guesses.
43
+ */
44
+ inferred_from_id?: true;
34
45
  }
35
46
  /** The direct canonical selector for a format option the seller did not declare. */
36
47
  export interface UndeclaredFormatOptionSelector {
@@ -132,7 +132,8 @@ function legacyRoutesForProduct(productId, declarations, options = {}) {
132
132
  format_kind: selector.format_kind,
133
133
  ...selector.params !== void 0 && { params: selector.params }
134
134
  }
135
- }
135
+ },
136
+ ...(0, import_legacy_metadata.isInferredFromIdFormatOption)(declaration) && { inferred_from_id: true }
136
137
  }
137
138
  ];
138
139
  });