@adcp/sdk 16.0.0-beta.2 → 16.0.0-beta.4

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 (248) hide show
  1. package/README.md +54 -0
  2. package/dist/lib/auth/oauth/diagnose.js +3 -11
  3. package/dist/lib/auth/oauth/diagnose.mjs +4 -12
  4. package/dist/lib/auth/oauth/diagnostics.d.mts +2 -1
  5. package/dist/lib/auth/oauth/diagnostics.d.ts +2 -1
  6. package/dist/lib/auth/oauth/diagnostics.js +8 -10
  7. package/dist/lib/auth/oauth/diagnostics.mjs +7 -10
  8. package/dist/lib/core/ConversationTypes.d.mts +8 -3
  9. package/dist/lib/core/ConversationTypes.d.ts +8 -3
  10. package/dist/lib/core/SingleAgentClient.d.mts +5 -3
  11. package/dist/lib/core/SingleAgentClient.d.ts +5 -3
  12. package/dist/lib/core/TaskExecutor.js +5 -1
  13. package/dist/lib/core/TaskExecutor.mjs +5 -1
  14. package/dist/lib/errors/index.d.mts +9 -4
  15. package/dist/lib/errors/index.d.ts +9 -4
  16. package/dist/lib/index.d.mts +3 -3
  17. package/dist/lib/index.d.ts +3 -3
  18. package/dist/lib/index.js +8 -0
  19. package/dist/lib/index.mjs +14 -2
  20. package/dist/lib/negotiation/types.d.mts +20 -39
  21. package/dist/lib/negotiation/types.d.ts +20 -39
  22. package/dist/lib/protocols/index.d.mts +60 -24
  23. package/dist/lib/protocols/index.d.ts +60 -24
  24. package/dist/lib/protocols/index.js +9 -4
  25. package/dist/lib/protocols/index.mjs +3 -0
  26. package/dist/lib/protocols/mcp-modern.js +1 -0
  27. package/dist/lib/protocols/mcp-modern.mjs +2 -1
  28. package/dist/lib/protocols/mcp.js +1 -0
  29. package/dist/lib/protocols/mcp.mjs +2 -1
  30. package/dist/lib/protocols/responseSizeLimit.d.mts +91 -5
  31. package/dist/lib/protocols/responseSizeLimit.d.ts +91 -5
  32. package/dist/lib/protocols/responseSizeLimit.js +195 -31
  33. package/dist/lib/protocols/responseSizeLimit.mjs +192 -31
  34. package/dist/lib/reporting/consumer-runtime.js +2 -1
  35. package/dist/lib/reporting/consumer-runtime.mjs +2 -1
  36. package/dist/lib/reporting/ledger/handler.js +50 -11
  37. package/dist/lib/reporting/ledger/handler.mjs +50 -12
  38. package/dist/lib/reporting/ledger/index.d.mts +17 -14
  39. package/dist/lib/reporting/ledger/index.d.ts +17 -14
  40. package/dist/lib/reporting/ledger/index.js +32 -20
  41. package/dist/lib/reporting/ledger/index.mjs +21 -10
  42. package/dist/lib/reporting/ledger/offering-validation.d.mts +9 -0
  43. package/dist/lib/reporting/ledger/offering-validation.d.ts +9 -0
  44. package/dist/lib/reporting/{gcs/bucket-policy.js → ledger/offering-validation.js} +9 -8
  45. package/dist/lib/reporting/ledger/offering-validation.mjs +8 -0
  46. package/dist/lib/reporting/ledger/receipts.d.mts +48 -0
  47. package/dist/lib/reporting/ledger/receipts.d.ts +48 -0
  48. package/dist/lib/reporting/ledger/receipts.js +186 -0
  49. package/dist/lib/reporting/ledger/receipts.mjs +161 -0
  50. package/dist/lib/reporting/ledger/status-ingest.js +3 -3
  51. package/dist/lib/reporting/ledger/status-ingest.mjs +4 -5
  52. package/dist/lib/reporting/ledger/types.d.mts +43 -0
  53. package/dist/lib/reporting/ledger/types.d.ts +43 -0
  54. package/dist/lib/reporting/ledger/types.js +31 -2
  55. package/dist/lib/reporting/ledger/types.mjs +26 -1
  56. package/dist/lib/reporting/pagination.d.mts +6 -0
  57. package/dist/lib/reporting/pagination.d.ts +6 -0
  58. package/dist/lib/reporting/{gcs/errors.js → pagination.js} +12 -17
  59. package/dist/lib/reporting/pagination.mjs +12 -0
  60. package/dist/lib/reporting/reconciliation.d.mts +1 -0
  61. package/dist/lib/reporting/reconciliation.d.ts +1 -0
  62. package/dist/lib/reporting/reconciliation.js +3 -2
  63. package/dist/lib/reporting/reconciliation.mjs +3 -2
  64. package/dist/lib/reporting/service/index.d.mts +79 -153
  65. package/dist/lib/reporting/service/index.d.ts +79 -153
  66. package/dist/lib/reporting/service/index.js +34 -491
  67. package/dist/lib/reporting/service/index.mjs +36 -510
  68. package/dist/lib/reporting/service/scheduler-support.d.mts +43 -0
  69. package/dist/lib/reporting/service/scheduler-support.d.ts +43 -0
  70. package/dist/lib/reporting/service/scheduler-support.js +125 -0
  71. package/dist/lib/reporting/service/scheduler-support.mjs +96 -0
  72. package/dist/lib/schemas-data/v2.5/_provenance.json +1 -1
  73. package/dist/lib/signing/canonicalize.d.mts +4 -0
  74. package/dist/lib/signing/canonicalize.d.ts +4 -0
  75. package/dist/lib/signing/canonicalize.js +14 -8
  76. package/dist/lib/signing/canonicalize.mjs +14 -8
  77. package/dist/lib/signing/content-digest.d.mts +8 -0
  78. package/dist/lib/signing/content-digest.d.ts +8 -0
  79. package/dist/lib/signing/content-digest.js +11 -5
  80. package/dist/lib/signing/content-digest.mjs +10 -5
  81. package/dist/lib/signing/crypto.d.mts +15 -0
  82. package/dist/lib/signing/crypto.d.ts +15 -0
  83. package/dist/lib/signing/crypto.js +75 -3
  84. package/dist/lib/signing/crypto.mjs +78 -3
  85. package/dist/lib/signing/server.d.mts +1 -1
  86. package/dist/lib/signing/server.d.ts +1 -1
  87. package/dist/lib/signing/server.js +2 -0
  88. package/dist/lib/signing/server.mjs +2 -1
  89. package/dist/lib/signing/signer.js +11 -14
  90. package/dist/lib/signing/signer.mjs +13 -16
  91. package/dist/lib/signing/testing.js +2 -6
  92. package/dist/lib/signing/testing.mjs +3 -7
  93. package/dist/lib/signing/verifier.js +2 -2
  94. package/dist/lib/signing/verifier.mjs +3 -3
  95. package/dist/lib/signing/web-bot-auth.js +122 -43
  96. package/dist/lib/signing/web-bot-auth.mjs +128 -44
  97. package/dist/lib/signing/webhook-verifier.js +2 -2
  98. package/dist/lib/signing/webhook-verifier.mjs +3 -3
  99. package/dist/lib/substitution/compile.js +2 -1
  100. package/dist/lib/substitution/compile.mjs +2 -1
  101. package/dist/lib/substitution/consent-macros.d.mts +4 -0
  102. package/dist/lib/substitution/consent-macros.d.ts +4 -0
  103. package/dist/lib/substitution/consent-macros.js +45 -0
  104. package/dist/lib/substitution/consent-macros.mjs +20 -0
  105. package/dist/lib/substitution/index.d.mts +1 -1
  106. package/dist/lib/substitution/index.d.ts +1 -1
  107. package/dist/lib/substitution/index.js +2 -0
  108. package/dist/lib/substitution/index.mjs +2 -1
  109. package/dist/lib/substitution/translate.d.mts +15 -2
  110. package/dist/lib/substitution/translate.d.ts +15 -2
  111. package/dist/lib/substitution/translate.js +148 -26
  112. package/dist/lib/substitution/translate.mjs +147 -26
  113. package/dist/lib/testing/client.js +2 -1
  114. package/dist/lib/testing/client.mjs +2 -1
  115. package/dist/lib/testing/scenarios/capabilities.js +1 -1
  116. package/dist/lib/testing/scenarios/capabilities.mjs +1 -1
  117. package/dist/lib/testing/storyboard/junit.js +16 -3
  118. package/dist/lib/testing/storyboard/junit.mjs +16 -3
  119. package/dist/lib/testing/storyboard/request-signing/builder.js +12 -14
  120. package/dist/lib/testing/storyboard/request-signing/builder.mjs +13 -15
  121. package/dist/lib/testing/storyboard/runner.js +94 -25
  122. package/dist/lib/testing/storyboard/runner.mjs +94 -25
  123. package/dist/lib/testing/storyboard/signer-grader/grader.js +2 -7
  124. package/dist/lib/testing/storyboard/signer-grader/grader.mjs +2 -7
  125. package/dist/lib/testing/storyboard/types.d.mts +6 -0
  126. package/dist/lib/testing/storyboard/types.d.ts +6 -0
  127. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  128. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  129. package/dist/lib/types/enums.generated.d.mts +3 -0
  130. package/dist/lib/types/enums.generated.d.ts +3 -0
  131. package/dist/lib/types/enums.generated.js +9 -0
  132. package/dist/lib/types/enums.generated.mjs +6 -0
  133. package/dist/lib/validation/schema-loader.js +25 -0
  134. package/dist/lib/validation/schema-loader.mjs +24 -0
  135. package/dist/lib/version.d.mts +3 -3
  136. package/dist/lib/version.d.ts +3 -3
  137. package/dist/lib/version.js +3 -3
  138. package/dist/lib/version.mjs +3 -3
  139. package/docs/TYPE-SUMMARY.md +28 -5
  140. package/docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md +3 -2
  141. package/docs/guides/REPORTING-GCS-FENCE.md +3 -3
  142. package/docs/guides/REPORTING-GCS-MANAGED.md +4 -4
  143. package/docs/guides/REPORTING-LEDGER-CUTOVER.md +7 -7
  144. package/docs/guides/REPORTING-LEDGER.md +107 -51
  145. package/docs/guides/REPORTING-OPERATIONS.md +66 -5
  146. package/docs/guides/REPORTING-STABILITY.md +36 -32
  147. package/docs/guides/UNIVERSAL-MACRO-COMPILATION.md +38 -0
  148. package/docs/guides/VALIDATE-YOUR-AGENT.md +12 -0
  149. package/docs/llms.txt +4 -3
  150. package/docs/migration-14.x-rc-worksheet.md +4 -7
  151. package/docs/migration-reporting-storage-package.md +186 -0
  152. package/examples/README.md +1 -1
  153. package/package.json +14 -78
  154. package/dist/lib/reporting/azure/index.d.mts +0 -31
  155. package/dist/lib/reporting/azure/index.d.ts +0 -31
  156. package/dist/lib/reporting/azure/index.js +0 -266
  157. package/dist/lib/reporting/azure/index.mjs +0 -249
  158. package/dist/lib/reporting/bigquery/index.d.mts +0 -246
  159. package/dist/lib/reporting/bigquery/index.d.ts +0 -246
  160. package/dist/lib/reporting/bigquery/index.js +0 -633
  161. package/dist/lib/reporting/bigquery/index.mjs +0 -594
  162. package/dist/lib/reporting/gcs/adapter.d.mts +0 -38
  163. package/dist/lib/reporting/gcs/adapter.d.ts +0 -38
  164. package/dist/lib/reporting/gcs/adapter.js +0 -342
  165. package/dist/lib/reporting/gcs/adapter.mjs +0 -325
  166. package/dist/lib/reporting/gcs/bucket-policy.d.mts +0 -3
  167. package/dist/lib/reporting/gcs/bucket-policy.d.ts +0 -3
  168. package/dist/lib/reporting/gcs/bucket-policy.mjs +0 -7
  169. package/dist/lib/reporting/gcs/errors.d.mts +0 -11
  170. package/dist/lib/reporting/gcs/errors.d.ts +0 -11
  171. package/dist/lib/reporting/gcs/errors.mjs +0 -16
  172. package/dist/lib/reporting/gcs/fence.d.mts +0 -41
  173. package/dist/lib/reporting/gcs/fence.d.ts +0 -41
  174. package/dist/lib/reporting/gcs/fence.js +0 -250
  175. package/dist/lib/reporting/gcs/fence.mjs +0 -230
  176. package/dist/lib/reporting/gcs/index.d.mts +0 -18
  177. package/dist/lib/reporting/gcs/index.d.ts +0 -18
  178. package/dist/lib/reporting/gcs/index.js +0 -44
  179. package/dist/lib/reporting/gcs/index.mjs +0 -14
  180. package/dist/lib/reporting/gcs/io.d.mts +0 -7
  181. package/dist/lib/reporting/gcs/io.d.ts +0 -7
  182. package/dist/lib/reporting/gcs/io.js +0 -95
  183. package/dist/lib/reporting/gcs/io.mjs +0 -69
  184. package/dist/lib/reporting/gcs/reader.d.mts +0 -67
  185. package/dist/lib/reporting/gcs/reader.d.ts +0 -67
  186. package/dist/lib/reporting/gcs/reader.js +0 -193
  187. package/dist/lib/reporting/gcs/reader.mjs +0 -169
  188. package/dist/lib/reporting/gcs/row-provider.d.mts +0 -39
  189. package/dist/lib/reporting/gcs/row-provider.d.ts +0 -39
  190. package/dist/lib/reporting/gcs/row-provider.js +0 -225
  191. package/dist/lib/reporting/gcs/row-provider.mjs +0 -208
  192. package/dist/lib/reporting/gcs/validation.d.mts +0 -5
  193. package/dist/lib/reporting/gcs/validation.d.ts +0 -5
  194. package/dist/lib/reporting/gcs/validation.js +0 -49
  195. package/dist/lib/reporting/gcs/validation.mjs +0 -25
  196. package/dist/lib/reporting/ledger/change-feed.d.mts +0 -69
  197. package/dist/lib/reporting/ledger/change-feed.d.ts +0 -69
  198. package/dist/lib/reporting/ledger/change-feed.js +0 -107
  199. package/dist/lib/reporting/ledger/change-feed.mjs +0 -80
  200. package/dist/lib/reporting/ledger/managed-postgres.d.mts +0 -293
  201. package/dist/lib/reporting/ledger/managed-postgres.d.ts +0 -293
  202. package/dist/lib/reporting/ledger/managed-postgres.js +0 -2346
  203. package/dist/lib/reporting/ledger/managed-postgres.mjs +0 -2332
  204. package/dist/lib/reporting/ledger/managed-router.d.mts +0 -148
  205. package/dist/lib/reporting/ledger/managed-router.d.ts +0 -148
  206. package/dist/lib/reporting/ledger/managed-router.js +0 -280
  207. package/dist/lib/reporting/ledger/managed-router.mjs +0 -258
  208. package/dist/lib/reporting/ledger/managed.d.mts +0 -535
  209. package/dist/lib/reporting/ledger/managed.d.ts +0 -535
  210. package/dist/lib/reporting/ledger/managed.js +0 -761
  211. package/dist/lib/reporting/ledger/managed.mjs +0 -729
  212. package/dist/lib/reporting/ledger/notification-activity.d.mts +0 -332
  213. package/dist/lib/reporting/ledger/notification-activity.d.ts +0 -332
  214. package/dist/lib/reporting/ledger/notification-activity.js +0 -1366
  215. package/dist/lib/reporting/ledger/notification-activity.mjs +0 -1337
  216. package/dist/lib/reporting/ledger/object-writes.d.mts +0 -128
  217. package/dist/lib/reporting/ledger/object-writes.d.ts +0 -128
  218. package/dist/lib/reporting/ledger/object-writes.js +0 -147
  219. package/dist/lib/reporting/ledger/object-writes.mjs +0 -114
  220. package/dist/lib/reporting/ledger/postgres.d.mts +0 -689
  221. package/dist/lib/reporting/ledger/postgres.d.ts +0 -689
  222. package/dist/lib/reporting/ledger/postgres.js +0 -4462
  223. package/dist/lib/reporting/ledger/postgres.mjs +0 -4462
  224. package/dist/lib/reporting/ledger/row-storage-migration.d.mts +0 -59
  225. package/dist/lib/reporting/ledger/row-storage-migration.d.ts +0 -59
  226. package/dist/lib/reporting/ledger/row-storage-migration.js +0 -365
  227. package/dist/lib/reporting/ledger/row-storage-migration.mjs +0 -339
  228. package/dist/lib/reporting/ledger/row-storage-object.d.mts +0 -203
  229. package/dist/lib/reporting/ledger/row-storage-object.d.ts +0 -203
  230. package/dist/lib/reporting/ledger/row-storage-object.js +0 -379
  231. package/dist/lib/reporting/ledger/row-storage-object.mjs +0 -335
  232. package/dist/lib/reporting/ledger/row-storage-provider-io.d.mts +0 -44
  233. package/dist/lib/reporting/ledger/row-storage-provider-io.d.ts +0 -44
  234. package/dist/lib/reporting/ledger/row-storage-provider-io.js +0 -142
  235. package/dist/lib/reporting/ledger/row-storage-provider-io.mjs +0 -111
  236. package/dist/lib/reporting/ledger/row-storage.d.mts +0 -316
  237. package/dist/lib/reporting/ledger/row-storage.d.ts +0 -316
  238. package/dist/lib/reporting/ledger/row-storage.js +0 -812
  239. package/dist/lib/reporting/ledger/row-storage.mjs +0 -802
  240. package/dist/lib/reporting/s3/index.d.mts +0 -34
  241. package/dist/lib/reporting/s3/index.d.ts +0 -34
  242. package/dist/lib/reporting/s3/index.js +0 -347
  243. package/dist/lib/reporting/s3/index.mjs +0 -340
  244. package/dist/lib/reporting/service/maintenance.d.mts +0 -148
  245. package/dist/lib/reporting/service/maintenance.d.ts +0 -148
  246. package/dist/lib/reporting/service/maintenance.js +0 -185
  247. package/dist/lib/reporting/service/maintenance.mjs +0 -159
  248. package/examples/reliable-reporting-service/README.md +0 -169
