@adcp/client 4.18.2 → 4.20.0

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

@@ -133,6 +133,10 @@ export type SignalID = {
      */
     id: string;
 };
+/**
+ * Postal code system (e.g., 'us_zip', 'gb_outward')
+ */
+export type PostalCodeSystem = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'gb_full' | 'ca_fsa' | 'ca_full' | 'de_plz' | 'fr_code_postal' | 'au_postcode' | 'ch_plz' | 'at_plz';
 /**
  * Request parameters for discovering or refining advertising products. buying_mode declares the buyer's intent: 'brief' for curated discovery, 'wholesale' for raw catalog access, or 'refine' to iterate on known products and proposals.
  */
@@ -439,6 +443,35 @@ export interface ProductFilters {
      * Filter to products supporting specific signals from data provider catalogs. Products must have the requested signals in their data_provider_signals and signal_targeting_allowed must be true (or all signals requested).
      */
     signal_targeting?: SignalTargeting[];
+    /**
+     * Filter by postal area coverage for locally-bound inventory (direct mail, DOOH, local campaigns). Use when products have postal-area-specific coverage. For digital inventory where products have broad coverage, use required_geo_targeting instead to filter by seller capability.
+     */
+    postal_areas?: {
+        system: PostalCodeSystem;
+        /**
+         * Postal codes within the system (e.g., ['10001', '10002'] for us_zip)
+         */
+        values: string[];
+    }[];
+    /**
+     * Filter by proximity to geographic points. Returns products with inventory coverage near these locations. Follows the same format as the targeting overlay — each entry uses exactly one method: travel_time + transport_mode, radius, or geometry. For locally-bound inventory (DOOH, radio), filters to products with coverage in the area. For digital inventory, filters to products from sellers supporting geo_proximity targeting.
+     */
+    geo_proximity?: {
+        [k: string]: unknown | undefined;
+    }[];
+    /**
+     * Filter by keyword relevance for search and retail media platforms. Returns products that support keyword targeting for these terms. Allows the sell-side agent to assess keyword availability and recommend appropriate products. Use match_type to indicate the desired precision.
+     */
+    keywords?: {
+        /**
+         * The keyword to target
+         */
+        keyword: string;
+        /**
+         * Desired match type: broad matches related queries, phrase matches queries containing the keyword phrase, exact matches the query exactly. Defaults to broad.
+         */
+        match_type?: 'broad' | 'phrase' | 'exact';
+    }[];
 }
 /**
  * Structured format identifier with agent URL and format name. Can reference: (1) a concrete format with fixed dimensions (id only), (2) a template format without parameters (id only), or (3) a template format with parameters (id + dimensions/duration). Template formats accept parameters in format_id while concrete formats have fixed dimensions in their definition. Parameterized format IDs create unique, specific format variants.
@@ -603,9 +636,9 @@ export type PriceAdjustmentKind = 'fee' | 'discount' | 'commission' | 'settlemen
  */
 export type DemographicSystem = 'nielsen' | 'barb' | 'agf' | 'oztam' | 'mediametrie' | 'custom';
 /**
- * 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.
+ * How to interpret the points array. 'spend' (default when omitted): points at ascending budget levels. 'availability': total available inventory, budget omitted. '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';
+export type ForecastRangeUnit = 'spend' | 'availability' | 'reach_freq' | 'weekly' | 'daily' | 'clicks' | 'conversions';
 /**
  * Method used to produce this forecast
  */
