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

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 (209) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/client/core.d.mts +4 -0
  3. package/dist/lib/client/core.d.ts +4 -0
  4. package/dist/lib/client/core.js +13 -0
  5. package/dist/lib/client/core.mjs +12 -0
  6. package/dist/lib/conformance/property-lists.d.mts +1 -1
  7. package/dist/lib/conformance/property-lists.d.ts +1 -1
  8. package/dist/lib/conformance/property-lists.js +1 -1
  9. package/dist/lib/conformance/property-lists.mjs +1 -1
  10. package/dist/lib/core/SingleAgentClient.d.mts +10 -1
  11. package/dist/lib/core/SingleAgentClient.d.ts +10 -1
  12. package/dist/lib/core/SingleAgentClient.js +56 -7
  13. package/dist/lib/core/SingleAgentClient.mjs +61 -7
  14. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  15. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  16. package/dist/lib/core/targeting-helpers.js +412 -0
  17. package/dist/lib/core/targeting-helpers.mjs +370 -0
  18. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  19. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  20. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  21. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  22. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  23. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  24. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  25. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  26. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  27. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  28. package/dist/lib/entrypoints/discovery.js +72 -0
  29. package/dist/lib/entrypoints/discovery.mjs +56 -0
  30. package/dist/lib/entrypoints/errors.d.mts +11 -0
  31. package/dist/lib/entrypoints/errors.d.ts +11 -0
  32. package/dist/lib/entrypoints/errors.js +159 -0
  33. package/dist/lib/entrypoints/errors.mjs +132 -0
  34. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  35. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  36. package/dist/lib/entrypoints/media-buy.js +119 -0
  37. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  38. package/dist/lib/entrypoints/registry.d.mts +5 -0
  39. package/dist/lib/entrypoints/registry.d.ts +5 -0
  40. package/dist/lib/entrypoints/registry.js +61 -0
  41. package/dist/lib/entrypoints/registry.mjs +40 -0
  42. package/dist/lib/entrypoints/utils.d.mts +7 -0
  43. package/dist/lib/entrypoints/utils.d.ts +7 -0
  44. package/dist/lib/entrypoints/utils.js +100 -0
  45. package/dist/lib/entrypoints/utils.mjs +72 -0
  46. package/dist/lib/entrypoints/version.d.mts +3 -0
  47. package/dist/lib/entrypoints/version.d.ts +3 -0
  48. package/dist/lib/entrypoints/version.js +57 -0
  49. package/dist/lib/entrypoints/version.mjs +36 -0
  50. package/dist/lib/index.d.mts +1 -1
  51. package/dist/lib/index.d.ts +1 -1
  52. package/dist/lib/media-buy/action-contracts.js +3 -3
  53. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  54. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  55. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  56. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  57. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  58. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  59. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  60. package/dist/lib/media-buy/valid-actions.js +42 -0
  61. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  62. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  63. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  64. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  65. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  66. package/dist/lib/registry/types.generated.d.ts +18 -2
  67. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  68. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  69. package/dist/lib/reporting/ledger/index.js +3 -1
  70. package/dist/lib/reporting/ledger/index.mjs +1 -0
  71. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  72. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  73. package/dist/lib/reporting/ledger/instant.js +10 -0
  74. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  75. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  76. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  77. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  78. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  79. package/dist/lib/reporting/service/index.d.mts +36 -1
  80. package/dist/lib/reporting/service/index.d.ts +36 -1
  81. package/dist/lib/reporting/service/index.js +51 -1
  82. package/dist/lib/reporting/service/index.mjs +52 -2
  83. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  84. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  85. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  86. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  87. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  88. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  89. package/dist/lib/server/capabilities-release-projection.js +128 -0
  90. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  91. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  92. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  93. package/dist/lib/server/create-adcp-server.js +95 -22
  94. package/dist/lib/server/create-adcp-server.mjs +106 -21
  95. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  96. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  97. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  98. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  99. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  100. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  101. package/dist/lib/server/declared-input-schema.js +167 -0
  102. package/dist/lib/server/declared-input-schema.mjs +137 -0
  103. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  104. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  105. package/dist/lib/server/envelope-allowlist.js +3 -79
  106. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  107. package/dist/lib/server/errors.d.mts +1 -186
  108. package/dist/lib/server/errors.d.ts +1 -186
  109. package/dist/lib/server/errors.js +3 -98
  110. package/dist/lib/server/errors.mjs +1 -94
  111. package/dist/lib/server/index.d.mts +1 -1
  112. package/dist/lib/server/index.d.ts +1 -1
  113. package/dist/lib/server/mcp-modern-server.js +21 -4
  114. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  115. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  116. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  117. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  118. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  119. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  120. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  121. package/dist/lib/server/media-buy-helpers.js +3 -23
  122. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  123. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  124. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  125. package/dist/lib/server/pick-safe-details.js +3 -61
  126. package/dist/lib/server/pick-safe-details.mjs +1 -56
  127. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  128. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  129. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  130. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  131. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  132. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  133. package/dist/lib/server/targeting-helpers.js +3 -393
  134. package/dist/lib/server/targeting-helpers.mjs +1 -370
  135. package/dist/lib/server/test-controller.js +7 -3
  136. package/dist/lib/server/test-controller.mjs +7 -3
  137. package/dist/lib/storage/memory-ledger.js +219 -1
  138. package/dist/lib/storage/memory-ledger.mjs +223 -1
  139. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  140. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  141. package/dist/lib/testing/comply-controller.js +7 -2
  142. package/dist/lib/testing/comply-controller.mjs +7 -2
  143. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  144. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  145. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  146. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  147. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  148. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  149. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  150. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  151. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  152. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  153. package/dist/lib/testing/storyboard/runner.js +2 -2
  154. package/dist/lib/testing/storyboard/runner.mjs +2 -2
  155. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  156. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  157. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  158. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  159. package/dist/lib/utils/adcp-error-response.js +118 -0
  160. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  161. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  162. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  163. package/dist/lib/utils/capabilities.d.mts +6 -0
  164. package/dist/lib/utils/capabilities.d.ts +6 -0
  165. package/dist/lib/utils/capabilities.js +6 -2
  166. package/dist/lib/utils/capabilities.mjs +6 -2
  167. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  168. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  169. package/dist/lib/utils/envelope-allowlist.js +98 -0
  170. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  171. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  172. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  173. package/dist/lib/utils/pick-safe-details.js +80 -0
  174. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  175. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  176. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  177. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  178. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  179. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  180. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  181. package/dist/lib/v2/projection/index.d.mts +2 -2
  182. package/dist/lib/v2/projection/index.d.ts +2 -2
  183. package/dist/lib/v2/projection/index.js +4 -0
  184. package/dist/lib/v2/projection/index.mjs +5 -1
  185. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  186. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  187. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  188. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  189. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  190. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  191. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  192. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  193. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  194. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  195. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  196. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  197. package/dist/lib/version.d.mts +3 -3
  198. package/dist/lib/version.d.ts +3 -3
  199. package/dist/lib/version.js +3 -3
  200. package/dist/lib/version.mjs +3 -3
  201. package/docs/TYPE-SUMMARY.md +2 -2
  202. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  203. package/docs/guides/REPORTING-LEDGER.md +121 -0
  204. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  205. package/docs/llms.txt +2 -2
  206. package/docs/migration-14.x-rc-worksheet.md +4 -4
  207. package/docs/migration-16-to-17.md +149 -0
  208. package/docs/migration-reporting-storage-package.md +10 -0
  209. package/package.json +106 -1
