# API 参考

完整的 Hezor2 SDK API 文档。

## 导出总览

`hezor_common.transfer.hezor2_sdk` 公开导出如下对象：

- `Hezor2SDK`
- `MetaInfo`
- `Hezor2APIClient`
- `Hezor2EnvConfig`
- `load_env`
- `CreationGenerateResult`
- `WebhookRequest`
- `WebhookResponse`
- `GenerateReportIdPayload`
- `GenerateReportIdResponseData`
- `GetReportStatusPayload`
- `PublishCreationPayload`
- `PublishCreationResponseData`
- `ReportMetadata`

## Hezor2SDK 类

### 构造函数

```python
Hezor2SDK(
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = 120.0,
    api_key: str | None = DEFAULT_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600
)
```

#### 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `base_url` | `str` | 环境变量 (`HEZOR2_API_BASE_URL`) | Hezor2 API 基础 URL |
| `timeout` | `float` | `120.0` | 请求超时时间（秒） |
| `api_key` | `str \| None` | 环境变量 (`HEZOR2_API_KEY`) | API 密钥（Bearer Token） |
| `meta_info` | `MetaInfo \| None` | `None` | 元信息对象（用于签名相关请求头） |
| `private_key_path` | `str \| Path \| None` | `None` | 私钥文件路径 |
| `password` | `bytes \| None` | `None` | 私钥密码 |
| `meta_info_expires_in` | `int` | `3600` | MetaInfo JWT 过期时间（秒） |

#### 示例

```python
from hezor_common.transfer.hezor2_sdk import Hezor2SDK

async with Hezor2SDK(api_key="your-api-key") as sdk:
    is_healthy, health = await sdk.health_check()
    print(is_healthy, health)
```

---

### publish_creation_report()

发布创作报告到 Hezor2。

```python
async def publish_creation_report(
    creation_result: CreationGenerateResult,
    task_id: str,
    execution_id: str,
) -> CreationWebhookResponse
```

#### 参数

- **creation_result** (`CreationGenerateResult`) - 生成的创作结果
    - 推荐导入：`from hezor_common.transfer.hezor2_sdk import CreationGenerateResult`
    - 实际来源：`hezor_common.data_model.creations.core.creation_generate_result`
- **task_id** (`str`) - 任务 ID（可重复，表示任务类型）
- **execution_id** (`str`) - 执行 ID（唯一，表示一次具体执行）

#### 返回

`CreationWebhookResponse` - Webhook 响应结果

- 推荐导入：`from hezor_common.transfer.hezor2_sdk import CreationWebhookResponse`
- 实际来源：`hezor_common.data_model.creations.execution.webhook`

#### 异常

- `httpx.HTTPError` - HTTP 请求失败

#### 示例

```python
response = await sdk.publish_creation_report(
    creation_result=result,
    task_id="monthly_report",
    execution_id="exec_2026_01_27_001",
)
print(response.status)
```

---

### health_check()

执行服务健康检查。

```python
async def health_check() -> tuple[bool, dict]
```

#### 返回

`tuple[bool, dict]`

- 第一项：是否健康（`status == "healthy"`）
- 第二项：原始响应数据

#### 行为说明

- 当底层请求成功时，返回真实健康状态。
- 当发生 `httpx.HTTPError` 时，`Hezor2SDK.health_check()` 会捕获异常并返回：
  - `False`
  - `{"error": "HTTP request failed"}`

#### 示例

```python
is_healthy, health_data = await sdk.health_check()
if is_healthy:
    print("Service is healthy")
else:
    print(health_data)
```

---

## Hezor2APIClient 类

底层 API 客户端，继承自 `BaseAPIClient`，适合需要细粒度控制的场景。

### 构造函数

```python
Hezor2APIClient(
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = 120.0,
    api_key: str | None = DEFAULT_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600
)
```

参数语义与 `Hezor2SDK` 一致。

### publish_creation_report()

```python
async def publish_creation_report(
    payload: CreationGenerateResult,
    task_id: str,
    execution_id: str,
) -> CreationWebhookResponse
```

#### 请求端点

- `POST /creations/webhook`

#### 说明

- `payload` 使用模型 `CreationGenerateResult`
    - 推荐导入：`from hezor_common.transfer.hezor2_sdk import CreationGenerateResult`
    - 实际来源：`hezor_common.data_model.creations.core.creation_generate_result`
- 返回模型为 `CreationWebhookResponse`
    - 推荐导入：`from hezor_common.transfer.hezor2_sdk import CreationWebhookResponse`
    - 实际来源：`hezor_common.data_model.creations.execution.webhook`
- 内部会自动构造 `CreationWebhookRequest`：
    - 推荐导入：`from hezor_common.transfer.hezor2_sdk import CreationWebhookRequest`
    - 实际来源：`hezor_common.data_model.creations.execution.webhook`
  - `action = "publish_creation_report"`
  - `payload = payload`
  - `task_id = task_id`
  - `execution_id = execution_id`

### health_check()

```python
async def health_check() -> tuple[bool, dict]
```

#### 请求端点

- `GET /health`

#### 返回判定

- 当响应 JSON 中 `status == "healthy"` 时，返回 `True`

---

## 环境配置

### Hezor2EnvConfig

基于 `pydantic-settings` 的配置模型，支持从环境变量读取。

#### 字段

| 字段 | 类型 | 默认值 | 环境变量（不区分大小写） |
|------|------|--------|--------------------------|
| `hezor2_api_base_url` | `str` | `"http://localhost:8000"` | `HEZOR2_API_BASE_URL` |
| `hezor2_api_key` | `str` | `"test-api-key"` | `HEZOR2_API_KEY` |
| `hezor2_header_pk_filepath` | `str` | `""` | `HEZOR2_HEADER_PK_FILEPATH` |
| `hezor2_header_pk_password` | `str` | `""` | `HEZOR2_HEADER_PK_PASSWORD` |

### load_env()

```python
def load_env(env_file: str | Path | None = None) -> Hezor2EnvConfig
```

#### 行为

- `env_file is None`：仅从环境变量读取。
- 指定 `env_file`：额外从指定 `.env` 文件读取配置。

---

## 常量

`hezor_common.transfer.hezor2_sdk.base.constants` 暴露：

- `DEFAULT_API_BASE_URL`
- `DEFAULT_API_KEY`
- `DEFAULT_HEADER_PK_FILEPATH`
- `DEFAULT_HEADER_PK_PASSWORD`
