@adcp/client 0.4.2 → 2.0.2

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 (35) hide show
  1. package/dist/lib/core/ADCPClient.d.ts +34 -1
  2. package/dist/lib/core/ADCPClient.d.ts.map +1 -1
  3. package/dist/lib/core/ADCPClient.js +46 -0
  4. package/dist/lib/core/ADCPClient.js.map +1 -1
  5. package/dist/lib/core/ADCPMultiAgentClient.d.ts +78 -0
  6. package/dist/lib/core/ADCPMultiAgentClient.d.ts.map +1 -1
  7. package/dist/lib/core/ADCPMultiAgentClient.js +99 -0
  8. package/dist/lib/core/ADCPMultiAgentClient.js.map +1 -1
  9. package/dist/lib/core/CreativeAgentClient.d.ts +148 -0
  10. package/dist/lib/core/CreativeAgentClient.d.ts.map +1 -0
  11. package/dist/lib/core/CreativeAgentClient.js +162 -0
  12. package/dist/lib/core/CreativeAgentClient.js.map +1 -0
  13. package/dist/lib/core/TaskExecutor.d.ts.map +1 -1
  14. package/dist/lib/core/TaskExecutor.js +2 -1
  15. package/dist/lib/core/TaskExecutor.js.map +1 -1
  16. package/dist/lib/index.d.ts +2 -1
  17. package/dist/lib/index.d.ts.map +1 -1
  18. package/dist/lib/index.js +5 -1
  19. package/dist/lib/index.js.map +1 -1
  20. package/dist/lib/types/adcp.d.ts +4 -3
  21. package/dist/lib/types/adcp.d.ts.map +1 -1
  22. package/dist/lib/types/core.generated.d.ts +700 -136
  23. package/dist/lib/types/core.generated.d.ts.map +1 -1
  24. package/dist/lib/types/core.generated.js +2 -2
  25. package/dist/lib/types/index.d.ts +1 -0
  26. package/dist/lib/types/index.d.ts.map +1 -1
  27. package/dist/lib/types/tools.generated.d.ts +1629 -525
  28. package/dist/lib/types/tools.generated.d.ts.map +1 -1
  29. package/dist/lib/types/tools.generated.js.map +1 -1
  30. package/dist/lib/utils/index.d.ts.map +1 -1
  31. package/dist/lib/utils/index.js +16 -4
  32. package/dist/lib/utils/index.js.map +1 -1
  33. package/dist/lib/version.d.ts +5 -5
  34. package/dist/lib/version.js +5 -5
  35. package/package.json +6 -2
@@ -1,3 +1,14 @@
1
+ /**
2
+ * Brand information manifest providing brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest.
3
+ */
4
+ export type BrandManifestReference = BrandManifest | string;
5
+ /**
6
+ * Inline brand manifest object
7
+ */
8
+ export type BrandManifest = BrandManifest1 & BrandManifest2;
9
+ export type BrandManifest1 = {
10
+ [k: string]: unknown;
11
+ };
1
12
  /**
2
13
  * Type of inventory delivery
3
14
  */
@@ -6,18 +17,11 @@ export type DeliveryType = 'guaranteed' | 'non_guaranteed';
6
17
  * Request parameters for discovering available advertising products
7
18
  */
8
19
  export interface GetProductsRequest {
9
- /**
10
- * AdCP schema version for this request
11
- */
12
- adcp_version?: string;
13
20
  /**
14
21
  * Natural language description of campaign requirements
15
22
  */
16
23
  brief?: string;
17
- /**
18
- * Description of advertiser and what is being promoted
19
- */
20
- promoted_offering: string;
24
+ brand_manifest: BrandManifestReference;
21
25
  /**
22
26
  * Structured filters for product discovery
23
27
  */
@@ -34,17 +38,246 @@ export interface GetProductsRequest {
34
38
  /**
35
39
  * Filter by specific format IDs
36
40
  */
37
- format_ids?: string[];
41
+ format_ids?: FormatID[];
38
42
  /**
39
43
  * Only return products accepting IAB standard formats
40
44
  */
41
45
  standard_formats_only?: boolean;
46
+ /**
47
+ * Minimum exposures/impressions needed for measurement validity
48
+ */
49
+ min_exposures?: number;
50
+ };
51
+ }
52
+ export interface BrandManifest2 {
53
+ /**
54
+ * Primary brand URL for context and asset discovery. Creative agents can infer brand information from this URL.
55
+ */
56
+ url?: string;
57
+ /**
58
+ * Brand or business name
59
+ */
60
+ name?: string;
61
+ /**
62
+ * Brand logo assets with semantic tags for different use cases
63
+ */
64
+ logos?: {
65
+ /**
66
+ * URL to the logo asset
67
+ */
68
+ url: string;
69
+ /**
70
+ * Semantic tags describing the logo variant (e.g., 'dark', 'light', 'square', 'horizontal', 'icon')
71
+ */
72
+ tags?: string[];
73
+ /**
74
+ * Logo width in pixels
75
+ */
76
+ width?: number;
77
+ /**
78
+ * Logo height in pixels
79
+ */
80
+ height?: number;
81
+ }[];
82
+ /**
83
+ * Brand color palette
84
+ */
85
+ colors?: {
86
+ /**
87
+ * Primary brand color (hex format)
88
+ */
89
+ primary?: string;
90
+ /**
91
+ * Secondary brand color (hex format)
92
+ */
93
+ secondary?: string;
94
+ /**
95
+ * Accent color (hex format)
96
+ */
97
+ accent?: string;
98
+ /**
99
+ * Background color (hex format)
100
+ */
101
+ background?: string;
102
+ /**
103
+ * Text color (hex format)
104
+ */
105
+ text?: string;
106
+ };
107
+ /**
108
+ * Brand typography guidelines
109
+ */
110
+ fonts?: {
111
+ /**
112
+ * Primary font family name
113
+ */
114
+ primary?: string;
115
+ /**
116
+ * Secondary font family name
117
+ */
118
+ secondary?: string;
119
+ /**
120
+ * URLs to web font files if using custom fonts
121
+ */
122
+ font_urls?: string[];
123
+ };
124
+ /**
125
+ * Brand voice and messaging tone (e.g., 'professional', 'casual', 'humorous', 'trustworthy', 'innovative')
126
+ */
127
+ tone?: string;
128
+ /**
129
+ * Brand tagline or slogan
130
+ */
131
+ tagline?: string;
132
+ /**
133
+ * Brand asset library with explicit assets and tags. Assets are referenced inline with URLs pointing to CDN-hosted files.
134
+ */
135
+ assets?: {
136
+ /**
137
+ * Unique identifier for this asset
138
+ */
139
+ asset_id: string;
140
+ /**
141
+ * Type of asset
142
+ */
143
+ asset_type: 'image' | 'video' | 'audio' | 'text';
144
+ /**
145
+ * URL to CDN-hosted asset file
146
+ */
147
+ url: string;
148
+ /**
149
+ * Tags for asset discovery (e.g., 'holiday', 'lifestyle', 'product_shot')
150
+ */
151
+ tags?: string[];
152
+ /**
153
+ * Human-readable asset name
154
+ */
155
+ name?: string;
156
+ /**
157
+ * Asset description or usage notes
158
+ */
159
+ description?: string;
160
+ /**
161
+ * Image/video width in pixels
162
+ */
163
+ width?: number;
164
+ /**
165
+ * Image/video height in pixels
166
+ */
167
+ height?: number;
168
+ /**
169
+ * Video/audio duration in seconds
170
+ */
171
+ duration_seconds?: number;
172
+ /**
173
+ * File size in bytes
174
+ */
175
+ file_size_bytes?: number;
176
+ /**
177
+ * File format (e.g., 'jpg', 'mp4', 'mp3')
178
+ */
179
+ format?: string;
180
+ /**
181
+ * Additional asset-specific metadata
182
+ */
183
+ metadata?: {
184
+ [k: string]: unknown;
185
+ };
186
+ }[];
187
+ /**
188
+ * Product catalog information for e-commerce advertisers. Enables SKU-level creative generation and product selection.
189
+ */
190
+ product_catalog?: {
191
+ /**
192
+ * URL to product catalog feed
193
+ */
194
+ feed_url: string;
195
+ /**
196
+ * Format of the product feed
197
+ */
198
+ feed_format?: 'google_merchant_center' | 'facebook_catalog' | 'custom';
199
+ /**
200
+ * Product categories available in the catalog (for filtering)
201
+ */
202
+ categories?: string[];
203
+ /**
204
+ * When the product catalog was last updated
205
+ */
206
+ last_updated?: string;
207
+ /**
208
+ * How frequently the product catalog is updated
209
+ */
210
+ update_frequency?: 'realtime' | 'hourly' | 'daily' | 'weekly';
211
+ };
212
+ /**
213
+ * Legal disclaimers or required text that must appear in creatives
214
+ */
215
+ disclaimers?: {
216
+ /**
217
+ * Disclaimer text
218
+ */
219
+ text: string;
220
+ /**
221
+ * When this disclaimer applies (e.g., 'financial_products', 'health_claims', 'all')
222
+ */
223
+ context?: string;
224
+ /**
225
+ * Whether this disclaimer must appear
226
+ */
227
+ required?: boolean;
228
+ }[];
229
+ /**
230
+ * Industry or vertical (e.g., 'retail', 'automotive', 'finance', 'healthcare')
231
+ */
232
+ industry?: string;
233
+ /**
234
+ * Primary target audience description
235
+ */
236
+ target_audience?: string;
237
+ /**
238
+ * Brand contact information
239
+ */
240
+ contact?: {
241
+ /**
242
+ * Contact email
243
+ */
244
+ email?: string;
245
+ /**
246
+ * Contact phone number
247
+ */
248
+ phone?: string;
249
+ };
250
+ /**
251
+ * Additional brand metadata
252
+ */
253
+ metadata?: {
254
+ /**
255
+ * When this brand manifest was created
256
+ */
257
+ created_date?: string;
258
+ /**
259
+ * When this brand manifest was last updated
260
+ */
261
+ updated_date?: string;
262
+ /**
263
+ * Brand card version number
264
+ */
265
+ version?: string;
42
266
  };
43
267
  }
44
268
  /**
45
- * Current task state
269
+ * Structured format identifier with agent URL and format name
46
270
  */
47
- export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required' | 'unknown';
271
+ export interface FormatID {
272
+ /**
273
+ * URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)
274
+ */
275
+ agent_url: string;
276
+ /**
277
+ * Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')
278
+ */
279
+ id: string;
280
+ }
48
281
  /**
49
282
  * Represents available advertising inventory
50
283
  */
@@ -56,6 +289,7 @@ export type PropertyIdentifierTypes = 'domain' | 'subdomain' | 'network_id' | 'i
56
289
  /**
57
290
  * Type of inventory delivery
58
291
  */
