aliases.py

"""Semantic type aliases for generated AdCP types.

This module provides user-friendly aliases for generated types where the
auto-generated names don't match user expectations from reading the spec.

The code generator (datamodel-code-generator) creates numbered suffixes for
discriminated union variants (e.g., Response1, Response2), but users expect
semantic names (e.g., SuccessResponse, ErrorResponse).

Categories of aliases:

1. Discriminated Union Response Variants
   - Success/Error cases for API responses
   - Named to match the semantic meaning from the spec

2. Preview/Render Types
   - Input/Output/Request/Response variants
   - Numbered types mapped to their semantic purpose

3. Activation Keys
   - Signal activation key variants

DO NOT EDIT the generated types directly - they are regenerated from schemas.
Add aliases here for any types where the generated name is unclear.

Validation:
This module will raise ImportError at import time if any of the referenced
generated types do not exist. This ensures that schema changes are caught
immediately rather than at runtime when users try to use the aliases.
"""

from __future__ import annotations

from adcp.types._generated import (
    # Account reference variants
    AccountReference1,
    AccountReference2,
    # Activation responses
    ActivateSignalResponse1,
    ActivateSignalResponse2,
    # Activation key variants
    ActivationKey1,
    ActivationKey2,
    # Authorized agents
    AuthorizedAgents,
    AuthorizedAgents1,
    AuthorizedAgents2,
    AuthorizedAgents3,
    AuthorizedAgents4,
    AuthorizedAgents5,
    # Build creative responses
    BuildCreativeResponse1,
    BuildCreativeResponse2,
    # Calibrate content responses
    CalibrateContentResponse1,
    CalibrateContentResponse2,
    ConsentBasis,
    CpaPricingOption,
    CpcPricingOption,
    CpcvPricingOption,
    CpmPricingOption,
    CppPricingOption,
    CpvPricingOption,
    # Content standards responses
    CreateContentStandardsResponse1,
    CreateContentStandardsResponse2,
    # Create media buy responses
    CreateMediaBuyResponse1,
    CreateMediaBuyResponse2,
    # DAAST assets
    DaastAsset1,
    DaastAsset2,
    # Deployment types
    Deployment1,
    Deployment2,
    # Destination types
    Destination1,
    Destination2,
    FlatRatePricingOption,
    # Get account financials responses
    GetAccountFinancialsResponse1,
    GetAccountFinancialsResponse2,
    # Content standards get responses
    GetContentStandardsResponse1,
    GetContentStandardsResponse2,
    # Creative delivery requests
    GetCreativeDeliveryRequest1,
    GetCreativeDeliveryRequest2,
    GetCreativeDeliveryRequest3,
    # Get creative features responses
    GetCreativeFeaturesResponse1,
    GetCreativeFeaturesResponse2,
    # Media buy artifacts responses
    GetMediaBuyArtifactsResponse1,
    GetMediaBuyArtifactsResponse2,
    # Get products request variants
    GetProductsRequest1,
    GetProductsRequest2,
    GetProductsRequest3,
    # Get signals request variants
    GetSignalsRequest1,
    GetSignalsRequest2,
    # Content standards list responses
    ListContentStandardsResponse1,
    ListContentStandardsResponse2,
    # Log event responses
    LogEventResponse1,
    LogEventResponse2,
    # Preview creative requests
    PreviewCreativeRequest1,
    PreviewCreativeRequest2,
    PreviewCreativeRequest3,
    # Preview creative responses
    PreviewCreativeResponse1,
    PreviewCreativeResponse2,
    PreviewCreativeResponse3,
    # Preview renders (discriminated union by output_format)
    PreviewRender1,  # output_format='url'
    PreviewRender2,  # output_format='html'
    PreviewRender3,  # output_format='both'
    # Publisher properties types
    PropertyId,
    PropertyTag,
    # Performance feedback requests
    ProvidePerformanceFeedbackRequest1,
    ProvidePerformanceFeedbackRequest2,
    # Performance feedback responses
    ProvidePerformanceFeedbackResponse1,
    ProvidePerformanceFeedbackResponse2,
    # Signal pricing option variants
    SignalPricingOption5,
    SignalPricingOption6,
    SignalPricingOption7,
    # SI send message request variants
    SiSendMessageRequest1,
    SiSendMessageRequest2,
    # SubAssets
    SubAsset1,
    SubAsset2,
    # Sync accounts responses
    SyncAccountsResponse1,
    SyncAccountsResponse2,
    # Sync audiences responses
    SyncAudiencesResponse1,
    SyncAudiencesResponse2,
    # Sync catalogs responses
    SyncCatalogsResponse1,
    SyncCatalogsResponse2,
    # Sync creatives responses
    SyncCreativesResponse1,
    SyncCreativesResponse2,
    # Sync event sources responses
    SyncEventSourcesResponse1,
    SyncEventSourcesResponse2,
    TimeBasedPricingOption,
    # Update content standards responses
    UpdateContentStandardsResponse1,
    UpdateContentStandardsResponse2,
    # Update media buy requests
    UpdateMediaBuyRequest1,
    UpdateMediaBuyRequest2,
    # Update media buy responses
    UpdateMediaBuyResponse1,
    UpdateMediaBuyResponse2,
    # Validate content delivery responses
    ValidateContentDeliveryResponse1,
    ValidateContentDeliveryResponse2,
    # VAST assets
    VastAsset1,
    VastAsset2,
    VcpmPricingOption,
)

