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

adcp/types/generated_poc/format.py

@@ -0,0 +1,260 @@
+# generated by datamodel-codegen:
+#   filename:  format.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+from . import format_id as format_id_1
+
+
+class AssetType(Enum):
+    image = "image"
+    video = "video"
+    audio = "audio"
+    vast = "vast"
+    daast = "daast"
+    text = "text"
+    markdown = "markdown"
+    html = "html"
+    css = "css"
+    javascript = "javascript"
+    url = "url"
+    webhook = "webhook"
+    promoted_offerings = "promoted_offerings"
+
+
+class AssetsRequired(AdCPBaseModel):
+    asset_id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for this asset. Creative manifests MUST use this exact value as the key in the assets object."
+        ),
+    ]
+    asset_role: Annotated[
+        str | None,
+        Field(
+            description="Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests—use asset_id instead. This field is for human-readable documentation and UI display only."
+        ),
+    ] = None
+    asset_type: Annotated[AssetType, Field(description="Type of asset")]
+    item_type: Annotated[
+        Literal["individual"],
+        Field(description="Discriminator indicating this is an individual asset requirement"),
+    ]
+    required: Annotated[bool | None, Field(description="Whether this asset is required")] = None
+    requirements: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description="Technical requirements for this asset (dimensions, file size, duration, etc.)"
+        ),
+    ] = None
+
+
+class Asset(AdCPBaseModel):
+    asset_id: Annotated[str, Field(description="Identifier for this asset within the group")]
+    asset_role: Annotated[
+        str | None,
+        Field(
+            description="Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests—use asset_id instead. This field is for human-readable documentation and UI display only."
+        ),
+    ] = None
+    asset_type: Annotated[AssetType, Field(description="Type of asset")]
+    required: Annotated[
+        bool | None, Field(description="Whether this asset is required in each repetition")
+    ] = None
+    requirements: Annotated[
+        dict[str, Any] | None, Field(description="Technical requirements for this asset")
+    ] = None
+
+
+class AssetsRequired1(AdCPBaseModel):
+    asset_group_id: Annotated[
+        str, Field(description="Identifier for this asset group (e.g., 'product', 'slide', 'card')")
+    ]
+    assets: Annotated[list[Asset], Field(description="Assets within each repetition of this group")]
+    item_type: Annotated[
+        Literal["repeatable_group"],
+        Field(description="Discriminator indicating this is a repeatable asset group"),
+    ]
+    max_count: Annotated[int, Field(description="Maximum number of repetitions allowed", ge=1)]
+    min_count: Annotated[int, Field(description="Minimum number of repetitions required", ge=1)]
+
+
+class FormatCard(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description="Creative format defining the card layout (typically format_card_standard)"
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(description="Asset manifest for rendering the card, structure defined by the format"),
+    ]
+
+
+class FormatCardDetailed(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description="Creative format defining the detailed card layout (typically format_card_detailed)"
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(
+            description="Asset manifest for rendering the detailed card, structure defined by the format"
+        ),
+    ]
+
+
+class Responsive(AdCPBaseModel):
+    height: bool
+    width: bool
+
+
+class Unit(Enum):
+    px = "px"
+    dp = "dp"
+    inches = "inches"
+    cm = "cm"
+
+
+class Dimensions(AdCPBaseModel):
+    aspect_ratio: Annotated[
+        str | None,
+        Field(
+            description="Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')",
+            pattern="^\\d+:\\d+$",
+        ),
+    ] = None
+    height: Annotated[
+        float | None, Field(description="Fixed height in specified units", ge=0.0)
+    ] = None
+    max_height: Annotated[
+        float | None, Field(description="Maximum height for responsive renders", ge=0.0)
+    ] = None
+    max_width: Annotated[
+        float | None, Field(description="Maximum width for responsive renders", ge=0.0)
+    ] = None
+    min_height: Annotated[
+        float | None, Field(description="Minimum height for responsive renders", ge=0.0)
+    ] = None
+    min_width: Annotated[
+        float | None, Field(description="Minimum width for responsive renders", ge=0.0)
+    ] = None
+    responsive: Annotated[
+        Responsive | None, Field(description="Indicates which dimensions are responsive/fluid")
+    ] = None
+    unit: Annotated[Unit, Field(description="Unit of measurement for dimensions")]
+    width: Annotated[float | None, Field(description="Fixed width in specified units", ge=0.0)] = (
+        None
+    )
+
+
+class Render(AdCPBaseModel):
+    dimensions: Annotated[Dimensions, Field(description="Dimensions for this rendered piece")]
+    role: Annotated[
+        str,
+        Field(
+            description="Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')"
+        ),
+    ]
+
+
+class Type(Enum):
+    audio = "audio"
+    video = "video"
+    display = "display"
+    native = "native"
+    dooh = "dooh"
+    rich_media = "rich_media"
+    universal = "universal"
+
+
+class Format(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    assets_required: Annotated[
+        list[AssetsRequired | AssetsRequired1] | None,
+        Field(
+            description="Array of required assets or asset groups for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames)."
+        ),
+    ] = None
+    delivery: Annotated[
+        dict[str, Any] | None,
+        Field(description="Delivery method specifications (e.g., hosted, VAST, third-party tags)"),
+    ] = None
+    description: Annotated[
+        str | None,
+        Field(
+            description="Plain text explanation of what this format does and what assets it requires"
+        ),
+    ] = None
+    example_url: Annotated[
+        AnyUrl | None,
+        Field(
+            description="Optional URL to showcase page with examples and interactive demos of this format"
+        ),
+    ] = None
+    format_card: Annotated[
+        FormatCard | None,
+        Field(
+            description="Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated."
+        ),
+    ] = None
+    format_card_detailed: Annotated[
+        FormatCardDetailed | None,
+        Field(
+            description="Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages."
+        ),
+    ] = None
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(description="Structured format identifier with agent URL and format name"),
+    ]
+    name: Annotated[str, Field(description="Human-readable format name")]
+    output_format_ids: Annotated[
+        list[format_id_1.FormatId] | None,
+        Field(
+            description="For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats)."
+        ),
+    ] = None
+    preview_image: Annotated[
+        AnyUrl | None,
+        Field(
+            description="DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach."
+        ),
+    ] = None
+    renders: Annotated[
+        list[Render] | None,
+        Field(
+            description="Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.",
+            min_length=1,
+        ),
+    ] = None
+    supported_macros: Annotated[
+        list[str] | None,
+        Field(
+            description="List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling."
+        ),
+    ] = None
+    type: Annotated[
+        Type,
+        Field(
+            description="Media type of this format - determines rendering method and asset requirements"
+        ),
+    ]

