client.py

# This file was auto-generated by Fern from our API Definition.

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from .raw_client import AsyncRawPhoneNumbersClient, RawPhoneNumbersClient
from .types.add_phone_numbers_request_inbound_config import AddPhoneNumbersRequestInboundConfig
from .types.add_phone_numbers_request_outbound_config import AddPhoneNumbersRequestOutboundConfig
from .types.add_phone_numbers_request_provider import AddPhoneNumbersRequestProvider
from .types.add_phone_numbers_response import AddPhoneNumbersResponse
from .types.get_phone_numbers_response import GetPhoneNumbersResponse
from .types.list_phone_numbers_response_item import ListPhoneNumbersResponseItem
from .types.update_phone_numbers_request_inbound_config import UpdatePhoneNumbersRequestInboundConfig
from .types.update_phone_numbers_request_outbound_config import UpdatePhoneNumbersRequestOutboundConfig
from .types.update_phone_numbers_response import UpdatePhoneNumbersResponse

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class PhoneNumbersClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawPhoneNumbersClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawPhoneNumbersClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawPhoneNumbersClient
        """
        return self._raw_client

    def list(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.List[ListPhoneNumbersResponseItem]:
        """
        Retrieve a list of all imported phone numbers under the current account.

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[ListPhoneNumbersResponseItem]
            Request was successful. The response body contains a JSON array of phone number configurations.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.phone_numbers.list()
        """
        _response = self._raw_client.list(request_options=request_options)
        return _response.data

    def add(
        self,
        *,
        provider: AddPhoneNumbersRequestProvider,
        phone_number: str,
        label: str,
        inbound_config: AddPhoneNumbersRequestInboundConfig,
        outbound_config: AddPhoneNumbersRequestOutboundConfig,
        inbound: typing.Optional[bool] = OMIT,
        outbound: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AddPhoneNumbersResponse:
        """
        Import a pre-configured phone number that can be used for inbound or outbound calls.

        Parameters
        ----------
        provider : AddPhoneNumbersRequestProvider
            Number provider:
            - `byo`: BYO (Bring Your Own)
            - `twilio`: Twilio

        phone_number : str
            Telephone number in E.164 format.

        label : str
            A label used to identify the number.

        inbound_config : AddPhoneNumbersRequestInboundConfig
            SIP inbound call configuration.

        outbound_config : AddPhoneNumbersRequestOutboundConfig
            SIP outbound call configuration.

        inbound : typing.Optional[bool]
            Whether the number supports inbound calls.

        outbound : typing.Optional[bool]
            Whether the number supports outbound calls.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AddPhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora
        from agora_agent.phone_numbers import (
            AddPhoneNumbersRequestInboundConfig,
            AddPhoneNumbersRequestOutboundConfig,
        )

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.phone_numbers.add(
            provider="byo",
            phone_number="+19876543210",
            label="Sales Hotline",
            inbound=True,
            outbound=True,
            inbound_config=AddPhoneNumbersRequestInboundConfig(
                allowed_addresses=["112.126.15.64/27"],
            ),
            outbound_config=AddPhoneNumbersRequestOutboundConfig(
                address="xxx:xxx@sip.example.com",
                transport="tls",
            ),
        )
        """
        _response = self._raw_client.add(
            provider=provider,
            phone_number=phone_number,
            label=label,
            inbound_config=inbound_config,
            outbound_config=outbound_config,
            inbound=inbound,
            outbound=outbound,
            request_options=request_options,
        )
        return _response.data

    def get(
        self, phone_number: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetPhoneNumbersResponse:
        """
        Retrieve detailed information for a specific phone number.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetPhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.phone_numbers.get(
            phone_number="phone_number",
        )
        """
        _response = self._raw_client.get(phone_number, request_options=request_options)
        return _response.data

    def delete(self, phone_number: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Remove an imported phone number from the system.

        After calling this endpoint, the number stops receiving calls routed through this system. To delete the number from the service provider, remove it in the service provider's console.
        > This operation only removes the number configuration from the Agora system; the number stored with the phone service provider is not deleted.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.phone_numbers.delete(
            phone_number="phone_number",
        )
        """
        _response = self._raw_client.delete(phone_number, request_options=request_options)
        return _response.data

    def update(
        self,
        phone_number: str,
        *,
        inbound_config: typing.Optional[UpdatePhoneNumbersRequestInboundConfig] = OMIT,
        outbound_config: typing.Optional[UpdatePhoneNumbersRequestOutboundConfig] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdatePhoneNumbersResponse:
        """
        Update the configuration for a phone number.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        inbound_config : typing.Optional[UpdatePhoneNumbersRequestInboundConfig]
            Update inbound call configuration. Passing `null` will clear the configuration.

        outbound_config : typing.Optional[UpdatePhoneNumbersRequestOutboundConfig]
            Update outbound call configuration. Passing `null` will clear the configuration.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdatePhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora
        from agora_agent.phone_numbers import (
            UpdatePhoneNumbersRequestInboundConfig,
            UpdatePhoneNumbersRequestOutboundConfig,
        )

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.phone_numbers.update(
            phone_number="phone_number",
            inbound_config=UpdatePhoneNumbersRequestInboundConfig(
                pipeline_id="xxxxx",
            ),
            outbound_config=UpdatePhoneNumbersRequestOutboundConfig(
                pipeline_id="xxxxx",
            ),
        )
        """
        _response = self._raw_client.update(
            phone_number,
            inbound_config=inbound_config,
            outbound_config=outbound_config,
            request_options=request_options,
        )
        return _response.data


class AsyncPhoneNumbersClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawPhoneNumbersClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawPhoneNumbersClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawPhoneNumbersClient
        """
        return self._raw_client

    async def list(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.List[ListPhoneNumbersResponseItem]:
        """
        Retrieve a list of all imported phone numbers under the current account.

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[ListPhoneNumbersResponseItem]
            Request was successful. The response body contains a JSON array of phone number configurations.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.phone_numbers.list()


        asyncio.run(main())
        """
        _response = await self._raw_client.list(request_options=request_options)
        return _response.data

    async def add(
        self,
        *,
        provider: AddPhoneNumbersRequestProvider,
        phone_number: str,
        label: str,
        inbound_config: AddPhoneNumbersRequestInboundConfig,
        outbound_config: AddPhoneNumbersRequestOutboundConfig,
        inbound: typing.Optional[bool] = OMIT,
        outbound: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AddPhoneNumbersResponse:
        """
        Import a pre-configured phone number that can be used for inbound or outbound calls.

        Parameters
        ----------
        provider : AddPhoneNumbersRequestProvider
            Number provider:
            - `byo`: BYO (Bring Your Own)
            - `twilio`: Twilio

        phone_number : str
            Telephone number in E.164 format.

        label : str
            A label used to identify the number.

        inbound_config : AddPhoneNumbersRequestInboundConfig
            SIP inbound call configuration.

        outbound_config : AddPhoneNumbersRequestOutboundConfig
            SIP outbound call configuration.

        inbound : typing.Optional[bool]
            Whether the number supports inbound calls.

        outbound : typing.Optional[bool]
            Whether the number supports outbound calls.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AddPhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora
        from agora_agent.phone_numbers import (
            AddPhoneNumbersRequestInboundConfig,
            AddPhoneNumbersRequestOutboundConfig,
        )

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.phone_numbers.add(
                provider="byo",
                phone_number="+19876543210",
                label="Sales Hotline",
                inbound=True,
                outbound=True,
                inbound_config=AddPhoneNumbersRequestInboundConfig(
                    allowed_addresses=["112.126.15.64/27"],
                ),
                outbound_config=AddPhoneNumbersRequestOutboundConfig(
                    address="xxx:xxx@sip.example.com",
                    transport="tls",
                ),
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.add(
            provider=provider,
            phone_number=phone_number,
            label=label,
            inbound_config=inbound_config,
            outbound_config=outbound_config,
            inbound=inbound,
            outbound=outbound,
            request_options=request_options,
        )
        return _response.data

    async def get(
        self, phone_number: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetPhoneNumbersResponse:
        """
        Retrieve detailed information for a specific phone number.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetPhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.phone_numbers.get(
                phone_number="phone_number",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(phone_number, request_options=request_options)
        return _response.data

    async def delete(self, phone_number: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Remove an imported phone number from the system.

        After calling this endpoint, the number stops receiving calls routed through this system. To delete the number from the service provider, remove it in the service provider's console.
        > This operation only removes the number configuration from the Agora system; the number stored with the phone service provider is not deleted.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.phone_numbers.delete(
                phone_number="phone_number",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete(phone_number, request_options=request_options)
        return _response.data

    async def update(
        self,
        phone_number: str,
        *,
        inbound_config: typing.Optional[UpdatePhoneNumbersRequestInboundConfig] = OMIT,
        outbound_config: typing.Optional[UpdatePhoneNumbersRequestOutboundConfig] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdatePhoneNumbersResponse:
        """
        Update the configuration for a phone number.

        Parameters
        ----------
        phone_number : str
            Telephone number in E.164 format. For example, +11234567890.

        inbound_config : typing.Optional[UpdatePhoneNumbersRequestInboundConfig]
            Update inbound call configuration. Passing `null` will clear the configuration.

        outbound_config : typing.Optional[UpdatePhoneNumbersRequestOutboundConfig]
            Update outbound call configuration. Passing `null` will clear the configuration.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdatePhoneNumbersResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora
        from agora_agent.phone_numbers import (
            UpdatePhoneNumbersRequestInboundConfig,
            UpdatePhoneNumbersRequestOutboundConfig,
        )

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.phone_numbers.update(
                phone_number="phone_number",
                inbound_config=UpdatePhoneNumbersRequestInboundConfig(
                    pipeline_id="xxxxx",
                ),
                outbound_config=UpdatePhoneNumbersRequestOutboundConfig(
                    pipeline_id="xxxxx",
                ),
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update(
            phone_number,
            inbound_config=inbound_config,
            outbound_config=outbound_config,
            request_options=request_options,
        )
        return _response.data