@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
@@ -3,10 +3,6 @@ var __defProp = Object.defineProperty;
3
3
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
4
  var __getOwnPropNames = Object.getOwnPropertyNames;
5
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
6
  var __copyProps = (to, from, except, desc) => {
11
7
  if (from && typeof from === "object" || typeof from === "function") {
12
8
  for (let key of __getOwnPropNames(from))
@@ -15,84 +11,12 @@ var __copyProps = (to, from, except, desc) => {
15
11
  }
16
12
  return to;
17
13
  };
14
+ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
18
15
  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
16
  var envelope_allowlist_exports = {};
20
- __export(envelope_allowlist_exports, {
21
- ADCP_ERROR_FIELD_ALLOWLIST: () => ADCP_ERROR_FIELD_ALLOWLIST,
22
- CONFLICT_ADCP_ERROR_ALLOWLIST: () => CONFLICT_ADCP_ERROR_ALLOWLIST,
23
- DEFAULT_ERROR_ENVELOPE_FIELDS: () => DEFAULT_ERROR_ENVELOPE_FIELDS,
24
- ERROR_ENVELOPE_FIELD_ALLOWLIST: () => ERROR_ENVELOPE_FIELD_ALLOWLIST
25
- });
26
17
  module.exports = __toCommonJS(envelope_allowlist_exports);
27
- const DEFAULT_ERROR_ENVELOPE_FIELDS = Object.freeze(/* @__PURE__ */ new Set(["context"]));
28
- const ERROR_ENVELOPE_FIELD_ALLOWLIST = Object.freeze({
29
- // Spec-defined: conflict is not a replay; `replayed` intentionally
30
- // dropped. `operation_id` round-trips for async-op correlation.
31
- IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set(["context", "operation_id"]),
32
- // A cached purge result is itself the durable outcome. Replays MUST be
33
- // distinguishable without reopening the committed-resource lookup.
34
- COMMITTED_RESOURCE_PURGED: /* @__PURE__ */ new Set(["context", "replayed"])
35
- });
36
- const ADCP_ERROR_FIELD_ALLOWLIST = Object.freeze({
37
- IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set([
38
- "code",
39
- "message",
40
- "recovery",
41
- "status",
42
- "correlation_id",
43
- "request_id",
44
- "operation_id"
45
- ]),
46
- // `IDEMPOTENCY_IN_FLIGHT` (AdCP 3.1) carries `recovery: transient` plus a
47
- // store-derived `retry_after` so transient-aware buyer SDKs can replay
48
- // shortly. Allowlist registration is defense-in-depth — `adcpError()` at
49
- // the in-flight call site only assembles framework-controlled keys today,
50
- // but the registration forces any future caller that tries to attach
51
- // payload fingerprints onto the in-flight envelope to land here in code
52
- // review first.
53
- IDEMPOTENCY_IN_FLIGHT: /* @__PURE__ */ new Set([
54
- "code",
55
- "message",
56
- "recovery",
57
- "retry_after",
58
- "status",
59
- "correlation_id",
60
- "request_id",
61
- "operation_id"
62
- ])
63
- });
64
- const CONFLICT_ADCP_ERROR_ALLOWLIST = ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT;
65
- function ensureContextEcho(allowlist) {
66
- if (!DEFAULT_ERROR_ENVELOPE_FIELDS.has("context")) {
67
- throw new Error(
68
- "DEFAULT_ERROR_ENVELOPE_FIELDS must include 'context' so correlation ids can round-trip on error envelopes."
69
- );
70
- }
71
- for (const [code, fields] of Object.entries(allowlist)) {
72
- if (!fields.has("context")) {
73
- throw new Error(
74
- `ERROR_ENVELOPE_FIELD_ALLOWLIST['${code}'] is missing 'context'. Every error-code allowlist must include 'context' so correlation ids can round-trip on error envelopes.`
75
- );
76
- }
77
- }
78
- }
79
- ensureContextEcho(ERROR_ENVELOPE_FIELD_ALLOWLIST);
80
- function ensureCoreAdcpErrorFields(allowlist) {
81
- for (const [code, fields] of Object.entries(allowlist)) {
82
- for (const required of ["code", "message"]) {
83
- if (!fields.has(required)) {
84
- throw new Error(
85
- `ADCP_ERROR_FIELD_ALLOWLIST['${code}'] is missing '${required}'. Every inside-adcp_error allowlist must include 'code' and 'message' \u2014 they are the only two required fields on the AdCP error schema.`
86
- );
87
- }
88
- }
89
- }
90
- }
91
- ensureCoreAdcpErrorFields(ADCP_ERROR_FIELD_ALLOWLIST);
18
+ __reExport(envelope_allowlist_exports, require('../utils/envelope-allowlist.js'), module.exports);
92
19
  // Annotate the CommonJS export names for ESM import in node:
93
20
  0 && (module.exports = {
94
- ADCP_ERROR_FIELD_ALLOWLIST,
95
- CONFLICT_ADCP_ERROR_ALLOWLIST,
96
- DEFAULT_ERROR_ENVELOPE_FIELDS,
97
- ERROR_ENVELOPE_FIELD_ALLOWLIST
21
+ ...require('../utils/envelope-allowlist.js')
98
22
  });
@@ -1,71 +1 @@
1
- const DEFAULT_ERROR_ENVELOPE_FIELDS = Object.freeze(/* @__PURE__ */ new Set(["context"]));
2
- const ERROR_ENVELOPE_FIELD_ALLOWLIST = Object.freeze({
3
- // Spec-defined: conflict is not a replay; `replayed` intentionally
4
- // dropped. `operation_id` round-trips for async-op correlation.
5
- IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set(["context", "operation_id"]),
6
- // A cached purge result is itself the durable outcome. Replays MUST be
7
- // distinguishable without reopening the committed-resource lookup.
8
- COMMITTED_RESOURCE_PURGED: /* @__PURE__ */ new Set(["context", "replayed"])
9
- });
10
- const ADCP_ERROR_FIELD_ALLOWLIST = Object.freeze({
11
- IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set([
12
- "code",
13
- "message",
14
- "recovery",
15
- "status",
16
- "correlation_id",
17
- "request_id",
18
- "operation_id"
19
- ]),
20
- // `IDEMPOTENCY_IN_FLIGHT` (AdCP 3.1) carries `recovery: transient` plus a
21
- // store-derived `retry_after` so transient-aware buyer SDKs can replay
22
- // shortly. Allowlist registration is defense-in-depth — `adcpError()` at
23
- // the in-flight call site only assembles framework-controlled keys today,
24
- // but the registration forces any future caller that tries to attach
25
- // payload fingerprints onto the in-flight envelope to land here in code
26
- // review first.
27
- IDEMPOTENCY_IN_FLIGHT: /* @__PURE__ */ new Set([
28
- "code",
29
- "message",
30
- "recovery",
31
- "retry_after",
32
- "status",
33
- "correlation_id",
34
- "request_id",
35
- "operation_id"
36
- ])
37
- });
38
- const CONFLICT_ADCP_ERROR_ALLOWLIST = ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT;
39
- function ensureContextEcho(allowlist) {
40
- if (!DEFAULT_ERROR_ENVELOPE_FIELDS.has("context")) {
41
- throw new Error(
42
- "DEFAULT_ERROR_ENVELOPE_FIELDS must include 'context' so correlation ids can round-trip on error envelopes."
43
- );
44
- }
45
- for (const [code, fields] of Object.entries(allowlist)) {
46
- if (!fields.has("context")) {
47
- throw new Error(
48
- `ERROR_ENVELOPE_FIELD_ALLOWLIST['${code}'] is missing 'context'. Every error-code allowlist must include 'context' so correlation ids can round-trip on error envelopes.`
49
- );
50
- }
51
- }
52
- }
53
- ensureContextEcho(ERROR_ENVELOPE_FIELD_ALLOWLIST);
54
- function ensureCoreAdcpErrorFields(allowlist) {
55
- for (const [code, fields] of Object.entries(allowlist)) {
56
- for (const required of ["code", "message"]) {
57
- if (!fields.has(required)) {
58
- throw new Error(
59
- `ADCP_ERROR_FIELD_ALLOWLIST['${code}'] is missing '${required}'. Every inside-adcp_error allowlist must include 'code' and 'message' \u2014 they are the only two required fields on the AdCP error schema.`
60
- );
61
- }
62
- }
63
- }
64
- }
65
- ensureCoreAdcpErrorFields(ADCP_ERROR_FIELD_ALLOWLIST);
66
- export {
67
- ADCP_ERROR_FIELD_ALLOWLIST,
68
- CONFLICT_ADCP_ERROR_ALLOWLIST,
69
- DEFAULT_ERROR_ENVELOPE_FIELDS,
70
- ERROR_ENVELOPE_FIELD_ALLOWLIST
71
- };
1
+ export * from "../utils/envelope-allowlist.mjs";
@@ -1,186 +1 @@
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.mjs';
8
- import type { ValidationIssue } from '../validation/schema-validator.mjs';
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
- export interface AdcpErrorPayload {
79
- code: string;
80
- message: string;
81
- /**
82
- * Closed-enum classifier. Populated by `adcpError()` from
83
- * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
84
- * override. Marked optional because per-code inside-`adcp_error`
85
- * allowlists may deliberately drop it from the wire shape — consumers
86
- * reading a payload parsed off the wire MUST tolerate `undefined`.
87
- */
88
- recovery?: ErrorRecovery;
89
- field?: string;
90
- suggestion?: string;
91
- retry_after?: number;
92
- details?: Record<string, unknown>;
93
- /**
94
- * Schema validation issues (`VALIDATION_ERROR`) exposed at the top
95
- * level so the list is the first thing a reader sees when inspecting
96
- * the envelope. Also mirrored at `details.issues` for spec-convention
97
- * compatibility.
98
- */
99
- issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
100
- schemaPath?: string;
101
- }>;
102
- /**
103
- * Buyer-actionable classification of the failure. See
104
- * {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
105
- */
106
- buyer_reason?: {
107
- code: string;
108
- message: string;
109
- };
110
- }
111
- export interface AdcpErrorResponse {
112
- [key: string]: unknown;
113
- content: Array<{
114
- type: 'text';
115
- text: string;
116
- }>;
117
- isError: true;
118
- structuredContent: {
119
- adcp_error: AdcpErrorPayload;
120
- context?: object;
121
- };
122
- }
123
- /**
124
- * Build an L3-compliant MCP tool error response with all three transport layers:
125
- *
126
- * 1. `structuredContent.adcp_error` — programmatic extraction (L3)
127
- * 2. `content[0].text` — JSON text fallback (L2)
128
- * 3. `isError: true` — MCP error signal
129
- *
130
- * Recovery is auto-populated from the standard error code table when not provided.
131
- *
132
- * Before returning, any field NOT allowlisted for the given code in
133
- * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
134
- * ergonomics for every code AND the strict wire shape for codes that have
135
- * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
136
- * payload-shaped diagnostics like `field`, `suggestion`, and `details`
137
- * silently drop while standard `recovery` metadata is preserved as the
138
- * canonical standard-table value. Codes without a registered allowlist
139
- * pass through unchanged.
140
- *
141
- * **Two-layer wire shape.** This builder emits the envelope layer
142
- * (`structuredContent.adcp_error`) only. For tools whose response
143
- * schema declares a typed Error arm (`errors[]` required at the top
144
- * level), the framework dispatcher synthesises the payload-layer
145
- * `errors[]` from the same data at finalize time, so the wire carries
146
- * both the envelope marker and the typed Error arm together — no
147
- * adopter code change required. The list of affected tools is derived
148
- * at server build from the bundled schema cache. RFC:
149
- * `docs/proposals/adcperror-two-layer-emission.md`.
150
- *
151
- * @example
152
- * ```typescript
153
- * import { adcpError } from '@adcp/sdk';
154
- *
155
- * server.registerTool("get_products", { inputSchema: schema }, async request => {
156
- * const { query, context } = request;
157
- * if (!products.length) {
158
- * return adcpError('PRODUCT_NOT_FOUND', {
159
- * message: 'No products match query',
160
- * field: 'query',
161
- * suggestion: 'Try a broader search term',
162
- * context,
163
- * });
164
- * }
165
- * return { content: [...], structuredContent: { products, context } };
166
- * });
167
- * ```
168
- */
169
- export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
170
- /**
171
- * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
172
- * When an allowlisted standard code carries `recovery`, normalize it to
173
- * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
174
- * caller-supplied value.
175
- * Codes without an entry pass through unchanged — the allowlist is
176
- * opt-in per code, not a global filter. The returned object is re-typed
177
- * as `AdcpErrorPayload` on the assumption that `code` and `message`
178
- * (the only required fields) are in every registered allowlist; that
179
- * invariant is re-asserted at runtime by the module-load check in
180
- * `envelope-allowlist.ts`.
181
- */
182
- export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
183
- export declare function sanitizeStructuredAdcpError<T extends {
184
- code: string;
185
- message: string;
186
- }>(error: T): T;
1
+ export * from '../utils/adcp-error-response.mjs';
@@ -1,186 +1 @@
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
- export interface AdcpErrorPayload {
79
- code: string;
80
- message: string;
81
- /**
82
- * Closed-enum classifier. Populated by `adcpError()` from
83
- * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
84
- * override. Marked optional because per-code inside-`adcp_error`
85
- * allowlists may deliberately drop it from the wire shape — consumers
86
- * reading a payload parsed off the wire MUST tolerate `undefined`.
87
- */
88
- recovery?: ErrorRecovery;
89
- field?: string;
90
- suggestion?: string;
91
- retry_after?: number;
92
- details?: Record<string, unknown>;
93
- /**
94
- * Schema validation issues (`VALIDATION_ERROR`) exposed at the top
95
- * level so the list is the first thing a reader sees when inspecting
96
- * the envelope. Also mirrored at `details.issues` for spec-convention
97
- * compatibility.
98
- */
99
- issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
100
- schemaPath?: string;
101
- }>;
102
- /**
103
- * Buyer-actionable classification of the failure. See
104
- * {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
105
- */
106
- buyer_reason?: {
107
- code: string;
108
- message: string;
109
- };
110
- }
111
- export interface AdcpErrorResponse {
112
- [key: string]: unknown;
113
- content: Array<{
114
- type: 'text';
115
- text: string;
116
- }>;
117
- isError: true;
118
- structuredContent: {
119
- adcp_error: AdcpErrorPayload;
120
- context?: object;
121
- };
122
- }
123
- /**
124
- * Build an L3-compliant MCP tool error response with all three transport layers:
125
- *
126
- * 1. `structuredContent.adcp_error` — programmatic extraction (L3)
127
- * 2. `content[0].text` — JSON text fallback (L2)
128
- * 3. `isError: true` — MCP error signal
129
- *
130
- * Recovery is auto-populated from the standard error code table when not provided.
131
- *
132
- * Before returning, any field NOT allowlisted for the given code in
133
- * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
134
- * ergonomics for every code AND the strict wire shape for codes that have
135
- * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
136
- * payload-shaped diagnostics like `field`, `suggestion`, and `details`
137
- * silently drop while standard `recovery` metadata is preserved as the
138
- * canonical standard-table value. Codes without a registered allowlist
139
- * pass through unchanged.
140
- *
141
- * **Two-layer wire shape.** This builder emits the envelope layer
142
- * (`structuredContent.adcp_error`) only. For tools whose response
143
- * schema declares a typed Error arm (`errors[]` required at the top
144
- * level), the framework dispatcher synthesises the payload-layer
145
- * `errors[]` from the same data at finalize time, so the wire carries
146
- * both the envelope marker and the typed Error arm together — no
147
- * adopter code change required. The list of affected tools is derived
148
- * at server build from the bundled schema cache. RFC:
149
- * `docs/proposals/adcperror-two-layer-emission.md`.
150
- *
151
- * @example
152
- * ```typescript
153
- * import { adcpError } from '@adcp/sdk';
154
- *
155
- * server.registerTool("get_products", { inputSchema: schema }, async request => {
156
- * const { query, context } = request;
157
- * if (!products.length) {
158
- * return adcpError('PRODUCT_NOT_FOUND', {
159
- * message: 'No products match query',
160
- * field: 'query',
161
- * suggestion: 'Try a broader search term',
162
- * context,
163
- * });
164
- * }
165
- * return { content: [...], structuredContent: { products, context } };
166
- * });
167
- * ```
168
- */
169
- export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
170
- /**
171
- * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
172
- * When an allowlisted standard code carries `recovery`, normalize it to
173
- * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
174
- * caller-supplied value.
175
- * Codes without an entry pass through unchanged — the allowlist is
176
- * opt-in per code, not a global filter. The returned object is re-typed
177
- * as `AdcpErrorPayload` on the assumption that `code` and `message`
178
- * (the only required fields) are in every registered allowlist; that
179
- * invariant is re-asserted at runtime by the module-load check in
180
- * `envelope-allowlist.ts`.
181
- */
182
- export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
183
- export declare function sanitizeStructuredAdcpError<T extends {
184
- code: string;
185
- message: string;
186
- }>(error: T): T;
1
+ export * from '../utils/adcp-error-response';
@@ -3,10 +3,6 @@ var __defProp = Object.defineProperty;
3
3
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
4
  var __getOwnPropNames = Object.getOwnPropertyNames;
