Add AgoraPool and AsyncAgoraPool wrapper clients

- Create AgoraPool that wraps Agora with domain pool
- Create AsyncAgoraPool that wraps AsyncAgora with domain pool
- Automatically use pool's current URL as base URL
- Expose pool, next_region(), select_best_domain(), get_current_url() methods
- Export AgoraPool and AsyncAgoraPool from main package

Co-Authored-By: blank@buildwithfern.com <blank@buildwithfern.com>

Author: devin-ai-integration[bot]

src/agoraio/__init__.py

@@ -9,11 +9,14 @@
     from . import agents, core, phone_numbers, telephony
     from .client import Agora, AsyncAgora
     from .core.domain import Area, Pool, create_pool
+    from .pool_client import AgoraPool, AsyncAgoraPool
     from .version import __version__
 _dynamic_imports: typing.Dict[str, str] = {
     "Agora": ".client",
+    "AgoraPool": ".pool_client",
     "Area": ".core.domain",
     "AsyncAgora": ".client",
+    "AsyncAgoraPool": ".pool_client",
     "Pool": ".core.domain",
     "__version__": ".version",
     "agents": ".agents",
@@ -45,4 +48,4 @@ def __dir__():
     return sorted(lazy_attrs)
 
 
-__all__ = ["Agora", "Area", "AsyncAgora", "Pool", "__version__", "agents", "core", "create_pool", "phone_numbers", "telephony"]
+__all__ = ["Agora", "AgoraPool", "Area", "AsyncAgora", "AsyncAgoraPool", "Pool", "__version__", "agents", "core", "create_pool", "phone_numbers", "telephony"]

src/agoraio/pool_client.py

@@ -0,0 +1,279 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from __future__ import annotations
+
+import typing
+
+import httpx
+
+from .core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from .core.domain import Area, Pool
+
+if typing.TYPE_CHECKING:
+    from .agents.client import AgentsClient, AsyncAgentsClient
+    from .phone_numbers.client import AsyncPhoneNumbersClient, PhoneNumbersClient
+    from .telephony.client import AsyncTelephonyClient, TelephonyClient
+
+
+class AgoraPool:
+    """
+    AgoraPool is a wrapper around Agora that uses a domain pool
+    for regional URL cycling and automatic domain selection.
+
+    This client automatically:
+    - Selects the best domain based on DNS resolution
+    - Cycles through region prefixes on request failures
+    - Supports US, EU, AP, and CN areas
+
+    Parameters
+    ----------
+    area : Area
+        The area to use for regional URL selection.
+
+    username : typing.Union[str, typing.Callable[[], str]]
+    password : typing.Union[str, typing.Callable[[], str]]
+    headers : typing.Optional[typing.Dict[str, str]]
+        Additional headers to send with every request.
+
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
+
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
+
+    httpx_client : typing.Optional[httpx.Client]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
+
+    Examples
+    --------
+    from agoraio import AgoraPool, Area
+
+    client = AgoraPool(
+        area=Area.US,
+        username="YOUR_USERNAME",
+        password="YOUR_PASSWORD",
+    )
+    """
+
+    def __init__(
+        self,
+        *,
+        area: Area,
+        username: typing.Union[str, typing.Callable[[], str]],
+        password: typing.Union[str, typing.Callable[[], str]],
+        headers: typing.Optional[typing.Dict[str, str]] = None,
+        timeout: typing.Optional[float] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.Client] = None,
+    ):
+        self._pool = Pool(area)
+        _defaulted_timeout = (
+            timeout if timeout is not None else 60 if httpx_client is None else httpx_client.timeout.read
+        )
+        self._client_wrapper = SyncClientWrapper(
+            base_url=self._pool.get_current_url(),
+            username=username,
+            password=password,
+            headers=headers,
+            httpx_client=httpx_client
+            if httpx_client is not None
+            else httpx.Client(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
+            if follow_redirects is not None
+            else httpx.Client(timeout=_defaulted_timeout),
+            timeout=_defaulted_timeout,
+        )
+        self._agents: typing.Optional[AgentsClient] = None
+        self._telephony: typing.Optional[TelephonyClient] = None
+        self._phone_numbers: typing.Optional[PhoneNumbersClient] = None
+
+    @property
+    def pool(self) -> Pool:
+        """
+        Get the underlying domain pool for advanced usage.
+        You can use this to manually cycle regions or select the best domain.
+        """
+        return self._pool
+
+    def next_region(self) -> None:
+        """
+        Cycle to the next region prefix in the pool.
+        Call this when a request fails to try a different region.
+        """
+        self._pool.next_region()
+        self._update_base_url()
+
+    def select_best_domain(self) -> None:
+        """
+        Select the best domain using DNS resolution.
+        This is automatically called periodically, but you can call it manually.
+        """
+        self._pool.select_best_domain()
+        self._update_base_url()
+
+    def get_current_url(self) -> str:
+        """
+        Get the current URL being used for requests.
+        """
+        return self._pool.get_current_url()
+
+    def _update_base_url(self) -> None:
+        """
+        Update the base URL in the client wrapper to match the pool's current URL.
+        """
+        self._client_wrapper._base_url = self._pool.get_current_url()
+
+    @property
+    def agents(self):
+        if self._agents is None:
+            from .agents.client import AgentsClient  # noqa: E402
+
+            self._agents = AgentsClient(client_wrapper=self._client_wrapper)
+        return self._agents
+
+    @property
+    def telephony(self):
+        if self._telephony is None:
+            from .telephony.client import TelephonyClient  # noqa: E402
+
+            self._telephony = TelephonyClient(client_wrapper=self._client_wrapper)
+        return self._telephony
+
+    @property
+    def phone_numbers(self):
+        if self._phone_numbers is None:
+            from .phone_numbers.client import PhoneNumbersClient  # noqa: E402
+
+            self._phone_numbers = PhoneNumbersClient(client_wrapper=self._client_wrapper)
+        return self._phone_numbers
+
+
+class AsyncAgoraPool:
+    """
+    AsyncAgoraPool is a wrapper around AsyncAgora that uses a domain pool
+    for regional URL cycling and automatic domain selection.
+
+    This client automatically:
+    - Selects the best domain based on DNS resolution
+    - Cycles through region prefixes on request failures
+    - Supports US, EU, AP, and CN areas
+
+    Parameters
+    ----------
+    area : Area
+        The area to use for regional URL selection.
+
+    username : typing.Union[str, typing.Callable[[], str]]
+    password : typing.Union[str, typing.Callable[[], str]]
+    headers : typing.Optional[typing.Dict[str, str]]
+        Additional headers to send with every request.
+
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
+
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
+
+    httpx_client : typing.Optional[httpx.AsyncClient]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
+
+    Examples
+    --------
+    from agoraio import AsyncAgoraPool, Area
+
+    client = AsyncAgoraPool(
+        area=Area.US,
+        username="YOUR_USERNAME",
+        password="YOUR_PASSWORD",
+    )
+    """
+
+    def __init__(
+        self,
+        *,
+        area: Area,
+        username: typing.Union[str, typing.Callable[[], str]],
+        password: typing.Union[str, typing.Callable[[], str]],
+        headers: typing.Optional[typing.Dict[str, str]] = None,
+        timeout: typing.Optional[float] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.AsyncClient] = None,
+    ):
+        self._pool = Pool(area)
+        _defaulted_timeout = (
+            timeout if timeout is not None else 60 if httpx_client is None else httpx_client.timeout.read
+        )
+        self._client_wrapper = AsyncClientWrapper(
+            base_url=self._pool.get_current_url(),
+            username=username,
+            password=password,
+            headers=headers,
+            httpx_client=httpx_client
+            if httpx_client is not None
+            else httpx.AsyncClient(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
+            if follow_redirects is not None
+            else httpx.AsyncClient(timeout=_defaulted_timeout),
+            timeout=_defaulted_timeout,
+        )
+        self._agents: typing.Optional[AsyncAgentsClient] = None
+        self._telephony: typing.Optional[AsyncTelephonyClient] = None
+        self._phone_numbers: typing.Optional[AsyncPhoneNumbersClient] = None
+
+    @property
+    def pool(self) -> Pool:
+        """
+        Get the underlying domain pool for advanced usage.
+        You can use this to manually cycle regions or select the best domain.
+        """
+        return self._pool
+
+    def next_region(self) -> None:
+        """
+        Cycle to the next region prefix in the pool.
+        Call this when a request fails to try a different region.
+        """
+        self._pool.next_region()
+        self._update_base_url()
+
+    async def select_best_domain(self) -> None:
+        """
+        Select the best domain using DNS resolution (async).
+        This is automatically called periodically, but you can call it manually.
+        """
+        await self._pool.select_best_domain_async()
+        self._update_base_url()
+
+    def get_current_url(self) -> str:
+        """
+        Get the current URL being used for requests.
+        """
+        return self._pool.get_current_url()
+
+    def _update_base_url(self) -> None:
+        """
+        Update the base URL in the client wrapper to match the pool's current URL.
+        """
+        self._client_wrapper._base_url = self._pool.get_current_url()
+
+    @property
+    def agents(self):
+        if self._agents is None:
+            from .agents.client import AsyncAgentsClient  # noqa: E402
+
+            self._agents = AsyncAgentsClient(client_wrapper=self._client_wrapper)
+        return self._agents
+
+    @property
+    def telephony(self):
+        if self._telephony is None:
+            from .telephony.client import AsyncTelephonyClient  # noqa: E402
+
+            self._telephony = AsyncTelephonyClient(client_wrapper=self._client_wrapper)
+        return self._telephony
+
+    @property
+    def phone_numbers(self):
+        if self._phone_numbers is None:
+            from .phone_numbers.client import AsyncPhoneNumbersClient  # noqa: E402
+
+            self._phone_numbers = AsyncPhoneNumbersClient(client_wrapper=self._client_wrapper)
+        return self._phone_numbers