@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.
- package/README.md +26 -2
- package/dist/lib/client/core.d.mts +4 -0
- package/dist/lib/client/core.d.ts +4 -0
- package/dist/lib/client/core.js +13 -0
- package/dist/lib/client/core.mjs +12 -0
- package/dist/lib/conformance/property-lists.d.mts +1 -1
- package/dist/lib/conformance/property-lists.d.ts +1 -1
- package/dist/lib/conformance/property-lists.js +1 -1
- package/dist/lib/conformance/property-lists.mjs +1 -1
- package/dist/lib/core/SingleAgentClient.d.mts +10 -1
- package/dist/lib/core/SingleAgentClient.d.ts +10 -1
- package/dist/lib/core/SingleAgentClient.js +56 -7
- package/dist/lib/core/SingleAgentClient.mjs +61 -7
- package/dist/lib/core/targeting-helpers.d.mts +123 -0
- package/dist/lib/core/targeting-helpers.d.ts +123 -0
- package/dist/lib/core/targeting-helpers.js +412 -0
- package/dist/lib/core/targeting-helpers.mjs +370 -0
- package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
- package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
- package/dist/lib/entrypoints/client-account-changes.js +28 -0
- package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
- package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
- package/dist/lib/entrypoints/discovery.d.mts +9 -0
- package/dist/lib/entrypoints/discovery.d.ts +9 -0
- package/dist/lib/entrypoints/discovery.js +72 -0
- package/dist/lib/entrypoints/discovery.mjs +56 -0
- package/dist/lib/entrypoints/errors.d.mts +11 -0
- package/dist/lib/entrypoints/errors.d.ts +11 -0
- package/dist/lib/entrypoints/errors.js +159 -0
- package/dist/lib/entrypoints/errors.mjs +132 -0
- package/dist/lib/entrypoints/media-buy.d.mts +5 -0
- package/dist/lib/entrypoints/media-buy.d.ts +5 -0
- package/dist/lib/entrypoints/media-buy.js +119 -0
- package/dist/lib/entrypoints/media-buy.mjs +100 -0
- package/dist/lib/entrypoints/registry.d.mts +5 -0
- package/dist/lib/entrypoints/registry.d.ts +5 -0
- package/dist/lib/entrypoints/registry.js +61 -0
- package/dist/lib/entrypoints/registry.mjs +40 -0
- package/dist/lib/entrypoints/utils.d.mts +7 -0
- package/dist/lib/entrypoints/utils.d.ts +7 -0
- package/dist/lib/entrypoints/utils.js +100 -0
- package/dist/lib/entrypoints/utils.mjs +72 -0
- package/dist/lib/entrypoints/version.d.mts +3 -0
- package/dist/lib/entrypoints/version.d.ts +3 -0
- package/dist/lib/entrypoints/version.js +57 -0
- package/dist/lib/entrypoints/version.mjs +36 -0
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/media-buy/action-contracts.js +3 -3
- package/dist/lib/media-buy/action-contracts.mjs +1 -1
- package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
- package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
- package/dist/lib/media-buy/creative-start-policy.js +59 -0
- package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
- package/dist/lib/media-buy/valid-actions.d.mts +47 -0
- package/dist/lib/media-buy/valid-actions.d.ts +47 -0
- package/dist/lib/media-buy/valid-actions.js +42 -0
- package/dist/lib/media-buy/valid-actions.mjs +18 -0
- package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.js +209 -0
- package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
- package/dist/lib/registry/types.generated.d.ts +18 -2
- package/dist/lib/reporting/ledger/index.d.mts +1 -0
- package/dist/lib/reporting/ledger/index.d.ts +1 -0
- package/dist/lib/reporting/ledger/index.js +3 -1
- package/dist/lib/reporting/ledger/index.mjs +1 -0
- package/dist/lib/reporting/ledger/instant.d.mts +5 -0
- package/dist/lib/reporting/ledger/instant.d.ts +5 -0
- package/dist/lib/reporting/ledger/instant.js +10 -0
- package/dist/lib/reporting/ledger/instant.mjs +9 -0
- package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
- package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
- package/dist/lib/reporting/ledger/issue-events.js +310 -0
- package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
- package/dist/lib/reporting/service/index.d.mts +36 -1
- package/dist/lib/reporting/service/index.d.ts +36 -1
- package/dist/lib/reporting/service/index.js +51 -1
- package/dist/lib/reporting/service/index.mjs +52 -2
- package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
- package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
- package/dist/lib/reporting/service/scheduler-support.js +1 -1
- package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
- package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
- package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
- package/dist/lib/server/capabilities-release-projection.js +128 -0
- package/dist/lib/server/capabilities-release-projection.mjs +112 -0
- package/dist/lib/server/create-adcp-server.d.mts +29 -5
- package/dist/lib/server/create-adcp-server.d.ts +29 -5
- package/dist/lib/server/create-adcp-server.js +95 -22
- package/dist/lib/server/create-adcp-server.mjs +106 -21
- package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
- package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
- package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
- package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
- package/dist/lib/server/declared-input-schema.d.mts +108 -0
- package/dist/lib/server/declared-input-schema.d.ts +108 -0
- package/dist/lib/server/declared-input-schema.js +167 -0
- package/dist/lib/server/declared-input-schema.mjs +137 -0
- package/dist/lib/server/envelope-allowlist.d.mts +1 -105
- package/dist/lib/server/envelope-allowlist.d.ts +1 -105
- package/dist/lib/server/envelope-allowlist.js +3 -79
- package/dist/lib/server/envelope-allowlist.mjs +1 -71
- package/dist/lib/server/errors.d.mts +1 -186
- package/dist/lib/server/errors.d.ts +1 -186
- package/dist/lib/server/errors.js +3 -98
- package/dist/lib/server/errors.mjs +1 -94
- package/dist/lib/server/index.d.mts +1 -1
- package/dist/lib/server/index.d.ts +1 -1
- package/dist/lib/server/mcp-modern-server.js +21 -4
- package/dist/lib/server/mcp-modern-server.mjs +21 -4
- package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
- package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
- package/dist/lib/server/media-buy-action-resolver.js +10 -1
- package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
- package/dist/lib/server/media-buy-helpers.d.mts +1 -47
- package/dist/lib/server/media-buy-helpers.d.ts +1 -47
- package/dist/lib/server/media-buy-helpers.js +3 -23
- package/dist/lib/server/media-buy-helpers.mjs +1 -18
- package/dist/lib/server/pick-safe-details.d.mts +1 -89
- package/dist/lib/server/pick-safe-details.d.ts +1 -89
- package/dist/lib/server/pick-safe-details.js +3 -61
- package/dist/lib/server/pick-safe-details.mjs +1 -56
- package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.js +3 -190
- package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
- package/dist/lib/server/targeting-helpers.d.mts +1 -123
- package/dist/lib/server/targeting-helpers.d.ts +1 -123
- package/dist/lib/server/targeting-helpers.js +3 -393
- package/dist/lib/server/targeting-helpers.mjs +1 -370
- package/dist/lib/server/test-controller.js +7 -3
- package/dist/lib/server/test-controller.mjs +7 -3
- package/dist/lib/storage/memory-ledger.js +219 -1
- package/dist/lib/storage/memory-ledger.mjs +223 -1
- package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
- package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
- package/dist/lib/testing/comply-controller.js +7 -2
- package/dist/lib/testing/comply-controller.mjs +7 -2
- package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
- package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
- package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
- package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
- package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
- package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
- package/dist/lib/testing/storyboard/runner.js +2 -2
- package/dist/lib/testing/storyboard/runner.mjs +2 -2
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/utils/adcp-error-response.d.mts +196 -0
- package/dist/lib/utils/adcp-error-response.d.ts +196 -0
- package/dist/lib/utils/adcp-error-response.js +118 -0
- package/dist/lib/utils/adcp-error-response.mjs +95 -0
- package/dist/lib/utils/buyer-retry-policy.js +2 -2
- package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
- package/dist/lib/utils/capabilities.d.mts +6 -0
- package/dist/lib/utils/capabilities.d.ts +6 -0
- package/dist/lib/utils/capabilities.js +6 -2
- package/dist/lib/utils/capabilities.mjs +6 -2
- package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
- package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
- package/dist/lib/utils/envelope-allowlist.js +98 -0
- package/dist/lib/utils/envelope-allowlist.mjs +71 -0
- package/dist/lib/utils/pick-safe-details.d.mts +89 -0
- package/dist/lib/utils/pick-safe-details.d.ts +89 -0
- package/dist/lib/utils/pick-safe-details.js +80 -0
- package/dist/lib/utils/pick-safe-details.mjs +56 -0
- package/dist/lib/v2/projection/augment-response.d.mts +4 -0
- package/dist/lib/v2/projection/augment-response.d.ts +4 -0
- package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
- package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
- package/dist/lib/v2/projection/creative-delivery.js +20 -4
- package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
- package/dist/lib/v2/projection/index.d.mts +2 -2
- package/dist/lib/v2/projection/index.d.ts +2 -2
- package/dist/lib/v2/projection/index.js +4 -0
- package/dist/lib/v2/projection/index.mjs +5 -1
- package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.js +14 -0
- package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
- package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
- package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
- package/dist/lib/v2/projection/legacy-routes.js +2 -1
- package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
- package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.js +18 -11
- package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/docs/TYPE-SUMMARY.md +2 -2
- package/docs/guides/CREATIVE-DELIVERY.md +12 -0
- package/docs/guides/REPORTING-LEDGER.md +121 -0
- package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
- package/docs/llms.txt +2 -2
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +149 -0
- package/docs/migration-reporting-storage-package.md +10 -0
- package/package.json +106 -1
|
@@ -219,9 +219,12 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
219
219
|
const exactCatalogEntry = (0, import_catalog.lookupV1Format)(fid, options?._catalogPath);
|
|
220
220
|
const canonicalAgentUrl = (0, import_resolve_agent_properties.canonicalizeAgentUrl)(fid.agent_url);
|
|
221
221
|
const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !(0, import_address_guards.isLikelyPrivateUrl)(canonicalAgentUrl);
|
|
222
|
-
const
|
|
222
|
+
const atAaoAgent = (0, import_catalog.isAaoAgentUrl)(fid.agent_url);
|
|
223
|
+
const authoritativeOnly = options?.authoritativeOnly === true || options?._authoritativeOnly === true;
|
|
224
|
+
const aaoGuessesApply = !authoritativeOnly || atAaoAgent;
|
|
223
225
|
const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
|
|
224
|
-
|
|
226
|
+
const converterBeforeGuesses = uniqueAliasEntry !== void 0 || exactCatalogEntry === void 0 && !atAaoAgent;
|
|
227
|
+
if (converterBeforeGuesses) {
|
|
225
228
|
const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
226
229
|
if (explicit) return explicit;
|
|
227
230
|
}
|
|
@@ -259,11 +262,13 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
259
262
|
format_kind: projection.kind,
|
|
260
263
|
params,
|
|
261
264
|
v1_format_ref: [fid]
|
|
262
|
-
}
|
|
265
|
+
},
|
|
266
|
+
// An entry found only by its bare id describes the AAO's id, not this agent's.
|
|
267
|
+
...exactCatalogEntry === void 0 && !atAaoAgent && { inferredFromId: true }
|
|
263
268
|
};
|
|
264
269
|
}
|
|
265
270
|
if (catalogEntry && !catalogEntry.canonical) {
|
|
266
|
-
const custom2 = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
271
|
+
const custom2 = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
267
272
|
if (custom2) return custom2;
|
|
268
273
|
return {
|
|
269
274
|
diagnostic: {
|
|
@@ -288,7 +293,8 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
288
293
|
format_kind: globMatch.canonical,
|
|
289
294
|
params: buildParams(fid, globMatch.parameters),
|
|
290
295
|
v1_format_ref: [fid]
|
|
291
|
-
}
|
|
296
|
+
},
|
|
297
|
+
...!atAaoAgent && { inferredFromId: true }
|
|
292
298
|
};
|
|
293
299
|
}
|
|
294
300
|
if (catalogEntry?.assets) {
|
|
@@ -304,7 +310,7 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
304
310
|
};
|
|
305
311
|
}
|
|
306
312
|
}
|
|
307
|
-
const custom = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
313
|
+
const custom = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
308
314
|
if (custom) return custom;
|
|
309
315
|
return {
|
|
310
316
|
diagnostic: {
|
|
@@ -329,11 +335,11 @@ function projectV1ProductToV2(v1, options) {
|
|
|
329
335
|
for (let i = 0; i < inputFormatIds.length; i++) {
|
|
330
336
|
const fid = inputFormatIds[i];
|
|
331
337
|
const field = `products[${v1.product_id}].format_ids[${i}]`;
|
|
332
|
-
const { decl, diagnostic } = projectFormatId(fid, v1.product_id, field, options);
|
|
338
|
+
const { decl, diagnostic, inferredFromId } = projectFormatId(fid, v1.product_id, field, options);
|
|
333
339
|
if (decl) {
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
);
|
|
340
|
+
const option = typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) };
|
|
341
|
+
if (inferredFromId) (0, import_legacy_metadata.rememberInferredFromIdFormatOption)(option);
|
|
342
|
+
format_options.push(option);
|
|
337
343
|
}
|
|
338
344
|
if (diagnostic) diagnostics.push(diagnostic);
|
|
339
345
|
}
|
|
@@ -391,7 +397,8 @@ function sameIdentity(left, right) {
|
|
|
391
397
|
});
|
|
392
398
|
}
|
|
393
399
|
function compatible(option, ref) {
|
|
394
|
-
const
|
|
400
|
+
const bare = { agent_url: ref.agent_url, id: ref.id };
|
|
401
|
+
const known = projectFormatId(bare, `<bare:${ref.id}>`, `bareFormatId(${ref.id})`, { authoritativeOnly: true }).decl;
|
|
395
402
|
if (known && known.format_kind !== option.format_kind) return false;
|
|
396
403
|
const params = record(option.params) ?? {};
|
|
397
404
|
const knownParams = record(known?.params) ?? {};
|
|
@@ -15,6 +15,7 @@ import { legacyRoutesForProduct } from "./legacy-routes.mjs";
|
|
|
15
15
|
import {
|
|
16
16
|
concealLegacyFormatRefs,
|
|
17
17
|
legacyFormatRefsForDeclaration,
|
|
18
|
+
rememberInferredFromIdFormatOption,
|
|
18
19
|
rememberSynthesizedFormatOption,
|
|
19
20
|
transferLegacyCreativeMetadata
|
|
20
21
|
} from "./legacy-metadata.mjs";
|
|
@@ -202,9 +203,12 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
202
203
|
const exactCatalogEntry = lookupV1Format(fid, options?._catalogPath);
|
|
203
204
|
const canonicalAgentUrl = canonicalizeAgentUrl(fid.agent_url);
|
|
204
205
|
const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !isLikelyPrivateUrl(canonicalAgentUrl);
|
|
205
|
-
const
|
|
206
|
+
const atAaoAgent = isAaoAgentUrl(fid.agent_url);
|
|
207
|
+
const authoritativeOnly = options?.authoritativeOnly === true || options?._authoritativeOnly === true;
|
|
208
|
+
const aaoGuessesApply = !authoritativeOnly || atAaoAgent;
|
|
206
209
|
const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
|
|
207
|
-
|
|
210
|
+
const converterBeforeGuesses = uniqueAliasEntry !== void 0 || exactCatalogEntry === void 0 && !atAaoAgent;
|
|
211
|
+
if (converterBeforeGuesses) {
|
|
208
212
|
const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
209
213
|
if (explicit) return explicit;
|
|
210
214
|
}
|
|
@@ -242,11 +246,13 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
242
246
|
format_kind: projection.kind,
|
|
243
247
|
params,
|
|
244
248
|
v1_format_ref: [fid]
|
|
245
|
-
}
|
|
249
|
+
},
|
|
250
|
+
// An entry found only by its bare id describes the AAO's id, not this agent's.
|
|
251
|
+
...exactCatalogEntry === void 0 && !atAaoAgent && { inferredFromId: true }
|
|
246
252
|
};
|
|
247
253
|
}
|
|
248
254
|
if (catalogEntry && !catalogEntry.canonical) {
|
|
249
|
-
const custom2 = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
255
|
+
const custom2 = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
250
256
|
if (custom2) return custom2;
|
|
251
257
|
return {
|
|
252
258
|
diagnostic: {
|
|
@@ -271,7 +277,8 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
271
277
|
format_kind: globMatch.canonical,
|
|
272
278
|
params: buildParams(fid, globMatch.parameters),
|
|
273
279
|
v1_format_ref: [fid]
|
|
274
|
-
}
|
|
280
|
+
},
|
|
281
|
+
...!atAaoAgent && { inferredFromId: true }
|
|
275
282
|
};
|
|
276
283
|
}
|
|
277
284
|
if (catalogEntry?.assets) {
|
|
@@ -287,7 +294,7 @@ function projectFormatId(fid, productId, field, options) {
|
|
|
287
294
|
};
|
|
288
295
|
}
|
|
289
296
|
}
|
|
290
|
-
const custom = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
297
|
+
const custom = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
|
|
291
298
|
if (custom) return custom;
|
|
292
299
|
return {
|
|
293
300
|
diagnostic: {
|
|
@@ -312,11 +319,11 @@ function projectV1ProductToV2(v1, options) {
|
|
|
312
319
|
for (let i = 0; i < inputFormatIds.length; i++) {
|
|
313
320
|
const fid = inputFormatIds[i];
|
|
314
321
|
const field = `products[${v1.product_id}].format_ids[${i}]`;
|
|
315
|
-
const { decl, diagnostic } = projectFormatId(fid, v1.product_id, field, options);
|
|
322
|
+
const { decl, diagnostic, inferredFromId } = projectFormatId(fid, v1.product_id, field, options);
|
|
316
323
|
if (decl) {
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
);
|
|
324
|
+
const option = typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) };
|
|
325
|
+
if (inferredFromId) rememberInferredFromIdFormatOption(option);
|
|
326
|
+
format_options.push(option);
|
|
320
327
|
}
|
|
321
328
|
if (diagnostic) diagnostics.push(diagnostic);
|
|
322
329
|
}
|
|
@@ -374,7 +381,8 @@ function sameIdentity(left, right) {
|
|
|
374
381
|
});
|
|
375
382
|
}
|
|
376
383
|
function compatible(option, ref) {
|
|
377
|
-
const
|
|
384
|
+
const bare = { agent_url: ref.agent_url, id: ref.id };
|
|
385
|
+
const known = projectFormatId(bare, `<bare:${ref.id}>`, `bareFormatId(${ref.id})`, { authoritativeOnly: true }).decl;
|
|
378
386
|
if (known && known.format_kind !== option.format_kind) return false;
|
|
379
387
|
const params = record(option.params) ?? {};
|
|
380
388
|
const knownParams = record(known?.params) ?? {};
|
package/dist/lib/version.d.mts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* AdCP SDK library version
|
|
3
3
|
*/
|
|
4
|
-
export declare const LIBRARY_VERSION = "17.0.0-beta.
|
|
4
|
+
export declare const LIBRARY_VERSION = "17.0.0-beta.22";
|
|
5
5
|
/**
|
|
6
6
|
* AdCP specification version this library is built for
|
|
7
7
|
*/
|
|
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
|
|
|
33
33
|
* Full version information
|
|
34
34
|
*/
|
|
35
35
|
export declare const VERSION_INFO: {
|
|
36
|
-
readonly library: "17.0.0-beta.
|
|
36
|
+
readonly library: "17.0.0-beta.22";
|
|
37
37
|
readonly adcp: "3.3.0-beta.5";
|
|
38
38
|
readonly compatibleVersions: readonly ["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.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.5", "3.3-beta.5"];
|
|
39
|
-
readonly generatedAt: "2026-11-
|
|
39
|
+
readonly generatedAt: "2026-11-09T21:22:54.182Z";
|
|
40
40
|
};
|
|
41
41
|
/**
|
|
42
42
|
* Get the AdCP specification version this library is built for
|
package/dist/lib/version.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* AdCP SDK library version
|
|
3
3
|
*/
|
|
4
|
-
export declare const LIBRARY_VERSION = "17.0.0-beta.
|
|
4
|
+
export declare const LIBRARY_VERSION = "17.0.0-beta.22";
|
|
5
5
|
/**
|
|
6
6
|
* AdCP specification version this library is built for
|
|
7
7
|
*/
|
|
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
|
|
|
33
33
|
* Full version information
|
|
34
34
|
*/
|
|
35
35
|
export declare const VERSION_INFO: {
|
|
36
|
-
readonly library: "17.0.0-beta.
|
|
36
|
+
readonly library: "17.0.0-beta.22";
|
|
37
37
|
readonly adcp: "3.3.0-beta.5";
|
|
38
38
|
readonly compatibleVersions: readonly ["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.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.5", "3.3-beta.5"];
|
|
39
|
-
readonly generatedAt: "2026-11-
|
|
39
|
+
readonly generatedAt: "2026-11-09T21:22:54.182Z";
|
|
40
40
|
};
|
|
41
41
|
/**
|
|
42
42
|
* Get the AdCP specification version this library is built for
|
package/dist/lib/version.js
CHANGED
|
@@ -31,7 +31,7 @@ __export(version_exports, {
|
|
|
31
31
|
toReleasePrecisionVersion: () => toReleasePrecisionVersion
|
|
32
32
|
});
|
|
33
33
|
module.exports = __toCommonJS(version_exports);
|
|
34
|
-
const LIBRARY_VERSION = "17.0.0-beta.
|
|
34
|
+
const LIBRARY_VERSION = "17.0.0-beta.22";
|
|
35
35
|
const ADCP_VERSION = "3.3.0-beta.5";
|
|
36
36
|
const ADCP_MAJOR_VERSION = 3;
|
|
37
37
|
const COMPATIBLE_ADCP_VERSIONS = [
|
|
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
|
|
|
109
109
|
"3.3-beta.5"
|
|
110
110
|
];
|
|
111
111
|
const VERSION_INFO = {
|
|
112
|
-
library: "17.0.0-beta.
|
|
112
|
+
library: "17.0.0-beta.22",
|
|
113
113
|
adcp: "3.3.0-beta.5",
|
|
114
114
|
compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
|
|
115
|
-
generatedAt: "2026-11-
|
|
115
|
+
generatedAt: "2026-11-09T21:22:54.182Z"
|
|
116
116
|
};
|
|
117
117
|
function getAdcpVersion() {
|
|
118
118
|
return ADCP_VERSION;
|
package/dist/lib/version.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
const LIBRARY_VERSION = "17.0.0-beta.
|
|
1
|
+
const LIBRARY_VERSION = "17.0.0-beta.22";
|
|
2
2
|
const ADCP_VERSION = "3.3.0-beta.5";
|
|
3
3
|
const ADCP_MAJOR_VERSION = 3;
|
|
4
4
|
const COMPATIBLE_ADCP_VERSIONS = [
|
|
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
|
|
|
76
76
|
"3.3-beta.5"
|
|
77
77
|
];
|
|
78
78
|
const VERSION_INFO = {
|
|
79
|
-
library: "17.0.0-beta.
|
|
79
|
+
library: "17.0.0-beta.22",
|
|
80
80
|
adcp: "3.3.0-beta.5",
|
|
81
81
|
compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
|
|
82
|
-
generatedAt: "2026-11-
|
|
82
|
+
generatedAt: "2026-11-09T21:22:54.182Z"
|
|
83
83
|
};
|
|
84
84
|
function getAdcpVersion() {
|
|
85
85
|
return ADCP_VERSION;
|
package/docs/TYPE-SUMMARY.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# AdCP Type Summary
|
|
2
2
|
|
|
3
|
-
> Generated at: 2026-11-
|
|
4
|
-
> @adcp/sdk v17.0.0-beta.
|
|
3
|
+
> Generated at: 2026-11-09
|
|
4
|
+
> @adcp/sdk v17.0.0-beta.22
|
|
5
5
|
|
|
6
6
|
Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
|
|
7
7
|
|
|
@@ -267,6 +267,18 @@ it. Authorization changes and discovery invalidation invalidate the evidence.
|
|
|
267
267
|
Request-scoped custom transports require explicit capability or tool-schema
|
|
268
268
|
support and do not reuse this inferred product evidence.
|
|
269
269
|
|
|
270
|
+
Package selectors follow the seller's release even when creatives stay on the
|
|
271
|
+
legacy wire. AdCP 3.1 defines `format_option_refs` on the package request, so
|
|
272
|
+
when `supported_versions` proves a mutually served 3.1 release, a
|
|
273
|
+
`createMediaBuy` package or `updateMediaBuy` new package whose selected options
|
|
274
|
+
have no legacy `format_ids` is sent with its `format_option_refs`, and the
|
|
275
|
+
seller resolves them. Selections with a complete legacy mapping are still sent
|
|
276
|
+
as `format_ids`. AdCP 3.0 does not define the field, so a 3.0 seller, or one
|
|
277
|
+
whose release cannot be proven, gets `CreativeFormatProjectionError` instead:
|
|
278
|
+
dropping the selector would activate every format the product offers.
|
|
279
|
+
Configure `canonicalFormatLegacyResolver` to supply the legacy mapping for
|
|
280
|
+
those sellers.
|
|
281
|
+
|
|
270
282
|
Assignment-only sync and updates containing only an existing `package_id` keep
|
|
271
283
|
their existing wire behavior. Pass the matching selectors for this request to
|
|
272
284
|
use the product-based fallback; package IDs alone do not establish support.
|
|
@@ -2479,3 +2479,124 @@ The repository-only fixture at
|
|
|
2479
2479
|
23/25-hour cases,
|
|
2480
2480
|
a calendar-month boundary, and the obligation-missing path with no invented
|
|
2481
2481
|
obligation ID.
|
|
2482
|
+
|
|
2483
|
+
### Observe consumer-status mismatches: `issueObserver`
|
|
2484
|
+
|
|
2485
|
+
A `CONSUMER_STATUS_MISMATCH` is caller-scoped: only the buyer whose
|
|
2486
|
+
`sync_reporting_status` statement caused it sees it in `get_reporting_status`.
|
|
2487
|
+
To hear about one without waiting for that buyer to poll, pass an
|
|
2488
|
+
`issueObserver` (adcp-client#3648, the Python SDK's `issue_observer`):
|
|
2489
|
+
|
|
2490
|
+
```ts
|
|
2491
|
+
import { createReliableReportingService, type ReportingIssueEventV1 } from '@adcp/sdk/reporting/service';
|
|
2492
|
+
|
|
2493
|
+
async function onIssue(event: ReportingIssueEventV1) {
|
|
2494
|
+
// Delivery is at least once: deduplicate on event.eventId.
|
|
2495
|
+
if (event.kind === 'resolved') return alerts.close(event.issueId, { dedupeKey: event.eventId });
|
|
2496
|
+
if (event.issue && event.issue.responsibleParty !== 'buyer') {
|
|
2497
|
+
await alerts.open(event.issueId, {
|
|
2498
|
+
dedupeKey: event.eventId,
|
|
2499
|
+
escalated: event.kind === 'escalated',
|
|
2500
|
+
action: event.issue.recommendedAction,
|
|
2501
|
+
});
|
|
2502
|
+
}
|
|
2503
|
+
}
|
|
2504
|
+
|
|
2505
|
+
const reporting = createReliableReportingService({
|
|
2506
|
+
storage, // memoryStorage(), or postgresStorage({ pool }) with migration 0012 applied
|
|
2507
|
+
resolveConsumerId,
|
|
2508
|
+
consumerMismatchEscalation: {
|
|
2509
|
+
escalationSeconds: 4 * 3_600,
|
|
2510
|
+
operationsContact: { email: 'reporting-ops@seller.example' },
|
|
2511
|
+
},
|
|
2512
|
+
issueObserver: onIssue,
|
|
2513
|
+
// ...adapters, contact, resolveSource, resolveCurrency, resolveCoverage, windows
|
|
2514
|
+
});
|
|
2515
|
+
reporting.start({ intervalMilliseconds: 60_000, deploymentWide: true, onError: reportToSentry });
|
|
2516
|
+
```
|
|
2517
|
+
|
|
2518
|
+
**When it is called.** Once per lifecycle transition of a mismatch occurrence:
|
|
2519
|
+
|
|
2520
|
+
| `event.kind` | The transition | Recorded |
|
|
2521
|
+
| --- | --- | --- |
|
|
2522
|
+
| `opened` | A consumer's current statement started to conflict with the seller's record: a negative statement landed, or a restatement made a `received` statement stale. | In the same transaction as that `sync_reporting_status` write or revision commit. |
|
|
2523
|
+
| `escalated` | An open occurrence passed `openedAt` plus `consumerMismatchEscalation.escalationSeconds`, where the issue turns `action_required` with a `contact_*` action. | By `runCycle`'s sweep, which settles the obligation first so a cleared condition resolves instead. |
|
|
2524
|
+
| `resolved` | The statement that caused it is no longer the consumer's current leaf (the buyer superseded it), or it no longer conflicts. | In the same transaction as the write that cleared it. |
|
|
2525
|
+
|
|
2526
|
+
An occurrence follows the read path's own projection, with one difference: while the seller's own
|
|
2527
|
+
projection is degraded, `get_reporting_status` publishes the seller's issue instead of the mismatch,
|
|
2528
|
+
but the disagreement still stands, so the occurrence stays open (and can escalate). An occurrence
|
|
2529
|
+
needs at least one revision; a statement filed before the first one opens when it commits.
|
|
2530
|
+
|
|
2531
|
+
The kind union also has `acknowledged` and `waived`, the Python SDK's operator transitions
|
|
2532
|
+
(`set_issue_state`). **No TypeScript store emits them yet**: the TypeScript ledger has no operator
|
|
2533
|
+
issue-state API.
|
|
2534
|
+
|
|
2535
|
+
**Delivery needs `runCycle`.** The ledger records `opened` and `resolved` with the writes, but the
|
|
2536
|
+
observer runs only on `runCycle` (`start()`, or your own scheduler), after the worker: it sweeps
|
|
2537
|
+
escalations, then delivers committed events, each occurrence's in recording order with at most one
|
|
2538
|
+
leased at a time. Without `runCycle` events are recorded but the observer is never called, and
|
|
2539
|
+
`escalated` is never recorded. The Python SDK is the same: its worker turn does both.
|
|
2540
|
+
|
|
2541
|
+
**At least once.** An occurrence is `(issueId, consumerId)`: the `issueId` that `get_reporting_status`
|
|
2542
|
+
publishes names the obligation and the causing `reporting_status_id` but not the consumer, and two
|
|
2543
|
+
consumers may reuse one status id. Each transition is recorded exactly once, even when replicas make it
|
|
2544
|
+
together (`(issueId, consumerId, kind)` is unique). A cycle that stops after the observer returned but
|
|
2545
|
+
before the event was marked delivered delivers it again. Every delivery carries the same `eventId`,
|
|
2546
|
+
`"rpie_" + sha256(canonical_json_utf8_v1(["reporting-issue-event-v1", issueId, consumerId, kind])).hex()[:40]`
|
|
2547
|
+
(`reportingIssueEventIdV1`). That is the Python SDK's scheme with the consumer added: Python's `issue_id` is
|
|
2548
|
+
already consumer-scoped, so it hashes `[tag, issue_id, kind]`. An exact retry of `sync_reporting_status`
|
|
2549
|
+
(`unchanged`) and status reads record nothing.
|
|
2550
|
+
|
|
2551
|
+
**Failures never reach the buyer.** An observer that throws, or an async one past 10 seconds, is
|
|
2552
|
+
retried on a later cycle after a backoff of 30 seconds doubling to one hour, with no limit;
|
|
2553
|
+
`event.attempt` counts deliveries. The failure is handed to the scheduler's `onError` as a
|
|
2554
|
+
`ReportingIssueObserverError` (`component: 'issue_observer'`, with `eventId`; `issue_events` when the
|
|
2555
|
+
sweep or claim failed; `issue_events:snapshot` when the evidence could not be read, which is retried
|
|
2556
|
+
rather than delivered unrendered) and returned in `runCycle(...).issueEvents.errors`.
|
|
2557
|
+
|
|
2558
|
+
**The event.** `eventId`, `kind`, `occurredAt` (the issue's `openedAt`, the escalation boundary, or when
|
|
2559
|
+
it resolved), `accountId`, `consumerId`, `principal` (for a subscription obligation, on every kind including `resolved`, while the obligation is retained; omitted once retention removed it), `issueId`,
|
|
2560
|
+
`reportingObligationId`, `reportingStatusId`, `attempt`, and `issue`: the `ReportingLedgerIssueV1`
|
|
2561
|
+
`get_reporting_status` showed `consumerId` at `occurredAt` (`responsibleParty`, `recommendedAction`,
|
|
2562
|
+
`severity`, `openedAt`). It is `null` for `resolved`, while the seller's own projection suppressed the
|
|
2563
|
+
mismatch at that instant, and when the evidence is no longer retained. Rendering is best effort and
|
|
2564
|
+
leaves Managed Delivery out.
|
|
2565
|
+
|
|
2566
|
+
**Storage.** `memoryStorage()` records issue events. On PostgreSQL, `@adcp/reporting-storage` needs
|
|
2567
|
+
migration `0012 reporting_issue_events` (`npx adcp-reporting-storage migrate`): one new table and its
|
|
2568
|
+
indexes, additive, so workers of an earlier release keep running beside it (they record no events for
|
|
2569
|
+
their own writes). Until it is applied, writes record nothing, `postgresStorage().checkSchema()` names
|
|
2570
|
+
`0012` as pending, and a store constructed directly refuses `issueObserver` at its first cycle. The
|
|
2571
|
+
service refuses `issueObserver` at construction against a store that does not record issue events.
|
|
2572
|
+
Retention prunes only closed occurrences: resolved, every event delivered more than seven days ago, and
|
|
2573
|
+
unable to be derived again because the causing statement is no longer the consumer's current leaf or the
|
|
2574
|
+
obligation is gone. An open occurrence is never pruned, however long ago its events were delivered: the
|
|
2575
|
+
outbox is also the record of which occurrences are open, which a later supersession resolves and the sweep
|
|
2576
|
+
escalates. A resolved occurrence whose statement is still current is kept too, as the anchor that stops a
|
|
2577
|
+
later write recording its delivered events again under the same `eventId`.
|
|
2578
|
+
|
|
2579
|
+
When ledger retention retires a period (`retireExpiredPeriods`), its open occurrences resolve in the same
|
|
2580
|
+
transaction, because nothing can resolve or escalate them once the obligation and statements are gone. The
|
|
2581
|
+
`resolved` event is delivered like any other, with `issue: null` and no `principal`, and the occurrence is
|
|
2582
|
+
then pruned.
|
|
2583
|
+
|
|
2584
|
+
**Production service.** `createPostgresReliableReportingProductionService` (`@adcp/reporting-storage/service`)
|
|
2585
|
+
takes `issueObserver` too: it passes it to the core service whose `runCycle` and `start()` it drives, and
|
|
2586
|
+
adds `REPORTING_ISSUE_EVENTS_MIGRATION` to `service.setup.migrations` when it is set. The Python SDK adds the
|
|
2587
|
+
same in adcp-client-python#1873.
|
|
2588
|
+
|
|
2589
|
+
Composing the ledger without the service? Run
|
|
2590
|
+
`createReportingIssueEventDispatcherV1({ store, observer, escalation }).runOnce({ accountId })` on your
|
|
2591
|
+
own schedule.
|
|
2592
|
+
|
|
2593
|
+
**Known gaps against the Python SDK.**
|
|
2594
|
+
- `acknowledged` and `waived` are never emitted (no operator issue-state API).
|
|
2595
|
+
- A seller-side change never clears a TypeScript mismatch: the read projection only stops conflicting
|
|
2596
|
+
when the buyer supersedes its statement, while Python's `consumer_statement_conflicts` also clears
|
|
2597
|
+
`content_mismatch`, `revision_missing` and `unreadable` on the seller's own record change
|
|
2598
|
+
([#3653](https://github.com/adcontextprotocol/adcp-client/issues/3653)). `commitRevision` already
|
|
2599
|
+
records `resolved` when the projection stops conflicting, so events follow once that is fixed.
|
|
2600
|
+
- The issue id is per causing statement, not per chain occurrence, so a TypeScript and a Python seller
|
|
2601
|
+
publish different `issueId`s (and therefore `eventId`s) for the same disagreement, and the TypeScript
|
|
2602
|
+
`eventId` also hashes the consumer. Observers should not compare ids across SDKs.
|
|
@@ -469,6 +469,7 @@ npx @adcp/sdk@15.9 storyboard run https://sandbox.agent.example/mcp signed_reque
|
|
|
469
469
|
- **A2A discovery fails closed.** If the Agent Card cannot resolve to a supported JSON-RPC interface, networked vectors skip with detailed reason `signing_transport_unavailable`; the storyboard cannot pass, the `security_transport` track stays `partial`, and the command exits 3. Publish a resolvable modern or legacy Agent Card, or grade an MCP/REST binding. Do not use `--soft-fail` to dismiss actual A2A verifier failures: once discovery succeeds, they are real grades.
|
|
470
470
|
- **The in-library vector remains transport-independent.** `025-jwk-alg-crv-mismatch` is decided against the SDK verifier with no wire exchange, so its result does not grade your agent.
|
|
471
471
|
- **Vectors excluded on their own terms say so, on every protocol.** `026-non-ascii-host` reports `transport_ungradable` (no HTTP client can carry a non-ASCII authority — `fetch` punycodes it first). `028-unsigned-protocol-method-required` reports `capability_profile_mismatch` unless your `get_adcp_capabilities` declares `request_signing.protocol_methods_required_for` — **this applies on MCP runs too, not just A2A**: previously the storyboard dispatched 028 at every agent, so one that never claimed the JSON-RPC bucket could fail it. Declare the bucket (e.g. `['tasks/cancel']`) if you verify signatures on protocol methods; a declaration your AdCP line's schema rejects is discarded rather than treated as "not declared", so it cannot suppress the vector. Note `adcp grade request-signing` does not read your advertisement — it uses the profile you pass it — so the two commands can disagree about 028 by design.
|
|
472
|
+
- **Vector `027-webhook-registration-authentication-unsigned` grades only while legacy HMAC is on.** From 3.3 it declares `applies_when: "webhook_signing.legacy_hmac_fallback == true"`. The storyboard reads your `get_adcp_capabilities` and reports `capability_profile_mismatch` when the flag is false or `webhook_signing` is absent, because such a seller rejects the registration with `UNSUPPORTED_FEATURE` instead. `adcp grade request-signing` does not read your advertisement; library callers can pass `agentCapabilities` to `gradeRequestSigning()` for the same check.
|
|
472
473
|
- **A run that graded nothing exits nonzero.** Skipped steps are `passed: true`, so a coverage gap used to exit 0. `adcp storyboard step` now exits 3 when the runner could not dispatch the step, and the full assessment exits 3 when a storyboard's signing coverage went unverified — including when your own `--signing-skip-vectors` removed every vector, which is the other way to end up with nothing graded. The message names which of the two happened. Everything else keeps exit 0: other `partial` runs, legacy fixture gaps, and single steps you excluded yourself. `--soft-fail` works on both commands and reports the gap while exiting 0.
|
|
473
474
|
- **Library callers get the same knobs.** `comply(agentUrl, { request_signing: { transport: 'mcp', skipVectors: [...], onlyVectors: [...], skipRateAbuse: true, rateAbuseCap: 5 } })` from `@adcp/sdk/testing` mirrors the storyboard CLI knobs. The standalone `gradeRequestSigning()` API also accepts `signingProfileVersion: '3.2'`, matching `adcp grade request-signing --signing-profile 3.2`. `storyboard run` prefixes transport and vector-filter flags because `--transport` is already taken by the storyboard's own transport.
|
|
474
475
|
- **Mistyped flag values are rejected.** `--signing-skip-vectors` validates every id against the shipped vector set (a typo silently skipped nothing before), and `--signing-skip-rate-abuse` refuses a value — `=false` used to read as "on".
|
package/docs/llms.txt
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Ad Context Protocol (AdCP)
|
|
2
2
|
|
|
3
|
-
> Generated at: 2026-11-
|
|
4
|
-
> Library: @adcp/sdk v17.0.0-beta.
|
|
3
|
+
> Generated at: 2026-11-09
|
|
4
|
+
> Library: @adcp/sdk v17.0.0-beta.22
|
|
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.
|
|
@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
|
|
|
16
16
|
|
|
17
17
|
| Fact | Value |
|
|
18
18
|
| --- | --- |
|
|
19
|
-
| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.
|
|
20
|
-
| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.
|
|
19
|
+
| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.22` |
|
|
20
|
+
| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.22 dist.integrity` |
|
|
21
21
|
| Node.js runtime | `^20.19.0 || >=22.12.0` |
|
|
22
22
|
| Default AdCP wire release | `3.3.0-beta.5` |
|
|
23
23
|
| Maintained wire releases | `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.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.1.30`, `3.1.31`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.2.8`, `3.3.0-beta.5`, `3.3-beta.5` |
|
|
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
|
|
|
26
26
|
For a checkout at the published release commit, install the exact package version:
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
npm install --save-exact '@adcp/sdk@17.0.0-beta.
|
|
30
|
-
npm view '@adcp/sdk@17.0.0-beta.
|
|
29
|
+
npm install --save-exact '@adcp/sdk@17.0.0-beta.22'
|
|
30
|
+
npm view '@adcp/sdk@17.0.0-beta.22' dist.integrity
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
### Required and optional peers
|
|
@@ -152,6 +152,155 @@ server handlers are `mediaBuy.listCollections` and `mediaBuy.listProposals`,
|
|
|
152
152
|
or optional methods on `MediaBuyLifecyclePlatform`. Their synchronous results
|
|
153
153
|
use `outcome` and do not acquire a synthetic task `status` field.
|
|
154
154
|
|
|
155
|
+
## Creative start policy on `control_media_buy`
|
|
156
|
+
|
|
157
|
+
AdCP 3.3 lets a buyer hold a package's first enablement for serving until every
|
|
158
|
+
assigned creative is approved: `packages[].start_requires_all_creatives_approved`
|
|
159
|
+
on `control_media_buy`. A seller that does not declare
|
|
160
|
+
`media_buy.features.creative_start_policy: true` must reject `true` with
|
|
161
|
+
`UNSUPPORTED_FEATURE` before mutation, and buyers must not send it.
|
|
162
|
+
|
|
163
|
+
**This breaks sellers that honored `true` without declaring the feature.** When
|
|
164
|
+
the server's `adcpVersion` is 3.3 or later, the dispatcher now refuses such a
|
|
165
|
+
request itself, before the idempotency lookup, and the handler never sees it:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"code": "UNSUPPORTED_FEATURE",
|
|
170
|
+
"message": "start_requires_all_creatives_approved: true requires media_buy.features.creative_start_policy, which this seller does not declare",
|
|
171
|
+
"recovery": "correctable",
|
|
172
|
+
"field": "packages[0].start_requires_all_creatives_approved",
|
|
173
|
+
"suggestion": "Omit start_requires_all_creatives_approved or send false; check media_buy.features.creative_start_policy in get_adcp_capabilities before opting in",
|
|
174
|
+
"details": {
|
|
175
|
+
"feature": "media_buy.features.creative_start_policy",
|
|
176
|
+
"fields": ["packages[0].start_requires_all_creatives_approved"]
|
|
177
|
+
},
|
|
178
|
+
"mutation_outcome": "not_applied"
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`field` names the first opted-in package and `details.fields` lists every one.
|
|
183
|
+
`false` and omission always reach the handler. To accept `true`, hold the
|
|
184
|
+
package's first enablement until every current assignment is approved, echo the
|
|
185
|
+
policy on `get_media_buys`, and declare the feature:
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
createAdcpServer({
|
|
189
|
+
capabilities: { features: { creativeStartPolicy: true } },
|
|
190
|
+
// ...
|
|
191
|
+
});
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`createAdcpServerFromPlatform` takes the same `capabilities.features.creativeStartPolicy`.
|
|
195
|
+
`capabilities.overrides.media_buy.features.creative_start_policy` also counts.
|
|
196
|
+
Under `createTenantRegistry` each tenant's own capabilities decide.
|
|
197
|
+
`create_media_buy` and `update_media_buy` are not checked. Withdrawing the field
|
|
198
|
+
from their packages is pending adcontextprotocol/adcp#8767. The pinned
|
|
199
|
+
`3.3.0-beta.5` `package-request` and `package-update` schemas still declare it
|
|
200
|
+
with the same must-refuse rule, so until that lands a create or update that
|
|
201
|
+
sets `true` reaches your handler unenforced. Refuse it yourself if you don't
|
|
202
|
+
honor it. The Python SDK has the same known gap.
|
|
203
|
+
|
|
204
|
+
`mediaBuyActionResolver.resolve()` follows the same rule: it offers
|
|
205
|
+
`update_creative_start_policy` only when you pass `creativeStartPolicy: true`
|
|
206
|
+
with `metadata.update_creative_start_policy`. Without it the action is reported
|
|
207
|
+
unavailable (`not_supported_on_buy`), because the dispatcher would refuse the
|
|
208
|
+
opt-in it advertises. A seller that already offers the action adds the option:
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
mediaBuyActionResolver.resolve({
|
|
212
|
+
buy,
|
|
213
|
+
decide,
|
|
214
|
+
creativeStartPolicy: true,
|
|
215
|
+
metadata: { update_creative_start_policy: decision },
|
|
216
|
+
});
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
On the buyer side, `control_media_buy` throws `ProtocolFeatureUnsupportedError`
|
|
220
|
+
before sending when the call targets 3.3 or later and the seller's discovered
|
|
221
|
+
capabilities lack the feature. The error has `code: 'UNSUPPORTED_FEATURE'`, the
|
|
222
|
+
same `field`, `details.feature` and `details.fields` as the seller's refusal, and
|
|
223
|
+
`dispatched: false`; `getClientPreflightAdcpError(error)` returns the AdCP error.
|
|
224
|
+
With synthetic or missing capabilities the client sends and the seller decides.
|
|
225
|
+
Check `client.supports('creative_start_policy')`, or
|
|
226
|
+
`capabilities.features.creativeStartPolicy`, before opting in.
|
|
227
|
+
|
|
228
|
+
## Custom tool input validation
|
|
229
|
+
|
|
230
|
+
Tools registered with a zod `inputSchema` now validate it in the AdCP layer
|
|
231
|
+
instead of the MCP SDK (#3666). This covers:
|
|
232
|
+
|
|
233
|
+
- `customTools` on `createAdcpServer`, and so `tasks_get` on `createAdcpServerFromPlatform`
|
|
234
|
+
- `comply_test_controller` from `registerTestController`, `createComplyController().register()` and `createAdcpServerFromPlatform({ complyTest })`
|
|
235
|
+
|
|
236
|
+
MCP `tools/list` still advertises the declared schema.
|
|
237
|
+
|
|
238
|
+
**Buyers: the error shape changed.** A call that fails the schema used to get
|
|
239
|
+
the MCP SDK's bare `-32602` text result, with no `structuredContent` and no
|
|
240
|
+
`context`. It now gets an AdCP error that echoes `context`, like framework tools:
|
|
241
|
+
|
|
242
|
+
```jsonc
|
|
243
|
+
{
|
|
244
|
+
"adcp_error": {
|
|
245
|
+
"code": "INVALID_REQUEST",
|
|
246
|
+
"message": "search_brands request failed schema validation at /query: must have required property 'query'",
|
|
247
|
+
"recovery": "correctable",
|
|
248
|
+
"field": "query",
|
|
249
|
+
"issues": [{ "pointer": "/query", "message": "must have required property 'query'", "keyword": "required" }],
|
|
250
|
+
"details": { "tool": "search_brands", "side": "request", "issues": [/* the same issues */] }
|
|
251
|
+
},
|
|
252
|
+
"context": { "trace": "tr-1" },
|
|
253
|
+
"status": "failed",
|
|
254
|
+
"adcp_version": "3.3-beta.5"
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Read `adcp_error` instead of matching the `-32602` text or its `Input
|
|
259
|
+
validation error:` prefix. Framework tools still use `VALIDATION_ERROR` for
|
|
260
|
+
request-schema failures. #3674 tracks moving them to `INVALID_REQUEST`, the
|
|
261
|
+
spec's code for schema violations.
|
|
262
|
+
|
|
263
|
+
**Sellers: handlers receive the parsed value on every path.** On MCP, nothing
|
|
264
|
+
changes for a valid call: the handler gets the value the schema parsed, with
|
|
265
|
+
coercion, defaults and transforms applied and undeclared keys stripped.
|
|
266
|
+
`AdcpServer.invoke()`, `dispatchTestRequest()` and A2A used to skip the schema
|
|
267
|
+
and pass the caller's raw arguments to the handler. **They now validate too, and
|
|
268
|
+
pass the same parsed, stripped value.** A handler on those paths no longer sees
|
|
269
|
+
keys its schema does not declare, and an invalid call no longer reaches it.
|
|
270
|
+
|
|
271
|
+
If a handler reads keys its schema does not declare, declare them. To keep every
|
|
272
|
+
key, use a loose object:
|
|
273
|
+
|
|
274
|
+
```ts
|
|
275
|
+
customTools: {
|
|
276
|
+
vendor_lookup: {
|
|
277
|
+
// Keeps undeclared keys instead of stripping them.
|
|
278
|
+
inputSchema: z.looseObject({ query: z.string() }), // zod 3: z.object({...}).passthrough()
|
|
279
|
+
handler: async args => {
|
|
280
|
+
/* … */
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
},
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
The arguments are parsed once, and everything that reads them uses the parsed
|
|
287
|
+
value: `identity33` authorization, release selection and the handler. On
|
|
288
|
+
`invoke()`, `dispatchTestRequest()` and A2A, authorization and release selection
|
|
289
|
+
used to read the raw arguments. They now see the parsed value.
|
|
290
|
+
|
|
291
|
+
**Behavior change on A2A, `invoke()` and `dispatchTestRequest()`:** a custom tool
|
|
292
|
+
whose schema does not declare `adcp_version` used to let the caller's raw
|
|
293
|
+
`adcp_version` select the release on those paths. Now the schema strips that
|
|
294
|
+
field, so the server's default release applies, as it always has on MCP. A2A
|
|
295
|
+
has no AdCP version negotiation at the envelope level: `A2A-Version` selects
|
|
296
|
+
only the A2A wire. Framework tools are unchanged. To let a buyer pick the
|
|
297
|
+
release, declare `adcp_version` (and `adcp_major_version`) in the schema. A
|
|
298
|
+
declared default or coercion then selects the release.
|
|
299
|
+
|
|
300
|
+
Rejections on these tools echo the caller's `context` even when the schema
|
|
301
|
+
strips it: validation, version, authorization, and errors your handler returns
|
|
302
|
+
or throws.
|
|
303
|
+
|
|
155
304
|
## AdCP 3.3.0-beta.5
|
|
156
305
|
|
|
157
306
|
SDK 17 now pins AdCP `3.3.0-beta.5` and no longer packages or advertises
|
|
@@ -188,6 +188,16 @@ See [Orphaned object collection](guides/REPORTING-OPERATIONS.md#adopting-row-sto
|
|
|
188
188
|
2. The `adcp_reporting_row_sets` and `adcp_reporting_row_write_intents` columns reference the ID by foreign key and carry no bound of their own, so nothing else changes.
|
|
189
189
|
3. The bound is exported as `REPORTING_ROW_BINDING_ID_MAX_LENGTH` and `REPORTING_ROW_CREDENTIAL_REF_MAX_LENGTH`. A provider's `clients` map accepts the same 255-character references.
|
|
190
190
|
|
|
191
|
+
### Issue-lifecycle events (storage `0.3`, migration `0012`)
|
|
192
|
+
|
|
193
|
+
`createReliableReportingService({ issueObserver })` (adcp-client#3648) reads an outbox of `CONSUMER_STATUS_MISMATCH` transitions that `PostgresReportingLedgerStore` records beside its writes. Every deployment upgrading the storage package must apply the migration, because `postgresStorage().checkSchema()` requires every shipped version.
|
|
194
|
+
|
|
195
|
+
1. Run `npx adcp-reporting-storage migrate` (version `0012`, `reporting_issue_events`, additive; the SQL is exported as `REPORTING_ISSUE_EVENTS_MIGRATION`). It creates `adcp_reporting_issue_events` and its indexes and changes no existing table, key, function or trigger, so it is safe while workers of the previous release still run. Those workers neither read nor write the table and record no events for the transitions they make.
|
|
196
|
+
2. Until it is applied, `sync_reporting_status` writes and revision commits record nothing and `store.issueEventsReady()` is `false`; nothing else changes. `checkSchema()` names `0012` as pending.
|
|
197
|
+
3. Without an `issueObserver`, nothing reads the table. Rows accumulate only for consumer-mismatch transitions. The dispatcher prunes a closed occurrence (resolved, with its statement superseded or its obligation gone) seven days after its last event was delivered, and never prunes an open one, because the table also records which occurrences are open.
|
|
198
|
+
|
|
199
|
+
The Python SDK ships the same outbox as its migration `0008` (adcp-client-python#1874). The version numbers differ because the two packages' migration lists already differ, and neither moves a storage contract: the Python storage contract stays `2`, and this package has no contract version.
|
|
200
|
+
|
|
191
201
|
### `service.setup.migrations` comes from the store
|
|
192
202
|
|
|
193
203
|
`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.
|