adcp 2.12.0__py3-none-any.whl

adcp/types/generated_poc/media_buy/create_media_buy_response.py

@@ -0,0 +1,56 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/create_media_buy_response.json
+#   timestamp: 2025-11-22T19:16:02+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field, RootModel
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..core import package
+
+
+class CreateMediaBuyResponse2(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    context: context_1.ContextObject | None = None
+    errors: Annotated[
+        list[error.Error],
+        Field(description='Array of errors explaining why the operation failed', min_length=1),
+    ]
+    ext: ext_1.ExtensionObject | None = None
+
+
+class CreateMediaBuyResponse1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    buyer_ref: Annotated[str, Field(description="Buyer's reference identifier for this media buy")]
+    context: context_1.ContextObject | None = None
+    creative_deadline: Annotated[
+        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    media_buy_id: Annotated[
+        str, Field(description="Publisher's unique identifier for the created media buy")
+    ]
+    packages: Annotated[
+        list[package.Package],
+        Field(description='Array of created packages with complete state information'),
+    ]
+
+
+class CreateMediaBuyResponse(RootModel[CreateMediaBuyResponse1 | CreateMediaBuyResponse2]):
+    root: Annotated[
+        CreateMediaBuyResponse1 | CreateMediaBuyResponse2,
+        Field(
+            description='Response payload for create_media_buy task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - the media buy is either fully created or not created at all.',
+            title='Create Media Buy Response',
+        ),
+    ]

adcp/types/generated_poc/media_buy/get_media_buy_delivery_request.py

@@ -0,0 +1,47 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/get_media_buy_delivery_request.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from ..core import context as context_1
+from ..core import ext as ext_1
+from ..enums import media_buy_status
+
+
+class GetMediaBuyDeliveryRequest(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    buyer_refs: Annotated[
+        list[str] | None, Field(description='Array of buyer reference IDs to get delivery data for')
+    ] = None
+    context: context_1.ContextObject | None = None
+    end_date: Annotated[
+        str | None,
+        Field(
+            description='End date for reporting period (YYYY-MM-DD)',
+            pattern='^\\d{4}-\\d{2}-\\d{2}$',
+        ),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    media_buy_ids: Annotated[
+        list[str] | None,
+        Field(description='Array of publisher media buy IDs to get delivery data for'),
+    ] = None
+    start_date: Annotated[
+        str | None,
+        Field(
+            description='Start date for reporting period (YYYY-MM-DD)',
+            pattern='^\\d{4}-\\d{2}-\\d{2}$',
+        ),
+    ] = None
+    status_filter: Annotated[
+        media_buy_status.MediaBuyStatus | list[media_buy_status.MediaBuyStatus] | None,
+        Field(description='Filter by status. Can be a single status or array of statuses'),
+    ] = None

adcp/types/generated_poc/media_buy/get_media_buy_delivery_response.py

@@ -0,0 +1,235 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/get_media_buy_delivery_response.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..core.delivery_metrics import DeliveryMetrics
+from ..enums import pricing_model as pricing_model_1
+
+
+class AggregatedTotals(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    clicks: Annotated[
+        float | None,
+        Field(description='Total clicks across all media buys (if applicable)', ge=0.0),
+    ] = None
+    impressions: Annotated[
+        float, Field(description='Total impressions delivered across all media buys', ge=0.0)
+    ]
+    media_buy_count: Annotated[
+        int, Field(description='Number of media buys included in the response', ge=0)
+    ]
+    spend: Annotated[float, Field(description='Total amount spent across all media buys', ge=0.0)]
+    video_completions: Annotated[
+        float | None,
+        Field(description='Total video completions across all media buys (if applicable)', ge=0.0),
+    ] = None
+
+
+class DeliveryStatus(Enum):
+    delivering = 'delivering'
+    completed = 'completed'
+    budget_exhausted = 'budget_exhausted'
+    flight_ended = 'flight_ended'
+    goal_met = 'goal_met'
+
+
+class DailyBreakdownItem(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    date: Annotated[str, Field(description='Date (YYYY-MM-DD)', pattern='^\\d{4}-\\d{2}-\\d{2}$')]
+    impressions: Annotated[float, Field(description='Daily impressions', ge=0.0)]
+    spend: Annotated[float, Field(description='Daily spend', ge=0.0)]
+
+
+class Status(Enum):
+    pending = 'pending'
+    active = 'active'
+    paused = 'paused'
+    completed = 'completed'
+    failed = 'failed'
+    reporting_delayed = 'reporting_delayed'
+
+
+class Totals(DeliveryMetrics):
+    effective_rate: Annotated[
+        float | None,
+        Field(
+            description="Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')",
+            ge=0.0,
+        ),
+    ] = None
+
+
+class NotificationType(Enum):
+    scheduled = 'scheduled'
+    final = 'final'
+    delayed = 'delayed'
+    adjusted = 'adjusted'
+
+
+class ReportingPeriod(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    end: Annotated[
+        AwareDatetime,
+        Field(description='ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)'),
+    ]
+    start: Annotated[
+        AwareDatetime,
+        Field(description='ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)'),
+    ]
+
+
+class ByPackageItem(DeliveryMetrics):
+    buyer_ref: Annotated[
+        str | None, Field(description="Buyer's reference identifier for this package")
+    ] = None
+    currency: Annotated[
+        str,
+        Field(
+            description="ISO 4217 currency code (e.g., USD, EUR, GBP) for this package's pricing. Indicates the currency in which the rate and spend values are denominated. Different packages can use different currencies when supported by the publisher.",
+            pattern='^[A-Z]{3}$',
+        ),
+    ]
+    delivery_status: Annotated[
+        DeliveryStatus | None,
+        Field(
+            description='System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control.'
+        ),
+    ] = None
+    pacing_index: Annotated[
+        float | None,
+        Field(description='Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)', ge=0.0),
+    ] = None
+    package_id: Annotated[str, Field(description="Publisher's package identifier")]
+    paused: Annotated[
+        bool | None, Field(description='Whether this package is currently paused by the buyer')
+    ] = None
+    pricing_model: Annotated[
+        pricing_model_1.PricingModel,
+        Field(
+            description='The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization.'
+        ),
+    ]
+    rate: Annotated[
+        float,
+        Field(
+            description='The pricing rate for this package in the specified currency. For fixed-rate pricing, this is the agreed rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this represents the effective rate based on actual delivery.',
+            ge=0.0,
+        ),
+    ]
+
+
+class MediaBuyDelivery(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    buyer_ref: Annotated[
+        str | None, Field(description="Buyer's reference identifier for this media buy")
+    ] = None
+    by_package: Annotated[list[ByPackageItem], Field(description='Metrics broken down by package')]
+    daily_breakdown: Annotated[
+        list[DailyBreakdownItem] | None, Field(description='Day-by-day delivery')
+    ] = None
+    expected_availability: Annotated[
+        AwareDatetime | None,
+        Field(
+            description='When delayed data is expected to be available (only present when status is reporting_delayed)'
+        ),
+    ] = None
+    is_adjusted: Annotated[
+        bool | None,
+        Field(
+            description='Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.'
+        ),
+    ] = None
+    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
+    pricing_model: Annotated[
+        pricing_model_1.PricingModel | None,
+        Field(description='Pricing model used for this media buy'),
+    ] = None
+    status: Annotated[
+        Status,
+        Field(
+            description='Current media buy status. In webhook context, reporting_delayed indicates data temporarily unavailable.'
+        ),
+    ]
+    totals: Totals
+
+
+class GetMediaBuyDeliveryResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    aggregated_totals: Annotated[
+        AggregatedTotals | None,
+        Field(
+            description='Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.'
+        ),
+    ] = None
+    context: context_1.ContextObject | None = None
+    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
+    errors: Annotated[
+        list[error.Error] | None,
+        Field(
+            description='Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)'
+        ),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    media_buy_deliveries: Annotated[
+        list[MediaBuyDelivery],
+        Field(
+            description='Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.'
+        ),
+    ]
+    next_expected_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            description="ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')"
+        ),
+    ] = None
+    notification_type: Annotated[
+        NotificationType | None,
+        Field(
+            description='Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with updated data'
+        ),
+    ] = None
+    partial_data: Annotated[
+        bool | None,
+        Field(
+            description='Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)'
+        ),
+    ] = None
+    reporting_period: Annotated[
+        ReportingPeriod,
+        Field(description='Date range for the report. All periods use UTC timezone.'),
+    ]
+    sequence_number: Annotated[
+        int | None,
+        Field(
+            description='Sequential notification number (only present in webhook deliveries, starts at 1)',
+            ge=1,
+        ),
+    ] = None
+    unavailable_count: Annotated[
+        int | None,
+        Field(
+            description='Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)',
+            ge=0,
+        ),
+    ] = None

adcp/types/generated_poc/media_buy/get_products_request.py

@@ -0,0 +1,48 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/get_products_request.json
+#   timestamp: 2025-11-22T15:29:34+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+from ..core import brand_manifest as brand_manifest_1
+from ..core import context as context_1
+from ..core import ext as ext_1
+from ..core import product_filters
+
+
+class GetProductsRequest(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    brand_manifest: Annotated[
+        brand_manifest_1.BrandManifest | AnyUrl | None,
+        Field(
+            description='Brand information manifest providing brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest.',
+            examples=[
+                {
+                    'data': {
+                        'colors': {'primary': '#FF6B35'},
+                        'name': 'ACME Corporation',
+                        'url': 'https://acmecorp.com',
+                    },
+                    'description': 'Inline brand manifest',
+                },
+                {
+                    'data': 'https://cdn.acmecorp.com/brand-manifest.json',
+                    'description': 'URL string reference to hosted manifest',
+                },
+            ],
+            title='Brand Manifest Reference',
+        ),
+    ] = None
+    brief: Annotated[
+        str | None, Field(description='Natural language description of campaign requirements')
+    ] = None
+    context: context_1.ContextObject | None = None
+    ext: ext_1.ExtensionObject | None = None
+    filters: product_filters.ProductFilters | None = None

adcp/types/generated_poc/media_buy/get_products_response.py

@@ -0,0 +1,28 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/get_products_response.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..core import product
+
+
+class GetProductsResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    context: context_1.ContextObject | None = None
+    errors: Annotated[
+        list[error.Error] | None,
+        Field(description='Task-specific errors and warnings (e.g., product filtering issues)'),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    products: Annotated[list[product.Product], Field(description='Array of matching products')]

adcp/types/generated_poc/media_buy/list_authorized_properties_request.py

@@ -0,0 +1,38 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/list_authorized_properties_request.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field, RootModel
+
+from ..core import context as context_1
+from ..core import ext as ext_1
+
+
+class PublisherDomain(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="Publisher domain to filter by (e.g., 'cnn.com', 'espn.com')",
+            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
+        ),
+    ]
+
+
+class ListAuthorizedPropertiesRequest(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    context: context_1.ContextObject | None = None
+    ext: ext_1.ExtensionObject | None = None
+    publisher_domains: Annotated[
+        list[PublisherDomain] | None,
+        Field(
+            description='Filter to specific publisher domains (optional). If omitted, returns all publishers this agent represents.',
+            min_length=1,
+        ),
+    ] = None

adcp/types/generated_poc/media_buy/list_authorized_properties_response.py

@@ -0,0 +1,84 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/list_authorized_properties_response.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field, RootModel
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..enums import channels
+
+
+class PrimaryCountry(RootModel[str]):
+    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]
+
+
+class PublisherDomain(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
+            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
+        ),
+    ]
+
+
+class ListAuthorizedPropertiesResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    advertising_policies: Annotated[
+        str | None,
+        Field(
+            description="Publisher's advertising content policies, restrictions, and guidelines in natural language. May include prohibited categories, blocked advertisers, restricted tactics, brand safety requirements, or links to full policy documentation.",
+            max_length=10000,
+            min_length=1,
+        ),
+    ] = None
+    context: context_1.ContextObject | None = None
+    errors: Annotated[
+        list[error.Error] | None,
+        Field(description='Task-specific errors and warnings (e.g., property availability issues)'),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    last_updated: Annotated[
+        AwareDatetime | None,
+        Field(
+            description="ISO 8601 timestamp of when the agent's publisher authorization list was last updated. Buyers can use this to determine if their cached publisher adagents.json files might be stale."
+        ),
+    ] = None
+    portfolio_description: Annotated[
+        str | None,
+        Field(
+            description='Markdown-formatted description of the property portfolio, including inventory types, audience characteristics, and special features.',
+            max_length=5000,
+            min_length=1,
+        ),
+    ] = None
+    primary_channels: Annotated[
+        list[channels.AdvertisingChannels] | None,
+        Field(
+            description='Primary advertising channels represented in this property portfolio. Helps buying agents quickly filter relevance.',
+            min_length=1,
+        ),
+    ] = None
+    primary_countries: Annotated[
+        list[PrimaryCountry] | None,
+        Field(
+            description='Primary countries (ISO 3166-1 alpha-2 codes) where properties are concentrated. Helps buying agents quickly filter relevance.',
+            min_length=1,
+        ),
+    ] = None
+    publisher_domains: Annotated[
+        list[PublisherDomain],
+        Field(
+            description="Publisher domains this agent is authorized to represent. Buyers should fetch each publisher's adagents.json to see property definitions and verify this agent is in their authorized_agents list with authorization scope.",
+            min_length=1,
+        ),
+    ]

adcp/types/generated_poc/media_buy/list_creative_formats_request.py

@@ -0,0 +1,74 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/list_creative_formats_request.json
+#   timestamp: 2025-11-22T19:54:03+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from ..core import context as context_1
+from ..core import ext as ext_1
+from ..core import format_id
+from ..enums import asset_content_type, format_category
+
+
+class ListCreativeFormatsRequest(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    asset_types: Annotated[
+        list[asset_content_type.AssetContentType] | None,
+        Field(
+            description="Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags."
+        ),
+    ] = None
+    context: context_1.ContextObject | None = None
+    ext: ext_1.ExtensionObject | None = None
+    format_ids: Annotated[
+        list[format_id.FormatId] | None,
+        Field(
+            description='Return only these specific format IDs (e.g., from get_products response)'
+        ),
+    ] = None
+    is_responsive: Annotated[
+        bool | None,
+        Field(
+            description='Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.'
+        ),
+    ] = None
+    max_height: Annotated[
+        int | None,
+        Field(
+            description='Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits.'
+        ),
+    ] = None
+    max_width: Annotated[
+        int | None,
+        Field(
+            description='Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits.'
+        ),
+    ] = None
+    min_height: Annotated[
+        int | None,
+        Field(
+            description='Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.'
+        ),
+    ] = None
+    min_width: Annotated[
+        int | None,
+        Field(
+            description='Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.'
+        ),
+    ] = None
+    name_search: Annotated[
+        str | None, Field(description='Search for formats by name (case-insensitive partial match)')
+    ] = None
+    type: Annotated[
+        format_category.FormatCategory | None,
+        Field(
+            description='Filter by format type (technical categories with distinct requirements)'
+        ),
+    ] = None

adcp/types/generated_poc/media_buy/list_creative_formats_response.py

@@ -0,0 +1,56 @@
+# generated by datamodel-codegen:
+#   filename:  media_buy/list_creative_formats_response.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..core import format
+from ..enums import creative_agent_capability
+
+
+class CreativeAgent(AdCPBaseModel):
+    agent_name: Annotated[
+        str | None, Field(description='Human-readable name for the creative agent')
+    ] = None
+    agent_url: Annotated[
+        AnyUrl,
+        Field(
+            description="Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats."
+        ),
+    ]
+    capabilities: Annotated[
+        list[creative_agent_capability.CreativeAgentCapability] | None,
+        Field(description='Capabilities this creative agent provides'),
+    ] = None
+
+
+class ListCreativeFormatsResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    context: context_1.ContextObject | None = None
+    creative_agents: Annotated[
+        list[CreativeAgent] | None,
+        Field(
+            description='Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.'
+        ),
+    ] = None
+    errors: Annotated[
+        list[error.Error] | None,
+        Field(description='Task-specific errors and warnings (e.g., format availability issues)'),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    formats: Annotated[
+        list[format.Format],
+        Field(
+            description="Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field."
+        ),
+    ]