# CatalogFieldBinding1 = catalog_group binding; give it a semantic name.
from adcp.types._generated import CatalogFieldBinding1 as CatalogGroupBinding
from adcp.types._generated import (
    PublisherPropertySelector1 as PublisherPropertiesInternal,
)
from adcp.types._generated import (
    PublisherPropertySelector2 as PublisherPropertiesByIdInternal,
)
from adcp.types._generated import (
    PublisherPropertySelector3 as PublisherPropertiesByTagInternal,
)

# Note: Package collision resolved by PR #223
# Both create_media_buy and update_media_buy now return full Package objects
# No more separate reference type needed
# Import Package from _generated (still uses qualified name for internal reasons)
from adcp.types._generated import _PackageFromPackage as Package

# Status name collides across many modules. Preserve backward compat by importing
# the specific variant that was exported on main (media buy delivery status).
from adcp.types.generated_poc.media_buy.get_media_buy_delivery_response import (
    Status as MediaBuyDeliveryStatus,
)

# Audience name collides in _generated (delivery breakdown wins over sync request)
from adcp.types.generated_poc.media_buy.sync_audiences_request import (
    Audience as SyncAudiencesAudienceInternal,
)

# Import nested types that aren't exported by _generated but are useful for type hints
from adcp.types.generated_poc.media_buy.sync_catalogs_response import (
    Catalog as SyncCatalogResultInternal,
)
from adcp.types.generated_poc.media_buy.sync_creatives_response import (
    Creative as SyncCreativeResultInternal,
)

# ============================================================================
# ACCOUNT REFERENCE ALIASES - Identification Method Discriminated Unions
# ============================================================================
# AccountReference is a discriminated union with two identification methods:
#
# 1. By seller-assigned ID (account_id):
#    - Use when the buyer manages accounts via list_accounts or sync_accounts
#    - Requires seller-assigned account_id string
#
# 2. By natural key (brand + operator):
#    - Use when the seller resolves accounts internally from brand identity
#    - Requires brand reference + operator domain

AccountReferenceById = AccountReference1
"""Account reference using a seller-assigned account ID.

Use when the buyer manages accounts (e.g., picked from list_accounts or
sync_accounts). The account_id must match one returned by the seller.

Fields:
- account_id: Seller-assigned account identifier

Example:
    ```python
    from adcp import AccountReferenceById

    account = AccountReferenceById(account_id="acc_acme_001")
    ```
"""

AccountReferenceByNaturalKey = AccountReference2
"""Account reference using brand + operator natural key.

Use when the seller resolves accounts internally from brand identity.
The seller looks up the account based on the brand/operator combination.

Fields:
- brand: BrandReference identifying the advertiser
- operator: Domain of the entity operating on the brand's behalf

Example:
    ```python
    from adcp import AccountReferenceByNaturalKey

    account = AccountReferenceByNaturalKey(
        brand={"domain": "acme-corp.com"},
        operator="acme-corp.com"
    )
    ```
"""

# ============================================================================
# RESPONSE TYPE ALIASES - Success/Error Discriminated Unions
# ============================================================================
# These are atomic operations where the response is EITHER success OR error,
# never both. The numbered suffixes from the generator don't convey this
# critical semantic distinction.

# Activate Signal Response Variants
ActivateSignalSuccessResponse = ActivateSignalResponse1
"""Success response - signal activation succeeded."""

ActivateSignalErrorResponse = ActivateSignalResponse2
"""Error response - signal activation failed."""

# Build Creative Response Variants
BuildCreativeSuccessResponse = BuildCreativeResponse1
"""Success response - creative built successfully, manifest returned."""

BuildCreativeErrorResponse = BuildCreativeResponse2
"""Error response - creative build failed, no manifest created."""

# Create Media Buy Response Variants
CreateMediaBuySuccessResponse = CreateMediaBuyResponse1
"""Success response - media buy created successfully with media_buy_id."""

CreateMediaBuyErrorResponse = CreateMediaBuyResponse2
"""Error response - media buy creation failed, no media buy created."""

# Performance Feedback Response Variants
ProvidePerformanceFeedbackSuccessResponse = ProvidePerformanceFeedbackResponse1
"""Success response - performance feedback accepted."""

ProvidePerformanceFeedbackErrorResponse = ProvidePerformanceFeedbackResponse2
"""Error response - performance feedback rejected."""

# Sync Creatives Response Variants
SyncCreativesSuccessResponse = SyncCreativesResponse1
"""Success response - sync operation processed creatives."""

SyncCreativesErrorResponse = SyncCreativesResponse2
"""Error response - sync operation failed."""

# Sync Creative Result (nested type from SyncCreativesResponse1.creatives[])
SyncCreativeResult = SyncCreativeResultInternal
"""Result of syncing a single creative - indicates action taken (created, updated, failed, etc.)

This is the item type from SyncCreativesSuccessResponse.creatives[]. In TypeScript, this would be:
    type SyncCreativeResult = SyncCreativesSuccessResponse["creatives"][number]

Example usage:
    from adcp import SyncCreativeResult, SyncCreativesSuccessResponse

    def process_result(result: SyncCreativeResult) -> None:
        if result.action == "created":
            print(f"Created creative {result.creative_id}")
        elif result.action == "failed":
            print(f"Failed: {result.errors}")
"""

