xtree-sdk 0.1.0__tar.gz

xtree_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: require PyPI name xtree-sdk
+        run: python -c "import pathlib,sys,tomllib; n=tomllib.load(pathlib.Path('pyproject.toml').open('rb'))['project']['name']; sys.exit('pyproject project.name must be xtree-sdk' if n!='xtree-sdk' else 0)"
+      - run: pip install build twine
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

xtree_sdk-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest tests -q

xtree_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: xtree-sdk
+Version: 0.1.0
+Summary: Python client for the XTREE API — real-time raw data layer
+Project-URL: Homepage, https://www.xtree.io
+Project-URL: Documentation, https://www.xtree.io/docs
+Project-URL: Repository, https://github.com/xtree-io/xtree-python
+Author-email: XTREE <business@xtree.io>
+License: MIT
+Keywords: api,sdk,wechat,xtree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# XTREE Python SDK
+
+Python client for the [XTREE](https://www.xtree.io) social media data API. Scripts and backends call REST through `XTreeClient`. Agent hosts that want tools should use [xtree-mcp](https://github.com/xtree-io/xtree-mcp) (WeChat tools today). **Not** a BI or analytics platform.
+
+Covers the public OpenAPI surface (WeChat, Douyin, Xiaohongshu, and the other live platforms). See [API reference](https://www.xtree.io/docs/apis) and [OpenAPI](https://api.xtree.io/api/openapi.json). Facebook, JD, and PDD client classes exist in the source tree and are not live catalog products.
+
+## Install
+
+```bash
+pip install xtree-sdk
+```
+
+Requires Python 3.10+.
+
+## Get an API Key
+
+1. Sign up at [www.xtree.io](https://www.xtree.io/login?tab=signup).
+2. Copy a key from the account console (`xt_live_...`).
+3. Export it:
+
+```bash
+export XTREE_API_KEY=xt_live_...
+```
+
+## Quickstart
+
+```python
+from xtree import XTreeClient
+
+client = XTreeClient()  # reads XTREE_API_KEY
+
+print(client.account.balance().data["balance_cny"])
+
+resp = client.wechat.search.articles(keyword="人民日报", page=1)
+print(resp.data)
+print(client.last_meta.cost_cny if client.last_meta else None)
+```
+
+## CLI
+
+```bash
+xtree balance
+xtree wechat search videos --keyword "人民日报" --json
+xtree call POST /wechat/search/articles --body '{"keyword":"人民日报"}'
+```
+
+## Billing
+
+Pay per call from your wallet (CNY). Incomplete delivery is not billed. Unit prices: [API Catalog](https://www.xtree.io/catalog). No volume tiers and no `/pricing` plans page. Bulk / bank transfer / enterprise: [business@xtree.io](mailto:business@xtree.io).
+
+## Docs
+
+- Quick start: https://www.xtree.io/docs
+- API reference: https://www.xtree.io/docs/apis
+- OpenAPI: https://api.xtree.io/api/openapi.json
+- MCP for agents: https://github.com/xtree-io/xtree-mcp
+- Examples: https://github.com/xtree-io/xtree-examples
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `XTREE_API_KEY` | yes | — |
+| `XTREE_BASE_URL` | no | `https://api.xtree.io/api` |
+| `XTREE_VERIFY_CODE` | no | — |
+
+## Mirror notice
+
+**Do not develop in this repository.** It is a public mirror synced from a private monorepo. Open issues here for SDK / docs feedback. Contact: [business@xtree.io](mailto:business@xtree.io).
+
+## License
+
+MIT.

xtree_sdk-0.1.0/README.md

@@ -0,0 +1,73 @@
+# XTREE Python SDK
+
+Python client for the [XTREE](https://www.xtree.io) social media data API. Scripts and backends call REST through `XTreeClient`. Agent hosts that want tools should use [xtree-mcp](https://github.com/xtree-io/xtree-mcp) (WeChat tools today). **Not** a BI or analytics platform.
+
+Covers the public OpenAPI surface (WeChat, Douyin, Xiaohongshu, and the other live platforms). See [API reference](https://www.xtree.io/docs/apis) and [OpenAPI](https://api.xtree.io/api/openapi.json). Facebook, JD, and PDD client classes exist in the source tree and are not live catalog products.
+
+## Install
+
+```bash
+pip install xtree-sdk
+```
+
+Requires Python 3.10+.
+
+## Get an API Key
+
+1. Sign up at [www.xtree.io](https://www.xtree.io/login?tab=signup).
+2. Copy a key from the account console (`xt_live_...`).
+3. Export it:
+
+```bash
+export XTREE_API_KEY=xt_live_...
+```
+
+## Quickstart
+
+```python
+from xtree import XTreeClient
+
+client = XTreeClient()  # reads XTREE_API_KEY
+
+print(client.account.balance().data["balance_cny"])
+
+resp = client.wechat.search.articles(keyword="人民日报", page=1)
+print(resp.data)
+print(client.last_meta.cost_cny if client.last_meta else None)
+```
+
+## CLI
+
+```bash
+xtree balance
+xtree wechat search videos --keyword "人民日报" --json
+xtree call POST /wechat/search/articles --body '{"keyword":"人民日报"}'
+```
+
+## Billing
+
+Pay per call from your wallet (CNY). Incomplete delivery is not billed. Unit prices: [API Catalog](https://www.xtree.io/catalog). No volume tiers and no `/pricing` plans page. Bulk / bank transfer / enterprise: [business@xtree.io](mailto:business@xtree.io).
+
+## Docs
+
+- Quick start: https://www.xtree.io/docs
+- API reference: https://www.xtree.io/docs/apis
+- OpenAPI: https://api.xtree.io/api/openapi.json
+- MCP for agents: https://github.com/xtree-io/xtree-mcp
+- Examples: https://github.com/xtree-io/xtree-examples
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `XTREE_API_KEY` | yes | — |
+| `XTREE_BASE_URL` | no | `https://api.xtree.io/api` |
+| `XTREE_VERIFY_CODE` | no | — |
+
+## Mirror notice
+
+**Do not develop in this repository.** It is a public mirror synced from a private monorepo. Open issues here for SDK / docs feedback. Contact: [business@xtree.io](mailto:business@xtree.io).
+
+## License
+
+MIT.

xtree_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xtree-sdk"
+version = "0.1.0"
+description = "Python client for the XTREE API — real-time raw data layer"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "XTREE", email = "business@xtree.io" }]
+keywords = ["xtree", "wechat", "api", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-httpx>=0.30",
+]
+
+[project.urls]
+Homepage = "https://www.xtree.io"
+Documentation = "https://www.xtree.io/docs"
+Repository = "https://github.com/xtree-io/xtree-python"
+
+[project.scripts]
+xtree = "xtree.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["xtree"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xtree_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,54 @@
+"""Client integration tests with httpx mock transport."""
+
+import httpx
+import pytest
+
+from xtree.client import XTreeClient
+
+
+def _envelope(data, **meta):
+    return {
+        "ok": True,
+        "data": data,
+        "meta": {"request_id": "01JMOCK", **meta},
+        "error": None,
+    }
+
+
+def test_balance():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["X-XTREE-Key"] == "xt_test_key"
+        assert request.url.path == "/api/account/balance"
+        return httpx.Response(200, json=_envelope({"balance_cny": 42.5}))
+
+    transport = httpx.MockTransport(handler)
+    http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
+    client = XTreeClient(api_key="xt_test_key", http_client=http)
+    resp = client.account.balance()
+    assert resp.data["balance_cny"] == 42.5
+    assert client.last_meta is not None
+    assert client.last_meta.request_id == "01JMOCK"
+
+
+def test_search_videos():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = request.content.decode()
+        return httpx.Response(
+            200,
+            json=_envelope({"items": [], "session": "next"}, cost_cny=0.5),
+        )
+
+    transport = httpx.MockTransport(handler)
+    http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
+    client = XTreeClient(api_key="xt_test_key", http_client=http)
+    resp = client.wechat.search.videos(keyword="test", page=2)
+    assert resp.data["session"] == "next"
+    assert client.last_meta.cost_cny == 0.5
+    assert '"keyword":"test"' in captured["body"]
+
+
+def test_missing_api_key():
+    with pytest.raises(ValueError, match="XTREE_API_KEY"):
+        XTreeClient(api_key=None)

xtree_sdk-0.1.0/tests/test_coverage.py

@@ -0,0 +1,42 @@
+"""Coverage tests — SDK registry vs OpenAPI spec."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from xtree.registry import COVERED_ENDPOINTS, SLUG_BY_PATH
+
+ROOT = Path(__file__).resolve().parents[2]  # sdk/
+SPEC = ROOT / "openapi" / "spec" / "openapi.json"
+
+
+def _openapi_operations(spec: dict) -> set[tuple[str, str]]:
+    ops: set[tuple[str, str]] = set()
+    for path, item in spec["paths"].items():
+        for method in item:
+            if method in ("get", "post", "put", "patch", "delete"):
+                ops.add((method.upper(), path))
+    return ops
+
+
+@pytest.fixture(scope="module")
+def openapi_spec() -> dict:
+    return json.loads(SPEC.read_text(encoding="utf-8"))
+
+
+def test_openapi_has_114_operations(openapi_spec: dict) -> None:
+    assert len(_openapi_operations(openapi_spec)) == 120
+
+
+def test_registry_covers_openapi(openapi_spec: dict) -> None:
+    openapi_ops = _openapi_operations(openapi_spec)
+    covered = set(COVERED_ENDPOINTS)
+    assert openapi_ops == covered
+
+
+def test_slug_map_covers_all_registry_entries() -> None:
+    assert set(SLUG_BY_PATH) == set(COVERED_ENDPOINTS)
+    assert len(SLUG_BY_PATH) == 120

xtree_sdk-0.1.0/tests/test_envelope.py

@@ -0,0 +1,68 @@
+"""Envelope parsing tests."""
+
+import pytest
+
+from xtree._http import _unwrap_envelope
+from xtree.exceptions import (
+    XTreeInsufficientBalanceError,
+    XTreeRateLimitError,
+    XTreeServiceError,
+    XTreeUpstreamError,
+)
+
+
+def test_unwrap_success():
+    resp = _unwrap_envelope(
+        {
+            "ok": True,
+            "data": {"balance_cny": 100.0},
+            "meta": {"request_id": "01JTEST", "cost_cny": 0},
+            "error": None,
+        },
+        status_code=200,
+    )
+    assert resp.data["balance_cny"] == 100.0
+    assert resp.meta.request_id == "01JTEST"
+
+
+def test_unwrap_insufficient_balance():
+    with pytest.raises(XTreeInsufficientBalanceError) as exc:
+        _unwrap_envelope(
+            {
+                "ok": False,
+                "data": None,
+                "meta": {"request_id": "01JFAIL"},
+                "error": {"code": "INSUFFICIENT_BALANCE", "message": "余额不足"},
+            },
+            status_code=402,
+        )
+    assert exc.value.code == "INSUFFICIENT_BALANCE"
+    assert exc.value.request_id == "01JFAIL"
+
+
+def test_unwrap_internal_delivery_failure():
+    with pytest.raises(XTreeServiceError) as exc:
+        _unwrap_envelope(
+            {
+                "ok": False,
+                "data": None,
+                "meta": {"request_id": "01JERR"},
+                "error": {"code": "INTERNAL_ERROR", "message": "接口异常"},
+            },
+            status_code=502,
+        )
+    assert exc.value.code == "INTERNAL_ERROR"
+    assert isinstance(exc.value, XTreeUpstreamError)
+
+
+def test_unwrap_rate_limited():
+    with pytest.raises(XTreeRateLimitError):
+        _unwrap_envelope(
+            {
+                "ok": False,
+                "data": None,
+                "meta": {"request_id": "01JRATE"},
+                "error": {"code": "RATE_LIMITED", "message": "too many requests"},
+            },
+            status_code=429,
+        )

xtree_sdk-0.1.0/xtree/__init__.py

@@ -0,0 +1,7 @@
+"""XTREE Python SDK — HTTP client for api.xtree.io."""
+
+from xtree.client import XTreeClient
+from xtree.exceptions import XTreeError
+
+__all__ = ["XTreeClient", "XTreeError"]
+__version__ = "0.1.0"

xtree_sdk-0.1.0/xtree/_http.py

@@ -0,0 +1,111 @@
+"""HTTP transport with envelope parsing and retries."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from xtree.exceptions import XTreeError, error_from_envelope
+from xtree.types import APIResponse, ResponseMeta
+
+DEFAULT_BASE_URL = "https://api.xtree.io/api"
+API_KEY_HEADER = "X-XTREE-Key"
+VERIFY_CODE_HEADER = "X-Verify-Code"
+DEFAULT_TIMEOUT = 60.0
+RETRY_STATUS = {429, 502, 503}
+MAX_RETRIES = 3
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        verify_code: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.verify_code = verify_code
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+        self._headers = {
+            API_KEY_HEADER: api_key,
+            "Accept": "application/json",
+            "User-Agent": "xtree-python/0.1.0",
+        }
+        if verify_code:
+            self._headers[VERIFY_CODE_HEADER] = verify_code
+        self.last_meta: ResponseMeta | None = None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> HTTPClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> APIResponse[Any]:
+        url = f"{self.base_url}{path}"
+        last_exc: Exception | None = None
+
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    headers=self._headers,
+                    json=json,
+                    params=params,
+                )
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt >= MAX_RETRIES:
+                    raise XTreeError(str(exc), code="TRANSPORT_ERROR") from exc
+                time.sleep(2**attempt * 0.5)
+                continue
+
+            payload = _parse_json(response)
+            if response.status_code in RETRY_STATUS and attempt < MAX_RETRIES:
+                time.sleep(2**attempt * 0.5)
+                continue
+
+            return _unwrap_envelope(payload, status_code=response.status_code)
+
+        if last_exc:
+            raise XTreeError(str(last_exc), code="TRANSPORT_ERROR") from last_exc
+        raise XTreeError("Request failed after retries", code="TRANSPORT_ERROR")
+
+
+def _parse_json(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+        if isinstance(data, dict):
+            return data
+    except ValueError:
+        pass
+    raise XTreeError(
+        f"Non-JSON response (HTTP {response.status_code})",
+        code="INVALID_RESPONSE",
+        status_code=response.status_code,
+    )
+
+
+def _unwrap_envelope(payload: dict[str, Any], *, status_code: int) -> APIResponse[Any]:
+    meta = ResponseMeta.from_dict(payload.get("meta") or {})
+    if payload.get("ok") is True:
+        return APIResponse(data=payload.get("data"), meta=meta)
+    raise error_from_envelope(payload, status_code=status_code)

xtree_sdk-0.1.0/xtree/account.py

@@ -0,0 +1,19 @@
+"""Account endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class AccountAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def balance(self) -> APIResponse[dict[str, Any]]:
+        """GET /account/balance — free, returns balance_cny."""
+        resp = self._http.request("GET", "/account/balance")
+        self._http.last_meta = resp.meta
+        return resp

xtree_sdk-0.1.0/xtree/bilibili/__init__.py

@@ -0,0 +1,40 @@
+"""AUTO-GENERATED `bilibili` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class BilibiliAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def search_videos(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/search/videos", json=body)
+
+    def videos_detail(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/videos/detail", json=body)
+
+    def videos_comments(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/videos/comments", json=body)
+
+    def videos_download(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/videos/download", json=body)
+
+    def users_profile(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/users/profile", json=body)
+
+    def users_posts(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/users/posts", json=body)
+
+    def users_videos(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/users/videos", json=body)
+
+    def popular_list(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/popular/list", json=body)
+
+    def rank_list(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/bilibili/rank/list", json=body)