getanyapi 0.1.0__tar.gz

getanyapi-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# dependencies
+node_modules/
+.pnpm-store/
+
+# build output
+dist/
+*.tsbuildinfo
+
+# python
+__pycache__/
+*.egg-info/
+.venv/
+venv/
+.mypy_cache/
+.pyright/
+.pytest_cache/
+.ruff_cache/
+build/
+
+# generator outputs: ir.json and fixtures.json ARE committed (byte-determinism is guarded
+# by `pnpm generate:check`; the fixture integration suites read fixtures.json directly).
+# ir.sample.json remains the hand-built 3-SKU reference.
+
+# os / editor
+.DS_Store
+*.log
+.idea/
+.vscode/

getanyapi-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: getanyapi
+Version: 0.1.0
+Summary: Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions.
+Project-URL: Homepage, https://getanyapi.com
+Project-URL: Documentation, https://getanyapi.com/docs
+Project-URL: Repository, https://github.com/getanyapi-com/sdks
+Project-URL: Issues, https://github.com/getanyapi-com/sdks/issues
+Author-email: AnyAPI <support@getanyapi.com>
+License-Expression: MIT
+Keywords: anyapi,api,getanyapi,scraping,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# getanyapi
+
+Official typed Python SDK for [AnyAPI](https://getanyapi.com): any API, one wallet, USD, no
+subscriptions. Reach hundreds of scraping and data APIs through one interface and one key; pay
+per request in real US dollars. httpx + pydantic v2, Python 3.10+, sync and async clients.
+
+```bash
+pip install getanyapi
+```
+
+## Quickstart
+
+```python
+from getanyapi import AnyAPI
+
+client = AnyAPI()  # reads ANYAPI_API_KEY from the environment
+res = client.reddit.search(query="mechanical keyboard")
+for post in res.output.posts:
+    print(post.title, post.score)
+print("charged", res.cost_usd, "USD")
+```
+
+Async:
+
+```python
+from getanyapi import AsyncAnyAPI
+
+async with AsyncAnyAPI() as client:
+    res = await client.google.search(query="best coffee maker")
+```
+
+## Inputs vs outputs (naming asymmetry)
+
+Input keyword arguments mirror the wire API verbatim (camelCase where the API uses it), because
+they are sent as-is. Output models are Pythonic: attributes are snake_case with a wire alias
+(`item.reviews_count` reads the wire `reviewsCount`), and `model_dump(by_alias=True)` reproduces
+the wire shape. Open provider records round-trip unknown fields via `.model_extra`.
+
+## Not found vs error
+
+A successful call always returns. For most SKUs the payload is wrapped in a `found` flag:
+`res.output.found` is `False` when the upstream had no matching entity (not an error). Use
+`unwrap` to get the data or raise `ResultNotFoundError` when empty:
+
+```python
+from getanyapi import unwrap, ResultNotFoundError
+
+res = client.amazon.reviews(product="B07FZ8S74R")
+try:
+    data = unwrap(res)  # the typed data payload, or raises
+except ResultNotFoundError:
+    ...  # empty result (found: False), not an HTTP failure
+```
+
+`ResultNotFoundError` subclasses `NotFoundError`, so `except NotFoundError` catches both an
+HTTP 404 and an empty result; catch `ResultNotFoundError` to handle only empty results. A few
+SKUs (e.g. `reddit.search`) return their data object directly as `output` with no `found`
+wrapper; `unwrap` returns it as-is and never raises for those.
+
+## Pagination
+
+Paginated SKUs expose an `iter_*` method that yields validated item models across pages and
+follows the cursor for you. Call `.pages()` on it to walk whole results (each has its own
+`cost_usd`).
+
+```python
+for post in client.reddit.iter_search(query="coffee", options={"max_items": 100}):
+    print(post.title)  # a validated model, not a dict
+
+for page in client.reddit.iter_search(query="coffee").pages():
+    print(page.cost_usd)
+```
+
+## Request options (context-cost savers)
+
+Pass `options=` to shape the response. These trim what comes back but do NOT change the price:
+
+```python
+res = client.google.search(
+    query="coffee",
+    options={"fields": ["title", "link"], "max_items": 5, "summary": True},
+)
+```
+
+`options` also carries per-call `timeout` and `max_retries` overrides.
+
+## Errors and retries
+
+| Class | HTTP | Meaning |
+| --- | --- | --- |
+| `BadRequestError` | 400 | Input failed validation |
+| `AuthenticationError` | 401 | Missing or invalid API key |
+| `InsufficientBalanceError` | 402 | Wallet balance or per-key cap exceeded |
+| `NotFoundError` | 404 | Slug or resource does not exist |
+| `ResultNotFoundError` | - | `unwrap` on an empty found-data result |
+| `RateLimitedError` | 429 | Too many requests (retried automatically) |
+| `UpstreamError` | 502 | An upstream backend failed |
+| `ConnectionError` | 0 | Network or transport failure (retried) |
+| `TimeoutError` | 0 | Request exceeded its timeout (not retried) |
+
+All extend `AnyAPIError` (with `.status` and `.request_id`). Retries cover only 429 and network
+failures, with jittered exponential backoff honoring `Retry-After`. Default `max_retries` is 2
+(up to 3 attempts); set it on the client (`AnyAPI(max_retries=...)`) or per request via
+`options`. Timeouts are never retried.
+
+## Agent signup
+
+Bootstrap a key with no account (for autonomous agents):
+
+```python
+from getanyapi import agent_signup, AnyAPI
+
+result = agent_signup(label="my-agent")
+client = AnyAPI(api_key=result.secret)
+```
+
+The key ships with a small starter credit and a per-key spend cap; a human funds it by claiming
+it at `result.claim_url`.
+
+## Docs
+
+Full API reference and catalog: [getanyapi.com/docs](https://getanyapi.com/docs).
+
+## License
+
+MIT

getanyapi-0.1.0/README.md

@@ -0,0 +1,126 @@
+# getanyapi
+
+Official typed Python SDK for [AnyAPI](https://getanyapi.com): any API, one wallet, USD, no
+subscriptions. Reach hundreds of scraping and data APIs through one interface and one key; pay
+per request in real US dollars. httpx + pydantic v2, Python 3.10+, sync and async clients.
+
+```bash
+pip install getanyapi
+```
+
+## Quickstart
+
+```python
+from getanyapi import AnyAPI
+
+client = AnyAPI()  # reads ANYAPI_API_KEY from the environment
+res = client.reddit.search(query="mechanical keyboard")
+for post in res.output.posts:
+    print(post.title, post.score)
+print("charged", res.cost_usd, "USD")
+```
+
+Async:
+
+```python
+from getanyapi import AsyncAnyAPI
+
+async with AsyncAnyAPI() as client:
+    res = await client.google.search(query="best coffee maker")
+```
+
+## Inputs vs outputs (naming asymmetry)
+
+Input keyword arguments mirror the wire API verbatim (camelCase where the API uses it), because
+they are sent as-is. Output models are Pythonic: attributes are snake_case with a wire alias
+(`item.reviews_count` reads the wire `reviewsCount`), and `model_dump(by_alias=True)` reproduces
+the wire shape. Open provider records round-trip unknown fields via `.model_extra`.
+
+## Not found vs error
+
+A successful call always returns. For most SKUs the payload is wrapped in a `found` flag:
+`res.output.found` is `False` when the upstream had no matching entity (not an error). Use
+`unwrap` to get the data or raise `ResultNotFoundError` when empty:
+
+```python
+from getanyapi import unwrap, ResultNotFoundError
+
+res = client.amazon.reviews(product="B07FZ8S74R")
+try:
+    data = unwrap(res)  # the typed data payload, or raises
+except ResultNotFoundError:
+    ...  # empty result (found: False), not an HTTP failure
+```
+
+`ResultNotFoundError` subclasses `NotFoundError`, so `except NotFoundError` catches both an
+HTTP 404 and an empty result; catch `ResultNotFoundError` to handle only empty results. A few
+SKUs (e.g. `reddit.search`) return their data object directly as `output` with no `found`
+wrapper; `unwrap` returns it as-is and never raises for those.
+
+## Pagination
+
+Paginated SKUs expose an `iter_*` method that yields validated item models across pages and
+follows the cursor for you. Call `.pages()` on it to walk whole results (each has its own
+`cost_usd`).
+
+```python
+for post in client.reddit.iter_search(query="coffee", options={"max_items": 100}):
+    print(post.title)  # a validated model, not a dict
+
+for page in client.reddit.iter_search(query="coffee").pages():
+    print(page.cost_usd)
+```
+
+## Request options (context-cost savers)
+
+Pass `options=` to shape the response. These trim what comes back but do NOT change the price:
+
+```python
+res = client.google.search(
+    query="coffee",
+    options={"fields": ["title", "link"], "max_items": 5, "summary": True},
+)
+```
+
+`options` also carries per-call `timeout` and `max_retries` overrides.
+
+## Errors and retries
+
+| Class | HTTP | Meaning |
+| --- | --- | --- |
+| `BadRequestError` | 400 | Input failed validation |
+| `AuthenticationError` | 401 | Missing or invalid API key |
+| `InsufficientBalanceError` | 402 | Wallet balance or per-key cap exceeded |
+| `NotFoundError` | 404 | Slug or resource does not exist |
+| `ResultNotFoundError` | - | `unwrap` on an empty found-data result |
+| `RateLimitedError` | 429 | Too many requests (retried automatically) |
+| `UpstreamError` | 502 | An upstream backend failed |
+| `ConnectionError` | 0 | Network or transport failure (retried) |
+| `TimeoutError` | 0 | Request exceeded its timeout (not retried) |
+
+All extend `AnyAPIError` (with `.status` and `.request_id`). Retries cover only 429 and network
+failures, with jittered exponential backoff honoring `Retry-After`. Default `max_retries` is 2
+(up to 3 attempts); set it on the client (`AnyAPI(max_retries=...)`) or per request via
+`options`. Timeouts are never retried.
+
+## Agent signup
+
+Bootstrap a key with no account (for autonomous agents):
+
+```python
+from getanyapi import agent_signup, AnyAPI
+
+result = agent_signup(label="my-agent")
+client = AnyAPI(api_key=result.secret)
+```
+
+The key ships with a small starter credit and a per-key spend cap; a human funds it by claiming
+it at `result.claim_url`.
+
+## Docs
+
+Full API reference and catalog: [getanyapi.com/docs](https://getanyapi.com/docs).
+
+## License
+
+MIT

getanyapi-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getanyapi"
+version = "0.1.0"
+description = "Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "AnyAPI", email = "support@getanyapi.com" }]
+keywords = ["getanyapi", "anyapi", "api", "scraping", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.5",
+  "typing_extensions>=4.7",
+]
+
+[project.urls]
+Homepage = "https://getanyapi.com"
+Documentation = "https://getanyapi.com/docs"
+Repository = "https://github.com/getanyapi-com/sdks"
+Issues = "https://github.com/getanyapi-com/sdks/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pyright>=1.1.380",
+  "mypy>=1.11",
+  "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getanyapi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src/getanyapi"]
+
+[tool.pyright]
+include = ["src/getanyapi"]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

getanyapi-0.1.0/src/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-0.1.0/src/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
+    )