@adcp/client 3.12.0 → 3.14.0

package/dist/lib/types/tools.generated.d.ts

@@ -792,6 +792,10 @@ export type PropertyTag = string;
  * 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.
  */
 export type PricingOption = CPMPricingOption | VCPMPricingOption | CPCPricingOption | CPCVPricingOption | CPVPricingOption | CPPPricingOption | CPAPricingOption | FlatRatePricingOption | TimeBasedPricingOption;
+/**
+ * Measurement system for the demographic field. Defaults to nielsen when omitted.
+ */
+export type DemographicSystem = 'nielsen' | 'barb' | 'agf' | 'oztam' | 'mediametrie' | 'custom';
 /**
  * Standard marketing event types for event logging, aligned with IAB ECAPI
  */
@@ -862,6 +866,26 @@ export type DataProviderSignalSelector = {
  * Where the conversion event originated
  */
 export type ActionSource = 'website' | 'app' | 'offline' | 'phone_call' | 'chat' | 'email' | 'in_store' | 'system_generated' | 'other';
+/**
+ * Days of the week for daypart targeting
+ */
+export type DayOfWeek = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+/**
+ * How to interpret the points array. 'spend' (default when omitted): points at ascending budget levels. 'reach_freq': points at ascending reach/frequency targets. 'weekly'/'daily': metrics are per-period values. 'clicks'/'conversions': points at ascending outcome targets.
+ */
+export type ForecastRangeUnit = 'spend' | 'reach_freq' | 'weekly' | 'daily' | 'clicks' | 'conversions';
+/**
+ * Method used to produce this forecast
+ */
+export type ForecastMethod = 'estimate' | 'modeled' | 'guaranteed';
+/**
+ * Measurement system for the demographic field. Ensures buyer and seller agree on demographic notation.
+ */
+export type DemographicSystem1 = 'nielsen' | 'barb' | 'agf' | 'oztam' | 'mediametrie' | 'custom';
+/**
+ * Unit of measurement for reach and audience_size metrics in this forecast. Required for cross-channel forecast comparison.
+ */
+export type ReachUnit = 'individuals' | 'households' | 'devices' | 'accounts' | 'cookies' | 'custom';
 /**
  * Response payload for get_products task
  */
@@ -994,6 +1018,23 @@ export interface Product {
         platform_managed?: boolean;
         [k: string]: unknown | undefined;
     };
+    /**
+     * When the buyer provides a brand_manifest with product_catalog, indicates which of the buyer's catalog items are eligible for this product. Enables buyers to make informed product_selector choices in create_media_buy. Only present for products where catalog matching is relevant (e.g. sponsored product listings on retail media). Sellers SHOULD include at least one of matched_gtins or matched_skus.
+     */
+    catalog_match?: {
+        /**
+         * GTINs from the buyer's catalog that are eligible on this product's inventory. Buyers can use these values in product_selectors.manifest_gtins when creating media buys. Standard GTIN formats (GTIN-8 through GTIN-14).
+         */
+        matched_gtins?: string[];
+        /**
+         * SKUs from the buyer's catalog that are eligible on this product's inventory. Buyers can use these values in product_selectors.manifest_skus when creating media buys.
+         */
+        matched_skus?: string[];
+        /**
+         * Total catalog items evaluated from the buyer's feed.
+         */
+        submitted_count: number;
+    };
     /**
      * Explanation of why this product matches the brief (only included when brief is provided)
      */
@@ -1362,8 +1403,9 @@ export interface CPPPricingOption {
      * CPP-specific parameters for demographic targeting
      */
     parameters: {
+        demographic_system?: DemographicSystem;
         /**
-         * Target demographic in Nielsen format (P18-49, M25-54, W35+, etc.)
+         * Target demographic code within the specified demographic_system (e.g., P18-49 for Nielsen, ABC1 Adults for BARB)
          */
         demographic: string;
         /**
@@ -1770,6 +1812,7 @@ export interface Proposal {
      * Explanation of how this proposal aligns with the campaign brief
      */
     brief_alignment?: string;
+    forecast?: DeliveryForecast1;
     ext?: ExtensionObject;
     [k: string]: unknown | undefined;
 }
@@ -1801,6 +1844,136 @@ export interface ProductAllocation {
      * Categorical tags for this allocation (e.g., 'desktop', 'german', 'mobile') - useful for grouping/filtering allocations by dimension
      */
     tags?: string[];
+    /**
+     * Recommended time windows for this allocation in spot-plan proposals.
+     *
+     * @minItems 1
+     */
+    daypart_targets?: [DaypartTarget, ...DaypartTarget[]];
+    forecast?: DeliveryForecast;
+    ext?: ExtensionObject;
+    [k: string]: unknown | undefined;
+}
+/**
+ * A time window for daypart targeting. Specifies days of week and an hour range. start_hour is inclusive, end_hour is exclusive (e.g., 6-10 = 6:00am to 10:00am). Follows the Google Ads AdScheduleInfo / DV360 DayPartTargeting pattern.
+ */
+export interface DaypartTarget {
+    /**
+     * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object).
+     *
+     * @minItems 1
+     */
+    days: [DayOfWeek, ...DayOfWeek[]];
+    /**
+     * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm.
+     */
+    start_hour: number;
+    /**
+     * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour.
+     */
+    end_hour: number;
+    /**
+     * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
+     */
+    label?: string;
+}
+/**
+ * Forecasted delivery metrics for this allocation
+ */
+export interface DeliveryForecast {
+    /**
+     * Forecasted delivery at one or more budget levels. A single point is a standard forecast; multiple points ordered by ascending budget form a curve showing how metrics scale with spend. Each point pairs a budget with metric ranges.
+     *
+     * @minItems 1
+     */
+    points: [ForecastPoint, ...ForecastPoint[]];
+    forecast_range_unit?: ForecastRangeUnit;
+    method: ForecastMethod;
+    /**
+     * ISO 4217 currency code for monetary values in this forecast (spend, budget)
+     */
+    currency: string;
+    demographic_system?: DemographicSystem1;
+    /**
+     * Target demographic code within the specified demographic_system. For Nielsen: P18-49, M25-54, W35+. For BARB: ABC1 Adults, 16-34. For AGF: E 14-49.
+     */
+    demographic?: string;
+    reach_unit?: ReachUnit;
+    /**
+     * When this forecast was computed
+     */
+    generated_at?: string;
+    /**
+     * When this forecast expires. After this time, the forecast should be refreshed. Forecast expiry does not affect proposal executability.
+     */
+    valid_until?: string;
+    ext?: ExtensionObject;
+    [k: string]: unknown | undefined;
+}
+/**
+ * A forecast at a specific budget level. A single point represents a standard forecast; multiple points ordered by ascending budget form a curve showing how delivery metrics scale with spend.
+ */
+export interface ForecastPoint {
+    /**
+     * Budget amount for this forecast point. For allocation-level forecasts, this is the absolute budget for that allocation (not the percentage). For proposal-level forecasts, this is the total proposal budget.
+     */
+    budget: number;
+    /**
+     * Forecasted metric values at this budget level. Keys are either forecastable-metric values for delivery/engagement (impressions, reach, spend, etc.) or event-type values for outcomes (purchase, lead, app_install, etc.). Values are ForecastRange objects (low/mid/high). Use { "mid": value } for point estimates. Include spend when the platform predicts it will differ from budget.
+     */
+    metrics: {
+        [k: string]: ForecastRange | undefined;
+    };
+    [k: string]: unknown | undefined;
+}
+/**
+ * A forecast value with optional low/high bounds. The mid value represents the most likely outcome. When low and high are provided, they represent conservative and optimistic estimates respectively.
+ */
+export interface ForecastRange {
+    /**
+     * Conservative (low-end) forecast value
+     */
+    low?: number;
+    /**
+     * Expected (most likely) forecast value
+     */
+    mid: number;
+    /**
+     * Optimistic (high-end) forecast value
+     */
+    high?: number;
+    [k: string]: unknown | undefined;
+}
+/**
+ * Aggregate forecasted delivery metrics for the entire proposal. When both proposal-level and allocation-level forecasts are present, the proposal-level forecast is authoritative for total delivery estimation.
+ */
+export interface DeliveryForecast1 {
+    /**
+     * Forecasted delivery at one or more budget levels. A single point is a standard forecast; multiple points ordered by ascending budget form a curve showing how metrics scale with spend. Each point pairs a budget with metric ranges.
+     *
+     * @minItems 1
+     */
+    points: [ForecastPoint, ...ForecastPoint[]];
+    forecast_range_unit?: ForecastRangeUnit;
+    method: ForecastMethod;
+    /**
+     * ISO 4217 currency code for monetary values in this forecast (spend, budget)
+     */
+    currency: string;
+    demographic_system?: DemographicSystem1;
+    /**
+     * Target demographic code within the specified demographic_system. For Nielsen: P18-49, M25-54, W35+. For BARB: ABC1 Adults, 16-34. For AGF: E 14-49.
+     */
+    demographic?: string;
+    reach_unit?: ReachUnit;
+    /**
+     * When this forecast was computed
+     */
+    generated_at?: string;
+    /**
+     * When this forecast expires. After this time, the forecast should be refreshed. Forecast expiry does not affect proposal executability.
+     */
+    valid_until?: string;
     ext?: ExtensionObject;
     [k: string]: unknown | undefined;
 }
@@ -2161,7 +2334,7 @@ export type PostalCodeSystem = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'g
  */
 export type PostalCodeSystem1 = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'gb_full' | 'ca_fsa' | 'ca_full' | 'de_plz' | 'fr_code_postal' | 'au_postcode';
 /**
- * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
+ * Days of the week for daypart targeting
  */
 export type AgeVerificationMethod = 'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id';
 /**
@@ -2349,9 +2522,9 @@ export interface CreateMediaBuyRequest {
      */
     buyer_ref: string;
     /**
-     * Account to bill for this media buy. The seller maps the agent's brand + operator to an account during sync_accounts; the agent passes that account_id here.
+     * Account to bill for this media buy. Required when the agent has access to multiple accounts; when omitted, the seller uses the agent's sole account. The seller maps the agent's brand + operator to an account during sync_accounts; the agent passes that account_id here.
      */
-    account_id: string;
+    account_id?: string;
     /**
      * 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.
      */
@@ -2645,6 +2818,12 @@ export interface TargetingOverlay {
             values: [string, ...string[]];
         }[]
     ];
+    /**
+     * Restrict delivery to specific time windows. Each entry specifies days of week and an hour range.
+     *
+     * @minItems 1
+     */
+    daypart_targets?: [DaypartTarget, ...DaypartTarget[]];
     /**
      * AXE segment ID to include for targeting
      */
@@ -2689,7 +2868,7 @@ export interface TargetingOverlay {
     [k: string]: unknown | undefined;
 }
 /**
- * Frequency capping settings for package-level application
+ * A time window for daypart targeting. Specifies days of week and an hour range. start_hour is inclusive, end_hour is exclusive (e.g., 6-10 = 6:00am to 10:00am). Follows the Google Ads AdScheduleInfo / DV360 DayPartTargeting pattern.
  */
 export interface FrequencyCap {
     /**
@@ -3255,7 +3434,7 @@ export interface Account {
      */
     account_id: string;
     /**
-     * Human-readable account name (e.g., 'Coke', 'Coke c/o Publicis')
+     * Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')
      */
     name: string;
     /**
@@ -8677,7 +8856,7 @@ export interface SyncAccountsRequest {
      */
     accounts: {
         /**
-         * House domain where brand.json is hosted (e.g., 'unilever.com', 'coca-cola.com'). This is the canonical identity anchor for the brand, resolved via /.well-known/brand.json. For single-brand houses, this alone identifies the brand.
+         * House domain where brand.json is hosted (e.g., 'unilever.com', 'acme-corp.com'). This is the canonical identity anchor for the brand, resolved via /.well-known/brand.json. For single-brand houses, this alone identifies the brand.
          */
         house: string;
         /**