getanyapi 0.1.0__py3-none-any.whl

getanyapi/__init__.py

@@ -0,0 +1,76 @@
+"""getanyapi - official typed Python SDK for AnyAPI.
+
+    from getanyapi import AnyAPI, AsyncAnyAPI, agent_signup, unwrap
+    from getanyapi import AnyAPIError, NotFoundError, RateLimitedError  # etc.
+
+Sync and async clients share generated per-platform namespaces (attached lazily)
+through a single transport seam. Output models are pydantic v2; open provider
+records round-trip unknown fields via ``.model_extra``. See ../../../SPEC.md
+section 3 for the frozen public surface.
+"""
+
+from __future__ import annotations
+
+from ._async_client import AsyncAnyAPI
+from ._client import AnyAPI, agent_signup
+from ._errors import (
+    AnyAPIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    InsufficientBalanceError,
+    NotFoundError,
+    RateLimitedError,
+    ResultNotFoundError,
+    TimeoutError,
+    UpstreamError,
+)
+from ._pagination import AsyncPaginator, Paginator
+from .types import (
+    AccountProfile,
+    AgentSignupResult,
+    Balance,
+    BareRunResult,
+    CatalogEntry,
+    Output,
+    OutputFound,
+    OutputNotFound,
+    RequestOptions,
+    RunResult,
+    unwrap,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    # clients + top-level functions
+    "AnyAPI",
+    "AsyncAnyAPI",
+    "agent_signup",
+    "unwrap",
+    # result + data models
+    "RunResult",
+    "BareRunResult",
+    "Output",
+    "OutputFound",
+    "OutputNotFound",
+    "Balance",
+    "AccountProfile",
+    "CatalogEntry",
+    "RequestOptions",
+    "AgentSignupResult",
+    # pagination
+    "Paginator",
+    "AsyncPaginator",
+    # errors
+    "AnyAPIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "NotFoundError",
+    "ResultNotFoundError",
+    "RateLimitedError",
+    "UpstreamError",
+    "ConnectionError",
+    "TimeoutError",
+]

getanyapi/_account.py

