@adcp/client 4.8.0 → 4.10.0

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 (149) hide show
  1. package/bin/adcp.js +346 -0
  2. package/dist/lib/adapters/governance-adapter.d.ts +88 -0
  3. package/dist/lib/adapters/governance-adapter.d.ts.map +1 -0
  4. package/dist/lib/adapters/governance-adapter.js +96 -0
  5. package/dist/lib/adapters/governance-adapter.js.map +1 -0
  6. package/dist/lib/adapters/index.d.ts +1 -0
  7. package/dist/lib/adapters/index.d.ts.map +1 -1
  8. package/dist/lib/adapters/index.js +7 -1
  9. package/dist/lib/adapters/index.js.map +1 -1
  10. package/dist/lib/agents/index.generated.d.ts +33 -1
  11. package/dist/lib/agents/index.generated.d.ts.map +1 -1
  12. package/dist/lib/agents/index.generated.js +48 -0
  13. package/dist/lib/agents/index.generated.js.map +1 -1
  14. package/dist/lib/core/AgentClient.d.ts +92 -1
  15. package/dist/lib/core/AgentClient.d.ts.map +1 -1
  16. package/dist/lib/core/AgentClient.js +237 -0
  17. package/dist/lib/core/AgentClient.js.map +1 -1
  18. package/dist/lib/core/AsyncHandler.d.ts +19 -2
  19. package/dist/lib/core/AsyncHandler.d.ts.map +1 -1
  20. package/dist/lib/core/AsyncHandler.js.map +1 -1
  21. package/dist/lib/core/ConversationTypes.d.ts +8 -2
  22. package/dist/lib/core/ConversationTypes.d.ts.map +1 -1
  23. package/dist/lib/core/GovernanceMiddleware.d.ts +86 -0
  24. package/dist/lib/core/GovernanceMiddleware.d.ts.map +1 -0
  25. package/dist/lib/core/GovernanceMiddleware.js +289 -0
  26. package/dist/lib/core/GovernanceMiddleware.js.map +1 -0
  27. package/dist/lib/core/GovernanceTypes.d.ts +118 -0
  28. package/dist/lib/core/GovernanceTypes.d.ts.map +1 -0
  29. package/dist/lib/core/GovernanceTypes.js +69 -0
  30. package/dist/lib/core/GovernanceTypes.js.map +1 -0
  31. package/dist/lib/core/SingleAgentClient.d.ts +103 -1
  32. package/dist/lib/core/SingleAgentClient.d.ts.map +1 -1
  33. package/dist/lib/core/SingleAgentClient.js +151 -0
  34. package/dist/lib/core/SingleAgentClient.js.map +1 -1
  35. package/dist/lib/core/TaskExecutor.d.ts +10 -0
  36. package/dist/lib/core/TaskExecutor.d.ts.map +1 -1
  37. package/dist/lib/core/TaskExecutor.js +95 -10
  38. package/dist/lib/core/TaskExecutor.js.map +1 -1
  39. package/dist/lib/index.d.ts +6 -2
  40. package/dist/lib/index.d.ts.map +1 -1
  41. package/dist/lib/index.js +22 -4
  42. package/dist/lib/index.js.map +1 -1
  43. package/dist/lib/observability/index.d.ts +8 -0
  44. package/dist/lib/observability/index.d.ts.map +1 -0
  45. package/dist/lib/observability/index.js +17 -0
  46. package/dist/lib/observability/index.js.map +1 -0
  47. package/dist/lib/observability/tracing.d.ts +42 -0
  48. package/dist/lib/observability/tracing.d.ts.map +1 -0
  49. package/dist/lib/observability/tracing.js +126 -0
  50. package/dist/lib/observability/tracing.js.map +1 -0
  51. package/dist/lib/protocols/a2a.d.ts.map +1 -1
  52. package/dist/lib/protocols/a2a.js +16 -1
  53. package/dist/lib/protocols/a2a.js.map +1 -1
  54. package/dist/lib/protocols/index.d.ts.map +1 -1
  55. package/dist/lib/protocols/index.js +37 -29
  56. package/dist/lib/protocols/index.js.map +1 -1
  57. package/dist/lib/protocols/mcp.d.ts.map +1 -1
  58. package/dist/lib/protocols/mcp.js +21 -1
  59. package/dist/lib/protocols/mcp.js.map +1 -1
  60. package/dist/lib/registry/types.generated.d.ts +754 -5
  61. package/dist/lib/registry/types.generated.d.ts.map +1 -1
  62. package/dist/lib/registry/types.generated.js +1 -1
  63. package/dist/lib/testing/agent-tester.d.ts +1 -1
  64. package/dist/lib/testing/agent-tester.d.ts.map +1 -1
  65. package/dist/lib/testing/agent-tester.js +36 -11
  66. package/dist/lib/testing/agent-tester.js.map +1 -1
  67. package/dist/lib/testing/client.d.ts +6 -1
  68. package/dist/lib/testing/client.d.ts.map +1 -1
  69. package/dist/lib/testing/client.js +36 -19
  70. package/dist/lib/testing/client.js.map +1 -1
  71. package/dist/lib/testing/compliance/briefs.d.ts +12 -0
  72. package/dist/lib/testing/compliance/briefs.d.ts.map +1 -0
  73. package/dist/lib/testing/compliance/briefs.js +157 -0
  74. package/dist/lib/testing/compliance/briefs.js.map +1 -0
  75. package/dist/lib/testing/compliance/comply.d.ts +26 -0
  76. package/dist/lib/testing/compliance/comply.d.ts.map +1 -0
  77. package/dist/lib/testing/compliance/comply.js +540 -0
  78. package/dist/lib/testing/compliance/comply.js.map +1 -0
  79. package/dist/lib/testing/compliance/convince.d.ts +27 -0
  80. package/dist/lib/testing/compliance/convince.d.ts.map +1 -0
  81. package/dist/lib/testing/compliance/convince.js +418 -0
  82. package/dist/lib/testing/compliance/convince.js.map +1 -0
  83. package/dist/lib/testing/compliance/index.d.ts +13 -0
  84. package/dist/lib/testing/compliance/index.d.ts.map +1 -0
  85. package/dist/lib/testing/compliance/index.js +22 -0
  86. package/dist/lib/testing/compliance/index.js.map +1 -0
  87. package/dist/lib/testing/compliance/types.d.ts +123 -0
  88. package/dist/lib/testing/compliance/types.d.ts.map +1 -0
  89. package/dist/lib/testing/compliance/types.js +9 -0
  90. package/dist/lib/testing/compliance/types.js.map +1 -0
  91. package/dist/lib/testing/index.d.ts +1 -0
  92. package/dist/lib/testing/index.d.ts.map +1 -1
  93. package/dist/lib/testing/index.js +15 -1
  94. package/dist/lib/testing/index.js.map +1 -1
  95. package/dist/lib/testing/orchestrator.d.ts +0 -2
  96. package/dist/lib/testing/orchestrator.d.ts.map +1 -1
  97. package/dist/lib/testing/orchestrator.js +14 -3
  98. package/dist/lib/testing/orchestrator.js.map +1 -1
  99. package/dist/lib/testing/scenarios/capabilities.d.ts.map +1 -1
  100. package/dist/lib/testing/scenarios/capabilities.js +70 -9
  101. package/dist/lib/testing/scenarios/capabilities.js.map +1 -1
  102. package/dist/lib/testing/scenarios/creative.d.ts +14 -0
  103. package/dist/lib/testing/scenarios/creative.d.ts.map +1 -1
  104. package/dist/lib/testing/scenarios/creative.js +261 -55
  105. package/dist/lib/testing/scenarios/creative.js.map +1 -1
  106. package/dist/lib/testing/scenarios/discovery.d.ts.map +1 -1
  107. package/dist/lib/testing/scenarios/discovery.js +7 -5
  108. package/dist/lib/testing/scenarios/discovery.js.map +1 -1
  109. package/dist/lib/testing/scenarios/edge-cases.d.ts.map +1 -1
  110. package/dist/lib/testing/scenarios/edge-cases.js +90 -112
  111. package/dist/lib/testing/scenarios/edge-cases.js.map +1 -1
  112. package/dist/lib/testing/scenarios/governance.d.ts +48 -0
  113. package/dist/lib/testing/scenarios/governance.d.ts.map +1 -1
  114. package/dist/lib/testing/scenarios/governance.js +725 -39
  115. package/dist/lib/testing/scenarios/governance.js.map +1 -1
  116. package/dist/lib/testing/scenarios/index.d.ts +3 -3
  117. package/dist/lib/testing/scenarios/index.d.ts.map +1 -1
  118. package/dist/lib/testing/scenarios/index.js +8 -1
  119. package/dist/lib/testing/scenarios/index.js.map +1 -1
  120. package/dist/lib/testing/scenarios/media-buy.d.ts +14 -5
  121. package/dist/lib/testing/scenarios/media-buy.d.ts.map +1 -1
  122. package/dist/lib/testing/scenarios/media-buy.js +358 -63
  123. package/dist/lib/testing/scenarios/media-buy.js.map +1 -1
  124. package/dist/lib/testing/scenarios/schema-compliance.d.ts.map +1 -1
  125. package/dist/lib/testing/scenarios/schema-compliance.js +26 -22
  126. package/dist/lib/testing/scenarios/schema-compliance.js.map +1 -1
  127. package/dist/lib/testing/scenarios/signals.d.ts +4 -8
  128. package/dist/lib/testing/scenarios/signals.d.ts.map +1 -1
  129. package/dist/lib/testing/scenarios/signals.js +17 -59
  130. package/dist/lib/testing/scenarios/signals.js.map +1 -1
  131. package/dist/lib/testing/scenarios/sponsored-intelligence.d.ts.map +1 -1
  132. package/dist/lib/testing/scenarios/sponsored-intelligence.js +23 -19
  133. package/dist/lib/testing/scenarios/sponsored-intelligence.js.map +1 -1
  134. package/dist/lib/testing/types.d.ts +3 -2
  135. package/dist/lib/testing/types.d.ts.map +1 -1
  136. package/dist/lib/types/core.generated.d.ts +629 -5
  137. package/dist/lib/types/core.generated.d.ts.map +1 -1
  138. package/dist/lib/types/core.generated.js +1 -1
  139. package/dist/lib/types/schemas.generated.d.ts +13059 -11101
  140. package/dist/lib/types/schemas.generated.d.ts.map +1 -1
  141. package/dist/lib/types/schemas.generated.js +573 -107
  142. package/dist/lib/types/schemas.generated.js.map +1 -1
  143. package/dist/lib/types/tools.generated.d.ts +1827 -360
  144. package/dist/lib/types/tools.generated.d.ts.map +1 -1
  145. package/dist/lib/utils/capabilities.d.ts +17 -2
  146. package/dist/lib/utils/capabilities.d.ts.map +1 -1
  147. package/dist/lib/utils/capabilities.js +26 -2
  148. package/dist/lib/utils/capabilities.js.map +1 -1
  149. package/package.json +13 -3
