@adcp/sdk 17.0.0-beta.24 → 17.0.0-beta.26

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 (89) hide show
  1. package/dist/lib/adapters/version/schema-projection.d.mts +11 -0
  2. package/dist/lib/adapters/version/schema-projection.d.ts +11 -0
  3. package/dist/lib/adapters/version/schema-projection.js +52 -0
  4. package/dist/lib/adapters/version/schema-projection.mjs +51 -0
  5. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  6. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  7. package/dist/lib/discovery/property-crawler.js +15 -2
  8. package/dist/lib/discovery/property-crawler.mjs +15 -2
  9. package/dist/lib/discovery/resolve-agent-properties.d.mts +81 -8
  10. package/dist/lib/discovery/resolve-agent-properties.d.ts +81 -8
  11. package/dist/lib/discovery/resolve-agent-properties.js +94 -14
  12. package/dist/lib/discovery/resolve-agent-properties.mjs +91 -13
  13. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  14. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  15. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  16. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  17. package/dist/lib/entrypoints/discovery.js +4 -0
  18. package/dist/lib/entrypoints/discovery.mjs +5 -1
  19. package/dist/lib/index.d.mts +1 -1
  20. package/dist/lib/index.d.ts +1 -1
  21. package/dist/lib/index.js +4 -0
  22. package/dist/lib/index.mjs +5 -1
  23. package/dist/lib/reporting/evidence.d.mts +8 -0
  24. package/dist/lib/reporting/evidence.d.ts +8 -0
  25. package/dist/lib/reporting/evidence.js +10 -2
  26. package/dist/lib/reporting/evidence.mjs +8 -1
  27. package/dist/lib/reporting/ledger/index.d.mts +1 -1
  28. package/dist/lib/reporting/ledger/index.d.ts +1 -1
  29. package/dist/lib/reporting/ledger/index.js +3 -1
  30. package/dist/lib/reporting/ledger/index.mjs +4 -2
  31. package/dist/lib/reporting/ledger/status-ingest.js +3 -2
  32. package/dist/lib/reporting/ledger/status-ingest.mjs +3 -2
  33. package/dist/lib/reporting/subscriptions/engine.js +1 -1
  34. package/dist/lib/reporting/subscriptions/engine.mjs +1 -1
  35. package/dist/lib/server/account-response-identity.d.mts +4 -3
  36. package/dist/lib/server/account-response-identity.d.ts +4 -3
  37. package/dist/lib/server/account-response-identity.js +8 -4
  38. package/dist/lib/server/account-response-identity.mjs +8 -4
  39. package/dist/lib/server/credential-policy.js +5 -0
  40. package/dist/lib/server/credential-policy.mjs +5 -0
  41. package/dist/lib/server/decisioning/account.js +14 -3
  42. package/dist/lib/server/decisioning/account.mjs +16 -4
  43. package/dist/lib/server/notification-subscriptions/runtime.d.mts +6 -0
  44. package/dist/lib/server/notification-subscriptions/runtime.d.ts +6 -0
  45. package/dist/lib/server/notification-subscriptions/runtime.js +99 -0
  46. package/dist/lib/server/notification-subscriptions/runtime.mjs +98 -0
  47. package/dist/lib/server/principal/reporting-subscriptions.js +4 -1
  48. package/dist/lib/server/principal/reporting-subscriptions.mjs +4 -1
  49. package/dist/lib/server/reporting-delivery-config.d.mts +2 -2
  50. package/dist/lib/server/reporting-delivery-config.d.ts +2 -2
  51. package/dist/lib/server/reporting-delivery-config.js +9 -3
  52. package/dist/lib/server/reporting-delivery-config.mjs +9 -3
  53. package/dist/lib/server/wire-safe.js +3 -0
  54. package/dist/lib/server/wire-safe.mjs +3 -0
  55. package/dist/lib/supply-path/validation.d.mts +8 -0
  56. package/dist/lib/supply-path/validation.d.ts +8 -0
  57. package/dist/lib/testing/compliance/comply.js +1 -1
  58. package/dist/lib/testing/compliance/comply.mjs +3 -2
  59. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  60. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  61. package/dist/lib/testing/storyboard/index.js +6 -0
  62. package/dist/lib/testing/storyboard/index.mjs +6 -0
  63. package/dist/lib/testing/storyboard/loader.js +52 -28
  64. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  65. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  66. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  67. package/dist/lib/testing/storyboard/runner.js +75 -7
  68. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  69. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  70. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  71. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  72. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  73. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  74. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  75. package/dist/lib/utils/json-depth.d.mts +8 -0
  76. package/dist/lib/utils/json-depth.d.ts +8 -0
  77. package/dist/lib/utils/json-depth.js +18 -2
  78. package/dist/lib/utils/json-depth.mjs +16 -1
  79. package/dist/lib/version.d.mts +3 -3
  80. package/dist/lib/version.d.ts +3 -3
  81. package/dist/lib/version.js +3 -3
  82. package/dist/lib/version.mjs +3 -3
  83. package/docs/TYPE-SUMMARY.md +2 -2
  84. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  85. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  86. package/docs/llms.txt +2 -2
  87. package/docs/migration-14.x-rc-worksheet.md +4 -4
  88. package/docs/migration-16-to-17.md +47 -8
  89. package/package.json +1 -1
