adcp 1.6.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

adcp/types/generated_poc/pricing_option.py

@@ -0,0 +1,365 @@
+# generated by datamodel-codegen:
+#   filename:  pricing-option.json
+#   timestamp: 2025-11-15T17:41:03+00:00
+
+from __future__ import annotations
+
+from typing import Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field, RootModel
+
+
+class CpmFixedOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpm_usd_guaranteed')",
+    )
+    pricing_model: Literal["cpm"] = Field(..., description="Cost per 1,000 impressions")
+    rate: float = Field(..., description="Fixed CPM rate (cost per 1,000 impressions)", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class PriceGuidance(AdCPBaseModel):
+    floor: float = Field(
+        ..., description="Minimum bid price - publisher will reject bids under this value", ge=0.0
+    )
+    p25: float | None = Field(None, description="25th percentile winning price", ge=0.0)
+    p50: float | None = Field(None, description="Median winning price", ge=0.0)
+    p75: float | None = Field(None, description="75th percentile winning price", ge=0.0)
+    p90: float | None = Field(None, description="90th percentile winning price", ge=0.0)
+
+
+class CpmAuctionOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpm_usd_auction')",
+    )
+    pricing_model: Literal["cpm"] = Field(..., description="Cost per 1,000 impressions")
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    price_guidance: PriceGuidance = Field(
+        ..., description="Pricing guidance for auction-based CPM bidding"
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class VcpmFixedOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_guaranteed')",
+    )
+    pricing_model: Literal["vcpm"] = Field(
+        ..., description="Cost per 1,000 viewable impressions (MRC standard)"
+    )
+    rate: float = Field(
+        ..., description="Fixed vCPM rate (cost per 1,000 viewable impressions)", ge=0.0
+    )
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class PriceGuidance1(AdCPBaseModel):
+    floor: float = Field(..., description="Minimum acceptable bid price", ge=0.0)
+    p25: float | None = Field(None, description="25th percentile of recent winning bids", ge=0.0)
+    p50: float | None = Field(None, description="Median of recent winning bids", ge=0.0)
+    p75: float | None = Field(None, description="75th percentile of recent winning bids", ge=0.0)
+    p90: float | None = Field(None, description="90th percentile of recent winning bids", ge=0.0)
+
+
+class VcpmAuctionOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_auction')",
+    )
+    pricing_model: Literal["vcpm"] = Field(
+        ..., description="Cost per 1,000 viewable impressions (MRC standard)"
+    )
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    price_guidance: PriceGuidance1 = Field(
+        ..., description="Statistical guidance for auction pricing"
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class CpcOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpc_usd_fixed')",
+    )
+    pricing_model: Literal["cpc"] = Field(..., description="Cost per click")
+    rate: float = Field(..., description="Fixed CPC rate (cost per click)", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class CpcvOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpcv_usd_guaranteed')",
+    )
+    pricing_model: Literal["cpcv"] = Field(
+        ..., description="Cost per completed view (100% completion)"
+    )
+    rate: float = Field(..., description="Fixed CPCV rate (cost per 100% completion)", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class ViewThreshold(RootModel[float]):
+    root: float = Field(
+        ...,
+        description="Percentage completion threshold for CPV pricing (0.0 to 1.0, e.g., 0.5 = 50% completion)",
+        ge=0.0,
+        le=1.0,
+    )
+
+
+class ViewThreshold1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    duration_seconds: int = Field(
+        ...,
+        description="Seconds of viewing required (e.g., 30 for YouTube-style '30 seconds = view')",
+        ge=1,
+    )
+
+
+class Parameters(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    view_threshold: ViewThreshold | ViewThreshold1
+
+
+class CpvOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpv_usd_50pct')",
+    )
+    pricing_model: Literal["cpv"] = Field(..., description="Cost per view at threshold")
+    rate: float = Field(..., description="Fixed CPV rate (cost per view)", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    parameters: Parameters = Field(
+        ..., description="CPV-specific parameters defining the view threshold"
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class Parameters1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    demographic: str = Field(
+        ...,
+        description="Target demographic in Nielsen format: P/M/W/A/C + age range. Examples: P18-49 (Persons 18-49), M25-54 (Men 25-54), W35+ (Women 35+), A18-34 (Adults 18-34), C2-11 (Children 2-11)",
+        pattern="^[PMWAC][0-9]{2}(-[0-9]{2}|\\+)$",
+    )
+    min_points: float | None = Field(
+        None, description="Minimum GRPs/TRPs required for this pricing option", ge=0.0
+    )
+
+
+class CppOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'cpp_usd_p18-49')",
+    )
+    pricing_model: Literal["cpp"] = Field(..., description="Cost per Gross Rating Point")
+    rate: float = Field(..., description="Fixed CPP rate (cost per rating point)", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    parameters: Parameters1 = Field(
+        ..., description="CPP-specific parameters for demographic targeting and GRP requirements"
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class Parameters2(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    duration_hours: float | None = Field(
+        None, description="Duration in hours for time-based flat rate pricing (DOOH)", ge=0.0
+    )
+    sov_percentage: float | None = Field(
+        None, description="Guaranteed share of voice as percentage (DOOH, 0-100)", ge=0.0, le=100.0
+    )
+    loop_duration_seconds: int | None = Field(
+        None, description="Duration of ad loop rotation in seconds (DOOH)", ge=1
+    )
+    min_plays_per_hour: int | None = Field(
+        None,
+        description="Minimum number of times ad plays per hour (DOOH frequency guarantee)",
+        ge=0,
+    )
+    venue_package: str | None = Field(
+        None,
+        description="Named venue package identifier for DOOH (e.g., 'times_square_network', 'airport_terminals')",
+    )
+    estimated_impressions: int | None = Field(
+        None,
+        description="Estimated impressions for this flat rate option (informational, commonly used with SOV or time-based DOOH)",
+        ge=0,
+    )
+    daypart: str | None = Field(
+        None,
+        description="Specific daypart for time-based pricing (e.g., 'morning_commute', 'evening_prime', 'overnight')",
+    )
+
+
+class FlatRateOption(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pricing_option_id: str = Field(
+        ...,
+        description="Unique identifier for this pricing option within the product (e.g., 'flat_rate_usd_24h_takeover')",
+    )
+    pricing_model: Literal["flat_rate"] = Field(
+        ..., description="Fixed cost regardless of delivery volume"
+    )
+    rate: float = Field(..., description="Flat rate cost", ge=0.0)
+    currency: str = Field(
+        ...,
+        description="ISO 4217 currency code",
+        examples=["USD", "EUR", "GBP", "JPY"],
+        pattern="^[A-Z]{3}$",
+    )
+    is_fixed: Literal[True] = Field(
+        ..., description="Whether this is a fixed rate (true) or auction-based (false)"
+    )
+    parameters: Parameters2 | None = Field(
+        None, description="Flat rate parameters for DOOH and time-based campaigns"
+    )
+    min_spend_per_package: float | None = Field(
+        None,
+        description="Minimum spend requirement per package using this pricing option, in the specified currency",
+        ge=0.0,
+    )
+
+
+class PricingOption(
+    RootModel[
+        CpmFixedOption
+        | CpmAuctionOption
+        | VcpmFixedOption
+        | VcpmAuctionOption
+        | CpcOption
+        | CpcvOption
+        | CpvOption
+        | CppOption
+        | FlatRateOption
+    ]
+):
+    root: (
+        CpmFixedOption
+        | CpmAuctionOption
+        | VcpmFixedOption
+        | VcpmAuctionOption
+        | CpcOption
+        | CpcvOption
+        | CpvOption
+        | CppOption
+        | FlatRateOption
+    ) = Field(
+        ...,
+        description="A pricing model option offered by a publisher for a product. Each pricing model has its own schema with model-specific requirements.",
+        title="Pricing Option",
+    )

adcp/types/generated_poc/product.py

@@ -0,0 +1,211 @@
+# generated by datamodel-codegen:
+#   filename:  product.json
+#   timestamp: 2025-11-15T22:03:55+00:00
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field, RootModel, model_validator
+
+from . import cpc_option, cpcv_option, cpm_auction_option, cpm_fixed_option, cpp_option, cpv_option
+from . import creative_policy as creative_policy_1
+from . import delivery_type as delivery_type_1
+from . import flat_rate_option
+from . import format_id as format_id_1
+from . import measurement as measurement_1
+from . import placement
+from . import reporting_capabilities as reporting_capabilities_1
+from . import vcpm_auction_option, vcpm_fixed_option
+
+
+class DeliveryMeasurement(AdCPBaseModel):
+    notes: Annotated[
+        str | None,
+        Field(
+            description="Additional details about measurement methodology in plain language (e.g., 'MRC-accredited viewability. 50% in-view for 1s display / 2s video', 'Panel-based demographic measurement updated monthly')"
+        ),
+    ] = None
+    provider: Annotated[
+        str,
+        Field(
+            description="Measurement provider(s) used for this product (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions')"
+        ),
+    ]
+
+
+class ProductCard(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description="Creative format defining the card layout (typically product_card_standard)"
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(description="Asset manifest for rendering the card, structure defined by the format"),
+    ]
+
+
+class ProductCardDetailed(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description="Creative format defining the detailed card layout (typically product_card_detailed)"
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(
+            description="Asset manifest for rendering the detailed card, structure defined by the format"
+        ),
+    ]
+
+
+class PropertyId(RootModel[str]):
+    root: Annotated[str, Field(pattern="^[a-z0-9_]+$")]
+
+
+class PublisherProperties(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    property_ids: Annotated[
+        list[PropertyId],
+        Field(description="Specific property IDs from the publisher's adagents.json", min_length=1),
+    ]
+    publisher_domain: 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])?)*$",
+        ),
+    ]
+    selection_type: Annotated[
+        Literal["by_id"],
+        Field(description="Discriminator indicating selection by specific property IDs"),
+    ]
+
+
+class PropertyTag(PropertyId):
+    pass
+
+
+class PublisherProperties3(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    property_tags: Annotated[
+        list[PropertyTag],
+        Field(
+            description="Property tags from the publisher's adagents.json. Product covers all properties with these tags",
+            min_length=1,
+        ),
+    ]
+    publisher_domain: 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])?)*$",
+        ),
+    ]
+    selection_type: Annotated[
+        Literal["by_tag"], Field(description="Discriminator indicating selection by property tags")
+    ]
+
+
+class Product(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    brief_relevance: Annotated[
+        str | None,
+        Field(
+            description="Explanation of why this product matches the brief (only included when brief is provided)"
+        ),
+    ] = None
+    creative_policy: creative_policy_1.CreativePolicy | None = None
+    delivery_measurement: Annotated[
+        DeliveryMeasurement,
+        Field(
+            description="Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. REQUIRED for all products."
+        ),
+    ]
+    delivery_type: delivery_type_1.DeliveryType
+    description: Annotated[
+        str, Field(description="Detailed description of the product and its inventory")
+    ]
+    estimated_exposures: Annotated[
+        int | None,
+        Field(description="Estimated exposures/impressions for guaranteed products", ge=0),
+    ] = None
+    expires_at: Annotated[
+        AwareDatetime | None, Field(description="Expiration timestamp for custom products")
+    ] = None
+    format_ids: Annotated[
+        list[format_id_1.FormatId],
+        Field(
+            description="Array of supported creative format IDs - structured format_id objects with agent_url and id"
+        ),
+    ]
+    is_custom: Annotated[bool | None, Field(description="Whether this is a custom product")] = None
+    measurement: measurement_1.Measurement | None = None
+    name: Annotated[str, Field(description="Human-readable product name")]
+    placements: Annotated[
+        list[placement.Placement] | None,
+        Field(
+            description="Optional array of specific placements within this product. When provided, buyers can target specific placements when assigning creatives.",
+            min_length=1,
+        ),
+    ] = None
+    pricing_options: Annotated[
+        list[
+            cpm_fixed_option.CpmFixedRatePricingOption
+            | cpm_auction_option.CpmAuctionPricingOption
+            | vcpm_fixed_option.VcpmFixedRatePricingOption
+            | vcpm_auction_option.VcpmAuctionPricingOption
+            | cpc_option.CpcPricingOption
+            | cpcv_option.CpcvPricingOption
+            | cpv_option.CpvPricingOption
+            | cpp_option.CppPricingOption
+            | flat_rate_option.FlatRatePricingOption
+        ],
+        Field(description="Available pricing models for this product", min_length=1),
+    ]
+    product_card: Annotated[
+        ProductCard | None,
+        Field(
+            description="Optional standard visual card (300x400px) for displaying this product in user interfaces. Can be rendered via preview_creative or pre-generated."
+        ),
+    ] = None
+    product_card_detailed: Annotated[
+        ProductCardDetailed | None,
+        Field(
+            description="Optional detailed card with carousel and full specifications. Provides rich product presentation similar to media kit pages."
+        ),
+    ] = None
+    product_id: Annotated[str, Field(description="Unique identifier for the product")]
+    publisher_properties: Annotated[
+        list[PublisherProperties | PublisherProperties3],
+        Field(
+            description="Publisher properties covered by this product. Buyers fetch actual property definitions from each publisher's adagents.json and validate agent authorization.",
+            min_length=1,
+        ),
+    ]
+    reporting_capabilities: reporting_capabilities_1.ReportingCapabilities | None = None
+
+    @model_validator(mode="after")
+    def validate_publisher_properties_items(self) -> "Product":
+        """Validate all publisher_properties items."""
+        from adcp.validation import validate_product
+
+        data = self.model_dump()
+        validate_product(data)
+        return self

adcp/types/generated_poc/promoted_offerings.py

@@ -0,0 +1,102 @@
+# generated by datamodel-codegen:
+#   filename:  promoted-offerings.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 promoted_products
+
+
+class AssetType(Enum):
+    image = "image"
+    video = "video"
+    audio = "audio"
+    vast = "vast"
+    daast = "daast"
+    text = "text"
+    url = "url"
+    html = "html"
+    css = "css"
+    javascript = "javascript"
+    webhook = "webhook"
+
+
+class AssetSelectors(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    asset_types: Annotated[
+        list[AssetType] | None, Field(description="Filter by asset type (e.g., ['image', 'video'])")
+    ] = None
+    exclude_tags: Annotated[
+        list[str] | None, Field(description="Exclude assets with these tags")
+    ] = None
+    tags: Annotated[
+        list[str] | None,
+        Field(description="Select assets with specific tags (e.g., ['holiday', 'premium'])"),
+    ] = None
+
+
+class Offering(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    assets: Annotated[
+        list[dict[str, Any]] | None, Field(description="Assets specific to this offering")
+    ] = None
+    description: Annotated[str | None, Field(description="Description of what's being offered")] = (
+        None
+    )
+    name: Annotated[
+        str, Field(description="Offering name (e.g., 'Winter Sale', 'New Product Launch')")
+    ]
+
+
+class PromotedOfferings(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    asset_selectors: Annotated[
+        AssetSelectors | None,
+        Field(description="Selectors to choose specific assets from the brand manifest"),
+    ] = None
+    brand_manifest: Annotated[
+        brand_manifest_1.BrandManifest | AnyUrl,
+        Field(
+            description="Brand information manifest containing assets, themes, and guidelines. 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",
+        ),
+    ]
+    offerings: Annotated[
+        list[Offering] | None,
+        Field(
+            description="Inline offerings for campaigns without a product catalog. Each offering has a name, description, and associated assets."
+        ),
+    ] = None
+    product_selectors: Annotated[
+        promoted_products.PromotedProducts | None,
+        Field(
+            description="Selectors to choose which products/offerings from the brand manifest product catalog to promote"
+        ),
+    ] = None