@@ -64,18 +64,26 @@ export type GetProductsRequest = {
64
64
  * Buyer's campaign reference label. Groups related discovery and buy operations under a single campaign for CRM and ad server correlation (e.g., 'NovaDrink_Meals_Q2').
65
65
  */
66
66
  buyer_campaign_ref?: string;
67
+ /**
68
+ * Delivery types the buyer prefers, in priority order. Unlike filters.delivery_type which excludes non-matching products, this signals preference for curation — the publisher may still include other delivery types when they match the brief well.
69
+ */
70
+ preferred_delivery_types?: DeliveryType[];
67
71
  filters?: ProductFilters;
68
72
  property_list?: PropertyListReference;
69
73
  /**
70
74
  * Specific product fields to include in the response. When omitted, all fields are returned. Use for lightweight discovery calls where only a subset of product data is needed (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.
71
75
  */
72
- fields?: ('product_id' | 'name' | 'description' | 'publisher_properties' | 'channels' | 'format_ids' | 'placements' | 'delivery_type' | 'pricing_options' | 'forecast' | 'outcome_measurement' | 'delivery_measurement' | 'reporting_capabilities' | 'creative_policy' | 'catalog_types' | 'metric_optimization' | 'conversion_tracking' | 'data_provider_signals' | 'max_optimization_goals' | 'catalog_match' | 'brief_relevance' | 'expires_at' | 'product_card' | 'product_card_detailed')[];
76
+ fields?: ('product_id' | 'name' | 'description' | 'publisher_properties' | 'channels' | 'format_ids' | 'placements' | 'delivery_type' | 'exclusivity' | 'pricing_options' | 'forecast' | 'outcome_measurement' | 'delivery_measurement' | 'reporting_capabilities' | 'creative_policy' | 'catalog_types' | 'metric_optimization' | 'conversion_tracking' | 'data_provider_signals' | 'max_optimization_goals' | 'catalog_match' | 'show_ids' | 'episodes' | 'brief_relevance' | 'expires_at' | 'product_card' | 'product_card_detailed')[];
73
77
  /**
74
78
  * Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing.
75
79
  */
76
80
  time_budget?: Duration;
77
81
  pagination?: PaginationRequest;
78
82
  context?: ContextObject;
83
+ /**
84
+ * Registry policy IDs that the buyer requires to be enforced for products in this response. Sellers filter products to only those that comply with or already enforce the requested policies.
85
+ */
86
+ required_policies?: string[];
79
87
  ext?: ExtensionObject;
80
88
  } & ({
81
89
  buying_mode: 'brief';
@@ -135,6 +143,10 @@ export type AccountReference = {
135
143
  * Type of inventory delivery
136
144
  */
137
145
  export type DeliveryType = 'guaranteed' | 'non_guaranteed';
146
+ /**
147
+ * Filter by exclusivity level. Returns products matching the specified exclusivity (e.g., 'exclusive' returns only sole-sponsorship products).
148
+ */
149
+ export type Exclusivity = 'none' | 'category' | 'exclusive';
138
150
  /**
139
151
  * DEPRECATED: High-level categories for creative formats. These categories are lossy abstractions that don't scale well to emerging ad formats. Use the assets array in Format objects to understand creative requirements instead - it provides precise information about what asset types are needed (video, image, text, etc.).
140
152
  */
@@ -146,7 +158,7 @@ export type MetroAreaSystem = 'nielsen_dma' | 'uk_itl1' | 'uk_itl2' | 'eurostat_
146
158
  /**
147
159
  * Standardized advertising media channels describing how buyers allocate budget. Channels are planning abstractions, not technical substrates. See the Media Channel Taxonomy specification for detailed definitions.
148
160
  */
149
- export type MediaChannel = 'display' | 'olv' | 'social' | 'search' | 'ctv' | 'linear_tv' | 'radio' | 'streaming_audio' | 'podcast' | 'dooh' | 'ooh' | 'print' | 'cinema' | 'email' | 'gaming' | 'retail_media' | 'influencer' | 'affiliate' | 'product_placement';
161
+ export type MediaChannel = 'display' | 'olv' | 'social' | 'search' | 'ctv' | 'linear_tv' | 'radio' | 'streaming_audio' | 'podcast' | 'dooh' | 'ooh' | 'print' | 'cinema' | 'email' | 'gaming' | 'retail_media' | 'influencer' | 'affiliate' | 'product_placement' | 'sponsored_intelligence';
150
162
  /**
151
163
  * Geographic targeting level (country, region, metro, postal_area)
152
164
  */
@@ -342,6 +354,7 @@ export interface ExtensionObject {
342
354
  */
343
355
  export interface ProductFilters {
344
356
  delivery_type?: DeliveryType;
357
+ exclusivity?: Exclusivity;
345
358
  /**
346
359
  * Filter by pricing availability: true = products offering fixed pricing (at least one option with fixed_price), false = products offering auction pricing (at least one option without fixed_price). Products with both fixed and auction options match both true and false.
347
360
  */
@@ -647,6 +660,42 @@ export type DataProviderSignalSelector = {
647
660
  * Where the conversion event originated
648
661
  */
649
662
  export type ActionSource = 'website' | 'app' | 'offline' | 'phone_call' | 'chat' | 'email' | 'in_store' | 'system_generated' | 'other';
663
+ /**
664
+ * Lifecycle status of the episode
665
+ */
666
+ export type EpisodeStatus = 'scheduled' | 'tentative' | 'live' | 'postponed' | 'cancelled' | 'aired' | 'published';
667
+ /**
668
+ * Rating system used
669
+ */
670
+ export type ContentRatingSystem = 'tv_parental' | 'mpaa' | 'podcast' | 'esrb' | 'bbfc' | 'fsk' | 'acb' | 'custom';
671
+ /**
672
+ * Role of this person on the show or episode
673
+ */
674
+ export type TalentRole = 'host' | 'guest' | 'creator' | 'cast' | 'narrator' | 'producer' | 'correspondent';
675
+ /**
676
+ * What kind of derivative content this is
677
+ */
678
+ export type DerivativeType = 'clip' | 'highlight' | 'recap' | 'trailer' | 'bonus';
679
+ /**
680
+ * How frequently the show releases new episodes
681
+ */
682
+ export type ShowCadence = 'daily' | 'weekly' | 'seasonal' | 'event' | 'irregular';
683
+ /**
684
+ * Lifecycle status of the show
685
+ */
686
+ export type ShowStatus = 'active' | 'hiatus' | 'ended' | 'upcoming';
687
+ /**
688
+ * Production quality tier. Seller-declared. Maps to OpenRTB content.prodq (professional=1, prosumer=2, ugc=3).
689
+ */
690
+ export type ProductionQuality = 'professional' | 'prosumer' | 'ugc';
691
+ /**
692
+ * Type of distribution identifier
693
+ */
694
+ export type DistributionIdentifierType = 'apple_podcast_id' | 'spotify_show_id' | 'rss_url' | 'podcast_guid' | 'amazon_music_id' | 'iheart_id' | 'podcast_index_id' | 'youtube_channel_id' | 'youtube_playlist_id' | 'amazon_title_id' | 'roku_channel_id' | 'pluto_channel_id' | 'tubi_id' | 'peacock_id' | 'tiktok_id' | 'twitch_channel' | 'imdb_id' | 'gracenote_id' | 'eidr_id' | 'domain' | 'substack_id';
695
+ /**
696
+ * How the shows are related
697
+ */
698
+ export type ShowRelationship = 'spinoff' | 'companion' | 'sequel' | 'prequel' | 'crossover';
650
699
  /**
651
700
  * Days of the week for daypart targeting
652
701
  */
@@ -659,6 +708,10 @@ export interface GetProductsResponse {
659
708
  * Array of matching products
660
709
  */
661
710
  products: Product[];
711
+ /**
712
+ * Shows referenced by products in this response. Only includes shows referenced by the returned products. Under pagination, each page includes all show objects needed for that page's products.
713
+ */
714
+ shows?: Show[];
662
715
  /**
663
716
  * Optional array of proposed media plans with budget allocations across products. Publishers include proposals when they can provide strategic guidance based on the brief. Proposals are actionable - buyers can refine them via follow-up get_products calls within the same session, or execute them directly via create_media_buy.
664
717
  */
@@ -754,6 +807,7 @@ export interface Product {
754
807
  */
755
808
  placements?: Placement[];
756
809
  delivery_type: DeliveryType;
810
+ exclusivity?: Exclusivity;
757
811
  /**
758
812
  * Available pricing models for this product
759
813
  */
@@ -761,9 +815,9 @@ export interface Product {
761
815
  forecast?: DeliveryForecast;
762
816
  outcome_measurement?: OutcomeMeasurement;
763
817
  /**
764
- * Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. REQUIRED for all products.
818
+ * Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. When absent, buyers should apply their own measurement defaults.
765
819
  */
766
- delivery_measurement: {
820
+ delivery_measurement?: {
767
821
  /**
768
822
  * Measurement provider(s) used for this product (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions')
769
823
  */
@@ -886,6 +940,18 @@ export interface Product {
886
940
  */
887
941
  manifest: {};
888
942
  };
943
+ /**
944
+ * References to shows in the response's top-level shows array. When present, the product covers inventory associated with these shows. A product can span multiple shows (e.g., a podcast network bundle).
945
+ */
946
+ show_ids?: string[];
947
+ /**
948
+ * Specific episodes included in this product. Each episode references its parent show via show_id when the product spans multiple shows. When absent with show_ids present, the product covers the shows broadly (run-of-show).
949
+ */
950
+ episodes?: Episode[];
951
+ /**
952
+ * Registry policy IDs the seller enforces for this product. Enforcement level comes from the policy registry. Buyers can filter products by required policies.
953
+ */
954
+ enforced_policies?: string[];
889
955
  ext?: ExtensionObject;
890
956
  }
891
957
  /**
@@ -1497,6 +1563,193 @@ export interface CreativePolicy {
1497
1563
  */
1498
1564
  provenance_required?: boolean;
1499
1565
  }
1566
+ /**
1567
+ * A specific installment of a show. Episodes inherit show-level fields they don't override: content_rating defaults to the show's baseline, guest_talent is additive to the show's recurring talent, and topics add context beyond the show's genre.
1568
+ */
1569
+ export interface Episode {
1570
+ /**
1571
+ * Unique identifier for this episode within the show
1572
+ */
1573
+ episode_id: string;
1574
+ /**
1575
+ * Parent show reference. Required when the product spans multiple shows (has multiple entries in show_ids on the product).
1576
+ */
1577
+ show_id?: string;
1578
+ /**
1579
+ * Episode title
1580
+ */
1581
+ name?: string;
1582
+ /**
1583
+ * Season identifier (e.g., '1', '2024', 'spring_2026')
1584
+ */
1585
+ season?: string;
1586
+ /**
1587
+ * Episode number within the season (e.g., '3', '47')
1588
+ */
1589
+ episode_number?: string;
1590
+ /**
1591
+ * When the episode airs or publishes (ISO 8601)
1592
+ */
1593
+ scheduled_at?: string;
1594
+ status?: EpisodeStatus;
1595
+ /**
1596
+ * Expected duration of the episode in seconds
1597
+ */
1598
+ duration_seconds?: number;
1599
+ /**
1600
+ * Whether the end time is approximate (live events, sports)
1601
+ */
1602
+ flexible_end?: boolean;
1603
+ /**
1604
+ * When this episode data expires and should be re-queried. Agents should re-query before committing budget to products with tentative episodes.
1605
+ */
1606
+ valid_until?: string;
1607
+ content_rating?: ContentRating;
1608
+ /**
1609
+ * Content topics for this episode. Uses the same taxonomy as the show's genre_taxonomy when present. Enables episode-level brand safety evaluation beyond content_rating.
1610
+ */
1611
+ topics?: string[];
1612
+ /**
1613
+ * Episode-specific guests and talent. Additive to the show's recurring talent.
1614
+ */
1615
+ guest_talent?: Talent[];
1616
+ ad_inventory?: AdInventoryConfiguration;
1617
+ /**
1618
+ * When this episode is a clip, highlight, or recap derived from a full episode. The source episode_id must reference an episode within the same response.
1619
+ */
1620
+ derivative_of?: {
1621
+ /**
1622
+ * The source episode this content is derived from
1623
+ */
1624
+ episode_id: string;
1625
+ type: DerivativeType;
1626
+ };
1627
+ ext?: ExtensionObject;
1628
+ }
1629
+ /**
1630
+ * Episode-specific content rating. Overrides the show's baseline content_rating when present.
1631
+ */
1632
+ export interface ContentRating {
1633
+ system: ContentRatingSystem;
1634
+ /**
1635
+ * Rating value within the system (e.g., 'TV-PG', 'R', 'explicit')
1636
+ */
1637
+ rating: string;
1638
+ }
1639
+ /**
1640
+ * A person associated with a show or episode, with an optional link to their brand.json identity
1641
+ */
1642
+ export interface Talent {
1643
+ role: TalentRole;
1644
+ /**
1645
+ * Person's name as credited on the show
1646
+ */
1647
+ name: string;
1648
+ /**
1649
+ * URL to this person's brand.json entry. Enables buyer agents to evaluate the talent's brand identity and associations.
1650
+ */
1651
+ brand_url?: string;
1652
+ }
1653
+ /**
1654
+ * Break-based ad inventory for this episode. For non-break formats (host reads, integrations), use product placements.
1655
+ */
1656
+ export interface AdInventoryConfiguration {
1657
+ /**
1658
+ * Number of planned ad breaks in the episode
1659
+ */
1660
+ expected_breaks: number;
1661
+ /**
1662
+ * Total seconds of ad time across all breaks
1663
+ */
1664
+ total_ad_seconds?: number;
1665
+ /**
1666
+ * Maximum duration in seconds for a single ad within a break. Buyers need this to know whether their creative fits.
1667
+ */
1668
+ max_ad_duration_seconds?: number;
1669
+ /**
1670
+ * Whether ad breaks are dynamic and driven by live conditions (sports timeouts, election coverage). When false, all breaks are pre-defined.
1671
+ */
1672
+ unplanned_breaks?: boolean;
1673
+ /**
1674
+ * Ad format types supported in breaks (e.g., 'video', 'audio', 'display')
1675
+ */
1676
+ supported_formats?: string[];
1677
+ }
1678
+ /**
1679
+ * A persistent content program that produces episodes over time. Shows are reusable objects that products reference by show_id. The show_id is seller-scoped — use distribution identifiers for cross-seller matching.
1680
+ */
1681
+ export interface Show {
1682
+ /**
1683
+ * Seller-assigned identifier for this show. Unique within a single get_products response but not globally unique across sellers. Use distribution identifiers for cross-seller matching.
1684
+ */
1685
+ show_id: string;
1686
+ /**
1687
+ * Human-readable show name
1688
+ */
1689
+ name: string;
1690
+ /**
1691
+ * What the show is about
1692
+ */
1693
+ description?: string;
1694
+ /**
1695
+ * Genre tags. When genre_taxonomy is present, values are taxonomy IDs (e.g., IAB Content Taxonomy 3.0 codes). Otherwise free-form.
1696
+ */
1697
+ genre?: string[];
1698
+ /**
1699
+ * Taxonomy system for genre values (e.g., 'iab_content_3.0'). When present, genre values should be valid taxonomy IDs. Recommended for machine-readable brand safety evaluation.
1700
+ */
1701
+ genre_taxonomy?: string;
1702
+ /**
1703
+ * Primary language (BCP 47 tag, e.g., 'en', 'es-MX')
1704
+ */
1705
+ language?: string;
1706
+ content_rating?: ContentRating;
1707
+ cadence?: ShowCadence;
1708
+ /**
1709
+ * Current or most recent season identifier (e.g., '3', '2026', 'spring_2026'). A lightweight label — not a full season object.
1710
+ */
1711
+ season?: string;
1712
+ status?: ShowStatus;
1713
+ production_quality?: ProductionQuality;
1714
+ /**
1715
+ * Hosts, recurring cast, creators associated with the show. Each talent entry may include a brand_url linking to their brand.json identity.
1716
+ */
1717
+ talent?: Talent[];
1718
+ /**
1719
+ * Where this show is distributed. Each entry maps the show to a publisher platform with platform-specific identifiers. Shows SHOULD include at least one platform-independent identifier (imdb_id, gracenote_id, eidr_id) when available.
1720
+ */
1721
+ distribution?: ShowDistribution[];
1722
+ /**
1723
+ * Relationships to other shows (spin-offs, companion shows, etc.). Each entry references another show by show_id within the same response.
1724
+ */
1725
+ related_shows?: {
1726
+ /**
1727
+ * The related show's show_id within this seller's response
1728
+ */
1729
+ show_id: string;
1730
+ relationship: ShowRelationship;
1731
+ }[];
1732
+ ext?: ExtensionObject;
1733
+ }
1734
+ /**
1735
+ * A show's presence on a specific publisher platform, identified by platform-specific identifiers. Enables cross-seller matching when the same show is sold by different agents.
1736
+ */
1737
+ export interface ShowDistribution {
1738
+ /**
1739
+ * Domain of the publisher platform where the show is distributed (e.g., 'youtube.com', 'spotify.com')
1740
+ */
1741
+ publisher_domain: string;
1742
+ /**
1743
+ * Platform-specific identifiers for the show on this publisher
1744
+ */
1745
+ identifiers: {
1746
+ type: DistributionIdentifierType;
1747
+ /**
1748
+ * The identifier value
1749
+ */
1750
+ value: string;
1751
+ }[];
1752
+ }
1500
1753
  /**
1501
1754
  * A proposed media plan with budget allocations across products. Represents the publisher's strategic recommendation for how to structure a campaign based on the brief. Proposals are actionable - buyers can execute them directly via create_media_buy by providing the proposal_id.
1502
1755
  */
@@ -2359,6 +2612,10 @@ export interface CreateMediaBuyRequest {
2359
2612
  * Buyer's campaign reference label. Groups related discovery and buy operations under a single campaign for CRM and ad server correlation (e.g., 'NovaDrink_Meals_Q2').
2360
2613
  */
2361
2614
  buyer_campaign_ref?: string;
2615
+ /**
2616
+ * Campaign governance plan identifier. Required when the account has governance_agents. The seller includes this in the committed check_governance request so the governance agent can validate against the correct plan.
2617
+ */
2618
+ plan_id?: string;
2362
2619
  account: AccountReference;
2363
2620
  /**
2364
2621
  * ID of a proposal from get_products to execute. When provided with total_budget, the publisher converts the proposal's allocation percentages into packages automatically. Alternative to providing packages array.
@@ -3437,6 +3694,7 @@ export interface CreateMediaBuySuccess {
3437
3694
  * Array of created packages with complete state information
3438
3695
  */
3439
3696
  packages: Package[];
3697
+ planned_delivery?: PlannedDelivery;
3440
3698
  /**
3441
3699
  * When true, this response contains simulated data from sandbox mode.
3442
3700
  */
@@ -3513,6 +3771,29 @@ export interface Account {
3513
3771
  * How the seller scoped this account. operator: shared across all brands for this operator. brand: shared across all operators for this brand. operator_brand: dedicated to a specific operator+brand combination. agent: the agent's default account with no brand or operator association.
3514
3772
  */
3515
3773
  account_scope?: 'operator' | 'brand' | 'operator_brand' | 'agent';
3774
+ /**
3775
+ * Governance agent endpoints for this account. When present, the seller MUST call these agents for governance approval before confirming media buy requests. Each agent can be scoped to specific validation categories. All applicable agents must approve for the action to proceed (unanimous approval).
3776
+ */
3777
+ governance_agents?: {
3778
+ /**
3779
+ * Governance agent endpoint URL.
3780
+ */
3781
+ url: string;
3782
+ authentication: {
3783
+ /**
3784
+ * @maxItems 1
3785
+ */
3786
+ schemes: [] | [AuthenticationScheme];
3787
+ /**
3788
+ * Authentication credential (e.g., Bearer token).
3789
+ */
3790
+ credentials: string;
3791
+ };
3792
+ /**
3793
+ * Governance categories this agent handles (e.g., ['budget_authority', 'strategic_alignment']). When omitted, the agent handles all categories.
3794
+ */
3795
+ categories?: string[];
3796
+ }[];
3516
3797
  /**
3517
3798
  * When true, this is a sandbox account — no real platform calls, no real spend. For explicit accounts (require_operator_auth: true), sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts. For implicit accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.
3518
3799
  */
@@ -3587,6 +3868,54 @@ export interface Package {
3587
3868
  paused?: boolean;
3588
3869
  ext?: ExtensionObject;
3589
3870
  }
3871
+ /**
3872
+ * The seller's interpreted delivery parameters. Describes what the seller will actually run -- geo, channels, flight dates, frequency caps, and budget. Present when the account has governance_agents or when the seller chooses to provide delivery transparency.
3873
+ */
3874
+ export interface PlannedDelivery {
3875
+ /**
3876
+ * Geographic targeting the seller will apply.
3877
+ */
3878
+ geo?: {
3879
+ /**
3880
+ * ISO 3166-1 alpha-2 country codes where ads will deliver.
3881
+ */
3882
+ countries?: string[];
3883
+ /**
3884
+ * ISO 3166-2 subdivision codes where ads will deliver.
3885
+ */
3886
+ regions?: string[];
3887
+ };
3888
+ /**
3889
+ * Channels the seller will deliver on.
3890
+ */
3891
+ channels?: MediaChannel[];
3892
+ /**
3893
+ * Actual flight start the seller will use.
3894
+ */
3895
+ start_time?: string;
3896
+ /**
3897
+ * Actual flight end the seller will use.
3898
+ */
3899
+ end_time?: string;
3900
+ frequency_cap?: FrequencyCap;
3901
+ /**
3902
+ * Human-readable summary of the audience the seller will target.
3903
+ */
3904
+ audience_summary?: string;
3905
+ /**
3906
+ * Total budget the seller will deliver against.
3907
+ */
3908
+ total_budget?: number;
3909
+ /**
3910
+ * ISO 4217 currency code for the budget.
3911
+ */
3912
+ currency?: string;
3913
+ /**
3914
+ * Registry policy IDs the seller will enforce for this delivery.
3915
+ */
3916
+ enforced_policies?: string[];
3917
+ ext?: ExtensionObject;
3918
+ }
3590
3919
  /**
3591
3920
  * Error response - operation failed, no media buy created
3592
3921
  */
@@ -5446,6 +5775,31 @@ export type BuildCreativeRequest = {
5446
5775
  * Maximum number of catalog items to use when generating. When a catalog asset contains more items than this limit, the creative agent selects the top items based on relevance or catalog ordering. When item_limit exceeds the format's max_items, the creative agent SHOULD use the lesser of the two. Ignored when the manifest contains no catalog assets.
5447
5776
  */
5448
5777
  item_limit?: number;
5778
+ /**
5779
+ * When true, requests the creative agent to include preview renders in the response alongside the manifest. Agents that support this return a 'preview' object in the response using the same structure as preview_creative. Agents that do not support inline preview simply omit the field. This avoids a separate preview_creative round trip for platforms that generate previews as a byproduct of building.
5780
+ */
5781
+ include_preview?: boolean;
5782
+ /**
5783
+ * Input sets for preview generation when include_preview is true. Each input set defines macros and context values for one preview variant. If include_preview is true but this is omitted, the agent generates a single default preview. Only supported with target_format_id (single-format requests). Ignored when using target_format_ids — multi-format requests generate one default preview per format. Ignored when include_preview is false or omitted.
5784
+ */
5785
+ preview_inputs?: {
5786
+ /**
5787
+ * Human-readable name for this input set (e.g., 'Sunny morning on mobile', 'Evening podcast ad')
5788
+ */
5789
+ name: string;
5790
+ /**
5791
+ * Macro values to use for this preview variant
5792
+ */
5793
+ macros?: {
5794
+ [k: string]: string | undefined;
5795
+ };
5796
+ /**
5797
+ * Natural language description of the context for AI-generated content
5798
+ */
5799
+ context_description?: string;
5800
+ }[];
5801
+ preview_quality?: CreativeQuality;
5802
+ preview_output_format?: PreviewOutputFormat;
5449
5803
  /**
5450
5804
  * Macro values to pre-substitute into the output manifest's assets. Keys are universal macro names (e.g., CLICK_URL, CACHEBUSTER); values are the substitution strings. The creative agent translates universal macros to its platform's native syntax. Substitution is literal — all occurrences of each macro in output assets are replaced with the provided value. The caller is responsible for URL-encoding values if the output context requires it. Macros not provided here remain as {MACRO} placeholders for the sales agent to resolve at serve time. Creative agents MUST ignore keys they do not recognize — unknown macro names are not an error.
5451
5805
  */
@@ -5459,10 +5813,22 @@ export type BuildCreativeRequest = {
5459
5813
  } | {
5460
5814
  target_format_id?: never;
5461
5815
  });
5816
+ /**
5817
+ * Types of rights usage that can be licensed through the brand protocol. Aligned with DDEX UseType direction for interoperability with music and media rights systems.
5818
+ */
5819
+ export type RightUse = 'likeness' | 'voice' | 'name' | 'endorsement' | 'motion_capture' | 'signature' | 'catchphrase' | 'sync' | 'background_music' | 'editorial' | 'commercial';
5820
+ /**
5821
+ * Type of rights (talent, music, etc.). Helps identify constraints when a creative combines multiple rights types.
5822
+ */
5823
+ export type RightType = 'talent' | 'character' | 'brand_ip' | 'music' | 'stock_media';
5462
5824
  /**
5463
5825
  * Quality tier for generation. 'draft' produces fast, lower-fidelity output for iteration and review. 'production' produces full-quality output for final delivery. If omitted, the creative agent uses its own default. For non-generative transforms (e.g., format resizing), creative agents MAY ignore this field.
5464
5826
  */
5465
5827
  export type CreativeQuality = 'draft' | 'production';
5828
+ /**
5829
+ * Output format for preview renders when include_preview is true. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML). Ignored when include_preview is false or omitted.
5830
+ */
5831
+ export type PreviewOutputFormat = 'url' | 'html';
5466
5832
  /**
5467
5833
  * Creative manifest to transform or generate from. For pure generation, this should include the target format_id and any required input assets. For transformation (e.g., resizing, reformatting), this is the complete creative to adapt. When creative_id is provided, the agent resolves the creative from its library and this field is ignored.
5468
5834
  */
@@ -5480,169 +5846,73 @@ export interface CreativeManifest {
5480
5846
  */
5481
5847
  [k: string]: ImageAsset | VideoAsset | AudioAsset | VASTAsset | TextAsset | URLAsset | HTMLAsset | JavaScriptAsset | WebhookAsset | CSSAsset | DAASTAsset | MarkdownAsset | BriefAsset | CatalogAsset;
5482
5848
  };
5849
+ /**
5850
+ * Rights constraints attached to this creative. Each entry represents constraints from a single rights holder. A creative may combine multiple rights constraints (e.g., talent likeness + music license). For v1, rights constraints are informational metadata — the buyer/orchestrator manages creative lifecycle against these terms.
5851
+ */
5852
+ rights?: RightsConstraint[];
5483
5853
  provenance?: Provenance;
5484
5854
  ext?: ExtensionObject;
5485
5855
  }
5486
5856
  /**
5487
- * Response containing the transformed or generated creative manifest(s), ready for use with preview_creative or sync_creatives. Returns either a single creative_manifest, an array of creative_manifests (for multi-format requests), or error information.
5488
- */
5489
- export type BuildCreativeResponse = BuildCreativeSuccess | BuildCreativeMultiSuccess | BuildCreativeError;
5490
- /**
5491
- * Single-format success response. Returned when the request used target_format_id.
5857
+ * Rights metadata attached to a creative manifest. Each entry represents constraints from a single rights holder. A creative may combine multiple rights constraints (e.g., talent likeness + music license). For v1, rights constraints are informational metadata — the buyer/orchestrator manages creative lifecycle against these terms.
5492
5858
  */
5493
- export interface BuildCreativeSuccess {
5494
- creative_manifest: CreativeManifest;
5859
+ export interface RightsConstraint {
5495
5860
  /**
5496
- * When true, this response contains simulated data from sandbox mode.
5861
+ * Rights grant identifier from the acquire_rights response
5497
5862
  */
5498
- sandbox?: boolean;
5863
+ rights_id: string;
5499
5864
  /**
5500
- * ISO 8601 timestamp when generated asset URLs in the manifest expire. Set to the earliest expiration across all generated assets. Re-build the creative after this time to get fresh URLs.
5865
+ * The agent that granted these rights
5501
5866
  */
5502
- expires_at?: string;
5503
- context?: ContextObject;
5504
- ext?: ExtensionObject;
5505
- }
5506
- /**
5507
- * Multi-format success response. Returned when the request used target_format_ids. Contains one manifest per requested format. Multi-format requests are atomic — all formats must succeed or the entire request fails with an error response. Array order corresponds to the target_format_ids request order.
5508
- */
5509
- export interface BuildCreativeMultiSuccess {
5867
+ rights_agent: {
5868
+ /**
5869
+ * MCP endpoint URL of the rights agent
5870
+ */
5871
+ url: string;
5872
+ /**
5873
+ * Agent identifier
5874
+ */
5875
+ id: string;
5876
+ };
5510
5877
  /**
5511
- * Array of generated creative manifests, one per requested format. Each manifest contains its own format_id identifying which format it was generated for.
5878
+ * Start of the rights validity period
5512
5879
  */
5513
- creative_manifests: CreativeManifest[];
5880
+ valid_from?: string;
5514
5881
  /**
5515
- * When true, this response contains simulated data from sandbox mode.
5882
+ * End of the rights validity period. Creative should not be served after this time.
5516
5883
  */
5517
- sandbox?: boolean;
5884
+ valid_until?: string;
5518
5885
  /**
5519
- * ISO 8601 timestamp when the earliest generated asset URL expires across all manifests. Re-build after this time to get fresh URLs.
5886
+ * Rights uses covered by this constraint
5520
5887
  */
5521
- expires_at?: string;
5522
- context?: ContextObject;
5888
+ uses: RightUse[];
5889
+ /**
5890
+ * Countries where this creative may be served under these rights (ISO 3166-1 alpha-2). If omitted, no country restriction. When both countries and excluded_countries are present, the effective set is countries minus excluded_countries.
5891
+ */
5892
+ countries?: string[];
5893
+ /**
5894
+ * Countries excluded from rights availability (ISO 3166-1 alpha-2). Use when the grant is worldwide except specific markets.
5895
+ */
5896
+ excluded_countries?: string[];
5897
+ /**
5898
+ * Maximum total impressions allowed for the full validity period (valid_from to valid_until). This is the absolute cap across all creatives using this rights grant, not a per-creative or per-period limit.
5899
+ */
5900
+ impression_cap?: number;
5901
+ right_type?: RightType;
5902
+ /**
5903
+ * Approval status from the rights holder at manifest creation time (snapshot, not a live value)
5904
+ */
5905
+ approval_status?: 'pending' | 'approved' | 'rejected';
5906
+ /**
5907
+ * URL where downstream supply chain participants can verify this rights grant is active. Returns HTTP 200 with the current grant status, or 404 if revoked. Enables SSPs and verification vendors to confirm rights before serving.
5908
+ */
5909
+ verification_url?: string;
5523
5910
  ext?: ExtensionObject;
5524
5911
  }
5525
5912
  /**
5526
- * Error response - creative generation failed
5913
+ * Response containing the transformed or generated creative manifest(s), ready for use with preview_creative or sync_creatives. Returns either a single creative_manifest, an array of creative_manifests (for multi-format requests), or error information.
5527
5914
  */
5528
- export interface BuildCreativeError {
5529
- /**
5530
- * Array of errors explaining why creative generation failed
5531
- */
5532
- errors: Error[];
5533
- context?: ContextObject;
5534
- ext?: ExtensionObject;
5535
- }
5536
- /**
5537
- * Request to generate previews of one or more creative manifests. Accepts either a single creative request or an array of requests for batch processing.
5538
- */
5539
- export type PreviewCreativeRequest = {
5540
- /**
5541
- * Discriminator indicating this is a single preview request
5542
- */
5543
- request_type: 'single';
5544
- format_id?: FormatID;
5545
- creative_manifest: CreativeManifest;
5546
- /**
5547
- * Array of input sets for generating multiple preview variants. Each input set defines macros and context values for one preview rendering. If not provided, creative agent will generate default previews.
5548
- */
5549
- inputs?: {
5550
- /**
5551
- * Human-readable name for this input set (e.g., 'Sunny morning on mobile', 'Evening podcast ad', 'Desktop dark mode')
5552
- */
5553
- name: string;
5554
- /**
5555
- * Macro values to use for this preview. Supports all universal macros from the format's supported_macros list. See docs/creative/universal-macros.md for available macros.
5556
- */
5557
- macros?: {
5558
- [k: string]: string | undefined;
5559
- };
5560
- /**
5561
- * Natural language description of the context for AI-generated content (e.g., 'User just searched for running shoes', 'Podcast discussing weather patterns', 'Article about electric vehicles')
5562
- */
5563
- context_description?: string;
5564
- }[];
5565
- /**
5566
- * Specific template ID for custom format rendering
5567
- */
5568
- template_id?: string;
5569
- output_format?: PreviewOutputFormat;
5570
- /**
5571
- * Maximum number of catalog items to render in the preview. For catalog-driven generative formats, caps how many items are rendered per preview variant. When item_limit exceeds the format's max_items, the creative agent SHOULD use the lesser of the two. Ignored when the manifest contains no catalog assets. Creative agents SHOULD default to a reasonable sample when omitted and the catalog is large.
5572
- */
5573
- item_limit?: number;
5574
- context?: ContextObject;
5575
- ext?: ExtensionObject;
5576
- } | {
5577
- /**
5578
- * Discriminator indicating this is a batch preview request
5579
- */
5580
- request_type: 'batch';
5581
- /**
5582
- * Array of preview requests (1-50 items). Each follows the single request structure.
5583
- *
5584
- * @maxItems 50
5585
- */
5586
- requests: {
5587
- format_id?: FormatID;
5588
- creative_manifest: CreativeManifest;
5589
- /**
5590
- * Array of input sets for generating multiple preview variants
5591
- */
5592
- inputs?: {
5593
- /**
5594
- * Human-readable name for this input set
5595
- */
5596
- name: string;
5597
- /**
5598
- * Macro values to use for this preview
5599
- */
5600
- macros?: {
5601
- [k: string]: string | undefined;
5602
- };
5603
- /**
5604
- * Natural language description of the context for AI-generated content
5605
- */
5606
- context_description?: string;
5607
- }[];
5608
- /**
5609
- * Specific template ID for custom format rendering
5610
- */
5611
- template_id?: string;
5612
- output_format?: PreviewOutputFormat;
5613
- /**
5614
- * Maximum number of catalog items to render in this preview.
5615
- */
5616
- item_limit?: number;
5617
- }[];
5618
- output_format?: PreviewOutputFormat;
5619
- context?: ContextObject;
5620
- ext?: ExtensionObject;
5621
- } | {
5622
- /**
5623
- * Discriminator indicating this is a variant preview request
5624
- */
5625
- request_type: 'variant';
5626
- /**
5627
- * Platform-assigned variant identifier from get_creative_delivery response
5628
- */
5629
- variant_id: string;
5630
- /**
5631
- * Creative identifier for context
5632
- */
5633
- creative_id?: string;
5634
- output_format?: PreviewOutputFormat;
5635
- context?: ContextObject;
5636
- ext?: ExtensionObject;
5637
- };
5638
- /**
5639
- * Output format for previews. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML for direct embedding). Default: 'url' for backward compatibility.
5640
- */
5641
- export type PreviewOutputFormat = 'url' | 'html';
5642
- /**
5643
- * Response containing preview links for one or more creatives. Format matches the request: single preview response for single requests, batch results for batch requests.
5644
- */
5645
- export type PreviewCreativeResponse = PreviewCreativeSingleResponse | PreviewCreativeBatchResponse | PreviewCreativeVariantResponse;
5915
+ export type BuildCreativeResponse = BuildCreativeSuccess | BuildCreativeMultiSuccess | BuildCreativeError;
5646
5916
  /**
5647
5917
  * A single rendered piece of a creative preview with discriminated output format
5648
5918
  */
@@ -5787,109 +6057,357 @@ export type PreviewRender = {
5787
6057
  };
5788
6058
  };
5789
6059
  /**
5790
- * Single preview response - each preview URL returns an HTML page that can be embedded in an iframe
6060
+ * Single-format success response. Returned when the request used target_format_id.
5791
6061
  */
5792
- export interface PreviewCreativeSingleResponse {
6062
+ export interface BuildCreativeSuccess {
6063
+ creative_manifest: CreativeManifest;
5793
6064
  /**
5794
- * Discriminator indicating this is a single preview response
6065
+ * When true, this response contains simulated data from sandbox mode.
5795
6066
  */
5796
- response_type: 'single';
6067
+ sandbox?: boolean;
5797
6068
  /**
5798
- * Array of preview variants. Each preview corresponds to an input set from the request. If no inputs were provided, returns a single default preview.
6069
+ * ISO 8601 timestamp when generated asset URLs in the manifest expire. Set to the earliest expiration across all generated assets. Re-build the creative after this time to get fresh URLs.
5799
6070
  */
5800
- previews: {
5801
- /**
5802
- * Unique identifier for this preview variant
5803
- */
5804
- preview_id: string;
5805
- /**
5806
- * Array of rendered pieces for this preview variant. Most formats render as a single piece. Companion ad formats (video + banner), multi-placement formats, and adaptive formats render as multiple pieces.
5807
- */
5808
- renders: PreviewRender[];
6071
+ expires_at?: string;
6072
+ /**
6073
+ * Preview renders included when the request set include_preview to true and the agent supports it. Contains the same content fields as a preview_creative single response (previews, interactive_url, expires_at) minus the response_type discriminator, so clients can reuse the same preview rendering logic.
6074
+ */
6075
+ preview?: {
5809
6076
  /**
5810
- * The input parameters that generated this preview variant. Echoes back the request input or shows defaults used.
6077
+ * Array of preview variants. Each preview corresponds to an input set from preview_inputs, or a single default preview if no inputs were provided.
5811
6078
  */
5812
- input: {
6079
+ previews: {
5813
6080
  /**
5814
- * Human-readable name for this variant
6081
+ * Unique identifier for this preview variant
5815
6082
  */
5816
- name: string;
6083
+ preview_id: string;
5817
6084
  /**
5818
- * Macro values applied to this variant
6085
+ * Array of rendered pieces for this preview variant. Most formats render as a single piece. Companion ad formats render as multiple pieces.
5819
6086
  */
5820
- macros?: {
5821
- [k: string]: string | undefined;
5822
- };
6087
+ renders: PreviewRender[];
5823
6088
  /**
5824
- * Context description applied to this variant
6089
+ * The input parameters that generated this preview variant. Echoes back the request input or shows defaults used.
5825
6090
  */
5826
- context_description?: string;
5827
- };
5828
- }[];
5829
- /**
5830
- * Optional URL to an interactive testing page that shows all preview variants with controls to switch between them, modify macro values, and test different scenarios.
5831
- */
5832
- interactive_url?: string;
5833
- /**
5834
- * ISO 8601 timestamp when preview links expire
5835
- */
5836
- expires_at: string;
6091
+ input: {
6092
+ /**
6093
+ * Human-readable name for this variant
6094
+ */
6095
+ name: string;
6096
+ /**
6097
+ * Macro values applied to this variant
6098
+ */
6099
+ macros?: {
6100
+ [k: string]: string | undefined;
6101
+ };
6102
+ /**
6103
+ * Context description applied to this variant
6104
+ */
6105
+ context_description?: string;
6106
+ };
6107
+ }[];
6108
+ /**
6109
+ * Optional URL to an interactive testing page that shows all preview variants with controls to switch between them.
6110
+ */
6111
+ interactive_url?: string;
6112
+ /**
6113
+ * ISO 8601 timestamp when preview URLs expire. May differ from the manifest's expires_at.
6114
+ */
6115
+ expires_at: string;
6116
+ };
6117
+ preview_error?: Error;
5837
6118
  context?: ContextObject;
5838
6119
  ext?: ExtensionObject;
5839
6120
  }
5840
6121
  /**
5841
- * Batch preview response - contains results for multiple creative requests
6122
+ * Multi-format success response. Returned when the request used target_format_ids. Contains one manifest per requested format. Multi-format requests are atomic all formats must succeed or the entire request fails with an error response. Array order corresponds to the target_format_ids request order.
5842
6123
  */
5843
- export interface PreviewCreativeBatchResponse {
6124
+ export interface BuildCreativeMultiSuccess {
5844
6125
  /**
5845
- * Discriminator indicating this is a batch preview response
6126
+ * Array of generated creative manifests, one per requested format. Each manifest contains its own format_id identifying which format it was generated for.
5846
6127
  */
5847
- response_type: 'batch';
6128
+ creative_manifests: CreativeManifest[];
5848
6129
  /**
5849
- * Array of preview results corresponding to each request in the same order. results[0] is the result for requests[0], results[1] for requests[1], etc. Order is guaranteed even when some requests fail. Each result contains either a successful preview response or an error.
6130
+ * When true, this response contains simulated data from sandbox mode.
5850
6131
  */
5851
- results: (PreviewBatchResultSuccess | PreviewBatchResultError)[];
5852
- context?: ContextObject;
5853
- ext?: ExtensionObject;
5854
- }
5855
- export interface PreviewBatchResultSuccess {
6132
+ sandbox?: boolean;
5856
6133
  /**
5857
- * Indicates this preview request succeeded
6134
+ * ISO 8601 timestamp when the earliest generated asset URL expires across all manifests. Re-build after this time to get fresh URLs.
5858
6135
  */
5859
- success?: true;
5860
- }
5861
- export interface PreviewBatchResultError {
6136
+ expires_at?: string;
5862
6137
  /**
5863
- * Indicates this preview request failed
6138
+ * Preview renders included when the request set include_preview to true and the agent supports it. Contains one default preview per requested format. preview_inputs is ignored for multi-format requests.
5864
6139
  */
5865
- success?: false;
6140
+ preview?: {
6141
+ /**
6142
+ * Array of preview entries, one per requested format. Array order matches creative_manifests. Each entry includes a format_id for explicit correlation.
6143
+ */
6144
+ previews: {
6145
+ /**
6146
+ * Unique identifier for this preview
6147
+ */
6148
+ preview_id: string;
6149
+ format_id: FormatID;
6150
+ /**
6151
+ * Array of rendered pieces for this format's preview. Most formats render as a single piece. Companion ad formats render as multiple pieces.
6152
+ */
6153
+ renders: PreviewRender[];
6154
+ /**
6155
+ * The input parameters that generated this preview. For multi-format responses, this is always a default input.
6156
+ */
6157
+ input: {
6158
+ /**
6159
+ * Human-readable name for this preview
6160
+ */
6161
+ name: string;
6162
+ /**
6163
+ * Macro values applied to this preview
6164
+ */
6165
+ macros?: {
6166
+ [k: string]: string | undefined;
6167
+ };
6168
+ /**
6169
+ * Context description applied to this preview
6170
+ */
6171
+ context_description?: string;
6172
+ };
6173
+ }[];
6174
+ /**
6175
+ * Optional URL to an interactive testing page that shows all format previews with controls to switch between them.
6176
+ */
6177
+ interactive_url?: string;
6178
+ /**
6179
+ * ISO 8601 timestamp when preview URLs expire. May differ from the manifest's expires_at.
6180
+ */
6181
+ expires_at: string;
6182
+ };
6183
+ preview_error?: Error;
6184
+ context?: ContextObject;
6185
+ ext?: ExtensionObject;
5866
6186
  }
5867
6187
  /**
5868
- * Variant preview response - shows what a specific creative variant looked like when served during delivery
6188
+ * Error response - creative generation failed
5869
6189
  */
5870
- export interface PreviewCreativeVariantResponse {
5871
- /**
5872
- * Discriminator indicating this is a variant preview response
5873
- */
5874
- response_type: 'variant';
6190
+ export interface BuildCreativeError {
5875
6191
  /**
5876
- * Platform-assigned variant identifier
6192
+ * Array of errors explaining why creative generation failed
5877
6193
  */
5878
- variant_id: string;
6194
+ errors: Error[];
6195
+ context?: ContextObject;
6196
+ ext?: ExtensionObject;
6197
+ }
6198
+ /**
6199
+ * Request to generate previews of one or more creative manifests. Accepts either a single creative request or an array of requests for batch processing.
6200
+ */
6201
+ export type PreviewCreativeRequest = {
5879
6202
  /**
5880
- * Creative identifier this variant belongs to
6203
+ * Discriminator indicating this is a single preview request
5881
6204
  */
5882
- creative_id?: string;
6205
+ request_type: 'single';
6206
+ format_id?: FormatID;
6207
+ creative_manifest: CreativeManifest;
5883
6208
  /**
5884
- * Array of rendered pieces for this variant. Most formats render as a single piece.
6209
+ * Array of input sets for generating multiple preview variants. Each input set defines macros and context values for one preview rendering. If not provided, creative agent will generate default previews.
5885
6210
  */
5886
- previews: {
6211
+ inputs?: {
5887
6212
  /**
5888
- * Unique identifier for this preview
6213
+ * Human-readable name for this input set (e.g., 'Sunny morning on mobile', 'Evening podcast ad', 'Desktop dark mode')
5889
6214
  */
5890
- preview_id: string;
6215
+ name: string;
5891
6216
  /**
5892
- * Rendered pieces for this variant
6217
+ * Macro values to use for this preview. Supports all universal macros from the format's supported_macros list. See docs/creative/universal-macros.md for available macros.
6218
+ */
6219
+ macros?: {
6220
+ [k: string]: string | undefined;
6221
+ };
6222
+ /**
6223
+ * Natural language description of the context for AI-generated content (e.g., 'User just searched for running shoes', 'Podcast discussing weather patterns', 'Article about electric vehicles')
6224
+ */
6225
+ context_description?: string;
6226
+ }[];
6227
+ /**
6228
+ * Specific template ID for custom format rendering
6229
+ */
6230
+ template_id?: string;
6231
+ quality?: CreativeQuality;
6232
+ output_format?: PreviewOutputFormat;
6233
+ /**
6234
+ * Maximum number of catalog items to render in the preview. For catalog-driven generative formats, caps how many items are rendered per preview variant. When item_limit exceeds the format's max_items, the creative agent SHOULD use the lesser of the two. Ignored when the manifest contains no catalog assets. Creative agents SHOULD default to a reasonable sample when omitted and the catalog is large.
6235
+ */
6236
+ item_limit?: number;
6237
+ context?: ContextObject;
6238
+ ext?: ExtensionObject;
6239
+ } | {
6240
+ /**
6241
+ * Discriminator indicating this is a batch preview request
6242
+ */
6243
+ request_type: 'batch';
6244
+ /**
6245
+ * Array of preview requests (1-50 items). Each follows the single request structure.
6246
+ *
6247
+ * @maxItems 50
6248
+ */
6249
+ requests: {
6250
+ format_id?: FormatID;
6251
+ creative_manifest: CreativeManifest;
6252
+ /**
6253
+ * Array of input sets for generating multiple preview variants
6254
+ */
6255
+ inputs?: {
6256
+ /**
6257
+ * Human-readable name for this input set
6258
+ */
6259
+ name: string;
6260
+ /**
6261
+ * Macro values to use for this preview
6262
+ */
6263
+ macros?: {
6264
+ [k: string]: string | undefined;
6265
+ };
6266
+ /**
6267
+ * Natural language description of the context for AI-generated content
6268
+ */
6269
+ context_description?: string;
6270
+ }[];
6271
+ /**
6272
+ * Specific template ID for custom format rendering
6273
+ */
6274
+ template_id?: string;
6275
+ quality?: CreativeQuality;
6276
+ output_format?: PreviewOutputFormat;
6277
+ /**
6278
+ * Maximum number of catalog items to render in this preview.
6279
+ */
6280
+ item_limit?: number;
6281
+ }[];
6282
+ quality?: CreativeQuality;
6283
+ output_format?: PreviewOutputFormat;
6284
+ context?: ContextObject;
6285
+ ext?: ExtensionObject;
6286
+ } | {
6287
+ /**
6288
+ * Discriminator indicating this is a variant preview request
6289
+ */
6290
+ request_type: 'variant';
6291
+ /**
6292
+ * Platform-assigned variant identifier from get_creative_delivery response
6293
+ */
6294
+ variant_id: string;
6295
+ /**
6296
+ * Creative identifier for context
6297
+ */
6298
+ creative_id?: string;
6299
+ output_format?: PreviewOutputFormat;
6300
+ context?: ContextObject;
6301
+ ext?: ExtensionObject;
6302
+ };
6303
+ /**
6304
+ * Response containing preview links for one or more creatives. Format matches the request: single preview response for single requests, batch results for batch requests.
6305
+ */
6306
+ export type PreviewCreativeResponse = PreviewCreativeSingleResponse | PreviewCreativeBatchResponse | PreviewCreativeVariantResponse;
6307
+ /**
6308
+ * Single preview response - each preview URL returns an HTML page that can be embedded in an iframe
6309
+ */
6310
+ export interface PreviewCreativeSingleResponse {
6311
+ /**
6312
+ * Discriminator indicating this is a single preview response
6313
+ */
6314
+ response_type: 'single';
6315
+ /**
6316
+ * Array of preview variants. Each preview corresponds to an input set from the request. If no inputs were provided, returns a single default preview.
6317
+ */
6318
+ previews: {
6319
+ /**
6320
+ * Unique identifier for this preview variant
6321
+ */
6322
+ preview_id: string;
6323
+ /**
6324
+ * Array of rendered pieces for this preview variant. Most formats render as a single piece. Companion ad formats (video + banner), multi-placement formats, and adaptive formats render as multiple pieces.
6325
+ */
6326
+ renders: PreviewRender[];
6327
+ /**
6328
+ * The input parameters that generated this preview variant. Echoes back the request input or shows defaults used.
6329
+ */
6330
+ input: {
6331
+ /**
6332
+ * Human-readable name for this variant
6333
+ */
6334
+ name: string;
6335
+ /**
6336
+ * Macro values applied to this variant
6337
+ */
6338
+ macros?: {
6339
+ [k: string]: string | undefined;
6340
+ };
6341
+ /**
6342
+ * Context description applied to this variant
6343
+ */
6344
+ context_description?: string;
6345
+ };
6346
+ }[];
6347
+ /**
6348
+ * Optional URL to an interactive testing page that shows all preview variants with controls to switch between them, modify macro values, and test different scenarios.
6349
+ */
6350
+ interactive_url?: string;
6351
+ /**
6352
+ * ISO 8601 timestamp when preview links expire
6353
+ */
6354
+ expires_at: string;
6355
+ context?: ContextObject;
6356
+ ext?: ExtensionObject;
6357
+ }
6358
+ /**
6359
+ * Batch preview response - contains results for multiple creative requests
6360
+ */
6361
+ export interface PreviewCreativeBatchResponse {
6362
+ /**
6363
+ * Discriminator indicating this is a batch preview response
6364
+ */
6365
+ response_type: 'batch';
6366
+ /**
6367
+ * Array of preview results corresponding to each request in the same order. results[0] is the result for requests[0], results[1] for requests[1], etc. Order is guaranteed even when some requests fail. Each result contains either a successful preview response or an error.
6368
+ */
6369
+ results: (PreviewBatchResultSuccess | PreviewBatchResultError)[];
6370
+ context?: ContextObject;
6371
+ ext?: ExtensionObject;
6372
+ }
6373
+ export interface PreviewBatchResultSuccess {
6374
+ /**
6375
+ * Indicates this preview request succeeded
6376
+ */
6377
+ success?: true;
6378
+ }
6379
+ export interface PreviewBatchResultError {
6380
+ /**
6381
+ * Indicates this preview request failed
6382
+ */
6383
+ success?: false;
6384
+ }
6385
+ /**
6386
+ * Variant preview response - shows what a specific creative variant looked like when served during delivery
6387
+ */
6388
+ export interface PreviewCreativeVariantResponse {
6389
+ /**
6390
+ * Discriminator indicating this is a variant preview response
6391
+ */
6392
+ response_type: 'variant';
6393
+ /**
6394
+ * Platform-assigned variant identifier
6395
+ */
6396
+ variant_id: string;
6397
+ /**
6398
+ * Creative identifier this variant belongs to
6399
+ */
6400
+ creative_id?: string;
6401
+ /**
6402
+ * Array of rendered pieces for this variant. Most formats render as a single piece.
6403
+ */
6404
+ previews: {
6405
+ /**
6406
+ * Unique identifier for this preview
6407
+ */
6408
+ preview_id: string;
6409
+ /**
6410
+ * Rendered pieces for this variant
5893
6411
  */
5894
6412
  renders: PreviewRender[];
5895
6413
  }[];
@@ -7603,7 +8121,11 @@ export interface CreateContentStandardsRequest {
7603
8121
  description?: string;
7604
8122
  };
7605
8123
  /**
7606
- * Natural language policy describing acceptable and unacceptable content contexts. Used by LLMs and human reviewers to make judgments.
8124
+ * Registry policy IDs to use as the evaluation basis for this content standard. When provided, the agent resolves policies from the registry and uses their policy text and exemplars as the evaluation criteria. The 'policy' field becomes optional when registry_policy_ids is provided.
8125
+ */
8126
+ registry_policy_ids?: string[];
8127
+ /**
8128
+ * Natural language policy describing acceptable and unacceptable content contexts. Used by LLMs and human reviewers to make judgments. Optional when registry_policy_ids is provided.
7607
8129
  */
7608
8130
  policy: string;
7609
8131
  /**
@@ -7696,6 +8218,10 @@ export interface UpdateContentStandardsRequest {
7696
8218
  */
7697
8219
  description?: string;
7698
8220
  };
8221
+ /**
8222
+ * Registry policy IDs to use as the evaluation basis. When provided, the agent resolves policies from the registry and uses their policy text and exemplars as the evaluation criteria.
8223
+ */
8224
+ registry_policy_ids?: string[];
7699
8225
  /**
7700
8226
  * Updated natural language policy describing acceptable and unacceptable content contexts.
7701
8227
  */
@@ -7917,222 +8443,1104 @@ export type ValidateContentDeliveryResponse = {
7917
8443
  value?: unknown;
7918
8444
  message?: string;
7919
8445
  /**
7920
- * Which rule triggered this result (e.g., GARM category, Scope3 standard)
8446
+ * Which rule triggered this result (e.g., GARM category, Scope3 standard)
8447
+ */
8448
+ rule_id?: string;
8449
+ }[];
8450
+ }[];
8451
+ context?: ContextObject;
8452
+ ext?: ExtensionObject;
8453
+ } | {
8454
+ errors: Error[];
8455
+ context?: ContextObject;
8456
+ ext?: ExtensionObject;
8457
+ };
8458
+ /**
8459
+ * Request parameters for retrieving content artifacts from a media buy for validation
8460
+ */
8461
+ export interface GetMediaBuyArtifactsRequest {
8462
+ account?: AccountReference;
8463
+ /**
8464
+ * Media buy to get artifacts from
8465
+ */
8466
+ media_buy_id: string;
8467
+ /**
8468
+ * Filter to specific packages within the media buy
8469
+ */
8470
+ package_ids?: string[];
8471
+ /**
8472
+ * Sampling parameters. Defaults to the sampling rate agreed in the media buy.
8473
+ */
8474
+ sampling?: {
8475
+ /**
8476
+ * Sampling rate (0-1). 1.0 = all deliveries, 0.25 = 25% sample.
8477
+ */
8478
+ rate?: number;
8479
+ /**
8480
+ * How to select the sample
8481
+ */
8482
+ method?: 'random' | 'stratified' | 'recent' | 'failures_only';
8483
+ };
8484
+ /**
8485
+ * Filter to specific time period
8486
+ */
8487
+ time_range?: {
8488
+ /**
8489
+ * Start of time range (inclusive)
8490
+ */
8491
+ start?: string;
8492
+ /**
8493
+ * End of time range (exclusive)
8494
+ */
8495
+ end?: string;
8496
+ };
8497
+ /**
8498
+ * Pagination parameters. Uses higher limits than standard pagination because artifact result sets can be very large.
8499
+ */
8500
+ pagination?: {
8501
+ /**
8502
+ * Maximum number of artifacts to return per page
8503
+ */
8504
+ max_results?: number;
8505
+ /**
8506
+ * Opaque cursor from a previous response to fetch the next page
8507
+ */
8508
+ cursor?: string;
8509
+ };
8510
+ context?: ContextObject;
8511
+ ext?: ExtensionObject;
8512
+ }
8513
+ /**
8514
+ * Response containing content artifacts from a media buy for validation
8515
+ */
8516
+ export type GetMediaBuyArtifactsResponse = {
8517
+ /**
8518
+ * Media buy these artifacts belong to
8519
+ */
8520
+ media_buy_id: string;
8521
+ /**
8522
+ * Delivery records with full artifact content
8523
+ */
8524
+ artifacts: {
8525
+ /**
8526
+ * Unique identifier for this delivery record
8527
+ */
8528
+ record_id: string;
8529
+ /**
8530
+ * When the delivery occurred
8531
+ */
8532
+ timestamp?: string;
8533
+ /**
8534
+ * Which package this delivery belongs to
8535
+ */
8536
+ package_id?: string;
8537
+ artifact: Artifact;
8538
+ /**
8539
+ * ISO 3166-1 alpha-2 country code where delivery occurred
8540
+ */
8541
+ country?: string;
8542
+ /**
8543
+ * Channel type (e.g., display, video, audio, social)
8544
+ */
8545
+ channel?: string;
8546
+ /**
8547
+ * Brand information for policy evaluation. Schema TBD - placeholder for brand identifiers.
8548
+ */
8549
+ brand_context?: {
8550
+ /**
8551
+ * Brand identifier
8552
+ */
8553
+ brand_id?: string;
8554
+ /**
8555
+ * Product/SKU identifier if applicable
8556
+ */
8557
+ sku_id?: string;
8558
+ };
8559
+ /**
8560
+ * Seller's local model verdict for this artifact
8561
+ */
8562
+ local_verdict?: 'pass' | 'fail' | 'unevaluated';
8563
+ }[];
8564
+ /**
8565
+ * Information about how the sample was generated
8566
+ */
8567
+ sampling_info?: {
8568
+ /**
8569
+ * Total deliveries in the time range
8570
+ */
8571
+ total_deliveries?: number;
8572
+ /**
8573
+ * Number of artifacts in this response
8574
+ */
8575
+ sampled_count?: number;
8576
+ /**
8577
+ * Actual sampling rate achieved
8578
+ */
8579
+ effective_rate?: number;
8580
+ /**
8581
+ * Sampling method used
8582
+ */
8583
+ method?: 'random' | 'stratified' | 'recent' | 'failures_only';
8584
+ };
8585
+ pagination?: PaginationResponse;
8586
+ context?: ContextObject;
8587
+ ext?: ExtensionObject;
8588
+ } | {
8589
+ errors: Error[];
8590
+ context?: ContextObject;
8591
+ ext?: ExtensionObject;
8592
+ };
8593
+ /**
8594
+ * Request payload for the get_creative_features task. Submits a creative manifest for evaluation by a governance agent, which analyzes the creative and returns scored feature values (brand safety, content categorization, quality metrics, etc.).
8595
+ */
8596
+ export interface GetCreativeFeaturesRequest {
8597
+ creative_manifest: CreativeManifest;
8598
+ /**
8599
+ * Optional filter to specific features. If omitted, returns all available features.
8600
+ */
8601
+ feature_ids?: string[];
8602
+ account?: AccountReference;
8603
+ context?: ContextObject;
8604
+ ext?: ExtensionObject;
8605
+ }
8606
+ /**
8607
+ * Response payload for the get_creative_features task. Returns scored feature values from the governance agent's evaluation of the submitted creative manifest.
8608
+ */
8609
+ export type GetCreativeFeaturesResponse = {
8610
+ /**
8611
+ * Feature values for the evaluated creative
8612
+ */
8613
+ results: CreativeFeatureResult[];
8614
+ /**
8615
+ * URL to the vendor's full assessment report. The vendor controls what information is disclosed and access control.
8616
+ */
8617
+ detail_url?: string;
8618
+ context?: ContextObject;
8619
+ ext?: ExtensionObject;
8620
+ } | {
8621
+ errors: Error[];
8622
+ context?: ContextObject;
8623
+ ext?: ExtensionObject;
8624
+ };
8625
+ /**
8626
+ * A single feature evaluation result for a creative. Uses the same value structure as property-feature-value (value, confidence, expires_at, etc.).
8627
+ */
8628
+ export interface CreativeFeatureResult {
8629
+ /**
8630
+ * The feature that was evaluated (e.g., 'auto_redirect', 'brand_consistency'). Features prefixed with 'registry:' reference standardized policies from the shared policy registry (e.g., 'registry:eu_ai_act_article_50'). Unprefixed feature IDs are agent-defined.
8631
+ */
8632
+ feature_id: string;
8633
+ /**
8634
+ * The feature value. Type depends on feature definition: boolean for binary, number for quantitative, string for categorical.
8635
+ */
8636
+ value: boolean | number | string;
8637
+ /**
8638
+ * Unit of measurement for quantitative values (e.g., 'percentage', 'score')
8639
+ */
8640
+ unit?: string;
8641
+ /**
8642
+ * Confidence score for this value (0-1)
8643
+ */
8644
+ confidence?: number;
8645
+ /**
8646
+ * When this feature was evaluated
8647
+ */
8648
+ measured_at?: string;
8649
+ /**
8650
+ * When this evaluation expires and should be refreshed
8651
+ */
8652
+ expires_at?: string;
8653
+ /**
8654
+ * Version of the methodology used to evaluate this feature
8655
+ */
8656
+ methodology_version?: string;
8657
+ /**
8658
+ * Additional vendor-specific details about this evaluation
8659
+ */
8660
+ details?: {};
8661
+ ext?: ExtensionObject;
8662
+ }
8663
+ /**
8664
+ * Budget authority level for the orchestrator agent.
8665
+ */
8666
+ export type BudgetAuthorityLevel = 'agent_full' | 'agent_limited' | 'human_required';
8667
+ /**
8668
+ * Authority level granted to this agent.
8669
+ */
8670
+ export type DelegationAuthority = 'full' | 'execute_only' | 'propose_only';
8671
+ /**
8672
+ * Governance enforcement mode for this plan. 'enforce': denied actions are blocked. 'advisory': denied actions proceed with findings logged. 'audit': all actions proceed, findings logged. Defaults to 'enforce' if omitted.
8673
+ */
8674
+ export type GovernanceMode = 'audit' | 'advisory' | 'enforce';
8675
+ /**
8676
+ * Push campaign plans to the governance agent. A plan defines the authorized parameters for a campaign -- budget limits, channels, flight dates, and authorized markets.
8677
+ */
8678
+ export interface SyncPlansRequest {
8679
+ /**
8680
+ * One or more campaign plans to sync.
8681
+ */
8682
+ plans: {
8683
+ /**
8684
+ * Unique identifier for this plan.
8685
+ */
8686
+ plan_id: string;
8687
+ brand: BrandReference;
8688
+ /**
8689
+ * Natural language campaign objectives. Used for strategic alignment validation.
8690
+ */
8691
+ objectives: string;
8692
+ /**
8693
+ * Budget authorization parameters.
8694
+ */
8695
+ budget: {
8696
+ /**
8697
+ * Total authorized budget.
8698
+ */
8699
+ total: number;
8700
+ /**
8701
+ * ISO 4217 currency code.
8702
+ */
8703
+ currency: string;
8704
+ authority_level: BudgetAuthorityLevel;
8705
+ /**
8706
+ * Maximum percentage of budget that can go to a single seller.
8707
+ */
8708
+ per_seller_max_pct?: number;
8709
+ /**
8710
+ * Amount above which reallocations require escalation (for agent_limited).
8711
+ */
8712
+ reallocation_threshold?: number;
8713
+ };
8714
+ /**
8715
+ * Channel constraints. If omitted, all channels are allowed.
8716
+ */
8717
+ channels?: {
8718
+ /**
8719
+ * Channels that must be included in the media mix.
8720
+ */
8721
+ required?: MediaChannel[];
8722
+ /**
8723
+ * Channels the orchestrator may use.
8724
+ */
8725
+ allowed?: MediaChannel[];
8726
+ /**
8727
+ * Target allocation ranges per channel, keyed by channel ID.
8728
+ */
8729
+ mix_targets?: {
8730
+ [k: string]: {
8731
+ min_pct?: number;
8732
+ max_pct?: number;
8733
+ } | undefined;
8734
+ };
8735
+ };
8736
+ /**
8737
+ * Authorized flight dates. Media buys with dates outside this window are rejected.
8738
+ */
8739
+ flight: {
8740
+ /**
8741
+ * Flight start (ISO 8601).
8742
+ */
8743
+ start: string;
8744
+ /**
8745
+ * Flight end (ISO 8601).
8746
+ */
8747
+ end: string;
8748
+ };
8749
+ /**
8750
+ * ISO 3166-1 alpha-2 country codes for authorized markets (e.g., ['US', 'GB']). The governance agent rejects media buys targeting outside these countries and resolves applicable policies by matching against policy jurisdictions.
8751
+ */
8752
+ countries?: string[];
8753
+ /**
8754
+ * ISO 3166-2 subdivision codes for authorized sub-national markets (e.g., ['US-MA', 'US-CA']). When present, the governance agent restricts buys to these specific regions rather than the full country. Use for campaigns limited to specific states or provinces (e.g., cannabis in legal states). Policy resolution matches against both the subdivision and its parent country.
8755
+ */
8756
+ regions?: string[];
8757
+ /**
8758
+ * Registry policy IDs to enforce for this plan. The governance agent resolves full policy definitions from the registry and evaluates actions against them. Intersected with the plan's countries/regions to activate only geographically relevant policies.
8759
+ */
8760
+ policy_ids?: string[];
8761
+ /**
8762
+ * Natural language policy statements specific to this campaign (e.g., 'No advertising adjacent to competitor content'). Applied regardless of geography.
8763
+ */
8764
+ custom_policies?: string[];
8765
+ /**
8766
+ * List of approved seller agent URLs. null means any seller.
8767
+ */
8768
+ approved_sellers?: string[] | null;
8769
+ /**
8770
+ * Agents authorized to execute against this plan. Each delegation scopes an agent's authority by budget, markets, and expiration. The governance agent validates that the requesting agent matches a delegation before approving actions.
8771
+ */
8772
+ delegations?: {
8773
+ /**
8774
+ * URL of the delegated agent.
8775
+ */
8776
+ agent_url: string;
8777
+ authority: DelegationAuthority;
8778
+ /**
8779
+ * Maximum budget this agent can commit. When omitted, the agent can commit up to the plan's total budget.
8780
+ */
8781
+ budget_limit?: {
8782
+ amount: number;
8783
+ currency: string;
8784
+ };
8785
+ /**
8786
+ * ISO 3166-1/3166-2 codes this agent is authorized for. When omitted, the agent can operate in all plan markets.
8787
+ */
8788
+ markets?: string[];
8789
+ /**
8790
+ * When this delegation expires. After expiration, the governance agent denies actions from this agent.
8791
+ */
8792
+ expires_at?: string;
8793
+ }[];
8794
+ /**
8795
+ * Portfolio-level governance constraints. When present, this plan acts as a portfolio plan that governs member plans. Portfolio plans define cross-brand constraints that no individual brand plan can override.
8796
+ */
8797
+ portfolio?: {
8798
+ /**
8799
+ * Plan IDs governed by this portfolio plan. The governance agent validates member plan actions against portfolio constraints.
8800
+ */
8801
+ member_plan_ids: string[];
8802
+ /**
8803
+ * Maximum aggregate budget across all member plans.
8804
+ */
8805
+ total_budget_cap?: {
8806
+ amount: number;
8807
+ currency: string;
8808
+ };
8809
+ /**
8810
+ * Registry policy IDs enforced across all member plans, regardless of individual brand configuration.
8811
+ */
8812
+ shared_policy_ids?: string[];
8813
+ /**
8814
+ * Natural language exclusion rules applied across all member plans (e.g., 'No advertising on properties owned by competitor holding companies').
8815
+ */
8816
+ shared_exclusions?: string[];
8817
+ };
8818
+ mode?: GovernanceMode;
8819
+ ext?: ExtensionObject;
8820
+ }[];
8821
+ }
8822
+ /**
8823
+ * Enforcement level for this policy.
8824
+ */
8825
+ export type PolicyEnforcementLevel = 'must' | 'should' | 'may';
8826
+ /**
8827
+ * Response from syncing campaign plans. Returns status and active validation categories for each plan.
8828
+ */
8829
+ export interface SyncPlansResponse {
8830
+ /**
8831
+ * Status for each synced plan.
8832
+ */
8833
+ plans: {
8834
+ /**
8835
+ * Plan identifier.
8836
+ */
8837
+ plan_id: string;
8838
+ /**
8839
+ * Sync result status. 'active' means sync succeeded; 'error' means sync failed.
8840
+ */
8841
+ status: 'active' | 'error';
8842
+ /**
8843
+ * Plan version (increments on each sync).
8844
+ */
8845
+ version: number;
8846
+ /**
8847
+ * Validation categories active for this plan.
8848
+ */
8849
+ categories?: {
8850
+ /**
8851
+ * Validation category identifier.
8852
+ */
8853
+ category_id: string;
8854
+ /**
8855
+ * Whether this category is active for this plan.
8856
+ */
8857
+ status: 'active' | 'inactive';
8858
+ }[];
8859
+ /**
8860
+ * Policies the governance agent will enforce for this plan. Includes explicitly referenced policies from the brand compliance configuration and auto-applied policies matched by jurisdiction or vertical. Present when the governance agent supports policy resolution.
8861
+ */
8862
+ resolved_policies?: {
8863
+ /**
8864
+ * Registry policy ID.
8865
+ */
8866
+ policy_id: string;
8867
+ /**
8868
+ * How this policy was included. 'explicit': referenced in the brand compliance configuration. 'auto_applied': matched automatically by jurisdiction, vertical, or category.
8869
+ */
8870
+ source: 'explicit' | 'auto_applied';
8871
+ enforcement: PolicyEnforcementLevel;
8872
+ /**
8873
+ * Why this policy was included (e.g., 'Matched jurisdiction US and vertical pharmaceutical').
8874
+ */
8875
+ reason?: string;
8876
+ }[];
8877
+ }[];
8878
+ }
8879
+ /**
8880
+ * Outcome type.
8881
+ */
8882
+ export type OutcomeType = 'completed' | 'failed' | 'delivery';
8883
+ /**
8884
+ * Report the outcome of an action to the governance agent. Called by the orchestrator (buyer-side agent) after a seller responds. This is the 'after' half of the governance loop. Sellers do not call this task -- they report delivery data via check_governance with phase 'delivery'.
8885
+ */
8886
+ export interface ReportPlanOutcomeRequest {
8887
+ /**
8888
+ * The plan this outcome is for.
8889
+ */
8890
+ plan_id: string;
8891
+ /**
8892
+ * The check_id from check_governance. Links the outcome to the governance check that authorized it. Required for 'completed' and 'failed' outcomes.
8893
+ */
8894
+ check_id?: string;
8895
+ /**
8896
+ * Campaign identifier.
8897
+ */
8898
+ buyer_campaign_ref: string;
8899
+ outcome: OutcomeType;
8900
+ /**
8901
+ * The seller's full response. Required when outcome is 'completed'.
8902
+ */
8903
+ seller_response?: {
8904
+ /**
8905
+ * Seller's media buy identifier.
8906
+ */
8907
+ media_buy_id?: string;
8908
+ /**
8909
+ * The buyer reference echoed back by the seller.
8910
+ */
8911
+ buyer_ref?: string;
8912
+ /**
8913
+ * Total budget committed across all confirmed packages. When present, the governance agent uses this directly instead of summing package budgets.
8914
+ */
8915
+ committed_budget?: number;
8916
+ /**
8917
+ * Confirmed packages with actual budget and targeting.
8918
+ */
8919
+ packages?: {
8920
+ budget?: number;
8921
+ }[];
8922
+ planned_delivery?: PlannedDelivery;
8923
+ /**
8924
+ * ISO 8601 deadline for creative submission.
8925
+ */
8926
+ creative_deadline?: string;
8927
+ };
8928
+ /**
8929
+ * Delivery metrics. Required when outcome is 'delivery'.
8930
+ */
8931
+ delivery?: {
8932
+ /**
8933
+ * The media buy being reported on.
8934
+ */
8935
+ media_buy_id?: string;
8936
+ /**
8937
+ * Start and end timestamps for the reporting window.
8938
+ */
8939
+ reporting_period?: {
8940
+ start: string;
8941
+ end: string;
8942
+ };
8943
+ /**
8944
+ * Impressions delivered in the period.
8945
+ */
8946
+ impressions?: number;
8947
+ /**
8948
+ * Spend in the period.
8949
+ */
8950
+ spend?: number;
8951
+ /**
8952
+ * Effective CPM for the period.
8953
+ */
8954
+ cpm?: number;
8955
+ /**
8956
+ * Viewability rate (0-1).
8957
+ */
8958
+ viewability_rate?: number;
8959
+ /**
8960
+ * Video completion rate (0-1).
8961
+ */
8962
+ completion_rate?: number;
8963
+ };
8964
+ /**
8965
+ * Error details. Required when outcome is 'failed'.
8966
+ */
8967
+ error?: {
8968
+ /**
8969
+ * Error code from the seller.
8970
+ */
8971
+ code?: string;
8972
+ /**
8973
+ * Human-readable error description.
8974
+ */
8975
+ message?: string;
8976
+ };
8977
+ }
8978
+ /**
8979
+ * Finding severity.
8980
+ */
8981
+ export type EscalationSeverity = 'info' | 'warning' | 'critical';
8982
+ /**
8983
+ * Response from reporting an action outcome. Only returned to the orchestrator (buyer-side agent) that manages the plan. Sellers report delivery data via check_governance with phase 'delivery', not via this task.
8984
+ */
8985
+ export interface ReportPlanOutcomeResponse {
8986
+ /**
8987
+ * Unique identifier for this outcome record.
8988
+ */
8989
+ outcome_id: string;
8990
+ /**
8991
+ * 'accepted' means state updated with no issues. 'findings' means issues were detected.
8992
+ */
8993
+ status: 'accepted' | 'findings';
8994
+ /**
8995
+ * Budget committed from this outcome. Present for 'completed' and 'failed' outcomes.
8996
+ */
8997
+ committed_budget?: number;
8998
+ /**
8999
+ * Issues detected. Present only when status is 'findings'.
9000
+ */
9001
+ findings?: {
9002
+ /**
9003
+ * Which validation category flagged the issue.
9004
+ */
9005
+ category_id: string;
9006
+ severity: EscalationSeverity;
9007
+ /**
9008
+ * Human-readable description of the issue.
9009
+ */
9010
+ explanation: string;
9011
+ /**
9012
+ * Structured details for programmatic consumption.
9013
+ */
9014
+ details?: {};
9015
+ }[];
9016
+ /**
9017
+ * Updated plan budget state. Present for 'completed' and 'failed' outcomes.
9018
+ */
9019
+ plan_summary?: {
9020
+ /**
9021
+ * Total budget committed across all campaigns in the plan.
9022
+ */
9023
+ total_committed?: number;
9024
+ /**
9025
+ * Authorized budget minus total committed.
9026
+ */
9027
+ budget_remaining?: number;
9028
+ };
9029
+ }
9030
+ /**
9031
+ * Retrieve governance state and audit trail for one or more plans.
9032
+ */
9033
+ export type GetPlanAuditLogsRequest = {
9034
+ [k: string]: unknown | undefined;
9035
+ } & {
9036
+ /**
9037
+ * Plan IDs to retrieve. For a single plan, pass a one-element array.
9038
+ */
9039
+ plan_ids?: string[];
9040
+ /**
9041
+ * Portfolio plan IDs. The governance agent expands each to its member_plan_ids and returns combined audit data.
9042
+ */
9043
+ portfolio_plan_ids?: string[];
9044
+ /**
9045
+ * Filter to a specific campaign. Omit for plan-level aggregate.
9046
+ */
9047
+ buyer_campaign_ref?: string;
9048
+ /**
9049
+ * Include the full audit trail. Default: false.
9050
+ */
9051
+ include_entries?: boolean;
9052
+ };
9053
+ /**
9054
+ * Governance state and audit trail for one or more plans.
9055
+ */
9056
+ export interface GetPlanAuditLogsResponse {
9057
+ /**
9058
+ * Audit data for each requested plan.
9059
+ */
9060
+ plans: {
9061
+ /**
9062
+ * Plan identifier.
9063
+ */
9064
+ plan_id: string;
9065
+ /**
9066
+ * Current plan version.
9067
+ */
9068
+ plan_version: number;
9069
+ /**
9070
+ * Plan lifecycle status.
9071
+ */
9072
+ status: 'active' | 'suspended' | 'completed';
9073
+ /**
9074
+ * Budget state.
9075
+ */
9076
+ budget: {
9077
+ /**
9078
+ * Total authorized budget from the plan.
9079
+ */
9080
+ authorized?: number;
9081
+ /**
9082
+ * Total budget committed from confirmed outcomes.
9083
+ */
9084
+ committed?: number;
9085
+ /**
9086
+ * Authorized minus committed.
9087
+ */
9088
+ remaining?: number;
9089
+ /**
9090
+ * Committed as a percentage of authorized.
9091
+ */
9092
+ utilization_pct?: number;
9093
+ };
9094
+ /**
9095
+ * Current channel mix. Keyed by channel ID.
9096
+ */
9097
+ channel_allocation?: {
9098
+ [k: string]: {
9099
+ /**
9100
+ * Budget committed to this channel.
9101
+ */
9102
+ committed?: number;
9103
+ /**
9104
+ * Channel's share of the authorized total budget.
9105
+ */
9106
+ pct?: number;
9107
+ } | undefined;
9108
+ };
9109
+ /**
9110
+ * Per-campaign breakdown.
9111
+ */
9112
+ campaigns: {
9113
+ /**
9114
+ * Campaign identifier.
9115
+ */
9116
+ buyer_campaign_ref: string;
9117
+ /**
9118
+ * Campaign status.
9119
+ */
9120
+ status: 'active' | 'suspended' | 'completed';
9121
+ /**
9122
+ * Budget committed in this campaign.
9123
+ */
9124
+ committed: number;
9125
+ /**
9126
+ * Media buy IDs currently active.
9127
+ */
9128
+ active_media_buys?: string[];
9129
+ }[];
9130
+ /**
9131
+ * Aggregate validation and outcome statistics.
9132
+ */
9133
+ summary: {
9134
+ /**
9135
+ * Total governance checks performed.
9136
+ */
9137
+ checks_performed?: number;
9138
+ /**
9139
+ * Total outcomes reported.
9140
+ */
9141
+ outcomes_reported?: number;
9142
+ /**
9143
+ * Count of each governance check status.
9144
+ */
9145
+ statuses?: {
9146
+ approved?: number;
9147
+ denied?: number;
9148
+ conditions?: number;
9149
+ escalated?: number;
9150
+ };
9151
+ /**
9152
+ * Total findings across all checks and outcomes.
9153
+ */
9154
+ findings_count?: number;
9155
+ /**
9156
+ * All escalations and their resolutions.
9157
+ */
9158
+ escalations?: {
9159
+ /**
9160
+ * The escalated governance check.
9161
+ */
9162
+ check_id: string;
9163
+ /**
9164
+ * Why it was escalated.
9165
+ */
9166
+ reason: string;
9167
+ /**
9168
+ * How it was resolved (e.g., 'approved_by_human', 'rejected_by_human').
9169
+ */
9170
+ resolution?: string;
9171
+ /**
9172
+ * ISO 8601 resolution timestamp.
9173
+ */
9174
+ resolved_at?: string;
9175
+ }[];
9176
+ /**
9177
+ * Aggregate governance metrics for detecting oversight drift. A declining escalation rate may indicate well-calibrated governance or eroding human oversight -- surfacing the trend lets the organization make that judgment.
9178
+ */
9179
+ drift_metrics?: {
9180
+ /**
9181
+ * Fraction of checks that resulted in escalation.
9182
+ */
9183
+ escalation_rate?: number;
9184
+ /**
9185
+ * Direction of escalation rate over the plan's lifetime.
9186
+ */
9187
+ escalation_rate_trend?: 'increasing' | 'stable' | 'declining';
9188
+ /**
9189
+ * Fraction of checks approved without human intervention.
9190
+ */
9191
+ auto_approval_rate?: number;
9192
+ /**
9193
+ * Fraction of escalations where the human overrode the governance agent's recommendation.
9194
+ */
9195
+ human_override_rate?: number;
9196
+ /**
9197
+ * Average confidence score across all findings. Present when findings include confidence scores.
9198
+ */
9199
+ mean_confidence?: number;
9200
+ /**
9201
+ * Organization-defined thresholds for drift metrics. When a metric crosses its threshold, the governance agent SHOULD include a finding on the next check. Set by the organization in governance agent configuration, echoed here for visibility.
9202
+ */
9203
+ thresholds?: {
9204
+ /**
9205
+ * Maximum acceptable escalation rate. A rate above this suggests policy miscalibration.
9206
+ */
9207
+ escalation_rate_max?: number;
9208
+ /**
9209
+ * Minimum acceptable escalation rate. A rate below this may indicate eroding oversight.
9210
+ */
9211
+ escalation_rate_min?: number;
9212
+ /**
9213
+ * Maximum acceptable auto-approval rate.
9214
+ */
9215
+ auto_approval_rate_max?: number;
9216
+ /**
9217
+ * Maximum acceptable human override rate. A high rate suggests the governance agent's recommendations are poorly calibrated.
9218
+ */
9219
+ human_override_rate_max?: number;
9220
+ };
9221
+ };
9222
+ };
9223
+ /**
9224
+ * Ordered audit trail. Only present when include_entries is true.
9225
+ */
9226
+ entries?: {
9227
+ /**
9228
+ * Entry identifier.
9229
+ */
9230
+ id: string;
9231
+ /**
9232
+ * Entry type.
9233
+ */
9234
+ type: 'check' | 'outcome';
9235
+ /**
9236
+ * ISO 8601 timestamp.
9237
+ */
9238
+ timestamp: string;
9239
+ /**
9240
+ * Plan this entry belongs to. Present when querying multiple plans or a portfolio.
9241
+ */
9242
+ plan_id?: string;
9243
+ /**
9244
+ * URL of the agent that made the request. Resolved from the credentials used on the governance callback.
9245
+ */
9246
+ caller?: string;
9247
+ /**
9248
+ * The AdCP tool (present for check entries).
9249
+ */
9250
+ tool?: string;
9251
+ /**
9252
+ * Governance check status (present for check entries).
9253
+ */
9254
+ status?: 'approved' | 'denied' | 'conditions' | 'escalated';
9255
+ /**
9256
+ * Whether the check was proposed or committed (present for check entries).
9257
+ */
9258
+ binding?: 'proposed' | 'committed';
9259
+ /**
9260
+ * Human-readable explanation of the governance decision (present for check entries).
9261
+ */
9262
+ explanation?: string;
9263
+ /**
9264
+ * Registry policy IDs evaluated during this check (present for check entries).
9265
+ */
9266
+ policies_evaluated?: string[];
9267
+ /**
9268
+ * Governance categories evaluated (e.g., 'budget_authority', 'regulatory_compliance'). Present for check entries.
7921
9269
  */
7922
- rule_id?: string;
9270
+ categories_evaluated?: string[];
9271
+ /**
9272
+ * Findings from this check or outcome. Same structure as check_governance response findings.
9273
+ */
9274
+ findings?: {
9275
+ category_id: string;
9276
+ policy_id?: string;
9277
+ severity: EscalationSeverity;
9278
+ explanation: string;
9279
+ confidence?: number;
9280
+ }[];
9281
+ outcome?: OutcomeType;
9282
+ /**
9283
+ * Budget committed (present for completed outcome entries).
9284
+ */
9285
+ committed_budget?: number;
9286
+ /**
9287
+ * Media buy ID (present for delivery outcome entries).
9288
+ */
9289
+ media_buy_id?: string;
9290
+ /**
9291
+ * Outcome status (present for outcome entries).
9292
+ */
9293
+ outcome_status?: string;
7923
9294
  }[];
7924
9295
  }[];
7925
- context?: ContextObject;
7926
- ext?: ExtensionObject;
7927
- } | {
7928
- errors: Error[];
7929
- context?: ContextObject;
7930
- ext?: ExtensionObject;
7931
- };
9296
+ }
7932
9297
  /**
7933
- * Request parameters for retrieving content artifacts from a media buy for validation
9298
+ * The phase of the media buy lifecycle. 'purchase': initial create_media_buy. 'modification': update_media_buy. 'delivery': periodic delivery reporting. Defaults to 'purchase' if omitted.
7934
9299
  */
7935
- export interface GetMediaBuyArtifactsRequest {
7936
- account?: AccountReference;
9300
+ export type GovernancePhase = 'purchase' | 'modification' | 'delivery';
9301
+ /**
9302
+ * Universal governance check for campaign actions. Called by the orchestrator before sending to a seller (proposed) or by the seller before executing (committed). The governance agent evaluates the action against the campaign plan and returns a status.
9303
+ */
9304
+ export interface CheckGovernanceRequest {
7937
9305
  /**
7938
- * Media buy to get artifacts from
9306
+ * Campaign governance plan identifier.
7939
9307
  */
7940
- media_buy_id: string;
9308
+ plan_id: string;
7941
9309
  /**
7942
- * Filter to specific packages within the media buy
9310
+ * Buyer's campaign identifier. The governance agent tracks state per campaign within a plan.
7943
9311
  */
7944
- package_ids?: string[];
9312
+ buyer_campaign_ref: string;
7945
9313
  /**
7946
- * Sampling parameters. Defaults to the sampling rate agreed in the media buy.
9314
+ * Whether this is an advisory check or a binding commitment. 'proposed': the orchestrator is checking before sending to a seller — no budget is committed. 'committed': the seller is about to execute — the governance agent validates the planned delivery against the plan. Budget is committed later via report_plan_outcome, not on approval.
7947
9315
  */
7948
- sampling?: {
7949
- /**
7950
- * Sampling rate (0-1). 1.0 = all deliveries, 0.25 = 25% sample.
7951
- */
7952
- rate?: number;
7953
- /**
7954
- * How to select the sample
7955
- */
7956
- method?: 'random' | 'stratified' | 'recent' | 'failures_only';
7957
- };
9316
+ binding: 'proposed' | 'committed';
7958
9317
  /**
7959
- * Filter to specific time period
9318
+ * URL of the agent making the request (orchestrator for proposed, seller for committed).
7960
9319
  */
7961
- time_range?: {
7962
- /**
7963
- * Start of time range (inclusive)
7964
- */
7965
- start?: string;
7966
- /**
7967
- * End of time range (exclusive)
7968
- */
7969
- end?: string;
7970
- };
9320
+ caller: string;
7971
9321
  /**
7972
- * Pagination parameters. Uses higher limits than standard pagination because artifact result sets can be very large.
9322
+ * The AdCP tool being checked (e.g., 'create_media_buy', 'get_products'). Expected for proposed checks. The governance agent uses this to apply tool-specific validation rules.
7973
9323
  */
7974
- pagination?: {
7975
- /**
7976
- * Maximum number of artifacts to return per page
7977
- */
7978
- max_results?: number;
7979
- /**
7980
- * Opaque cursor from a previous response to fetch the next page
7981
- */
7982
- cursor?: string;
7983
- };
7984
- context?: ContextObject;
7985
- ext?: ExtensionObject;
7986
- }
7987
- /**
7988
- * Response containing content artifacts from a media buy for validation
7989
- */
7990
- export type GetMediaBuyArtifactsResponse = {
9324
+ tool?: string;
7991
9325
  /**
7992
- * Media buy these artifacts belong to
9326
+ * The full tool arguments as they would be sent to the seller. Expected for proposed checks. The governance agent can inspect any field to validate against the plan.
7993
9327
  */
7994
- media_buy_id: string;
9328
+ payload?: {};
9329
+ governance_context?: GovernanceContext;
7995
9330
  /**
7996
- * Delivery records with full artifact content
9331
+ * The seller's identifier for the media buy. Expected for committed checks.
7997
9332
  */
7998
- artifacts: {
9333
+ media_buy_id?: string;
9334
+ /**
9335
+ * The buyer's reference identifier from the create_media_buy request.
9336
+ */
9337
+ buyer_ref?: string;
9338
+ phase?: GovernancePhase;
9339
+ planned_delivery?: PlannedDelivery;
9340
+ /**
9341
+ * Actual delivery performance data. MUST be present for 'delivery' phase. The governance agent compares these metrics against the planned delivery to detect drift.
9342
+ */
9343
+ delivery_metrics?: {
7999
9344
  /**
8000
- * Unique identifier for this delivery record
9345
+ * Start and end timestamps for the reporting window.
8001
9346
  */
8002
- record_id: string;
9347
+ reporting_period: {
9348
+ start: string;
9349
+ end: string;
9350
+ };
8003
9351
  /**
8004
- * When the delivery occurred
9352
+ * Total spend during the reporting period.
8005
9353
  */
8006
- timestamp?: string;
9354
+ spend?: number;
8007
9355
  /**
8008
- * Which package this delivery belongs to
9356
+ * Total spend since the media buy started.
8009
9357
  */
8010
- package_id?: string;
8011
- artifact: Artifact;
9358
+ cumulative_spend?: number;
8012
9359
  /**
8013
- * ISO 3166-1 alpha-2 country code where delivery occurred
9360
+ * Impressions delivered during the reporting period.
8014
9361
  */
8015
- country?: string;
9362
+ impressions?: number;
8016
9363
  /**
8017
- * Channel type (e.g., display, video, audio, social)
9364
+ * Total impressions since the media buy started.
8018
9365
  */
8019
- channel?: string;
9366
+ cumulative_impressions?: number;
8020
9367
  /**
8021
- * Brand information for policy evaluation. Schema TBD - placeholder for brand identifiers.
9368
+ * Actual geographic distribution. Keys are ISO 3166-1 alpha-2 codes, values are percentages.
8022
9369
  */
8023
- brand_context?: {
8024
- /**
8025
- * Brand identifier
8026
- */
8027
- brand_id?: string;
8028
- /**
8029
- * Product/SKU identifier if applicable
8030
- */
8031
- sku_id?: string;
9370
+ geo_distribution?: {
9371
+ [k: string]: number | undefined;
8032
9372
  };
8033
9373
  /**
8034
- * Seller's local model verdict for this artifact
9374
+ * Actual channel distribution. Keys are channel enum values, values are percentages.
8035
9375
  */
8036
- local_verdict?: 'pass' | 'fail' | 'unevaluated';
8037
- }[];
9376
+ channel_distribution?: {
9377
+ [k: string]: number | undefined;
9378
+ };
9379
+ /**
9380
+ * Whether delivery is ahead of, on track with, or behind the planned pace.
9381
+ */
9382
+ pacing?: 'ahead' | 'on_track' | 'behind';
9383
+ };
8038
9384
  /**
8039
- * Information about how the sample was generated
9385
+ * Human-readable summary of what changed. SHOULD be present for 'modification' phase.
8040
9386
  */
8041
- sampling_info?: {
9387
+ modification_summary?: string;
9388
+ }
9389
+ /**
9390
+ * Normalized governance-relevant fields extracted from the tool payload. When present, the governance agent SHOULD use these fields for plan validation instead of parsing the payload directly. The caller is responsible for extracting these from the tool arguments.
9391
+ */
9392
+ export interface GovernanceContext {
9393
+ /**
9394
+ * Total budget for the action.
9395
+ */
9396
+ total_budget?: {
8042
9397
  /**
8043
- * Total deliveries in the time range
9398
+ * Budget amount.
8044
9399
  */
8045
- total_deliveries?: number;
9400
+ amount: number;
8046
9401
  /**
8047
- * Number of artifacts in this response
9402
+ * ISO 4217 currency code.
8048
9403
  */
8049
- sampled_count?: number;
9404
+ currency: string;
9405
+ };
9406
+ /**
9407
+ * ISO 3166-1 alpha-2 country codes targeted by this action.
9408
+ */
9409
+ countries?: string[];
9410
+ /**
9411
+ * Channels targeted by this action.
9412
+ */
9413
+ channels?: string[];
9414
+ /**
9415
+ * Flight dates for this action.
9416
+ */
9417
+ flight?: {
8050
9418
  /**
8051
- * Actual sampling rate achieved
9419
+ * Flight start (ISO 8601).
8052
9420
  */
8053
- effective_rate?: number;
9421
+ start: string;
8054
9422
  /**
8055
- * Sampling method used
9423
+ * Flight end (ISO 8601).
8056
9424
  */
8057
- method?: 'random' | 'stratified' | 'recent' | 'failures_only';
9425
+ end: string;
8058
9426
  };
8059
- pagination?: PaginationResponse;
8060
- context?: ContextObject;
8061
- ext?: ExtensionObject;
8062
- } | {
8063
- errors: Error[];
8064
- context?: ContextObject;
8065
- ext?: ExtensionObject;
8066
- };
8067
- /**
8068
- * Request payload for the get_creative_features task. Submits a creative manifest for evaluation by a governance agent, which analyzes the creative and returns scored feature values (brand safety, content categorization, quality metrics, etc.).
8069
- */
8070
- export interface GetCreativeFeaturesRequest {
8071
- creative_manifest: CreativeManifest;
8072
9427
  /**
8073
- * Optional filter to specific features. If omitted, returns all available features.
9428
+ * URL of the seller agent this action targets.
8074
9429
  */
8075
- feature_ids?: string[];
8076
- account?: AccountReference;
8077
- context?: ContextObject;
8078
- ext?: ExtensionObject;
9430
+ seller_url?: string;
8079
9431
  }
8080
9432
  /**
8081
- * Response payload for the get_creative_features task. Returns scored feature values from the governance agent's evaluation of the submitted creative manifest.
9433
+ * Governance agent's response to a check request. Returns whether the action is approved under the campaign plan.
8082
9434
  */
8083
- export type GetCreativeFeaturesResponse = {
9435
+ export interface CheckGovernanceResponse {
8084
9436
  /**
8085
- * Feature values for the evaluated creative
9437
+ * Unique identifier for this governance check record. Use in report_plan_outcome to link outcomes to the check that authorized them.
8086
9438
  */
8087
- results: CreativeFeatureResult[];
9439
+ check_id: string;
8088
9440
  /**
8089
- * URL to the vendor's full assessment report. The vendor controls what information is disclosed and access control.
9441
+ * Governance decision. 'approved': proceed as planned. 'denied': do not proceed. 'conditions': approved if the caller accepts the listed conditions, then re-calls check_governance with the adjusted parameters. 'escalated': halted pending human review.
8090
9442
  */
8091
- detail_url?: string;
8092
- context?: ContextObject;
8093
- ext?: ExtensionObject;
8094
- } | {
8095
- errors: Error[];
8096
- context?: ContextObject;
8097
- ext?: ExtensionObject;
8098
- };
8099
- /**
8100
- * A single feature evaluation result for a creative. Uses the same value structure as property-feature-value (value, confidence, expires_at, etc.).
8101
- */
8102
- export interface CreativeFeatureResult {
9443
+ status: 'approved' | 'denied' | 'conditions' | 'escalated';
8103
9444
  /**
8104
- * The feature that was evaluated (e.g., 'auto_redirect', 'brand_consistency', 'iab_casinos_gambling')
9445
+ * Echoed from request. Lets the caller confirm the governance agent understood the commitment level.
8105
9446
  */
8106
- feature_id: string;
9447
+ binding: 'proposed' | 'committed';
8107
9448
  /**
8108
- * The feature value. Type depends on feature definition: boolean for binary, number for quantitative, string for categorical.
9449
+ * Echoed from request.
8109
9450
  */
8110
- value: boolean | number | string;
9451
+ plan_id: string;
8111
9452
  /**
8112
- * Unit of measurement for quantitative values (e.g., 'percentage', 'score')
9453
+ * Echoed from request.
8113
9454
  */
8114
- unit?: string;
9455
+ buyer_campaign_ref: string;
8115
9456
  /**
8116
- * Confidence score for this value (0-1)
9457
+ * Human-readable explanation of the governance decision.
8117
9458
  */
8118
- confidence?: number;
9459
+ explanation: string;
9460
+ mode?: GovernanceMode;
8119
9461
  /**
8120
- * When this feature was evaluated
9462
+ * Specific issues found during the governance check. Present when status is 'denied', 'conditions', or 'escalated'. MAY also be present on 'approved' for advisory findings (e.g., budget approaching limit).
8121
9463
  */
8122
- measured_at?: string;
9464
+ findings?: {
9465
+ /**
9466
+ * Validation category that flagged the issue (e.g., 'budget_compliance', 'regulatory_compliance', 'brand_safety').
9467
+ */
9468
+ category_id: string;
9469
+ /**
9470
+ * Registry policy ID that triggered this finding. Present when the finding originates from a specific registry policy. Enables programmatic routing of compliance failures.
9471
+ */
9472
+ policy_id?: string;
9473
+ severity: EscalationSeverity;
9474
+ /**
9475
+ * Human-readable description of the issue.
9476
+ */
9477
+ explanation: string;
9478
+ /**
9479
+ * Structured details for programmatic consumption.
9480
+ */
9481
+ details?: {};
9482
+ /**
9483
+ * Confidence score (0-1) in this finding. Distinguishes 'this definitely violates the policy' (0.95) from 'this might violate depending on how audience segments resolve' (0.6). When absent, the finding is presented without a confidence qualifier.
9484
+ */
9485
+ confidence?: number;
9486
+ /**
9487
+ * Explanation of why confidence is below 1.0 (e.g., 'Targeting includes regions that partially overlap jurisdiction boundaries'). Present when confidence is below a governance-agent-defined threshold.
9488
+ */
9489
+ uncertainty_reason?: string;
9490
+ }[];
8123
9491
  /**
8124
- * When this evaluation expires and should be refreshed
9492
+ * Present when status is 'conditions'. Specific adjustments the caller must make. After applying conditions, the caller MUST re-call check_governance with the adjusted parameters before proceeding.
9493
+ */
9494
+ conditions?: {
9495
+ /**
9496
+ * Dot-path to the field that needs adjustment (in payload for proposed, in planned_delivery for committed).
9497
+ */
9498
+ field: string;
9499
+ /**
9500
+ * The value the field must have for approval. When present, the condition is machine-actionable. When absent, the condition is advisory.
9501
+ */
9502
+ required_value?: {
9503
+ [k: string]: unknown | undefined;
9504
+ };
9505
+ /**
9506
+ * Why this condition is required.
9507
+ */
9508
+ reason: string;
9509
+ }[];
9510
+ /**
9511
+ * Present when status is 'escalated'. The action is halted pending human review.
9512
+ */
9513
+ escalation?: {
9514
+ /**
9515
+ * Human-readable explanation of why the action was escalated.
9516
+ */
9517
+ reason: string;
9518
+ severity: EscalationSeverity;
9519
+ /**
9520
+ * Whether human approval is required before proceeding.
9521
+ */
9522
+ requires_human: boolean;
9523
+ /**
9524
+ * Organizational role or tier required to resolve this escalation. The value is organization-defined; the governance agent infers the tier from the escalation context. Common values include 'manager', 'director', 'legal', 'cfo'. Enables programmatic routing of escalations to the right person.
9525
+ */
9526
+ approval_tier?: string;
9527
+ };
9528
+ /**
9529
+ * When this approval expires. Present when status is 'approved' or 'conditions'. The caller must act before this time or re-call check_governance. A lapsed approval is no approval.
8125
9530
  */
8126
9531
  expires_at?: string;
8127
9532
  /**
8128
- * Version of the methodology used to evaluate this feature
9533
+ * When the seller should next call check_governance with delivery metrics. Present when the governance agent expects ongoing delivery reporting.
8129
9534
  */
8130
- methodology_version?: string;
9535
+ next_check?: string;
8131
9536
  /**
8132
- * Additional vendor-specific details about this evaluation
9537
+ * Governance categories evaluated during this check.
8133
9538
  */
8134
- details?: {};
8135
- ext?: ExtensionObject;
9539
+ categories_evaluated?: string[];
9540
+ /**
9541
+ * Registry policy IDs evaluated during this check.
9542
+ */
9543
+ policies_evaluated?: string[];
8136
9544
  }
8137
9545
  /**
8138
9546
  * Get offering details and availability before session handoff. Returns offering information, availability status, and optionally matching products based on context.
@@ -8754,7 +10162,7 @@ export interface GetAdCPCapabilitiesResponse {
8754
10162
  /**
8755
10163
  * Which AdCP domain protocols this seller supports
8756
10164
  */
8757
- supported_protocols: ('media_buy' | 'signals' | 'governance' | 'sponsored_intelligence' | 'creative')[];
10165
+ supported_protocols: ('media_buy' | 'signals' | 'governance' | 'sponsored_intelligence' | 'creative' | 'brand')[];
8758
10166
  /**
8759
10167
  * Account management capabilities. Describes how accounts are established, what billing models are supported, and whether an account is required before browsing products.
8760
10168
  */
@@ -9224,6 +10632,35 @@ export interface GetAdCPCapabilitiesResponse {
9224
10632
  */
9225
10633
  brand_url?: string;
9226
10634
  };
10635
+ /**
10636
+ * Brand protocol capabilities. Only present if brand is in supported_protocols. Brand agents provide identity data (logos, colors, tone, assets) and optionally rights clearance for licensable content (talent, music, stock media).
10637
+ */
10638
+ brand?: {
10639
+ /**
10640
+ * Supports get_brand_identity for retrieving brand identity data
10641
+ */
10642
+ identity?: boolean;
10643
+ /**
10644
+ * Supports get_rights and acquire_rights for rights discovery and clearance
10645
+ */
10646
+ rights?: boolean;
10647
+ /**
10648
+ * Types of rights available through this agent
10649
+ */
10650
+ right_types?: RightType[];
10651
+ /**
10652
+ * Rights uses available across this agent's roster
10653
+ */
10654
+ available_uses?: RightUse[];
10655
+ /**
10656
+ * LLM/generation providers this agent can issue credentials for
10657
+ */
10658
+ generation_providers?: string[];
10659
+ /**
10660
+ * Description of the agent's brand protocol capabilities
10661
+ */
10662
+ description?: string;
10663
+ };
9227
10664
  /**
9228
10665
  * Creative protocol capabilities. Only present if creative is in supported_protocols.
9229
10666
  */
@@ -9319,6 +10756,32 @@ export interface SyncAccountsRequest {
9319
10756
  * When true, provision this as a sandbox account with no real platform calls or billing. Only applicable to implicit accounts (require_operator_auth: false). For explicit accounts, sandbox accounts are pre-existing test accounts discovered via list_accounts.
9320
10757
  */
9321
10758
  sandbox?: boolean;
10759
+ /**
10760
+ * Governance agent endpoints for this account. When present, the seller MUST call these agents for governance approval before confirming media buy requests. Each agent can be scoped to specific validation categories. The seller routes check_governance calls to the appropriate agent based on the action being validated. All applicable agents must approve for the action to proceed (unanimous approval).
10761
+ */
10762
+ governance_agents?: {
10763
+ /**
10764
+ * Governance agent endpoint URL.
10765
+ */
10766
+ url: string;
10767
+ /**
10768
+ * Authentication the seller presents when calling this governance agent.
10769
+ */
10770
+ authentication: {
10771
+ /**
10772
+ * @maxItems 1
10773
+ */
10774
+ schemes: [] | [AuthenticationScheme];
10775
+ /**
10776
+ * Authentication credential (e.g., Bearer token).
10777
+ */
10778
+ credentials: string;
10779
+ };
10780
+ /**
10781
+ * Governance categories this agent handles (e.g., ['budget_authority', 'strategic_alignment']). When omitted, the agent handles all categories.
10782
+ */
10783
+ categories?: string[];
10784
+ }[];
9322
10785
  }[];
9323
10786
  /**
9324
10787
  * When true, accounts previously synced by this agent but not included in this request will be deactivated. Scoped to the authenticated agent — does not affect accounts managed by other agents. Use with caution.
@@ -9475,6 +10938,10 @@ export interface ReportUsageRequest {
9475
10938
  * Content standards configuration identifier. Required for governance agents.
9476
10939
  */
9477
10940
  standards_id?: string;
10941
+ /**
10942
+ * Rights grant identifier from acquire_rights. Required for brand/rights agents. Links usage records to specific rights grants for cap tracking, billing verification, and overage calculation.
10943
+ */
10944
+ rights_id?: string;
9478
10945
  }[];
9479
10946
  context?: ContextObject;
9480
10947
  ext?: ExtensionObject;