@@ -0,0 +1,132 @@
+"""Account, catalog, and agent-signup request/response mapping (SPEC 2.7, 3.7).
+
+Pure functions that build the HTTP request pieces and map raw JSON bodies into
+the public models. The sync and async clients share these so the wire mapping
+lives in one place. Credits never appear in the public surface: the catalog
+price is converted from internal credits to USD here, before any model is built.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from ._errors import AnyAPIError, error_for_status
+from ._transport import as_dict, error_message
+from .types import AccountProfile, AgentSignupResult, Balance, CatalogEntry
+
+__all__ = [
+    "balance_path",
+    "me_path",
+    "catalog_request",
+    "describe_path",
+    "signup_request",
+    "parse_balance",
+    "parse_me",
+    "parse_catalog",
+    "parse_describe",
+    "parse_signup",
+    "map_error",
+]
+
+_CREDIT_USD = 0.00001  # 1 credit = $0.00001 USD (internal unit, never surfaced)
+
+balance_path = "/v1/balance"
+me_path = "/v1/me"
+
+
+def catalog_request(
+    query: str | None, category: str | None
+) -> tuple[str, dict[str, str]]:
+    """Path and query params for ``catalog()`` (GET /v1/apis)."""
+    params: dict[str, str] = {}
+    if query is not None:
+        params["query"] = query
+    if category is not None:
+        params["category"] = category
+    return "/v1/apis", params
+
+
+def describe_path(slug: str) -> str:
+    return f"/v1/apis/{slug}"
+
+
+def signup_request(
+    sponsor_email: str | None, label: str | None
+) -> dict[str, Any]:
+    """JSON body for ``agent_signup()`` (POST /agent/signup, no auth)."""
+    body: dict[str, Any] = {}
+    if sponsor_email is not None:
+        body["sponsorEmail"] = sponsor_email
+    if label is not None:
+        body["label"] = label
+    return body
+
+
+def _split_slug(slug: str) -> tuple[str, str]:
+    """Derive (platform, action) from a dotted slug; action "" if no dot."""
+    platform, _, action = slug.partition(".")
+    return platform, action
+
+
+def parse_balance(body: Any) -> Balance:
+    return Balance.model_validate(body)
+
+
+def parse_me(body: Any) -> AccountProfile:
+    """Map /v1/me, dropping clerkUserId and signupGrantApplied (SPEC 2.7)."""
+    return AccountProfile.model_validate(body)
+
+
+def _str_field(raw: dict[str, object], key: str) -> str:
+    value = raw.get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _from_credits(raw: dict[str, object]) -> float:
+    value = raw.get("fromCredits")
+    if isinstance(value, (int, float)):
+        return float(value)
+    return 0.0
+
+
+def _to_catalog_entry(raw: dict[str, object]) -> CatalogEntry:
+    slug = _str_field(raw, "slug")
+    platform, action = _split_slug(slug)
+    return CatalogEntry.model_validate(
+        {
+            "slug": slug,
+            "platform": platform,
+            "action": action,
+            "name": _str_field(raw, "name"),
+            "category": _str_field(raw, "category"),
+            "description": _str_field(raw, "description"),
+            "priceUsd": _from_credits(raw) * _CREDIT_USD,
+        }
+    )
+
+
+def parse_catalog(body: object) -> list[CatalogEntry]:
+    """Map {apis:[...]} into CatalogEntry[] (SPEC 2.7)."""
+    raw = as_dict(body).get("apis")
+    if not isinstance(raw, list):
+        return []
+    apis: list[object] = list(cast("list[object]", raw))
+    return [_to_catalog_entry(as_dict(item)) for item in apis]
+
+
+def parse_describe(body: object) -> CatalogEntry:
+    """Map a single /v1/apis/{slug} entry into one CatalogEntry."""
+    return _to_catalog_entry(as_dict(body))
+
+
+def parse_signup(body: Any) -> AgentSignupResult:
+    return AgentSignupResult.model_validate(body)
+
+
+def map_error(
+    status: int, body: object, request_id: str | None
+) -> AnyAPIError:
+    """Map a non-2xx account/catalog response to the frozen error hierarchy."""
+    return error_for_status(
+        status, error_message(body, status), request_id=request_id
+    )

getanyapi/_async_client.py

@@ -0,0 +1,215 @@
+"""Async AsyncAnyAPI client (SPEC 3.1).
+
+Mirrors :class:`getanyapi.AnyAPI` with ``async def`` methods, ``aclose``, and an
+async context manager. Generated async namespaces attach lazily via
+``__getattr__`` using the same ``getanyapi.platforms.REGISTRY`` table as the sync
+client (see ``_client`` module docstring for the full contract); the async
+client instantiates the registry's async class.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import os
+from typing import Any
+
+import httpx
+
+from . import _account
+from . import _transport
+from ._client import lookup_namespace
+from ._errors import AnyAPIError, ConnectionError, TimeoutError
+from ._transport import (
+    RetryState,
+    build_request,
+    is_retryable_error,
+    parse_raw,
+)
+from .types import (
+    AccountProfile,
+    Balance,
+    CatalogEntry,
+    RequestOptions,
+    RunResult,
+)
+
+__all__ = ["AsyncAnyAPI"]
+
+_DEFAULT_BASE_URL = "https://api.getanyapi.com"
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    key = api_key if api_key is not None else os.environ.get("ANYAPI_API_KEY")
+    if not key:
+        raise AnyAPIError(
+            "no API key: pass api_key= or set ANYAPI_API_KEY", status=0
+        )
+    return key
+
+
+class AsyncAnyAPI:
+    """Asynchronous AnyAPI client (SPEC 3.1)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._namespaces: dict[str, Any] = {}
+
+    # -- generated namespace attachment -----------------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        cache = self.__dict__.get("_namespaces")
+        if cache is not None and name in cache:
+            return cache[name]
+        entry = lookup_namespace(name)
+        if entry is None:
+            raise AttributeError(name)
+        module_suffix, _sync_class, async_class = entry
+        module = importlib.import_module(f"getanyapi.platforms.{module_suffix}")
+        namespace = getattr(module, async_class)(self)
+        if cache is not None:
+            cache[name] = namespace
+        return namespace
+
+    # -- transport seam ---------------------------------------------------
+
+    async def _arun_raw(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Execute one SKU run with retries, returning the raw JSON dict.
+
+        The raw seam generated methods call (SPEC N2): the generated code
+        validates this dict into its concrete ``RunResult[XData]`` /
+        ``BareRunResult[XData]`` model, so there is no double-parse.
+        """
+        timeout = self._timeout
+        max_retries = self._max_retries
+        if options:
+            opt_timeout = options.get("timeout")
+            if opt_timeout is not None:
+                timeout = float(opt_timeout)
+            opt_retries = options.get("max_retries")
+            if opt_retries is not None:
+                max_retries = int(opt_retries)
+        request = build_request(
+            base_url=self._base_url,
+            slug=slug,
+            input=input,
+            api_key=self._api_key,
+            options=options,
+            timeout=timeout,
+        )
+        retry = RetryState(max_retries)
+        while True:
+            response: httpx.Response | None = None
+            try:
+                response = await self._http.send(request)
+                return parse_raw(response)
+            except AnyAPIError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    await asyncio.sleep(retry.next_delay(response))
+                    continue
+                raise
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(
+                    str(exc) or "request timed out", status=0
+                ) from exc
+            except httpx.HTTPError as exc:
+                if retry.can_retry:
+                    await asyncio.sleep(retry.next_delay(None))
+                    continue
+                raise ConnectionError(
+                    str(exc) or "connection failed", status=0
+                ) from exc
+
+    async def _arun(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        options: RequestOptions | None = None,
+    ) -> RunResult[Any]:
+        """Execute one SKU run and parse the generic found-data envelope."""
+        raw = await self._arun_raw(slug, input, options)
+        return _transport.validate_run_result(raw)
+
+    async def run(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        *,
+        options: RequestOptions | None = None,
+    ) -> RunResult[Any]:
+        """Generic typed run for any SKU by slug (SPEC 3.1)."""
+        return await self._arun(slug, input, options)
+
+    # -- account + catalog ------------------------------------------------
+
+    async def _get(
+        self, path: str, params: dict[str, str] | None = None
+    ) -> object:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+        }
+        response = await self._http.get(
+            url, params=params or {}, headers=headers
+        )
+        return self._json_or_raise(response)
+
+    def _json_or_raise(self, response: httpx.Response) -> object:
+        request_id = response.headers.get("x-request-id")
+        body: object = None
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if response.status_code != 200:
+            raise _account.map_error(response.status_code, body, request_id)
+        return body
+
+    async def balance(self) -> Balance:
+        return _account.parse_balance(await self._get(_account.balance_path))
+
+    async def me(self) -> AccountProfile:
+        return _account.parse_me(await self._get(_account.me_path))
+
+    async def catalog(
+        self, *, query: str | None = None, category: str | None = None
+    ) -> list[CatalogEntry]:
+        path, params = _account.catalog_request(query, category)
+        return _account.parse_catalog(await self._get(path, params))
+
+    async def describe(self, slug: str) -> CatalogEntry:
+        body = await self._get(_account.describe_path(slug))
+        return _account.parse_describe(body)
+
+    # -- lifecycle --------------------------------------------------------
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAnyAPI:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

