# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Union
from typing_extensions import Literal, Annotated, TypedDict

from .._types import SequenceNotStr
from .._utils import PropertyInfo

__all__ = ["PhoneNumberListParams", "Filter", "FilterNumberType", "FilterVoiceConnectionName"]


class PhoneNumberListParams(TypedDict, total=False):
    filter: Filter
    """Consolidated filter parameter (deepObject style).

    Originally: filter[tag], filter[phone_number], filter[status],
    filter[country_iso_alpha2], filter[connection_id],
    filter[voice.connection_name], filter[voice.usage_payment_method],
    filter[billing_group_id], filter[emergency_address_id],
    filter[customer_reference], filter[number_type], filter[source]
    """

    handle_messaging_profile_error: Literal["true", "false"]
    """
    Although it is an infrequent occurrence, due to the highly distributed nature of
    the Telnyx platform, it is possible that there will be an issue when loading in
    Messaging Profile information. As such, when this parameter is set to `true` and
    an error in fetching this information occurs, messaging profile related fields
    will be omitted in the response and an error message will be included instead of
    returning a 503 error.
    """

    page_number: Annotated[int, PropertyInfo(alias="page[number]")]

    page_size: Annotated[int, PropertyInfo(alias="page[size]")]

    sort: Literal["purchased_at", "phone_number", "connection_name", "usage_payment_method"]
    """Specifies the sort order for results.

    If not given, results are sorted by created_at in descending order.
    """


class FilterNumberType(TypedDict, total=False):
    """Filter phone numbers by phone number type."""

    eq: Literal["local", "national", "toll_free", "mobile", "shared_cost"]
    """Filter phone numbers by phone number type."""


class FilterVoiceConnectionName(TypedDict, total=False):
    """Filter by voice connection name pattern matching."""

    contains: str
    """Filter contains connection name. Requires at least three characters."""

    ends_with: str
    """Filter ends with connection name. Requires at least three characters."""

    eq: str
    """Filter by connection name."""

    starts_with: str
    """Filter starts with connection name. Requires at least three characters."""


class Filter(TypedDict, total=False):
    """Consolidated filter parameter (deepObject style).

    Originally: filter[tag], filter[phone_number], filter[status], filter[country_iso_alpha2], filter[connection_id], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference], filter[number_type], filter[source]
    """

    billing_group_id: str
    """Filter by the billing_group_id associated with phone numbers.

    To filter to only phone numbers that have no billing group associated them, set
    the value of this filter to the string 'null'.
    """

    connection_id: str
    """Filter by connection_id."""

    country_iso_alpha2: Union[str, SequenceNotStr[str]]
    """Filter by phone number country ISO alpha-2 code.

    Can be a single value or an array of values.
    """

    customer_reference: str
    """Filter numbers via the customer_reference set."""

    emergency_address_id: str
    """Filter by the emergency_address_id associated with phone numbers.

    To filter only phone numbers that have no emergency address associated with
    them, set the value of this filter to the string 'null'.
    """

    number_type: FilterNumberType
    """Filter phone numbers by phone number type."""

    phone_number: str
    """Filter by phone number.

    Requires at least three digits. Non-numerical characters will result in no
    values being returned.
    """

    source: Literal["ported", "purchased"]
    """Filter phone numbers by their source.

    Use 'ported' for numbers ported from other carriers, or 'purchased' for numbers
    bought directly from Telnyx.
    """

    status: Literal[
        "purchase-pending",
        "purchase-failed",
        "port-pending",
        "active",
        "deleted",
        "port-failed",
        "emergency-only",
        "ported-out",
        "port-out-pending",
    ]
    """Filter by phone number status."""

    tag: str
    """Filter by phone number tags."""

    voice_connection_name: Annotated[FilterVoiceConnectionName, PropertyInfo(alias="voice.connection_name")]
    """Filter by voice connection name pattern matching."""

    voice_usage_payment_method: Annotated[
        Literal["pay-per-minute", "channel"], PropertyInfo(alias="voice.usage_payment_method")
    ]
    """Filter by usage_payment_method."""

    without_tags: Literal["true", "false"]
    """When set to 'true', filters for phone numbers that do not have any tags applied.

    All other values are ignored.
    """