@@ -1504,7 +1537,7 @@ export interface TimeBasedPricingOption {
  */
 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.
+     * Forecasted delivery data points. For spend curves (default), points at ascending budget levels show how metrics scale with spend. For availability forecasts, points represent total available inventory independent of budget. See forecast_range_unit for interpretation.
      */
     points: ForecastPoint[];
     forecast_range_unit?: ForecastRangeUnit;
@@ -1530,15 +1563,15 @@ export interface DeliveryForecast {
     ext?: ExtensionObject;
 }
 /**
- * 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.
+ * A forecast data point. When budget is present, the point pairs a spend level with expected delivery — multiple points at ascending budgets form a curve. When budget is omitted, the point represents total available inventory for the requested targeting and dates, independent of 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 amount for this forecast point. Required for spend curves; omit for availability forecasts where the metrics represent total available inventory. 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. When omitted, use metrics.spend to express the estimated cost of the available inventory.
      */
-    budget: number;
+    budget?: number;
     /**
-     * Forecasted metric values at this budget level. Keys are forecastable-metric enum values for delivery/engagement or event-type enum values for outcomes. Values are ForecastRange objects (low/mid/high). Use { "mid": value } for point estimates. Include spend when the platform predicts it will differ from budget. Additional keys beyond the documented properties are allowed for event-type values (purchase, lead, app_install, etc.).
+     * Forecasted metric values. Keys are forecastable-metric enum values for delivery/engagement or event-type enum values for outcomes. Values are ForecastRange objects (low/mid/high). Use { "mid": value } for point estimates. When budget is present, these are the expected metrics at that spend level. When budget is omitted, these represent total available inventory — use spend to express the estimated cost. Additional keys beyond the documented properties are allowed for event-type values (purchase, lead, app_install, etc.).
      */
     metrics: {
         audience_size?: ForecastRange;
@@ -2578,10 +2611,6 @@ export type OptimizationGoal = {
      */
     priority?: number;
 };
-/**
- * Postal code system (e.g., 'us_zip', 'gb_outward'). System name encodes country and precision.
- */
-export type PostalCodeSystem = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'gb_full' | 'ca_fsa' | 'ca_full' | 'de_plz' | 'fr_code_postal' | 'au_postcode' | 'ch_plz' | 'at_plz';
 /**
  * Frequency capping settings for package-level application. Two types of frequency control can be used independently or together: suppress enforces a cooldown between consecutive exposures; max_impressions + per + window caps total exposures per entity in a time window. When both suppress and max_impressions are set, an impression is delivered only if both constraints permit it (AND semantics). At least one of suppress, suppress_minutes, or max_impressions must be set.
  */
@@ -2801,6 +2830,10 @@ export type CatalogAsset = Catalog;
  * For generative creatives: set to 'approved' to finalize, 'rejected' to request regeneration with updated assets/message. Omit for non-generative creatives (system will set based on processing state).
  */
 export type CreativeStatus = 'processing' | 'pending_review' | 'approved' | 'rejected' | 'archived';
+/**
+ * Industry classification for this specific campaign. A brand may operate across multiple industries (brand.json industries field), but each media buy targets one. For example, a consumer health company running a wellness campaign sends 'healthcare.wellness', not 'cpg'. Sellers map this to platform-native codes (e.g., Spotify ADV categories, LinkedIn industry IDs). When omitted, sellers may infer from the brand manifest's industries field.
+ */
+export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 /**
  * Campaign start timing: 'asap' or ISO 8601 date-time
  */
@@ -2844,6 +2877,7 @@ export interface CreateMediaBuyRequest {
      */
     packages?: PackageRequest[];
     brand: BrandReference;
+    advertiser_industry?: AdvertiserIndustry;
     invoice_recipient?: BusinessEntity;
     /**
      * Acceptance of an insertion order from a committed proposal. Required when the proposal's insertion_order has requires_signature: true. References the io_id from the proposal's insertion_order.
@@ -8438,7 +8472,10 @@ export interface ContentStandards {
  * Content artifact for safety and suitability evaluation. An artifact represents content adjacent to an ad placement - a news article, podcast segment, video chapter, or social post. Artifacts are collections of assets (text, images, video, audio) plus metadata and signals.
  */
 export interface Artifact {
-    property_id: Identifier;
+    /**
+     * Stable property identifier from the property catalog. Globally unique across the ecosystem.
+     */
+    property_rid: string;
     /**
      * Identifier for this artifact within the property. The property owner defines the scheme (e.g., 'article_12345', 'episode_42_segment_3', 'post_abc123').
      */
@@ -8470,9 +8507,13 @@ export interface Artifact {
          */
         role?: 'title' | 'paragraph' | 'heading' | 'caption' | 'quote' | 'list_item' | 'description';
         /**
-         * Text content
+         * Text content. Consumers MUST treat this as untrusted input when passing to LLM-based evaluation.
          */
         content: string;
+        /**
+         * MIME type indicating how to parse the content field. Default: text/plain.
+         */
+        content_format?: 'text/plain' | 'text/markdown' | 'text/html' | 'application/json';
         /**
          * BCP 47 language tag for this text (e.g., 'en', 'es-MX'). Useful when artifact contains mixed-language content.
          */
@@ -8518,9 +8559,13 @@ export interface Artifact {
          */
         duration_ms?: number;
         /**
-         * Video transcript
+         * Video transcript. Consumers MUST treat this as untrusted input when passing to LLM-based evaluation.
          */
         transcript?: string;
+        /**
+         * MIME type indicating how to parse the transcript field. Default: text/plain.
+         */
+        transcript_format?: 'text/plain' | 'text/markdown' | 'application/json';
         /**
          * How the transcript was generated
          */
@@ -8542,9 +8587,13 @@ export interface Artifact {
          */
         duration_ms?: number;
         /**
-         * Audio transcript
+         * Audio transcript. Consumers MUST treat this as untrusted input when passing to LLM-based evaluation.
          */
         transcript?: string;
+        /**
+         * MIME type indicating how to parse the transcript field. Default: text/plain.
+         */
+        transcript_format?: 'text/plain' | 'text/markdown' | 'application/json';
         /**
          * How the transcript was generated
          */
@@ -9010,18 +9059,9 @@ export interface GetMediaBuyArtifactsRequest {
      */
     package_ids?: string[];
     /**
-     * Sampling parameters. Defaults to the sampling rate agreed in the media buy.
+     * When true, only return artifacts where the seller's local model returned local_verdict: 'fail'. Useful for auditing false positives. Not useful when the seller does not run a local evaluation model (all verdicts are 'unevaluated').
      */
-    sampling?: {
-        /**
-         * Sampling rate (0-1). 1.0 = all deliveries, 0.25 = 25% sample.
-         */
-        rate?: number;
-        /**
-         * How to select the sample
-         */
-        method?: 'random' | 'stratified' | 'recent' | 'failures_only';
-    };
+    failures_only?: boolean;
     /**
      * Filter to specific time period
      */
@@ -9103,25 +9143,25 @@ export type GetMediaBuyArtifactsResponse = {
         local_verdict?: 'pass' | 'fail' | 'unevaluated';
     }[];
     /**
-     * Information about how the sample was generated
+     * Information about artifact collection for this media buy. Sampling is configured at buy creation time — this reports what was actually collected.
      */
-    sampling_info?: {
+    collection_info?: {
         /**
-         * Total deliveries in the time range
+         * Total deliveries in the requested time range
          */
         total_deliveries?: number;
         /**
-         * Number of artifacts in this response
+         * Total artifacts collected (per the buy's sampling configuration)
          */
-        sampled_count?: number;
+        total_collected?: number;
         /**
-         * Actual sampling rate achieved
+         * Number of artifacts in this response (may be less than total_collected due to pagination or filters)
          */
-        effective_rate?: number;
+        returned_count?: number;
         /**
-         * Sampling method used
+         * Actual collection rate achieved (total_collected / total_deliveries)
          */
-        method?: 'random' | 'stratified' | 'recent' | 'failures_only';
+        effective_rate?: number;
     };
     pagination?: PaginationResponse;
     context?: ContextObject;
@@ -9213,10 +9253,6 @@ export type RestrictedAttribute = 'racial_ethnic_origin' | 'political_opinions'
  * Authority level granted to this agent.
  */
 export type DelegationAuthority = 'full' | 'execute_only' | 'propose_only';
-/**
- * Governance enforcement mode for this plan. 'enforce': denied actions are blocked. 'advisory': denied actions proceed with findings logged. 'audit': all actions proceed, findings logged. Defaults to 'enforce' if omitted.
- */
-export type GovernanceMode = 'audit' | 'advisory' | 'enforce';
 /**
  * Push campaign plans to the governance agent. A plan defines the authorized parameters for a campaign -- budget limits, channels, flight dates, and authorized markets.
  */
@@ -9377,7 +9413,6 @@ export interface SyncPlansRequest {
              */
             shared_exclusions?: string[];
         };
-        mode?: GovernanceMode;
         ext?: ExtensionObject;
     }[];
 }
@@ -9696,7 +9731,10 @@ export interface GetPlanAuditLogsResponse {
                 approved?: number;
                 denied?: number;
                 conditions?: number;
-                escalated?: number;
+                /**
+                 * Supplementary count of checks that went through internal human review. These checks are also counted in approved or denied.
+                 */
+                human_reviewed?: number;
             };
             /**
              * Total findings across all checks and outcomes.
@@ -9801,11 +9839,11 @@ export interface GetPlanAuditLogsResponse {
             /**
              * Governance check status (present for check entries).
              */
-            status?: 'approved' | 'denied' | 'conditions' | 'escalated';
+            status?: 'approved' | 'denied' | 'conditions';
             /**
-             * Whether the check was proposed or committed (present for check entries).
+             * Whether the check was an intent check (orchestrator) or execution check (seller). Inferred from the fields present on the original check request. Present for check entries.
              */
-            binding?: 'proposed' | 'committed';
+            check_type?: 'intent' | 'execution';
             /**
              * Human-readable explanation of the governance decision (present for check entries).
              */
@@ -9870,7 +9908,7 @@ export interface GetPlanAuditLogsResponse {
  */
 export type GovernancePhase = 'purchase' | 'modification' | 'delivery';
 /**
- * Universal governance check for campaign actions. Called by the orchestrator before sending to a seller (proposed) or by the seller before executing (committed). The governance agent evaluates the action against the campaign plan and returns a status.
+ * Universal governance check for campaign actions. The governance agent infers the check type from the fields present: tool+payload (intent check, orchestrator) or media_buy_id+planned_delivery (execution check, seller).
  */
 export interface CheckGovernanceRequest {
     /**
@@ -9878,19 +9916,15 @@ export interface CheckGovernanceRequest {
      */
     plan_id: string;
     /**
-     * Whether this is an advisory check or a binding commitment. 'proposed': the orchestrator is checking before sending to a seller — no budget is committed. 'committed': the seller is about to execute — the governance agent validates the planned delivery against the plan. Budget is committed later via report_plan_outcome, not on approval.
-     */
-    binding: 'proposed' | 'committed';
-    /**
-     * URL of the agent making the request (orchestrator for proposed, seller for committed).
+     * URL of the agent making the request.
      */
     caller: string;
     /**
-     * The AdCP tool being checked (e.g., 'create_media_buy', 'get_products'). Expected for proposed checks. The governance agent uses this to apply tool-specific validation rules.
+     * The AdCP tool being checked (e.g., 'create_media_buy', 'get_products'). Present on intent checks (orchestrator). The governance agent uses the presence of tool+payload to identify an intent check.
      */
     tool?: string;
     /**
-     * The full tool arguments as they would be sent to the seller. Expected for proposed checks. The governance agent can inspect any field to validate against the plan.
+     * The full tool arguments as they would be sent to the seller. Present on intent checks. The governance agent can inspect any field to validate against the plan.
      */
     payload?: {};
     /**
@@ -9898,7 +9932,7 @@ export interface CheckGovernanceRequest {
      */
     governance_context?: string;
     /**
-     * The seller's identifier for the media buy. Expected for committed checks.
+     * The seller's identifier for the media buy. Present on execution checks (seller). The governance agent uses the presence of media_buy_id+planned_delivery to identify an execution check.
      */
     media_buy_id?: string;
     phase?: GovernancePhase;
@@ -9987,13 +10021,9 @@ export interface CheckGovernanceResponse {
      */
     check_id: string;
     /**
-     * Governance decision. 'approved': proceed as planned. 'denied': do not proceed. 'conditions': approved if the caller accepts the listed conditions, then re-calls check_governance with the adjusted parameters. 'escalated': halted pending human review.
-     */
-    status: 'approved' | 'denied' | 'conditions' | 'escalated';
-    /**
-     * Echoed from request. Lets the caller confirm the governance agent understood the commitment level.
+     * Governance decision. 'approved': proceed as planned. 'denied': do not proceed. 'conditions': approved if the caller accepts the listed conditions, then re-calls check_governance with the adjusted parameters.
      */
-    binding: 'proposed' | 'committed';
+    status: 'approved' | 'denied' | 'conditions';
     /**
      * Echoed from request.
      */
@@ -10002,9 +10032,8 @@ export interface CheckGovernanceResponse {
      * Human-readable explanation of the governance decision.
      */
     explanation: string;
-    mode?: GovernanceMode;
     /**
-     * Specific issues found during the governance check. Present when status is 'denied', 'conditions', or 'escalated'. MAY also be present on 'approved' for advisory findings (e.g., budget approaching limit).
+     * Specific issues found during the governance check. Present when status is 'denied' or 'conditions'. MAY also be present on 'approved' for informational findings (e.g., budget approaching limit).
      */
     findings?: {
         /**
@@ -10052,24 +10081,6 @@ export interface CheckGovernanceResponse {
          */
         reason: string;
     }[];
-    /**
-     * Present when status is 'escalated'. The action is halted pending human review.
-     */
-    escalation?: {
-        /**
-         * Human-readable explanation of why the action was escalated.
-         */
-        reason: string;
-        severity: EscalationSeverity;
-        /**
-         * Whether human approval is required before proceeding.
-         */
-        requires_human: boolean;
-        /**
-         * Organizational role or tier required to resolve this escalation. The value is organization-defined; the governance agent infers the tier from the escalation context. Common values include 'manager', 'director', 'legal', 'cfo'. Enables programmatic routing of escalations to the right person.
-         */
-        approval_tier?: string;
-    };
     /**
      * When this approval expires. Present when status is 'approved' or 'conditions'. The caller must act before this time or re-call check_governance. A lapsed approval is no approval.
      */
@@ -10791,7 +10802,20 @@ export interface GetAdCPCapabilitiesResponse {
          */
         execution?: {
             /**
-             * Agentic ad exchange (AXE) integrations supported. URLs are canonical identifiers for exchanges this seller can execute through.
+             * Trusted Match Protocol (TMP) support. When present, this seller supports real-time contextual and/or identity matching. Check individual products via get_products for per-product TMP capabilities.
+             */
+            trusted_match?: {
+                /**
+                 * Whether this seller has TMP infrastructure deployed.
+                 */
+                supported?: boolean;
+                /**
+                 * Surface types this seller supports via TMP.
+                 */
+                surfaces?: ('website' | 'mobile_app' | 'ctv_app' | 'desktop_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio' | 'ai_assistant')[];
+            };
+            /**
+             * Deprecated. Legacy AXE integrations. Use trusted_match for new integrations.
              */
             axe_integrations?: string[];
             /**
@@ -11038,6 +11062,23 @@ export interface GetAdCPCapabilitiesResponse {
                 post_view?: Duration[];
             }[];
         };
+        /**
+         * Content standards implementation details. Only meaningful when features.content_standards is true. Gives buyers pre-buy visibility into local evaluation and artifact delivery capabilities.
+         */
+        content_standards_detail?: {
+            /**
+             * Whether the seller runs a local evaluation model. When false, all artifacts will have local_verdict: 'unevaluated' and the failures_only filter on get_media_buy_artifacts is not useful.
+             */
+            supports_local_evaluation?: boolean;
+            /**
+             * Channels for which the seller can provide content artifacts. Helps buyers understand which parts of a mixed-channel buy will have content standards coverage.
+             */
+            supported_channels?: MediaChannel[];
+            /**
+             * Whether the seller supports push-based artifact delivery via artifact_webhook configured at buy creation time.
+             */
+            supports_webhook_delivery?: boolean;
+        };
         /**
          * Information about the seller's media inventory portfolio
          */