Metadata-Version: 2.4
Name: PlanetLink
Version: 0.1.0
Summary: Python library to send messages to WeCom (企业微信) applications.
Home-page: https://github.com/vu1nex/PlanetLink
Author: vu1nex
Author-email: me@vu1nex.com
Keywords: wx,wechat,bot,message,reminder,wecom
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PlanetLink

[![PyPI - Version](https://img.shields.io/pypi/v/planetlink?color=blue)](https://pypi.org/project/planetlink/)
[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/planetlink)](https://pypi.org/project/planetlink/)
[![PyPI - License](https://img.shields.io/pypi/l/planetlink)](LICENSE)

一个用于向**企业微信（WeCom）应用**群发消息的 Python 库，附带轻量的消息构建器。

- 🚀 三行代码完成推送：`WxBot(...).send_text("hello")`
- 🧱 内置 `MessageBuilder`，支持多行/结构化消息与链式调用
- 🔄 access_token 自动获取与缓存（临近过期自动刷新）
- 🛡 失败抛出 `WxBotError`，不再静默吞错
- 🔌 兼容旧版 `wxBot` / `wxMessage` API

## 安装

要求 Python ≥ 3.10：

```bash
pip install planetlink
```

## 快速开始

```python
from PlanetLink import WxBot

bot = WxBot(corpid="wwxxxxxxxx", corpsecret="xxxxxxxx", agentid="1000002")

# 最简单用法：直接发字符串（原样发送，零格式）
bot.send_text("部署完成")

# 带标题与级别（自动附加 emoji 与时间戳）
bot.send_text("构建成功 ✅", title="CI 通知", sign="COMPLETE")
```

## 配置

需要企业微信「应用」的以下三个值（可在企业微信管理后台 → 应用管理 获取）：

| 参数 | 说明 |
| :--- | :--- |
| `corpid` | 企业 ID（形如 `ww...`） |
| `corpsecret` | 应用的 Secret |
| `agentid` | 应用 ID（数字） |

### 环境变量方式

```bash
export WX_CORPID=wwxxxxxxxx
export WX_CORPSECRET=xxxxxxxx
export WX_AGENTID=1000002
```

```python
import os
from PlanetLink import WxBot

bot = WxBot(
    corpid=os.environ["WX_CORPID"],
    corpsecret=os.environ["WX_CORPSECRET"],
    agentid=os.environ["WX_AGENTID"],
)
```

## 发送消息

### 1. 直接发送字符串

```python
bot.send_text("部署完成")
```

### 2. 多行 / 结构化消息（MessageBuilder）

```python
from PlanetLink import MessageBuilder

msg = MessageBuilder(title="每日汇总", sign="INFO")
msg.add_content("今日入账: ¥12,800")            # 追加单行
msg.add_content(["转化率: 3.2%", "异常单: 0"])   # 追加多行

bot.send_text(msg)
```

`MessageBuilder` 支持链式调用与清空：

```python
MessageBuilder(title="提醒", sign="WARNING") \
    .add_content("line1") \
    .add_content(["line2", "line3"])
```

### 3. 控制接收人

默认发送给 `@all`，可通过 `touser` / `toparty` / `totag` 指定：

```python
bot.send_text("会议室预约提醒", touser="zhangsan|lisi")
```

### 4. 发送结果与异常

`send_text` 成功返回企业微信接口的 JSON（`errcode=0`）；失败抛出 `WxBotError`：

```python
from PlanetLink import WxBotError

try:
    bot.send_text("重要通知", title="告警", sign="ERROR")
except WxBotError as e:
    print("发送失败:", e)
```

## MessageBuilder 细节

### Sign 与 emoji 对照

| sign | emoji | 备注 |
| :---: | :---: | :--- |
| `INFO` | ℹ️ | 默认 |
| `WARNING` | ⚠️ | |
| `ERROR` | ❌ | |
| `COMPLETE` | ✅ | |
| 其他 | ⛔ | |

### 消息格式示例

```
✅ 打新提醒
[2026-08-21 10:00:00]
====================
今日共有 2 只申购
--------------------
```

### 分隔线宽度

`MessageBuilder` 默认使用 **20 字符** 的等宽符号分隔线，保证在窄终端（如手机端企业微信）**不会折行**。

对于固定场景的程序，**推荐在初始化 `WxBot` 时统一配置**（之后所有发送自动生效，无需每次重复）：

```python
bot = WxBot(
    corpid="ww...", corpsecret="...", agentid="1000002",
    delimiter_char="*", delimiter_count=10,          # 内容分隔线：**********
    title_delimiter_char="#", title_delimiter_count=6,  # 标题分隔线：######
)
```

也支持只给数量（沿用默认字符 `-` / `=`），或完整串 `delimiter="***"`：

```python
WxBot(..., delimiter_count=10, title_delimiter_count=6)          # 默认字符
WxBot(..., delimiter="***", title_delimiter="###")               # 完整串
```

> 说明（同 `MessageBuilder`）：
> - 只给 `delimiter_count` 而省略 `delimiter_char` 时，使用默认字符（`-` / `=`）
> - `delimiter_count=0` 可关闭对应分隔线
> - 显式传入的 `MessageBuilder` 实例不受 bot 级配置影响，以其自身设置为准

## 兼容旧 API

旧写法（`wxBot` / `wxMessage` 类名与 `initBot` / `addContent` 等）仍可用，但更推荐新 API：

```python
# 旧写法（可用，不推荐）
from PlanetLink.wxBot import wxBot
bot = wxBot()
bot.initBot("corpid", "corpsecret", "1000002", "title", "INFO")
bot.addContent("hello")
bot.send()
```

```python
# 新写法（推荐）
from PlanetLink import WxBot
bot = WxBot("corpid", "corpsecret", "1000002")
bot.send_text("hello", title="title", sign="INFO")
```

## Changelog

- `0.1.0`：重构 API（`WxBot` / `MessageBuilder`）；token 自动缓存；失败抛 `WxBotError`；分隔线缩短至 20 字符防折行
- `0.0.2`：新增 `clearContent` / `getSendMessage`
- `0.0.1`：首个版本

## License

[MIT](LICENSE)