@@ -0,0 +1,196 @@
1
+ /**
2
+ * Server-side helpers for producing L3-compliant AdCP error responses.
3
+ *
4
+ * Use `adcpError()` in MCP tool handlers to return structured errors
5
+ * that clients can automatically detect, classify, and act on.
6
+ */
7
+ import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes';
8
+ import type { ValidationIssue } from '../validation/schema-validator';
9
+ export interface AdcpErrorOptions {
10
+ message: string;
11
+ /**
12
+ * Opaque request context to echo beside `adcp_error`. Only a non-null,
13
+ * non-array object is echoable, matching the framework envelope behavior.
14
+ */
15
+ context?: unknown;
16
+ /**
17
+ * Override the recovery classification. Defaults to
18
+ * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
19
+ * otherwise. Dropped from the wire shape for codes whose entry in
20
+ * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the
21
+ * standard table value for allowlisted standard-code envelopes.
22
+ */
23
+ recovery?: ErrorRecovery;
24
+ /**
25
+ * Name of the request field the error applies to (validation /
26
+ * constraint errors). Dropped from the wire shape for codes whose
27
+ * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`
28
+ * — a conflict response MUST NOT echo prior payload state).
29
+ */
30
+ field?: string;
31
+ /**
32
+ * Human-readable remediation hint. Dropped from the wire shape for
33
+ * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.
34
+ * `IDEMPOTENCY_CONFLICT`).
35
+ */
36
+ suggestion?: string;
37
+ /**
38
+ * Seconds to wait before retrying a transient error. Only meaningful
39
+ * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped
40
+ * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`
41
+ * — a computed `retry_after` on conflict would leak cached-entry age).
42
+ */
43
+ retry_after?: number;
44
+ /**
45
+ * Code-specific diagnostic payload. Dropped from the wire shape for
46
+ * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it
47
+ * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the
48
+ * prior request payload or cached response body).
49
+ */
50
+ details?: Record<string, unknown>;
51
+ /**
52
+ * Schema validation issues surfaced at the top level of `adcp_error`
53
+ * so operators see JSON Pointers on the first render. Primary use is
54
+ * `VALIDATION_ERROR`; framework validation hooks populate this
55
+ * automatically and also mirror the same array to `details.issues`
56
+ * for buyers that already index into `details` per AdCP spec
57
+ * convention.
58
+ */
59
+ issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
60
+ schemaPath?: string;
61
+ }>;
62
+ /**
63
+ * Buyer-actionable classification. Populate when the top-level `code`
64
+ * is coarse or producer-internal and a buyer-safe `{code, message}` pair
65
+ * (drawn from the standard error vocabulary) would give the buyer's
66
+ * agent something to act on. Per AdCP 3.2 `core/error.json`, `message`
67
+ * MUST be safe to show to the buyer — no vendor identifiers, ad-server
68
+ * type names, internal object names, internal IDs, or stack traces. The
69
+ * envelope allowlist for `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_IN_FLIGHT`
70
+ * drops this key — those codes are wire-shape-restricted and never carry
71
+ * a buyer-actionable classification.
72
+ */
73
+ buyer_reason?: {
74
+ code: string;
75
+ message: string;
76
+ };
77
+ /**
78
+ * Whether the failed state-changing request changed seller state (AdCP 3.3
79
+ * `error.mutation_outcome`). Set `'not_applied'` only with pre-commit
80
+ * evidence: a typed rejection raised before the idempotency claim and
81
+ * before any write. Leave it unset to make no claim.
82
+ */
83
+ mutation_outcome?: AdcpMutationOutcome;
84
+ }
85
+ /** AdCP 3.3 `error.mutation_outcome` values. */
86
+ export type AdcpMutationOutcome = 'not_applied' | 'unknown' | 'applied';
87
+ export interface AdcpErrorPayload {
88
+ code: string;
89
+ message: string;
90
+ /**
91
+ * Closed-enum classifier. Populated by `adcpError()` from
92
+ * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
93
+ * override. Marked optional because per-code inside-`adcp_error`
94
+ * allowlists may deliberately drop it from the wire shape — consumers
95
+ * reading a payload parsed off the wire MUST tolerate `undefined`.
96
+ */
97
+ recovery?: ErrorRecovery;
98
+ field?: string;
99
+ suggestion?: string;
100
+ retry_after?: number;
101
+ details?: Record<string, unknown>;
102
+ /**
103
+ * Schema validation issues (`VALIDATION_ERROR`) exposed at the top
104
+ * level so the list is the first thing a reader sees when inspecting
105
+ * the envelope. Also mirrored at `details.issues` for spec-convention
106
+ * compatibility.
107
+ */
108
+ issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
109
+ schemaPath?: string;
110
+ }>;
111
+ /**
112
+ * Buyer-actionable classification of the failure. See
113
+ * {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
114
+ */
115
+ buyer_reason?: {
116
+ code: string;
117
+ message: string;
118
+ };
119
+ mutation_outcome?: AdcpMutationOutcome;
120
+ }
121
+ export interface AdcpErrorResponse {
122
+ [key: string]: unknown;
123
+ content: Array<{
124
+ type: 'text';
125
+ text: string;
126
+ }>;
127
+ isError: true;
128
+ structuredContent: {
129
+ adcp_error: AdcpErrorPayload;
130
+ context?: object;
131
+ };
132
+ }
133
+ /**
134
+ * Build an L3-compliant MCP tool error response with all three transport layers:
135
+ *
136
+ * 1. `structuredContent.adcp_error` — programmatic extraction (L3)
137
+ * 2. `content[0].text` — JSON text fallback (L2)
138
+ * 3. `isError: true` — MCP error signal
139
+ *
140
+ * Recovery is auto-populated from the standard error code table when not provided.
141
+ *
142
+ * Before returning, any field NOT allowlisted for the given code in
143
+ * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
144
+ * ergonomics for every code AND the strict wire shape for codes that have
145
+ * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
146
+ * payload-shaped diagnostics like `field`, `suggestion`, and `details`
147
+ * silently drop while standard `recovery` metadata is preserved as the
148
+ * canonical standard-table value. Codes without a registered allowlist
149
+ * pass through unchanged.
150
+ *
151
+ * **Two-layer wire shape.** This builder emits the envelope layer
152
+ * (`structuredContent.adcp_error`) only. For tools whose response
153
+ * schema declares a typed Error arm (`errors[]` required at the top
154
+ * level), the framework dispatcher synthesises the payload-layer
155
+ * `errors[]` from the same data at finalize time, so the wire carries
156
+ * both the envelope marker and the typed Error arm together — no
157
+ * adopter code change required. The list of affected tools is derived
158
+ * at server build from the bundled schema cache. RFC:
159
+ * `docs/proposals/adcperror-two-layer-emission.md`.
160
+ *
161
+ * @example
162
+ * ```typescript
163
+ * import { adcpError } from '@adcp/sdk';
164
+ *
165
+ * server.registerTool("get_products", { inputSchema: schema }, async request => {
166
+ * const { query, context } = request;
167
+ * if (!products.length) {
168
+ * return adcpError('PRODUCT_NOT_FOUND', {
169
+ * message: 'No products match query',
170
+ * field: 'query',
171
+ * suggestion: 'Try a broader search term',
172
+ * context,
173
+ * });
174
+ * }
175
+ * return { content: [...], structuredContent: { products, context } };
176
+ * });
177
+ * ```
178
+ */
179
+ export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
180
+ /**
181
+ * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
182
+ * When an allowlisted standard code carries `recovery`, normalize it to
183
+ * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
184
+ * caller-supplied value.
185
+ * Codes without an entry pass through unchanged — the allowlist is
186
+ * opt-in per code, not a global filter. The returned object is re-typed
187
+ * as `AdcpErrorPayload` on the assumption that `code` and `message`
188
+ * (the only required fields) are in every registered allowlist; that
189
+ * invariant is re-asserted at runtime by the module-load check in
190
+ * `envelope-allowlist.ts`.
191
+ */
192
+ export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
193
+ export declare function sanitizeStructuredAdcpError<T extends {
194
+ code: string;
195
+ message: string;
196
+ }>(error: T): T;
@@ -0,0 +1,118 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+ var adcp_error_response_exports = {};
20
+ __export(adcp_error_response_exports, {
21
+ adcpError: () => adcpError,
22
+ applyAdcpErrorAllowlist: () => applyAdcpErrorAllowlist,
23
+ sanitizeStructuredAdcpError: () => sanitizeStructuredAdcpError
24
+ });
25
+ module.exports = __toCommonJS(adcp_error_response_exports);
26
+ var import_error_codes = require('../types/error-codes.js');
27
+ var import_envelope_allowlist = require('./envelope-allowlist.js');
28
+ var import_pick_safe_details = require('./pick-safe-details.js');
29
+ function isEchoableContext(value) {
30
+ return value !== null && typeof value === "object" && !Array.isArray(value);
31
+ }
32
+ const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
33
+ "required_connections",
34
+ "missing_connections",
35
+ "provider",
36
+ "connection_type",
37
+ "required_for",
38
+ "scope",
39
+ "status",
40
+ "resource_ref",
41
+ "platform_account_id",
42
+ "identity_id",
43
+ "handle",
44
+ "profile_url",
45
+ "post_id",
46
+ "post_url",
47
+ "authorization_url",
48
+ "authorization_instructions",
49
+ "checked_at",
50
+ "expires_at",
51
+ "reference_authorization"
52
+ ];
53
+ function adcpError(code, options) {
54
+ const recovery = normalizeRecoveryForCode(code, options.recovery);
55
+ const adcp_error = {
56
+ code,
57
+ message: options.message,
58
+ recovery,
59
+ ...options.field != null && { field: options.field },
60
+ ...options.suggestion != null && { suggestion: options.suggestion },
61
+ ...options.retry_after != null && { retry_after: options.retry_after },
62
+ ...options.issues != null && { issues: options.issues },
63
+ ...options.details != null && { details: options.details },
64
+ ...options.buyer_reason != null && { buyer_reason: options.buyer_reason },
65
+ ...options.mutation_outcome != null && { mutation_outcome: options.mutation_outcome }
66
+ };
67
+ const filtered = applyAdcpErrorAllowlist(code, adcp_error);
68
+ const structuredContent = {
69
+ adcp_error: filtered,
70
+ ...isEchoableContext(options.context) ? { context: options.context } : {}
71
+ };
72
+ return {
73
+ content: [{ type: "text", text: JSON.stringify(structuredContent) }],
74
+ isError: true,
75
+ structuredContent
76
+ };
77
+ }
78
+ function applyAdcpErrorAllowlist(code, payload) {
79
+ payload = sanitizeAdcpErrorDetails(code, payload);
80
+ const allowlist = import_envelope_allowlist.ADCP_ERROR_FIELD_ALLOWLIST[code];
81
+ if (!allowlist) return payload;
82
+ const out = {};
83
+ for (const [key, value] of Object.entries(payload)) {
84
+ if (!allowlist.has(key)) continue;
85
+ out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
86
+ }
87
+ return out;
88
+ }
89
+ function sanitizeStructuredAdcpError(error) {
90
+ return applyAdcpErrorAllowlist(error.code, error);
91
+ }
92
+ function sanitizeAdcpErrorDetails(code, payload) {
93
+ if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
94
+ const sanitizedDetails = (0, import_pick_safe_details.pickSafeDetails)(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
95
+ maxDepth: 4,
96
+ maxSizeBytes: 4096
97
+ });
98
+ const { details: _details, ...rest } = payload;
99
+ return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
100
+ }
101
+ function isErrorRecovery(value) {
102
+ return value === "transient" || value === "correctable" || value === "terminal";
103
+ }
104
+ function normalizeRecoveryForCode(code, value) {
105
+ return isErrorRecovery(value) ? value : (0, import_error_codes.isStandardErrorCode)(code) ? import_error_codes.STANDARD_ERROR_CODES[code].recovery : "terminal";
106
+ }
107
+ function normalizeAllowlistedRecoveryForCode(code, value) {
108
+ if ((0, import_error_codes.isStandardErrorCode)(code)) {
109
+ return import_error_codes.STANDARD_ERROR_CODES[code].recovery;
110
+ }
111
+ return normalizeRecoveryForCode(code, value);
112
+ }
113
+ // Annotate the CommonJS export names for ESM import in node:
114
+ 0 && (module.exports = {
115
+ adcpError,
116
+ applyAdcpErrorAllowlist,
117
+ sanitizeStructuredAdcpError
118
+ });
@@ -0,0 +1,95 @@
1
+ import {
2
+ STANDARD_ERROR_CODES,
3
+ isStandardErrorCode
4
+ } from "../types/error-codes.mjs";
5
+ import { ADCP_ERROR_FIELD_ALLOWLIST } from "./envelope-allowlist.mjs";
6
+ import { pickSafeDetails } from "./pick-safe-details.mjs";
7
+ function isEchoableContext(value) {
8
+ return value !== null && typeof value === "object" && !Array.isArray(value);
9
+ }
10
+ const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
11
+ "required_connections",
12
+ "missing_connections",
13
+ "provider",
14
+ "connection_type",
15
+ "required_for",
16
+ "scope",
17
+ "status",
18
+ "resource_ref",
19
+ "platform_account_id",
20
+ "identity_id",
21
+ "handle",
22
+ "profile_url",
23
+ "post_id",
24
+ "post_url",
25
+ "authorization_url",
26
+ "authorization_instructions",
27
+ "checked_at",
28
+ "expires_at",
29
+ "reference_authorization"
30
+ ];
31
+ function adcpError(code, options) {
32
+ const recovery = normalizeRecoveryForCode(code, options.recovery);
33
+ const adcp_error = {
34
+ code,
35
+ message: options.message,
36
+ recovery,
37
+ ...options.field != null && { field: options.field },
38
+ ...options.suggestion != null && { suggestion: options.suggestion },
39
+ ...options.retry_after != null && { retry_after: options.retry_after },
40
+ ...options.issues != null && { issues: options.issues },
41
+ ...options.details != null && { details: options.details },
42
+ ...options.buyer_reason != null && { buyer_reason: options.buyer_reason },
43
+ ...options.mutation_outcome != null && { mutation_outcome: options.mutation_outcome }
44
+ };
45
+ const filtered = applyAdcpErrorAllowlist(code, adcp_error);
46
+ const structuredContent = {
47
+ adcp_error: filtered,
48
+ ...isEchoableContext(options.context) ? { context: options.context } : {}
49
+ };
50
+ return {
51
+ content: [{ type: "text", text: JSON.stringify(structuredContent) }],
52
+ isError: true,
53
+ structuredContent
54
+ };
55
+ }
56
+ function applyAdcpErrorAllowlist(code, payload) {
57
+ payload = sanitizeAdcpErrorDetails(code, payload);
58
+ const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];
59
+ if (!allowlist) return payload;
60
+ const out = {};
61
+ for (const [key, value] of Object.entries(payload)) {
62
+ if (!allowlist.has(key)) continue;
63
+ out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
64
+ }
65
+ return out;
66
+ }
67
+ function sanitizeStructuredAdcpError(error) {
68
+ return applyAdcpErrorAllowlist(error.code, error);
69
+ }
70
+ function sanitizeAdcpErrorDetails(code, payload) {
71
+ if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
72
+ const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
73
+ maxDepth: 4,
74
+ maxSizeBytes: 4096
75
+ });
76
+ const { details: _details, ...rest } = payload;
77
+ return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
78
+ }
79
+ function isErrorRecovery(value) {
80
+ return value === "transient" || value === "correctable" || value === "terminal";
81
+ }
82
+ function normalizeRecoveryForCode(code, value) {
83
+ return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : "terminal";
84
+ }
85
+ function normalizeAllowlistedRecoveryForCode(code, value) {
86
+ if (isStandardErrorCode(code)) {
87
+ return STANDARD_ERROR_CODES[code].recovery;
88
+ }
89
+ return normalizeRecoveryForCode(code, value);
90
+ }
91
+ export {
92
+ adcpError,
93
+ applyAdcpErrorAllowlist,
94
+ sanitizeStructuredAdcpError
95
+ };
@@ -22,7 +22,7 @@ __export(buyer_retry_policy_exports, {
22
22
  decideRetry: () => decideRetry
23
23
  });