@@ -29,5 +29,16 @@ export interface ProjectionResult<T = unknown> {
29
29
  * nothing needs removing or when either release has no schema for the tool.
30
30
  */
31
31
  export declare function projectToolPayload<T>(toolName: string, direction: Direction, payload: T, fromVersion: string, toVersion: string): ProjectionResult<T>;
32
+ /**
33
+ * Remove every member the schema at `schemaRef` does not declare, at any depth.
34
+ * Declared free-form maps (objects whose schema declares no properties, such as
35
+ * `ext`) keep their contents, and a typed `additionalProperties` schema
36
+ * declares its keys; the boolean `additionalProperties: true` of an open object
37
+ * declares nothing. Used where AdCP 3.3.0-beta.6 opened schemas
38
+ * (adcontextprotocol/adcp#8866) that the SDK relied on to keep undeclared data
39
+ * out. Throws when the schema is unavailable or the value is deeper than the
40
+ * projection bound.
41
+ */
42
+ export declare function projectToDeclaredMembers<T>(schemaRef: string, value: T, version?: string): ProjectionResult<T>;
32
43
  /** Whether the release's schema bundle defines a request schema for the tool. */
33
44
  export declare function releaseDefinesTool(toolName: string, version: string): boolean;
@@ -29,5 +29,16 @@ export interface ProjectionResult<T = unknown> {
29
29
  * nothing needs removing or when either release has no schema for the tool.
30
30
  */
31
31
  export declare function projectToolPayload<T>(toolName: string, direction: Direction, payload: T, fromVersion: string, toVersion: string): ProjectionResult<T>;
32
+ /**
33
+ * Remove every member the schema at `schemaRef` does not declare, at any depth.
34
+ * Declared free-form maps (objects whose schema declares no properties, such as
35
+ * `ext`) keep their contents, and a typed `additionalProperties` schema
36
+ * declares its keys; the boolean `additionalProperties: true` of an open object
37
+ * declares nothing. Used where AdCP 3.3.0-beta.6 opened schemas
38
+ * (adcontextprotocol/adcp#8866) that the SDK relied on to keep undeclared data
39
+ * out. Throws when the schema is unavailable or the value is deeper than the
40
+ * projection bound.
41
+ */
42
+ export declare function projectToDeclaredMembers<T>(schemaRef: string, value: T, version?: string): ProjectionResult<T>;
32
43
  /** Whether the release's schema bundle defines a request schema for the tool. */
33
44
  export declare function releaseDefinesTool(toolName: string, version: string): boolean;
@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
18
18
  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
19
  var schema_projection_exports = {};
20
20
  __export(schema_projection_exports, {
21
+ projectToDeclaredMembers: () => projectToDeclaredMembers,
21
22
  projectToolPayload: () => projectToolPayload,
22
23
  releaseDefinesTool: () => releaseDefinesTool
23
24
  });
@@ -284,6 +285,56 @@ function projectToolPayload(toolName, direction, payload, fromVersion, toVersion
284
285
  const projected = project(payload, [source], [target], "", dropped, 0, envelopeKeys(toVersion));
285
286
  return { value: projected === OMIT ? payload : projected, dropped };
286
287
  }
288
+ function typesObject(schema) {
289
+ return schema.type === "object" || Array.isArray(schema.type) && schema.type.includes("object");
290
+ }
291
+ function keepDeclared(value, nodes, path, dropped, depth) {
292
+ if (depth > MAX_DEPTH) throw new RangeError("Value exceeds the maximum schema projection depth");
293
+ const expanded = nodes.flatMap((node) => expand(node, value, depth).nodes);
294
+ if (expanded.some((node) => typeof node.schema.$ref === "string")) {
295
+ throw new Error("Declared-member projection could not resolve a schema reference");
296
+ }
297
+ if (Array.isArray(value)) {
298
+ const items = expanded.map((node) => child(node, node.schema.items)).filter((n) => !!n);
299
+ if (items.length === 0) return value;
300
+ let changed2 = false;
301
+ const out2 = value.map((item, index2) => {
302
+ const projected = keepDeclared(item, items, `${path}[${index2}]`, dropped, depth + 1);
303
+ if (projected !== item) changed2 = true;
304
+ return projected;
305
+ });
306
+ return changed2 ? out2 : value;
307
+ }
308
+ if (!isObject(value)) return value;
309
+ const index = indexProperties(expanded);
310
+ if (!index.declares && expanded.some((node) => typesObject(node.schema))) return value;
311
+ let changed = false;
312
+ const out = {};
313
+ for (const [key, entry] of Object.entries(value)) {
314
+ const entryPath = joinPath(path, key);
315
+ const schemas = schemasForKey(index, key) ?? nonEmpty(index.additional);
316
+ if (!schemas) {
317
+ dropped.push({ path: entryPath, kind: "field" });
318
+ changed = true;
319
+ continue;
320
+ }
321
+ const projected = keepDeclared(entry, schemas, entryPath, dropped, depth + 1);
322
+ if (projected !== entry) changed = true;
323
+ out[key] = projected;
324
+ }
325
+ return changed ? out : value;
326
+ }
327
+ function projectToDeclaredMembers(schemaRef, value, version) {
328
+ const document = (0, import_schema_loader.getSchemaDocumentByRef)(schemaRef, version);
329
+ if (!document) throw new Error(`Schema unavailable for declared-member projection: ${schemaRef}`);
330
+ const root = document.schema;
331
+ const node = {
332
+ schema: root,
333
+ doc: { root, base: absoluteBase(root.$id), version: version ?? document.resolvedVersion }
334
+ };
335
+ const dropped = [];
336
+ return { value: keepDeclared(value, [node], "", dropped, 0), dropped };
337
+ }
287
338
  const NO_PROTECTED_KEYS = /* @__PURE__ */ new Set();
288
339
  const BASELINE_ENVELOPE_KEYS = [
289
340
  "adcp_error",
@@ -324,6 +375,7 @@ function releaseDefinesTool(toolName, version) {
324
375
  }
325
376
  // Annotate the CommonJS export names for ESM import in node:
326
377
  0 && (module.exports = {
378
+ projectToDeclaredMembers,
327
379
  projectToolPayload,
328
380
  releaseDefinesTool
329
381
  });
@@ -260,6 +260,56 @@ function projectToolPayload(toolName, direction, payload, fromVersion, toVersion
260
260
  const projected = project(payload, [source], [target], "", dropped, 0, envelopeKeys(toVersion));
261
261
  return { value: projected === OMIT ? payload : projected, dropped };
262
262
  }
263
+ function typesObject(schema) {
264
+ return schema.type === "object" || Array.isArray(schema.type) && schema.type.includes("object");
265
+ }
266
+ function keepDeclared(value, nodes, path, dropped, depth) {
267
+ if (depth > MAX_DEPTH) throw new RangeError("Value exceeds the maximum schema projection depth");
268
+ const expanded = nodes.flatMap((node) => expand(node, value, depth).nodes);
269
+ if (expanded.some((node) => typeof node.schema.$ref === "string")) {
270
+ throw new Error("Declared-member projection could not resolve a schema reference");
271
+ }
272
+ if (Array.isArray(value)) {
273
+ const items = expanded.map((node) => child(node, node.schema.items)).filter((n) => !!n);
274
+ if (items.length === 0) return value;
275
+ let changed2 = false;
276
+ const out2 = value.map((item, index2) => {
277
+ const projected = keepDeclared(item, items, `${path}[${index2}]`, dropped, depth + 1);
278
+ if (projected !== item) changed2 = true;
279
+ return projected;
280
+ });
281
+ return changed2 ? out2 : value;
282
+ }
283
+ if (!isObject(value)) return value;
284
+ const index = indexProperties(expanded);
285
+ if (!index.declares && expanded.some((node) => typesObject(node.schema))) return value;
286
+ let changed = false;
287
+ const out = {};
288
+ for (const [key, entry] of Object.entries(value)) {
289
+ const entryPath = joinPath(path, key);
290
+ const schemas = schemasForKey(index, key) ?? nonEmpty(index.additional);
291
+ if (!schemas) {
292
+ dropped.push({ path: entryPath, kind: "field" });
293
+ changed = true;
294
+ continue;
295
+ }
296
+ const projected = keepDeclared(entry, schemas, entryPath, dropped, depth + 1);
297
+ if (projected !== entry) changed = true;
298
+ out[key] = projected;
299
+ }
300
+ return changed ? out : value;
301
+ }
302
+ function projectToDeclaredMembers(schemaRef, value, version) {
303
+ const document = getSchemaDocumentByRef(schemaRef, version);
304
+ if (!document) throw new Error(`Schema unavailable for declared-member projection: ${schemaRef}`);
305
+ const root = document.schema;
306
+ const node = {
307
+ schema: root,
308
+ doc: { root, base: absoluteBase(root.$id), version: version ?? document.resolvedVersion }
309
+ };
310
+ const dropped = [];
311
+ return { value: keepDeclared(value, [node], "", dropped, 0), dropped };
312
+ }
263
313
  const NO_PROTECTED_KEYS = /* @__PURE__ */ new Set();
264
314
  const BASELINE_ENVELOPE_KEYS = [
265
315
  "adcp_error",
@@ -299,6 +349,7 @@ function releaseDefinesTool(toolName, version) {
299
349
  }
300
350
  }
301
351
  export {
352
+ projectToDeclaredMembers,
302
353
  projectToolPayload,
303
354
  releaseDefinesTool
304
355
  };
@@ -33,10 +33,21 @@ export interface PropertyCrawlerConfig {
33
33
  /** Custom identifier for outbound requests. Used as User-Agent for protocol
34
34
  * calls to agents and included in the From header for direct property fetches. */
35
35
  userAgent?: string;
36
+ /**
37
+ * AdCP release the crawler targets. Passed to each agent's client and used
38
+ * to match the agent against `authorized_agents[].url` when the agent's
39
+ * capabilities response does not report the release it served. Defaults to
40
+ * the SDK's pinned `ADCP_VERSION`. At 3.3 or later an origin-only entry
41
+ * authorizes the agent at any path on that origin (adcp#8862).
42
+ */
43
+ adcpVersion?: string;
36
44
  }
37
45
  export declare class PropertyCrawler {
38
46
  private logger;
39
47
  private userAgent?;
48
+ private adcpVersion?;
49
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
50
+ private servedVersions;
40
51
  constructor(config?: PropertyCrawlerConfig);
41
52
  /**
42
53
  * Crawl multiple agents to discover their publisher domains and properties
@@ -33,10 +33,21 @@ export interface PropertyCrawlerConfig {
33
33
  /** Custom identifier for outbound requests. Used as User-Agent for protocol
34
34
  * calls to agents and included in the From header for direct property fetches. */
35
35
  userAgent?: string;
36
+ /**
37
+ * AdCP release the crawler targets. Passed to each agent's client and used
38
+ * to match the agent against `authorized_agents[].url` when the agent's
39
+ * capabilities response does not report the release it served. Defaults to
40
+ * the SDK's pinned `ADCP_VERSION`. At 3.3 or later an origin-only entry
41
+ * authorizes the agent at any path on that origin (adcp#8862).
42
+ */
43
+ adcpVersion?: string;
36
44
  }
37
45
  export declare class PropertyCrawler {
38
46
  private logger;
39
47
  private userAgent?;
48
+ private adcpVersion?;
49
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
50
+ private servedVersions;
40
51
  constructor(config?: PropertyCrawlerConfig);
41
52
  /**
42
53
  * Crawl multiple agents to discover their publisher domains and properties
@@ -29,11 +29,15 @@ var import_validate_user_agent = require('../utils/validate-user-agent.js');
29
29
  var import_ssrf_fetch = require('../net/ssrf-fetch.js');
30
30
  var import_probe_policy = require('../utils/probe-policy.js');
31
31
  var import_resolve_agent_properties = require('./resolve-agent-properties.js');
32
+ var import_adcp_version_config = require('../utils/adcp-version-config.js');
32
33
  var import_adagents_redirects = require('./adagents-redirects.js');
33
34
  const MAX_ADAGENTS_BODY_BYTES = 256 * 1024;
34
35
  class PropertyCrawler {
35
36
  logger;
36
37
  userAgent;
38
+ adcpVersion;
39
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
40
+ servedVersions = /* @__PURE__ */ new Map();
37
41
  constructor(config) {
38
42
  this.logger = (0, import_logger.createLogger)({
39
43
  level: config?.logLevel || "warn"
@@ -42,6 +46,9 @@ class PropertyCrawler {
42
46
  (0, import_validate_user_agent.validateUserAgent)(config.userAgent);
43
47
  }
44
48
  this.userAgent = config?.userAgent;
49
+ if (config?.adcpVersion !== void 0) {
50
+ this.adcpVersion = (0, import_adcp_version_config.resolveAdcpVersion)(config.adcpVersion);
51
+ }
45
52
  }
46
53
  /**
47
54
  * Crawl multiple agents to discover their publisher domains and properties
@@ -57,6 +64,7 @@ class PropertyCrawler {
57
64
  };
58
65
  const index = (0, import_property_index.getPropertyIndex)();
59
66
  const allPublisherDomains = /* @__PURE__ */ new Set();
67
+ this.servedVersions.clear();
60
68
  for (const agentInfo of agents) {
61
69
  try {
62
70
  const domains = await this.crawlAgent(agentInfo);
@@ -95,7 +103,9 @@ class PropertyCrawler {
95
103
  for (const agentUrl of claimingAgents) {
96
104
  let attributable;
97
105
  if (adAgentsFile) {
98
- const scope = (0, import_resolve_agent_properties.resolveAgentProperties)(adAgentsFile, agentUrl);
106
+ const scope = (0, import_resolve_agent_properties.resolveAgentProperties)(adAgentsFile, agentUrl, {
107
+ adcpVersion: this.servedVersions.get(agentUrl) ?? this.adcpVersion
108
+ });
99
109
  attributable = scope.properties;
100
110
  } else {
101
111
  attributable = properties;
@@ -120,10 +130,13 @@ class PropertyCrawler {
120
130
  protocol: agentInfo.protocol || "mcp",
121
131
  ...agentInfo.auth_token && { auth_token: agentInfo.auth_token }
122
132
  },
123
- { userAgent: this.userAgent }
133
+ { userAgent: this.userAgent, ...this.adcpVersion !== void 0 && { adcpVersion: this.adcpVersion } }
124
134
  );
125
135
  try {
126
136
  const capabilities = await client.getCapabilities();
137
+ if (capabilities.servedVersion) {
138
+ this.servedVersions.set(agentInfo.agent_url, capabilities.servedVersion);
139
+ }
127
140
  if (!capabilities.publisherDomains) {
128
141
  return [];
129
142
  }
@@ -6,11 +6,15 @@ import { validateUserAgent } from "../utils/validate-user-agent.mjs";
6
6
  import { SsrfRefusedError, SSRF_TRANSIENT_CODES, decodeBodyAsJsonOrText } from "../net/ssrf-fetch.mjs";
7
7
  import { isInternalProbesAllowed } from "../utils/probe-policy.mjs";
8
8
  import { resolveAgentProperties } from "./resolve-agent-properties.mjs";
9
+ import { resolveAdcpVersion } from "../utils/adcp-version-config.mjs";
9
10
  import { AdAgentsRedirectRefusedError, ssrfSafeFetchAdAgents } from "./adagents-redirects.mjs";
10
11
  const MAX_ADAGENTS_BODY_BYTES = 256 * 1024;
11
12
  class PropertyCrawler {
12
13
  logger;
13
14
  userAgent;
15
+ adcpVersion;
16
+ /** Release each crawled agent served for `get_adcp_capabilities`, keyed by `agent_url`. */
17
+ servedVersions = /* @__PURE__ */ new Map();
14
18
  constructor(config) {
15
19
  this.logger = createLogger({
16
20
  level: config?.logLevel || "warn"
@@ -19,6 +23,9 @@ class PropertyCrawler {
19
23
  validateUserAgent(config.userAgent);
20
24
  }
21
25
  this.userAgent = config?.userAgent;
26
+ if (config?.adcpVersion !== void 0) {
27
+ this.adcpVersion = resolveAdcpVersion(config.adcpVersion);
28
+ }
22
29
  }
23
30
  /**
24
31
  * Crawl multiple agents to discover their publisher domains and properties
@@ -34,6 +41,7 @@ class PropertyCrawler {
34
41
  };
35
42
  const index = getPropertyIndex();
36
43
  const allPublisherDomains = /* @__PURE__ */ new Set();
44
+ this.servedVersions.clear();
37
45
  for (const agentInfo of agents) {
38
46
  try {
39
47
  const domains = await this.crawlAgent(agentInfo);
@@ -72,7 +80,9 @@ class PropertyCrawler {
72
80
  for (const agentUrl of claimingAgents) {
73
81
  let attributable;
74
82
  if (adAgentsFile) {
75
- const scope = resolveAgentProperties(adAgentsFile, agentUrl);
83
+ const scope = resolveAgentProperties(adAgentsFile, agentUrl, {
84
+ adcpVersion: this.servedVersions.get(agentUrl) ?? this.adcpVersion
85
+ });
76
86
  attributable = scope.properties;
77
87
  } else {
78
88
  attributable = properties;
@@ -97,10 +107,13 @@ class PropertyCrawler {
97
107
  protocol: agentInfo.protocol || "mcp",
98
108
  ...agentInfo.auth_token && { auth_token: agentInfo.auth_token }
99
109
  },
100
- { userAgent: this.userAgent }
110
+ { userAgent: this.userAgent, ...this.adcpVersion !== void 0 && { adcpVersion: this.adcpVersion } }
101
111
  );
102
112
  try {
103
113
  const capabilities = await client.getCapabilities();
114
+ if (capabilities.servedVersion) {
115
+ this.servedVersions.set(agentInfo.agent_url, capabilities.servedVersion);
116
+ }
104
117
  if (!capabilities.publisherDomains) {
105
118
  return [];
106
119
  }
@@ -25,6 +25,19 @@
25
25
  * top-level property to every listed agent is gone.
26
26
  */
27
27
  import type { AdAgentsJson, AuthorizedAgent, Property, PublisherPropertySelector, SinglePublisherPropertySelector } from './types.mjs';
28
+ /** Options shared by the `authorized_agents[].url` matching helpers. */
29
+ export interface AgentUrlMatchOptions {
30
+ /**
31
+ * AdCP release the caller negotiated or targets. Defaults to the SDK's
32
+ * pinned `ADCP_VERSION`.
33
+ *
34
+ * At 3.3 or later an origin-only entry (`https://agent.example.com`)
35
+ * authorizes the agent at that origin whatever its path. Below 3.3, or
36
+ * when the value is not a parseable AdCP version, every entry matches by
37
+ * exact canonical URL.
38
+ */
39
+ adcpVersion?: string;
40
+ }
28
41
  /**
29
42
  * Result of resolving a single agent's authorization scope against an
30
43
  * `adagents.json` file. `properties` are the locally-resolved entries
@@ -52,8 +65,22 @@ export interface ResolvedAgentScope {
52
65
  * iterate this array, not `cross_publisher` — see adcp#4504.
53
66
  */
54
67
  cross_publisher_expanded: SinglePublisherPropertySelector[];
55
- /** The matched agent entry, or `undefined` if no entry matched the agent URL. */
68
+ /**
69
+ * The matched agent entry, or `undefined` if no entry matched the agent URL.
70
+ * When several entries match (AdCP 3.3+), the first in document order; see
71
+ * {@link ResolvedAgentScope.matched_entries}.
72
+ */
56
73
  matched_entry?: AuthorizedAgent;
74
+ /**
75
+ * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
+ * later more than one entry can match (an exact entry and an origin-only
77
+ * entry, say); the scope above is the union of theirs. Per-entry fields the
78
+ * resolver does not combine, such as `signing_keys`, are read from here: the
79
+ * AAO registry reports keys as pinned when any matching entry pins one
80
+ * (adcontextprotocol/adcp#9011). Set at AdCP 3.3 or later whenever an
81
+ * entry matched; omitted below 3.3, where at most one entry can resolve.
82
+ */
83
+ matched_entries?: AuthorizedAgent[];
57
84
  /** Why the resolution returned an empty result, when it did. */
58
85
  unresolvable?: ResolveUnresolvableReason;
59
86
  }
@@ -88,18 +115,62 @@ export type ResolveUnresolvableReason =
88
115
  * resolver — e.g., TMP `seller_agent_url` validation.
89
116
  */
90
117
  export declare function canonicalizeAgentUrl(raw: string): string | null;
118
+ /**
119
+ * Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
120
+ * the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
121
+ */
122
+ export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
123
+ /**
124
+ * Whether `agentUrl` matches an `authorized_agents[].url` entry under
125
+ * [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
126
+ *
127
+ * Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
128
+ * and host case, default ports, unreserved percent-encoding and fragments
129
+ * never matter, and the scheme, host and port always do. A URL with userinfo
130
+ * never canonicalizes, so it matches nothing. Then:
131
+ *
132
+ * - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
133
+ * whose canonical form has the root path and no query
134
+ * (`https://agent.example.com` or `https://agent.example.com/`),
135
+ * matches any agent URL with the same canonical origin, including
136
+ * `https://agent.example.com/mcp`. An entry with a path, or with a query
137
+ * (even an empty `?`), matches only the same canonical URL, so path case
138
+ * and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
139
+ * also drop one trailing root-label dot from a DNS host
140
+ * (`https://agent.example.` matches `https://agent.example/mcp`), and a
141
+ * host ending in more than one dot matches nothing.
142
+ * - **AdCP 3.2 and earlier**: every entry matches only the same canonical
143
+ * URL, so an origin-only entry matches only an agent served at the root.
144
+ *
145
+ * Returns `false` when either URL fails to canonicalize.
146
+ */
147
+ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
91
148
  /**
92
149
  * Resolve `agentUrl`'s authorization scope against an `adagents.json`
93
- * file. The lookup uses canonicalized URL comparison — two URLs
94
- * differing only in host case, default port, percent-encoding of
95
- * unreserved chars, or fragment are the same agent. Scheme and trailing
96
- * slash differences remain distinct.
150
+ * file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
151
+ * two URLs differing only in host case, default port, percent-encoding
152
+ * of unreserved chars, or fragment are the same agent, and scheme
153
+ * differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
154
+ * default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
155
+ * matches an agent at any path on that origin; below 3.3 it matches only
156
+ * an agent served at the root. An entry with a path always matches only
157
+ * its canonical URL, trailing slash included.
158
+ *
159
+ * At 3.3 or later every matching entry authorizes the agent, and the scope
160
+ * is the union of theirs: `properties`, `cross_publisher` and
161
+ * `cross_publisher_expanded` combine (duplicates removed), so a narrower
162
+ * entry never removes scope another matching entry grants
163
+ * (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
164
+ * is empty, and then carries the first matching entry's reason.
165
+ *
166
+ * Below 3.3 the behaviour is unchanged: only exact canonical matches count,
167
+ * and more than one fails closed as `ambiguous_agent_url`.
97
168
  *
98
169
  * Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
99
170
  * (never throws) when the agent isn't listed, when its entry is
100
171
  * malformed, or when the agent uses a signals authorization type.
101
172
  */
102
- export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
173
+ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
103
174
  /**
104
175
  * Convenience: list every locally-resolvable (`agent_url` →
105
176
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -110,8 +181,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
110
181
  *
111
182
  * The returned map is keyed by public canonical URL; if a file contains
112
183
  * canonical-equivalent entries, the later entry wins in this non-authoritative
113
- * inventory view. Use `resolveAgentProperties` for an authorization decision
114
- * for a specific agent URL because it fails closed on ambiguous matches.
184
+ * inventory view, and an origin-only entry is not applied to path-mounted
185
+ * agents. Use `resolveAgentProperties` for an authorization decision for a
186
+ * specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
187
+ * closed on ambiguous matches below 3.3.
115
188
  */
116
189
  export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
117
190
  byAgent: Map<string, Property[]>;
@@ -25,6 +25,19 @@
25
25
  * top-level property to every listed agent is gone.
26
26
  */
27
27
  import type { AdAgentsJson, AuthorizedAgent, Property, PublisherPropertySelector, SinglePublisherPropertySelector } from './types';
28
+ /** Options shared by the `authorized_agents[].url` matching helpers. */
29
+ export interface AgentUrlMatchOptions {
30
+ /**
31
+ * AdCP release the caller negotiated or targets. Defaults to the SDK's
32
+ * pinned `ADCP_VERSION`.
33
+ *
34
+ * At 3.3 or later an origin-only entry (`https://agent.example.com`)
35
+ * authorizes the agent at that origin whatever its path. Below 3.3, or
36
+ * when the value is not a parseable AdCP version, every entry matches by
37
+ * exact canonical URL.
38
+ */
39
+ adcpVersion?: string;
40
+ }
28
41
  /**
29
42
  * Result of resolving a single agent's authorization scope against an
30
43
  * `adagents.json` file. `properties` are the locally-resolved entries
@@ -52,8 +65,22 @@ export interface ResolvedAgentScope {
52
65
  * iterate this array, not `cross_publisher` — see adcp#4504.
53
66
  */
54
67
  cross_publisher_expanded: SinglePublisherPropertySelector[];
55
- /** The matched agent entry, or `undefined` if no entry matched the agent URL. */
68
+ /**
69
+ * The matched agent entry, or `undefined` if no entry matched the agent URL.
70
+ * When several entries match (AdCP 3.3+), the first in document order; see
71
+ * {@link ResolvedAgentScope.matched_entries}.
72
+ */
56
73
  matched_entry?: AuthorizedAgent;
74
+ /**
75
+ * Every entry that matched the agent URL, in document order. At AdCP 3.3 or
76
+ * later more than one entry can match (an exact entry and an origin-only
77
+ * entry, say); the scope above is the union of theirs. Per-entry fields the
78
+ * resolver does not combine, such as `signing_keys`, are read from here: the
79
+ * AAO registry reports keys as pinned when any matching entry pins one
80
+ * (adcontextprotocol/adcp#9011). Set at AdCP 3.3 or later whenever an
81
+ * entry matched; omitted below 3.3, where at most one entry can resolve.
82
+ */
83
+ matched_entries?: AuthorizedAgent[];
57
84
  /** Why the resolution returned an empty result, when it did. */
58
85
  unresolvable?: ResolveUnresolvableReason;
59
86
  }
@@ -88,18 +115,62 @@ export type ResolveUnresolvableReason =
88
115
  * resolver — e.g., TMP `seller_agent_url` validation.
89
116
  */
90
117
  export declare function canonicalizeAgentUrl(raw: string): string | null;
118
+ /**
119
+ * Whether `adcpVersion` (default: the SDK's pinned `ADCP_VERSION`) applies
120
+ * the 3.3 origin-only rule to `authorized_agents[].url` (adcp#8862).
121
+ */
122
+ export declare function usesOriginOnlyAgentMatching(adcpVersion?: string): boolean;
123
+ /**
124
+ * Whether `agentUrl` matches an `authorized_agents[].url` entry under
125
+ * [Agent URL matching](https://adcontextprotocol.org/docs/governance/property/adagents#agent-url-matching).
126
+ *
127
+ * Both sides are canonicalized with {@link canonicalizeAgentUrl}, so scheme
128
+ * and host case, default ports, unreserved percent-encoding and fragments
129
+ * never matter, and the scheme, host and port always do. A URL with userinfo
130
+ * never canonicalizes, so it matches nothing. Then:
131
+ *
132
+ * - **AdCP 3.3 or later** (DR-0023, adcp#8862): an origin-only entry, one
133
+ * whose canonical form has the root path and no query
134
+ * (`https://agent.example.com` or `https://agent.example.com/`),
135
+ * matches any agent URL with the same canonical origin, including
136
+ * `https://agent.example.com/mcp`. An entry with a path, or with a query
137
+ * (even an empty `?`), matches only the same canonical URL, so path case
138
+ * and a trailing slash (`/mcp` vs `/mcp/`) stay significant. Both sides
139
+ * also drop one trailing root-label dot from a DNS host
140
+ * (`https://agent.example.` matches `https://agent.example/mcp`), and a
141
+ * host ending in more than one dot matches nothing.
142
+ * - **AdCP 3.2 and earlier**: every entry matches only the same canonical
143
+ * URL, so an origin-only entry matches only an agent served at the root.
144
+ *
145
+ * Returns `false` when either URL fails to canonicalize.
146
+ */
147
+ export declare function agentUrlMatchesAuthorizedEntry(entryUrl: string, agentUrl: string, options?: AgentUrlMatchOptions): boolean;
91
148
  /**
92
149
  * Resolve `agentUrl`'s authorization scope against an `adagents.json`
93
- * file. The lookup uses canonicalized URL comparison — two URLs
94
- * differing only in host case, default port, percent-encoding of
95
- * unreserved chars, or fragment are the same agent. Scheme and trailing
96
- * slash differences remain distinct.
150
+ * file. Entries are matched with {@link agentUrlMatchesAuthorizedEntry}:
151
+ * two URLs differing only in host case, default port, percent-encoding
152
+ * of unreserved chars, or fragment are the same agent, and scheme
153
+ * differences remain distinct. At AdCP 3.3 or later (`options.adcpVersion`,
154
+ * default the SDK's pinned `ADCP_VERSION`) an origin-only entry also
155
+ * matches an agent at any path on that origin; below 3.3 it matches only
156
+ * an agent served at the root. An entry with a path always matches only
157
+ * its canonical URL, trailing slash included.
158
+ *
159
+ * At 3.3 or later every matching entry authorizes the agent, and the scope
160
+ * is the union of theirs: `properties`, `cross_publisher` and
161
+ * `cross_publisher_expanded` combine (duplicates removed), so a narrower
162
+ * entry never removes scope another matching entry grants
163
+ * (adcontextprotocol/adcp#9011). `unresolvable` is set only when the union
164
+ * is empty, and then carries the first matching entry's reason.
165
+ *
166
+ * Below 3.3 the behaviour is unchanged: only exact canonical matches count,
167
+ * and more than one fails closed as `ambiguous_agent_url`.
97
168
  *
98
169
  * Returns `{ properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: '...' }`
99
170
  * (never throws) when the agent isn't listed, when its entry is
100
171
  * malformed, or when the agent uses a signals authorization type.
101
172
  */
102
- export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string): ResolvedAgentScope;
173
+ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl: string, options?: AgentUrlMatchOptions): ResolvedAgentScope;
103
174
  /**
104
175
  * Convenience: list every locally-resolvable (`agent_url` →
105
176
  * `Property[]`) pair from an `adagents.json` file. Agents listed with
@@ -110,8 +181,10 @@ export declare function resolveAgentProperties(adAgents: AdAgentsJson, agentUrl:
110
181
  *
111
182
  * The returned map is keyed by public canonical URL; if a file contains
112
183
  * canonical-equivalent entries, the later entry wins in this non-authoritative
113
- * inventory view. Use `resolveAgentProperties` for an authorization decision
114
- * for a specific agent URL because it fails closed on ambiguous matches.
184
+ * inventory view, and an origin-only entry is not applied to path-mounted
185
+ * agents. Use `resolveAgentProperties` for an authorization decision for a
186
+ * specific agent URL: it unions every matching entry at AdCP 3.3+ and fails
187
+ * closed on ambiguous matches below 3.3.
115
188
  */
116
189
  export declare function listAgentPropertyMap(adAgents: AdAgentsJson): {
117
190
  byAgent: Map<string, Property[]>;