# Sync Accounts Response Variants
SyncAccountsSuccessResponse = SyncAccountsResponse1
"""Success response - accounts synced successfully."""

SyncAccountsErrorResponse = SyncAccountsResponse2
"""Error response - account sync failed."""

# Log Event Response Variants
LogEventSuccessResponse = LogEventResponse1
"""Success response - events logged successfully."""

LogEventErrorResponse = LogEventResponse2
"""Error response - event logging failed."""

# Sync Catalogs Response Variants
SyncCatalogsSuccessResponse = SyncCatalogsResponse1
"""Success response - sync operation processed catalogs (may include per-catalog failures)."""

SyncCatalogsErrorResponse = SyncCatalogsResponse2
"""Error response - operation failed completely, no catalogs were processed."""

# Sync Catalog Result (nested type from SyncCatalogsResponse1.catalogs[])
SyncCatalogResult = SyncCatalogResultInternal
"""Result of syncing a single catalog - indicates action taken and per-item status.

This is the item type from SyncCatalogsSuccessResponse.catalogs[]. In TypeScript, this would be:
    type SyncCatalogResult = SyncCatalogsSuccessResponse["catalogs"][number]

Example usage:
    from adcp import SyncCatalogResult, SyncCatalogsSuccessResponse

    def process_result(result: SyncCatalogResult) -> None:
        if result.action == "created":
            print(f"Created catalog {result.catalog_id}")
        elif result.action == "failed":
            print(f"Failed: {result.errors}")
"""

# Sync Event Sources Response Variants
SyncEventSourcesSuccessResponse = SyncEventSourcesResponse1
"""Success response - event sources synced successfully."""

SyncEventSourcesErrorResponse = SyncEventSourcesResponse2
"""Error response - event source sync failed."""

# Calibrate Content Response Variants
CalibrateContentSuccessResponse = CalibrateContentResponse1
"""Success response - content calibration completed."""

CalibrateContentErrorResponse = CalibrateContentResponse2
"""Error response - content calibration failed."""

# Validate Content Delivery Response Variants
ValidateContentDeliverySuccessResponse = ValidateContentDeliveryResponse1
"""Success response - content delivery validated."""

ValidateContentDeliveryErrorResponse = ValidateContentDeliveryResponse2
"""Error response - content delivery validation failed."""

# Get Content Standards Response Variants
GetContentStandardsSuccessResponse = GetContentStandardsResponse1
"""Success response - content standards retrieved."""

GetContentStandardsErrorResponse = GetContentStandardsResponse2
"""Error response - content standards retrieval failed."""

# List Content Standards Response Variants
ListContentStandardsSuccessResponse = ListContentStandardsResponse1
"""Success response - content standards listed."""

ListContentStandardsErrorResponse = ListContentStandardsResponse2
"""Error response - content standards listing failed."""

# Create Content Standards Response Variants
CreateContentStandardsSuccessResponse = CreateContentStandardsResponse1
"""Success response - content standards created."""

CreateContentStandardsErrorResponse = CreateContentStandardsResponse2
"""Error response - content standards creation failed."""

# Update Content Standards Response Variants
UpdateContentStandardsSuccessResponse = UpdateContentStandardsResponse1
"""Success response - content standards updated, returns standards_id."""

UpdateContentStandardsErrorResponse = UpdateContentStandardsResponse2
"""Error response - content standards update failed, includes errors."""

# Get Media Buy Artifacts Response Variants
GetMediaBuyArtifactsSuccessResponse = GetMediaBuyArtifactsResponse1
"""Success response - media buy artifacts retrieved."""

GetMediaBuyArtifactsErrorResponse = GetMediaBuyArtifactsResponse2
"""Error response - media buy artifacts retrieval failed."""

# Update Media Buy Response Variants
UpdateMediaBuySuccessResponse = UpdateMediaBuyResponse1
"""Success response - media buy updated successfully."""

UpdateMediaBuyErrorResponse = UpdateMediaBuyResponse2
"""Error response - media buy update failed, no changes applied."""

# Get Account Financials Response Variants
GetAccountFinancialsSuccessResponse = GetAccountFinancialsResponse1
"""Success response - account financials retrieved."""

GetAccountFinancialsErrorResponse = GetAccountFinancialsResponse2
"""Error response - account financials retrieval failed."""

# Sync Audiences Response Variants
SyncAudiencesSuccessResponse = SyncAudiencesResponse1
"""Success response - audiences synced successfully."""

SyncAudiencesErrorResponse = SyncAudiencesResponse2
"""Error response - audiences sync failed."""

# Get Creative Features Response Variants
GetCreativeFeaturesSuccessResponse = GetCreativeFeaturesResponse1
"""Success response - creative features retrieved."""

GetCreativeFeaturesErrorResponse = GetCreativeFeaturesResponse2
"""Error response - creative features retrieval failed."""

# ============================================================================
# REQUEST TYPE ALIASES - Operation Variants
# ============================================================================

# Preview Creative Request Variants
PreviewCreativeSingleRequest = PreviewCreativeRequest1
"""Single preview request with creative_manifest and optional format_id - request_type='single'."""

PreviewCreativeBatchRequest = PreviewCreativeRequest2
"""Batch preview request with array of requests (1-50) - request_type='batch'."""

PreviewCreativeVariantRequest = PreviewCreativeRequest3
"""Variant preview request using variant_id - request_type='variant'."""