292
+ export type PricingOption = CPMFixedRatePricingOption | CPMAuctionPricingOption | VCPMFixedRatePricingOption | VCPMAuctionPricingOption | CPCPricingOption | CPCVPricingOption | CPVPricingOption | CPPPricingOption | FlatRatePricingOption;
59
293
  export type Product2 = {
60
294
  [k: string]: unknown;
61
295
  } | {
@@ -65,11 +299,6 @@ export type Product2 = {
65
299
  * Response payload for get_products task
66
300
  */
67
301
  export interface GetProductsResponse {
68
- /**
69
- * AdCP schema version used for this response
70
- */
71
- adcp_version: string;
72
- status?: TaskStatus;
73
302
  /**
74
303
  * Array of matching products
75
304
  */
@@ -105,399 +334,1277 @@ export interface Product1 {
105
334
  */
106
335
  property_tags?: [string, ...string[]];
107
336
  /**
108
- * Array of supported creative format IDs - use list_creative_formats to get full format details
337
+ * Array of supported creative format IDs - structured format_id objects with agent_url and id
109
338
  */
110
- format_ids: string[];
339
+ format_ids: FormatID[];
111
340
  delivery_type: DeliveryType;
112
341
  /**
113
- * Whether this product has fixed pricing (true) or uses auction (false)
342
+ * Available pricing models for this product
343
+ *
344
+ * @minItems 1
345
+ */
346
+ pricing_options: [PricingOption, ...PricingOption[]];
347
+ /**
348
+ * Estimated exposures/impressions for guaranteed products
349
+ */
350
+ estimated_exposures?: number;
351
+ measurement?: Measurement;
352
+ /**
353
+ * 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.
354
+ */
355
+ delivery_measurement: {
356
+ /**
357
+ * Measurement provider(s) used for this product (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions')
358
+ */
359
+ provider: string;
360
+ /**
361
+ * Additional details about measurement methodology in plain language (e.g., 'MRC-accredited viewability. 50% in-view for 1s display / 2s video', 'Panel-based demographic measurement updated monthly')
362
+ */
363
+ notes?: string;
364
+ };
365
+ reporting_capabilities?: ReportingCapabilities;
366
+ creative_policy?: CreativePolicy;
367
+ /**
368
+ * Whether this is a custom product
369
+ */
370
+ is_custom?: boolean;
371
+ /**
372
+ * Explanation of why this product matches the brief (only included when brief is provided)
373
+ */
374
+ brief_relevance?: string;
375
+ /**
376
+ * Expiration timestamp for custom products
377
+ */
378
+ expires_at?: string;
379
+ }
380
+ /**
381
+ * An advertising property that can be validated via adagents.json
382
+ */
383
+ export interface Property {
384
+ /**
385
+ * Type of advertising property
386
+ */
387
+ property_type: 'website' | 'mobile_app' | 'ctv_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio';
388
+ /**
389
+ * Human-readable property name
390
+ */
391
+ name: string;
392
+ /**
393
+ * Array of identifiers for this property
394
+ *
395
+ * @minItems 1
396
+ */
397
+ identifiers: [
398
+ {
399
+ type: PropertyIdentifierTypes;
400
+ /**
401
+ * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
402
+ */
403
+ value: string;
404
+ },
405
+ ...{
406
+ type: PropertyIdentifierTypes;
407
+ /**
408
+ * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
409
+ */
410
+ value: string;
411
+ }[]
412
+ ];
413
+ /**
414
+ * Tags for categorization and grouping (e.g., network membership, content categories)
415
+ */
416
+ tags?: string[];
417
+ /**
418
+ * Domain where adagents.json should be checked for authorization validation
419
+ */
420
+ publisher_domain: string;
421
+ }
422
+ /**
423
+ * Structured format identifier with agent URL and format name
424
+ */
425
+ export interface CPMFixedRatePricingOption {
426
+ /**
427
+ * Unique identifier for this pricing option within the product (e.g., 'cpm_usd_guaranteed')
428
+ */
429
+ pricing_option_id: string;
430
+ /**
431
+ * Cost per 1,000 impressions
432
+ */
433
+ pricing_model: 'cpm';
434
+ /**
435
+ * Fixed CPM rate (cost per 1,000 impressions)
436
+ */
437
+ rate: number;
438
+ /**
439
+ * ISO 4217 currency code
440
+ */
441
+ currency: string;
442
+ /**
443
+ * Minimum spend requirement per package using this pricing option, in the specified currency
444
+ */
445
+ min_spend_per_package?: number;
446
+ }
447
+ /**
448
+ * Cost Per Mille (cost per 1,000 impressions) with auction-based pricing - common for programmatic/non-guaranteed inventory
449
+ */
450
+ export interface CPMAuctionPricingOption {
451
+ /**
452
+ * Unique identifier for this pricing option within the product (e.g., 'cpm_usd_auction')
453
+ */
454
+ pricing_option_id: string;
455
+ /**
456
+ * Cost per 1,000 impressions
457
+ */
458
+ pricing_model: 'cpm';
459
+ /**
460
+ * ISO 4217 currency code
461
+ */
462
+ currency: string;
463
+ /**
464
+ * Pricing guidance for auction-based CPM bidding
465
+ */
466
+ price_guidance: {
467
+ /**
468
+ * Minimum bid price - publisher will reject bids under this value
469
+ */
470
+ floor: number;
471
+ /**
472
+ * 25th percentile winning price
473
+ */
474
+ p25?: number;
475
+ /**
476
+ * Median winning price
477
+ */
478
+ p50?: number;
479
+ /**
480
+ * 75th percentile winning price
481
+ */
482
+ p75?: number;
483
+ /**
484
+ * 90th percentile winning price
485
+ */
486
+ p90?: number;
487
+ };
488
+ /**
489
+ * Minimum spend requirement per package using this pricing option, in the specified currency
490
+ */
491
+ min_spend_per_package?: number;
492
+ }
493
+ /**
494
+ * Viewable Cost Per Mille (cost per 1,000 viewable impressions) with guaranteed fixed rate - impressions meeting MRC viewability standard (50% pixels in-view for 1 second for display, 2 seconds for video)
495
+ */
496
+ export interface VCPMFixedRatePricingOption {
497
+ /**
498
+ * Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_guaranteed')
499
+ */
500
+ pricing_option_id: string;
501
+ /**
502
+ * Cost per 1,000 viewable impressions (MRC standard)
503
+ */
504
+ pricing_model: 'vcpm';
505
+ /**
506
+ * Fixed vCPM rate (cost per 1,000 viewable impressions)
114
507
  */
115
- is_fixed_price: boolean;
508
+ rate: number;
509
+ /**
510
+ * ISO 4217 currency code
511
+ */
512
+ currency: string;
513
+ /**
514
+ * Minimum spend requirement per package using this pricing option, in the specified currency
515
+ */
516
+ min_spend_per_package?: number;
517
+ }
518
+ /**
519
+ * Viewable Cost Per Mille (cost per 1,000 viewable impressions) with auction-based pricing - impressions meeting MRC viewability standard (50% pixels in-view for 1 second for display, 2 seconds for video)
520
+ */
521
+ export interface VCPMAuctionPricingOption {
522
+ /**
523
+ * Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_auction')
524
+ */
525
+ pricing_option_id: string;
526
+ /**
527
+ * Cost per 1,000 viewable impressions (MRC standard)
528
+ */
529
+ pricing_model: 'vcpm';
530
+ /**
531
+ * ISO 4217 currency code
532
+ */
533
+ currency: string;
534
+ /**
535
+ * Statistical guidance for auction pricing
536
+ */
537
+ price_guidance: {
538
+ /**
539
+ * Minimum acceptable bid price
540
+ */
541
+ floor: number;
542
+ /**
543
+ * 25th percentile of recent winning bids
544
+ */
545
+ p25?: number;
546
+ /**
547
+ * Median of recent winning bids
548
+ */
549
+ p50?: number;
550
+ /**
551
+ * 75th percentile of recent winning bids
552
+ */
553
+ p75?: number;
554
+ /**
555
+ * 90th percentile of recent winning bids
556
+ */
557
+ p90?: number;
558
+ };
559
+ /**
560
+ * Minimum spend requirement per package using this pricing option, in the specified currency
561
+ */
562
+ min_spend_per_package?: number;
563
+ }
564
+ /**
565
+ * Cost Per Click fixed-rate pricing for performance-driven advertising campaigns
566
+ */
567
+ export interface CPCPricingOption {
568
+ /**
569
+ * Unique identifier for this pricing option within the product (e.g., 'cpc_usd_fixed')
570
+ */
571
+ pricing_option_id: string;
572
+ /**
573
+ * Cost per click
574
+ */
575
+ pricing_model: 'cpc';
576
+ /**
577
+ * Fixed CPC rate (cost per click)
578
+ */
579
+ rate: number;
580
+ /**
581
+ * ISO 4217 currency code
582
+ */
583
+ currency: string;
584
+ /**
585
+ * Minimum spend requirement per package using this pricing option, in the specified currency
586
+ */
587
+ min_spend_per_package?: number;
588
+ }
589
+ /**
590
+ * Cost Per Completed View (100% video/audio completion) fixed-rate pricing
591
+ */
592
+ export interface CPCVPricingOption {
593
+ /**
594
+ * Unique identifier for this pricing option within the product (e.g., 'cpcv_usd_guaranteed')
595
+ */
596
+ pricing_option_id: string;
597
+ /**
598
+ * Cost per completed view (100% completion)
599
+ */
600
+ pricing_model: 'cpcv';
601
+ /**
602
+ * Fixed CPCV rate (cost per 100% completion)
603
+ */
604
+ rate: number;
605
+ /**
606
+ * ISO 4217 currency code
607
+ */
608
+ currency: string;
609
+ /**
610
+ * Minimum spend requirement per package using this pricing option, in the specified currency
611
+ */
612
+ min_spend_per_package?: number;
613
+ }
614
+ /**
615
+ * Cost Per View (at publisher-defined threshold) fixed-rate pricing for video/audio
616
+ */
617
+ export interface CPVPricingOption {
618
+ /**
619
+ * Unique identifier for this pricing option within the product (e.g., 'cpv_usd_50pct')
620
+ */
621
+ pricing_option_id: string;
622
+ /**
623
+ * Cost per view at threshold
624
+ */
625
+ pricing_model: 'cpv';
626
+ /**
627
+ * Fixed CPV rate (cost per view)
628
+ */
629
+ rate: number;
630
+ /**
631
+ * ISO 4217 currency code
632
+ */
633
+ currency: string;
634
+ /**
635
+ * CPV-specific parameters defining the view threshold
636
+ */
637
+ parameters: {
638
+ view_threshold: number | {
639
+ /**
640
+ * Seconds of viewing required (e.g., 30 for YouTube-style '30 seconds = view')
641
+ */
642
+ duration_seconds: number;
643
+ };
644
+ };
645
+ /**
646
+ * Minimum spend requirement per package using this pricing option, in the specified currency
647
+ */
648
+ min_spend_per_package?: number;
649
+ }
650
+ /**
651
+ * Cost Per Point (Gross Rating Point) fixed-rate pricing for TV and audio campaigns requiring demographic measurement
652
+ */
653
+ export interface CPPPricingOption {
654
+ /**
655
+ * Unique identifier for this pricing option within the product (e.g., 'cpp_usd_p18-49')
656
+ */
657
+ pricing_option_id: string;
658
+ /**
659
+ * Cost per Gross Rating Point
660
+ */
661
+ pricing_model: 'cpp';
662
+ /**
663
+ * Fixed CPP rate (cost per rating point)
664
+ */
665
+ rate: number;
666
+ /**
667
+ * ISO 4217 currency code
668
+ */
669
+ currency: string;
670
+ /**
671
+ * CPP-specific parameters for demographic targeting and GRP requirements
672
+ */
673
+ parameters: {
674
+ /**
675
+ * Target demographic in Nielsen format: P/M/W/A/C + age range. Examples: P18-49 (Persons 18-49), M25-54 (Men 25-54), W35+ (Women 35+), A18-34 (Adults 18-34), C2-11 (Children 2-11)
676
+ */
677
+ demographic: string;
678
+ /**
679
+ * Minimum GRPs/TRPs required for this pricing option
680
+ */
681
+ min_points?: number;
682
+ };
683
+ /**
684
+ * Minimum spend requirement per package using this pricing option, in the specified currency
685
+ */
686
+ min_spend_per_package?: number;
687
+ }
688
+ /**
689
+ * Flat rate pricing for DOOH, sponsorships, and time-based campaigns - fixed cost regardless of delivery volume
690
+ */
691
+ export interface FlatRatePricingOption {
692
+ /**
693
+ * Unique identifier for this pricing option within the product (e.g., 'flat_rate_usd_24h_takeover')
694
+ */
695
+ pricing_option_id: string;
696
+ /**
697
+ * Fixed cost regardless of delivery volume
698
+ */
699
+ pricing_model: 'flat_rate';
700
+ /**
701
+ * Flat rate cost
702
+ */
703
+ rate: number;
704
+ /**
705
+ * ISO 4217 currency code
706
+ */
707
+ currency: string;
708
+ /**
709
+ * Whether this is a fixed rate (true) or auction-based (false)
710
+ */
711
+ is_fixed: true;
712
+ /**
713
+ * Flat rate parameters for DOOH and time-based campaigns
714
+ */
715
+ parameters?: {
716
+ /**
717
+ * Duration in hours for time-based flat rate pricing (DOOH)
718
+ */
719
+ duration_hours?: number;
720
+ /**
721
+ * Guaranteed share of voice as percentage (DOOH, 0-100)
722
+ */
723
+ sov_percentage?: number;
724
+ /**
725
+ * Duration of ad loop rotation in seconds (DOOH)
726
+ */
727
+ loop_duration_seconds?: number;
728
+ /**
729
+ * Minimum number of times ad plays per hour (DOOH frequency guarantee)
730
+ */
731
+ min_plays_per_hour?: number;
732
+ /**
733
+ * Named venue package identifier for DOOH (e.g., 'times_square_network', 'airport_terminals')
734
+ */
735
+ venue_package?: string;
736
+ /**
737
+ * Estimated impressions for this flat rate option (informational, commonly used with SOV or time-based DOOH)
738
+ */
739
+ estimated_impressions?: number;
740
+ /**
741
+ * Specific daypart for time-based pricing (e.g., 'morning_commute', 'evening_prime', 'overnight')
742
+ */
743
+ daypart?: string;
744
+ };
745
+ /**
746
+ * Minimum spend requirement per package using this pricing option, in the specified currency
747
+ */
748
+ min_spend_per_package?: number;
749
+ }
750
+ /**
751
+ * Measurement capabilities included with a product
752
+ */
753
+ export interface Measurement {
754
+ /**
755
+ * Type of measurement
756
+ */
757
+ type: string;
758
+ /**
759
+ * Attribution methodology
760
+ */
761
+ attribution: string;
762
+ /**
763
+ * Attribution window
764
+ */
765
+ window?: string;
766
+ /**
767
+ * Reporting frequency and format
768
+ */
769
+ reporting: string;
770
+ }
771
+ /**
772
+ * Reporting capabilities available for a product
773
+ */
774
+ export interface ReportingCapabilities {
775
+ /**
776
+ * Supported reporting frequency options
777
+ *
778
+ * @minItems 1
779
+ */
780
+ available_reporting_frequencies: ['hourly' | 'daily' | 'monthly', ...('hourly' | 'daily' | 'monthly')[]];
781
+ /**
782
+ * Expected delay in minutes before reporting data becomes available (e.g., 240 for 4-hour delay)
783
+ */
784
+ expected_delay_minutes: number;
785
+ /**
786
+ * Timezone for reporting periods. Use 'UTC' or IANA timezone (e.g., 'America/New_York'). Critical for daily/monthly frequency alignment.
787
+ */
788
+ timezone: string;
789
+ /**
790
+ * Whether this product supports webhook-based reporting notifications
791
+ */
792
+ supports_webhooks: boolean;
793
+ /**
794
+ * Metrics available in reporting. Impressions and spend are always implicitly included.
795
+ */
796
+ available_metrics: ('impressions' | 'spend' | 'clicks' | 'ctr' | 'video_completions' | 'completion_rate' | 'conversions' | 'viewability' | 'engagement_rate')[];
797
+ }
798
+ /**
799
+ * Creative requirements and restrictions for a product
800
+ */
801
+ export interface CreativePolicy {
802
+ /**
803
+ * Co-branding requirement
804
+ */
805
+ co_branding: 'required' | 'optional' | 'none';
806
+ /**
807
+ * Landing page requirements
808
+ */
809
+ landing_page: 'any' | 'retailer_site_only' | 'must_include_retailer';
810
+ /**
811
+ * Whether creative templates are provided
812
+ */
813
+ templates_available: boolean;
814
+ }
815
+ /**
816
+ * Standard error structure for task-specific errors and warnings
817
+ */
818
+ export interface Error {
819
+ /**
820
+ * Error code for programmatic handling
821
+ */
822
+ code: string;
823
+ /**
824
+ * Human-readable error message
825
+ */
826
+ message: string;
827
+ /**
828
+ * Field path associated with the error (e.g., 'packages[0].targeting')
829
+ */
830
+ field?: string;
831
+ /**
832
+ * Suggested fix for the error
833
+ */
834
+ suggestion?: string;
835
+ /**
836
+ * Seconds to wait before retrying the operation
837
+ */
838
+ retry_after?: number;
839
+ /**
840
+ * Additional task-specific error details
841
+ */
842
+ details?: {
843
+ [k: string]: unknown;
844
+ };
845
+ }
846
+ /**
847
+ * Request parameters for discovering supported creative formats
848
+ */
849
+ export interface ListCreativeFormatsRequest {
850
+ /**
851
+ * Return only these specific format IDs (e.g., from get_products response)
852
+ */
853
+ format_ids?: FormatID[];
854
+ /**
855
+ * Filter by format type (technical categories with distinct requirements)
856
+ */
857
+ type?: 'audio' | 'video' | 'display' | 'dooh';
858
+ /**
859
+ * Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.
860
+ */
861
+ asset_types?: ('image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url')[];
862
+ /**
863
+ * Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits.
864
+ */
865
+ max_width?: number;
866
+ /**
867
+ * Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits.
868
+ */
869
+ max_height?: number;
870
+ /**
871
+ * Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.
872
+ */
873
+ min_width?: number;
874
+ /**
875
+ * Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.
876
+ */
877
+ min_height?: number;
878
+ /**
879
+ * Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.
880
+ */
881
+ is_responsive?: boolean;
882
+ /**
883
+ * Search for formats by name (case-insensitive partial match)
884
+ */
885
+ name_search?: string;
886
+ }
887
+ /**
888
+ * Structured format identifier with agent URL and format name
889
+ */
890
+ /**
891
+ * Response payload for list_creative_formats task
892
+ */
893
+ export interface ListCreativeFormatsResponse {
894
+ /**
895
+ * Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field.
896
+ */
897
+ formats: Format[];
898
+ /**
899
+ * Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.
900
+ */
901
+ creative_agents?: {
902
+ /**
903
+ * Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats.
904
+ */
905
+ agent_url: string;
906
+ /**
907
+ * Human-readable name for the creative agent
908
+ */
909
+ agent_name?: string;
910
+ /**
911
+ * Capabilities this creative agent provides
912
+ */
913
+ capabilities?: ('validation' | 'assembly' | 'generation' | 'preview')[];
914
+ }[];
915
+ /**
916
+ * Task-specific errors and warnings (e.g., format availability issues)
917
+ */
918
+ errors?: Error[];
919
+ }
920
+ /**
921
+ * Represents a creative format with its requirements
922
+ */
923
+ export interface Format {
924
+ format_id: FormatID;
925
+ /**
926
+ * Human-readable format name
927
+ */
928
+ name: string;
929
+ /**
930
+ * Plain text explanation of what this format does and what assets it requires
931
+ */
932
+ description?: string;
933
+ /**
934
+ * Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers.
935
+ */
936
+ preview_image?: string;
937
+ /**
938
+ * Optional URL to showcase page with examples and interactive demos of this format
939
+ */
940
+ example_url?: string;
941
+ /**
942
+ * Media type of this format - determines rendering method and asset requirements
943
+ */
944
+ type: 'audio' | 'video' | 'display' | 'native' | 'dooh' | 'rich_media' | 'universal';
945
+ /**
946
+ * Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.
947
+ *
948
+ * @minItems 1
949
+ */
950
+ renders?: [
951
+ {
952
+ /**
953
+ * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
954
+ */
955
+ role: string;
956
+ /**
957
+ * Dimensions for this rendered piece
958
+ */
959
+ dimensions: {
960
+ /**
961
+ * Fixed width in specified units
962
+ */
963
+ width?: number;
964
+ /**
965
+ * Fixed height in specified units
966
+ */
967
+ height?: number;
968
+ /**
969
+ * Minimum width for responsive renders
970
+ */
971
+ min_width?: number;
972
+ /**
973
+ * Minimum height for responsive renders
974
+ */
975
+ min_height?: number;
976
+ /**
977
+ * Maximum width for responsive renders
978
+ */
979
+ max_width?: number;
980
+ /**
981
+ * Maximum height for responsive renders
982
+ */
983
+ max_height?: number;
984
+ /**
985
+ * Indicates which dimensions are responsive/fluid
986
+ */
987
+ responsive?: {
988
+ width: boolean;
989
+ height: boolean;
990
+ };
991
+ /**
992
+ * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')
993
+ */
994
+ aspect_ratio?: string;
995
+ /**
996
+ * Unit of measurement for dimensions
997
+ */
998
+ unit: 'px' | 'dp' | 'inches' | 'cm';
999
+ };
1000
+ },
1001
+ ...{
1002
+ /**
1003
+ * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
1004
+ */
1005
+ role: string;
1006
+ /**
1007
+ * Dimensions for this rendered piece
1008
+ */
1009
+ dimensions: {
1010
+ /**
1011
+ * Fixed width in specified units
1012
+ */
1013
+ width?: number;
1014
+ /**
1015
+ * Fixed height in specified units
1016
+ */
1017
+ height?: number;
1018
+ /**
1019
+ * Minimum width for responsive renders
1020
+ */
1021
+ min_width?: number;
1022
+ /**
1023
+ * Minimum height for responsive renders
1024
+ */
1025
+ min_height?: number;
1026
+ /**
1027
+ * Maximum width for responsive renders
1028
+ */
1029
+ max_width?: number;
1030
+ /**
1031
+ * Maximum height for responsive renders
1032
+ */
1033
+ max_height?: number;
1034
+ /**
1035
+ * Indicates which dimensions are responsive/fluid
1036
+ */
1037
+ responsive?: {
1038
+ width: boolean;
1039
+ height: boolean;
1040
+ };
1041
+ /**
1042
+ * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')
1043
+ */
1044
+ aspect_ratio?: string;
1045
+ /**
1046
+ * Unit of measurement for dimensions
1047
+ */
1048
+ unit: 'px' | 'dp' | 'inches' | 'cm';
1049
+ };
1050
+ }[]
1051
+ ];
1052
+ /**
1053
+ * Array of required assets or asset groups for this format. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).
1054
+ */
1055
+ assets_required?: ({
1056
+ /**
1057
+ * Identifier for this asset in the format
1058
+ */
1059
+ asset_id: string;
1060
+ /**
1061
+ * Type of asset
1062
+ */
1063
+ asset_type: 'image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url' | 'brand_manifest';
1064
+ /**
1065
+ * Purpose of this asset (e.g., 'hero_image', 'logo', 'headline', 'cta_button')
1066
+ */
1067
+ asset_role?: string;
1068
+ /**
1069
+ * Whether this asset is required
1070
+ */
1071
+ required?: boolean;
1072
+ /**
1073
+ * Technical requirements for this asset (dimensions, file size, duration, etc.)
1074
+ */
1075
+ requirements?: {
1076
+ [k: string]: unknown;
1077
+ };
1078
+ } | {
1079
+ /**
1080
+ * Identifier for this asset group (e.g., 'product', 'slide', 'card')
1081
+ */
1082
+ asset_group_id: string;
1083
+ /**
1084
+ * Indicates this is a repeatable asset group
1085
+ */
1086
+ repeatable: true;
1087
+ /**
1088
+ * Minimum number of repetitions required
1089
+ */
1090
+ min_count: number;
1091
+ /**
1092
+ * Maximum number of repetitions allowed
1093
+ */
1094
+ max_count: number;
1095
+ /**
1096
+ * Assets within each repetition of this group
1097
+ */
1098
+ assets: {
1099
+ /**
1100
+ * Identifier for this asset within the group
1101
+ */
1102
+ asset_id: string;
1103
+ /**
1104
+ * Type of asset
1105
+ */
1106
+ asset_type: 'image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url' | 'brand_manifest';
1107
+ /**
1108
+ * Purpose of this asset
1109
+ */
1110
+ asset_role?: string;
1111
+ /**
1112
+ * Whether this asset is required in each repetition
1113
+ */
1114
+ required?: boolean;
1115
+ /**
1116
+ * Technical requirements for this asset
1117
+ */
1118
+ requirements?: {
1119
+ [k: string]: unknown;
1120
+ };
1121
+ }[];
1122
+ })[];
1123
+ /**
1124
+ * Delivery method specifications (e.g., hosted, VAST, third-party tags)
1125
+ */
1126
+ delivery?: {
1127
+ [k: string]: unknown;
1128
+ };
1129
+ /**
1130
+ * List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.
1131
+ */
1132
+ supported_macros?: string[];
1133
+ /**
1134
+ * For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).
1135
+ */
1136
+ output_format_ids?: FormatID1[];
1137
+ }
1138
+ /**
1139
+ * Structured format identifier with agent URL and format name
1140
+ */
1141
+ export interface FormatID1 {
1142
+ /**
1143
+ * URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)
1144
+ */
1145
+ agent_url: string;
1146
+ /**
1147
+ * Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')
1148
+ */
1149
+ id: string;
1150
+ }
1151
+ /**
1152
+ * Standard error structure for task-specific errors and warnings
1153
+ */
1154
+ /**
1155
+ * Budget pacing strategy
1156
+ */
1157
+ export type Pacing = 'even' | 'asap' | 'front_loaded';
1158
+ /**
1159
+ * VAST (Video Ad Serving Template) tag for third-party video ad serving
1160
+ */
1161
+ export type VASTAsset = VASTAsset1 & VASTAsset2;
1162
+ export type VASTAsset2 = {
1163
+ [k: string]: unknown;
1164
+ } | {
1165
+ [k: string]: unknown;
1166
+ };
1167
+ /**
1168
+ * DAAST (Digital Audio Ad Serving Template) tag for third-party audio ad serving
1169
+ */
1170
+ export type DAASTAsset = DAASTAsset1 & DAASTAsset2;
1171
+ export type DAASTAsset2 = {
1172
+ [k: string]: unknown;
1173
+ } | {
1174
+ [k: string]: unknown;
1175
+ };
1176
+ /**
1177
+ * Brand information manifest serving as the namespace and identity for this media buy. Provides brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest. Can be cached and reused across multiple requests.
1178
+ */
1179
+ export type StartTiming = 'asap' | string;
1180
+ /**
1181
+ * Request parameters for creating a media buy
1182
+ */
1183
+ export interface CreateMediaBuyRequest {
116
1184
  /**
117
- * Cost per thousand impressions in USD
1185
+ * Buyer's reference identifier for this media buy
118
1186
  */
119
- cpm?: number;
1187
+ buyer_ref: string;
120
1188
  /**
121
- * Minimum budget requirement in USD
1189
+ * Array of package configurations
122
1190
  */
123
- min_spend?: number;
124
- measurement?: Measurement;
125
- creative_policy?: CreativePolicy;
1191
+ packages: PackageRequest[];
1192
+ brand_manifest: BrandManifestReference;
126
1193
  /**
127
- * Whether this is a custom product
1194
+ * Purchase order number for tracking
128
1195
  */
129
- is_custom?: boolean;
1196
+ po_number?: string;
1197
+ start_time: StartTiming;
130
1198
  /**
131
- * Explanation of why this product matches the brief (only included when brief is provided)
1199
+ * Campaign end date/time in ISO 8601 format
132
1200
  */
133
- brief_relevance?: string;
1201
+ end_time: string;
134
1202
  /**
135
- * Expiration timestamp for custom products
1203
+ * Total budget for this media buy. Currency is determined by the pricing_option_id selected in each package.
136
1204
  */
137
- expires_at?: string;
1205
+ budget: number;
1206
+ reporting_webhook?: PushNotificationConfig & {
1207
+ /**
1208
+ * Frequency for automated reporting delivery. Must be supported by all products in the media buy.
1209
+ */
1210
+ reporting_frequency: 'hourly' | 'daily' | 'monthly';
1211
+ /**
1212
+ * Optional list of metrics to include in webhook notifications. If omitted, all available metrics are included. Must be subset of product's available_metrics.
1213
+ */
1214
+ requested_metrics?: ('impressions' | 'spend' | 'clicks' | 'ctr' | 'video_completions' | 'completion_rate' | 'conversions' | 'viewability' | 'engagement_rate')[];
1215
+ };
138
1216
  }
139
1217
  /**
140
- * An advertising property that can be validated via adagents.json
1218
+ * Package configuration for media buy creation
141
1219
  */
142
- export interface Property {
1220
+ export interface PackageRequest {
143
1221
  /**
144
- * Type of advertising property
1222
+ * Buyer's reference identifier for this package
145
1223
  */
146
- property_type: 'website' | 'mobile_app' | 'ctv_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio';
1224
+ buyer_ref: string;
147
1225
  /**
148
- * Human-readable property name
1226
+ * Product ID for this package
149
1227
  */
150
- name: string;
1228
+ product_id: string;
151
1229
  /**
152
- * Array of identifiers for this property
1230
+ * Array of format IDs that will be used for this package - must be supported by the product. If omitted, defaults to all formats supported by the product.
153
1231
  *
154
1232
  * @minItems 1
155
1233
  */
156
- identifiers: [
157
- {
158
- type: PropertyIdentifierTypes;
159
- /**
160
- * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
161
- */
162
- value: string;
163
- },
164
- ...{
165
- type: PropertyIdentifierTypes;
166
- /**
167
- * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
168
- */
169
- value: string;
170
- }[]
171
- ];
1234
+ format_ids?: [FormatID, ...FormatID[]];
172
1235
  /**
173
- * Tags for categorization and grouping (e.g., network membership, content categories)
1236
+ * Budget allocation for this package in the media buy's currency
174
1237
  */
175
- tags?: string[];
1238
+ budget: number;
1239
+ pacing?: Pacing;
176
1240
  /**
177
- * Domain where adagents.json should be checked for authorization validation
1241
+ * ID of the selected pricing option from the product's pricing_options array
178
1242
  */
179
- publisher_domain: string;
1243
+ pricing_option_id: string;
1244
+ /**
1245
+ * Bid price for auction-based CPM pricing (required if using cpm-auction-option)
1246
+ */
1247
+ bid_price?: number;
1248
+ targeting_overlay?: TargetingOverlay;
1249
+ /**
1250
+ * Creative IDs to assign to this package at creation time (references existing library creatives)
1251
+ */
1252
+ creative_ids?: string[];
1253
+ /**
1254
+ * Full creative objects to upload and assign to this package at creation time (alternative to creative_ids - creatives will be added to library). Supports both static and generative creatives.
1255
+ *
1256
+ * @maxItems 100
1257
+ */
1258
+ creatives?: CreativeAsset[];
180
1259
  }
181
1260
  /**
182
- * Measurement capabilities included with a product
1261
+ * Structured format identifier with agent URL and format name
183
1262
  */
184
- export interface Measurement {
1263
+ export interface TargetingOverlay {
185
1264
  /**
186
- * Type of measurement
1265
+ * Restrict delivery to specific countries (ISO codes). Use for regulatory compliance or RCT testing.
187
1266
  */
188
- type: string;
1267
+ geo_country_any_of?: string[];
189
1268
  /**
190
- * Attribution methodology
1269
+ * Restrict delivery to specific regions/states. Use for regulatory compliance or RCT testing.
191
1270
  */
192
- attribution: string;
1271
+ geo_region_any_of?: string[];
193
1272
  /**
194
- * Attribution window
1273
+ * Restrict delivery to specific metro areas (DMA codes). Use for regulatory compliance or RCT testing.
195
1274
  */
196
- window?: string;
1275
+ geo_metro_any_of?: string[];
197
1276
  /**
198
- * Reporting frequency and format
1277
+ * Restrict delivery to specific postal/ZIP codes. Use for regulatory compliance or RCT testing.
199
1278
  */
200
- reporting: string;
1279
+ geo_postal_code_any_of?: string[];
1280
+ frequency_cap?: FrequencyCap;
201
1281
  }
202
1282
  /**
203
- * Creative requirements and restrictions for a product
1283
+ * Frequency capping settings for package-level application
204
1284
  */
205
- export interface CreativePolicy {
206
- /**
207
- * Co-branding requirement
208
- */
209
- co_branding: 'required' | 'optional' | 'none';
210
- /**
211
- * Landing page requirements
212
- */
213
- landing_page: 'any' | 'retailer_site_only' | 'must_include_retailer';
1285
+ export interface FrequencyCap {
214
1286
  /**
215
- * Whether creative templates are provided
1287
+ * Minutes to suppress after impression
216
1288
  */
217
- templates_available: boolean;
1289
+ suppress_minutes: number;
218
1290
  }
219
1291
  /**
220
- * Standard error structure for task-specific errors and warnings
1292
+ * Creative asset for upload to library - supports static assets, generative formats, and third-party snippets
221
1293
  */
222
- export interface Error {
1294
+ export interface CreativeAsset {
223
1295
  /**
224
- * Error code for programmatic handling
1296
+ * Unique identifier for the creative
225
1297
  */
226
- code: string;
1298
+ creative_id: string;
227
1299
  /**
228
- * Human-readable error message
1300
+ * Human-readable creative name
229
1301
  */
230
- message: string;
1302
+ name: string;
1303
+ format_id: FormatID1;
231
1304
  /**
232
- * Field path associated with the error (e.g., 'packages[0].targeting')
1305
+ * Assets required by the format, keyed by asset_role
233
1306
  */
234
- field?: string;
1307
+ assets: {
1308
+ /**
1309
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1310
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
1311
+ */
1312
+ [k: string]: ImageAsset | VideoAsset | AudioAsset | TextAsset | HTMLAsset | CSSAsset | JavaScriptAsset | VASTAsset | DAASTAsset | PromotedOfferingsAsset | URLAsset;
1313
+ };
235
1314
  /**
236
- * Suggested fix for the error
1315
+ * Preview contexts for generative formats - defines what scenarios to generate previews for
237
1316
  */
238
- suggestion?: string;
1317
+ inputs?: {
1318
+ /**
1319
+ * Human-readable name for this preview variant
1320
+ */
1321
+ name: string;
1322
+ /**
1323
+ * Macro values to apply for this preview
1324
+ */
1325
+ macros?: {
1326
+ [k: string]: string;
1327
+ };
1328
+ /**
1329
+ * Natural language description of the context for AI-generated content
1330
+ */
1331
+ context_description?: string;
1332
+ }[];
239
1333
  /**
240
- * Seconds to wait before retrying the operation
1334
+ * User-defined tags for organization and searchability
241
1335
  */
242
- retry_after?: number;
1336
+ tags?: string[];
243
1337
  /**
244
- * Additional task-specific error details
1338
+ * For generative creatives: set to true to approve and finalize, false to request regeneration with updated assets/message. Omit for non-generative creatives.
245
1339
  */
246
- details?: {
247
- [k: string]: unknown;
248
- };
1340
+ approved?: boolean;
249
1341
  }
250
1342
  /**
251
- * Request parameters for discovering supported creative formats
1343
+ * Structured format identifier with agent URL and format name
252
1344
  */
253
- export interface ListCreativeFormatsRequest {
1345
+ export interface ImageAsset {
1346
+ asset_type: 'image';
254
1347
  /**
255
- * AdCP schema version for this request
1348
+ * URL to the image asset
256
1349
  */
257
- adcp_version?: string;
1350
+ url: string;
258
1351
  /**
259
- * Filter by format type
1352
+ * Image width in pixels
260
1353
  */
261
- type?: 'audio' | 'video' | 'display';
1354
+ width?: number;
262
1355
  /**
263
- * Only return IAB standard formats
1356
+ * Image height in pixels
264
1357
  */
265
- standard_only?: boolean;
1358
+ height?: number;
266
1359
  /**
267
- * Filter by format category
1360
+ * Image file format (jpg, png, gif, webp, etc.)
268
1361
  */
269
- category?: 'standard' | 'custom';
1362
+ format?: string;
270
1363
  /**
271
- * Filter by specific format IDs (e.g., from get_products response)
1364
+ * Alternative text for accessibility
272
1365
  */
273
- format_ids?: string[];
1366
+ alt_text?: string;
274
1367
  }
275
1368
  /**
276
- * Current task state
277
- */
278
- export type CreativeAsset = CreativeAsset1 & CreativeAsset2;
279
- /**
280
- * Type of snippet content
281
- */
282
- export type SnippetType = 'vast_xml' | 'vast_url' | 'html' | 'javascript' | 'iframe' | 'daast_url';
283
- /**
284
- * Sub-asset for multi-asset creative formats, including carousel images and native ad template variables
285
- */
286
- export type SubAsset = SubAsset1 & SubAsset2;
287
- export type SubAsset2 = {
288
- [k: string]: unknown;
289
- } | {
290
- [k: string]: unknown;
291
- };
292
- export type CreativeAsset2 = {
293
- [k: string]: unknown;
294
- } | {
295
- [k: string]: unknown;
296
- };
297
- /**
298
- * Response payload for list_creative_formats task
1369
+ * Video asset with URL and specifications
299
1370
  */
300
- export interface ListCreativeFormatsResponse {
1371
+ export interface VideoAsset {
1372
+ asset_type: 'video';
301
1373
  /**
302
- * AdCP schema version used for this response
1374
+ * URL to the video asset
303
1375
  */
304
- adcp_version: string;
305
- status?: TaskStatus;
1376
+ url: string;
306
1377
  /**
307
- * Array of available creative formats
1378
+ * Video width in pixels
308
1379
  */
309
- formats: Format[];
1380
+ width?: number;
310
1381
  /**
311
- * Task-specific errors and warnings (e.g., format availability issues)
1382
+ * Video height in pixels
312
1383
  */
313
- errors?: Error[];
1384
+ height?: number;
1385
+ /**
1386
+ * Video duration in milliseconds
1387
+ */
1388
+ duration_ms?: number;
1389
+ /**
1390
+ * Video file format (mp4, webm, mov, etc.)
1391
+ */
1392
+ format?: string;
1393
+ /**
1394
+ * Video bitrate in kilobits per second
1395
+ */
1396
+ bitrate_kbps?: number;
314
1397
  }
315
1398
  /**
316
- * Represents a creative format with its requirements
1399
+ * Audio asset with URL and specifications
317
1400
  */
318
- export interface Format {
1401
+ export interface AudioAsset {
1402
+ asset_type: 'audio';
319
1403
  /**
320
- * Unique identifier for the format
1404
+ * URL to the audio asset
321
1405
  */
322
- format_id: string;
1406
+ url: string;
323
1407
  /**
324
- * Human-readable format name
1408
+ * Audio duration in milliseconds
325
1409
  */
326
- name: string;
1410
+ duration_ms?: number;
327
1411
  /**
328
- * Media type of this format - determines rendering method and asset requirements
1412
+ * Audio file format (mp3, wav, aac, etc.)
329
1413
  */
330
- type: 'audio' | 'video' | 'display' | 'native' | 'dooh' | 'rich_media' | 'universal';
1414
+ format?: string;
331
1415
  /**
332
- * Format category
1416
+ * Audio bitrate in kilobits per second
333
1417
  */
334
- category?: 'standard' | 'custom';
1418
+ bitrate_kbps?: number;
1419
+ }
1420
+ /**
1421
+ * Text content asset
1422
+ */
1423
+ export interface TextAsset {
1424
+ asset_type: 'text';
335
1425
  /**
336
- * Whether this format follows IAB specifications or AdCP standard format definitions (found in /schemas/v1/standard-formats/)
1426
+ * Text content
337
1427
  */
338
- is_standard?: boolean;
1428
+ content: string;
339
1429
  /**
340
- * Technical specifications for this format (e.g., dimensions, duration, file size limits, codecs)
1430
+ * Maximum character length constraint
341
1431
  */
342
- requirements?: {
343
- [k: string]: unknown;
344
- };
1432
+ max_length?: number;
345
1433
  /**
346
- * Array of required assets for this format
1434
+ * Language code (e.g., 'en', 'es', 'fr')
347
1435
  */
348
- assets_required?: CreativeAsset[];
1436
+ language?: string;
1437
+ }
1438
+ /**
1439
+ * HTML content asset
1440
+ */
1441
+ export interface HTMLAsset {
1442
+ asset_type: 'html';
349
1443
  /**
350
- * Array of optional assets that may be included
1444
+ * HTML content
351
1445
  */
352
- optional_assets?: CreativeAsset2[];
1446
+ content: string;
353
1447
  /**
354
- * Delivery method specifications (e.g., hosted, VAST, third-party tags)
1448
+ * HTML version (e.g., 'HTML5')
355
1449
  */
356
- delivery?: {
357
- [k: string]: unknown;
358
- };
1450
+ version?: string;
1451
+ }
1452
+ /**
1453
+ * CSS stylesheet asset
1454
+ */
1455
+ export interface CSSAsset {
1456
+ asset_type: 'css';
1457
+ /**
1458
+ * CSS content
1459
+ */
1460
+ content: string;
359
1461
  /**
360
- * Whether this format can accept third-party served creative tags as an alternative to hosted assets
1462
+ * CSS media query context (e.g., 'screen', 'print')
361
1463
  */
362
- accepts_3p_tags?: boolean;
1464
+ media?: string;
363
1465
  }
364
- export interface CreativeAsset1 {
1466
+ /**
1467
+ * JavaScript code asset
1468
+ */
1469
+ export interface JavaScriptAsset {
1470
+ asset_type: 'javascript';
365
1471
  /**
366
- * Unique identifier for the creative
1472
+ * JavaScript content
367
1473
  */
368
- creative_id: string;
1474
+ content: string;
369
1475
  /**
370
- * Human-readable creative name
1476
+ * JavaScript module type
371
1477
  */
372
- name: string;
1478
+ module_type?: 'esm' | 'commonjs' | 'script';
1479
+ }
1480
+ export interface VASTAsset1 {
1481
+ asset_type?: 'vast';
373
1482
  /**
374
- * Creative format type (e.g., video, audio, display)
1483
+ * URL endpoint that returns VAST XML
375
1484
  */
376
- format: string;
1485
+ url?: string;
377
1486
  /**
378
- * URL of the creative file (for hosted assets)
1487
+ * Inline VAST XML content
379
1488
  */
380
- media_url?: string;
1489
+ content?: string;
381
1490
  /**
382
- * Third-party tag, VAST XML, or code snippet (for third-party served assets)
1491
+ * VAST specification version
383
1492
  */
384
- snippet?: string;
385
- snippet_type?: SnippetType;
1493
+ vast_version?: '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
386
1494
  /**
387
- * Landing page URL for the creative
1495
+ * Whether VPAID (Video Player-Ad Interface Definition) is supported
388
1496
  */
389
- click_url?: string;
1497
+ vpaid_enabled?: boolean;
390
1498
  /**
391
- * Duration in milliseconds (for video/audio)
1499
+ * Maximum allowed wrapper/redirect depth
392
1500
  */
393
- duration?: number;
1501
+ max_wrapper_depth?: number;
394
1502
  /**
395
- * Width in pixels (for video/display)
1503
+ * Expected video duration in milliseconds (if known)
396
1504
  */
397
- width?: number;
1505
+ duration_ms?: number;
398
1506
  /**
399
- * Height in pixels (for video/display)
1507
+ * Tracking events supported by this VAST tag
400
1508
  */
401
- height?: number;
1509
+ tracking_events?: ('start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'click' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute' | 'fullscreen' | 'exitFullscreen' | 'playerExpand' | 'playerCollapse')[];
1510
+ }
1511
+ export interface DAASTAsset1 {
1512
+ asset_type?: 'daast';
402
1513
  /**
403
- * User-defined tags for organization and searchability
1514
+ * URL endpoint that returns DAAST XML
404
1515
  */
405
- tags?: string[];
1516
+ url?: string;
406
1517
  /**
407
- * Sub-assets for multi-asset formats like carousels
1518
+ * Inline DAAST XML content
408
1519
  */
409
- assets?: SubAsset[];
410
- }
411
- export interface SubAsset1 {
1520
+ content?: string;
412
1521
  /**
413
- * Type of asset. Common types: headline, body_text, thumbnail_image, product_image, featured_image, logo, cta_text, price_text, sponsor_name, author_name, click_url
1522
+ * DAAST specification version
414
1523
  */
415
- asset_type?: string;
1524
+ daast_version?: '1.0' | '1.1';
416
1525
  /**
417
- * Unique identifier for the asset within the creative
1526
+ * Expected audio duration in milliseconds (if known)
418
1527
  */
419
- asset_id?: string;
1528
+ duration_ms?: number;
420
1529
  /**
421
- * URL for media assets (images, videos, etc.)
1530
+ * Tracking events supported by this DAAST tag
422
1531
  */
423
- content_uri?: string;
1532
+ tracking_events?: ('start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute')[];
424
1533
  /**
425
- * Text content for text-based assets like headlines, body text, CTA text, etc.
1534
+ * Whether companion display ads are included
426
1535
  */
427
- content?: string | string[];
1536
+ companion_ads?: boolean;
428
1537
  }
429
1538
  /**
430
- * Standard error structure for task-specific errors and warnings
431
- */
432
- /**
433
- * Budget pacing strategy
434
- */
435
- export type Pacing = 'even' | 'asap' | 'front_loaded';
436
- /**
437
- * Request parameters for creating a media buy
1539
+ * Reference to promoted offerings specification
438
1540
  */
439
- export interface CreateMediaBuyRequest {
1541
+ export interface PromotedOfferingsAsset {
1542
+ asset_type: 'promoted_offerings';
440
1543
  /**
441
- * AdCP schema version for this request
1544
+ * URL of the advertiser's brand or offering (e.g., https://retailer.com)
442
1545
  */
443
- adcp_version?: string;
1546
+ url?: string;
444
1547
  /**
445
- * Buyer's reference identifier for this media buy
1548
+ * Brand colors
446
1549
  */
447
- buyer_ref: string;
1550
+ colors?: {
1551
+ primary?: string;
1552
+ secondary?: string;
1553
+ accent?: string;
1554
+ };
448
1555
  /**
449
- * Array of package configurations
1556
+ * Brand fonts
450
1557
  */
451
- packages: ({
452
- [k: string]: unknown;
453
- } | {
454
- [k: string]: unknown;
455
- })[];
1558
+ fonts?: string[];
456
1559
  /**
457
- * Description of advertiser and what is being promoted
1560
+ * Brand tone/voice
458
1561
  */
459
- promoted_offering: string;
1562
+ tone?: string;
1563
+ }
1564
+ /**
1565
+ * URL reference asset
1566
+ */
1567
+ export interface URLAsset {
1568
+ asset_type: 'url';
460
1569
  /**
461
- * Purchase order number for tracking
1570
+ * URL reference
462
1571
  */
463
- po_number?: string;
1572
+ url: string;
464
1573
  /**
465
- * Campaign start date/time in ISO 8601 format
1574
+ * Description of what this URL points to
466
1575
  */
467
- start_time: string;
1576
+ description?: string;
1577
+ }
1578
+ export interface PushNotificationConfig {
468
1579
  /**
469
- * Campaign end date/time in ISO 8601 format
1580
+ * Webhook endpoint URL for task status notifications
470
1581
  */
471
- end_time: string;
472
- budget: Budget;
473
- }
474
- /**
475
- * Budget configuration for a media buy or package
476
- */
477
- export interface Budget {
1582
+ url: string;
478
1583
  /**
479
- * Total budget amount
1584
+ * Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.
480
1585
  */
481
- total: number;
1586
+ token?: string;
482
1587
  /**
483
- * ISO 4217 currency code
1588
+ * Authentication configuration for webhook delivery (A2A-compatible)
484
1589
  */
485
- currency: string;
486
- pacing?: Pacing;
1590
+ authentication: {
1591
+ /**
1592
+ * Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)
1593
+ *
1594
+ * @minItems 1
1595
+ * @maxItems 1
1596
+ */
1597
+ schemes: ['Bearer' | 'HMAC-SHA256'];
1598
+ /**
1599
+ * Credentials for authentication. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.
1600
+ */
1601
+ credentials: string;
1602
+ };
487
1603
  }
488
1604
  /**
489
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations, 'input-required' if approval needed
1605
+ * Response payload for create_media_buy task
490
1606
  */
491
1607
  export interface CreateMediaBuyResponse {
492
- /**
493
- * AdCP schema version used for this response
494
- */
495
- adcp_version: string;
496
- status: TaskStatus;
497
- /**
498
- * Unique identifier for tracking this async operation (present for submitted/working status)
499
- */
500
- task_id?: string;
501
1608
  /**
502
1609
  * Publisher's unique identifier for the created media buy
503
1610
  */
@@ -532,13 +1639,9 @@ export interface CreateMediaBuyResponse {
532
1639
  * Standard error structure for task-specific errors and warnings
533
1640
  */
534
1641
  /**
535
- * Creative asset for upload to library - supports both hosted assets and third-party snippets
1642
+ * VAST (Video Ad Serving Template) tag for third-party video ad serving
536
1643
  */
537
1644
  export interface SyncCreativesRequest {
538
- /**
539
- * AdCP schema version for this request
540
- */
541
- adcp_version?: string;
542
1645
  /**
543
1646
  * Array of creative assets to sync (create or update)
544
1647
  *
@@ -573,69 +1676,23 @@ export interface SyncCreativesRequest {
573
1676
  * Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors.
574
1677
  */
575
1678
  validation_mode?: 'strict' | 'lenient';
1679
+ push_notification_config?: PushNotificationConfig;
576
1680
  }
577
1681
  /**
578
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations
1682
+ * Creative asset for upload to library - supports static assets, generative formats, and third-party snippets
579
1683
  */
580
- export type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';
581
1684
  /**
582
- * Response from creative sync operation with detailed results and bulk operation summary
583
- */
584
- export interface SyncCreativesResponse {
585
- /**
586
- * AdCP schema version used for this response
587
- */
588
- adcp_version: string;
589
- /**
590
- * Human-readable result message summarizing the sync operation
591
- */
592
- message: string;
593
- /**
594
- * Context ID for tracking async operations
595
- */
596
- context_id?: string;
597
- status: TaskStatus;
598
- /**
599
- * Unique identifier for tracking this async operation (present for submitted/working status)
600
- */
601
- task_id?: string;
1685
+ * Response from creative sync operation with results for each creative
1686
+ */
1687
+ export interface SyncCreativesResponse {
602
1688
  /**
603
1689
  * Whether this was a dry run (no actual changes made)
604
1690
  */
605
1691
  dry_run?: boolean;
606
1692
  /**
607
- * High-level summary of sync operation results
608
- */
609
- summary?: {
610
- /**
611
- * Total number of creatives processed
612
- */
613
- total_processed: number;
614
- /**
615
- * Number of new creatives created
616
- */
617
- created: number;
618
- /**
619
- * Number of existing creatives updated
620
- */
621
- updated: number;
622
- /**
623
- * Number of creatives that were already up-to-date
624
- */
625
- unchanged: number;
626
- /**
627
- * Number of creatives that failed validation or processing
628
- */
629
- failed: number;
630
- /**
631
- * Number of creatives deleted/archived (when delete_missing=true)
632
- */
633
- deleted?: number;
634
- };
635
- /**
636
- * Detailed results for each creative processed
1693
+ * Results for each creative processed
637
1694
  */
638
- results?: {
1695
+ creatives: {
639
1696
  /**
640
1697
  * Creative ID from the request
641
1698
  */
@@ -644,17 +1701,16 @@ export interface SyncCreativesResponse {
644
1701
  * Action taken for this creative
645
1702
  */
646
1703
  action: 'created' | 'updated' | 'unchanged' | 'failed' | 'deleted';
647
- status?: CreativeStatus;
648
1704
  /**
649
1705
  * Platform-specific ID assigned to the creative
650
1706
  */
651
1707
  platform_id?: string;
652
1708
  /**
653
- * List of field names that were modified (for 'updated' action)
1709
+ * Field names that were modified (only present when action='updated')
654
1710
  */
655
1711
  changes?: string[];
656
1712
  /**
657
- * Validation or processing errors (for 'failed' action)
1713
+ * Validation or processing errors (only present when action='failed')
658
1714
  */
659
1715
  errors?: string[];
660
1716
  /**
@@ -662,99 +1718,43 @@ export interface SyncCreativesResponse {
662
1718
  */
663
1719
  warnings?: string[];
664
1720
  /**
665
- * Feedback from platform review process
666
- */
667
- review_feedback?: string;
668
- /**
669
- * Recommended creative adaptations for better performance
670
- */
671
- suggested_adaptations?: {
672
- /**
673
- * Unique identifier for this adaptation
674
- */
675
- adaptation_id: string;
676
- /**
677
- * Target format ID for the adaptation
678
- */
679
- format_id: string;
680
- /**
681
- * Suggested name for the adapted creative
682
- */
683
- name: string;
684
- /**
685
- * What this adaptation does
686
- */
687
- description: string;
688
- /**
689
- * Expected performance improvement (percentage)
690
- */
691
- estimated_performance_lift?: number;
692
- }[];
693
- }[];
694
- /**
695
- * Summary of assignment operations (when assignments were included in request)
696
- */
697
- assignments_summary?: {
698
- /**
699
- * Total number of creative-package assignment operations processed
700
- */
701
- total_assignments_processed: number;
702
- /**
703
- * Number of successful creative-package assignments
704
- */
705
- assigned: number;
706
- /**
707
- * Number of creative-package unassignments
708
- */
709
- unassigned: number;
710
- /**
711
- * Number of assignment operations that failed
712
- */
713
- failed: number;
714
- };
715
- /**
716
- * Detailed assignment results (when assignments were included in request)
717
- */
718
- assignment_results?: {
719
- /**
720
- * Creative that was assigned/unassigned
1721
+ * Preview URL for generative creatives (only present for generative formats)
721
1722
  */
722
- creative_id: string;
1723
+ preview_url?: string;
723
1724
  /**
724
- * Packages successfully assigned to this creative
1725
+ * ISO 8601 timestamp when preview link expires (only present when preview_url exists)
725
1726
  */
726
- assigned_packages?: string[];
1727
+ expires_at?: string;
727
1728
  /**
728
- * Packages successfully unassigned from this creative
1729
+ * Package IDs this creative was successfully assigned to (only present when assignments were requested)
729
1730
  */
730
- unassigned_packages?: string[];
1731
+ assigned_to?: string[];
731
1732
  /**
732
- * Packages that failed to assign/unassign
1733
+ * Assignment errors by package ID (only present when assignment failures occurred)
733
1734
  */
734
- failed_packages?: {
735
- /**
736
- * Package ID that failed
737
- */
738
- package_id: string;
1735
+ assignment_errors?: {
739
1736
  /**
740
- * Error message for the failed assignment
1737
+ * Error message for this package assignment
1738
+ *
1739
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1740
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
741
1741
  */
742
- error: string;
743
- }[];
1742
+ [k: string]: string;
1743
+ };
744
1744
  }[];
745
1745
  }
746
1746
  /**
747
1747
  * Filter by creative approval status
748
1748
  */
1749
+ export type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';
1750
+ /**
1751
+ * Status of a creative asset
1752
+ */
749
1753
  export type CreativeStatus1 = 'processing' | 'approved' | 'rejected' | 'pending_review';
750
1754
  /**
751
- * Filter by third-party snippet type
1755
+ * Request parameters for querying creative assets from the centralized library with filtering, sorting, and pagination
752
1756
  */
753
1757
  export interface ListCreativesRequest {
754
- /**
755
- * AdCP schema version for this request
756
- */
757
- adcp_version?: string;
758
1758
  /**
759
1759
  * Filter criteria for querying creatives
760
1760
  */
@@ -818,7 +1818,6 @@ export interface ListCreativesRequest {
818
1818
  * Filter for unassigned creatives when true, assigned creatives when false
819
1819
  */
820
1820
  unassigned?: boolean;
821
- snippet_type?: SnippetType;
822
1821
  /**
823
1822
  * Filter creatives that have performance data when true
824
1823
  */
@@ -870,19 +1869,16 @@ export interface ListCreativesRequest {
870
1869
  /**
871
1870
  * Current approval status of the creative
872
1871
  */
1872
+ export type SubAsset = SubAsset1 & SubAsset2;
1873
+ export type SubAsset2 = {
1874
+ [k: string]: unknown;
1875
+ } | {
1876
+ [k: string]: unknown;
1877
+ };
1878
+ /**
1879
+ * Response from creative library query with filtered results, metadata, and optional enriched data
1880
+ */
873
1881
  export interface ListCreativesResponse {
874
- /**
875
- * AdCP schema version used for this response
876
- */
877
- adcp_version: string;
878
- /**
879
- * Human-readable result message
880
- */
881
- message: string;
882
- /**
883
- * Context ID for tracking related operations
884
- */
885
- context_id?: string;
886
1882
  /**
887
1883
  * Summary of the query that was executed
888
1884
  */
@@ -905,7 +1901,6 @@ export interface ListCreativesResponse {
905
1901
  sort_applied?: {
906
1902
  field?: string;
907
1903
  direction?: 'asc' | 'desc';
908
- [k: string]: unknown;
909
1904
  };
910
1905
  };
911
1906
  /**
@@ -945,10 +1940,7 @@ export interface ListCreativesResponse {
945
1940
  * Human-readable creative name
946
1941
  */
947
1942
  name: string;
948
- /**
949
- * Creative format type
950
- */
951
- format: string;
1943
+ format_id: FormatID;
952
1944
  status: CreativeStatus;
953
1945
  /**
954
1946
  * When the creative was uploaded to the library
@@ -963,10 +1955,15 @@ export interface ListCreativesResponse {
963
1955
  */
964
1956
  media_url?: string;
965
1957
  /**
966
- * Third-party tag, VAST XML, or code snippet (for third-party assets)
1958
+ * Assets for this creative, keyed by asset_role
967
1959
  */
968
- snippet?: string;
969
- snippet_type?: SnippetType;
1960
+ assets?: {
1961
+ /**
1962
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1963
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
1964
+ */
1965
+ [k: string]: ImageAsset | VideoAsset | AudioAsset | TextAsset | HTMLAsset | CSSAsset | JavaScriptAsset | VASTAsset | DAASTAsset | PromotedOfferingsAsset | URLAsset;
1966
+ };
970
1967
  /**
971
1968
  * Landing page URL for the creative
972
1969
  */
@@ -1085,21 +2082,38 @@ export interface ListCreativesResponse {
1085
2082
  archived?: number;
1086
2083
  };
1087
2084
  }
2085
+ /**
2086
+ * Format identifier specifying which format this creative conforms to
2087
+ */
2088
+ export interface SubAsset1 {
2089
+ /**
2090
+ * Type of asset. Common types: headline, body_text, thumbnail_image, product_image, featured_image, logo, cta_text, price_text, sponsor_name, author_name, click_url
2091
+ */
2092
+ asset_type?: string;
2093
+ /**
2094
+ * Unique identifier for the asset within the creative
2095
+ */
2096
+ asset_id?: string;
2097
+ /**
2098
+ * URL for media assets (images, videos, etc.)
2099
+ */
2100
+ content_uri?: string;
2101
+ /**
2102
+ * Text content for text-based assets like headlines, body text, CTA text, etc.
2103
+ */
2104
+ content?: string | string[];
2105
+ }
1088
2106
  /**
1089
2107
  * Request parameters for updating campaign and package settings
1090
2108
  */
1091
2109
  export type UpdateMediaBuyRequest = UpdateMediaBuyRequest1 & UpdateMediaBuyRequest2;
1092
2110
  /**
1093
- * Budget pacing strategy
2111
+ * Campaign start timing: 'asap' or ISO 8601 date-time
1094
2112
  */
1095
2113
  export type UpdateMediaBuyRequest2 = {
1096
2114
  [k: string]: unknown;
1097
2115
  };
1098
2116
  export interface UpdateMediaBuyRequest1 {
1099
- /**
1100
- * AdCP schema version for this request
1101
- */
1102
- adcp_version?: string;
1103
2117
  /**
1104
2118
  * Publisher's ID of the media buy to update
1105
2119
  */
@@ -1112,15 +2126,15 @@ export interface UpdateMediaBuyRequest1 {
1112
2126
  * Pause/resume the entire media buy
1113
2127
  */
1114
2128
  active?: boolean;
1115
- /**
1116
- * New start date/time in ISO 8601 format
1117
- */
1118
- start_time?: string;
2129
+ start_time?: StartTiming;
1119
2130
  /**
1120
2131
  * New end date/time in ISO 8601 format
1121
2132
  */
1122
2133
  end_time?: string;
1123
- budget?: Budget;
2134
+ /**
2135
+ * Updated total budget for this media buy. Currency is determined by the pricing_option_id selected in each package.
2136
+ */
2137
+ budget?: number;
1124
2138
  /**
1125
2139
  * Package-specific updates
1126
2140
  */
@@ -1129,23 +2143,15 @@ export interface UpdateMediaBuyRequest1 {
1129
2143
  } | {
1130
2144
  [k: string]: unknown;
1131
2145
  })[];
2146
+ push_notification_config?: PushNotificationConfig;
1132
2147
  }
1133
2148
  /**
1134
- * Budget configuration for a media buy or package
2149
+ * Optional webhook configuration for async update notifications. Publisher will send webhook when update completes if operation takes longer than immediate response time.
1135
2150
  */
1136
2151
  /**
1137
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations, 'input-required' if approval needed
2152
+ * Response payload for update_media_buy task
1138
2153
  */
1139
2154
  export interface UpdateMediaBuyResponse {
1140
- /**
1141
- * AdCP schema version used for this response
1142
- */
1143
- adcp_version: string;
1144
- status: TaskStatus;
1145
- /**
1146
- * Unique identifier for tracking this async operation (present for submitted/working status)
1147
- */
1148
- task_id?: string;
1149
2155
  /**
1150
2156
  * Publisher's identifier for the media buy
1151
2157
  */
@@ -1183,10 +2189,6 @@ export interface UpdateMediaBuyResponse {
1183
2189
  * Request parameters for retrieving comprehensive delivery metrics
1184
2190
  */
1185
2191
  export interface GetMediaBuyDeliveryRequest {
1186
- /**
1187
- * AdCP schema version for this request
1188
- */
1189
- adcp_version?: string;
1190
2192
  /**
1191
2193
  * Array of publisher media buy IDs to get delivery data for
1192
2194
  */
@@ -1208,24 +2210,44 @@ export interface GetMediaBuyDeliveryRequest {
1208
2210
  */
1209
2211
  end_date?: string;
1210
2212
  }
2213
+ /**
2214
+ * Pricing model used for this media buy
2215
+ */
2216
+ export type PricingModel = 'cpm' | 'vcpm' | 'cpc' | 'cpcv' | 'cpv' | 'cpp' | 'flat_rate';
1211
2217
  /**
1212
2218
  * Response payload for get_media_buy_delivery task
1213
2219
  */
1214
2220
  export interface GetMediaBuyDeliveryResponse {
1215
2221
  /**
1216
- * AdCP schema version used for this response
2222
+ * Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with updated data
2223
+ */
2224
+ notification_type?: 'scheduled' | 'final' | 'delayed' | 'adjusted';
2225
+ /**
2226
+ * Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)
2227
+ */
2228
+ partial_data?: boolean;
2229
+ /**
2230
+ * Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)
2231
+ */
2232
+ unavailable_count?: number;
2233
+ /**
2234
+ * Sequential notification number (only present in webhook deliveries, starts at 1)
2235
+ */
2236
+ sequence_number?: number;
2237
+ /**
2238
+ * ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')
1217
2239
  */
1218
- adcp_version: string;
2240
+ next_expected_at?: string;
1219
2241
  /**
1220
- * Date range for the report
2242
+ * Date range for the report. All periods use UTC timezone.
1221
2243
  */
1222
2244
  reporting_period: {
1223
2245
  /**
1224
- * ISO 8601 start timestamp
2246
+ * ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)
1225
2247
  */
1226
2248
  start: string;
1227
2249
  /**
1228
- * ISO 8601 end timestamp
2250
+ * ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)
1229
2251
  */
1230
2252
  end: string;
1231
2253
  };
@@ -1234,9 +2256,9 @@ export interface GetMediaBuyDeliveryResponse {
1234
2256
  */
1235
2257
  currency: string;
1236
2258
  /**
1237
- * Combined metrics across all returned media buys
2259
+ * Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.
1238
2260
  */
1239
- aggregated_totals: {
2261
+ aggregated_totals?: {
1240
2262
  /**
1241
2263
  * Total impressions delivered across all media buys
1242
2264
  */
@@ -1259,9 +2281,9 @@ export interface GetMediaBuyDeliveryResponse {
1259
2281
  media_buy_count: number;
1260
2282
  };
1261
2283
  /**
1262
- * Array of delivery data for each media buy
2284
+ * Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.
1263
2285
  */
1264
- deliveries: {
2286
+ media_buy_deliveries: {
1265
2287
  /**
1266
2288
  * Publisher's media buy identifier
1267
2289
  */
@@ -1271,42 +2293,28 @@ export interface GetMediaBuyDeliveryResponse {
1271
2293
  */
1272
2294
  buyer_ref?: string;
1273
2295
  /**
1274
- * Current media buy status
2296
+ * Current media buy status. In webhook context, reporting_delayed indicates data temporarily unavailable.
1275
2297
  */
1276
- status: 'pending' | 'active' | 'paused' | 'completed' | 'failed';
2298
+ status: 'pending' | 'active' | 'paused' | 'completed' | 'failed' | 'reporting_delayed';
1277
2299
  /**
1278
- * Aggregate metrics for this media buy across all packages
2300
+ * When delayed data is expected to be available (only present when status is reporting_delayed)
1279
2301
  */
1280
- totals: {
1281
- /**
1282
- * Total impressions delivered
1283
- */
1284
- impressions: number;
1285
- /**
1286
- * Total amount spent
1287
- */
1288
- spend: number;
1289
- /**
1290
- * Total clicks (if applicable)
1291
- */
1292
- clicks?: number;
1293
- /**
1294
- * Click-through rate (clicks/impressions)
1295
- */
1296
- ctr?: number;
1297
- /**
1298
- * Total video completions (if applicable)
1299
- */
1300
- video_completions?: number;
2302
+ expected_availability?: string;
2303
+ /**
2304
+ * Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.
2305
+ */
2306
+ is_adjusted?: boolean;
2307
+ pricing_model?: PricingModel;
2308
+ totals: DeliveryMetrics & {
1301
2309
  /**
1302
- * Video completion rate (completions/impressions)
2310
+ * Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')
1303
2311
  */
1304
- completion_rate?: number;
2312
+ effective_rate?: number;
1305
2313
  };
1306
2314
  /**
1307
2315
  * Metrics broken down by package
1308
2316
  */
1309
- by_package: {
2317
+ by_package: (DeliveryMetrics & {
1310
2318
  /**
1311
2319
  * Publisher's package identifier
1312
2320
  */
@@ -1315,27 +2323,11 @@ export interface GetMediaBuyDeliveryResponse {
1315
2323
  * Buyer's reference identifier for this package
1316
2324
  */
1317
2325
  buyer_ref?: string;
1318
- /**
1319
- * Package impressions
1320
- */
1321
- impressions: number;
1322
- /**
1323
- * Package spend
1324
- */
1325
- spend: number;
1326
- /**
1327
- * Package clicks
1328
- */
1329
- clicks?: number;
1330
- /**
1331
- * Package video completions
1332
- */
1333
- video_completions?: number;
1334
2326
  /**
1335
2327
  * Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)
1336
2328
  */
1337
2329
  pacing_index?: number;
1338
- }[];
2330
+ })[];
1339
2331
  /**
1340
2332
  * Day-by-day delivery
1341
2333
  */
@@ -1359,6 +2351,135 @@ export interface GetMediaBuyDeliveryResponse {
1359
2351
  */
1360
2352
  errors?: Error[];
1361
2353
  }
2354
+ /**
2355
+ * Standard delivery metrics that can be reported at media buy, package, or creative level
2356
+ */
2357
+ export interface DeliveryMetrics {
2358
+ /**
2359
+ * Impressions delivered
2360
+ */
2361
+ impressions?: number;
2362
+ /**
2363
+ * Amount spent
2364
+ */
2365
+ spend?: number;
2366
+ /**
2367
+ * Total clicks
2368
+ */
2369
+ clicks?: number;
2370
+ /**
2371
+ * Click-through rate (clicks/impressions)
2372
+ */
2373
+ ctr?: number;
2374
+ /**
2375
+ * Views at threshold (for CPV)
2376
+ */
2377
+ views?: number;
2378
+ /**
2379
+ * 100% completions (for CPCV)
2380
+ */
2381
+ completed_views?: number;
2382
+ /**
2383
+ * Completion rate (completed_views/impressions)
2384
+ */
2385
+ completion_rate?: number;
2386
+ /**
2387
+ * Conversions (reserved for future CPA pricing support)
2388
+ */
2389
+ conversions?: number;
2390
+ /**
2391
+ * Leads generated (reserved for future CPL pricing support)
2392
+ */
2393
+ leads?: number;
2394
+ /**
2395
+ * Gross Rating Points delivered (for CPP)
2396
+ */
2397
+ grps?: number;
2398
+ /**
2399
+ * Unique reach - units depend on measurement provider (e.g., individuals, households, devices, cookies). See delivery_measurement.provider for methodology.
2400
+ */
2401
+ reach?: number;
2402
+ /**
2403
+ * Average frequency per individual (typically measured over campaign duration, but can vary by measurement provider)
2404
+ */
2405
+ frequency?: number;
2406
+ /**
2407
+ * Video quartile completion data
2408
+ */
2409
+ quartile_data?: {
2410
+ /**
2411
+ * 25% completion views
2412
+ */
2413
+ q1_views?: number;
2414
+ /**
2415
+ * 50% completion views
2416
+ */
2417
+ q2_views?: number;
2418
+ /**
2419
+ * 75% completion views
2420
+ */
2421
+ q3_views?: number;
2422
+ /**
2423
+ * 100% completion views
2424
+ */
2425
+ q4_views?: number;
2426
+ };
2427
+ /**
2428
+ * DOOH-specific metrics (only included for DOOH campaigns)
2429
+ */
2430
+ dooh_metrics?: {
2431
+ /**
2432
+ * Number of times ad played in rotation
2433
+ */
2434
+ loop_plays?: number;
2435
+ /**
2436
+ * Number of unique screens displaying the ad
2437
+ */
2438
+ screens_used?: number;
2439
+ /**
2440
+ * Total display time in seconds
2441
+ */
2442
+ screen_time_seconds?: number;
2443
+ /**
2444
+ * Actual share of voice delivered (0.0 to 1.0)
2445
+ */
2446
+ sov_achieved?: number;
2447
+ /**
2448
+ * Explanation of how DOOH impressions were calculated
2449
+ */
2450
+ calculation_notes?: string;
2451
+ /**
2452
+ * Per-venue performance breakdown
2453
+ */
2454
+ venue_breakdown?: {
2455
+ /**
2456
+ * Venue identifier
2457
+ */
2458
+ venue_id: string;
2459
+ /**
2460
+ * Human-readable venue name
2461
+ */
2462
+ venue_name?: string;
2463
+ /**
2464
+ * Venue type (e.g., 'airport', 'transit', 'retail', 'billboard')
2465
+ */
2466
+ venue_type?: string;
2467
+ /**
2468
+ * Impressions delivered at this venue
2469
+ */
2470
+ impressions: number;
2471
+ /**
2472
+ * Loop plays at this venue
2473
+ */
2474
+ loop_plays?: number;
2475
+ /**
2476
+ * Number of screens used at this venue
2477
+ */
2478
+ screens_used?: number;
2479
+ }[];
2480
+ };
2481
+ [k: string]: unknown;
2482
+ }
1362
2483
  /**
1363
2484
  * Standard error structure for task-specific errors and warnings
1364
2485
  */
@@ -1366,10 +2487,6 @@ export interface GetMediaBuyDeliveryResponse {
1366
2487
  * Request parameters for discovering all properties this agent is authorized to represent
1367
2488
  */
1368
2489
  export interface ListAuthorizedPropertiesRequest {
1369
- /**
1370
- * AdCP schema version for this request
1371
- */
1372
- adcp_version?: string;
1373
2490
  /**
1374
2491
  * Filter properties by specific tags (optional)
1375
2492
  */
@@ -1378,11 +2495,11 @@ export interface ListAuthorizedPropertiesRequest {
1378
2495
  /**
1379
2496
  * Type of identifier for this property
1380
2497
  */
2498
+ export type AdvertisingChannels = 'display' | 'video' | 'audio' | 'native' | 'dooh' | 'ctv' | 'podcast' | 'retail' | 'social';
2499
+ /**
2500
+ * Response payload for list_authorized_properties task
2501
+ */
1381
2502
  export interface ListAuthorizedPropertiesResponse {
1382
- /**
1383
- * AdCP schema version used for this response
1384
- */
1385
- adcp_version: string;
1386
2503
  /**
1387
2504
  * Array of all properties this agent is authorized to represent
1388
2505
  */
@@ -1402,6 +2519,26 @@ export interface ListAuthorizedPropertiesResponse {
1402
2519
  description: string;
1403
2520
  };
1404
2521
  };
2522
+ /**
2523
+ * Primary advertising channels represented in this property portfolio. Helps buying agents quickly filter relevance.
2524
+ *
2525
+ * @minItems 1
2526
+ */
2527
+ primary_channels?: [AdvertisingChannels, ...AdvertisingChannels[]];
2528
+ /**
2529
+ * Primary countries (ISO 3166-1 alpha-2 codes) where properties are concentrated. Helps buying agents quickly filter relevance.
2530
+ *
2531
+ * @minItems 1
2532
+ */
2533
+ primary_countries?: [string, ...string[]];
2534
+ /**
2535
+ * Markdown-formatted description of the property portfolio, including inventory types, audience characteristics, and special features.
2536
+ */
2537
+ portfolio_description?: string;
2538
+ /**
2539
+ * Publisher's advertising content policies, restrictions, and guidelines in natural language. May include prohibited categories, blocked advertisers, restricted tactics, brand safety requirements, or links to full policy documentation.
2540
+ */
2541
+ advertising_policies?: string;
1405
2542
  /**
1406
2543
  * Task-specific errors and warnings (e.g., property availability issues)
1407
2544
  */
@@ -1414,10 +2551,6 @@ export interface ListAuthorizedPropertiesResponse {
1414
2551
  * Request payload for provide_performance_feedback task
1415
2552
  */
1416
2553
  export interface ProvidePerformanceFeedbackRequest {
1417
- /**
1418
- * AdCP schema version for this request
1419
- */
1420
- adcp_version?: string;
1421
2554
  /**
1422
2555
  * Publisher's media buy identifier
1423
2556
  */
@@ -1460,18 +2593,10 @@ export interface ProvidePerformanceFeedbackRequest {
1460
2593
  * Response payload for provide_performance_feedback task
1461
2594
  */
1462
2595
  export interface ProvidePerformanceFeedbackResponse {
1463
- /**
1464
- * AdCP schema version used for this response
1465
- */
1466
- adcp_version: string;
1467
2596
  /**
1468
2597
  * Whether the performance feedback was successfully received
1469
2598
  */
1470
2599
  success: boolean;
1471
- /**
1472
- * Optional human-readable message about the feedback processing
1473
- */
1474
- message?: string;
1475
2600
  /**
1476
2601
  * Task-specific errors and warnings (e.g., invalid measurement period, missing campaign data)
1477
2602
  */
@@ -1484,10 +2609,6 @@ export interface ProvidePerformanceFeedbackResponse {
1484
2609
  * Request parameters for discovering signals based on description
1485
2610
  */
1486
2611
  export interface GetSignalsRequest {
1487
- /**
1488
- * AdCP schema version for this request
1489
- */
1490
- adcp_version?: string;
1491
2612
  /**
1492
2613
  * Natural language description of the desired signals
1493
2614
  */
@@ -1548,10 +2669,6 @@ export interface GetSignalsRequest {
1548
2669
  * Response payload for get_signals task
1549
2670
  */
1550
2671
  export interface GetSignalsResponse {
1551
- /**
1552
- * AdCP schema version used for this response
1553
- */
1554
- adcp_version: string;
1555
2672
  /**
1556
2673
  * Array of matching signals
1557
2674
  */
@@ -1635,10 +2752,6 @@ export interface GetSignalsResponse {
1635
2752
  * Request parameters for activating a signal on a specific platform/account
1636
2753
  */
1637
2754
  export interface ActivateSignalRequest {
1638
- /**
1639
- * AdCP schema version for this request
1640
- */
1641
- adcp_version?: string;
1642
2755
  /**
1643
2756
  * The universal identifier for the signal to activate
1644
2757
  */
@@ -1653,18 +2766,9 @@ export interface ActivateSignalRequest {
1653
2766
  account?: string;
1654
2767
  }
1655
2768
  /**
1656
- * Current activation state: 'submitted' (pending), 'working' (processing), 'completed' (deployed), 'failed', 'input-required' (needs auth), etc.
2769
+ * Response payload for activate_signal task
1657
2770
  */
1658
2771
  export interface ActivateSignalResponse {
1659
- /**
1660
- * AdCP schema version used for this response
1661
- */
1662
- adcp_version: string;
1663
- /**
1664
- * Unique identifier for tracking the activation
1665
- */
1666
- task_id: string;
1667
- status: TaskStatus;
1668
2772
  /**
1669
2773
  * The platform-specific ID to use once activated
1670
2774
  */