@@ -96,3 +96,41 @@ Do not create a global mapping based only on a token's spelling. A token such as
96
96
  cookie for another, and an account identifier for a third. Scope every mapping
97
97
  to its source dialect and keep the supporting vendor documentation with the
98
98
  registry entry.
99
+
100
+ Vendor-scoped TCF mappings retain the complete receiving vendor ID: map
101
+ `${GDPR_CONSENT_755}` to `{GDPR_CONSENT_755}`, never to unscoped
102
+ `{GDPR_CONSENT}` or another vendor's token. The suffix must be a positive
103
+ decimal integer without leading zeros. `{ADDTL_CONSENT}` is also supported,
104
+ with the same source-dialect and documentation requirements. Its CMP-provided
105
+ value is opaque; the helper does not generate consent or modify provider lists.
106
+
107
+ For the return translation, supply exact native mappings:
108
+
109
+ ```typescript
110
+ import { translateUniversalMacros } from '@adcp/sdk/substitution';
111
+
112
+ const translated = translateUniversalMacros(
113
+ 'https://pixel.vendor.example/i?gdpr={GDPR}&c={GDPR_CONSENT_755}&a={ADDTL_CONSENT}',
114
+ {
115
+ '{GDPR}': { native: '${GDPR}' },
116
+ '{GDPR_CONSENT_755}': { native: '${GDPR_CONSENT_755}' },
117
+ '{ADDTL_CONSENT}': { native: '${ADDTL_CONSENT}' },
118
+ }
119
+ );
120
+ ```
121
+
122
+ Existing native tokens pass through unchanged. The emitted URL may contain at
123
+ most one scoped TCF token, including pre-existing tokens and native aliases
124
+ identified by the supplied mappings. After dropping unsupported parameters,
125
+ multiple occurrences throw `MultipleVendorConsentMacrosError` with code
126
+ `multiple_vendor_consent_macros` and the second token in canonical AdCP form.
127
+ Additional Consent does not count toward that limit. Concrete `value` mappings
128
+ are encoded and reported in `frozen_consent_macros`; missing consent mappings
129
+ appear in `dropped_consent_macros`. When an unscoped target requires an unknown
130
+ vendor ID, use `'{GDPR_CONSENT}': { value: '' }` and translate `{GDPR}`
131
+ independently rather than guessing an ID.
132
+
133
+ These helpers implement the AdCP 3.3 translation contract. Generated protocol
134
+ types and declaration/capability validation still follow the SDK's pinned schema
135
+ release. Helper support alone does not establish a resolver's declared support
136
+ for a scoped token or Additional Consent.
@@ -668,6 +668,18 @@ try {
668
668
 
669
669
  These policies follow the language-neutral fixture ratified in [AdCP #6674](https://github.com/adcontextprotocol/adcp/issues/6674).
670
670
 
671
+ The AdCP 3.3 fixture also covers vendor-scoped `{GDPR_CONSENT_<gvl_id>}` and
672
+ `{ADDTL_CONSENT}`. Preserve the receiving vendor ID and treat Additional Consent
673
+ as opaque CMP data. Both participate in dropped/frozen consent diagnostics.
674
+ After unsupported parameters are dropped, a URL with multiple scoped TCF
675
+ occurrences throws `MultipleVendorConsentMacrosError` (exported from both
676
+ `@adcp/sdk` and `@adcp/sdk/substitution`), with code
677
+ `multiple_vendor_consent_macros` and the canonical second token in `macro`.
678
+ Existing native tokens and verified native aliases count; encoded concrete
679
+ values and Additional Consent do not. See the
680
+ [compilation guide](UNIVERSAL-MACRO-COMPILATION.md) for mapping and schema-version
681
+ boundaries.
682
+
671
683
  ---
672
684
 
673
685
  ## The fork-matrix: canonical adapter → compliance
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
- > Generated at: 2026-10-15
4
- > Library: @adcp/sdk v16.0.0-beta.2
3
+ > Generated at: 2026-10-16
4
+ > Library: @adcp/sdk v16.0.0-beta.4
5
5
  > AdCP major version: 3
6
6
  > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
7
7
  > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -2126,6 +2126,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
2126
2126
  | Seller quick start (AdCP 3.2) | docs/guides/SELLER-QUICKSTART-3.2.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/SELLER-QUICKSTART-3.2.md) |
2127
2127
  | Production durability checklist | docs/guides/PRODUCTION-DURABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PRODUCTION-DURABILITY.md) |
