内容
# 状态专业版 — API 客户端生态系统
用于 [StatusPro API](https://app.orderstatuspro.com/api/v1) 的多语言客户端生态系统，这是一个用于**读取和更新订单状态**的小型 REST API。StatusPro API 被商家用于向其客户公开生产进度（订单已收到 → 生产中 → 已发货等），并从其自身系统更新该状态。
此 monorepo 包含：
- 一个具有传输层重试、速率限制感知和跨所有列表端点自动分页的生产级 Python 客户端。
- 从同一 OpenAPI 规范生成的 TypeScript 客户端。
- 一个 MCP 服务器，将 StatusPro 操作作为 Claude Desktop 等 AI 助手的工具公开。
[](https://www.python.org/downloads/)
[](https://www.typescriptlang.org/)
[](https://spec.openapis.org/oas/v3.1.0)
## 软件包
| 软件包 | 语言 | 版本 | 描述 |
| -------------------------------------------------------- | ------ | ----- | --------------------------------------------- |
| [statuspro-openapi-client](statuspro_public_api_client/) | Python | 0.1.0 | 具有传输层恢复能力的 API 客户端 |
| [statuspro-mcp-server](statuspro_mcp_server/) | Python | 0.1.0 | 用于 AI 助手的模型上下文协议服务器 |
| [statuspro-client](packages/statuspro-client/) | TypeScript | 0.1.0 | 具有完全类型安全性的 TypeScript/JavaScript 客户端 |
## 功能
| 功能 | Python | TypeScript | MCP 服务器 |
| ------------------------------------------- | ------ | ---------- | ----------------------- |
| 自动重试（网络 + 5xx） | 是 | 是 | 是（通过 Python 客户端） |
| 速率限制重试，指数退避 | 是 | 是 | 是 |
| 自动分页（页面 + 每页，带元数据） | 是 | 是 | 是 |
| 变更的两步确认 | — | — | 是 |
| 完全类型安全性（属性 + Pydantic / TS） | 是 | 是 | 是 |
| AI 工具表面 | — | — | Claude, Cursor 等 |
## 快速入门
### Python 客户端
```bash
pip install statuspro-openapi-client
```
```python
import asyncio
from statuspro_public_api_client import StatusProClient
async def main():
async with StatusProClient() as client:
orders = await client.orders.list(per_page=25)
for order in orders:
status = order.status.name if order.status else "(no status)"
print(f"{order.name}: {status}")
asyncio.run(main())
```
### TypeScript 客户端
```bash
npm install statuspro-client
```
```typescript
import { StatusProClient } from "statuspro-client";
const client = await StatusProClient.create();
const response = await client.get("/orders");
const { data, meta } = await response.json();
console.log(`Found ${meta.total} orders (page ${meta.current_page}/${meta.last_page})`);
```
### MCP 服务器（Claude Desktop）
```bash
pip install statuspro-mcp-server
```
将以下内容添加到 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"statuspro": {
"command": "uvx",
"args": ["statuspro-mcp-server"],
"env": {
"STATUSPRO_API_KEY": "your-api-key-here"
}
}
}
}
```
## 配置
所有软件包都通过 bearer token 进行身份验证：
1. **环境变量**：`STATUSPRO_API_KEY`
2. **`.env` 文件**：`STATUSPRO_API_KEY=your-key`
3. **直接参数**：将 `api_key=...` 传递给客户端构造函数
4. **`~/.netrc`**：`machine app.orderstatuspro.com` + `password your-key`
```bash
# .env
STATUSPRO_API_KEY=your-api-key-here
STATUSPRO_BASE_URL=https://app.orderstatuspro.com/api/v1 # 可选覆盖
```
## API 覆盖范围
StatusPro API 故意设计得小且专注于订单状态。所有 7 个端点都已覆盖：
| 标签 | 方法 | 路径 | 目的 |
| -------- | ------ | ------------------------------ | -------------------------------------------------------------- |
| 订单 | GET | `/orders` | 带过滤器的分页列表（搜索、状态、标签、到期日期）。 |
| 订单 | GET | `/orders/{id}` | 包括历史记录的单个订单的完整详细信息。 |
| 订单 | GET | `/orders/lookup` | 通过订单编号和客户电子邮件查找订单。 |
| 订单 | GET | `/orders/{id}/viable-statuses` | 从当前状态有效的状态转换。 |
| 订单 | POST | `/orders/{id}/status` | 更改单个订单的状态。 |
| 订单 | POST | `/orders/{id}/comment` | 添加历史记录注释（5 分钟速率限制）。 |
| 订单 | POST | `/orders/{id}/due-date` | 设置或更新到期日期（单一日期或范围）。 |
| 订单 | POST | `/orders/bulk-status` | 一次更新最多 50 个订单（5 分钟，异步排队）。 |
| 状态 | GET | `/statuses` | 帐户上定义的每个状态（代码、名称、颜色）。 |
**约定：**
- 每个端点使用 bearer token 身份验证（`Authorization: Bearer <STATUSPRO_API_KEY>`）。
- `GET /orders` 返回 `{"data": [...], "meta": {current_page, last_page, per_page, total, from, to}}`。
- `GET /statuses` 和 `GET /orders/{id}/viable-statuses` 返回原始 JSON 数组。
- 分页使用 `page` + `per_page` 查询参数（`per_page` 最多 100）。
- 速率限制按端点记录（大多数为 60 分钟，`/comment` 和 `/bulk-status` 为 5 分钟），但不在响应头中显示。
## MCP 工具
`statuspro-mcp-server` 软件包将每个端点映射到一个工具。变更使用两步确认模式：调用 `confirm=false` 进行预览，然后调用 `confirm=true` 应用（客户端引发明确的用户批准）。
| 工具 | 是否为变更 | 描述 |
| -------------------------- | --------- | ----------------------------------------- |
| `list_orders` | 否 | 过滤 + 分页订单 |
| `get_order` | 否 | 单个订单的完整详细信息 |
| `lookup_order` | 否 | 通过订单编号 + 客户电子邮件查找订单 |
| `list_statuses` | 否 | 完整状态目录 |
| `get_viable_statuses` | 否 | 订单的有效状态转换 |
| `update_order_status` | 是 | 更改单个订单的状态 |
| `add_order_comment` | 是 | 添加历史记录注释 |
| `update_order_due_date` | 是 | 设置或更改到期日期 |
| `bulk_update_order_status` | 是 | 一次更改最多 50 个订单的状态 |
另外还有两个资源：
- `statuspro://statuses` — 每个状态的 JSON 列表（缓存读取）。
- `statuspro://help` — 工具参考和推荐的工作流程。
## 恢复能力（Python 客户端）
每个端点都自动继承这些传输层行为 — 不需要装饰器或包装器：
- **重试**：`httpx-retries` 在 502/503/504 和任意方法上对 429 进行幂等重试。可通过 `max_retries` 配置。
- **速率限制感知**：在存在 `Retry-After` 头部时遵循该头部；否则使用指数退避。
- **自动分页**：`GET /orders` 使用 `meta.last_page` 作为停止条件，遍历到完成，最高可达 `max_pages`（默认为 100）或显式 `max_items` 覆盖。原始数组端点（`/statuses`，`/viable-statuses`）永远不会分页。
- **敏感数据删除**：授权头部和公共秘密字段名称（`api_key`，`password`，`email` 等）从日志输出中清除。
## 项目结构
```text
statuspro-openapi-client/ # Monorepo 根目录
├── pyproject.toml # 工作区配置（uv）
├── uv.lock # Python 锁定文件
├── pnpm-workspace.yaml # TypeScript 工作区
├── docs/
│ ├── statuspro-openapi.yaml # OpenAPI 3.1.0 规范（真实来源）
│ └── *.md # 共享文档
├── statuspro_public_api_client/ # Python 客户端
│ ├── statuspro_client.py # 弹性客户端 + 传输层
│ ├── domain/ # 手动编写的 Pydantic 领域模型
│ ├── helpers/ # 人性化 facade（client.orders，.statuses）
│ ├── utils.py # unwrap/unwrap_as/unwrap_data + 错误类型
│ ├── api/, models/ # 从 OpenAPI 规范生成
│ └── docs/ # 软件包文档
├── statuspro_mcp_server/ # MCP 服务器
│ └── src/statuspro_mcp/
│ ├── server.py # FastMCP 服务器
│ ├── tools/ # 9 个工具（订单 + 状态）
│ └── resources/ # 帮助 + 状态资源
└── packages/
└── statuspro-client/ # TypeScript 客户端
├── src/
│ └── generated/ # 从同一规范生成
└── openapi-ts.config.ts
```
## 开发
### 先决条件
- **Python 3.12+** 用于 Python 软件包
- **Node.js 18+** 用于 TypeScript 软件包
- **uv** ([安装](https://docs.astral.sh/uv/getting-started/installation/))
- **pnpm** ([安装](https://pnpm.io/installation))
### 设置
```bash
git clone https://github.com/dougborg/statuspro-openapi-client.git
cd statuspro-openapi-client
uv sync --all-extras # 安装 Python 依赖项
uv run pre-commit install # 安装 git 钩子
pnpm install # 安装 TypeScript 依赖项
cp .env.example .env # 添加 STATUSPRO_API_KEY
```
### 常用命令
```bash
uv run poe quick-check # 快速：格式化 + lint
uv run poe check # 完整：格式化 + lint + 类型检查 + 测试
uv run poe test # 仅测试（pytest -n 4）
uv run poe regenerate-client # 从 docs/statuspro-openapi.yaml 重新生成 Python 客户端
uv run poe generate-pydantic # 重新生成 Pydantic v2 模型
pnpm --filter statuspro-client generate # 重新生成 TypeScript 客户端
```
### 提交标准
约定提交驱动每个软件包的语义发布版本控制：
```bash
git commit -m "feat(client): add helper for archived orders"
git commit -m "fix(client): handle empty viable-status responses"
git commit -m "feat(mcp): add tool for lookup by date range"
git commit -m "feat(ts): export pagination helpers"
git commit -m "docs: update quick-start"
```
对破坏性更改使用 `!`：`feat(client)!: drop Python 3.11 support`。
详见 [MONOREPO_SEMANTIC_RELEASE.md](docs/MONOREPO_SEMANTIC_RELEASE.md)。
## 许可证
MIT 许可证 — 参见 [LICENSE](LICENSE)。
## 贡献
欢迎贡献。参见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 获取指南。
