adcp 2.1.0__tar.gz → 2.3.0__tar.gz

{adcp-2.1.0/src/adcp.egg-info → adcp-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.1.0
+Version: 2.3.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -26,6 +26,7 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: typing-extensions>=4.5.0
 Requires-Dist: a2a-sdk>=0.3.0
 Requires-Dist: mcp>=0.9.0
+Requires-Dist: email-validator>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -34,7 +35,6 @@ Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: datamodel-code-generator[http]>=0.35.0; extra == "dev"
-Requires-Dist: email-validator>=2.0.0; extra == "dev"
 Dynamic: license-file
 
 # adcp - Python Client for Ad Context Protocol
@@ -544,6 +544,42 @@ is_authorized = await verify_agent_for_property(
 
 See `examples/adagents_validation.py` for complete examples.
 
+### Authorization Discovery
+
+Discover which publishers have authorized your agent using two approaches:
+
+**1. "Push" Approach** - Ask the agent (recommended, fastest):
+```python
+from adcp import ADCPClient
+
+async with ADCPClient(agent_config) as client:
+    # Single API call to agent
+    response = await client.simple.list_authorized_properties()
+    print(f"Authorized for: {response.publisher_domains}")
+```
+
+**2. "Pull" Approach** - Check publisher adagents.json files (when you need property details):
+```python
+from adcp import fetch_agent_authorizations
+
+# Check specific publishers (fetches in parallel)
+contexts = await fetch_agent_authorizations(
+    "https://our-sales-agent.com",
+    ["nytimes.com", "wsj.com", "cnn.com"]
+)
+
+for domain, ctx in contexts.items():
+    print(f"{domain}:")
+    print(f"  Property IDs: {ctx.property_ids}")
+    print(f"  Tags: {ctx.property_tags}")
+```
+
+**When to use which:**
+- **Push**: Quick discovery, portfolio overview, high-level authorization check
+- **Pull**: Property-level details, specific publisher list, works offline
+
+See `examples/fetch_agent_authorizations.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-2.1.0 → adcp-2.3.0}/README.md

@@ -505,6 +505,42 @@ is_authorized = await verify_agent_for_property(
 
 See `examples/adagents_validation.py` for complete examples.
 
+### Authorization Discovery
+
+Discover which publishers have authorized your agent using two approaches:
+
+**1. "Push" Approach** - Ask the agent (recommended, fastest):
+```python
+from adcp import ADCPClient
+
+async with ADCPClient(agent_config) as client:
+    # Single API call to agent
+    response = await client.simple.list_authorized_properties()
+    print(f"Authorized for: {response.publisher_domains}")
+```
+
+**2. "Pull" Approach** - Check publisher adagents.json files (when you need property details):
+```python
+from adcp import fetch_agent_authorizations
+
+# Check specific publishers (fetches in parallel)
+contexts = await fetch_agent_authorizations(
+    "https://our-sales-agent.com",
+    ["nytimes.com", "wsj.com", "cnn.com"]
+)
+
+for domain, ctx in contexts.items():
+    print(f"{domain}:")
+    print(f"  Property IDs: {ctx.property_ids}")
+    print(f"  Tags: {ctx.property_tags}")
+```
+
+**When to use which:**
+- **Push**: Quick discovery, portfolio overview, high-level authorization check
+- **Pull**: Property-level details, specific publisher list, works offline
+
+See `examples/fetch_agent_authorizations.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-2.1.0 → adcp-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "2.1.0"
+version = "2.3.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
@@ -31,6 +31,7 @@ dependencies = [
     "typing-extensions>=4.5.0",
     "a2a-sdk>=0.3.0",
     "mcp>=0.9.0",
+    "email-validator>=2.0.0",
 ]
 
 [project.scripts]
@@ -45,7 +46,6 @@ dev = [
     "black>=23.0.0",
     "ruff>=0.1.0",
     "datamodel-code-generator[http]>=0.35.0",
-    "email-validator>=2.0.0",
 ]
 
 [project.urls]

{adcp-2.1.0 → adcp-2.3.0}/src/adcp/__init__.py

@@ -8,8 +8,10 @@ Supports both A2A and MCP protocols with full type safety.
 """
 
 from adcp.adagents import (
+    AuthorizationContext,
     domain_matches,
     fetch_adagents,
+    fetch_agent_authorizations,
     get_all_properties,
     get_all_tags,
     get_properties_by_agent,
@@ -56,27 +58,33 @@ from adcp.types import aliases, generated
 from adcp.types.aliases import (
     ActivateSignalErrorResponse,
     ActivateSignalSuccessResponse,
+    BothPreviewRender,
     BuildCreativeErrorResponse,
     BuildCreativeSuccessResponse,
     CreateMediaBuyErrorResponse,
     CreateMediaBuySuccessResponse,
+    HtmlPreviewRender,
+    InlineDaastAsset,
+    InlineVastAsset,
+    MediaSubAsset,
     PreviewCreativeFormatRequest,
     PreviewCreativeInteractiveResponse,
     PreviewCreativeManifestRequest,
     PreviewCreativeStaticResponse,
-    PreviewRenderHtml,
-    PreviewRenderIframe,
-    PreviewRenderImage,
     PropertyIdActivationKey,
     PropertyTagActivationKey,
     ProvidePerformanceFeedbackErrorResponse,
     ProvidePerformanceFeedbackSuccessResponse,
     SyncCreativesErrorResponse,
     SyncCreativesSuccessResponse,
+    TextSubAsset,
     UpdateMediaBuyErrorResponse,
     UpdateMediaBuyPackagesRequest,
     UpdateMediaBuyPropertiesRequest,
     UpdateMediaBuySuccessResponse,
+    UrlDaastAsset,
+    UrlPreviewRender,
+    UrlVastAsset,
 )
 from adcp.types.core import AgentConfig, Protocol, TaskResult, TaskStatus, WebhookMetadata
 
@@ -128,7 +136,7 @@ from adcp.validation import (
     validate_publisher_properties_item,
 )
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 __all__ = [
     # Client classes
@@ -172,7 +180,9 @@ __all__ = [
     "Product",
     "Property",
     # Adagents validation
+    "AuthorizationContext",
     "fetch_adagents",
+    "fetch_agent_authorizations",
     "verify_agent_authorization",
     "verify_agent_for_property",
     "domain_matches",
@@ -219,25 +229,31 @@ __all__ = [
     # Semantic type aliases (for better API ergonomics)
     "ActivateSignalSuccessResponse",
     "ActivateSignalErrorResponse",
+    "BothPreviewRender",
     "BuildCreativeSuccessResponse",
     "BuildCreativeErrorResponse",
     "CreateMediaBuySuccessResponse",
     "CreateMediaBuyErrorResponse",
-    "ProvidePerformanceFeedbackSuccessResponse",
-    "ProvidePerformanceFeedbackErrorResponse",
-    "SyncCreativesSuccessResponse",
-    "SyncCreativesErrorResponse",
-    "UpdateMediaBuySuccessResponse",
-    "UpdateMediaBuyErrorResponse",
+    "HtmlPreviewRender",
+    "InlineDaastAsset",
+    "InlineVastAsset",
+    "MediaSubAsset",
     "PreviewCreativeFormatRequest",
     "PreviewCreativeManifestRequest",
     "PreviewCreativeStaticResponse",
     "PreviewCreativeInteractiveResponse",
-    "PreviewRenderImage",
-    "PreviewRenderHtml",
-    "PreviewRenderIframe",
     "PropertyIdActivationKey",
     "PropertyTagActivationKey",
+    "ProvidePerformanceFeedbackSuccessResponse",
+    "ProvidePerformanceFeedbackErrorResponse",
+    "SyncCreativesSuccessResponse",
+    "SyncCreativesErrorResponse",
+    "TextSubAsset",
+    "UpdateMediaBuySuccessResponse",
+    "UpdateMediaBuyErrorResponse",
     "UpdateMediaBuyPackagesRequest",
     "UpdateMediaBuyPropertiesRequest",
+    "UrlDaastAsset",
+    "UrlPreviewRender",
+    "UrlVastAsset",
 ]

{adcp-2.1.0 → adcp-2.3.0}/src/adcp/adagents.py

@@ -518,3 +518,125 @@ def get_properties_by_agent(adagents_data: dict[str, Any], agent_url: str) -> li
         return [p for p in properties if isinstance(p, dict)]
 
     return []
+
+
+class AuthorizationContext:
+    """Authorization context for a publisher domain.
+
+    Attributes:
+        property_ids: List of property IDs the agent is authorized for
+        property_tags: List of property tags the agent is authorized for
+        raw_properties: Raw property data from adagents.json
+    """
+
+    def __init__(self, properties: list[dict[str, Any]]):
+        """Initialize from list of properties.
+
+        Args:
+            properties: List of property dictionaries from adagents.json
+        """
+        self.property_ids: list[str] = []
+        self.property_tags: list[str] = []
+        self.raw_properties = properties
+
+        # Extract property IDs and tags
+        for prop in properties:
+            if not isinstance(prop, dict):
+                continue
+
+            # Extract property ID
+            prop_id = prop.get("id")
+            if prop_id and isinstance(prop_id, str):
+                self.property_ids.append(prop_id)
+
+            # Extract tags
+            tags = prop.get("tags", [])
+            if isinstance(tags, list):
+                for tag in tags:
+                    if isinstance(tag, str) and tag not in self.property_tags:
+                        self.property_tags.append(tag)
+
+    def __repr__(self) -> str:
+        return (
+            f"AuthorizationContext("
+            f"property_ids={self.property_ids}, "
+            f"property_tags={self.property_tags})"
+        )
+
+
+async def fetch_agent_authorizations(
+    agent_url: str,
+    publisher_domains: list[str],
+    timeout: float = 10.0,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, AuthorizationContext]:
+    """Fetch authorization contexts by checking publisher adagents.json files.
+
+    This function discovers what publishers have authorized your agent by fetching
+    their adagents.json files from the .well-known directory and extracting the
+    properties your agent can access.
+
+    This is the "pull" approach - you query publishers to see if they've authorized you.
+    For the "push" approach where the agent tells you what it's authorized for,
+    use the agent's list_authorized_properties endpoint via ADCPClient.
+
+    Args:
+        agent_url: URL of your sales agent
+        publisher_domains: List of publisher domains to check (e.g., ["nytimes.com", "wsj.com"])
+        timeout: Request timeout in seconds for each fetch
+        client: Optional httpx.AsyncClient for connection pooling
+
+    Returns:
+        Dictionary mapping publisher domain to AuthorizationContext.
+        Only includes domains where the agent is authorized.
+
+    Example:
+        >>> # "Pull" approach - check what publishers have authorized you
+        >>> contexts = await fetch_agent_authorizations(
+        ...     "https://our-sales-agent.com",
+        ...     ["nytimes.com", "wsj.com", "cnn.com"]
+        ... )
+        >>> for domain, ctx in contexts.items():
+        ...     print(f"{domain}:")
+        ...     print(f"  Property IDs: {ctx.property_ids}")
+        ...     print(f"  Tags: {ctx.property_tags}")
+
+    See Also:
+        ADCPClient.list_authorized_properties: "Push" approach using the agent's API
+
+    Notes:
+        - Silently skips domains where adagents.json is not found or invalid
+        - Only returns domains where the agent is explicitly authorized
+        - For production use with many domains, pass a shared httpx.AsyncClient
+          to enable connection pooling
+    """
+    import asyncio
+
+    # Create tasks to fetch all adagents.json files in parallel
+    async def fetch_authorization_for_domain(
+        domain: str,
+    ) -> tuple[str, AuthorizationContext | None]:
+        """Fetch authorization context for a single domain."""
+        try:
+            adagents_data = await fetch_adagents(domain, timeout=timeout, client=client)
+
+            # Check if agent is authorized
+            if not verify_agent_authorization(adagents_data, agent_url):
+                return (domain, None)
+
+            # Get properties for this agent
+            properties = get_properties_by_agent(adagents_data, agent_url)
+
+            # Create authorization context
+            return (domain, AuthorizationContext(properties))
+
+        except (AdagentsNotFoundError, AdagentsValidationError, AdagentsTimeoutError):
+            # Silently skip domains with missing or invalid adagents.json
+            return (domain, None)
+
+    # Fetch all domains in parallel
+    tasks = [fetch_authorization_for_domain(domain) for domain in publisher_domains]
+    results = await asyncio.gather(*tasks)
+
+    # Build result dictionary, filtering out None values
+    return {domain: ctx for domain, ctx in results if ctx is not None}

adcp-2.3.0/src/adcp/types/__init__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+"""Type definitions for AdCP client."""
+
+from adcp.types.aliases import (
+    BothPreviewRender,
+    HtmlPreviewRender,
+    InlineDaastAsset,
+    InlineVastAsset,
+    MediaSubAsset,
+    TextSubAsset,
+    UrlDaastAsset,
+    UrlPreviewRender,
+    UrlVastAsset,
+)
+from adcp.types.base import AdCPBaseModel
+from adcp.types.core import (
+    Activity,
+    ActivityType,
+    AgentConfig,
+    DebugInfo,
+    Protocol,
+    TaskResult,
+    TaskStatus,
+    WebhookMetadata,
+)
+
+__all__ = [
+    "AdCPBaseModel",
+    "AgentConfig",
+    "Protocol",
+    "TaskResult",
+    "TaskStatus",
+    "WebhookMetadata",
+    "Activity",
+    "ActivityType",
+    "DebugInfo",
+    # Semantic aliases for discriminated unions
+    "BothPreviewRender",
+    "HtmlPreviewRender",
+    "InlineDaastAsset",
+    "InlineVastAsset",
+    "MediaSubAsset",
+    "TextSubAsset",
+    "UrlDaastAsset",
+    "UrlPreviewRender",
+    "UrlVastAsset",
+]

{adcp-2.1.0 → adcp-2.3.0}/src/adcp/types/aliases.py

@@ -45,6 +45,9 @@ from adcp.types.generated import (
     # Create media buy responses
     CreateMediaBuyResponse1,
     CreateMediaBuyResponse2,
+    # DAAST assets
+    DaastAsset1,
+    DaastAsset2,
     # Preview creative requests
     PreviewCreativeRequest1,
     PreviewCreativeRequest2,
@@ -58,6 +61,9 @@ from adcp.types.generated import (
     # Performance feedback responses
     ProvidePerformanceFeedbackResponse1,
     ProvidePerformanceFeedbackResponse2,
+    # SubAssets
+    SubAsset1,
+    SubAsset2,
     # Sync creatives responses
     SyncCreativesResponse1,
     SyncCreativesResponse2,
@@ -67,6 +73,9 @@ from adcp.types.generated import (
     # Update media buy responses
     UpdateMediaBuyResponse1,
     UpdateMediaBuyResponse2,
+    # VAST assets
+    VastAsset1,
+    VastAsset2,
 )
 
 # ============================================================================
@@ -157,15 +166,40 @@ PreviewCreativeStaticResponse = PreviewCreativeResponse1
 PreviewCreativeInteractiveResponse = PreviewCreativeResponse2
 """Preview response with interactive renders (iframe embedding)."""
 
-# Preview Render Variants
-PreviewRenderImage = PreviewRender1
-"""Image-based preview render (PNG/JPEG)."""
+# Preview Render Variants (discriminated by output_format)
+UrlPreviewRender = PreviewRender1
+"""Preview render with output_format='url' - provides preview_url for iframe embedding."""
 
-PreviewRenderHtml = PreviewRender2
-"""HTML-based preview render (static markup)."""
+HtmlPreviewRender = PreviewRender2
+"""Preview render with output_format='html' - provides preview_html for direct embedding."""
 
-PreviewRenderIframe = PreviewRender3
-"""Interactive iframe-based preview render."""
+BothPreviewRender = PreviewRender3
+"""Preview render with output_format='both' - provides both preview_url and preview_html."""
+
+# ============================================================================
+# ASSET TYPE ALIASES - Delivery & Kind Discriminated Unions
+# ============================================================================
+
+# VAST Asset Variants (discriminated by delivery_type)
+UrlVastAsset = VastAsset1
+"""VAST asset delivered via URL endpoint - delivery_type='url'."""
+
+InlineVastAsset = VastAsset2
+"""VAST asset with inline XML content - delivery_type='inline'."""
+
+# DAAST Asset Variants (discriminated by delivery_type)
+UrlDaastAsset = DaastAsset1
+"""DAAST asset delivered via URL endpoint - delivery_type='url'."""
+
+InlineDaastAsset = DaastAsset2
+"""DAAST asset with inline XML content - delivery_type='inline'."""
+
+# SubAsset Variants (discriminated by asset_kind)
+MediaSubAsset = SubAsset1
+"""SubAsset for media content (images, videos) - asset_kind='media', provides content_uri."""
+
+TextSubAsset = SubAsset2
+"""SubAsset for text content (headlines, body text) - asset_kind='text', provides content."""
 
 # ============================================================================
 # EXPORTS
@@ -178,6 +212,16 @@ __all__ = [
     # Activation keys
     "PropertyIdActivationKey",
     "PropertyTagActivationKey",
+    # Asset type aliases
+    "BothPreviewRender",
+    "HtmlPreviewRender",
+    "InlineDaastAsset",
+    "InlineVastAsset",
+    "MediaSubAsset",
+    "TextSubAsset",
+    "UrlDaastAsset",
+    "UrlPreviewRender",
+    "UrlVastAsset",
     # Build creative responses
     "BuildCreativeSuccessResponse",
     "BuildCreativeErrorResponse",
@@ -193,10 +237,6 @@ __all__ = [
     # Preview creative responses
     "PreviewCreativeStaticResponse",
     "PreviewCreativeInteractiveResponse",
-    # Preview renders
-    "PreviewRenderImage",
-    "PreviewRenderHtml",
-    "PreviewRenderIframe",
     # Sync creatives responses
     "SyncCreativesSuccessResponse",
     "SyncCreativesErrorResponse",

{adcp-2.1.0 → adcp-2.3.0/src/adcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.1.0
+Version: 2.3.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -26,6 +26,7 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: typing-extensions>=4.5.0
 Requires-Dist: a2a-sdk>=0.3.0
 Requires-Dist: mcp>=0.9.0
+Requires-Dist: email-validator>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -34,7 +35,6 @@ Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: datamodel-code-generator[http]>=0.35.0; extra == "dev"
-Requires-Dist: email-validator>=2.0.0; extra == "dev"
 Dynamic: license-file
 
 # adcp - Python Client for Ad Context Protocol
@@ -544,6 +544,42 @@ is_authorized = await verify_agent_for_property(
 
 See `examples/adagents_validation.py` for complete examples.
 
+### Authorization Discovery
+
+Discover which publishers have authorized your agent using two approaches:
+
+**1. "Push" Approach** - Ask the agent (recommended, fastest):
+```python
+from adcp import ADCPClient
+
+async with ADCPClient(agent_config) as client:
+    # Single API call to agent
+    response = await client.simple.list_authorized_properties()
+    print(f"Authorized for: {response.publisher_domains}")
+```
+
+**2. "Pull" Approach** - Check publisher adagents.json files (when you need property details):
+```python
+from adcp import fetch_agent_authorizations
+
+# Check specific publishers (fetches in parallel)
+contexts = await fetch_agent_authorizations(
+    "https://our-sales-agent.com",
+    ["nytimes.com", "wsj.com", "cnn.com"]
+)
+
+for domain, ctx in contexts.items():
+    print(f"{domain}:")
+    print(f"  Property IDs: {ctx.property_ids}")
+    print(f"  Tags: {ctx.property_tags}")
+```
+
+**When to use which:**
+- **Push**: Quick discovery, portfolio overview, high-level authorization check
+- **Pull**: Property-level details, specific publisher list, works offline
+
+See `examples/fetch_agent_authorizations.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.