2128
2128
  | Persistent notification subscriptions | docs/guides/PERSISTENT-NOTIFICATION-RUNTIME.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PERSISTENT-NOTIFICATION-RUNTIME.md) |
2129
+ | Reliable Reporting storage moved to @adcp/reporting-storage (SDK 16 beta) | docs/migration-reporting-storage-package.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-reporting-storage-package.md) |
2129
2130
  | Migrating SDK 13 → 14 | docs/migration-13-to-14.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-13-to-14.md) |
2130
2131
  | Getting started / install | docs/getting-started.md | [link](https://adcontextprotocol.github.io/adcp-client/getting-started.md) |
2131
2132
  | Build a server-side agent | docs/guides/BUILD-AN-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/BUILD-AN-AGENT.md) |
@@ -2143,7 +2144,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
2143
2144
  | Reporting ledger cutover from custom tables | docs/guides/REPORTING-LEDGER-CUTOVER.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-LEDGER-CUTOVER.md) |
2144
2145
  | Buyer reporting reconciliation | docs/guides/REPORTING-RECONCILIATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-RECONCILIATION.md) |
2145
2146
  | Reliable Reporting production operations | docs/guides/REPORTING-OPERATIONS.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-OPERATIONS.md) |
2146
- | Reliable Reporting stability policy (experimental storage subpaths) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
2147
+ | Reliable Reporting stability policy (experimental storage package) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
2147
2148
  | Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |
2148
2149
  | Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
2149
2150
  | Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |
@@ -11,8 +11,8 @@ below as the publication/deployment gate.
11
11
 
12
12
  | Fact | Value |
13
13
  | --- | --- |
14
- | Exact npm package | `@adcp/sdk@16.0.0-beta.2` |
15
- | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.2 dist.integrity` |
14
+ | Exact npm package | `@adcp/sdk@16.0.0-beta.4` |
15
+ | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.4 dist.integrity` |
16
16
  | Node.js runtime | `^20.19.0 || >=22.12.0` |
17
17
  | Default AdCP wire release | `3.2.4` |
18
18
  | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
21
21
  Install exact production inputs rather than a moving range or dist-tag:
22
22
 
