@adcp/sdk 17.0.0-beta.25 → 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 (49) hide show
  1. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  2. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  3. package/dist/lib/discovery/property-crawler.js +15 -2
  4. package/dist/lib/discovery/property-crawler.mjs +15 -2
  5. package/dist/lib/discovery/resolve-agent-properties.d.mts +81 -8
  6. package/dist/lib/discovery/resolve-agent-properties.d.ts +81 -8
  7. package/dist/lib/discovery/resolve-agent-properties.js +94 -14
  8. package/dist/lib/discovery/resolve-agent-properties.mjs +91 -13
  9. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  10. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  11. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  12. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  13. package/dist/lib/entrypoints/discovery.js +4 -0
  14. package/dist/lib/entrypoints/discovery.mjs +5 -1
  15. package/dist/lib/index.d.mts +1 -1
  16. package/dist/lib/index.d.ts +1 -1
  17. package/dist/lib/index.js +4 -0
  18. package/dist/lib/index.mjs +5 -1
  19. package/dist/lib/supply-path/validation.d.mts +8 -0
  20. package/dist/lib/supply-path/validation.d.ts +8 -0
  21. package/dist/lib/testing/compliance/comply.js +1 -1
  22. package/dist/lib/testing/compliance/comply.mjs +3 -2
  23. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  24. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  25. package/dist/lib/testing/storyboard/index.js +6 -0
  26. package/dist/lib/testing/storyboard/index.mjs +6 -0
  27. package/dist/lib/testing/storyboard/loader.js +52 -28
  28. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  29. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  30. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  31. package/dist/lib/testing/storyboard/runner.js +75 -7
  32. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  33. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  34. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  35. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  36. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  37. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  38. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  39. package/dist/lib/version.d.mts +3 -3
  40. package/dist/lib/version.d.ts +3 -3
  41. package/dist/lib/version.js +3 -3
  42. package/dist/lib/version.mjs +3 -3
  43. package/docs/TYPE-SUMMARY.md +1 -1
  44. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  45. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  46. package/docs/llms.txt +1 -1
  47. package/docs/migration-14.x-rc-worksheet.md +4 -4
  48. package/docs/migration-16-to-17.md +25 -0
  49. package/package.json +1 -1
@@ -1,4 +1,7 @@
1
1
  import { resolveInlinePublisherProperties } from "./inline-publisher-properties.mjs";