# Get Products Request Variants
GetProductsRefineRequest = GetProductsRequest3
"""Get products request in refine mode - buying_mode='refine'.

Used to iterate on previous product results with refinement actions
(include, omit, more_like_this) at request, product, or proposal scope.

Example:
    ```python
    from adcp import GetProductsRefineRequest

    request = GetProductsRefineRequest(
        buying_mode="refine",
        account={"account_id": "acc_123"},
        refine=[{"action": "more_like_this", "product_id": "prod_456"}]
    )
    ```
"""

# Performance Feedback Request Variants
ProvidePerformanceFeedbackByMediaBuyRequest = ProvidePerformanceFeedbackRequest1
"""Performance feedback request identified by media_buy_id (required)."""

ProvidePerformanceFeedbackByBuyerRefRequest = ProvidePerformanceFeedbackRequest2
"""Performance feedback request identified by buyer_ref (required)."""

# Update Media Buy Request Variants
UpdateMediaBuyPackagesRequest = UpdateMediaBuyRequest1
"""Update request modifying packages in the media buy."""

UpdateMediaBuyPropertiesRequest = UpdateMediaBuyRequest2
"""Update request modifying media buy properties (not packages)."""

# Get Creative Delivery Request Variants
GetCreativeDeliveryByMediaBuyRequest = GetCreativeDeliveryRequest1
"""Request creative delivery by media_buy_ids."""

GetCreativeDeliveryByBuyerRefRequest = GetCreativeDeliveryRequest2
"""Request creative delivery by media_buy_buyer_refs."""

GetCreativeDeliveryByCreativeRequest = GetCreativeDeliveryRequest3
"""Request creative delivery by creative_ids."""

# Get Products Request Variants (by buying_mode)
GetProductsBriefRequest = GetProductsRequest1
"""Get products in brief mode - buying_mode='brief', requires brief text."""

GetProductsWholesaleRequest = GetProductsRequest2
"""Get products in wholesale mode - buying_mode='wholesale', raw inventory."""

# Get Signals Request Variants
GetSignalsRequest = GetSignalsRequest1 | GetSignalsRequest2
"""Union of GetSignalsRequest variants. Use instead of the RootModel wrapper."""

GetSignalsDiscoveryRequest = GetSignalsRequest1
"""Discover signals by natural language spec - signal_spec required."""

GetSignalsLookupRequest = GetSignalsRequest2
"""Look up signals by IDs - signal_ids required."""

# SI Send Message Request Variants
SiSendTextMessageRequest = SiSendMessageRequest1
"""Send a text message to the brand agent - message required."""

SiSendActionResponseRequest = SiSendMessageRequest2
"""Send an action response to the brand agent - action_response required."""

# ============================================================================
# ACTIVATION KEY ALIASES
# ============================================================================

SegmentIdActivationKey = ActivationKey1
"""Activation key using segment ID targeting - type='segment_id'."""

KeyValueActivationKey = ActivationKey2
"""Activation key using key-value pair targeting - type='key_value'."""

# ============================================================================
# PREVIEW/RENDER TYPE ALIASES
# ============================================================================

# Preview Creative Response Variants
PreviewCreativeSingleResponse = PreviewCreativeResponse1
"""Single preview response with previews array and expires_at - response_type='single'."""

PreviewCreativeBatchResponse = PreviewCreativeResponse2
"""Batch preview response with results array - response_type='batch'."""

PreviewCreativeVariantResponse = PreviewCreativeResponse3
"""Variant preview response with variant_id and rendered pieces - response_type='variant'."""


# Preview Render Aliases (discriminated union by output_format)
UrlPreviewRender = PreviewRender1
"""Preview render with output_format='url' and preview_url for iframe embedding."""

HtmlPreviewRender = PreviewRender2
"""Preview render with output_format='html' and preview_html for direct embedding."""

BothPreviewRender = PreviewRender3
"""Preview render with output_format='both' and both preview_url and preview_html."""

# ============================================================================
# ASSET TYPE ALIASES - Delivery & Kind Discriminated Unions
# ============================================================================

# VAST Asset Variants (discriminated by delivery_type)
UrlVastAsset = VastAsset1
"""VAST asset delivered via URL endpoint - delivery_type='url'."""

InlineVastAsset = VastAsset2
"""VAST asset with inline XML content - delivery_type='inline'."""

# DAAST Asset Variants (discriminated by delivery_type)
UrlDaastAsset = DaastAsset1
"""DAAST asset delivered via URL endpoint - delivery_type='url'."""

InlineDaastAsset = DaastAsset2
"""DAAST asset with inline XML content - delivery_type='inline'."""

# SubAsset Variants (discriminated by asset_kind)
MediaSubAsset = SubAsset1
"""SubAsset for media content (images, videos) - asset_kind='media', provides content_uri."""

TextSubAsset = SubAsset2
"""SubAsset for text content (headlines, body text) - asset_kind='text', provides content."""

# ============================================================================
# PACKAGE TYPE ALIASES - Resolving Type Name Collisions
# ============================================================================
# The AdCP schemas define two genuinely different types both named "Package":
#
# 1. Full Package (from package.json schema):
#    - Complete operational package with all fields (budget, pricing_option_id, etc.)
#    - Used in MediaBuy, update operations, and package management
#    - Has 12+ fields for full package configuration
#
# Package collision resolved by PR #223:
# - create-media-buy-response.json now returns full Package objects (not minimal refs)
# - update-media-buy-response.json already returned full Package objects
# - Both operations return identical Package structures
# - Single Package type imported above, no aliases needed