23
23
  ```bash
24
- npm install --save-exact '@adcp/sdk@16.0.0-beta.2'
25
- npm view '@adcp/sdk@16.0.0-beta.2' dist.integrity
24
+ npm install --save-exact '@adcp/sdk@16.0.0-beta.4'
25
+ npm view '@adcp/sdk@16.0.0-beta.4' dist.integrity
26
26
  ```
27
27
 
28
28
  ### Required and optional peers
@@ -32,9 +32,6 @@ Install the peer packages used by your application at versions satisfying these
32
32
  | Peer | Supported range | Installation |
33
33
  | --- | --- | --- |
34
34
  | `@a2a-js/sdk` | `^1.0.1` | Required |
35
- | `@aws-sdk/client-s3` | `^3.700.0` | Optional |
36
- | `@azure/storage-blob` | `^12.23.0` | Optional |
37
- | `@google-cloud/storage` | `^7.22.0 || ^8.2.0` | Optional |
38
35
  | `@modelcontextprotocol/sdk` | `^1.31.0` | Required |
39
36
  | `@opentelemetry/api` | `^1.0.0` | Optional |
40
37
  | `redis` | `^4.6.0 || ^5.0.0 || ^6.0.0` | Optional |
@@ -0,0 +1,186 @@
1
+ # Reliable Reporting storage moved to `@adcp/reporting-storage`
2
+
3
+ **Applies to:** SDK 16 beta. **Kind:** breaking, by design. There are no re-export shims: the moved subpaths are gone from `@adcp/sdk`.
4
+
5
+ The Reliable Reporting storage implementations now ship as their own package, `@adcp/reporting-storage`, on its own version line. `@adcp/sdk` keeps the protocol layer. If you import anything from `@adcp/sdk/reporting/gcs`, `/s3`, `/azure` or `/bigquery`, or the PostgreSQL store, row storage, managed delivery or notification activity from `@adcp/sdk/reporting/ledger`, or `createPostgresReliableReportingProductionService` from `@adcp/sdk/reporting/service`, change those imports. Nothing else changes on the wire, in the database schema, or in the ledger's behavior.
6
+
7
+ Why: storage keeps its own release cadence, as Auth.js, LangGraph and OpenTelemetry do, so a storage fix does not need an SDK release and an experimental storage break does not need an SDK major. The Python SDK is making the same split (adcp-client-python#1510). See [Reliable Reporting stability policy](guides/REPORTING-STABILITY.md).
8
+
9
+ ## What to do
10
+
11
+ 1. Install the package next to the SDK. `@adcp/sdk` is a peer dependency of it, so the host keeps exactly one copy:
12
+
13
+ ```bash
14
+ npm install @adcp/sdk@beta @adcp/reporting-storage@beta
15
+ ```
16
+
17
+ Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0-beta.0"` while SDK 16 is in beta, `"~0.1.0"` after a stable release; a prerelease version is not matched by `~0.1.0`): it is pre-1.0 and every export is experimental. The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
18
+
19
+ 2. Change the imports using the table below, then run `tsc --noEmit`. A moved name on `@adcp/sdk/reporting/ledger` or `/service` is `TS2305: Module '"@adcp/sdk/reporting/ledger"' has no exported member 'PostgresReportingLedgerStore'`; a deleted subpath is `TS2307: Cannot find module '@adcp/sdk/reporting/gcs'`. At runtime the deleted subpaths fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and a stale CommonJS `require` of a moved name on a kept subpath destructures to `undefined` and fails later as `X is not a constructor`, so grep JavaScript too (see [Self-grade](#self-grade)).
20
+
21
+ 3. If you pass `maintenance` to `createReliableReportingService`, wrap it (see [`maintenance` is now a factory](#maintenance-is-now-a-factory)).
22
+
23
+ 4. Re-run your own tests. No database migration is needed: every migration constant has the same SQL under its new import path.
24
+
25
+ ## Import mapping
26
+
27
+ | Old import | New import |
28
+ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
29
+ | `@adcp/sdk/reporting/ledger`: `PostgresReportingLedgerStore`, the ledger, row-storage, object-write and change-feed migrations, `sweepExpiredReportingLedgerState`, row storage (`ReportingRowStorageV1`, bindings, providers contract, filesystem provider, conformance suite), object writes, the change feed | `@adcp/reporting-storage` |
30
+ | `@adcp/sdk/reporting/ledger`: the managed-delivery runtime, `PostgresReportingManagedDeliveryStore`, `REPORTING_MANAGED_DELIVERY_MIGRATION`, the adapter contract and router | `@adcp/reporting-storage/managed` |
31
+ | `@adcp/sdk/reporting/ledger`: notification activity (`createPostgresReportingNotificationActivityRuntime`, `createPostgresReportingNotificationAttemptCheckpoint`, `REPORTING_NOTIFICATION_ACTIVITY_MIGRATION`) | `@adcp/reporting-storage/notifications` |
32
+ | `@adcp/sdk/reporting/ledger`: everything else (the `ReportingLedgerStore` interface and its types, `createReportingDeliveryHandler`, `createReportingStatusHandler`, `createSyncReportingStatusHandler`, `createReportingProducer`, health, coverage, lifecycle, row encoding and digests, `ReportingRowStoreError`) | unchanged: `@adcp/sdk/reporting/ledger` |
33
+ | `@adcp/sdk/reporting/service`: `createPostgresReliableReportingProductionService` and its types | `@adcp/reporting-storage/service` |
34
+ | `@adcp/sdk/reporting/service`: retention, compaction, orphan-collection and change-feed maintenance (`runReportingLedgerMaintenance`, `ReportingRetentionOptionsV1`, `ReportingCompactionOptionsV1`, `ReportingMaintenancePartialFailureError`, and the related types); `ReliableReportingMaintenanceOptionsV1` is now `ReportingLedgerMaintenanceOptionsV1` | `@adcp/reporting-storage` |
35
+ | `@adcp/sdk/reporting/service`: `createReliableReportingService`, the conformance runner | unchanged: `@adcp/sdk/reporting/service` |
36
+ | `@adcp/sdk/reporting/gcs` | `@adcp/reporting-storage/gcs` |
37
+ | `@adcp/sdk/reporting/s3` | `@adcp/reporting-storage/s3` |
38
+ | `@adcp/sdk/reporting/azure` | `@adcp/reporting-storage/azure` |
39
+ | `@adcp/sdk/reporting/bigquery` | `@adcp/reporting-storage/bigquery` |
40
+ | `@adcp/sdk/reporting/consumer`, `@adcp/sdk/reporting/source`, `@adcp/sdk` | unchanged |
41
+
42
+ Before and after:
43
+
44
+ ```ts
45
+ // Before
46
+ import {
47
+ PostgresReportingLedgerStore,
48
+ REPORTING_LEDGER_MIGRATION,
49
+ createReportingProducer,
50
+ } from '@adcp/sdk/reporting/ledger';
51
+ import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
52
+
53
+ // After
54
+ import { createReportingProducer } from '@adcp/sdk/reporting/ledger';
55
+ import { PostgresReportingLedgerStore, REPORTING_LEDGER_MIGRATION } from '@adcp/reporting-storage';
56
+ import { createGcsReportingRowObjectProviderV1 } from '@adcp/reporting-storage/gcs';
57
+ ```
58
+
59
+ ### Every moved export, by new subpath
60
+
61
+ <details>
62
+ <summary>84 exports of <code>@adcp/reporting-storage</code></summary>
63
+
64
+ `FilesystemReportingRowObjectProviderOptionsV1`, `PostgresReportingLedgerStore`, `PostgresReportingLedgerStoreOptions`, `REPORTING_LEDGER_CHANGES_MIGRATION`, `REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT`, `REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION`, `REPORTING_LEDGER_MIGRATION`, `REPORTING_OBJECT_WRITE_AUTHORITY_MIGRATION`, `REPORTING_OBJECT_WRITE_MIGRATION`, `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`, `REPORTING_ROW_KEY_PLACEHOLDERS`, `REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH`, `REPORTING_ROW_OBJECT_REF_MAX_LENGTH`, `REPORTING_ROW_STORAGE_MIGRATION`, `REPORTING_ROW_STORAGE_TABLES`, `ReportingChangeCursorExpiredError`, `ReportingChangeFeedMaintenanceOptionsV1`, `ReportingChangeKindV1`, `ReportingChangeRecordV1`, `ReportingChangesPageV1`, `ReportingCompactionOptionsV1`, `ReportingLedgerMaintenanceOptionsV1`, `ReportingLedgerMaintenanceStoreV1`, `ReportingLedgerMaintenanceTaskNameV1`, `ReportingLedgerMaintenanceTaskResultV1`, `ReportingMaintenancePartialFailureError`, `ReportingObjectRowBindingV1`, `ReportingObjectWriteAuthorityStoreV1`, `ReportingObjectWriteBindingV1`, `ReportingObjectWriteConflictError`, `ReportingObjectWriteContextV1`, `ReportingObjectWriteCursorV1`, `ReportingObjectWriteNotRevokedError`, `ReportingObjectWritePlanV1`, `ReportingObjectWriteScopeV1`, `ReportingObjectWriteStoreV1`, `ReportingObjectWriteV1`, `ReportingOrphanBindingResultV1`, `ReportingOrphanCollectionOptionsV1`, `ReportingOrphanCollectionResultV1`, `ReportingOrphanCollectionStateV1`, `ReportingPgPool`, `ReportingPostgresRowBindingV1`, `ReportingPreparedRowSetV1`, `ReportingRetentionOptionsV1`, `ReportingRowBindingDefinitionV1`, `ReportingRowBindingSelectionInputV1`, `ReportingRowChunkLocatorV1`, `ReportingRowObjectContextV1`, `ReportingRowObjectDeleteInputV1`, `ReportingRowObjectGetInputV1`, `ReportingRowObjectListEntryV1`, `ReportingRowObjectListInputV1`, `ReportingRowObjectLocationV1`, `ReportingRowObjectProviderV1`, `ReportingRowObjectPutInputV1`, `ReportingRowObjectStatInputV1`, `ReportingRowSetHandleV1`, `ReportingRowSetPrepareInputV1`, `ReportingRowStorageOptionsV1`, `ReportingRowStorageV1`, `RunReportingLedgerMaintenanceInputV1`, `assertReportingLedgerMaintenanceOptions`, `assertReportingObjectWriteScope`, `assertReportingRowKeyTemplateV1`, `assertReportingRowPrefixV1`, `createFilesystemReportingRowObjectProviderV1`, `decodeReportingChangeCursorV1`, `encodeReportingChangeCursorV1`, `isLegacyAccountChangeCursor`, `isReportingObjectWriteConflictError`, `isReportingObjectWriteNotRevokedError`, `probeReportingRowStorageSchemaV1`, `renderReportingRowObjectKeyV1`, `reportingLedgerMaintenance`, `reportingObjectWriteName`, `reportingObjectWritePlanFingerprint`, `reportingObjectWriteScopeKey`, `reportingRowAccountKeyV1`, `reportingRowRevisionKeyV1`, `reportingRowWriteIntentIdV1`, `runReportingLedgerMaintenance`, `runReportingRowObjectProviderConformanceV1`, `sweepExpiredReportingLedgerState`
65
+
66
+ </details>
67
+
68
+ <details>
69
+ <summary>35 exports of <code>@adcp/reporting-storage/managed</code></summary>
70
+
71
+ `CreateReportingManagedDeliveryAdapterRouterOptionsV1`, `CreateReportingManagedDeliveryRuntimeOptionsV1`, `PostgresReportingManagedDeliveryStore`, `PostgresReportingManagedDeliveryStoreOptions`, `REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1`, `REPORTING_DESTINATION_PATTERNS_V1`, `REPORTING_DESTINATION_TRANSPORT_PATTERN_V1`, `REPORTING_MANAGED_DELIVERY_MIGRATION`, `ReportingDestinationAuthorizationV1`, `ReportingDestinationPatternV1`, `ReportingDestinationRevocationLeaseV1`, `ReportingManagedDeliveryAdapterRouterV1`, `ReportingManagedDeliveryAdapterV1`, `ReportingManagedDeliveryAdvertisedPoliciesV1`, `ReportingManagedDeliveryLeaseV1`, `ReportingManagedDeliveryProbeErrorV1`, `ReportingManagedDeliveryRouteCountsV1`, `ReportingManagedDeliveryRouteDescriptionV1`, `ReportingManagedDeliveryRouteV1`, `ReportingManagedDeliveryRoutingErrorCodeV1`, `ReportingManagedDeliveryRoutingErrorV1`, `ReportingManagedDeliveryRoutingOperationV1`, `ReportingManagedDeliveryRuntimeV1`, `ReportingManagedDeliveryStore`, `ReportingManagedDeliveryWorkerOptionsV1`, `ReportingManagedDeliveryWorkerResultV1`, `UNROUTED_REPORTING_ROUTE_KEY_V1`, `adjustmentReceiptEvidenceMatches`, `assertCredentialFreeReportingResourceLocationV1`, `assertMaterializationOutcome`, `createReportingManagedDeliveryAdapterRouterV1`, `createReportingManagedDeliveryRuntime`, `readManagedReportingResource`, `receiptEvidenceMatches`, `runManagedDeliveryWorker`
72
+
73
+ </details>
74
+
75
+ <details>
76
+ <summary>20 exports of <code>@adcp/reporting-storage/notifications</code></summary>
77
+
78
+ `PostgresReportingNotificationActivityOptions`, `PostgresReportingNotificationActivityRuntime`, `REPORTING_NOTIFICATION_ACTIVITY_MIGRATION`, `ReportingAccountActivityPageV1`, `ReportingAccountActivityRecordV1`, `ReportingAccountActivityV1`, `ReportingDeliveryReadyActivityV1`, `ReportingLedgerChangedActivityV1`, `ReportingLifecycleActivityV1`, `ReportingNotificationActivityPageV1`, `ReportingNotificationActivityRecordV1`, `ReportingNotificationActivityV1`, `ReportingNotificationAttemptCheckpointV1`, `ReportingNotificationProjectionErrorV1`, `ReportingNotificationRecoveryMetricsV1`, `ReportingNotificationRetryableSuppressionError`, `createPostgresReportingNotificationActivityRuntime`, `createPostgresReportingNotificationAttemptCheckpoint`, `getReportingNotificationActivityMigration`, `recipientTableName`
79
+
80
+ </details>
81
+
82
+ <details>
83
+ <summary>3 exports of <code>@adcp/reporting-storage/service</code></summary>
84
+
85
+ `CreatePostgresReliableReportingProductionServiceOptionsV1`, `PostgresReliableReportingProductionServiceV1`, `createPostgresReliableReportingProductionService`
86
+
87
+ </details>
88
+
89
+ <details>
90
+ <summary>13 exports of <code>@adcp/reporting-storage/gcs</code></summary>
91
+
92
+ `CreateGcsReportingManagedDeliveryAdapterOptionsV1`, `CreateGcsReportingRowObjectProviderOptionsV1`, `GcsReportingObjectFenceV1`, `GcsReportingReadAuthorizationV1`, `GcsReportingReadScopeV1`, `GcsReportingReaderOptionsV1`, `ReportingGcsFenceError`, `createGcsReportingManagedDeliveryAdapterV1`, `createGcsReportingObjectFenceV1`, `createGcsReportingReferenceResolverV1`, `createGcsReportingResourceReaderV1`, `createGcsReportingRowObjectProviderV1`, `isReportingGcsFenceError`
93
+
94
+ </details>
95
+
96
+ <details>
97
+ <summary>2 exports of <code>@adcp/reporting-storage/s3</code></summary>
98
+
99
+ `CreateS3ReportingRowObjectProviderOptionsV1`, `createS3ReportingRowObjectProviderV1`
100
+
101
+ </details>
102
+
103
+ <details>
104
+ <summary>2 exports of <code>@adcp/reporting-storage/azure</code></summary>
105
+
106
+ `CreateAzureBlobReportingRowObjectProviderOptionsV1`, `createAzureBlobReportingRowObjectProviderV1`
107
+
108
+ </details>
109
+
110
+ <details>
111
+ <summary>10 exports of <code>@adcp/reporting-storage/bigquery</code></summary>
112
+
113
+ `BigQueryReportingWarehouseSinkV1`, `CreateBigQueryReportingWarehouseSinkOptionsV1`, `REPORTING_WAREHOUSE_SINK_MIGRATION`, `ReportingBigQueryClientV1`, `ReportingWarehouseRowContextV1`, `createBigQueryReportingWarehouseSinkV1`, `reportingWarehouseCurrentRowsViewSqlV1`, `reportingWarehouseDefaultTablesSqlV1`, `reportingWarehouseJobIdV1`, `reportingWarehouseLoadDeadlineV1`
114
+
115
+ </details>
116
+
117
+ ## Behavior changes
118
+
119
+ ### `maintenance` is now a factory
120
+
121
+ The SDK does not know what maintenance a store needs, and retention, compaction and orphan collection are about the PostgreSQL store's data model. So `createReliableReportingService({ maintenance })` takes a factory, and `@adcp/reporting-storage` supplies the PostgreSQL one:
122
+
123
+ ```ts
124
+ // Before
125
+ createReliableReportingService({
126
+ store,
127
+ maintenance: { retention: { enabled: true }, changeFeed: true },
128
+ });
129
+
130
+ // After
131
+ import { reportingLedgerMaintenance } from '@adcp/reporting-storage';
132
+
133
+ createReliableReportingService({
134
+ store,
135
+ maintenance: reportingLedgerMaintenance({ retention: { enabled: true }, changeFeed: true }),
136
+ });
137
+ ```
138
+
139
+ Passing the old options object now fails at construction with `maintenance must be a factory, not an options object` (and in TypeScript as `Type '{ retention: ... }' provides no match for the signature '(context: ReliableReportingMaintenanceContextV1): ReliableReportingMaintenanceV1'`). The options are unchanged. The service still hands the factory the retention and recovery-window commitments it advertises, so retention still cannot disagree with what buyers were told, and a configuration the store cannot serve still fails when the service is constructed, not on the first scheduled pass. `service.runMaintenance()` returns the same per-task results, typed as `ReliableReportingMaintenanceTaskResultV1` (`{ task, status, result | error, partialFailure? }`). A store from another package can supply its own factory. `createPostgresReliableReportingProductionService` is unchanged: it takes `retention`, `compaction`, `changeFeed` and `orphanCollection` directly.
140
+
141
+ ### `service.setup.migrations` comes from the store
142
+
143
+ `createReliableReportingService` no longer names the PostgreSQL migration. `service.setup.migrations` is the store's own `migrations` list (`ReportingLedgerStore.migrations`, optional). `PostgresReportingLedgerStore` lists `[REPORTING_LEDGER_MIGRATION]`. A store with nothing to install (an in-memory test double), or a decorator over the PostgreSQL store that does not forward `migrations`, gives an empty list.
144
+
145
+ The type changed too: it was the tuple `readonly [typeof REPORTING_LEDGER_MIGRATION]` and is now `readonly string[]`, so `reporting.setup.migrations[0]` is `string | undefined` under `noUncheckedIndexedAccess`, and `pool.query(undefined)` fails at runtime for a store that lists nothing. Apply the list instead:
146
+
147
+ ```ts
148
+ for (const sql of reporting.setup.migrations) await pool.query(sql);
149
+ ```
150
+
151
+ ### Error classes now live with the interface
152
+
153
+ `ReportingLedgerLeaseLostError`, `ReportingLedgerPeriodRetiredError` and `ReportingLedgerContinuityError` are exported from `@adcp/sdk/reporting/ledger`, where the `ReportingLedgerStore` types are. The package re-throws these exact classes. The protocol layer still recognizes them by `name`, so a store from any package, or another copy of the SDK, is understood.
154
+
155
+ ### The Core service refuses managed-delivery offerings
156
+
157
+ A `createReliableReportingService` without a managed-delivery composition still refuses offerings that need Managed Delivery or Reconciled Billing, now naming `@adcp/reporting-storage/service` in the error. A composition built elsewhere opts in with the exported `REPORTING_MANAGED_DELIVERY_COMPOSITION_V1` key, set to the very `store` it passes as `store`. That is an assertion by the composer, not an authentication boundary (the key is a `Symbol.for`, so any code can write it); it exists so a Core-only service cannot advertise offerings it has no runtime for by accident. Applications should not use it.
158
+
159
+ ### New exports on `@adcp/sdk`
160
+
161
+ So a store can live outside the SDK against public API only: `compareReportingInstants`, `reportingPeriodDate`, `reportingPeriodSchedule`, `isFrozenCalendarRulesMismatch`, the receipt and verification evidence guards, `isWellFormedUnicodeString` and `getReportingDeliveryOfferingValidatorV1` (from `@adcp/sdk/reporting/ledger`); `reportingManagedDeliveryBindingV1`, `createSyncReportingReceiptsHandler`, `ReportingReceiptSyncStoreV1` and `SyncReportingReceiptsParamsV1` (from `@adcp/sdk/reporting/ledger`; the receipts handler only needs `syncReceiptBatch`); the scheduler helpers `reportingSchedulerErrorMessage`, `reportingSchedulerDelay`, `rotateReportingRoster`, `reportingDeploymentWideAccountIds`, `reportReportingSchedulerError` and `warnReportingSchedulerFailure` (from `@adcp/sdk/reporting/service`); and `DEFAULT_UNKNOWN_ERROR_RECOVERY` (from `@adcp/sdk`).
162
+
163
+ ## Other things that moved
164
+
165
+ | Was | Now |
166
+ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
167
+ | `scripts/validate-reporting-gcp.mjs` | `packages/reporting-storage/scripts/validate-reporting-gcp.mjs` (`npm run validate:reporting-gcp` still works at the repository root) |
168
+ | `examples/reliable-reporting-lifecycle`, `examples/reliable-reporting-service` | `packages/reporting-storage/examples/...` |
169
+ | Optional peers `@aws-sdk/client-s3`, `@azure/storage-blob`, `@google-cloud/storage` on `@adcp/sdk` | optional peers of `@adcp/reporting-storage` |
170
+ | Experimental policy for `reporting/gcs`, `s3`, `azure`, `bigquery` and the storage exports of `ledger` and `service` | the whole `@adcp/reporting-storage` package is pre-1.0 and experimental; see [REPORTING-STABILITY.md](guides/REPORTING-STABILITY.md) |
171
+
172
+ The consumer-side Postgres persistence (`createPostgresReportingConsumerRuntimeV1`, `REPORTING_CONSUMER_POSTGRES_MIGRATION` under `@adcp/sdk/reporting/consumer`) and webhook activity (`createPostgresReportingWebhookActivityV1`, exported from `@adcp/sdk`) stay in the SDK for now.
173
+
174
+ ## Self-grade
175
+
176
+ ```bash
177
+ # 1. no deleted subpath
178
+ grep -rnE "@adcp/sdk/reporting/(gcs|s3|azure|bigquery)" src
179
+ # 2. in every file that still imports the ledger or service subpath, no moved name (this also catches multi-line
180
+ # imports, `require` destructuring and JavaScript, which `tsc` does not check)
181
+ grep -rlE "@adcp/sdk/reporting/(ledger|service)" src | xargs grep -nE "PostgresReporting|createPostgresReliable|REPORTING_[A-Z_]+_MIGRATION|createFilesystemReporting|ReportingRowStorageV1|createReportingManagedDeliveryRuntime|createPostgresReportingNotification|runReportingLedgerMaintenance|\bmaintenance:[[:space:]]*\{"
182
+ # 3. TypeScript
183
+ npx tsc --noEmit
184
+ ```
185
+
186
+ Every line check 2 prints is either a moved name still imported from the SDK or a `maintenance:` options object to wrap.
@@ -44,7 +44,7 @@ persists strict accepted state, produces strict readback, and refuses clears the
44
44
  provider cannot honor.
45
45
 
46
46
  Adding Reliable Reporting Core to an existing seller? Start with the
47
- [adapter-first installation example](./reliable-reporting-service/README.md).
47
+ [adapter-first installation example](https://github.com/adcontextprotocol/adcp-client/blob/main/packages/reporting-storage/examples/reliable-reporting-service/README.md).
48
48
  It uses the durable ledger as the sole authority and shows trusted account,
49
49
  source-scope, timezone, and currency resolution without sample reporting data.
50
50
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adcp/sdk",
3
- "version": "16.0.0-beta.2",
3
+ "version": "16.0.0-beta.4",
4
4
  "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
5
5
  "workspaces": [
6
6
  ".",
@@ -420,46 +420,6 @@
420
420
  "default": "./dist/lib/media-buy/actions.js"
421
421
  }
422
422
  },
423
- "./reporting/gcs": {
424
- "import": {
425
- "types": "./dist/lib/reporting/gcs/index.d.mts",
426
- "default": "./dist/lib/reporting/gcs/index.mjs"
427
- },
428
- "require": {
429
- "types": "./dist/lib/reporting/gcs/index.d.ts",
430
- "default": "./dist/lib/reporting/gcs/index.js"
431
- }
432
- },
433
- "./reporting/s3": {
434
- "import": {
435
- "types": "./dist/lib/reporting/s3/index.d.mts",
436
- "default": "./dist/lib/reporting/s3/index.mjs"
437
- },
438
- "require": {
439
- "types": "./dist/lib/reporting/s3/index.d.ts",
440
- "default": "./dist/lib/reporting/s3/index.js"
441
- }
442
- },
443
- "./reporting/azure": {
444
- "import": {
445
- "types": "./dist/lib/reporting/azure/index.d.mts",
446
- "default": "./dist/lib/reporting/azure/index.mjs"
447
- },
448
- "require": {
449
- "types": "./dist/lib/reporting/azure/index.d.ts",
450
- "default": "./dist/lib/reporting/azure/index.js"
451
- }
452
- },
453
- "./reporting/bigquery": {
454
- "import": {
455
- "types": "./dist/lib/reporting/bigquery/index.d.mts",
456
- "default": "./dist/lib/reporting/bigquery/index.mjs"
457
- },
458
- "require": {
459
- "types": "./dist/lib/reporting/bigquery/index.d.ts",
460
- "default": "./dist/lib/reporting/bigquery/index.js"
461
- }
462
- },
463
423
  "./identity-3.3": {
464
424
  "import": {
465
425
  "types": "./dist/lib/identity-3.3/index.d.mts",
@@ -593,18 +553,6 @@
593
553
  "media-buy/actions": [
594
554
  "dist/lib/media-buy/actions.d.ts"
595
555
  ],
596
- "reporting/gcs": [
597
- "dist/lib/reporting/gcs/index.d.ts"
598
- ],
599
- "reporting/s3": [
600
- "dist/lib/reporting/s3/index.d.ts"
601
- ],
602
- "reporting/azure": [
603
- "dist/lib/reporting/azure/index.d.ts"
604
- ],
605
- "reporting/bigquery": [
606
- "dist/lib/reporting/bigquery/index.d.ts"
607
- ],
608
556
  "identity-3.3": [
609
557
  "dist/lib/identity-3.3/index.d.ts"
610
558
  ]
@@ -642,7 +590,6 @@
642
590
  "examples/CONTRIBUTING.md",
643
591
  "examples/storyboards/account-sync-contract.yaml",
644
592
  "examples/adcp.config.json",
645
- "examples/reliable-reporting-service/README.md",
646
593
  "examples/reliable-reporting-buyer/**/*",
647
594
  "examples/seller-3.2-starter.ts",
648
595
  "examples/supply-path-verification.ts",
@@ -676,10 +623,10 @@
676
623
  "sync:agents": "node scripts/import-claude-agents.mjs",
677
624
  "prepublishOnly": "npm run clean && npm run sync-schemas:all && (test -f src/lib/types/tools.generated.ts || npm run generate-types) && npm run build:lib && npm run check:publish-protocol-artifacts && node --test-timeout=60000 --test-force-exit --test test/lib/adcp-client.test.js test/lib/validation.test.js test/lib/zod-schemas.test.js",
678
625
  "build": "npm run build:lib",
679
- "build:lib": "npm run sync-version && npm run schemas:ensure && tsx scripts/generate-wire-spec-fields.ts && tsup && node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --project tsconfig.lib.json --emitDeclarationOnly && tsx scripts/copy-schemas-to-dist.ts && tsx scripts/copy-reporting-source-schemas.ts && tsx scripts/copy-reporting-consumer-status-fixtures.ts && tsx scripts/sync-canonical-storyboard-fixtures.ts --copy-dist && tsx scripts/copy-v2-projection-catalog.ts && tsx scripts/generate-per-tool-types.ts && tsx scripts/generate-dmts-declarations.ts",
626
+ "build:lib": "npm run sync-version && npm run schemas:ensure && tsx scripts/generate-wire-spec-fields.ts && tsup && node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --project tsconfig.lib.json --emitDeclarationOnly && tsx scripts/copy-schemas-to-dist.ts && tsx scripts/copy-reporting-source-schemas.ts && tsx scripts/copy-reporting-consumer-status-fixtures.ts && tsx scripts/sync-canonical-storyboard-fixtures.ts --copy-dist && tsx scripts/copy-v2-projection-catalog.ts && tsx scripts/generate-per-tool-types.ts && tsx scripts/generate-dmts-declarations.ts && npm run build --workspace=@adcp/reporting-storage",
680
627
  "build:test-agents": "npm run build:lib && tsc -p test-agents/tsconfig.json --rootDir test-agents",
681
628
  "pretest": "npm run build:lib",
682
- "test": "npm run test:node && npm test --workspace=packages/eslint-plugin --if-present && npm test --workspace=@adcp/reference-renderers",
629
+ "test": "npm run test:node && npm test --workspace=packages/eslint-plugin --if-present && npm test --workspace=@adcp/reference-renderers && npm run test:reporting-storage",
683
630
  "test:node": "npm run test:node:fast && npm run test:node:slow",
684
631
  "test:node:fast": "node scripts/run-node-tests.mjs --group fast",
685
632
  "test:node:fast:shard": "node scripts/run-node-tests.mjs --group fast --shard-env",
@@ -727,21 +674,23 @@
727
674
  "compliance:fork-matrix": "node --test --test-timeout=300000 'test/examples/hello-*.test.js' test/examples/proxy-seller-snap.test.js",
728
675
  "typecheck:skill-examples": "tsx scripts/typecheck-skill-examples.ts",
729
676
  "check:skill-sync": "tsx scripts/check-skill-sync.ts",
730
- "check:package": "npm run check:runtime-compat && npm run check:packed-artifact && npm run check:publish-protocol-artifacts && npm run typecheck:examples && publint --strict && node --max-old-space-size=8192 ./node_modules/@arethetypeswrong/cli/dist/index.js --pack . --exclude-entrypoints compliance-fixtures/reporting-consumer-status-v1.json compliance-fixtures/principal.yaml compliance-fixtures/reporting-core.yaml compliance-fixtures/canonical-storyboards-provenance.json",
731
- "check:packed-artifact": "node scripts/check-packed-artifact.mjs && node scripts/check-reporting-consumer-package.mjs",
677
+ "check:package": "npm run check:runtime-compat && npm run check:packed-artifact && npm run check:publish-protocol-artifacts && npm run typecheck:examples && publint --strict && node --max-old-space-size=8192 ./node_modules/@arethetypeswrong/cli/dist/index.js --pack . --exclude-entrypoints compliance-fixtures/reporting-consumer-status-v1.json compliance-fixtures/principal.yaml compliance-fixtures/reporting-core.yaml compliance-fixtures/canonical-storyboards-provenance.json && npm run check --workspace=@adcp/reporting-storage && node --max-old-space-size=8192 ./node_modules/@arethetypeswrong/cli/dist/index.js --pack packages/reporting-storage",
678
+ "check:packed-artifact": "node scripts/check-packed-artifact.mjs && node scripts/check-reporting-consumer-package.mjs && node scripts/check-reporting-storage-package.mjs",
732
679
  "check:runtime-compat": "node scripts/check-runtime-compat.mjs",
733
- "check:package-size": "node scripts/check-package-size.mjs",
680
+ "check:package-size": "node scripts/check-package-size.mjs && node packages/reporting-storage/scripts/check-package.mjs --size",
734
681
  "check:publish-protocol-artifacts": "node scripts/check-publish-protocol-artifacts.mjs",
735
682
  "verify:package": "node scripts/verify-package.mjs",
736
- "validate:reporting-gcp": "node scripts/validate-reporting-gcp.mjs",
683
+ "validate:reporting-gcp": "node packages/reporting-storage/scripts/validate-reporting-gcp.mjs",
737
684
  "check:adopter-types": "tsx scripts/check-adopter-types.ts",
738
685
  "check:adopter-types-narrow": "tsx scripts/check-adopter-types-narrow.ts",
739
686
  "sync-version": "tsx scripts/sync-version.ts",
740
687
  "validate-schemas": "tsx scripts/validate-schemas.ts",
741
688
  "lint": "eslint 'src/lib/testing/**/*.ts'",
742
689
  "lint:fix": "eslint 'src/lib/testing/**/*.ts' --fix",
690
+ "lint:boundaries": "eslint --config eslint.boundaries.config.mjs 'src/**/*.{ts,tsx,js,mjs,cjs}' 'bin/**/*.js' 'examples/**/*.{ts,js,mjs}'",
743
691
  "lint:workflows": "node scripts/lint-workflows.js",
744
692
  "typecheck": "node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --noEmit",
693
+ "typecheck:reporting-storage": "npm run typecheck --workspace=@adcp/reporting-storage",
745
694
  "typecheck:examples": "tsc --noEmit --project tsconfig.examples.json",
746
695
  "clean": "rm -rf dist/",
747
696
  "docs": "typedoc",
@@ -749,7 +698,7 @@
749
698
  "docs:serve": "npx http-server docs -p 4000 -o",
750
699
  "docs:open": "open docs/api/index.html || xdg-open docs/api/index.html || start docs/api/index.html",
751
700
  "ci:validate": "node scripts/ci-validate.js",
752
- "ci:quick": "npm run format:check && npm run typecheck && npm run build:lib && npm test",
701
+ "ci:quick": "npm run format:check && npm run typecheck && npm run build:lib && npm run typecheck:reporting-storage && npm test",
753
702
  "test:zod-openapi-portability": "node --test test/lib/zod-openapi-portability.test.js",
754
703
  "test:schemas-browser": "node --test-timeout=60000 --test test/lib/schemas-browser.test.js",
755
704
  "ci:schema-check": "npm run sync-schemas && npm run generate-types && npm run generate-registry-types -- --sync && git diff --exit-code -I '// Generated at:' src/lib/types/ src/lib/agents/ src/lib/media-buy/action-metadata.generated.ts src/lib/media-buy/update-fields.generated.ts src/lib/registry/types.generated.ts schemas/registry/registry.yaml || (echo '⚠️ Generated files are out of sync. Run: npm run sync-schemas && npm run generate-types && npm run generate-registry-types -- --sync' && exit 1)",
@@ -766,7 +715,8 @@
766
715
  "registry:mcp": "tsx src/registry/mcp-server.ts",
767
716
  "format": "prettier --write \"./**/*.{css,html,js,ts,tsx,json}\"",
768
717
  "format:check": "prettier --check \"./**/*.{css,html,js,ts,tsx,json}\"",
769
- "review:codex": "bash scripts/codex-review.sh"
718
+ "review:codex": "bash scripts/codex-review.sh",
719
+ "test:reporting-storage": "npm test --workspace=@adcp/reporting-storage"
770
720
  },
771
721
  "keywords": [
772
722
  "adcp",
@@ -802,6 +752,7 @@
802
752
  "ajv": "^8.20.0",
803
753
  "ajv-formats": "^3.0.1",
804
754
  "fast-check": "^4.9.0",
755
+ "http-message-sig": "0.3.0",
805
756
  "jose": "^6.2.10",
806
757
  "pg": "^8.23.0",
807
758
  "secure-json-parse": "^4.1.0",
@@ -814,24 +765,12 @@
814
765
  },
815
766
  "peerDependencies": {
816
767
  "@a2a-js/sdk": "^1.0.1",
817
- "@aws-sdk/client-s3": "^3.700.0",
818
- "@azure/storage-blob": "^12.23.0",
819
- "@google-cloud/storage": "^7.22.0 || ^8.2.0",
820
768
  "@modelcontextprotocol/sdk": "^1.31.0",
821
769
  "@opentelemetry/api": "^1.0.0",
822
770
  "redis": "^4.6.0 || ^5.0.0 || ^6.0.0",
823
771
  "zod": "^4.1.5"
824
772
  },
825
773
  "peerDependenciesMeta": {
826
- "@aws-sdk/client-s3": {
827
- "optional": true
828
- },
829
- "@azure/storage-blob": {
830
- "optional": true
831
- },
832
- "@google-cloud/storage": {
833
- "optional": true
834
- },
835
774
  "@opentelemetry/api": {
836
775
  "optional": true
837
776
  },
@@ -843,12 +782,9 @@
843
782
  "@a2a-js/sdk": "^1.0.1",
844
783
  "@apidevtools/json-schema-ref-parser": "^15.5.2",
845
784
  "@arethetypeswrong/cli": "^0.18.5",
846
- "@aws-sdk/client-s3": "^3.1147.0",
847
- "@azure/storage-blob": "~12.32.0",
848
785
  "@changesets/cli": "^3.0.3",
849
786
  "@commitlint/cli": "^20.5.3",
850
787
  "@commitlint/config-conventional": "^20.5.3",
851
- "@google-cloud/storage": "^7.22.0",
852
788
  "@modelcontextprotocol/sdk": "^1.31.0",
853
789
  "@opentelemetry/api": "^1.9.1",
854
790
  "@types/express": "4.17.25",
@@ -859,7 +795,6 @@
859
795
  "esbuild": "^0.28.2",
860
796
  "esbuild-fix-imports-plugin": "^1.0.23",
861
797
  "eslint": "^10.9.1",
862
- "http-message-sig": "0.3.0",
863
798
  "json-schema-to-typescript": "^15.0.4",
864
799
  "json-schema-to-zod": "^2.8.1",
865
800
  "openapi-typescript": "^7.13.0",
@@ -875,6 +810,7 @@
875
810
  "typescript": "^5.9.3",
876
811
  "typescript-eslint": "^8.68.0",
877
812
  "web-bot-auth": "0.2.0",
813
+ "workerd": "1.20260730.1",
878
814
  "zod": "^4.4.3",
879
815
  "zod-openapi": "^5.4.3"
880
816
  },
@@ -1,31 +0,0 @@
1
- import type { BlobServiceClient } from '@azure/storage-blob';
2
- import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object.mjs';
3
- /**
4
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
5
- */
6
- export interface CreateAzureBlobReportingRowObjectProviderOptionsV1 {
7
- /** Official client used by bindings without a `credentialRef`. */
8
- client?: BlobServiceClient;
9
- /**
10
- * Official clients keyed by `credentialRef`. This map is the closed set of
11
- * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
12
- * Endpoint and credentials come only from these clients.
13
- */
14
- clients?: Readonly<Record<string, BlobServiceClient>>;
15
- }
16
- /**
17
- * Azure Blob Storage row-object provider (`@adcp/sdk/reporting/azure`).
18
- *
19
- * Inject official `BlobServiceClient`s with host-owned credentials (managed
20
- * identity, workload identity). Bindings use `location: { account, container }`;
21
- * the selected client must belong to `account`. Writes are block-blob uploads
22
- * with `If-None-Match: *`. Blob versioning must be enabled on the storage account:
23
- * the recorded native version is the write-unique `versionId` and pins every read
24
- * and delete, so a delayed delete can never remove a later write that re-created
25
- * identical bytes at the same key (ETags are content-derived and cannot fence that).
26
- * The probe refuses accounts without versioning and proves create-only behaviour
27
- * empirically.
28
- *
29
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
30
- */
31
- export declare function createAzureBlobReportingRowObjectProviderV1(options: CreateAzureBlobReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;
@@ -1,31 +0,0 @@
1
- import type { BlobServiceClient } from '@azure/storage-blob';
2
- import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object';
3
- /**
4
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
5
- */
6
- export interface CreateAzureBlobReportingRowObjectProviderOptionsV1 {
7
- /** Official client used by bindings without a `credentialRef`. */
8
- client?: BlobServiceClient;
9
- /**
10
- * Official clients keyed by `credentialRef`. This map is the closed set of
11
- * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
12
- * Endpoint and credentials come only from these clients.
13
- */
14
- clients?: Readonly<Record<string, BlobServiceClient>>;
15
- }
16
- /**
17
- * Azure Blob Storage row-object provider (`@adcp/sdk/reporting/azure`).
18
- *
19
- * Inject official `BlobServiceClient`s with host-owned credentials (managed
20
- * identity, workload identity). Bindings use `location: { account, container }`;
21
- * the selected client must belong to `account`. Writes are block-blob uploads
22
- * with `If-None-Match: *`. Blob versioning must be enabled on the storage account:
23
- * the recorded native version is the write-unique `versionId` and pins every read
24
- * and delete, so a delayed delete can never remove a later write that re-created
25
- * identical bytes at the same key (ETags are content-derived and cannot fence that).
26
- * The probe refuses accounts without versioning and proves create-only behaviour
27
- * empirically.
28
- *
29
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
30
- */
31
- export declare function createAzureBlobReportingRowObjectProviderV1(options: CreateAzureBlobReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;