okdata 0.1.0__tar.gz

okdata-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+src/okdata/_generated/
+dist/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/

okdata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 okdata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

okdata-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: okdata
+Version: 0.1.0
+Summary: Python SDK for okdata: social data from Douyin, Xiaohongshu, WeChat, Bilibili, Weibo, TikTok, X, YouTube and more, for AI agents, paid per call. Typed methods per endpoint, sync and async, safe retries, paging with a spend limit.
+Project-URL: Homepage, https://okdata.online/
+Project-URL: Documentation, https://okdata.online/docs/sdk/
+Project-URL: Endpoints, https://okdata.online/apis/
+Project-URL: Pricing, https://okdata.online/pricing/
+Project-URL: Source, https://github.com/okdataapi/okdata/tree/main/python
+Project-URL: Issues, https://github.com/okdataapi/okdata/issues
+Author-email: okdata <hello@okdata.online>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai agents,bilibili,douyin,instagram,mcp,okdata,reddit,rednote,sdk,social data,social media api,tiktok,twitter,wechat,weibo,x,xiaohongshu,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# okdata for Python
+
+Social data for AI agents, paid per call: Douyin, Xiaohongshu, WeChat, Bilibili, Weibo, Kuaishou, Zhihu,
+TikTok, X, YouTube, Instagram, Reddit and more, as one API with one envelope and one error format.
+Every endpoint is a typed method generated from the okdata catalog, with its price in its docstring.
+
+```sh
+pip install okdata          # Python 3.9+, one dependency (httpx)
+export OKDATA_API_KEY=okd_...
+```
+
+No key yet? Sign up at [okdata.online](https://okdata.online/signup/?src=pypi-okdata)
+(中文：[注册](https://okdata.online/zh/signup/?src=pypi-okdata)).
+
+## First call
+
+The Playground's Python tab shows the raw HTTP request; with the SDK the same call is:
+
+```python
+from okdata import OkData
+
+ok = OkData()  # reads OKDATA_API_KEY; OkData("okd_...") works too
+page = ok.douyin.videos.search(query="露营装备", sort="latest", max_price="0.05")
+for row in page.items:
+    print(row["id"], row["metrics"]["likes"], row["text"][:60])
+print("cost: $" + page.cost)
+```
+
+Parameters are flat and named as in the API (`query`, `id`, `url`, `cursor`, ...). Every method also
+takes `view` (`compact` | `standard` | `full`, same price), `fields` (`["id", "text"]` or `"id,text"`),
+`max_price` (sent as `X-Max-Price`: a call that could cost more is refused before it runs, never
+charged), `idempotency_key` and `timeout`. Any endpoint also works by id:
+`ok.call("weibo.trends.list")`, including ids newer than your SDK version.
+
+What comes back: `Page` (list endpoints: `items`, `next_cursor`, `has_more`), `Item` (one object:
+`item`) or `Batch` (`ids=[...]` on endpoints that take a list: `items`, `missing`). Each has `cost`,
+`balance_after`, `request_id`, `result_status`, `replayed`, `warnings`, `meta` and the `raw` envelope.
+Items are plain dicts, typed as `TypedDict`s (`Post`, `Account`, `Comment`, ...).
+
+## Paging within a budget
+
+```python
+for page in ok.pages("douyin.videos.comments.list", id="7301234567890123456", max_pages=5, max_spend="0.01"):
+    ...
+
+items = ok.items("x.posts.search", query="claude code", max_items=200, max_spend="0.05")
+rows = list(items)
+print(items.spent, items.stop_reason)   # "0.03", "max_items" | "max_spend" | "end" | "balance" | "max_pages"
+```
+
+Each page is a separate, separately charged call. Before each page the pager adds what that page could
+cost at most (the endpoint's `max_charge`) and stops if the total would pass `max_spend`; each call also
+carries `X-Max-Price` set to what is left, so the server refuses (free) anything dearer.
+
+## Retries and idempotency
+
+Every paid call gets an `Idempotency-Key`, reused by its retries, so a retry is never charged twice.
+Retries follow the error body: `retry` `yes` / `same_key` are retried (after `retry_after_seconds` when
+given; a wait longer than `max_retry_delay` raises instead), `once` gets one more try, `no` and
+`after_fix` are never retried. Defaults: `max_retries=2`, `timeout=65` seconds per attempt.
+
+## Errors
+
+```python
+from okdata import OkDataError
+
+try:
+    ok.x.posts.get(id="1850000000000000000")
+except OkDataError as err:
+    err.code, err.charged, err.retry, err.request_id   # branch on code, never on message
+    err.message, err.message_zh, err.problems, err.param, err.reason, err.retry_after_seconds
+```
+
+`charged` is `False` for almost every error, `True` for a `not_found` the endpoint charges (`amount`
+says how much) and `None` when it is not known yet (a lost answer, `settlement_unknown`): look it up
+with `ok.calls.get(err.request_id)` or `ok.calls.by_key(err.idempotency_key)`. A lost connection raises
+`OkDataConnectionError` (`connection_error` or `client_timeout`, `charged=None`). The codes are in
+`okdata.ERROR_CODES` and at https://okdata.online/docs/errors/.
+
+## Async
+
+```python
+import asyncio
+from okdata import AsyncOkData
+
+async def main():
+    async with AsyncOkData() as ok:
+        page = await ok.weibo.trends.list()
+        async for row in ok.items("douyin.videos.search", query="露营装备", max_spend="0.1"):
+            print(row["id"])
+
+asyncio.run(main())
+```
+
+## Free routes
+
+`ok.catalog()`, `ok.status()` (no key needed), `ok.account()` (balance, key limits, rate tier),
+`ok.usage(group_by=["day", "capability"])`, `ok.calls.get(request_id)`, `ok.calls.result(request_id,
+view="full")` (a result kept 24 h, read again for free) and `ok.calls.by_key(idempotency_key)`.
+
+## Options
+
+`OkData(api_key=None, *, base_url=None, timeout=65.0, max_retries=2, retry_base_delay=0.5,
+max_retry_delay=20.0, source=None, end_user=None, user_agent=None, http_client=None)`. `base_url`
+defaults to `OKDATA_BASE_URL`, then `https://api.okdata.online`. `source` and `end_user` are sent as
+`X-Source` and `X-End-User` for your usage figures; every call carries `X-Entry: sdk`.
+
+MIT licensed.

okdata-0.1.0/README.md

@@ -0,0 +1,108 @@
+# okdata for Python
+
+Social data for AI agents, paid per call: Douyin, Xiaohongshu, WeChat, Bilibili, Weibo, Kuaishou, Zhihu,
+TikTok, X, YouTube, Instagram, Reddit and more, as one API with one envelope and one error format.
+Every endpoint is a typed method generated from the okdata catalog, with its price in its docstring.
+
+```sh
+pip install okdata          # Python 3.9+, one dependency (httpx)
+export OKDATA_API_KEY=okd_...
+```
+
+No key yet? Sign up at [okdata.online](https://okdata.online/signup/?src=pypi-okdata)
+(中文：[注册](https://okdata.online/zh/signup/?src=pypi-okdata)).
+
+## First call
+
+The Playground's Python tab shows the raw HTTP request; with the SDK the same call is:
+
+```python
+from okdata import OkData
+
+ok = OkData()  # reads OKDATA_API_KEY; OkData("okd_...") works too
+page = ok.douyin.videos.search(query="露营装备", sort="latest", max_price="0.05")
+for row in page.items:
+    print(row["id"], row["metrics"]["likes"], row["text"][:60])
+print("cost: $" + page.cost)
+```
+
+Parameters are flat and named as in the API (`query`, `id`, `url`, `cursor`, ...). Every method also
+takes `view` (`compact` | `standard` | `full`, same price), `fields` (`["id", "text"]` or `"id,text"`),
+`max_price` (sent as `X-Max-Price`: a call that could cost more is refused before it runs, never
+charged), `idempotency_key` and `timeout`. Any endpoint also works by id:
+`ok.call("weibo.trends.list")`, including ids newer than your SDK version.
+
+What comes back: `Page` (list endpoints: `items`, `next_cursor`, `has_more`), `Item` (one object:
+`item`) or `Batch` (`ids=[...]` on endpoints that take a list: `items`, `missing`). Each has `cost`,
+`balance_after`, `request_id`, `result_status`, `replayed`, `warnings`, `meta` and the `raw` envelope.
+Items are plain dicts, typed as `TypedDict`s (`Post`, `Account`, `Comment`, ...).
+
+## Paging within a budget
+
+```python
+for page in ok.pages("douyin.videos.comments.list", id="7301234567890123456", max_pages=5, max_spend="0.01"):
+    ...
+
+items = ok.items("x.posts.search", query="claude code", max_items=200, max_spend="0.05")
+rows = list(items)
+print(items.spent, items.stop_reason)   # "0.03", "max_items" | "max_spend" | "end" | "balance" | "max_pages"
+```
+
+Each page is a separate, separately charged call. Before each page the pager adds what that page could
+cost at most (the endpoint's `max_charge`) and stops if the total would pass `max_spend`; each call also
+carries `X-Max-Price` set to what is left, so the server refuses (free) anything dearer.
+
+## Retries and idempotency
+
+Every paid call gets an `Idempotency-Key`, reused by its retries, so a retry is never charged twice.
+Retries follow the error body: `retry` `yes` / `same_key` are retried (after `retry_after_seconds` when
+given; a wait longer than `max_retry_delay` raises instead), `once` gets one more try, `no` and
+`after_fix` are never retried. Defaults: `max_retries=2`, `timeout=65` seconds per attempt.
+
+## Errors
+
+```python
+from okdata import OkDataError
+
+try:
+    ok.x.posts.get(id="1850000000000000000")
+except OkDataError as err:
+    err.code, err.charged, err.retry, err.request_id   # branch on code, never on message
+    err.message, err.message_zh, err.problems, err.param, err.reason, err.retry_after_seconds
+```
+
+`charged` is `False` for almost every error, `True` for a `not_found` the endpoint charges (`amount`
+says how much) and `None` when it is not known yet (a lost answer, `settlement_unknown`): look it up
+with `ok.calls.get(err.request_id)` or `ok.calls.by_key(err.idempotency_key)`. A lost connection raises
+`OkDataConnectionError` (`connection_error` or `client_timeout`, `charged=None`). The codes are in
+`okdata.ERROR_CODES` and at https://okdata.online/docs/errors/.
+
+## Async
+
+```python
+import asyncio
+from okdata import AsyncOkData
+
+async def main():
+    async with AsyncOkData() as ok:
+        page = await ok.weibo.trends.list()
+        async for row in ok.items("douyin.videos.search", query="露营装备", max_spend="0.1"):
+            print(row["id"])
+
+asyncio.run(main())
+```
+
+## Free routes
+
+`ok.catalog()`, `ok.status()` (no key needed), `ok.account()` (balance, key limits, rate tier),
+`ok.usage(group_by=["day", "capability"])`, `ok.calls.get(request_id)`, `ok.calls.result(request_id,
+view="full")` (a result kept 24 h, read again for free) and `ok.calls.by_key(idempotency_key)`.
+
+## Options
+
+`OkData(api_key=None, *, base_url=None, timeout=65.0, max_retries=2, retry_base_delay=0.5,
+max_retry_delay=20.0, source=None, end_user=None, user_agent=None, http_client=None)`. `base_url`
+defaults to `OKDATA_BASE_URL`, then `https://api.okdata.online`. `source` and `end_user` are sent as
+`X-Source` and `X-End-User` for your usage figures; every call carries `X-Entry: sdk`.
+
+MIT licensed.

okdata-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "okdata"
+dynamic = ["version"]
+description = "Python SDK for okdata: social data from Douyin, Xiaohongshu, WeChat, Bilibili, Weibo, TikTok, X, YouTube and more, for AI agents, paid per call. Typed methods per endpoint, sync and async, safe retries, paging with a spend limit."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "okdata", email = "hello@okdata.online" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25,<1"]
+keywords = [
+  "okdata", "sdk", "social media api", "social data", "ai agents", "mcp", "douyin", "xiaohongshu", "rednote",
+  "wechat", "bilibili", "weibo", "tiktok", "twitter", "x", "youtube", "instagram", "reddit",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://okdata.online/"
+Documentation = "https://okdata.online/docs/sdk/"
+Endpoints = "https://okdata.online/apis/"
+Pricing = "https://okdata.online/pricing/"
+Source = "https://github.com/okdataapi/okdata/tree/main/python"
+Issues = "https://github.com/okdataapi/okdata/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+dev = ["pytest>=7", "mypy>=1.8"]
+
+[tool.hatch.version]
+path = "src/okdata/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/okdata"]
+# src/okdata/_generated is generated from the okdata catalog (git-ignored in the monorepo, committed in
+# the public repo); ship it either way.
+artifacts = ["src/okdata/_generated/*.py"]
+
+[tool.hatch.build.targets.sdist]
+# Anchored ("/tests", not "tests"), so a virtualenv or any other folder in here never ships.
+include = ["/src/okdata", "/tests", "/README.md", "/LICENSE"]
+artifacts = ["src/okdata/_generated/*.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+# Runs on the interpreter at hand (mypy no longer targets 3.9); 3.9 itself is covered by running the tests on it.
+strict = true
+files = ["src/okdata", "tests/typing_check.py"]

okdata-0.1.0/src/okdata/__init__.py

@@ -0,0 +1,28 @@
+"""okdata: social data for AI agents, paid per call.
+
+    >>> from okdata import OkData
+    >>> ok = OkData()  # reads OKDATA_API_KEY
+    >>> page = ok.douyin.videos.search(query="露营装备", max_price="0.05")
+
+One typed method per endpoint (generated from the catalog), sync (OkData) and async (AsyncOkData),
+an automatic Idempotency-Key per call, retries driven by the error's ``retry`` field, and
+``pages()`` / ``items()`` that stop before ``max_spend``.
+"""
+from ._async_client import AsyncOkData
+from ._base import DEFAULT_BASE_URL, ENV_API_KEY, ENV_BASE_URL, endpoint
+from ._client import OkData
+from ._errors import OkDataConnectionError, OkDataError, RetryAdvice
+from ._generated._endpoints import CATALOG_REVISION, ENDPOINTS, PRICE_BOOK
+from ._generated._errors import ERROR_CODES, ERRORS
+from ._generated._models import *  # noqa: F401,F403  (Post, Account, Comment, ...)
+from ._paging import AsyncItemPager, AsyncPager, ItemPager, Pager, StopReason
+from ._types import Batch, Billing, CallWarning, EndpointInfo, Fields, Item, Meta, Missing, Page, Price, Result, View
+from ._version import __version__
+
+__all__ = [
+    "OkData", "AsyncOkData", "OkDataError", "OkDataConnectionError", "RetryAdvice",
+    "Page", "Item", "Batch", "Result", "Meta", "Billing", "CallWarning", "Missing", "EndpointInfo",
+    "View", "Fields", "Price", "Pager", "ItemPager", "AsyncPager", "AsyncItemPager", "StopReason",
+    "ENDPOINTS", "CATALOG_REVISION", "PRICE_BOOK", "ERROR_CODES", "ERRORS", "endpoint",
+    "DEFAULT_BASE_URL", "ENV_API_KEY", "ENV_BASE_URL", "__version__",
+]

okdata-0.1.0/src/okdata/_async_client.py

@@ -0,0 +1,119 @@
+"""AsyncOkData: the asyncio client, the same surface as OkData with ``await``."""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional, Sequence, Union
+
+import httpx
+
+from ._base import (
+    call_request, check_request_id, endpoint, make_config, merge_params, result_query, usage_query,
+)
+from ._generated._async import AsyncEndpoints
+from ._paging import AsyncItemPager, AsyncPager, _Budget
+from ._result import to_result
+from ._transport import Send, send_async
+from ._types import Price, Result, View
+
+
+class _AsyncCalls:
+    def __init__(self, ok: "AsyncOkData") -> None:
+        self._ok = ok
+
+    async def get(self, request_id: str) -> Dict[str, Any]:
+        return await self._ok.request("GET", f"/v1/calls/{check_request_id(request_id)}")
+
+    async def result(self, request_id: str, *, view: Optional[View] = None, fields: Optional[Union[str, Sequence[str]]] = None) -> Result:
+        body = await send_async(self._ok._cfg, self._ok._http, self._ok._sleep,
+                                Send("GET", f"/v1/calls/{check_request_id(request_id)}/result", result_query(view, fields)))
+        return to_result(body, None)
+
+    async def by_key(self, idempotency_key: str) -> Dict[str, Any]:
+        return await self._ok.request("GET", "/v1/calls", query=[("idempotency_key", idempotency_key)])
+
+
+class AsyncOkData(AsyncEndpoints):
+    """Async client for the okdata API.
+
+    >>> async with AsyncOkData() as ok:
+    ...     page = await ok.douyin.videos.search(query="露营装备")
+    ...     async for item in ok.items("douyin.videos.search", query="露营装备", max_spend="0.1"):
+    ...         ...
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 65.0,
+        max_retries: int = 2,
+        retry_base_delay: float = 0.5,
+        max_retry_delay: float = 20.0,
+        entry: str = "sdk",
+        source: Optional[str] = None,
+        end_user: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        sleep: Optional[Callable[[float], Awaitable[None]]] = None,
+    ) -> None:
+        self._cfg = make_config(api_key, base_url, timeout, max_retries, retry_base_delay, max_retry_delay, entry, source, end_user, user_agent)
+        self.base_url = self._cfg.base_url
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient()
+        self._sleep: Callable[[float], Awaitable[None]] = sleep or asyncio.sleep
+        self.calls = _AsyncCalls(self)
+        self._init_endpoints(self)
+
+    @property
+    def has_key(self) -> bool:
+        return self._cfg.api_key is not None
+
+    def __repr__(self) -> str:
+        return f"AsyncOkData(base_url={self.base_url!r}, key={'set' if self.has_key else 'missing'})"
+
+    async def __aenter__(self) -> "AsyncOkData":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _call(self, endpoint_id: str, params: Mapping[str, Any], *, idempotency_key: Optional[str] = None, timeout: Optional[float] = None) -> Result:
+        req = call_request(endpoint_id, params, idempotency_key, timeout)
+        return to_result(await send_async(self._cfg, self._http, self._sleep, req), req.idempotency_key)
+
+    async def call(self, endpoint_id: str, params: Optional[Mapping[str, Any]] = None, *, idempotency_key: Optional[str] = None,
+                   timeout: Optional[float] = None, **kwargs: Any) -> Result:
+        return await self._call(endpoint_id, merge_params(params, kwargs), idempotency_key=idempotency_key, timeout=timeout)
+
+    def pages(self, endpoint_id: str, params: Optional[Mapping[str, Any]] = None, *, max_pages: Optional[int] = None,
+              max_spend: Optional[Price] = None, timeout: Optional[float] = None, **kwargs: Any) -> AsyncPager[Dict[str, Any]]:
+        """``async for page in ok.pages(...)``: see OkData.pages."""
+        budget = _Budget(endpoint_id, endpoint(endpoint_id), merge_params(params, kwargs), max_pages, max_spend)
+        return AsyncPager(budget, lambda p: self._call(endpoint_id, p, timeout=timeout))
+
+    def items(self, endpoint_id: str, params: Optional[Mapping[str, Any]] = None, *, max_items: Optional[int] = None,
+              max_pages: Optional[int] = None, max_spend: Optional[Price] = None, timeout: Optional[float] = None,
+              **kwargs: Any) -> AsyncItemPager[Dict[str, Any]]:
+        return AsyncItemPager(self.pages(endpoint_id, params, max_pages=max_pages, max_spend=max_spend, timeout=timeout, **kwargs), max_items)
+
+    async def account(self) -> Dict[str, Any]:
+        return await self.request("GET", "/v1/account")
+
+    async def catalog(self) -> Dict[str, Any]:
+        return await self.request("GET", "/v1/catalog", auth=False)
+
+    async def status(self) -> Dict[str, Any]:
+        return await self.request("GET", "/v1/catalog/status", auth=False)
+
+    async def usage(self, *, group_by: Optional[Sequence[str]] = None, since: Optional[str] = None, until: Optional[str] = None) -> Dict[str, Any]:
+        return await self.request("GET", "/v1/usage", query=usage_query(group_by, since, until))
+
+    async def request(self, method: str, path: str, *, query: Sequence[Any] = (), body: Optional[Dict[str, Any]] = None, auth: bool = True) -> Dict[str, Any]:
+        envelope = await send_async(self._cfg, self._http, self._sleep, Send(method, path, tuple(query), body, None, None, auth))
+        data = envelope.get("data")
+        return data if isinstance(data, dict) else {}

okdata-0.1.0/src/okdata/_base.py

@@ -0,0 +1,88 @@
+"""What OkData and AsyncOkData share: options, headers, and turning a call into a request."""
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from ._generated._endpoints import ENDPOINTS
+from ._request import build_request, field_list
+from ._result import RetryPolicy
+from ._transport import Config, Send
+from ._types import EndpointInfo
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.okdata.online"
+ENV_API_KEY = "OKDATA_API_KEY"
+ENV_BASE_URL = "OKDATA_BASE_URL"
+_LABEL = re.compile(r"[\x21-\x7e]{1,128}")
+_KEY = re.compile(r"[\x21-\x7e]+")
+_REQUEST_ID = re.compile(r"[A-Za-z0-9-]{1,64}")
+
+
+def endpoint(endpoint_id: str) -> Optional[EndpointInfo]:
+    """The catalog entry this SDK was generated with, or None for an id it does not know."""
+    return ENDPOINTS.get(endpoint_id)
+
+
+def _label(value: Optional[str], name: str, most: int = 128) -> Optional[str]:
+    if value is None:
+        return None
+    if not _LABEL.fullmatch(value) or len(value) > most:
+        raise ValueError(f"{name} must be 1-{most} visible ASCII characters, no spaces")
+    return value
+
+
+def make_config(
+    api_key: Optional[str], base_url: Optional[str], timeout: float, max_retries: int, retry_base_delay: float,
+    max_retry_delay: float, entry: str, source: Optional[str], end_user: Optional[str], user_agent: Optional[str],
+) -> Config:
+    key = (api_key if api_key is not None else os.environ.get(ENV_API_KEY, "")).strip()
+    if key and not _KEY.fullmatch(key):
+        raise ValueError("the API key has spaces or control characters in it; copy it again (keys start with okd_)")
+    url = (base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+    if not re.match(r"https?://[^/]+", url):
+        raise ValueError(f"base_url must start with https:// or http://, got {url!r}")
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be a whole number, 0 or more")
+    headers = {"X-Entry": _label(entry, "entry", 32) or "sdk", "User-Agent": " ".join(filter(None, [f"okdata-sdk-python/{__version__}", user_agent]))}
+    for header, value, name in (("X-Source", source, "source"), ("X-End-User", end_user, "end_user")):
+        if _label(value, name) is not None:
+            headers[header] = value  # type: ignore[assignment]
+    return Config(url, key or None, timeout, RetryPolicy(max_retries, retry_base_delay, max_retry_delay), headers)
+
+
+def call_request(endpoint_id: str, params: Mapping[str, Any], idempotency_key: Optional[str], timeout: Optional[float]) -> Send:
+    req = build_request(endpoint_id, ENDPOINTS.get(endpoint_id), params)
+    return Send(req.method, req.path, tuple(req.query), req.body, idempotency_key or str(uuid.uuid4()), req.max_price, True, timeout)
+
+
+def merge_params(params: Optional[Mapping[str, Any]], kwargs: Mapping[str, Any]) -> Dict[str, Any]:
+    return {**(params or {}), **kwargs}
+
+
+def check_request_id(request_id: str) -> str:
+    if not _REQUEST_ID.fullmatch(request_id):
+        raise ValueError("request_id must be the request_id of an earlier call")
+    return request_id
+
+
+def result_query(view: Optional[str], fields: Optional[Union[str, Sequence[str]]]) -> Tuple[Tuple[str, str], ...]:
+    query: List[Tuple[str, str]] = []
+    if view is not None:
+        query.append(("view", view))
+    if fields is not None:
+        query.append(("fields", ",".join(field_list(fields))))
+    return tuple(query)
+
+
+def usage_query(group_by: Optional[Sequence[str]], since: Optional[str], until: Optional[str]) -> Tuple[Tuple[str, str], ...]:
+    query: List[Tuple[str, str]] = []
+    if group_by:
+        query.append(("group_by", ",".join(group_by)))
+    if since:
+        query.append(("since", since))
+    if until:
+        query.append(("until", until))
+    return tuple(query)