adcp/types/generated_poc/format_id.py

@@ -0,0 +1,29 @@
+# generated by datamodel-codegen:
+#   filename:  format-id.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+
+class FormatId(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    agent_url: Annotated[
+        AnyUrl,
+        Field(
+            description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)"
+        ),
+    ]
+    id: Annotated[
+        str,
+        Field(
+            description="Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')",
+            pattern="^[a-zA-Z0-9_-]+$",
+        ),
+    ]

adcp/types/generated_poc/frequency_cap.py

@@ -0,0 +1,19 @@
+# generated by datamodel-codegen:
+#   filename:  frequency-cap.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class FrequencyCap(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    suppress_minutes: Annotated[
+        float, Field(description="Minutes to suppress after impression", ge=0.0)
+    ]

adcp/types/generated_poc/frequency_cap_scope.py

@@ -0,0 +1,16 @@
+# generated by datamodel-codegen:
+#   filename:  frequency-cap-scope.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field, RootModel
+
+
+class FrequencyCapScope(RootModel[Literal["package"]]):
+    root: Annotated[
+        Literal["package"],
+        Field(description="Scope for frequency cap application", title="Frequency Cap Scope"),
+    ]

adcp/types/generated_poc/get_media_buy_delivery_request.py

@@ -0,0 +1,65 @@
+# generated by datamodel-codegen:
+#   filename:  get-media-buy-delivery-request.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class StatusFilter(Enum):
+    active = "active"
+    pending = "pending"
+    paused = "paused"
+    completed = "completed"
+    failed = "failed"
+    all = "all"
+
+
+class StatusFilterEnum(Enum):
+    active = "active"
+    pending = "pending"
+    paused = "paused"
+    completed = "completed"
+    failed = "failed"
+
+
+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: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata."
+        ),
+    ] = None
+    end_date: Annotated[
+        str | None,
+        Field(
+            description="End date for reporting period (YYYY-MM-DD)",
+            pattern="^\\d{4}-\\d{2}-\\d{2}$",
+        ),
+    ] = 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[
+        StatusFilter | list[StatusFilterEnum] | None,
+        Field(description="Filter by status. Can be a single status or array of statuses"),
+    ] = None

adcp/types/generated_poc/get_media_buy_delivery_response.py

@@ -0,0 +1,220 @@
+# generated by datamodel-codegen:
+#   filename:  get-media-buy-delivery-response.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field
+
+from . import error
+from . import pricing_model as pricing_model_1
+from .delivery_metrics import DeliveryMetrics
+
+
+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 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}$",
+        ),
+    ]
+    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")]
+    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: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers."
+        ),
+    ] = 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
+    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/get_products_request.py

@@ -0,0 +1,83 @@
+# generated by datamodel-codegen:
+#   filename:  get-products-request.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+from . import brand_manifest_ref as brand_manifest_1
+from . import delivery_type as delivery_type_1
+from . import format_id
+
+
+class FormatType(Enum):
+    video = "video"
+    display = "display"
+    audio = "audio"
+
+
+class Filters(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    delivery_type: delivery_type_1.DeliveryType | None = None
+    format_ids: Annotated[
+        list[format_id.FormatId] | None, Field(description="Filter by specific format IDs")
+    ] = None
+    format_types: Annotated[
+        list[FormatType] | None, Field(description="Filter by format types")
+    ] = None
+    is_fixed_price: Annotated[
+        bool | None, Field(description="Filter for fixed price vs auction products")
+    ] = None
+    min_exposures: Annotated[
+        int | None,
+        Field(description="Minimum exposures/impressions needed for measurement validity", ge=1),
+    ] = None
+    standard_formats_only: Annotated[
+        bool | None, Field(description="Only return products accepting IAB standard formats")
+    ] = None
+
+
+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: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata."
+        ),
+    ] = None
+    filters: Annotated[
+        Filters | None, Field(description="Structured filters for product discovery")
+    ] = None