adcp 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

adcp/__init__.py

@@ -18,35 +18,135 @@ from adcp.exceptions import (
     ADCPWebhookError,
     ADCPWebhookSignatureError,
 )
+
+# Test helpers
+from adcp.testing import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_client,
+)
 from adcp.types.core import AgentConfig, Protocol, TaskResult, TaskStatus, WebhookMetadata
 from adcp.types.generated import (
+    ActivateSignalError,
+    # Request/Response types
     ActivateSignalRequest,
     ActivateSignalResponse,
+    ActivateSignalSuccess,
+    ActivationKey,
+    AgentDeployment,
+    AgentDestination,
+    BothPreviewRender,
+    # Brand types
+    BrandManifest,
+    BrandManifestRef,
+    BuildCreativeRequest,
+    BuildCreativeResponse,
+    # Channel types
+    Channels,
+    CreateMediaBuyError,
     CreateMediaBuyRequest,
     CreateMediaBuyResponse,
+    CreateMediaBuySuccess,
+    # Creative types
+    CreativeAsset,
+    CreativeAssignment,
+    CreativeManifest,
+    CreativePolicy,
+    DaastAsset,
+    # Metrics types
+    DeliveryMetrics,
+    # Delivery types
+    DeliveryType,
+    Deployment,
+    # Deployment types
+    Destination,
+    Error,
+    Format,
+    FormatId,
+    FrequencyCap,
     GetMediaBuyDeliveryRequest,
     GetMediaBuyDeliveryResponse,
     GetProductsRequest,
     GetProductsResponse,
     GetSignalsRequest,
     GetSignalsResponse,
+    HtmlPreviewRender,
+    InlineDaastAsset,
+    InlineVastAsset,
+    Key_valueActivationKey,
     ListAuthorizedPropertiesRequest,
     ListAuthorizedPropertiesResponse,
     ListCreativeFormatsRequest,
     ListCreativeFormatsResponse,
     ListCreativesRequest,
     ListCreativesResponse,
+    Measurement,
+    # Core domain types
     MediaBuy,
+    # Status enums
+    MediaBuyStatus,
+    # Sub-asset types
+    MediaSubAsset,
+    Pacing,
+    Package,
+    PackageStatus,
+    PerformanceFeedback,
+    Placement,
+    PlatformDeployment,
+    PlatformDestination,
+    PreviewCreativeRequest,
+    PreviewCreativeResponse,
+    # Preview render types
+    PreviewRender,
+    PricingModel,
+    # Pricing types
+    PricingOption,
     Product,
+    PromotedProducts,
+    # Property and placement types
+    Property,
+    ProtocolEnvelope,
     ProvidePerformanceFeedbackRequest,
     ProvidePerformanceFeedbackResponse,
+    PushNotificationConfig,
+    ReportingCapabilities,
+    Response,
+    Segment_idActivationKey,
+    StandardFormatIds,
+    StartTiming,
+    SubAsset,
+    SyncCreativesError,
     SyncCreativesRequest,
     SyncCreativesResponse,
+    SyncCreativesSuccess,
+    # Targeting types
+    Targeting,
+    # Task types
+    TaskType,
+    TextSubAsset,
+    UpdateMediaBuyError,
     UpdateMediaBuyRequest,
     UpdateMediaBuyResponse,
+    UpdateMediaBuySuccess,
+    UrlDaastAsset,
+    UrlPreviewRender,
+    UrlVastAsset,
+    # Asset delivery types (VAST/DAAST)
+    VastAsset,
+    # Protocol types
+    WebhookPayload,
+)
+from adcp.types.generated import (
+    TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     # Client classes
@@ -58,6 +158,16 @@ __all__ = [
     "TaskResult",
     "TaskStatus",
     "WebhookMetadata",
+    # Test helpers
+    "test_agent",
+    "test_agent_a2a",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
     # Exceptions
     "ADCPError",
     "ADCPConnectionError",
@@ -67,30 +177,113 @@ __all__ = [
     "ADCPToolNotFoundError",
     "ADCPWebhookError",
     "ADCPWebhookSignatureError",
-    # Generated request/response types
-    "GetProductsRequest",
-    "GetProductsResponse",
+    # Request/Response types
+    "ActivateSignalRequest",
+    "ActivateSignalResponse",
+    "ActivateSignalSuccess",
+    "ActivateSignalError",
+    "ActivationKey",
+    "Segment_idActivationKey",
+    "Key_valueActivationKey",
+    "BuildCreativeRequest",
+    "BuildCreativeResponse",
     "CreateMediaBuyRequest",
     "CreateMediaBuyResponse",
-    "UpdateMediaBuyRequest",
-    "UpdateMediaBuyResponse",
-    "SyncCreativesRequest",
-    "SyncCreativesResponse",
-    "ListCreativesRequest",
-    "ListCreativesResponse",
-    "ListCreativeFormatsRequest",
-    "ListCreativeFormatsResponse",
+    "CreateMediaBuySuccess",
+    "CreateMediaBuyError",
     "GetMediaBuyDeliveryRequest",
     "GetMediaBuyDeliveryResponse",
-    "ListAuthorizedPropertiesRequest",
-    "ListAuthorizedPropertiesResponse",
+    "GetProductsRequest",
+    "GetProductsResponse",
     "GetSignalsRequest",
     "GetSignalsResponse",
-    "ActivateSignalRequest",
-    "ActivateSignalResponse",
+    "ListAuthorizedPropertiesRequest",
+    "ListAuthorizedPropertiesResponse",
+    "ListCreativeFormatsRequest",
+    "ListCreativeFormatsResponse",
+    "ListCreativesRequest",
+    "ListCreativesResponse",
+    "PreviewCreativeRequest",
+    "PreviewCreativeResponse",
     "ProvidePerformanceFeedbackRequest",
     "ProvidePerformanceFeedbackResponse",
+    "SyncCreativesRequest",
+    "SyncCreativesResponse",
+    "SyncCreativesSuccess",
+    "SyncCreativesError",
+    "UpdateMediaBuyRequest",
+    "UpdateMediaBuyResponse",
+    "UpdateMediaBuySuccess",
+    "UpdateMediaBuyError",
     # Core domain types
-    "Product",
     "MediaBuy",
+    "Product",
+    "Package",
+    "Error",
+    # Creative types
+    "CreativeAsset",
+    "CreativeManifest",
+    "CreativeAssignment",
+    "CreativePolicy",
+    "Format",
+    "FormatId",
+    # Property and placement types
+    "Property",
+    "Placement",
+    # Targeting types
+    "Targeting",
+    "FrequencyCap",
+    "Pacing",
+    # Brand types
+    "BrandManifest",
+    "BrandManifestRef",
+    # Metrics types
+    "DeliveryMetrics",
+    "Measurement",
+    "PerformanceFeedback",
+    # Status enums
+    "MediaBuyStatus",
+    "PackageStatus",
+    # Pricing types
+    "PricingOption",
+    "PricingModel",
+    # Delivery types
+    "DeliveryType",
+    "StartTiming",
+    # Channel types
+    "Channels",
+    "StandardFormatIds",
+    # Protocol types
+    "WebhookPayload",
+    "ProtocolEnvelope",
+    "Response",
+    "PromotedProducts",
+    "PushNotificationConfig",
+    "ReportingCapabilities",
+    # Deployment types
+    "Destination",
+    "Deployment",
+    "PlatformDestination",
+    "AgentDestination",
+    "PlatformDeployment",
+    "AgentDeployment",
+    # Sub-asset types
+    "MediaSubAsset",
+    "SubAsset",
+    "TextSubAsset",
+    # Asset delivery types (VAST/DAAST)
+    "VastAsset",
+    "UrlVastAsset",
+    "InlineVastAsset",
+    "DaastAsset",
+    "UrlDaastAsset",
+    "InlineDaastAsset",
+    # Preview render types
+    "PreviewRender",
+    "UrlPreviewRender",
+    "HtmlPreviewRender",
+    "BothPreviewRender",
+    # Task types
+    "TaskType",
+    "GeneratedTaskStatus",
 ]

adcp/client.py

@@ -11,6 +11,8 @@ from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 
+from pydantic import BaseModel
+
 from adcp.exceptions import ADCPWebhookSignatureError
 from adcp.protocols.a2a import A2AAdapter
 from adcp.protocols.base import ProtocolAdapter
@@ -154,7 +156,9 @@ class ADCPClient:
             )
         )
 