2
+ import { ADCP_VERSION } from "../version.mjs";
3
+ import { isAdcpVersionAtLeast } from "../utils/adcp-version-config.mjs";
4
+ const ORIGIN_ONLY_AGENT_MATCHING_SINCE = "3.3.0-beta.0";
2
5
  function canonicalizeAgentUrl(raw) {
3
6
  const parsed = parseAgentUrl(raw);
4
7
  if (!parsed) return null;
@@ -7,6 +10,38 @@ function canonicalizeAgentUrl(raw) {
7
10
  const query = parsed.search ? decodeUnreservedPercentEncoding(parsed.search) : fragmentlessHref.endsWith("?") ? "?" : "";
8
11
  return `${parsed.protocol}//${parsed.host}${path}${query}`;
9
12
  }
13
+ function canonicalAgentUrlParts(raw) {
14
+ const url = canonicalizeAgentUrl(raw);
15
+ if (url === null) return null;
16
+ const parsed = new URL(url);
17
+ const origin = `${parsed.protocol}//${parsed.host}`;
18
+ return { url, originOnly: url === `${origin}/`, rootDotless: stripRootDot(parsed, url, origin) };
19
+ }
20
+ function stripRootDot(parsed, url, origin) {
21
+ const host = parsed.hostname;
22
+ if (host.startsWith("[") || !host.endsWith(".")) return { url, origin };
23
+ if (host.endsWith("..") || host === ".") return null;
24
+ const dotless = `${parsed.protocol}//${host.slice(0, -1)}${parsed.port ? `:${parsed.port}` : ""}`;
25
+ return { url: dotless + url.slice(origin.length), origin: dotless };
26
+ }
27
+ function usesOriginOnlyAgentMatching(adcpVersion = ADCP_VERSION) {
28
+ return isAdcpVersionAtLeast(adcpVersion, ORIGIN_ONLY_AGENT_MATCHING_SINCE);
29
+ }
30
+ function agentUrlMatchesAuthorizedEntry(entryUrl, agentUrl, options = {}) {
31
+ const entry = canonicalAgentUrlParts(entryUrl);
32
+ const agent = canonicalAgentUrlParts(agentUrl);
33
+ if (!entry || !agent) return false;
34
+ return matchCanonicalAgentUrl(entry, agent, usesOriginOnlyAgentMatching(options.adcpVersion)) !== "none";
35
+ }
36
+ function matchCanonicalAgentUrl(entry, agent, originOnlyMatching) {
37
+ if (!originOnlyMatching) return entry.url === agent.url ? "exact" : "none";
38
+ const e = entry.rootDotless;
39
+ const a = agent.rootDotless;
40
+ if (!e || !a) return "none";
41
+ if (e.url === a.url) return "exact";
42
+ if (entry.originOnly && e.origin === a.origin) return "origin";
43
+ return "none";
44
+ }
10
45
  function parseAgentUrl(raw) {
11
46
  if (typeof raw !== "string" || raw.length === 0) return null;
12
47
  let parsed;
@@ -19,25 +54,66 @@ function parseAgentUrl(raw) {
19
54
  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
20
55
  return parsed;
21
56
  }
22
- function resolveAgentProperties(adAgents, agentUrl) {
23
- const wanted = canonicalizeAgentUrl(agentUrl);
57
+ function resolveAgentProperties(adAgents, agentUrl, options = {}) {
58
+ const wanted = canonicalAgentUrlParts(agentUrl);
24
59
  if (!wanted) {
25
60
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
26
61
  }
62
+ const originOnlyMatching = usesOriginOnlyAgentMatching(options.adcpVersion);
27
63
  const entries = Array.isArray(adAgents.authorized_agents) ? adAgents.authorized_agents : [];
28
- const matches = entries.filter((e) => {
29
- if (!e || typeof e.url !== "string") return false;
30
- const canon = canonicalizeAgentUrl(e.url);
31
- return canon !== null && canon === wanted;
32
- });
33
- if (matches.length > 1) {
34
- return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
64
+ const matches = [];
65
+ for (const e of entries) {
66
+ if (!e || typeof e.url !== "string") continue;
67
+ const canon = canonicalAgentUrlParts(e.url);
68
+ if (!canon) continue;
69
+ if (matchCanonicalAgentUrl(canon, wanted, originOnlyMatching) !== "none") matches.push(e);
35
70
  }
36
- const entry = matches[0];
37
- if (!entry) {
71
+ const first = matches[0];
72
+ if (!first) {
38
73
  return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "agent_not_listed" };
39
74
  }
40
- return resolveMatchedAgentProperties(adAgents, entry);
75
+ if (!originOnlyMatching) {
76
+ if (matches.length > 1) {
77
+ return { properties: [], cross_publisher: [], cross_publisher_expanded: [], unresolvable: "ambiguous_agent_url" };
78
+ }
79
+ return resolveMatchedAgentProperties(adAgents, first);
80
+ }
81
+ if (matches.length === 1) {
82
+ return { ...resolveMatchedAgentProperties(adAgents, first), matched_entries: [first] };
83
+ }
84
+ return unionAgentScopes(
85
+ matches.map((entry) => resolveMatchedAgentProperties(adAgents, entry)),
86
+ matches
87
+ );
88
+ }
89
+ function unionAgentScopes(scopes, entries) {
90
+ const properties = uniqueByValue(scopes.flatMap((s) => s.properties));
91
+ const cross_publisher = uniqueByValue(scopes.flatMap((s) => s.cross_publisher));
92
+ const cross_publisher_expanded = uniqueByValue(scopes.flatMap((s) => s.cross_publisher_expanded));
93
+ const empty = properties.length === 0 && cross_publisher.length === 0;
94
+ const reason = scopes.find((s) => s.unresolvable !== void 0)?.unresolvable;
95
+ return {
96
+ properties,
97
+ cross_publisher,
98
+ cross_publisher_expanded,
99
+ matched_entry: entries[0],
100
+ matched_entries: entries,
101
+ ...empty && reason !== void 0 ? { unresolvable: reason } : {}
102
+ };
103
+ }
104
+ function uniqueByValue(items) {
105
+ const seenRefs = /* @__PURE__ */ new Set();
106
+ const seenValues = /* @__PURE__ */ new Set();
107
+ const out = [];
108
+ for (const item of items) {
109
+ if (seenRefs.has(item)) continue;
110
+ seenRefs.add(item);
111
+ const value = JSON.stringify(item);
112
+ if (seenValues.has(value)) continue;
113
+ seenValues.add(value);
114
+ out.push(item);
115
+ }
116
+ return out;
41
117
  }
42
118
  function resolveMatchedAgentProperties(adAgents, entry) {
43
119
  const allProperties = filterRevokedProperties(adAgents.properties, adAgents.revoked_publisher_domains);
@@ -248,8 +324,10 @@ function allowsLegacyBareInline(adAgents) {
248
324
  return typeof adAgents.$schema !== "string" || adAgents.$schema.length === 0;
249
325
  }
250
326
  export {
327
+ agentUrlMatchesAuthorizedEntry,
251
328
  canonicalizeAgentUrl,
252
329
  getAllProperties,
253
330
  listAgentPropertyMap,
254
- resolveAgentProperties
331
+ resolveAgentProperties,
332
+ usesOriginOnlyAgentMatching
255
333
  };
@@ -103,6 +103,13 @@ export interface ValidateAdAgentsOptions {
103
103
  /**
104
104
  * Validate `adagents.json` for a publisher domain. Implements the
105
105
  * ads.txt `MANAGERDOMAIN` one-hop fallback specified in adcp#4175.
106
+ *
107
+ * This locates and loads the file; it does not decide whether a given agent
108
+ * is authorized. Check an agent against `result.adagents` with
109
+ * `resolveAgentProperties` or `agentUrlMatchesAuthorizedEntry`, passing the
110
+ * negotiated or targeted `adcpVersion`: at AdCP 3.3 or later an origin-only
111
+ * `authorized_agents[].url` authorizes the agent at any path on that origin
112
+ * (adcp#8862).
106
113
  */
107
114
  export declare function validateAdAgents(publisherDomain: string, options?: ValidateAdAgentsOptions): Promise<AdAgentsValidationResult>;
108
115
  /**
@@ -103,6 +103,13 @@ export interface ValidateAdAgentsOptions {
103
103
  /**
104
104
  * Validate `adagents.json` for a publisher domain. Implements the
105
105
  * ads.txt `MANAGERDOMAIN` one-hop fallback specified in adcp#4175.
106
+ *
107
+ * This locates and loads the file; it does not decide whether a given agent
108
+ * is authorized. Check an agent against `result.adagents` with
109
+ * `resolveAgentProperties` or `agentUrlMatchesAuthorizedEntry`, passing the
110
+ * negotiated or targeted `adcpVersion`: at AdCP 3.3 or later an origin-only
111
+ * `authorized_agents[].url` authorizes the agent at any path on that origin
112
+ * (adcp#8862).
106
113
  */
107
114
  export declare function validateAdAgents(publisherDomain: string, options?: ValidateAdAgentsOptions): Promise<AdAgentsValidationResult>;
108
115
  /**
@@ -2,7 +2,7 @@ export { PropertyIndex, getPropertyIndex, resetPropertyIndex, type PropertyMatch
2
2
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from '../discovery/network-consistency-checker.mjs';
3
3
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from '../discovery/types.mjs';
4
4
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from '../discovery/publisher-property-selector.mjs';
5
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties.mjs';
5
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties.mjs';
6
6
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from '../discovery/inline-publisher-properties.mjs';
7
7
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from '../discovery/agent-directory.mjs';
8
8
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from '../discovery/validate-adagents.mjs';
@@ -2,7 +2,7 @@ export { PropertyIndex, getPropertyIndex, resetPropertyIndex, type PropertyMatch
2
2
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from '../discovery/network-consistency-checker';
3
3
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from '../discovery/types';
4
4
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from '../discovery/publisher-property-selector';
5
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties';
5
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from '../discovery/resolve-agent-properties';
6
6
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from '../discovery/inline-publisher-properties';
7
7
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from '../discovery/agent-directory';
8
8
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from '../discovery/validate-adagents';
@@ -21,6 +21,7 @@ __export(discovery_exports, {
21
21
  NetworkConsistencyChecker: () => import_network_consistency_checker.NetworkConsistencyChecker,
22
22
  PropertyIndex: () => import_property_index.PropertyIndex,
23
23
  PublisherPropertySelectorParseError: () => import_publisher_property_selector.PublisherPropertySelectorParseError,
24
+ agentUrlMatchesAuthorizedEntry: () => import_resolve_agent_properties.agentUrlMatchesAuthorizedEntry,
24
25
  canonicalizeAgentUrl: () => import_resolve_agent_properties.canonicalizeAgentUrl,
25
26
  detectInlineFederatedDivergence: () => import_inline_publisher_properties.detectInlineFederatedDivergence,
26
27
  expandPublisherPropertySelector: () => import_publisher_property_selector.expandPublisherPropertySelector,
@@ -37,6 +38,7 @@ __export(discovery_exports, {
37
38
  resolveAgentProperties: () => import_resolve_agent_properties.resolveAgentProperties,
38
39
  resolveInlinePublisherProperties: () => import_inline_publisher_properties.resolveInlinePublisherProperties,
39
40
  resolveSingularInline: () => import_inline_publisher_properties.resolveSingularInline,
41
+ usesOriginOnlyAgentMatching: () => import_resolve_agent_properties.usesOriginOnlyAgentMatching,
40
42
  validateAdAgents: () => import_validate_adagents.validateAdAgents
41
43
  });
42
44
  module.exports = __toCommonJS(discovery_exports);
@@ -52,6 +54,7 @@ var import_validate_adagents = require('../discovery/validate-adagents.js');
52
54
  NetworkConsistencyChecker,
53
55
  PropertyIndex,
54
56
  PublisherPropertySelectorParseError,
57
+ agentUrlMatchesAuthorizedEntry,
55
58
  canonicalizeAgentUrl,
56
59
  detectInlineFederatedDivergence,
57
60
  expandPublisherPropertySelector,
@@ -68,5 +71,6 @@ var import_validate_adagents = require('../discovery/validate-adagents.js');
68
71
  resolveAgentProperties,
69
72
  resolveInlinePublisherProperties,
70
73
  resolveSingularInline,
74
+ usesOriginOnlyAgentMatching,
71
75
  validateAdAgents
72
76
  });
@@ -18,7 +18,9 @@ import {
18
18
  resolveAgentProperties,
19
19
  listAgentPropertyMap,
20
20
  getAllProperties,
21
- canonicalizeAgentUrl
21
+ canonicalizeAgentUrl,
22
+ agentUrlMatchesAuthorizedEntry,
23
+ usesOriginOnlyAgentMatching
22
24
  } from "../discovery/resolve-agent-properties.mjs";
23
25
  import {
24
26
  resolveInlinePublisherProperties,
@@ -36,6 +38,7 @@ export {
36
38
  NetworkConsistencyChecker,
37
39
  PropertyIndex,
38
40
  PublisherPropertySelectorParseError,
41
+ agentUrlMatchesAuthorizedEntry,
39
42
  canonicalizeAgentUrl,
40
43
  detectInlineFederatedDivergence,
41
44
  expandPublisherPropertySelector,
@@ -52,5 +55,6 @@ export {
52
55
  resolveAgentProperties,
53
56
  resolveInlinePublisherProperties,
54
57
  resolveSingularInline,
58
+ usesOriginOnlyAgentMatching,
55
59
  validateAdAgents
56
60
  };
@@ -11,7 +11,7 @@ export { PropertyCrawler, type AgentInfo, type CrawlResult, type PropertyCrawler
11
11
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from './discovery/network-consistency-checker.mjs';
12
12
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from './discovery/types.mjs';
13
13
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from './discovery/publisher-property-selector.mjs';
14
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties.mjs';
14
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties.mjs';
15
15
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from './discovery/inline-publisher-properties.mjs';
16
16
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory.mjs';
17
17
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents.mjs';
@@ -11,7 +11,7 @@ export { PropertyCrawler, type AgentInfo, type CrawlResult, type PropertyCrawler
11
11
  export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from './discovery/network-consistency-checker';
12
12
  export type { Property, PropertyIdentifier, PropertyIdentifierType, PropertyType, AdAgentsJson, AuthorizedAgent, AuthorizationType, PublisherPropertySelector as AdAgentsPublisherPropertySelector, SinglePublisherPropertySelector, CompactPublisherPropertySelector, } from './discovery/types';
13
13
  export { parsePublisherPropertySelector, expandPublisherPropertySelector, expandPublisherPropertySelectors, isCompactPublisherPropertySelector, publisherDomainsCoveredBySelectors, PublisherPropertySelectorParseError, type PublisherPropertySelectorError, } from './discovery/publisher-property-selector';
14
- export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties';
14
+ export { resolveAgentProperties, listAgentPropertyMap, getAllProperties, canonicalizeAgentUrl, agentUrlMatchesAuthorizedEntry, usesOriginOnlyAgentMatching, type AgentUrlMatchOptions, type ResolvedAgentScope, type ResolveUnresolvableReason, } from './discovery/resolve-agent-properties';
15
15
  export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFederatedDivergence, type InlineResolutionResult, type InlineFederatedDivergence, } from './discovery/inline-publisher-properties';
16
16
  export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory';
17
17
  export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents';
package/dist/lib/index.js CHANGED
@@ -239,6 +239,7 @@ __export(index_exports, {
239
239
  addSpanAttributes: () => import_observability.addSpanAttributes,
240
240
  adjustedMediaBuyDeliveryNotification: () => import_media_buy_delivery_notification_builders.adjustedMediaBuyDeliveryNotification,
241
241
  agentSignalId: () => import_signal_id_builders.agentSignalId,
242
+ agentUrlMatchesAuthorizedEntry: () => import_resolve_agent_properties.agentUrlMatchesAuthorizedEntry,
242
243
  applyBrandAssetMappings: () => import_brand.applyBrandAssetMappings,
243
244
  applyTargetingInput: () => import_media_buy.applyTargetingInput,
244
245
  assertCreativeTransition: () => import_server.assertCreativeTransition,
@@ -715,6 +716,7 @@ __export(index_exports, {
715
716
  urlRender: () => import_render_builders.urlRender,
716
717
  useIdempotencyKey: () => import_idempotency.useIdempotencyKey,
717
718
  usesDeprecatedAssetsField: () => import_format_assets.usesDeprecatedAssetsField,
719
+ usesOriginOnlyAgentMatching: () => import_resolve_agent_properties.usesOriginOnlyAgentMatching,
718
720
  usesV3CreativeAssignments: () => import_creative_adapter.usesV3CreativeAssignments,
719
721
  usesV3RenderFields: () => import_preview_normalizer.usesV3RenderFields,
720
722
  usesV3Renders: () => import_format_renders.usesV3Renders,
@@ -1109,6 +1111,7 @@ function createAdCPClientFromEnv() {
1109
1111
  addSpanAttributes,
1110
1112
  adjustedMediaBuyDeliveryNotification,
1111
1113
  agentSignalId,
1114
+ agentUrlMatchesAuthorizedEntry,
1112
1115
  applyBrandAssetMappings,
1113
1116
  applyTargetingInput,
1114
1117
  assertCreativeTransition,
@@ -1585,6 +1588,7 @@ function createAdCPClientFromEnv() {
1585
1588
  urlRender,
1586
1589
  useIdempotencyKey,
1587
1590
  usesDeprecatedAssetsField,
1591
+ usesOriginOnlyAgentMatching,
1588
1592
  usesV3CreativeAssignments,
1589
1593
  usesV3RenderFields,
1590
1594
  usesV3Renders,
@@ -57,7 +57,9 @@ import {
57
57
  resolveAgentProperties,
58
58
  listAgentPropertyMap,
59
59
  getAllProperties,
60
- canonicalizeAgentUrl
60
+ canonicalizeAgentUrl,
61
+ agentUrlMatchesAuthorizedEntry,
62
+ usesOriginOnlyAgentMatching
61
63
  } from "./discovery/resolve-agent-properties.mjs";
62
64
  import {
63
65
  resolveInlinePublisherProperties,
@@ -1068,6 +1070,7 @@ export {
1068
1070
  addSpanAttributes,
1069
1071
  adjustedMediaBuyDeliveryNotification,
1070
1072
  agentSignalId,
1073
+ agentUrlMatchesAuthorizedEntry,
1071
1074
  applyBrandAssetMappings,
1072
1075
  applyTargetingInput,
1073
1076
  assertCreativeTransition,
@@ -1544,6 +1547,7 @@ export {
1544
1547
  urlRender,
1545
1548
  useIdempotencyKey,
1546
1549
  usesDeprecatedAssetsField,
1550
+ usesOriginOnlyAgentMatching,
1547
1551
  usesV3CreativeAssignments,
1548
1552
  usesV3RenderFields,
1549
1553
  usesV3Renders,
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -617,7 +617,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
617
617
  if (predicates.length === 0) return false;
618
618
  if (typeof storyboard.adcp_version !== "string") return false;
619
619
  if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
620
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
620
+ if (predicates.flatMap(import_runner.capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
621
621
  return false;
622
622
  }
623
623
  for (const key of Object.keys(result)) {
@@ -15,7 +15,8 @@ import {
15
15
  storyboardCapabilityGateUnmet,
16
16
  storyboardRequiresCapabilityEvidence,
17
17
  storyboardAllowsCapabilityDiagnostic,
18
- storyboardCapabilityPredicates
18
+ storyboardCapabilityPredicates,
19
+ capabilityPathPredicates
19
20
  } from "../storyboard/runner.mjs";
20
21
  import { applyNativeA2AComplianceTransportOptions } from "../storyboard/native-a2a-compliance.mjs";
21
22
  import { validateTestKit } from "../storyboard/test-kit.mjs";
@@ -610,7 +611,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
610
611
  if (predicates.length === 0) return false;
611
612
  if (typeof storyboard.adcp_version !== "string") return false;
612
613
  if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
613
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
614
+ if (predicates.flatMap(capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
614
615
  return false;
615
616
  }
616
617
  for (const key of Object.keys(result)) {
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context.mjs';
18
18
  export type { RunnerVariables } from './context.mjs';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions.mjs';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader.mjs';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution.mjs';
23
23
  export type { FixtureContextOutput } from './types.mjs';
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context';
18
18
  export type { RunnerVariables } from './context';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution';
23
23
  export type { FixtureContextOutput } from './types';
@@ -56,6 +56,7 @@ __export(storyboard_exports, {
56
56
  buildFixtureResolutionSpecs: () => import_fixture_resolution.buildFixtureResolutionSpecs,
57
57
  buildProtectedResourceMetadataUrl: () => import_oauth_metadata_graph.buildProtectedResourceMetadataUrl,
58
58
  buildRequest: () => import_request_builder.buildRequest,
59
+ capabilityPathPredicates: () => import_runner.capabilityPathPredicates,
59
60
  clearAssertionRegistry: () => import_assertions.clearAssertionRegistry,
60
61
  clearSandboxCache: () => import_sandbox_entities.clearSandboxCache,
61
62
  compareCollectionPairs: () => import_collection_selection.compareCollectionPairs,
@@ -66,6 +67,7 @@ __export(storyboard_exports, {
66
67
  detectContextRejectionHints: () => import_rejection_hints.detectContextRejectionHints,
67
68
  diffCollectionPairSets: () => import_collection_selection.diffCollectionPairSets,
68
69
  evaluateCapabilityPredicate: () => import_runner.evaluateCapabilityPredicate,
70
+ evaluateCapabilityPredicateAgainstCapabilities: () => import_runner.evaluateCapabilityPredicateAgainstCapabilities,
69
71
  evaluateCollectionSelection: () => import_collection_selection.evaluateCollectionSelection,
70
72
  executeStoryboardTask: () => import_task_map.executeStoryboardTask,
71
73
  expandCreativeAssetDirectives: () => import_creative_assets.expandCreativeAssetDirectives,
@@ -87,6 +89,7 @@ __export(storyboard_exports, {
87
89
  gradeOAuthMetadataGraphVector: () => import_oauth_metadata_graph.gradeOAuthMetadataGraphVector,
88
90
  hasRequestBuilder: () => import_request_builder.hasRequestBuilder,
89
91
  injectContext: () => import_context2.injectContext,
92
+ isAnyOfCapabilityPredicate: () => import_runner.isAnyOfCapabilityPredicate,
90
93
  isComplianceVersionSupported: () => import_compliance.isComplianceVersionSupported,
91
94
  isProtectedContextKey: () => import_protected_context.isProtectedContextKey,
92
95
  isSandboxDomain: () => import_sandbox_entities.isSandboxDomain,
@@ -205,6 +208,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
205
208
  buildFixtureResolutionSpecs,
206
209
  buildProtectedResourceMetadataUrl,
207
210
  buildRequest,
211
+ capabilityPathPredicates,
208
212
  clearAssertionRegistry,
209
213
  clearSandboxCache,
210
214
  compareCollectionPairs,
@@ -215,6 +219,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
215
219
  detectContextRejectionHints,
216
220
  diffCollectionPairSets,
217
221
  evaluateCapabilityPredicate,
222
+ evaluateCapabilityPredicateAgainstCapabilities,
218
223
  evaluateCollectionSelection,
219
224
  executeStoryboardTask,
220
225
  expandCreativeAssetDirectives,
@@ -236,6 +241,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
236
241
  gradeOAuthMetadataGraphVector,
237
242
  hasRequestBuilder,
238
243
  injectContext,
244
+ isAnyOfCapabilityPredicate,
239
245
  isComplianceVersionSupported,
240
246
  isProtectedContextKey,
241
247
  isSandboxDomain,
@@ -25,6 +25,9 @@ import {
25
25
  listStrictOnlyFailures,
26
26
  resolveCapabilityPath,
27
27
  evaluateCapabilityPredicate,
28
+ evaluateCapabilityPredicateAgainstCapabilities,
29
+ isAnyOfCapabilityPredicate,
30
+ capabilityPathPredicates,
28
31
  describeStoryboardCapabilityGates,
29
32
  buildDiscoveryFailedResult
30
33
  } from "./runner.mjs";
@@ -161,6 +164,7 @@ export {
161
164
  buildFixtureResolutionSpecs,
162
165
  buildProtectedResourceMetadataUrl,
163
166
  buildRequest,
167
+ capabilityPathPredicates,
164
168
  clearAssertionRegistry,
165
169
  clearSandboxCache,
166
170
  compareCollectionPairs,
@@ -171,6 +175,7 @@ export {
171
175
  detectContextRejectionHints,
172
176
  diffCollectionPairSets,
173
177
  evaluateCapabilityPredicate,
178
+ evaluateCapabilityPredicateAgainstCapabilities,
174
179
  evaluateCollectionSelection,
175
180
  executeStoryboardTask,
176
181
  expandCreativeAssetDirectives,
@@ -192,6 +197,7 @@ export {
192
197
  gradeOAuthMetadataGraphVector,
193
198
  hasRequestBuilder,
194
199
  injectContext,
200
+ isAnyOfCapabilityPredicate,
195
201
  isComplianceVersionSupported,
196
202
  isProtectedContextKey,
197
203
  isSandboxDomain,
@@ -187,6 +187,10 @@ function validatePhaseSkipIf(storyboardId, phase) {
187
187
  }
188
188
  }
189
189
  function validateRequiresAllCapabilities(storyboard) {
190
+ validateAnyOfGate(storyboard.requires_capability, `[${storyboard.id}] requires_capability`);
191
+ for (const phase of storyboard.phases ?? []) {
192
+ validateAnyOfGate(phase.requires_capability, `[${storyboard.id}] phase '${phase.id}': requires_capability`);
193
+ }
190
194
  const predicates = storyboard.requires_all_capabilities;
191
195
  if (predicates === void 0) return;
192
196
  if (!Array.isArray(predicates) || predicates.length < 2) {
@@ -195,37 +199,57 @@ function validateRequiresAllCapabilities(storyboard) {
195
199
  );
196
200
  }
197
201
  for (let index = 0; index < predicates.length; index++) {
198
- const raw = predicates[index];
199
- const prefix = `[${storyboard.id}] requires_all_capabilities[${index}]`;
200
- if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
201
- throw new Error(`${prefix}: must be a capability predicate object`);
202
- }
203
- const predicate = raw;
204
- if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
205
- throw new Error(`${prefix}.path: must be a non-empty string`);
206
- }
207
- if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
208
- throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
209
- }
210
- const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
211
- (key) => Object.prototype.hasOwnProperty.call(predicate, key)
212
- );
213
- if (matcherKeys.length !== 1) {
214
- throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
215
- }
216
- const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
217
- if (unknownKeys.length > 0) {
218
- throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
219
- }
220
- if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
221
- throw new Error(`${prefix}.present: must be a boolean`);
202
+ validateCapabilityPredicateShape(predicates[index], `[${storyboard.id}] requires_all_capabilities[${index}]`);
203
+ }
204
+ }
205
+ function validateAnyOfGate(raw, prefix) {
206
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
207
+ if (!Object.prototype.hasOwnProperty.call(raw, "any_of")) return;
208
+ validateCapabilityPredicateShape(raw, prefix);
209
+ }
210
+ function validateCapabilityPredicateShape(raw, prefix) {
211
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
212
+ throw new Error(`${prefix}: must be a capability predicate object`);
213
+ }
214
+ const predicate = raw;
215
+ if (Object.prototype.hasOwnProperty.call(predicate, "any_of")) {
216
+ const unknownKeys2 = Object.keys(predicate).filter((key) => key !== "any_of");
217
+ if (unknownKeys2.length > 0) {
218
+ throw new Error(`${prefix}: any_of cannot be combined with ${unknownKeys2.join(", ")}`);
222
219
  }
223
- if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
224
- throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
220
+ const entries = predicate.any_of;
221
+ if (!Array.isArray(entries) || entries.length < 2) {
222
+ throw new Error(`${prefix}.any_of: must list at least two predicates`);
225
223
  }
226
- if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
227
- throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
224
+ for (let index = 0; index < entries.length; index++) {
225
+ validateCapabilityPredicateShape(entries[index], `${prefix}.any_of[${index}]`);
228
226
  }
227
+ return;
228
+ }
229
+ if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
230
+ throw new Error(`${prefix}.path: must be a non-empty string`);
231
+ }
232
+ if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
233
+ throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
234
+ }
235
+ const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
236
+ (key) => Object.prototype.hasOwnProperty.call(predicate, key)
237
+ );
238
+ if (matcherKeys.length !== 1) {
239
+ throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
240
+ }
241
+ const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
242
+ if (unknownKeys.length > 0) {
243
+ throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
244
+ }
245
+ if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
246
+ throw new Error(`${prefix}.present: must be a boolean`);
247
+ }
248
+ if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
249
+ throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
250
+ }
251
+ if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
252
+ throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
229
253
  }
230
254
  }
231
255
  function isJsonCapabilityValue(value, seen = /* @__PURE__ */ new Set()) {