Metadata-Version: 2.5
Name: qingniao
Version: 0.2.0
Summary: 青鸟 SDK — 统一封装多个自建项目的对外 API 接口
Project-URL: Homepage, https://github.com/leookun/qingniao
Project-URL: Repository, https://github.com/leookun/qingniao
Author: darren
License: MIT
Keywords: 2fauth,accountbox,api-client,fusionmail,sdk,totp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# qingniao

青鸟 SDK — 统一封装多个自建项目的对外 API 接口。

## 安装

```bash
pip install qingniao
```

## 快速开始

### 方式一：统一门面（推荐）

```python
from qingniao import Qingniao

# 从环境变量自动配置
# export ACCOUNTBOX_API_KEY=your_key
# export FUSIONMAIL_API_KEY=your_key
qn = Qingniao()

# 访问各项目客户端
qn.accountbox.get_websites()
qn.fusionmail.receive_mail(email="user@example.com")
```

### 方式二：单独使用某个客户端

```python
from qingniao import AccountBoxClient, FusionMailClient, TwoFAuthClient

ab = AccountBoxClient(api_key="your_key", base_url="http://localhost:5095")
ab.get_websites()

fm = FusionMailClient(api_key="your_key", base_url="http://localhost:3333")
fm.receive_mail(email="user@example.com")

tf = TwoFAuthClient(api_key="your_pat", base_url="https://my-2fauth.app")
tf.create_from_qrcode("/path/to/code.png")
```

## 2FAuth 用法

```python
from qingniao import TwoFAuthClient

tf = TwoFAuthClient(api_key="your_pat", base_url="https://my-2fauth.app")

# 扫码创建 2FA 账号（不填 group_id 进入默认分组）
account = tf.create_from_qrcode("/path/to/code.png")
account = tf.create_from_qrcode("/path/to/code.png", group_id=1)

# 按邮箱获取验证码
otp = tf.get_otp_by_account("abc@outlook.com")
otp = tf.get_otp_by_account("abc@outlook.com", group_id=2)
print(otp.password)  # "654321"

# 分组管理
groups = tf.get_groups()
tf.create_group("Social")
tf.assign_to_group(group_id=1, account_ids=[5, 6, 7])
```

## 环境变量

| 变量 | 说明 |
|------|------|
| `ACCOUNTBOX_API_KEY` | AccountBox API 密钥 |
| `ACCOUNTBOX_BASE_URL` | AccountBox Base URL（可选，有默认值）|
| `FUSIONMAIL_API_KEY` | FusionMail API 密钥 |
| `FUSIONMAIL_BASE_URL` | FusionMail Base URL（可选，有默认值）|
| `2FAUTH_API_KEY` | 2FAuth Personal Access Token |
| `2FAUTH_BASE_URL` | 2FAuth Base URL（必填，自托管实例地址）|

## 新项目接入

接入一个新项目只需 4 步：

1. 创建 `src/qingniao/myproject/` 子包
2. 在 `client.py` 中继承 `BaseClient`，实现 `client_name`、`api_prefix`、`auth_header` 三个属性
3. 在 `models.py` 中用 Pydantic v2 定义响应模型
4. 在 `__init__.py` 中用 `@register_client("myproject")` 注册

无需修改任何公共代码。

## License

MIT