@adcp/client 4.18.1 → 4.19.0

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

@@ -57,6 +57,10 @@ export type MetroAreaSystem = 'nielsen_dma' | 'uk_itl1' | 'uk_itl2' | 'eurostat_
  * 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 MediaChannel = 'display' | 'olv' | 'social' | 'search' | 'ctv' | 'linear_tv' | 'radio' | 'streaming_audio' | 'podcast' | 'dooh' | 'ooh' | 'print' | 'cinema' | 'email' | 'gaming' | 'retail_media' | 'influencer' | 'affiliate' | 'product_placement' | 'sponsored_intelligence';
+/**
+ * What the publisher wants back from a TMP context match. Determines the richness level of the buyer's offer response.
+ */
+export type TMPResponseType = 'activation' | 'catalog_items' | 'creative' | 'deal';
 /**
  * Geographic targeting level (country, region, metro, postal_area)
  */
@@ -129,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.
  */
@@ -200,7 +208,7 @@ export interface GetProductsRequest {
     /**
      * Specific product fields to include in the response. When omitted, all fields are returned. Use for lightweight discovery calls where only a subset of product data is needed (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.
      */
-    fields?: ('product_id' | 'name' | 'description' | 'publisher_properties' | 'channels' | 'format_ids' | 'placements' | 'delivery_type' | 'exclusivity' | 'pricing_options' | 'forecast' | 'outcome_measurement' | 'delivery_measurement' | 'reporting_capabilities' | 'creative_policy' | 'catalog_types' | 'metric_optimization' | 'conversion_tracking' | 'data_provider_signals' | 'max_optimization_goals' | 'catalog_match' | 'collections' | 'collection_targeting_allowed' | 'installments' | 'brief_relevance' | 'expires_at' | 'product_card' | 'product_card_detailed' | 'enforced_policies')[];
+    fields?: ('product_id' | 'name' | 'description' | 'publisher_properties' | 'channels' | 'format_ids' | 'placements' | 'delivery_type' | 'exclusivity' | 'pricing_options' | 'forecast' | 'outcome_measurement' | 'delivery_measurement' | 'reporting_capabilities' | 'creative_policy' | 'catalog_types' | 'metric_optimization' | 'conversion_tracking' | 'data_provider_signals' | 'max_optimization_goals' | 'catalog_match' | 'collections' | 'collection_targeting_allowed' | 'installments' | 'brief_relevance' | 'expires_at' | 'product_card' | 'product_card_detailed' | 'enforced_policies' | 'trusted_match')[];
     /**
      * Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing.
      */
@@ -390,9 +398,36 @@ export interface ProductFilters {
      */
     channels?: MediaChannel[];
     /**
-     * Filter to products executable through specific agentic ad exchanges. URLs are canonical identifiers.
+     * @deprecated
+     * Deprecated: Use trusted_match filter instead. Filter to products executable through specific agentic ad exchanges. URLs are canonical identifiers.
      */
     required_axe_integrations?: string[];
+    /**
+     * Filter products by Trusted Match Protocol capabilities. Only products with matching TMP support are returned.
+     */
+    trusted_match?: {
+        /**
+         * Filter to products with specific TMP providers and match types. Each entry identifies a provider by agent_url and optionally requires specific match capabilities. Products must match at least one entry.
+         */
+        providers?: {
+            /**
+             * Provider's agent URL from the registry.
+             */
+            agent_url: string;
+            /**
+             * When true, require this provider to support context match.
+             */
+            context_match?: boolean;
+            /**
+             * When true, require this provider to support identity match.
+             */
+            identity_match?: boolean;
+        }[];
+        /**
+         * Filter to products supporting specific TMP response types (e.g., 'activation', 'creative', 'catalog_items'). Products must support at least one of the listed types.
+         */
+        response_types?: TMPResponseType[];
+    };
     required_features?: MediaBuyFeatures;
     /**
      * Filter to products from sellers supporting specific geo targeting capabilities. Each entry specifies a targeting level (country, region, metro, postal_area) and optionally a system for levels that have multiple classification systems.
@@ -408,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.
@@ -572,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
  */
@@ -666,10 +730,6 @@ export type TalentRole = 'host' | 'guest' | 'creator' | 'cast' | 'narrator' | 'p
  * What kind of derivative content this is
  */
 export type DerivativeType = 'clip' | 'highlight' | 'recap' | 'trailer' | 'bonus';
-/**
- * What the publisher wants back from a TMP context match. Determines the richness level of the buyer's offer response.
- */
-export type TMPResponseType = 'activation' | 'catalog_items' | 'creative' | 'deal';
 /**
  * Days of the week for daypart targeting
  */
@@ -951,6 +1011,23 @@ export interface Product {
          * Whether the buyer can select a brand at match time. When false (default), the brand must be specified on the media buy/package. When true, the buyer's offer can include any brand — the publisher applies approval rules at match time. Enables multi-brand agreements where the holding company or buyer agent selects brand based on context.
          */
         dynamic_brands?: boolean;
+        /**
+         * TMP providers integrated with this product's inventory. Each entry identifies a provider by agent_url (from the registry) and declares what match types it supports for this product. The product-level context_match and identity_match booleans declare what the product supports overall; the per-provider booleans declare which provider handles each match type. Enables buyer discovery: 'find products where a specific provider does context matching.'
+         */
+        providers?: {
+            /**
+             * Provider's agent URL from the registry. Canonical identifier for this TMP provider.
+             */
+            agent_url: string;
+            /**
+             * Whether this provider handles context match for this product.
+             */
+            context_match?: boolean;
+            /**
+             * Whether this provider handles identity match for this product.
+             */
+            identity_match?: boolean;
+        }[];
     };
     /**
      * Instructions for submitting physical creative materials (print, static OOH, cinema). Present only for products requiring physical delivery outside the digital creative assignment flow. Buyer agents MUST validate url and email domains against the seller's known domains (from adagents.json) before submitting materials. Never auto-submit without human confirmation.
@@ -973,7 +1050,7 @@ export interface Product {
     ext?: ExtensionObject;
 }
 /**
- * Represents a specific ad placement within a product's inventory
+ * Represents a specific ad placement within a product's inventory. When the publisher declares a placement registry in adagents.json, products SHOULD reuse those placement_id values. Reusing a registered placement_id preserves the registry's semantic identity; product-level placement objects may narrow format_ids or add operational detail, but SHOULD NOT redefine the placement's meaning incompatibly.
  */
 export interface Placement {
     /**
@@ -988,6 +1065,10 @@ export interface Placement {
      * Detailed description of where and how the placement appears
      */
     description?: string;
+    /**
+     * Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope.
+     */
+    tags?: string[];
     /**
      * Format IDs supported by this specific placement. Can include: (1) concrete format_ids (fixed dimensions), (2) template format_ids without parameters (accepts any dimensions/duration), or (3) parameterized format_ids (specific dimension/duration constraints).
      */
@@ -1456,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;
@@ -1482,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;
@@ -2530,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.
  */
@@ -2996,11 +3073,13 @@ export interface TargetingOverlay {
      */
     daypart_targets?: DaypartTarget[];
     /**
-     * AXE segment ID to include for targeting
+     * @deprecated
+     * Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.
      */
     axe_include_segment?: string;
     /**
-     * AXE segment ID to exclude from targeting
+     * @deprecated
+     * Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.
      */
     axe_exclude_segment?: string;
     /**
@@ -9163,10 +9242,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.
  */
@@ -9327,7 +9402,6 @@ export interface SyncPlansRequest {
              */
             shared_exclusions?: string[];
         };
-        mode?: GovernanceMode;
         ext?: ExtensionObject;
     }[];
 }
@@ -9646,7 +9720,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.
@@ -9751,11 +9828,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).
              */
@@ -9820,7 +9897,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 {
     /**
@@ -9828,19 +9905,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?: {};
     /**
@@ -9848,7 +9921,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;
@@ -9937,13 +10010,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.
+     * 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.
      */
-    status: 'approved' | 'denied' | 'conditions' | 'escalated';
-    /**
-     * Echoed from request. Lets the caller confirm the governance agent understood the commitment level.
-     */
-    binding: 'proposed' | 'committed';
+    status: 'approved' | 'denied' | 'conditions';
     /**
      * Echoed from request.
      */
@@ -9952,9 +10021,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?: {
         /**
@@ -10002,24 +10070,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.
      */