busybee-mcp 0.2.1__tar.gz

busybee_mcp-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BusyBee Data
+
+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.

busybee_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: busybee-mcp
+Version: 0.2.1
+Summary: BusyBee Data MCP server — public social media data for AI agents (TikTok, Instagram, YouTube, X, Douyin, Xiaohongshu).
+Author: BusyBee Data
+License: MIT
+Project-URL: Homepage, https://lucydomi.com
+Keywords: mcp,social-media,tiktok,instagram,youtube,creator-discovery
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: http
+Requires-Dist: uvicorn>=0.30; extra == "http"
+Dynamic: license-file
+
+# BusyBee MCP
+
+**Public social media data for AI agents.** Ten business-level tools, one schema — TikTok, Instagram, YouTube, X (Twitter), Douyin and Xiaohongshu.
+
+Ask your agent *"who are the fastest-growing coffee creators on TikTok right now, and what do their comment sections complain about?"* — it answers with real data, in one conversation.
+
+```
+Endpoint    https://lucydomi.com/mcp
+Protocols   MCP Streamable HTTP · MCP SSE (legacy) · REST/JSON · stdio
+Tools       10
+Billing     pay per call; every response returns cost_usd + balance_usd
+```
+
+---
+
+## Works with every kind of agent
+
+Most "social data for AI" products ship one transport and hope your client speaks it. This server speaks four, on the same host, with the same 10 tools behind all of them.
+
+| Your agent | What it supports | How to connect |
+|---|---|---|
+| **Claude Code** | Streamable HTTP | `claude mcp add busybee --transport http https://lucydomi.com/mcp --header "Authorization: Bearer sk-..."` |
+| **Cursor / Cline / Windsurf / VS Code** | Streamable HTTP | add to `mcp.json` (see below) |
+| **Claude Desktop** | stdio | `uvx --from git+https://github.com/danfeistar/busybee-mcp busybee-mcp` with `BUSYBEE_API_KEY` (not on PyPI yet) |
+| **Older MCP clients (2024-11 era)** | SSE only | `https://lucydomi.com/sse` + `https://lucydomi.com/messages/` |
+| **Dify / n8n / Coze / FastGPT** | OpenAPI / plain HTTP | import `https://lucydomi.com/mcp/openapi.json` (3.1), or `?spec=3.0` for older importers |
+| **LangChain / LlamaIndex / custom code** | tools JSON or HTTP | `https://lucydomi.com/mcp/tools?format=openai`, or call REST directly |
+| **GPT Actions / Zapier / Make** | OpenAPI 3.x | same spec URL, bearer auth |
+| **Anything that can only GET a URL** | query string | `https://lucydomi.com/mcp/v1/search_creators?platform=tiktok&keyword=coffee&api_key=sk-...` |
+
+Discovery document (machine-readable, tells an agent what's available): `https://lucydomi.com/mcp/info`
+
+---
+
+## The 10 tools
+
+| Tool | What it answers |
+|---|---|
+| `list_platforms` | Which platforms exist, which tools each supports, which key group you need |
+| `search_creators` | "Find me mid-size coffee creators on TikTok" |
+| `search_posts` | "What is being posted about cold brew this week?" |
+| `get_creator` | "How big is this account, what's their bio?" |
+| `list_creator_posts` | "What has this account posted recently?" |
+| `get_post` | "Give me the details of this one video" |
+| `get_comments` | "What are people saying under this post?" |
+| `get_trending` | "What's trending on Douyin right now?" |
+| `get_comment_insights` | "Summarize the comment section: sentiment, questions, complaints" |
+| `check_balance` | "How much credit do I have left?" |
+
+`get_comment_insights` is the one people keep open: it samples comments, then returns sentiment split, question ratio, high-frequency phrases and top-liked comments — so the agent answers *"what do users actually want"* instead of dumping fifty raw rows.
+
+---
+
+## One schema, every platform
+
+```json
+{
+  "platform": "tiktok",
+  "id": "7690199760430566669",
+  "url": "https://www.tiktok.com/@creator/video/7690199760430566669",
+  "author": { "id": "6948174171005158405", "handle": "goldenbrown.coffee", "name": "Golden Brown Coffee" },
+  "text": "Spanish latte, but make it iced",
+  "created_at": "2026-10-18T09:12:00Z",
+  "stats": { "likes": 41200, "comments": 812, "shares": 2331, "views": 918000, "collects": 5120 },
+  "cover": "https://..."
+}
+```
+
+Every response also carries `cost_usd` and `balance_usd`, so the agent can budget itself and you can see what a task actually cost.
+
+---
+
+## Setup per client
+
+Need a key first: register at [lucydomi.com](https://lucydomi.com) → *Console → API Keys → New key* (`sk-…`). Overseas and China platforms use different key groups.
+
+### Claude Code
+```bash
+claude mcp add busybee --transport http https://lucydomi.com/mcp \
+  --header "Authorization: Bearer sk-YOUR_KEY"
+```
+
+### Cursor / Cline / Windsurf / VS Code (`~/.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "busybee": {
+      "url": "https://lucydomi.com/mcp",
+      "headers": { "Authorization": "Bearer sk-YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Claude Desktop (local stdio)
+```json
+{
+  "mcpServers": {
+    "busybee": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/danfeistar/busybee-mcp", "busybee-mcp"],
+      "args": ["busybee-mcp"],
+      "env": { "BUSYBEE_API_KEY": "sk-YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Legacy SSE clients
+```
+SSE URL      https://lucydomi.com/sse
+Messages URL https://lucydomi.com/messages/?session_id=<from the SSE event>
+Header       Authorization: Bearer sk-YOUR_KEY
+```
+
+### Dify / n8n / Coze / GPT Actions
+Import `https://lucydomi.com/mcp/openapi.json`, set auth to Bearer `sk-YOUR_KEY`. If the importer rejects 3.1, use `https://lucydomi.com/mcp/openapi.json?spec=3.0`.
+
+### LangChain / custom Python (no MCP needed)
+```python
+import json, urllib.request
+req = urllib.request.Request(
+    "https://lucydomi.com/mcp/v1/search_creators",
+    data=json.dumps({"platform": "tiktok", "keyword": "coffee", "limit": 3}).encode(),
+    headers={"Content-Type": "application/json", "Authorization": "Bearer sk-YOUR_KEY"},
+)
+print(json.load(urllib.request.urlopen(req)))
+```
+Tool schemas for function calling: `GET https://lucydomi.com/mcp/tools?format=openai`
+
+### Local package
+```bash
+pip install busybee-mcp
+BUSYBEE_API_KEY=sk-YOUR_KEY busybee-mcp          # stdio
+BUSYBEE_API_KEY=sk-YOUR_KEY busybee-mcp http     # serve all transports on :3013
+```
+
+---
+
+## Design decisions worth knowing
+
+- **Ten tools, not a thousand.** Call a business intent, not an endpoint. The more tools a model sees, the more often it picks wrong and burns money.
+- **Normalized fields.** `author / text / created_at / stats` mean the same thing on every platform.
+- **One implementation behind every protocol.** MCP, SSE and REST share the same dispatch layer, so behavior can't drift between clients.
+- **Pay per call, priced per endpoint.** Cheap calls cost fractions of a cent. Price is visible in your console.
+- **Cost transparency inside the result.** `cost_usd` + `balance_usd` on every response.
+- **Failures are not billed.**
+- **Clean errors.** No stack traces, no third-party vendor names, no upstream documentation links leaking into your agent's context.
+- **CORS enabled**, so browser-based agents and web widgets can call it directly.
+
+## Errors
+
+| `error` | Meaning | What to do |
+|---|---|---|
+| `no_api_key` | No key supplied | Add `Authorization: Bearer sk-...`, `X-API-Key`, or `?api_key=` |
+| `unauthorized` | Key invalid or deleted | Issue a new key in the console |
+| `insufficient_balance` | Out of credit | Top up |
+| `forbidden` | Key group doesn't cover that platform | Create a key in the right group |
+| `rate_limited` | Too many requests | Back off and retry |
+| `unsupported_tool` | That platform doesn't expose the tool | Call `list_platforms` to see the matrix |
+| `upstream_error` | Temporary provider failure | Retry once; not billed |
+
+## Scope and compliance
+
+BusyBee serves **public** social media data only, and only to users **outside mainland China**. Do not use it to profile private individuals, scrape private accounts, manipulate engagement, or train models on personal data without a lawful basis. See the [data policy](https://lucydomi.com/data-policy).
+
+## License
+
+MIT — see [LICENSE](LICENSE). This repository is the client-side MCP server; the hosted service is metered separately.
+
+---
+
+## 中文速览
+
+**BusyBee MCP** 把 TikTok、Instagram、YouTube、X、抖音、小红书六个平台的公开数据，压成 **10 个业务级工具 + 一套统一字段**，**同一台服务器支持四种接入方式**：
+
+| 你的 AI 工具 | 接入地址 |
+|---|---|
+| Claude Code / Cursor / Cline（MCP 新版） | `https://lucydomi.com/mcp` |
+| 只认旧版 SSE 的客户端 | `https://lucydomi.com/sse` |
+| Dify / n8n / Coze / GPT Actions（OpenAPI） | `https://lucydomi.com/mcp/openapi.json` |
+| 任何能发 HTTP 的程序 | `https://lucydomi.com/mcp/v1/<工具名>` |
+
+- 密钥：注册后在控制台建 `sk-` 开头的串
+- 计费：按次，每次返回都带本次花费与余额；失败不扣费
+- 报错是干净中文/英文，不暴露任何上游信息

busybee_mcp-0.2.1/README.md

@@ -0,0 +1,186 @@
+# BusyBee MCP
+
+**Public social media data for AI agents.** Ten business-level tools, one schema — TikTok, Instagram, YouTube, X (Twitter), Douyin and Xiaohongshu.
+
+Ask your agent *"who are the fastest-growing coffee creators on TikTok right now, and what do their comment sections complain about?"* — it answers with real data, in one conversation.
+
+```
+Endpoint    https://lucydomi.com/mcp
+Protocols   MCP Streamable HTTP · MCP SSE (legacy) · REST/JSON · stdio
+Tools       10
+Billing     pay per call; every response returns cost_usd + balance_usd
+```
+
+---
+
+## Works with every kind of agent
+
+Most "social data for AI" products ship one transport and hope your client speaks it. This server speaks four, on the same host, with the same 10 tools behind all of them.
+
+| Your agent | What it supports | How to connect |
+|---|---|---|
+| **Claude Code** | Streamable HTTP | `claude mcp add busybee --transport http https://lucydomi.com/mcp --header "Authorization: Bearer sk-..."` |
+| **Cursor / Cline / Windsurf / VS Code** | Streamable HTTP | add to `mcp.json` (see below) |
+| **Claude Desktop** | stdio | `uvx --from git+https://github.com/danfeistar/busybee-mcp busybee-mcp` with `BUSYBEE_API_KEY` (not on PyPI yet) |
+| **Older MCP clients (2024-11 era)** | SSE only | `https://lucydomi.com/sse` + `https://lucydomi.com/messages/` |
+| **Dify / n8n / Coze / FastGPT** | OpenAPI / plain HTTP | import `https://lucydomi.com/mcp/openapi.json` (3.1), or `?spec=3.0` for older importers |
+| **LangChain / LlamaIndex / custom code** | tools JSON or HTTP | `https://lucydomi.com/mcp/tools?format=openai`, or call REST directly |
+| **GPT Actions / Zapier / Make** | OpenAPI 3.x | same spec URL, bearer auth |
+| **Anything that can only GET a URL** | query string | `https://lucydomi.com/mcp/v1/search_creators?platform=tiktok&keyword=coffee&api_key=sk-...` |
+
+Discovery document (machine-readable, tells an agent what's available): `https://lucydomi.com/mcp/info`
+
+---
+
+## The 10 tools
+
+| Tool | What it answers |
+|---|---|
+| `list_platforms` | Which platforms exist, which tools each supports, which key group you need |
+| `search_creators` | "Find me mid-size coffee creators on TikTok" |
+| `search_posts` | "What is being posted about cold brew this week?" |
+| `get_creator` | "How big is this account, what's their bio?" |
+| `list_creator_posts` | "What has this account posted recently?" |
+| `get_post` | "Give me the details of this one video" |
+| `get_comments` | "What are people saying under this post?" |
+| `get_trending` | "What's trending on Douyin right now?" |
+| `get_comment_insights` | "Summarize the comment section: sentiment, questions, complaints" |
+| `check_balance` | "How much credit do I have left?" |
+
+`get_comment_insights` is the one people keep open: it samples comments, then returns sentiment split, question ratio, high-frequency phrases and top-liked comments — so the agent answers *"what do users actually want"* instead of dumping fifty raw rows.
+
+---
+
+## One schema, every platform
+
+```json
+{
+  "platform": "tiktok",
+  "id": "7690199760430566669",
+  "url": "https://www.tiktok.com/@creator/video/7690199760430566669",
+  "author": { "id": "6948174171005158405", "handle": "goldenbrown.coffee", "name": "Golden Brown Coffee" },
+  "text": "Spanish latte, but make it iced",
+  "created_at": "2026-10-18T09:12:00Z",
+  "stats": { "likes": 41200, "comments": 812, "shares": 2331, "views": 918000, "collects": 5120 },
+  "cover": "https://..."
+}
+```
+
+Every response also carries `cost_usd` and `balance_usd`, so the agent can budget itself and you can see what a task actually cost.
+
+---
+
+## Setup per client
+
+Need a key first: register at [lucydomi.com](https://lucydomi.com) → *Console → API Keys → New key* (`sk-…`). Overseas and China platforms use different key groups.
+
+### Claude Code
+```bash
+claude mcp add busybee --transport http https://lucydomi.com/mcp \
+  --header "Authorization: Bearer sk-YOUR_KEY"
+```
+
+### Cursor / Cline / Windsurf / VS Code (`~/.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "busybee": {
+      "url": "https://lucydomi.com/mcp",
+      "headers": { "Authorization": "Bearer sk-YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Claude Desktop (local stdio)
+```json
+{
+  "mcpServers": {
+    "busybee": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/danfeistar/busybee-mcp", "busybee-mcp"],
+      "args": ["busybee-mcp"],
+      "env": { "BUSYBEE_API_KEY": "sk-YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Legacy SSE clients
+```
+SSE URL      https://lucydomi.com/sse
+Messages URL https://lucydomi.com/messages/?session_id=<from the SSE event>
+Header       Authorization: Bearer sk-YOUR_KEY
+```
+
+### Dify / n8n / Coze / GPT Actions
+Import `https://lucydomi.com/mcp/openapi.json`, set auth to Bearer `sk-YOUR_KEY`. If the importer rejects 3.1, use `https://lucydomi.com/mcp/openapi.json?spec=3.0`.
+
+### LangChain / custom Python (no MCP needed)
+```python
+import json, urllib.request
+req = urllib.request.Request(
+    "https://lucydomi.com/mcp/v1/search_creators",
+    data=json.dumps({"platform": "tiktok", "keyword": "coffee", "limit": 3}).encode(),
+    headers={"Content-Type": "application/json", "Authorization": "Bearer sk-YOUR_KEY"},
+)
+print(json.load(urllib.request.urlopen(req)))
+```
+Tool schemas for function calling: `GET https://lucydomi.com/mcp/tools?format=openai`
+
+### Local package
+```bash
+pip install busybee-mcp
+BUSYBEE_API_KEY=sk-YOUR_KEY busybee-mcp          # stdio
+BUSYBEE_API_KEY=sk-YOUR_KEY busybee-mcp http     # serve all transports on :3013
+```
+
+---
+
+## Design decisions worth knowing
+
+- **Ten tools, not a thousand.** Call a business intent, not an endpoint. The more tools a model sees, the more often it picks wrong and burns money.
+- **Normalized fields.** `author / text / created_at / stats` mean the same thing on every platform.
+- **One implementation behind every protocol.** MCP, SSE and REST share the same dispatch layer, so behavior can't drift between clients.
+- **Pay per call, priced per endpoint.** Cheap calls cost fractions of a cent. Price is visible in your console.
+- **Cost transparency inside the result.** `cost_usd` + `balance_usd` on every response.
+- **Failures are not billed.**
+- **Clean errors.** No stack traces, no third-party vendor names, no upstream documentation links leaking into your agent's context.
+- **CORS enabled**, so browser-based agents and web widgets can call it directly.
+
+## Errors
+
+| `error` | Meaning | What to do |
+|---|---|---|
+| `no_api_key` | No key supplied | Add `Authorization: Bearer sk-...`, `X-API-Key`, or `?api_key=` |
+| `unauthorized` | Key invalid or deleted | Issue a new key in the console |
+| `insufficient_balance` | Out of credit | Top up |
+| `forbidden` | Key group doesn't cover that platform | Create a key in the right group |
+| `rate_limited` | Too many requests | Back off and retry |
+| `unsupported_tool` | That platform doesn't expose the tool | Call `list_platforms` to see the matrix |
+| `upstream_error` | Temporary provider failure | Retry once; not billed |
+
+## Scope and compliance
+
+BusyBee serves **public** social media data only, and only to users **outside mainland China**. Do not use it to profile private individuals, scrape private accounts, manipulate engagement, or train models on personal data without a lawful basis. See the [data policy](https://lucydomi.com/data-policy).
+
+## License
+
+MIT — see [LICENSE](LICENSE). This repository is the client-side MCP server; the hosted service is metered separately.
+
+---
+
+## 中文速览
+
+**BusyBee MCP** 把 TikTok、Instagram、YouTube、X、抖音、小红书六个平台的公开数据，压成 **10 个业务级工具 + 一套统一字段**，**同一台服务器支持四种接入方式**：
+
+| 你的 AI 工具 | 接入地址 |
+|---|---|
+| Claude Code / Cursor / Cline（MCP 新版） | `https://lucydomi.com/mcp` |
+| 只认旧版 SSE 的客户端 | `https://lucydomi.com/sse` |
+| Dify / n8n / Coze / GPT Actions（OpenAPI） | `https://lucydomi.com/mcp/openapi.json` |
+| 任何能发 HTTP 的程序 | `https://lucydomi.com/mcp/v1/<工具名>` |
+
+- 密钥：注册后在控制台建 `sk-` 开头的串
+- 计费：按次，每次返回都带本次花费与余额；失败不扣费
+- 报错是干净中文/英文，不暴露任何上游信息

busybee_mcp-0.2.1/busybee_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""BusyBee MCP —— 给 AI Agent 用的社媒公开数据工具箱。"""
+__version__ = "0.2.1"

busybee_mcp-0.2.1/busybee_mcp/cli.py

@@ -0,0 +1,20 @@
+"""命令行入口：默认 stdio；`busybee-mcp http` 起远程服务。"""
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    mode = sys.argv[1] if len(sys.argv) > 1 else "stdio"
+    if mode in ("http", "serve", "streamable-http"):
+        from .http_app import main as http_main
+
+        http_main()
+        return
+    from .server import serve
+
+    serve("stdio")
+
+
+if __name__ == "__main__":
+    main()

busybee_mcp-0.2.1/busybee_mcp/client.py

@@ -0,0 +1,138 @@
+"""HTTP 客户端 —— 只在进程内持有 API Key，不打印、不落盘。"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+DEFAULT_BASE = "https://lucydomi.com"
+SIGNUP_URL = "https://lucydomi.com"
+
+
+class BusyBeeError(Exception):
+    """带中文说明的业务异常，直接回给 AI/用户看。"""
+
+    def __init__(self, message: str, code: str = "error", hint: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.hint = hint
+
+    def as_dict(self) -> dict:
+        d = {"ok": False, "error": self.code, "message": self.message}
+        if self.hint:
+            d["hint"] = self.hint
+        return d
+
+
+class Client:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: int | None = None):
+        self.api_key = api_key or os.environ.get("BUSYBEE_API_KEY") or os.environ.get("XMF_API_KEY")
+        self.base_url = (base_url or os.environ.get("BUSYBEE_BASE_URL") or DEFAULT_BASE).rstrip("/")
+        self.timeout = int(timeout or os.environ.get("BUSYBEE_TIMEOUT") or 90)
+        self._bal_cache: tuple[float, float] | None = None
+
+    # ------------------------------------------------------------ 基础请求
+    def _request(self, path: str, params: dict | None = None, method: str = "GET",
+                 body: dict | None = None, auth: bool = True) -> dict:
+        if auth and not self.api_key:
+            raise BusyBeeError(
+                "还没有配置 API Key。免费领取地址：%s" % SIGNUP_URL,
+                code="no_api_key",
+                hint="注册后到「控制台 → API 密钥 → 新建密钥」复制 sk- 开头的串，"
+                     "并在客户端里配置环境变量 BUSYBEE_API_KEY。",
+            )
+        url = self.base_url + path
+        if params:
+            clean = {k: v for k, v in params.items() if v not in (None, "")}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        data = None
+        headers = {"Accept": "application/json", "User-Agent": "busybee-mcp/0.1"}
+        if auth:
+            headers["Authorization"] = "Bearer " + str(self.api_key)
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers,
+                                     method="POST" if body is not None else method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                raw = r.read()
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            raise self._http_error(e.code, raw) from None
+        except urllib.error.URLError as e:
+            raise BusyBeeError(
+                "连不上服务（%s）。请检查网络后重试。" % getattr(e, "reason", e),
+                code="network_error") from None
+        try:
+            return json.loads(raw)
+        except ValueError:
+            raise BusyBeeError("服务返回了无法解析的内容，请稍后重试。", code="bad_response") from None
+
+    @staticmethod
+    def _http_error(status: int, raw: bytes) -> BusyBeeError:
+        msg, hint = None, None
+        try:
+            j = json.loads(raw)
+            err = j.get("error") if isinstance(j, dict) else None
+            if isinstance(err, dict):
+                msg, hint = err, (err.get("hint") or err.get("groups_cn"))
+            elif isinstance(j, dict):
+                msg = j.get("message") or j.get("detail")
+            if isinstance(msg, dict):
+                hint = hint or msg.get("hint")
+                msg = msg.get("message_zh") or msg.get("message") or msg.get("msg")
+            if msg is not None and not isinstance(msg, str):
+                msg = None
+        except ValueError:
+            pass
+        if status == 401:
+            return BusyBeeError(msg or "API Key 无效或未登录。", code="unauthorized",
+                                hint=hint or "确认 Key 是 sk- 开头且未删除；免费领取：%s" % SIGNUP_URL)
+        if status == 402:
+            return BusyBeeError(msg or "账户余额不足。", code="insufficient_balance",
+                                hint="到 %s 充值后重试。" % SIGNUP_URL)
+        if status == 403:
+            return BusyBeeError(msg or "当前 API Key 无权调用该平台。", code="forbidden", hint=hint)
+        if status == 429:
+            return BusyBeeError(msg or "请求太频繁，触发了限流。", code="rate_limited",
+                                hint="降低并发或稍后重试。")
+        if status >= 500:
+            return BusyBeeError(msg or "上游服务暂时不可用（%d）。" % status, code="upstream_error",
+                                hint="这通常是临时故障，重试一次通常可恢复。")
+        return BusyBeeError(msg or "请求失败（HTTP %d）。" % status, code="http_%d" % status, hint=hint)
+
+    # ------------------------------------------------------------ 业务封装
+    def call_endpoint(self, path: str, params: dict | None = None, method: str = "GET",
+                      body: dict | None = None) -> dict:
+        return self._request(path, params=params, method=method, body=body)
+
+    def me(self) -> dict:
+        """账户概览：用户名、余额、分组。"""
+        j = self._request("/api/gw/me")
+        return j.get("data", j) if isinstance(j, dict) else {}
+
+    def balance_usd(self, fresh: bool = False) -> float | None:
+        now = time.time()
+        if not fresh and self._bal_cache and now - self._bal_cache[0] < 30:
+            return self._bal_cache[1]
+        try:
+            data = self.me()
+        except BusyBeeError:
+            return None
+        bal = data.get("quota_exact_usd")
+        if bal is None:
+            bal = data.get("quota_usd")
+        if isinstance(bal, (int, float)):
+            self._bal_cache = (now, float(bal))
+            return float(bal)
+        return None
+
+    def pricing(self) -> dict:
+        return self._request("/api/gw/pricing")