adcp 1.5.0__py3-none-any.whl → 1.6.1__py3-none-any.whl

adcp/__init__.py

@@ -7,8 +7,21 @@ Official Python client for the Ad Context Protocol (AdCP).
 Supports both A2A and MCP protocols with full type safety.
 """
 
+from adcp.adagents import (
+    domain_matches,
+    fetch_adagents,
+    get_all_properties,
+    get_all_tags,
+    get_properties_by_agent,
+    identifiers_match,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
 from adcp.client import ADCPClient, ADCPMultiAgentClient
 from adcp.exceptions import (
+    AdagentsNotFoundError,
+    AdagentsTimeoutError,
+    AdagentsValidationError,
     ADCPAuthenticationError,
     ADCPConnectionError,
     ADCPError,
@@ -150,7 +163,7 @@ from adcp.types.generated import (
     TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.5.0"
+__version__ = "1.6.1"
 
 __all__ = [
     # Client classes
@@ -162,6 +175,15 @@ __all__ = [
     "TaskResult",
     "TaskStatus",
     "WebhookMetadata",
+    # Adagents validation
+    "fetch_adagents",
+    "verify_agent_authorization",
+    "verify_agent_for_property",
+    "domain_matches",
+    "identifiers_match",
+    "get_all_properties",
+    "get_all_tags",
+    "get_properties_by_agent",
     # Test helpers
     "test_agent",
     "test_agent_a2a",
@@ -185,6 +207,9 @@ __all__ = [
     "ADCPToolNotFoundError",
     "ADCPWebhookError",
     "ADCPWebhookSignatureError",
+    "AdagentsValidationError",
+    "AdagentsNotFoundError",
+    "AdagentsTimeoutError",
     # Request/Response types
     "ActivateSignalRequest",
     "ActivateSignalResponse",

adcp/adagents.py

@@ -0,0 +1,521 @@
+from __future__ import annotations
+
+"""
+Utilities for fetching, parsing, and validating adagents.json files per the AdCP specification.
+
+Publishers declare authorized sales agents via adagents.json files hosted at
+https://{publisher_domain}/.well-known/adagents.json. This module provides utilities
+for sales agents to verify they are authorized for specific properties.
+"""
+
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from adcp.exceptions import AdagentsNotFoundError, AdagentsTimeoutError, AdagentsValidationError
+
+
+def _normalize_domain(domain: str) -> str:
+    """Normalize domain for comparison - strip, lowercase, remove trailing dots/slashes.
+
+    Args:
+        domain: Domain to normalize
+
+    Returns:
+        Normalized domain string
+
+    Raises:
+        AdagentsValidationError: If domain contains invalid patterns
+    """
+    domain = domain.strip().lower()
+    # Remove both trailing slashes and dots iteratively
+    while domain.endswith("/") or domain.endswith("."):
+        domain = domain.rstrip("/").rstrip(".")
+
+    # Check for invalid patterns
+    if not domain or ".." in domain:
+        raise AdagentsValidationError(f"Invalid domain format: {domain!r}")
+
+    return domain
+
+
+def _validate_publisher_domain(domain: str) -> str:
+    """Validate and sanitize publisher domain for security.
+
+    Args:
+        domain: Publisher domain to validate
+
+    Returns:
+        Validated and normalized domain
+
+    Raises:
+        AdagentsValidationError: If domain is invalid or contains suspicious characters
+    """
+    # Check for suspicious characters BEFORE stripping (to catch injection attempts)
+    suspicious_chars = ["\\", "@", "\n", "\r", "\t"]
+    for char in suspicious_chars:
+        if char in domain:
+            raise AdagentsValidationError(
+                f"Invalid character in publisher domain: {char!r}"
+            )
+
+    domain = domain.strip()
+
+    # Check basic constraints
+    if not domain:
+        raise AdagentsValidationError("Publisher domain cannot be empty")
+    if len(domain) > 253:  # DNS maximum length
+        raise AdagentsValidationError(f"Publisher domain too long: {len(domain)} chars (max 253)")
+
+    # Check for spaces after stripping leading/trailing whitespace
+    if " " in domain:
+        raise AdagentsValidationError(
+            "Invalid character in publisher domain: ' '"
+        )
+
+    # Remove protocol if present (common user error) - do this BEFORE checking for slashes
+    if "://" in domain:
+        domain = domain.split("://", 1)[1]
+
+    # Remove path if present (should only be domain) - do this BEFORE checking for slashes
+    if "/" in domain:
+        domain = domain.split("/", 1)[0]
+
+    # Normalize
+    domain = _normalize_domain(domain)
+
+    # Final validation - must look like a domain
+    if "." not in domain:
+        raise AdagentsValidationError(
+            f"Publisher domain must contain at least one dot: {domain!r}"
+        )
+
+    return domain
+
+
+def normalize_url(url: str) -> str:
+    """Normalize URL by removing protocol and trailing slash.
+
+    Args:
+        url: URL to normalize
+
+    Returns:
+        Normalized URL (domain/path without protocol or trailing slash)
+    """
+    parsed = urlparse(url)
+    normalized = parsed.netloc + parsed.path
+    return normalized.rstrip("/")
+
+
+def domain_matches(property_domain: str, agent_domain_pattern: str) -> bool:
+    """Check if domains match per AdCP rules.
+
+    Rules:
+    - Exact match always succeeds
+    - 'example.com' matches www.example.com, m.example.com (common subdomains)
+    - 'subdomain.example.com' matches that specific subdomain only
+    - '*.example.com' matches all subdomains
+
+    Args:
+        property_domain: Domain from property
+        agent_domain_pattern: Domain pattern from adagents.json
+
+    Returns:
+        True if domains match per AdCP rules
+    """
+    # Normalize both domains for comparison
+    try:
+        property_domain = _normalize_domain(property_domain)
+        agent_domain_pattern = _normalize_domain(agent_domain_pattern)
+    except AdagentsValidationError:
+        # Invalid domain format - no match
+        return False
+
+    # Exact match
+    if property_domain == agent_domain_pattern:
+        return True
+
+    # Wildcard pattern (*.example.com)
+    if agent_domain_pattern.startswith("*."):
+        base_domain = agent_domain_pattern[2:]
+        return property_domain.endswith(f".{base_domain}")
+
+    # Bare domain matches common subdomains (www, m)
+    # If agent pattern is a bare domain (no subdomain), match www/m subdomains
+    if "." in agent_domain_pattern and not agent_domain_pattern.startswith("www."):
+        # Check if this looks like a bare domain (e.g., example.com)
+        parts = agent_domain_pattern.split(".")
+        if len(parts) == 2:  # Looks like bare domain
+            common_subdomains = ["www", "m"]
+            for subdomain in common_subdomains:
+                if property_domain == f"{subdomain}.{agent_domain_pattern}":
+                    return True
+
+    return False
+
+
+def identifiers_match(
+    property_identifiers: list[dict[str, str]],
+    agent_identifiers: list[dict[str, str]],
+) -> bool:
+    """Check if any property identifier matches agent's authorized identifiers.
+
+    Args:
+        property_identifiers: Identifiers from property
+            (e.g., [{"type": "domain", "value": "cnn.com"}])
+        agent_identifiers: Identifiers from adagents.json
+
+    Returns:
+        True if any identifier matches
+
+    Notes:
+        - Domain identifiers use AdCP domain matching rules
+        - Other identifiers (bundle_id, roku_store_id, etc.) require exact match
+    """
+    for prop_id in property_identifiers:
+        prop_type = prop_id.get("type", "")
+        prop_value = prop_id.get("value", "")
+
+        for agent_id in agent_identifiers:
+            agent_type = agent_id.get("type", "")
+            agent_value = agent_id.get("value", "")
+
+            # Type must match
+            if prop_type != agent_type:
+                continue
+
+            # Domain identifiers use special matching rules
+            if prop_type == "domain":
+                if domain_matches(prop_value, agent_value):
+                    return True
+            else:
+                # Other identifier types require exact match
+                if prop_value == agent_value:
+                    return True
+
+    return False
+
+
+def verify_agent_authorization(
+    adagents_data: dict[str, Any],
+    agent_url: str,
+    property_type: str | None = None,
+    property_identifiers: list[dict[str, str]] | None = None,
+) -> bool:
+    """Check if agent is authorized for a property.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the sales agent to verify
+        property_type: Type of property (website, app, etc.) - optional
+        property_identifiers: List of identifiers to match - optional
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+
+    Notes:
+        - If property_type/identifiers are None, checks if agent is authorized
+          for ANY property on this domain
+        - Implements AdCP domain matching rules
+        - Agent URLs are matched ignoring protocol and trailing slash
+    """
+    # Validate structure
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    # Check each authorized agent
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found matching agent - now check properties
+        properties = agent.get("properties")
+
+        # If properties field is missing or empty, agent is authorized for all properties
+        if properties is None or (isinstance(properties, list) and len(properties) == 0):
+            return True
+
+        # If no property filters specified, we found the agent - authorized
+        if property_type is None and property_identifiers is None:
+            return True
+
+        # Check specific property authorization
+        if isinstance(properties, list):
+            for prop in properties:
+                if not isinstance(prop, dict):
+                    continue
+
+                # Check property type if specified
+                if property_type is not None:
+                    prop_type = prop.get("property_type", "")
+                    if prop_type != property_type:
+                        continue
+
+                # Check identifiers if specified
+                if property_identifiers is not None:
+                    prop_identifiers = prop.get("identifiers", [])
+                    if not isinstance(prop_identifiers, list):
+                        continue
+
+                    if identifiers_match(property_identifiers, prop_identifiers):
+                        return True
+                else:
+                    # Property type matched and no identifier check needed
+                    return True
+
+    return False
+
+
+async def fetch_adagents(
+    publisher_domain: str,
+    timeout: float = 10.0,
+    user_agent: str = "AdCP-Client/1.0",
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Fetch and parse adagents.json from publisher domain.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        timeout: Request timeout in seconds
+        user_agent: User-Agent header for HTTP request
+        client: Optional httpx.AsyncClient for connection pooling.
+            If provided, caller is responsible for client lifecycle.
+            If None, a new client is created for this request.
+
+    Returns:
+        Parsed adagents.json data
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+
+    Notes:
+        For production use with multiple requests, pass a shared httpx.AsyncClient
+        to enable connection pooling and improve performance.
+    """
+    # Validate and normalize domain for security
+    publisher_domain = _validate_publisher_domain(publisher_domain)
+
+    # Construct URL
+    url = f"https://{publisher_domain}/.well-known/adagents.json"
+
+    try:
+        # Use provided client or create a new one
+        if client is not None:
+            # Reuse provided client (connection pooling)
+            response = await client.get(
+                url,
+                headers={"User-Agent": user_agent},
+                timeout=timeout,
+                follow_redirects=True,
+            )
+        else:
+            # Create new client for single request
+            async with httpx.AsyncClient() as new_client:
+                response = await new_client.get(
+                    url,
+                    headers={"User-Agent": user_agent},
+                    timeout=timeout,
+                    follow_redirects=True,
+                )
+
+        # Process response (same for both paths)
+        if response.status_code == 404:
+            raise AdagentsNotFoundError(publisher_domain)
+
+        if response.status_code != 200:
+            raise AdagentsValidationError(
+                f"Failed to fetch adagents.json: HTTP {response.status_code}"
+            )
+
+        # Parse JSON
+        try:
+            data = response.json()
+        except Exception as e:
+            raise AdagentsValidationError(f"Invalid JSON in adagents.json: {e}") from e
+
+        # Validate basic structure
+        if not isinstance(data, dict):
+            raise AdagentsValidationError("adagents.json must be a JSON object")
+
+        if "authorized_agents" not in data:
+            raise AdagentsValidationError(
+                "adagents.json must have 'authorized_agents' field"
+            )
+
+        if not isinstance(data["authorized_agents"], list):
+            raise AdagentsValidationError("'authorized_agents' must be an array")
+
+        return data
+
+    except httpx.TimeoutException as e:
+        raise AdagentsTimeoutError(publisher_domain, timeout) from e
+    except httpx.RequestError as e:
+        raise AdagentsValidationError(f"Failed to fetch adagents.json: {e}") from e
+
+
+async def verify_agent_for_property(
+    publisher_domain: str,
+    agent_url: str,
+    property_identifiers: list[dict[str, str]],
+    property_type: str | None = None,
+    timeout: float = 10.0,
+    client: httpx.AsyncClient | None = None,
+) -> bool:
+    """Convenience wrapper to fetch adagents.json and verify authorization in one call.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        agent_url: URL of the sales agent to verify
+        property_identifiers: List of identifiers to match
+        property_type: Type of property (website, app, etc.) - optional
+        timeout: Request timeout in seconds
+        client: Optional httpx.AsyncClient for connection pooling
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+    """
+    adagents_data = await fetch_adagents(publisher_domain, timeout=timeout, client=client)
+    return verify_agent_authorization(
+        adagents_data=adagents_data,
+        agent_url=agent_url,
+        property_type=property_type,
+        property_identifiers=property_identifiers,
+    )
+
+
+def get_all_properties(adagents_data: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all properties from adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        List of all properties across all authorized agents, with agent_url added
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    properties = []
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url = agent.get("url", "")
+        if not agent_url:
+            continue
+
+        agent_properties = agent.get("properties", [])
+        if not isinstance(agent_properties, list):
+            continue
+
+        # Add each property with the agent URL for reference
+        for prop in agent_properties:
+            if isinstance(prop, dict):
+                # Create a copy and add agent_url
+                prop_with_agent = {**prop, "agent_url": agent_url}
+                properties.append(prop_with_agent)
+
+    return properties
+
+
+def get_all_tags(adagents_data: dict[str, Any]) -> set[str]:
+    """Extract all unique tags from properties in adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        Set of all unique tags across all properties
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    properties = get_all_properties(adagents_data)
+    tags = set()
+
+    for prop in properties:
+        prop_tags = prop.get("tags", [])
+        if isinstance(prop_tags, list):
+            for tag in prop_tags:
+                if isinstance(tag, str):
+                    tags.add(tag)
+
+    return tags
+
+
+def get_properties_by_agent(adagents_data: dict[str, Any], agent_url: str) -> list[dict[str, Any]]:
+    """Get all properties authorized for a specific agent.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the agent to filter by
+
+    Returns:
+        List of properties for the specified agent (empty if agent not found or no properties)
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found the agent - return their properties
+        properties = agent.get("properties", [])
+        if not isinstance(properties, list):
+            return []
+
+        return [p for p in properties if isinstance(p, dict)]
+
+    return []

adcp/exceptions.py

@@ -153,3 +153,33 @@ class ADCPSimpleAPIError(ADCPError):
             f"         # Handle error with full TaskResult context"
         )
         super().__init__(message, agent_id, None, suggestion)