-        result = self.adapter._parse_response(raw_result, GetProductsResponse)
+        result: TaskResult[GetProductsResponse] = self.adapter._parse_response(
+            raw_result, GetProductsResponse
+        )
 
         if fetch_previews and result.success and result.data and creative_agent_client:
             from adcp.utils.preview_cache import add_preview_urls_to_products
@@ -215,7 +219,9 @@ class ADCPClient:
             )
         )
 
-        result = self.adapter._parse_response(raw_result, ListCreativeFormatsResponse)
+        result: TaskResult[ListCreativeFormatsResponse] = self.adapter._parse_response(
+            raw_result, ListCreativeFormatsResponse
+        )
 
         if fetch_previews and result.success and result.data:
             from adcp.utils.preview_cache import add_preview_urls_to_formats
@@ -617,15 +623,16 @@ class ADCPClient:
         from adcp.utils.response_parser import parse_json_or_text
 
         # Map task types to their response types (using string literals, not enum)
-        response_type_map: dict[str, type] = {
+        # Note: Some response types are Union types (e.g., ActivateSignalResponse = Success | Error)
+        response_type_map: dict[str, type[BaseModel] | Any] = {
             "get_products": GetProductsResponse,
             "list_creative_formats": ListCreativeFormatsResponse,
-            "sync_creatives": SyncCreativesResponse,
+            "sync_creatives": SyncCreativesResponse,  # Union type
             "list_creatives": ListCreativesResponse,
             "get_media_buy_delivery": GetMediaBuyDeliveryResponse,
             "list_authorized_properties": ListAuthorizedPropertiesResponse,
             "get_signals": GetSignalsResponse,
-            "activate_signal": ActivateSignalResponse,
+            "activate_signal": ActivateSignalResponse,  # Union type
             "provide_performance_feedback": ProvidePerformanceFeedbackResponse,
         }
 

adcp/protocols/base.py

@@ -30,15 +30,18 @@ class ProtocolAdapter(ABC):
     # Helper methods for response parsing
     # ========================================================================
 
-    def _parse_response(self, raw_result: TaskResult[Any], response_type: type[T]) -> TaskResult[T]:
+    def _parse_response(
+        self, raw_result: TaskResult[Any], response_type: type[T] | Any
+    ) -> TaskResult[T]:
         """
         Parse raw TaskResult into typed TaskResult.
 
         Handles both MCP content arrays and A2A dict responses.
+        Supports both single types and Union types (for oneOf discriminated unions).
 
         Args:
             raw_result: Raw TaskResult from adapter
-            response_type: Expected Pydantic response type
+            response_type: Expected Pydantic response type (can be a Union type)
 
         Returns:
             Typed TaskResult

adcp/testing/__init__.py

@@ -0,0 +1,38 @@
+"""Test helpers for AdCP client library.
+
+Provides pre-configured test agents for examples and quick testing.
+"""
+
+from __future__ import annotations
+
+from adcp.testing.test_helpers import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_A2A_NO_AUTH_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_MCP_NO_AUTH_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_a2a_no_auth,
+    test_agent_client,
+    test_agent_no_auth,
+)
+
+__all__ = [
+    "test_agent",
+    "test_agent_a2a",
+    "test_agent_no_auth",
+    "test_agent_a2a_no_auth",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "TEST_AGENT_MCP_NO_AUTH_CONFIG",
+    "TEST_AGENT_A2A_NO_AUTH_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
+]

adcp/testing/test_helpers.py

@@ -0,0 +1,311 @@
+"""Test agent helpers for easy examples and quick testing.
+
+These provide pre-configured access to AdCP's public test agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from adcp.client import ADCPClient, ADCPMultiAgentClient
+from adcp.types.core import AgentConfig, Protocol
+
+# Public test agent auth token
+# This token is public and rate-limited, for testing/examples only.
+TEST_AGENT_TOKEN = "1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
+
+# Public test agent configuration - MCP protocol
+TEST_AGENT_MCP_CONFIG = AgentConfig(
+    id="test-agent-mcp",
+    agent_uri="https://test-agent.adcontextprotocol.org/mcp/",
+    protocol=Protocol.MCP,
+    auth_token=TEST_AGENT_TOKEN,
+)
+
+# Public test agent configuration - A2A protocol
+TEST_AGENT_A2A_CONFIG = AgentConfig(
+    id="test-agent-a2a",
+    agent_uri="https://test-agent.adcontextprotocol.org",
+    protocol=Protocol.A2A,
+    auth_token=TEST_AGENT_TOKEN,
+)
+
+# Public test agent configuration (no auth) - MCP protocol
+TEST_AGENT_MCP_NO_AUTH_CONFIG = AgentConfig(
+    id="test-agent-mcp-no-auth",
+    agent_uri="https://test-agent.adcontextprotocol.org/mcp/",
+    protocol=Protocol.MCP,
+)
+
+# Public test agent configuration (no auth) - A2A protocol
+TEST_AGENT_A2A_NO_AUTH_CONFIG = AgentConfig(
+    id="test-agent-a2a-no-auth",
+    agent_uri="https://test-agent.adcontextprotocol.org",
+    protocol=Protocol.A2A,
+)
+
+# Reference creative agent configuration - MCP protocol
+# No authentication required for the reference creative agent
+CREATIVE_AGENT_CONFIG = AgentConfig(
+    id="creative-agent",
+    agent_uri="https://creative.adcontextprotocol.org/mcp",
+    protocol=Protocol.MCP,
+)
+
+
+def _create_test_agent_client() -> ADCPClient:
+    """Create pre-configured test agent client using MCP protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent
+
+    Note:
+        This agent is rate-limited and intended for testing/examples only.
+        The auth token is public and may be rotated without notice.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_MCP_CONFIG)
+
+
+def _create_test_agent_a2a_client() -> ADCPClient:
+    """Create pre-configured test agent client using A2A protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent
+
+    Note:
+        This agent is rate-limited and intended for testing/examples only.
+        The auth token is public and may be rotated without notice.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_A2A_CONFIG)
+
+
+def _create_test_agent_no_auth_client() -> ADCPClient:
+    """Create pre-configured test agent client (no auth) using MCP protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent without authentication
+
+    Note:
+        This agent is rate-limited and intended for testing scenarios where no auth is provided.
+        Useful for testing behavior differences between authenticated and unauthenticated requests.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_MCP_NO_AUTH_CONFIG)
+
+
+def _create_test_agent_a2a_no_auth_client() -> ADCPClient:
+    """Create pre-configured test agent client (no auth) using A2A protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent without authentication
+
+    Note:
+        This agent is rate-limited and intended for testing scenarios where no auth is provided.
+        Useful for testing behavior differences between authenticated and unauthenticated requests.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_A2A_NO_AUTH_CONFIG)
+
+
+def _create_creative_agent_client() -> ADCPClient:
+    """Create pre-configured creative agent client.
+
+    Returns:
+        ADCPClient instance configured for the reference creative agent
+
+    Note:
+        The reference creative agent is public and requires no authentication.
+        It provides creative preview functionality for testing and examples.
+    """
+    return ADCPClient(CREATIVE_AGENT_CONFIG)
+
+
+def _create_test_multi_agent_client() -> ADCPMultiAgentClient:
+    """Create multi-agent client with both test agents configured.
+
+    Returns:
+        ADCPMultiAgentClient with both MCP and A2A test agents
+
+    Note:
+        This client is rate-limited and intended for testing/examples only.
+        DO NOT use in production applications.
+    """
+    return ADCPMultiAgentClient([TEST_AGENT_MCP_CONFIG, TEST_AGENT_A2A_CONFIG])
+
+
+# Pre-configured test agent client using MCP protocol.
+# Ready to use for examples, documentation, and quick testing.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent
+#
+#     # Simple get_products call
+#     result = await test_agent.get_products(
+#         GetProductsRequest(
+#             brief="Coffee subscription service for busy professionals",
+#             promoted_offering="Premium monthly coffee deliveries"
+#         )
+#     )
+#
+#     if result.success:
+#         print(f"Found {len(result.data.products)} products")
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     The auth token is public and may be rotated without notice.
+#     DO NOT use in production applications.
+test_agent: ADCPClient = _create_test_agent_client()
+
+# Pre-configured test agent client using A2A protocol.
+# Identical functionality to test_agent but uses A2A instead of MCP.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_a2a
+#
+#     result = await test_agent_a2a.get_products(
+#         GetProductsRequest(
+#             brief="Sustainable fashion brands",
+#             promoted_offering="Eco-friendly clothing"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     The auth token is public and may be rotated without notice.
+#     DO NOT use in production applications.
+test_agent_a2a: ADCPClient = _create_test_agent_a2a_client()
+
+# Pre-configured test agent client (no auth) using MCP protocol.
+# Useful for testing scenarios where authentication is not provided,
+# such as testing how agents handle unauthenticated requests or
+# comparing behavior between authenticated and unauthenticated calls.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_no_auth
+#
+#     # Test behavior without authentication
+#     result = await test_agent_no_auth.get_products(
+#         GetProductsRequest(
+#             brief="Coffee subscription service",
+#             promoted_offering="Premium monthly coffee"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_no_auth: ADCPClient = _create_test_agent_no_auth_client()
+
+# Pre-configured test agent client (no auth) using A2A protocol.
+# Identical functionality to test_agent_no_auth but uses A2A instead of MCP.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_a2a_no_auth
+#
+#     # Test A2A behavior without authentication
+#     result = await test_agent_a2a_no_auth.get_products(
+#         GetProductsRequest(
+#             brief="Sustainable fashion brands",
+#             promoted_offering="Eco-friendly clothing"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_a2a_no_auth: ADCPClient = _create_test_agent_a2a_no_auth_client()
+
+# Pre-configured reference creative agent.
+# Provides creative preview functionality without authentication.
+#
+# Example:
+#     ```python
+#     from adcp.testing import creative_agent
+#     from adcp.types.generated import PreviewCreativeRequest
+#
+#     result = await creative_agent.preview_creative(
+#         PreviewCreativeRequest(
+#             manifest={
+#                 "format_id": "banner_300x250",
+#                 "assets": {...}
+#             }
+#         )
+#     )
+#     ```
+#
+# Note:
+#     The reference creative agent is public and requires no authentication.
+#     Perfect for testing creative rendering and preview functionality.
+creative_agent: ADCPClient = _create_creative_agent_client()
+
+# Multi-agent client with both test agents configured.
+# Useful for testing multi-agent patterns and protocol comparisons.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_client
+#
+#     # Access individual agents
+#     mcp_agent = test_agent_client.agent("test-agent-mcp")
+#     a2a_agent = test_agent_client.agent("test-agent-a2a")
+#
+#     # Use for parallel operations
+#     results = await test_agent_client.get_products(
+#         GetProductsRequest(
+#             brief="Premium coffee brands",
+#             promoted_offering="Artisan coffee"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This client is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_client: ADCPMultiAgentClient = _create_test_multi_agent_client()
+
+
+def create_test_agent(**overrides: Any) -> AgentConfig:
+    """Create a custom test agent configuration.
+
+    Useful when you need to modify the default test agent setup.
+
+    Args:
+        **overrides: Keyword arguments to override default config values
+
+    Returns:
+        Complete agent configuration
+
+    Example:
+        ```python
+        from adcp.testing import create_test_agent
+        from adcp.client import ADCPClient
+
+        # Use default test agent with custom ID
+        config = create_test_agent(id="my-test-agent")
+        client = ADCPClient(config)
+        ```
+
+    Example:
+        ```python
+        # Use A2A protocol instead of MCP
+        from adcp.types.core import Protocol
+
+        config = create_test_agent(
+            protocol=Protocol.A2A,
+            agent_uri="https://test-agent.adcontextprotocol.org"
+        )
+        ```
+    """
+    base_config = TEST_AGENT_MCP_CONFIG.model_dump()
+    base_config.update(overrides)
+    return AgentConfig(**base_config)