xtree-sdk 0.1.0__py3-none-any.whl

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/_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/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/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)

xtree/cli.py

@@ -0,0 +1,138 @@
+"""xtree CLI — balance, wechat helpers, and raw call."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from xtree.client import XTreeClient
+from xtree.exceptions import XTreeError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="xtree", description="XTREE API CLI")
+    parser.add_argument("--json", action="store_true", help="Print data as JSON")
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print meta to stderr (request_id, cost_cny, balance_cny)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("balance", help="GET /account/balance")
+
+    call = sub.add_parser("call", help="Raw API call (any path)")
+    call.add_argument("method", choices=["GET", "POST"])
+    call.add_argument("path", help="API path, e.g. /wechat/search/articles")
+    call.add_argument("--body", default=None, help="JSON body for POST")
+    call.add_argument("--body-file", default=None, help="JSON file for POST body")
+
+    wechat = sub.add_parser("wechat", help="WeChat platform shortcuts")
+    wechat_sub = wechat.add_subparsers(dest="wechat_group", required=True)
+
+    search = wechat_sub.add_parser("search", help="搜一搜")
+    search_sub = search.add_subparsers(dest="search_action", required=True)
+    for name, help_text in [
+        ("articles", "POST /wechat/search/articles"),
+        ("videos", "POST /wechat/search/videos"),
+        ("mixed", "POST /wechat/search/mixed"),
+        ("accounts", "POST /wechat/search/accounts"),
+        ("suggestions", "POST /wechat/search/suggestions"),
+    ]:
+        p = search_sub.add_parser(name, help=help_text)
+        p.add_argument("--keyword", required=True)
+        p.add_argument("--page", type=int, default=1)
+        p.add_argument("--session", default=None)
+
+    library = wechat_sub.add_parser("library", help="库搜索 (Phase 2)")
+    library_sub = library.add_subparsers(dest="library_action", required=True)
+    lib_articles = library_sub.add_parser("articles", help="POST /wechat/library/articles/search")
+    lib_articles.add_argument("--keyword", required=True)
+    lib_articles.add_argument("--page", type=int, default=1)
+
+    args = parser.parse_args(argv)
+    resp = None
+
+    try:
+        with XTreeClient() as client:
+            resp = _dispatch(client, args, parser)
+            if args.verbose and client.last_meta:
+                _print_meta(client.last_meta)
+    except (XTreeError, ValueError, json.JSONDecodeError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    if args.json or args.command != "balance":
+        print(json.dumps(resp.data, ensure_ascii=False, indent=2))
+    else:
+        balance = (resp.data or {}).get("balance_cny")
+        print(f"balance_cny: {balance}")
+
+    return 0
+
+
+def _dispatch(client: XTreeClient, args: argparse.Namespace, parser: argparse.ArgumentParser) -> Any:
+    if args.command == "balance":
+        return client.account.balance()
+
+    if args.command == "call":
+        body = _load_body(args.body, args.body_file)
+        return client.request(args.method, args.path, json=body if args.method == "POST" else None)
+
+    if args.command == "wechat" and args.wechat_group == "search":
+        kwargs = {"keyword": args.keyword, "page": args.page, "session": args.session}
+        actions = {
+            "articles": client.wechat.search.articles,
+            "videos": client.wechat.search.videos,
+            "mixed": client.wechat.search.mixed,
+            "accounts": client.wechat.search.accounts,
+            "suggestions": client.wechat.search.suggestions,
+        }
+        fn = actions.get(args.search_action)
+        if fn is None:
+            parser.error("unknown wechat search action")
+        return fn(**kwargs)
+
+    if args.command == "wechat" and args.wechat_group == "library":
+        if args.library_action == "articles":
+            return client.wechat.library.search_articles(args.keyword, page=args.page)
+
+    parser.error("unknown command")
+    return None
+
+
+def _load_body(body: str | None, body_file: str | None) -> dict[str, Any]:
+    if body_file:
+        return json.loads(Path(body_file).read_text(encoding="utf-8"))
+    if body:
+        return json.loads(body)
+    return {}
+
+
+def _print_meta(meta: Any) -> None:
+    payload = {
+        "request_id": meta.request_id,
+        "cost_cny": meta.cost_cny,
+        "balance_cny": meta.balance_cny,
+        "rate_limit_remaining": meta.rate_limit_remaining,
+    }
+    for key in (
+        "observation_id",
+        "observed_at",
+        "basis",
+        "contract_rev",
+        "origin",
+        "cache_hit",
+        "cache_age_sec",
+    ):
+        value = getattr(meta, key, None)
+        if value is not None:
+            payload[key] = value
+    print(json.dumps(payload, ensure_ascii=False), file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xtree/client.py

@@ -0,0 +1,89 @@
+"""XTreeClient — entry point for the Python SDK."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from xtree._http import DEFAULT_BASE_URL, HTTPClient
+from xtree.account import AccountAPI
+from xtree.types import APIResponse, ResponseMeta
+from xtree.wechat import WechatAPI
+from xtree.douyin import DouyinAPI
+from xtree.xhs import XhsAPI
+from xtree.kuaishou import KuaishouAPI
+from xtree.weibo import WeiboAPI
+from xtree.bilibili import BilibiliAPI
+from xtree.tiktok import TiktokAPI
+from xtree.youtube import YoutubeAPI
+from xtree.facebook import FacebookAPI
+from xtree.taobao import TaobaoAPI
+from xtree.jd import JdAPI
+from xtree.pdd import PddAPI
+
+
+class XTreeClient:
+    """HTTP client for https://api.xtree.io/api."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        verify_code: str | None = None,
+        timeout: float = 60.0,
+        http_client: Any | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("XTREE_API_KEY")
+        if not key:
+            raise ValueError(
+                "api_key is required (pass api_key= or set XTREE_API_KEY)"
+            )
+        url = base_url or os.environ.get("XTREE_BASE_URL") or DEFAULT_BASE_URL
+        vcode = verify_code or os.environ.get("XTREE_VERIFY_CODE")
+        self._http = HTTPClient(
+            api_key=key,
+            base_url=url,
+            verify_code=vcode,
+            timeout=timeout,
+            client=http_client,
+        )
+        self.account = AccountAPI(self._http)
+        self.wechat = WechatAPI(self._http)
+        self.douyin = DouyinAPI(self._http)
+        self.xhs = XhsAPI(self._http)
+        self.kuaishou = KuaishouAPI(self._http)
+        self.weibo = WeiboAPI(self._http)
+        self.bilibili = BilibiliAPI(self._http)
+        self.tiktok = TiktokAPI(self._http)
+        self.youtube = YoutubeAPI(self._http)
+        self.facebook = FacebookAPI(self._http)
+        self.taobao = TaobaoAPI(self._http)
+        self.jd = JdAPI(self._http)
+        self.pdd = PddAPI(self._http)
+
+    @property
+    def last_meta(self) -> ResponseMeta | None:
+        return self._http.last_meta
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> APIResponse[Any]:
+        """Low-level API call with envelope parsing."""
+        resp = self._http.request(method, path, json=json, params=params)
+        self._http.last_meta = resp.meta
+        return resp
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> XTreeClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

xtree/douyin/__init__.py

@@ -0,0 +1,40 @@
+"""AUTO-GENERATED `douyin` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class DouyinAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def videos_detail(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/videos/detail", json=body)
+
+    def users_profile(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/users/profile", json=body)
+
+    def users_posts(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/users/posts", json=body)
+
+    def videos_comments(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/videos/comments", json=body)
+
+    def videos_sub_comments(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/videos/sub-comments", json=body)
+
+    def search_videos(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/search/videos", json=body)
+
+    def search_suggestions(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/search/suggestions", json=body)
+
+    def users_creator_metrics(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/users/creator-metrics", json=body)
+
+    def ids_resolve(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/douyin/ids/resolve", json=body)

xtree/exceptions.py

@@ -0,0 +1,89 @@
+"""XTREE API errors mapped from envelope.error.code."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class XTreeError(Exception):
+    """Base error for failed API calls."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "UNKNOWN",
+        status_code: int | None = None,
+        request_id: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = details
+
+    def __str__(self) -> str:
+        parts = [self.code, str(self.args[0])]
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+        return ": ".join(parts)
+
+
+class XTreeAuthError(XTreeError):
+    """401 UNAUTHORIZED or 403 FORBIDDEN."""
+
+
+class XTreeValidationError(XTreeError):
+    """400 VALIDATION_ERROR."""
+
+
+class XTreeInsufficientBalanceError(XTreeError):
+    """402 INSUFFICIENT_BALANCE."""
+
+
+class XTreeRateLimitError(XTreeError):
+    """429 RATE_LIMITED."""
+
+
+class XTreeServiceError(XTreeError):
+    """502 INTERNAL_ERROR（这次没有完成交付）或 503 EDGE_UNAVAILABLE。"""
+
+
+# 旧名保留，便于已有 except 继续接住 502。
+XTreeUpstreamError = XTreeServiceError
+
+
+_ERROR_MAP: dict[str, type[XTreeError]] = {
+    "UNAUTHORIZED": XTreeAuthError,
+    "FORBIDDEN": XTreeAuthError,
+    "VALIDATION_ERROR": XTreeValidationError,
+    "INSUFFICIENT_BALANCE": XTreeInsufficientBalanceError,
+    "RATE_LIMITED": XTreeRateLimitError,
+    "UPSTREAM_ERROR": XTreeServiceError,
+    "EDGE_UNAVAILABLE": XTreeServiceError,
+    "NOT_FOUND": XTreeError,
+}
+
+
+def error_from_envelope(
+    payload: dict[str, Any],
+    *,
+    status_code: int | None = None,
+) -> XTreeError:
+    err = payload.get("error") or {}
+    code = str(err.get("code") or "UNKNOWN")
+    message = str(err.get("message") or "API request failed")
+    meta = payload.get("meta") or {}
+    request_id = meta.get("request_id")
+    details = err.get("details")
+    cls = _ERROR_MAP.get(code, XTreeError)
+    if code == "INTERNAL_ERROR" and status_code == 502:
+        cls = XTreeServiceError
+    return cls(
+        message,
+        code=code,
+        status_code=status_code,
+        request_id=request_id,
+        details=details,
+    )

xtree/facebook/__init__.py

@@ -0,0 +1,19 @@
+"""AUTO-GENERATED `facebook` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class FacebookAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def search_general(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/facebook/search/general", json=body)
+
+    def search_users(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/facebook/search/users", json=body)

xtree/jd/__init__.py

@@ -0,0 +1,22 @@
+"""AUTO-GENERATED `jd` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class JdAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def items_detail(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/jd/items/detail", json=body)
+
+    def items_comments(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/jd/items/comments", json=body)
+
+    def items_comments_v2(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/jd/items/comments/v2", json=body)

xtree/kuaishou/__init__.py

@@ -0,0 +1,37 @@
+"""AUTO-GENERATED `kuaishou` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class KuaishouAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def videos_detail(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/videos/detail", json=body)
+
+    def videos_comments(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/videos/comments", json=body)
+
+    def users_profile(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/users/profile", json=body)
+
+    def users_posts(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/users/posts", json=body)
+
+    def search_videos(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/search/videos", json=body)
+
+    def videos_short_link(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/videos/short-link", json=body)
+
+    def hot_board(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/hot/board", json=body)
+
+    def ids_resolve(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/kuaishou/ids/resolve", json=body)

xtree/pdd/__init__.py

@@ -0,0 +1,22 @@
+"""AUTO-GENERATED `pdd` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from xtree._http import HTTPClient
+from xtree.types import APIResponse
+
+
+class PddAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def items_comments_submit(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/pdd/items/comments/submit", json=body)
+
+    def items_comments_status(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/pdd/items/comments/status", json=body)
+
+    def items_comments_fetch(self, **body: Any) -> APIResponse[Any]:
+        return self._http.request("POST", "/pdd/items/comments/fetch", json=body)