+
+
+class AdagentsValidationError(ADCPError):
+    """Base error for adagents.json validation issues."""
+
+
+class AdagentsNotFoundError(AdagentsValidationError):
+    """adagents.json file not found (404)."""
+
+    def __init__(self, publisher_domain: str):
+        """Initialize not found error."""
+        message = f"adagents.json not found for domain: {publisher_domain}"
+        suggestion = (
+            "Verify that the publisher has deployed adagents.json to:\n"
+            f"     https://{publisher_domain}/.well-known/adagents.json"
+        )
+        super().__init__(message, None, None, suggestion)
+
+
+class AdagentsTimeoutError(AdagentsValidationError):
+    """Request for adagents.json timed out."""
+
+    def __init__(self, publisher_domain: str, timeout: float):
+        """Initialize timeout error."""
+        message = f"Request to fetch adagents.json timed out after {timeout}s"
+        suggestion = (
+            "The publisher's server may be slow or unresponsive.\n"
+            "     Try increasing the timeout value or check the domain is correct."
+        )
+        super().__init__(message, None, None, suggestion)

adcp/types/__init__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 """Type definitions for AdCP client."""
 
+from adcp.types.base import AdCPBaseModel
 from adcp.types.core import (
     Activity,
     ActivityType,
@@ -14,6 +15,7 @@ from adcp.types.core import (
 )
 
 __all__ = [
+    "AdCPBaseModel",
     "AgentConfig",
     "Protocol",
     "TaskResult",

adcp/types/base.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+"""Base model for AdCP types with spec-compliant serialization."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class AdCPBaseModel(BaseModel):
+    """Base model for AdCP types with spec-compliant serialization.
+
+    AdCP JSON schemas use additionalProperties: false and do not allow null
+    for optional fields. Therefore, optional fields must be omitted entirely
+    when not present (not sent as null).
+    """
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump(**kwargs)
+
+    def model_dump_json(self, **kwargs: Any) -> str:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump_json(**kwargs)

adcp/types/generated.py

@@ -14,7 +14,9 @@ from __future__ import annotations
 import re
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import ConfigDict, Field, field_validator
+
+from adcp.types.base import AdCPBaseModel as BaseModel
 
 
 
@@ -945,6 +947,7 @@ class TasksListResponse(BaseModel):
 # The simple code generator produces type aliases (e.g., PreviewCreativeRequest = Any)
 # for complex schemas that use oneOf. We override them here with proper Pydantic classes
 # to maintain type safety and enable batch API support.
+# Note: All classes inherit from BaseModel (which is aliased to AdCPBaseModel for exclude_none).
 
 
 class FormatId(BaseModel):
@@ -978,7 +981,7 @@ class PreviewCreativeRequest(BaseModel):
 
     # Output format (applies to both modes)
     output_format: Literal["url", "html"] | None = Field(default="url", description="Output format: 'url' for iframe URLs, 'html' for direct embedding")
-
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 class PreviewCreativeResponse(BaseModel):
     """Response containing preview links for one or more creatives. Format matches the request: single preview response for single requests, batch results for batch requests."""
@@ -990,6 +993,7 @@ class PreviewCreativeResponse(BaseModel):
 
     # Batch mode field
     results: list[dict[str, Any]] | None = Field(default=None, description="Array of preview results for batch processing")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 # ============================================================================
@@ -1007,13 +1011,13 @@ class ActivateSignalSuccess(BaseModel):
     )
     estimated_activation_duration_minutes: float | None = None
     deployed_at: str | None = None
-
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 class ActivateSignalError(BaseModel):
     """Failed signal activation response"""
 
     errors: list[Error] = Field(description="Task-specific errors and warnings")
-
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 # Override the generated ActivateSignalResponse type alias
 ActivateSignalResponse = ActivateSignalSuccess | ActivateSignalError
@@ -1031,12 +1035,14 @@ class CreateMediaBuySuccess(BaseModel):
         None,
         description="ISO 8601 date when creatives must be provided for launch",
     )
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class CreateMediaBuyError(BaseModel):
     """Failed media buy creation response"""
 
     errors: list[Error] = Field(description="Task-specific errors and warnings")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 # Override the generated CreateMediaBuyResponse type alias
@@ -1051,13 +1057,14 @@ class UpdateMediaBuySuccess(BaseModel):
     packages: list[Package] = Field(
         description="Array of updated packages reflecting the changes"
     )
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class UpdateMediaBuyError(BaseModel):
     """Failed media buy update response"""
 
     errors: list[Error] = Field(description="Task-specific errors and warnings")
-
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 # Override the generated UpdateMediaBuyResponse type alias
 UpdateMediaBuyResponse = UpdateMediaBuySuccess | UpdateMediaBuyError
@@ -1069,13 +1076,14 @@ class SyncCreativesSuccess(BaseModel):
     assignments: list[CreativeAssignment] = Field(
         description="Array of creative assignments with updated status"
     )
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class SyncCreativesError(BaseModel):
     """Failed creative sync response"""
 
     errors: list[Error] = Field(description="Task-specific errors and warnings")
-
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 # Override the generated SyncCreativesResponse type alias
 SyncCreativesResponse = SyncCreativesSuccess | SyncCreativesError

adcp/utils/preview_cache.py

@@ -74,7 +74,11 @@ class PreviewURLGenerator:
 
         try:
             request = PreviewCreativeRequest(
-                format_id=format_id, creative_manifest=manifest, inputs=None, template_id=None
+                format_id=format_id,
+                creative_manifest=manifest,
+                inputs=None,
+                template_id=None,
+                context=None
             )
             result = await self.creative_agent_client.preview_creative(request)
 
@@ -164,6 +168,7 @@ class PreviewURLGenerator:
                 batch_request = PreviewCreativeRequest(
                     requests=chunk_requests,
                     output_format=output_format,  # type: ignore[arg-type]
+                    context=None,
                 )
                 result = await self.creative_agent_client.preview_creative(batch_request)
 

{adcp-1.5.0.dist-info → adcp-1.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.5.0
+Version: 1.6.1
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -461,6 +461,50 @@ auth = index.get_agent_authorizations("https://agent-x.com")
 premium = index.find_agents_by_property_tags(["premium", "ctv"])
 ```
 
+## Publisher Authorization Validation
+
+Verify sales agents are authorized to sell publisher properties via adagents.json:
+
+```python
+from adcp import (
+    fetch_adagents,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
+
+# Fetch and parse adagents.json from publisher
+adagents_data = await fetch_adagents("publisher.com")
+
+# Verify agent authorization for a property
+is_authorized = verify_agent_authorization(
+    adagents_data=adagents_data,
+    agent_url="https://sales-agent.example.com",
+    property_type="website",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}]
+)
+
+# Or use convenience wrapper (fetch + verify in one call)
+is_authorized = await verify_agent_for_property(
+    publisher_domain="publisher.com",
+    agent_url="https://sales-agent.example.com",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}],
+    property_type="website"
+)
+```
+
+**Domain Matching Rules:**
+- Exact match: `example.com` matches `example.com`
+- Common subdomains: `www.example.com` matches `example.com`
+- Wildcards: `api.example.com` matches `*.example.com`
+- Protocol-agnostic: `http://agent.com` matches `https://agent.com`
+
+**Use Cases:**
+- Sales agents verify authorization before accepting media buys
+- Publishers test their adagents.json files
+- Developer tools build authorization validators
+
+See `examples/adagents_validation.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-1.5.0.dist-info → adcp-1.6.1.dist-info}/RECORD

@@ -1,8 +1,9 @@
-adcp/__init__.py,sha256=Q3JzUv35ZwIU3Y97bd_wpHikojz-YFtlaekN961bakg,6976
+adcp/__init__.py,sha256=g3x4xqEGJgRcHZB6Oso3XAxs8uwNtEhk8l9TGFVcN1c,7612
 adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
+adcp/adagents.py,sha256=thq6qZScRHLWrRR4DjGlZzHpC1ZssQqhc5l0pbKSa-Q,17483
 adcp/client.py,sha256=4qoFNDT5swzi4w5bnWJ5nVTG5JIL0xnLJOJMGeMyci4,28412
 adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
-adcp/exceptions.py,sha256=9L7a3TKrMhmbEqDM0Qjdu3dQAFeKCSW4nc1IcLGSj4Y,5597
+adcp/exceptions.py,sha256=1aZEWpaM92OxD2jl9yKsqJp5ReSWaj0S0DFhxChhLlA,6732
 adcp/simple.py,sha256=FgPYWT32BNXkQz07r2x2gXgOmOikWLi88SzN5UIVSiU,10440
 adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,262
 adcp/protocols/a2a.py,sha256=FHgc6G_eU2qD0vH7_RyS1eZvUFSb2j3-EsceoHPi384,12467
@@ -10,17 +11,18 @@ adcp/protocols/base.py,sha256=vBHD23Fzl_CCk_Gy9nvSbBYopcJlYkYyzoz-rhI8wHg,5214
 adcp/protocols/mcp.py,sha256=d9uSpGd0BKvQ0JxztkfDvHwoDrDYhuiw5oivpYOAbmM,16647
 adcp/testing/__init__.py,sha256=ZWp_floWjVZfy8RBG5v_FUXQ8YbN7xjXvVcX-_zl_HU,1416
 adcp/testing/test_helpers.py,sha256=4n8fZYy1cVpjZpFW2SxBzpC8fmY-MBFrzY4tIPqe4rQ,10028
-adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
+adcp/types/__init__.py,sha256=FXm4210pkzOIQQEgpe-EeLLd7mxofzEgKLGl1r8fj4o,465
+adcp/types/base.py,sha256=QoEuVfI4yzefup0dc2KN11AcJTbcGxRep7xOw5hXfs8,837
 adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
-adcp/types/generated.py,sha256=li7OXwzwbSufdff6sF_tjA9X1Sce4pq_FB3aijvoW-E,81384
+adcp/types/generated.py,sha256=os26c6yVrCzfSJXJkMsNUODRgp4UrozMkc19OPYcxls,83621
 adcp/types/tasks.py,sha256=Ae9TSwG2F7oWXTcl4TvLhAzinbQkHNGF1Pc0q8RMNNM,23424
 adcp/utils/__init__.py,sha256=uetvSJB19CjQbtwEYZiTnumJG11GsafQmXm5eR3hL7E,153
 adcp/utils/operation_id.py,sha256=wQX9Bb5epXzRq23xoeYPTqzu5yLuhshg7lKJZihcM2k,294
-adcp/utils/preview_cache.py,sha256=8_2qs5CgrHv1_WOnD4bs43VWueu-rcZRu5PZMQ_lyuE,17573
+adcp/utils/preview_cache.py,sha256=8BqbGtilEWD-2ZIIcXCxVar6hs1uMLqTs9DND05RMh8,17685
 adcp/utils/response_parser.py,sha256=uPk2vIH-RYZmq7y3i8lC4HTMQ3FfKdlgXKTjgJ1955M,6253
-adcp-1.5.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.5.0.dist-info/METADATA,sha256=seaLyTrrjeh5W1sSvZajfvbomYy-VcX9jPWfCZQiXDU,19931
-adcp-1.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.5.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.5.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.5.0.dist-info/RECORD,,
+adcp-1.6.1.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.6.1.dist-info/METADATA,sha256=OgqXYiJzf7oW6Hta0L_sH3VJq2EYWMypqJzu9wBx_Qs,21345
+adcp-1.6.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.6.1.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.6.1.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.6.1.dist-info/RECORD,,