5
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
6
  var __copyProps = (to, from, except, desc) => {
11
7
  if (from && typeof from === "object" || typeof from === "function") {
12
8
  for (let key of __getOwnPropNames(from))
@@ -15,103 +11,12 @@ var __copyProps = (to, from, except, desc) => {
15
11
  }
16
12
  return to;
17
13
  };
14
+ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
18
15
  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
16
  var errors_exports = {};
20
- __export(errors_exports, {
21
- adcpError: () => adcpError,
22
- applyAdcpErrorAllowlist: () => applyAdcpErrorAllowlist,
23
- sanitizeStructuredAdcpError: () => sanitizeStructuredAdcpError
24
- });
25
17
  module.exports = __toCommonJS(errors_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
- };
66
- const filtered = applyAdcpErrorAllowlist(code, adcp_error);
67
- const structuredContent = {
68
- adcp_error: filtered,
69
- ...isEchoableContext(options.context) ? { context: options.context } : {}
70
- };
71
- return {
72
- content: [{ type: "text", text: JSON.stringify(structuredContent) }],
73
- isError: true,
74
- structuredContent
75
- };
76
- }
77
- function applyAdcpErrorAllowlist(code, payload) {
78
- payload = sanitizeAdcpErrorDetails(code, payload);
79
- const allowlist = import_envelope_allowlist.ADCP_ERROR_FIELD_ALLOWLIST[code];
80
- if (!allowlist) return payload;
81
- const out = {};
82
- for (const [key, value] of Object.entries(payload)) {
83
- if (!allowlist.has(key)) continue;
84
- out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
85
- }
86
- return out;
87
- }
88
- function sanitizeStructuredAdcpError(error) {
89
- return applyAdcpErrorAllowlist(error.code, error);
90
- }
91
- function sanitizeAdcpErrorDetails(code, payload) {
92
- if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
93
- const sanitizedDetails = (0, import_pick_safe_details.pickSafeDetails)(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
94
- maxDepth: 4,
95
- maxSizeBytes: 4096
96
- });
97
- const { details: _details, ...rest } = payload;
98
- return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
99
- }
100
- function isErrorRecovery(value) {
101
- return value === "transient" || value === "correctable" || value === "terminal";
102
- }
103
- function normalizeRecoveryForCode(code, value) {
104
- return isErrorRecovery(value) ? value : (0, import_error_codes.isStandardErrorCode)(code) ? import_error_codes.STANDARD_ERROR_CODES[code].recovery : "terminal";
105
- }
106
- function normalizeAllowlistedRecoveryForCode(code, value) {
107
- if ((0, import_error_codes.isStandardErrorCode)(code)) {
108
- return import_error_codes.STANDARD_ERROR_CODES[code].recovery;
109
- }
110
- return normalizeRecoveryForCode(code, value);
111
- }
18
+ __reExport(errors_exports, require('../utils/adcp-error-response.js'), module.exports);
112
19
  // Annotate the CommonJS export names for ESM import in node:
113
20
  0 && (module.exports = {
114
- adcpError,
115
- applyAdcpErrorAllowlist,
116
- sanitizeStructuredAdcpError
21
+ ...require('../utils/adcp-error-response.js')
117
22
  });