getanyapi/_client.py

@@ -0,0 +1,274 @@
+"""Sync AnyAPI client (SPEC 3.1) and the module-level agent_signup helper.
+
+Generated per-platform namespaces attach lazily. On first access,
+``__getattr__(name)`` looks the name up in the generated registry
+``getanyapi.platforms.REGISTRY`` and imports the platform module, instantiating its
+sync ``Namespace`` class bound to this client.
+
+Namespace-attachment contract (target for the py-emitter):
+    ``getanyapi.platforms.__init__`` exposes a module-level dict named ``REGISTRY``
+    mapping the client attribute name (the snake_case platform, e.g. "amazon")
+    to a 3-tuple ``(module_suffix, sync_class_name, async_class_name)``:
+
+        REGISTRY: dict[str, tuple[str, str, str]] = {
+            "amazon": ("amazon", "AmazonNamespace", "AsyncAmazonNamespace"),
+            ...
+        }
+
+    Each generated module ``getanyapi.platforms.<module_suffix>`` defines both the
+    sync class ``<sync_class_name>`` and the async class ``<async_class_name>``.
+    Each namespace class has ``__init__(self, client)`` storing the client, and
+    per-SKU methods that call ``client._run(slug, input, options)`` (sync) or
+    ``client._arun(...)`` (async), plus ``iter_*`` methods returning a
+    ``Paginator``/``AsyncPaginator`` via ``getanyapi._pagination.paginate`` /
+    ``apaginate``. The sync client instantiates the sync class; the async client
+    instantiates the async class. Both look the attribute up by the SAME key in
+    the SAME registry, so one generated table drives both clients.
+
+    Namespace instances are cached on the client instance after first access.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any
+
+import httpx
+
+from . import _account, _transport
+from ._errors import AnyAPIError, ConnectionError, TimeoutError
+from ._transport import (
+    RetryState,
+    build_request,
+    is_retryable_error,
+    parse_raw,
+)
+from .types import (
+    AccountProfile,
+    AgentSignupResult,
+    Balance,
+    CatalogEntry,
+    RequestOptions,
+    RunResult,
+)
+
+__all__ = ["AnyAPI", "agent_signup"]
+
+_DEFAULT_BASE_URL = "https://api.getanyapi.com"
+
+
+def lookup_namespace(name: str) -> tuple[str, str, str] | None:
+    """Look ``name`` up in the generated platform registry (typed accessor)."""
+    try:
+        module = importlib.import_module("getanyapi.platforms")
+    except ImportError:
+        return None
+    registry: dict[str, tuple[str, str, str]] = getattr(module, "REGISTRY", {})
+    return registry.get(name)
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    key = api_key if api_key is not None else os.environ.get("ANYAPI_API_KEY")
+    if not key:
+        raise AnyAPIError(
+            "no API key: pass api_key= or set ANYAPI_API_KEY", status=0
+        )
+    return key
+
+
+class AnyAPI:
+    """Synchronous AnyAPI client (SPEC 3.1).
+
+    Generated per-platform namespaces (``client.amazon``, ``client.facebook``,
+    ...) attach lazily via ``__getattr__``; see the module docstring for the
+    registry contract the emitter targets.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._namespaces: dict[str, Any] = {}
+
+    # -- generated namespace attachment -----------------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        # Only called for attributes not found normally.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        cache = self.__dict__.get("_namespaces")
+        if cache is not None and name in cache:
+            return cache[name]
+        entry = lookup_namespace(name)
+        if entry is None:
+            raise AttributeError(name)
+        module_suffix, sync_class, _async_class = entry
+        module = importlib.import_module(f"getanyapi.platforms.{module_suffix}")
+        namespace = getattr(module, sync_class)(self)
+        if cache is not None:
+            cache[name] = namespace
+        return namespace
+
+    # -- transport seam ---------------------------------------------------
+
+    def _run_raw(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Execute one SKU run with retries, returning the raw JSON dict.
+
+        The raw seam generated methods call (SPEC N2): the generated code
+        validates this dict into its concrete ``RunResult[XData]`` /
+        ``BareRunResult[XData]`` model, so there is no double-parse.
+        """
+        timeout = self._timeout
+        max_retries = self._max_retries
+        if options:
+            opt_timeout = options.get("timeout")
+            if opt_timeout is not None:
+                timeout = float(opt_timeout)
+            opt_retries = options.get("max_retries")
+            if opt_retries is not None:
+                max_retries = int(opt_retries)
+        request = build_request(
+            base_url=self._base_url,
+            slug=slug,
+            input=input,
+            api_key=self._api_key,
+            options=options,
+            timeout=timeout,
+        )
+        retry = RetryState(max_retries)
+        while True:
+            response: httpx.Response | None = None
+            try:
+                response = self._http.send(request)
+                return parse_raw(response)
+            except AnyAPIError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    _transport.sleep(retry.next_delay(response))
+                    continue
+                raise
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(
+                    str(exc) or "request timed out", status=0
+                ) from exc
+            except httpx.HTTPError as exc:
+                if retry.can_retry:
+                    _transport.sleep(retry.next_delay(None))
+                    continue
+                raise ConnectionError(
+                    str(exc) or "connection failed", status=0
+                ) from exc
+
+    def _run(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        options: RequestOptions | None = None,
+    ) -> RunResult[Any]:
+        """Execute one SKU run and parse the generic found-data envelope."""
+        raw = self._run_raw(slug, input, options)
+        return _transport.validate_run_result(raw)
+
+    def run(
+        self,
+        slug: str,
+        input: dict[str, Any],
+        *,
+        options: RequestOptions | None = None,
+    ) -> RunResult[Any]:
+        """Generic typed run for any SKU by slug (SPEC 3.1)."""
+        return self._run(slug, input, options)
+
+    # -- account + catalog ------------------------------------------------
+
+    def _get(self, path: str, params: dict[str, str] | None = None) -> object:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+        }
+        response = self._http.get(url, params=params or {}, headers=headers)
+        return self._json_or_raise(response)
+
+    def _json_or_raise(self, response: httpx.Response) -> object:
+        request_id = response.headers.get("x-request-id")
+        body: object = None
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if response.status_code != 200:
+            raise _account.map_error(response.status_code, body, request_id)
+        return body
+
+    def balance(self) -> Balance:
+        return _account.parse_balance(self._get(_account.balance_path))
+
+    def me(self) -> AccountProfile:
+        return _account.parse_me(self._get(_account.me_path))
+
+    def catalog(
+        self, *, query: str | None = None, category: str | None = None
+    ) -> list[CatalogEntry]:
+        path, params = _account.catalog_request(query, category)
+        return _account.parse_catalog(self._get(path, params))
+
+    def describe(self, slug: str) -> CatalogEntry:
+        return _account.parse_describe(self._get(_account.describe_path(slug)))
+
+    # -- lifecycle --------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> AnyAPI:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def agent_signup(
+    *,
+    base_url: str = _DEFAULT_BASE_URL,
+    sponsor_email: str | None = None,
+    label: str | None = None,
+) -> AgentSignupResult:
+    """Self-signup for an API key with no auth (SPEC 3.1, POST /agent/signup)."""
+    body = _account.signup_request(sponsor_email, label)
+    with httpx.Client(timeout=60.0) as http:
+        response = http.post(
+            f"{base_url.rstrip('/')}/agent/signup",
+            json=body,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+    request_id = response.headers.get("x-request-id")
+    parsed: object = None
+    try:
+        parsed = response.json()
+    except ValueError:
+        parsed = None
+    # The gateway returns 200 for agent signup; accept 200 only (SPEC S7).
+    if response.status_code != 200:
+        raise _account.map_error(response.status_code, parsed, request_id)
+    return _account.parse_signup(parsed)