Metadata-Version: 2.3
Name: feishu-bot-sdk
Version: 0.1.0
Summary: Reusable SDK for Feishu bot messaging, Bitable, Docx, and Drive permissions.
Author: Anderson
Author-email: Anderson <andersonby@163.com>
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# feishu-bot-sdk

面向飞书机器人的轻量 Python SDK，提供：

- 飞书 tenant token 获取与缓存
- 机器人文本消息发送
- Drive 权限授予（Bitable / Docx）
- CSV 导入多维表格（Bitable）
- Markdown 追加写入 Docx
- 同步 / 异步两套 API

## 安装

```bash
# pip
pip install feishu-bot-sdk

# uv
uv add feishu-bot-sdk
```

## 1 分钟上手（同步）

```python
from feishu_bot_sdk import FeishuClient, FeishuConfig, BitableService, DocxService

config = FeishuConfig(
    app_id="cli_xxx",
    app_secret="xxx",
    base_url="https://open.feishu.cn/open-apis",
    doc_url_prefix="https://your-tenant.feishu.cn/docx",
    doc_folder_token="fldcnxxx",   # 可选
    member_permission="edit",      # view/edit/full_access
)

client = FeishuClient(config)

# 1) 发消息
client.send_text_message("ou_xxx", "open_id", "你好，来自 SDK")

# 2) CSV -> Bitable
bitable = BitableService(client)
app_token, app_url = bitable.create_from_csv("final.csv", "任务结果", "结果表")
bitable.grant_edit_permission(app_token, "ou_xxx", "open_id")
print(app_url)

# 3) Markdown -> Docx
docx = DocxService(client)
doc_id, doc_url = docx.create_document("任务报告")
docx.append_markdown(doc_id, "# 标题\n\n这是正文。")
docx.grant_edit_permission(doc_id, "ou_xxx", "open_id")
print(doc_url or doc_id)
```

## 异步用法

```python
from feishu_bot_sdk import AsyncFeishuClient, AsyncBitableService, FeishuConfig

config = FeishuConfig(app_id="cli_xxx", app_secret="xxx")
client = AsyncFeishuClient(config)
bitable = AsyncBitableService(client)

await client.send_text_message("ou_xxx", "open_id", "hello async")
app_token, app_url = await bitable.create_from_csv("final.csv", "异步结果", "Sheet1")

await client.aclose()
```

## 核心对象

- `FeishuClient` / `AsyncFeishuClient`：飞书 API 基础客户端
- `BitableService` / `AsyncBitableService`：多维表格能力
- `DocxService` / `AsyncDocxService`：文档能力
- `DrivePermissionService` / `AsyncDrivePermissionService`：权限授予

英文说明见 `README_EN.md`。

## 示例脚本

```bash
uv run python examples/sync_demo.py --receive-id ou_xxx --receive-id-type open_id
uv run python examples/async_demo.py --receive-id ou_xxx --receive-id-type open_id
```

可选参数：

- `--csv final.csv`：演示 CSV 导入 Bitable
- `--markdown result.md`：演示 Markdown 追加到 Docx