# ============================================================================
# PUBLISHER PROPERTIES ALIASES - Selection Type Discriminated Unions
# ============================================================================
# The AdCP schemas define PublisherProperties as a discriminated union with
# three variants based on the `selection_type` field:
#
# 1. All Properties (selection_type='all'):
#    - Includes all properties from the publisher
#    - Only requires publisher_domain
#
# 2. By ID (selection_type='by_id'):
#    - Specific properties selected by property_id
#    - Requires publisher_domain + property_ids array
#
# 3. By Tag (selection_type='by_tag'):
#    - Properties selected by tags
#    - Requires publisher_domain + property_tags array
#
# These semantic aliases match the discriminator values and make code more
# readable when constructing or pattern-matching publisher properties.

PublisherPropertiesAll = PublisherPropertiesInternal
"""Publisher properties covering all properties from the publisher.

This variant uses selection_type='all' and includes all properties listed
in the publisher's adagents.json file.

Fields:
- publisher_domain: Domain where adagents.json is hosted
- selection_type: Literal['all']

Example:
    ```python
    from adcp import PublisherPropertiesAll

    props = PublisherPropertiesAll(
        publisher_domain="example.com",
        selection_type="all"
    )
    ```
"""

PublisherPropertiesById = PublisherPropertiesByIdInternal
"""Publisher properties selected by specific property IDs.

This variant uses selection_type='by_id' and specifies an explicit list
of property IDs from the publisher's adagents.json file.

Fields:
- publisher_domain: Domain where adagents.json is hosted
- selection_type: Literal['by_id']
- property_ids: List of PropertyId (non-empty)

Example:
    ```python
    from adcp import PublisherPropertiesById, PropertyId

    props = PublisherPropertiesById(
        publisher_domain="example.com",
        selection_type="by_id",
        property_ids=[PropertyId("homepage"), PropertyId("sports_section")]
    )
    ```
"""

PublisherPropertiesByTag = PublisherPropertiesByTagInternal
"""Publisher properties selected by tags.

This variant uses selection_type='by_tag' and specifies property tags.
The product covers all properties in the publisher's adagents.json that
have these tags.

Fields:
- publisher_domain: Domain where adagents.json is hosted
- selection_type: Literal['by_tag']
- property_tags: List of PropertyTag (non-empty)

Example:
    ```python
    from adcp import PublisherPropertiesByTag, PropertyTag

    props = PublisherPropertiesByTag(
        publisher_domain="example.com",
        selection_type="by_tag",
        property_tags=[PropertyTag("premium"), PropertyTag("video")]
    )
    ```
"""

# ============================================================================
# DEPLOYMENT & DESTINATION ALIASES - Signal Deployment Type Discriminated Unions
# ============================================================================
# The AdCP schemas define Deployment and Destination as discriminated unions
# with two variants based on the `type` field:
#
# Deployment (where a signal is activated):
# - Platform (type='platform'): DSP platform with platform ID
# - Agent (type='agent'): Sales agent with agent URL
#
# Destination (where a signal can be activated):
# - Platform (type='platform'): Target DSP platform
# - Agent (type='agent'): Target sales agent
#
# These are used in GetSignalsResponse to describe signal availability and
# activation status across different advertising platforms and agents.

PlatformDeployment = Deployment1
"""Signal deployment to a DSP platform.

This variant uses type='platform' for platform-based signal deployments
like The Trade Desk, Amazon DSP, etc.

Fields:
- type: Literal['platform']
- platform: Platform identifier (e.g., 'the-trade-desk')
- account: Optional account identifier
- is_live: Whether signal is currently active
- deployed_at: Activation timestamp if live
- activation_key: Targeting key if live and accessible
- estimated_activation_duration_minutes: Time to complete activation

Example:
    ```python
    from adcp import PlatformDeployment

    deployment = PlatformDeployment(
        type="platform",
        platform="the-trade-desk",
        account="advertiser-123",
        is_live=True,
        deployed_at=datetime.now(timezone.utc)
    )
    ```
"""

AgentDeployment = Deployment2
"""Signal deployment to a sales agent.

This variant uses type='agent' for agent-based signal deployments
using agent URLs.

Fields:
- type: Literal['agent']
- agent_url: URL identifying the destination agent
- account: Optional account identifier
- is_live: Whether signal is currently active
- deployed_at: Activation timestamp if live
- activation_key: Targeting key if live and accessible
- estimated_activation_duration_minutes: Time to complete activation

Example:
    ```python
    from adcp import AgentDeployment

    deployment = AgentDeployment(
        type="agent",
        agent_url="https://agent.example.com",
        is_live=False,
        estimated_activation_duration_minutes=30.0
    )
    ```
"""

PlatformDestination = Destination1
"""Available signal destination on a DSP platform.

This variant uses type='platform' for platform-based signal destinations.

Fields:
- type: Literal['platform']
- platform: Platform identifier (e.g., 'the-trade-desk', 'amazon-dsp')
- account: Optional account identifier on the platform

Example:
    ```python
    from adcp import PlatformDestination

    destination = PlatformDestination(
        type="platform",
        platform="the-trade-desk",
        account="advertiser-123"
    )
    ```
"""

