Metadata-Version: 2.5
Name: jira-ticket-client
Version: 0.1.0
Summary: Create Jira Cloud issues and upload attachments with an API token.
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Description-Content-Type: text/markdown

# jira-ticket-client

用 API Token 在现有 Jira Cloud 项目里创建工单并上传附件。调用方传入站点、Cloud ID、项目和 Token，这个包不读取环境变量，也不提供页面。

Token 只应放在服务端进程里。浏览器不要持有它。

## 安装

```bash
uv add jira-ticket-client
```

或：

```bash
pip install jira-ticket-client
```

源码和界面包 `jira-reporter` 放在同一层目录。其他项目用上面的命令从 PyPI 安装。API Token 仍由使用方的环境变量传入。

## 配置

下面这些值都要有，缺一项或格式不对时 `parse_jira_client_config` 返回 `None`，调用方应关闭上报入口。

| 参数 | 内容 |
| --- | --- |
| `site_url` | 站点 origin，必须是 `https`，例如 `https://brain-ai.atlassian.net` |
| `cloud_id` | 该站点的 Cloud ID |
| `user_email` | 创建 API Token 的 Atlassian 账号邮箱 |
| `api_token` | 该账号在 [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens) 生成的 API token |
| `project_key` | 已有项目，例如 `SBSA` |
| `issue_type_id` | 问题类型的数字 ID，例如 `12024` |
| `issue_label` | 工单标签，默认 `lingora` |

工单报告人是 Token 所属账号。`actor_name` 和 `actor_id` 只写进描述。

## 调用

```python
from jira_ticket_client import JiraIssueDraft, JiraTicketClient, parse_jira_client_config

config = parse_jira_client_config(
    site_url="https://brain-ai.atlassian.net",
    cloud_id="803fa87e-2a37-42e2-a070-b41b78962b9b",
    user_email="reporter@example.com",
    api_token="放在服务端环境变量里的 token",
    project_key="SBSA",
    issue_type_id="12024",
    issue_label="lingora",
)
if config is None:
    raise SystemExit("Jira is not configured")

client = JiraTicketClient(config)
try:
    created = await client.create_issue(
        JiraIssueDraft(
            summary="按钮没有反应",
            description="点击保存后没有请求",
            page_url="https://app.example.com/projects",
            page_title="项目",
            captured_at=captured_at,
            viewport_width=1440,
            viewport_height=900,
            device_pixel_ratio=2,
            actor_name="管理员",
            actor_id="user-id",
            actor_label="Lingora user",
        )
    )
    await client.add_attachments(created.issue_key, [("shot.jpg", jpeg_bytes, "image/jpeg")])
finally:
    await client.aclose()
```

`create_issue` 返回 `issue_key` 和 `https://{站点}/browse/{issue_key}`。附件请求使用 `X-Atlassian-Token: no-check`。

失败时抛出 `JiraClientError`：

| `code` | 含义 |
| --- | --- |
| `rate_limited` | Jira 返回 429，`retry_after_seconds` 可能有值 |
| `invalid_issue_key` | 工单号不属于配置的项目 |
| `upstream` | 认证失败、Jira 拒绝、暂时不可用或响应无法识别 |

## 测试

在本目录：

```bash
uv run --with pytest pytest
```