24
24
  module.exports = __toCommonJS(buyer_retry_policy_exports);
25
- var import_errors = require('../server/errors.js');
25
+ var import_adcp_error_response = require('./adcp-error-response.js');
26
26
  var import_error_codes = require('../types/error-codes.js');
27
27
  const EXPLICIT_CODE_POLICY = {
28
28
  // Transients — server-side, retry-safe with same idempotency_key.
@@ -218,7 +218,7 @@ function isRecord(value) {
218
218
  }
219
219
  function authorizationRequiredEscalationContext(error) {
220
220
  if (error.code !== "AUTHORIZATION_REQUIRED" || error.details === void 0) return {};
221
- const sanitized = (0, import_errors.applyAdcpErrorAllowlist)("AUTHORIZATION_REQUIRED", {
221
+ const sanitized = (0, import_adcp_error_response.applyAdcpErrorAllowlist)("AUTHORIZATION_REQUIRED", {
222
222
  code: error.code,
223
223
  message: error.message,
224
224
  recovery: error.recovery,
@@ -1,4 +1,4 @@
1
- import { applyAdcpErrorAllowlist } from "../server/errors.mjs";
1
+ import { applyAdcpErrorAllowlist } from "./adcp-error-response.mjs";
2
2
  import { STANDARD_ERROR_CODES } from "../types/error-codes.mjs";
3
3
  const EXPLICIT_CODE_POLICY = {
4
4
  // Transients — server-side, retry-safe with same idempotency_key.
@@ -45,6 +45,12 @@ export interface MediaBuyFeatures {
45
45
  conversionTracking?: boolean;
46
46
  /** Agent supports first-party CRM audience management (sync_audiences) */
47
47
  audienceTargeting?: boolean;
48
+ /**
49
+ * AdCP 3.3: seller honors `packages[].start_requires_all_creatives_approved:
50
+ * true` on `control_media_buy`. Without it, sellers refuse `true` with
51
+ * `UNSUPPORTED_FEATURE` and buyers must not send it. Absent means undeclared.
52
+ */
53
+ creativeStartPolicy?: boolean;
48
54
  }
49
55
  /**
50
56
  * Account management capabilities declared by the seller
@@ -45,6 +45,12 @@ export interface MediaBuyFeatures {
45
45
  conversionTracking?: boolean;
46
46
  /** Agent supports first-party CRM audience management (sync_audiences) */
47
47
  audienceTargeting?: boolean;
48
+ /**
49
+ * AdCP 3.3: seller honors `packages[].start_requires_all_creatives_approved:
50
+ * true` on `control_media_buy`. Without it, sellers refuse `true` with
51
+ * `UNSUPPORTED_FEATURE` and buyers must not send it. Absent means undeclared.
52
+ */
53
+ creativeStartPolicy?: boolean;
48
54
  }
49
55
  /**
50
56
  * Account management capabilities declared by the seller
@@ -293,7 +293,10 @@ function parseCapabilitiesResponse(response) {
293
293
  propertyListFiltering: response.media_buy?.features?.property_list_filtering ?? false,
294
294
  contentStandards: response.media_buy?.features?.content_standards === true || declaresContentStandardsSpecialism,
295
295
  conversionTracking: response.media_buy?.features?.conversion_tracking ?? false,
296
- audienceTargeting: response.media_buy?.features?.audience_targeting ?? false
296
+ audienceTargeting: response.media_buy?.features?.audience_targeting ?? false,
297
+ ...typeof response.media_buy?.features?.creative_start_policy === "boolean" && {
298
+ creativeStartPolicy: response.media_buy.features.creative_start_policy
299
+ }
297
300
  };
298
301
  let account;
299
302
  if (response.account) {
@@ -480,8 +483,9 @@ const FEATURE_KEY_MAP = {
480
483
  content_standards: "contentStandards",
481
484
  conversion_tracking: "conversionTracking",
482
485
  audience_targeting: "audienceTargeting",
483
- audience_management: "audienceTargeting"
486
+ audience_management: "audienceTargeting",
484
487
  // legacy alias
488
+ creative_start_policy: "creativeStartPolicy"
485
489
  };
486
490
  function resolveFeature(capabilities, feature) {
487
491
  if (capabilities.protocols.includes(feature)) {
@@ -238,7 +238,10 @@ function parseCapabilitiesResponse(response) {
238
238
  propertyListFiltering: response.media_buy?.features?.property_list_filtering ?? false,
239
239
  contentStandards: response.media_buy?.features?.content_standards === true || declaresContentStandardsSpecialism,
240
240
  conversionTracking: response.media_buy?.features?.conversion_tracking ?? false,
241
- audienceTargeting: response.media_buy?.features?.audience_targeting ?? false
241
+ audienceTargeting: response.media_buy?.features?.audience_targeting ?? false,
242
+ ...typeof response.media_buy?.features?.creative_start_policy === "boolean" && {
243
+ creativeStartPolicy: response.media_buy.features.creative_start_policy
244
+ }
242
245
  };
243
246
  let account;
244
247
  if (response.account) {
@@ -425,8 +428,9 @@ const FEATURE_KEY_MAP = {
425
428
  content_standards: "contentStandards",
426
429
  conversion_tracking: "conversionTracking",
427
430
  audience_targeting: "audienceTargeting",
428
- audience_management: "audienceTargeting"
431
+ audience_management: "audienceTargeting",
429
432
  // legacy alias
433
+ creative_start_policy: "creativeStartPolicy"
430
434
  };
431
435
  function resolveFeature(capabilities, feature) {
432
436
  if (capabilities.protocols.includes(feature)) {
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Envelope-allowlist governance for AdCP error responses.
3
+ *
4
+ * Two orthogonal concerns both govern what round-trips on an AdCP error
5
+ * envelope. They live side-by-side here so that a change to one forces
6
+ * the reviewer to weigh the other (security review M4 on #788 — the
7
+ * pair is conceptually related and can drift in separate files).
8
+ *
9
+ * - `ERROR_ENVELOPE_FIELD_ALLOWLIST` governs keys that may appear as
10
+ * SIBLINGS of `adcp_error` on the wire response. Enforced by
11
+ * `wrapEnvelope` in `./wrap-envelope.ts`.
12
+ * - `ADCP_ERROR_FIELD_ALLOWLIST` governs keys that may appear INSIDE
13
+ * the `adcp_error` block, keyed by error code. Consumed by
14
+ * `adcpError()` (which filters its output to the allowlisted set)
15
+ * AND by the dispatcher in `create-adcp-server.ts` (re-applied to
16
+ * every handler-returned envelope via `sanitizeAdcpErrorEnvelope`
17
+ * — defence-in-depth for handlers that hand-roll an error envelope
18
+ * instead of going through the builder). The same set powers the
19
+ * `idempotency.conflict_no_payload_leak` invariant in
20
+ * `../testing/storyboard/default-invariants.ts`. The legacy
21
+ * `CONFLICT_ADCP_ERROR_ALLOWLIST` export is a convenience alias for
22
+ * the `IDEMPOTENCY_CONFLICT` entry.
23
+ *
24
+ * Both sets apply to the same wire response but at different nesting
25
+ * levels. A seller that needs to extend one should audit whether the
26
+ * other also needs updating.
27
+ *
28
+ * Hand-rolling an error envelope? Prefer `adcpError(code, options)` —
29
+ * it wraps both transport layers and applies this allowlist for you.
30
+ * The dispatcher sanitizer is a belt-and-suspenders, not a primary API.
31
+ */
32
+ /**
33
+ * Fail-closed default allowlist for unknown error codes.
34
+ *
35
+ * An error code without an explicit entry in
36
+ * `ERROR_ENVELOPE_FIELD_ALLOWLIST` gets this set — only `context`
37
+ * round-trips (matching the invariant that every allowlist permits
38
+ * correlation tracing). Sellers that want `replayed` or `operation_id`
39
+ * on a bespoke error code must register it explicitly.
40
+ *
41
+ * This is the fail-closed posture — sellers MUST opt in to any field
42
+ * they want on an error envelope, rather than inheriting success-path
43
+ * semantics by default. Security review M3 on #788.
44
+ */
45
+ export declare const DEFAULT_ERROR_ENVELOPE_FIELDS: ReadonlySet<string>;
46
+ /**
47
+ * Per-error-code envelope-field allowlist.
48
+ *
49
+ * A code listed here restricts which envelope fields `wrapEnvelope`
50
+ * will attach on top of the error's inner payload. Codes NOT listed
51
+ * here receive `DEFAULT_ERROR_ENVELOPE_FIELDS` (fail-closed —
52
+ * `context` only).
53
+ *
54
+ * `IDEMPOTENCY_CONFLICT` deliberately excludes `replayed`: the
55
+ * conflict path in `create-adcp-server.ts` builds its error via
56
+ * `finalize()`, which only echoes `context` and never calls
57
+ * `stampReplayed`. The framework's own behavior is preserved.
58
+ *
59
+ * **Invariant**: every allowlist set MUST include `'context'`.
60
+ * `ensureContextEcho` enforces this at module load so new error codes
61
+ * can't accidentally drop context echo (which sellers rely on for
62
+ * correlation tracing across both success and error paths).
63
+ */
64
+ export declare const ERROR_ENVELOPE_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
65
+ /**
66
+ * Per-error-code allowlist for keys permitted INSIDE the `adcp_error`
67
+ * block. The `adcpError()` builder consults this table and drops any
68
+ * field the caller passes that isn't allowlisted for the given code —
69
+ * the allowlist IS the contract for what a framework-emitted error may
70
+ * carry. Storyboard invariants enforce the same contract on the wire.
71
+ *
72
+ * A code without an explicit entry permits everything `adcpError()`
73
+ * would otherwise emit — the default case is pass-through. Sellers who
74
+ * want a bespoke code to be strict should register it here (or wrap
75
+ * `adcpError()` with their own sanitizer).
76
+ *
77
+ * **Scope warning for future contributors:** only register a code here
78
+ * if it belongs to the AdCP standard error vocabulary (`enums/error-code.json`).
79
+ * Per `core/error.json`, clients "MUST handle unknown codes gracefully
80
+ * by falling back to the recovery classification" — so dropping
81
+ * `recovery` on a vendor / non-standard code makes the response
82
+ * genuinely lossy for any buyer agent that doesn't have the code in
83
+ * its local vocabulary.
84
+ *
85
+ * `IDEMPOTENCY_CONFLICT` is narrow on purpose: a conflict response MUST
86
+ * NOT echo the prior request payload or cached response (stolen-key
87
+ * read oracle defence). Standard recovery metadata is allowed because it
88
+ * is normalized to the fixed classifier, not trusted as caller-provided
89
+ * prior request or cached response data.
90
+ * `retry_after` is excluded: no framework path currently emits it on conflict, and a seller
91
+ * that computed `retry_after = cached_entry_age` would leak the prior
92
+ * payload's creation time (a distinguisher between "key never seen" vs
93
+ * "key seen N seconds ago"). Retry hints belong on transient codes
94
+ * (`SERVICE_UNAVAILABLE`, `RATE_LIMITED`), not on a terminal conflict.
95
+ * `adcpError()` and the dispatcher sanitizer both enforce this.
96
+ */
97
+ export declare const ADCP_ERROR_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
98
+ /**
99
+ * Convenience alias for the `IDEMPOTENCY_CONFLICT` entry in
100
+ * {@link ADCP_ERROR_FIELD_ALLOWLIST}. Kept as a named export because
101
+ * the default `idempotency.conflict_no_payload_leak` invariant and a
102
+ * handful of consumer tests reach for it by name; new code should use
103
+ * `ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT` directly.
104
+ */
105
+ export declare const CONFLICT_ADCP_ERROR_ALLOWLIST: ReadonlySet<string>;