AgentDestination = Destination2
"""Available signal destination via a sales agent.

This variant uses type='agent' for agent-based signal destinations.

Fields:
- type: Literal['agent']
- agent_url: URL identifying the destination agent
- account: Optional account identifier on the agent

Example:
    ```python
    from adcp import AgentDestination

    destination = AgentDestination(
        type="agent",
        agent_url="https://agent.example.com",
        account="partner-456"
    )
    ```
"""

# ============================================================================
# AUTHORIZED AGENTS ALIASES - Authorization Type Discriminated Unions
# ============================================================================
# The AdCP adagents.json schema defines AuthorizedAgents as a discriminated
# union with four variants based on the `authorization_type` field:
#
# 1. Property IDs (authorization_type='property_ids'):
#    - Agent authorized for specific property IDs
#    - Requires property_ids array
#
# 2. Property Tags (authorization_type='property_tags'):
#    - Agent authorized for properties matching tags
#    - Requires property_tags array
#
# 3. Inline Properties (authorization_type='inline_properties'):
#    - Agent authorized with inline property definitions
#    - Requires properties array with full Property objects
#
# 4. Publisher Properties (authorization_type='publisher_properties'):
#    - Agent authorized for properties from other publisher domains
#    - Requires publisher_properties array
#
# These define which sales agents are authorized to sell inventory and which
# properties they can access.

AuthorizedAgentsByPropertyId = AuthorizedAgents
"""Authorized agent with specific property IDs.

This variant uses authorization_type='property_ids' for agents authorized
to sell specific properties identified by their IDs.

Fields:
- authorization_type: Literal['property_ids']
- authorized_for: Human-readable description
- property_ids: List of PropertyId (non-empty)
- url: Agent's API endpoint URL

Example:
    ```python
    from adcp.types.aliases import AuthorizedAgentsByPropertyId, PropertyId

    agent = AuthorizedAgentsByPropertyId(
        authorization_type="property_ids",
        authorized_for="Premium display inventory",
        property_ids=[PropertyId("homepage"), PropertyId("sports")],
        url="https://agent.example.com"
    )
    ```
"""

AuthorizedAgentsByPropertyTag = AuthorizedAgents1
"""Authorized agent with property tags.

This variant uses authorization_type='property_tags' for agents authorized
to sell properties identified by matching tags.

Fields:
- authorization_type: Literal['property_tags']
- authorized_for: Human-readable description
- property_tags: List of PropertyTag (non-empty)
- url: Agent's API endpoint URL

Example:
    ```python
    from adcp.types.aliases import AuthorizedAgentsByPropertyTag, PropertyTag

    agent = AuthorizedAgentsByPropertyTag(
        authorization_type="property_tags",
        authorized_for="Video inventory",
        property_tags=[PropertyTag("video"), PropertyTag("premium")],
        url="https://agent.example.com"
    )
    ```
"""

AuthorizedAgentsByInlineProperties = AuthorizedAgents2
"""Authorized agent with inline property definitions.

This variant uses authorization_type='inline_properties' for agents with
inline Property objects rather than references to the top-level properties array.

Fields:
- authorization_type: Literal['inline_properties']
- authorized_for: Human-readable description
- properties: List of Property objects (non-empty)
- url: Agent's API endpoint URL

Example:
    ```python
    from adcp.types.aliases import AuthorizedAgentsByInlineProperties
    from adcp.types.stable import Property

    agent = AuthorizedAgentsByInlineProperties(
        authorization_type="inline_properties",
        authorized_for="Custom inventory bundle",
        properties=[...],  # Full Property objects
        url="https://agent.example.com"
    )
    ```
"""

AuthorizedAgentsByPublisherProperties = AuthorizedAgents3
"""Authorized agent for properties from other publishers.

This variant uses authorization_type='publisher_properties' for agents
authorized to sell inventory from other publisher domains.

Fields:
- authorization_type: Literal['publisher_properties']
- authorized_for: Human-readable description
- publisher_properties: List of PublisherPropertySelector variants (non-empty)
- url: Agent's API endpoint URL

Example:
    ```python
    from adcp.types.aliases import (
        AuthorizedAgentsByPublisherProperties,
        PublisherPropertiesAll
    )

    agent = AuthorizedAgentsByPublisherProperties(
        authorization_type="publisher_properties",
        authorized_for="Network inventory across publishers",
        publisher_properties=[
            PublisherPropertiesAll(
                publisher_domain="publisher1.com",
                selection_type="all"
            )
        ],
        url="https://agent.example.com"
    )
    ```
"""

AuthorizedAgentsBySignalId = AuthorizedAgents4
"""Authorized agent for specific signal IDs.

This variant uses authorization_type='signal_ids' for agents authorized
to resell specific signals identified by their IDs.

Fields:
- authorization_type: Literal['signal_ids']
- authorized_for: Human-readable description of signals authorization
- signal_ids: List of SignalId (non-empty)
- url: Authorized signals agent's API endpoint URL
"""

AuthorizedAgentsBySignalTag = AuthorizedAgents5
"""Authorized agent for signals matching tags.

This variant uses authorization_type='signal_tags' for agents authorized
to resell signals identified by matching tags.

Fields:
- authorization_type: Literal['signal_tags']
- authorized_for: Human-readable description of signals authorization
- signal_tags: List of SignalTag (non-empty)
- url: Authorized signals agent's API endpoint URL
"""

# ============================================================================
# UNION TYPE ALIASES - For Type Hints and Pattern Matching
# ============================================================================
# These union aliases provide convenient types for function signatures,
# type hints, and pattern matching without having to manually construct
# the union each time.

# Deployment union (for signals)
Deployment = PlatformDeployment | AgentDeployment
"""Union type for all deployment variants.

Use this for type hints when a function accepts any deployment type:

Example:
    ```python
    def process_deployment(deployment: Deployment) -> None:
        if isinstance(deployment, PlatformDeployment):
            print(f"Platform: {deployment.platform}")
        elif isinstance(deployment, AgentDeployment):
            print(f"Agent: {deployment.agent_url}")
    ```
"""

# Destination union (for signals)
Destination = PlatformDestination | AgentDestination
"""Union type for all destination variants.

Use this for type hints when a function accepts any destination type:

Example:
    ```python
    def format_destination(dest: Destination) -> str:
        if isinstance(dest, PlatformDestination):
            return f"Platform: {dest.platform}"
        elif isinstance(dest, AgentDestination):
            return f"Agent: {dest.agent_url}"
    ```
"""

# Authorized agent union (for adagents.json)
AuthorizedAgent = (
    AuthorizedAgentsByPropertyId
    | AuthorizedAgentsByPropertyTag
    | AuthorizedAgentsByInlineProperties
    | AuthorizedAgentsByPublisherProperties
    | AuthorizedAgentsBySignalId
    | AuthorizedAgentsBySignalTag
)
"""Union type for all authorized agent variants.

Use this for type hints when processing agents from adagents.json:

Example:
    ```python
    def validate_agent(agent: AuthorizedAgent) -> bool:
        match agent.authorization_type:
            case "property_ids":
                return len(agent.property_ids) > 0
            case "property_tags":
                return len(agent.property_tags) > 0
            case "inline_properties":
                return len(agent.properties) > 0
            case "publisher_properties":
                return len(agent.publisher_properties) > 0
    ```
"""

# Publisher properties union (for product requests)
PublisherProperties = PublisherPropertiesAll | PublisherPropertiesById | PublisherPropertiesByTag
"""Union type for all publisher properties variants.

Use this for type hints in product filtering:

Example:
    ```python
    def filter_products(props: PublisherProperties) -> None:
        match props.selection_type:
            case "all":
                print("All properties from publisher")
            case "by_id":
                print(f"Properties: {props.property_ids}")
            case "by_tag":
                print(f"Tags: {props.property_tags}")
    ```
"""

# ============================================================================
# SIGNAL PRICING OPTION ALIASES - Pricing Model Discriminated Unions
# ============================================================================
# SignalPricingOption is a discriminated union with three pricing models.
# Variants 5/6/7 combine the model-specific fields with pricing_option_id.

CpmSignalPricingOption = SignalPricingOption5
"""Signal pricing option with model='cpm' - fixed cost per thousand impressions."""

PercentOfMediaSignalPricingOption = SignalPricingOption6
"""Signal pricing option with model='percent_of_media' - percentage of media spend."""

FlatFeeSignalPricingOption = SignalPricingOption7
"""Signal pricing option with model='flat_fee' - fixed charge per reporting period."""

# ============================================================================
# SYNC AUDIENCES INPUT ALIASES
# ============================================================================
# The Audience input type for SyncAudiencesRequest is exported here following
# the same pattern as SyncCreativeResult and SyncCatalogResult.

SyncAudiencesAudience = SyncAudiencesAudienceInternal
"""Audience segment payload for SyncAudiencesRequest.audiences[].

Required: audience_id (buyer's identifier for the audience).
Optional: name, consent_basis, add (AudienceMember items), remove, delete.

Example:
    ```python
    from adcp import SyncAudiencesAudience, SyncAudiencesRequest

    request = SyncAudiencesRequest(
        account={"account_id": "acc_123"},
        audiences=[
            SyncAudiencesAudience(
                audience_id="seg_456",
                name="High-value customers",
                consent_basis="consent"
            )
        ]
    )
    ```
"""

# ============================================================================
# PRICING OPTION UNION TYPE - For Type Hints Without RootModel Wrapper
# ============================================================================
# The generated PricingOption is a RootModel wrapper that mypy doesn't recognize
# as compatible with the individual variant types. This union alias provides a
# way to type-hint pricing options without the wrapper, fixing mypy list-item errors.

PricingOption = (
    CpmPricingOption
    | VcpmPricingOption
    | CpcPricingOption
    | CpcvPricingOption
    | CpvPricingOption
    | CppPricingOption
    | CpaPricingOption
    | FlatRatePricingOption
    | TimeBasedPricingOption
)
"""Union type for all pricing option variants.

Use this for type hints when constructing Product.pricing_options or any field
that accepts pricing options. This fixes mypy list-item errors that occur when
using the individual variant types.

Example:
    ```python
    from adcp.types import Product, CpmPricingOption, PricingOption

    # Type hint for a list of pricing options
    def get_pricing(options: list[PricingOption]) -> None:
        for opt in options:
            print(f"Model: {opt.pricing_model}")

    # Use in Product construction (no more mypy errors!)
    product = Product(
        product_id="test",
        name="Test Product",
        pricing_options=[
            CpmPricingOption(
                pricing_model="cpm",
                floor_price=1.50,
                currency="USD"
            )
        ]
    )
    ```
"""

# ============================================================================
# EXPORTS
# ============================================================================

__all__ = [
    # Account reference variants
    "AccountReferenceById",
    "AccountReferenceByNaturalKey",
    # Activation key variants
    "SegmentIdActivationKey",
    "KeyValueActivationKey",
    # Activation responses
    "ActivateSignalSuccessResponse",
    "ActivateSignalErrorResponse",
    # Asset type aliases
    "BothPreviewRender",
    "HtmlPreviewRender",
    "InlineDaastAsset",
    "InlineVastAsset",
    "MediaSubAsset",
    "TextSubAsset",
    "UrlDaastAsset",
    "UrlPreviewRender",
    "UrlVastAsset",
    # Authorized agent variants
    "AuthorizedAgentsByPropertyId",
    "AuthorizedAgentsByPropertyTag",
    "AuthorizedAgentsByInlineProperties",
    "AuthorizedAgentsByPublisherProperties",
    "AuthorizedAgentsBySignalId",
    "AuthorizedAgentsBySignalTag",
    # Authorized agent union
    "AuthorizedAgent",
    # Build creative responses
    "BuildCreativeSuccessResponse",
    "BuildCreativeErrorResponse",
    # Calibrate content responses
    "CalibrateContentSuccessResponse",
    "CalibrateContentErrorResponse",
    # Content standards responses
    "CreateContentStandardsSuccessResponse",
    "CreateContentStandardsErrorResponse",
    "UpdateContentStandardsSuccessResponse",
    "UpdateContentStandardsErrorResponse",
    "GetContentStandardsSuccessResponse",
    "GetContentStandardsErrorResponse",
    "ListContentStandardsSuccessResponse",
    "ListContentStandardsErrorResponse",
    # Create media buy responses
    "CreateMediaBuySuccessResponse",
    "CreateMediaBuyErrorResponse",
    # Creative delivery requests
    "GetCreativeDeliveryByMediaBuyRequest",
    "GetCreativeDeliveryByBuyerRefRequest",
    "GetCreativeDeliveryByCreativeRequest",
    # Log event responses
    "LogEventSuccessResponse",
    "LogEventErrorResponse",
    # Media buy artifacts responses
    "GetMediaBuyArtifactsSuccessResponse",
    "GetMediaBuyArtifactsErrorResponse",
    # Performance feedback responses
    "ProvidePerformanceFeedbackSuccessResponse",
    "ProvidePerformanceFeedbackErrorResponse",
    # Preview creative requests
    "PreviewCreativeSingleRequest",
    "PreviewCreativeBatchRequest",
    "PreviewCreativeVariantRequest",
    # Preview creative responses
    "PreviewCreativeSingleResponse",
    "PreviewCreativeBatchResponse",
    "PreviewCreativeVariantResponse",
    # Get products request variants
    "GetProductsBriefRequest",
    "GetProductsWholesaleRequest",
    "GetProductsRefineRequest",
    # Get signals request variants
    "GetSignalsDiscoveryRequest",
    "GetSignalsLookupRequest",
    # Performance feedback request variants
    "ProvidePerformanceFeedbackByMediaBuyRequest",
    "ProvidePerformanceFeedbackByBuyerRefRequest",
    # SI send message request variants
    "SiSendTextMessageRequest",
    "SiSendActionResponseRequest",
    # Sync accounts responses
    "SyncAccountsSuccessResponse",
    "SyncAccountsErrorResponse",
    # Sync creatives responses
    "SyncCreativesSuccessResponse",
    "SyncCreativesErrorResponse",
    "SyncCreativeResult",
    # Sync catalogs responses
    "SyncCatalogResult",
    "SyncCatalogsSuccessResponse",
    "SyncCatalogsErrorResponse",
    # Sync event sources responses
    "SyncEventSourcesSuccessResponse",
    "SyncEventSourcesErrorResponse",
    # Update media buy requests
    "UpdateMediaBuyPackagesRequest",
    "UpdateMediaBuyPropertiesRequest",
    # Update media buy responses
    "UpdateMediaBuySuccessResponse",
    "UpdateMediaBuyErrorResponse",
    # Validate content delivery responses
    "ValidateContentDeliverySuccessResponse",
    "ValidateContentDeliveryErrorResponse",
    # Get account financials responses
    "GetAccountFinancialsSuccessResponse",
    "GetAccountFinancialsErrorResponse",
    # Sync audiences responses
    "SyncAudiencesSuccessResponse",
    "SyncAudiencesErrorResponse",
    # Get creative features responses
    "GetCreativeFeaturesSuccessResponse",
    "GetCreativeFeaturesErrorResponse",
    # Package type aliases
    "Package",
    # Publisher properties types
    "PropertyId",
    "PropertyTag",
    # Publisher properties variants
    "PublisherPropertiesAll",
    "PublisherPropertiesById",
    "PublisherPropertiesByTag",
    # Publisher properties union
    "PublisherProperties",
    # Deployment variants
    "PlatformDeployment",
    "AgentDeployment",
    # Deployment union
    "Deployment",
    # Destination variants
    "PlatformDestination",
    "AgentDestination",
    # Destination union
    "Destination",
    # Pricing option union
    "PricingOption",
    # Signal pricing option variants
    "CpmSignalPricingOption",
    "FlatFeeSignalPricingOption",
    "PercentOfMediaSignalPricingOption",
    # Sync audiences input type
    "SyncAudiencesAudience",
    "ConsentBasis",
    # Status (backward compat - delivery status, not invoice status)
    "MediaBuyDeliveryStatus",
    # Catalog field binding semantic alias
    "CatalogGroupBinding",
]