pynotifyhub 0.1.0__tar.gz

pynotifyhub-0.1.0/.claude/settings.local.json

@@ -0,0 +1,37 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/ubuntu/workspace/tmp/btcdom_arb status -sb)",
+      "Bash(git -C /home/ubuntu/workspace/tmp/btcdom_arb log --oneline -1)",
+      "Bash(pip3 install *)",
+      "Bash(python3 -m pytest -q)",
+      "Bash(NH_DISCORD_URL=\"https://discord.com/api/webhooks/1490400357577392239/eI3NisN0oG5G5QNPVj9kxOQp114vtPv17BKyUDJ8BVFZGyyNhtYHwwaUUJMC0EVLPuoV\" NH_SLACK_URL=\"https://hooks.slack.com/services/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\" NH_LARK_URL=\"https://open.larksuite.com/open-apis/bot/v2/hook/de57d6a6-d8bb-4335-a700-bfd674682175\" python3 /tmp/nh_smoke.py)",
+      "Bash(NH_LARK_URL=\"https://open.larksuite.com/open-apis/bot/v2/hook/de57d6a6-d8bb-4335-a700-bfd674682175\" python3 *)",
+      "Bash(DISCORD_WEBHOOK_URL=\"https://discord.com/api/webhooks/1490400357577392239/eI3NisN0oG5G5QNPVj9kxOQp114vtPv17BKyUDJ8BVFZGyyNhtYHwwaUUJMC0EVLPuoV\" SLACK_WEBHOOK_URL=\"https://hooks.slack.com/services/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\" LARK_WEBHOOK_URL=\"https://open.larksuite.com/open-apis/bot/v2/hook/de57d6a6-d8bb-4335-a700-bfd674682175\" python3 app.py)",
+      "Bash(python3 -)",
+      "Bash(git add *)",
+      "Bash(git commit -q -m 'Add Chinese usage guide with 30-second quickstart in docs/ *)",
+      "Bash(git push *)",
+      "Bash(gh auth *)",
+      "Bash(ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -T git@github.com)",
+      "Bash(ssh -o BatchMode=yes -i ~/.ssh/id_ed25519_allen -T git@github.com)",
+      "Bash(git config *)",
+      "Bash(git remote *)",
+      "Bash(sed -i 's|^DISCORD_WEBHOOK_URL=$|DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1490400357577392239/eI3NisN0oG5G5QNPVj9kxOQp114vtPv17BKyUDJ8BVFZGyyNhtYHwwaUUJMC0EVLPuoV|; s|^SLACK_WEBHOOK_URL=$|SLACK_WEBHOOK_URL=https://hooks.slack.com/services/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|; s|^LARK_WEBHOOK_URL=.*实际值.*|LARK_WEBHOOK_URL=|; s|^LARK_WEBHOOK_URL=$|LARK_WEBHOOK_URL=https://open.larksuite.com/open-apis/bot/v2/hook/de57d6a6-d8bb-4335-a700-bfd674682175|' .env)",
+      "Bash(git check-ignore *)",
+      "Bash(set -o pipefail)",
+      "Bash(python3 -m ruff format .)",
+      "Bash(python3 -m ruff check --fix .)",
+      "Bash(python3 -m mypy)",
+      "Bash(python3 -m ruff check .)",
+      "Bash(git commit -q -m 'Fix pre-release review findings: client leak, close race, secret redaction *)",
+      "Bash(sed -n '210,225p' docs/usage.md)",
+      "Bash(sed -n '314,320p' docs/usage.md)",
+      "Bash(git commit -q -m 'Add Lark image support via app credentials; accept WeCom webhook URL forms *)",
+      "Bash(python3 -m build)",
+      "Bash(python3 -m twine check dist/*)",
+      "Bash(python3 -m twine upload dist/*)",
+      "Bash(python3 -m twine upload --verbose dist/notify_hub-0.1.0-py3-none-any.whl)"
+    ]
+  }
+}

pynotifyhub-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# notify-hub 本地验证用的凭据模板。
+# 用法：cp .env.example .env，然后在 .env 里填真实值。
+# .env 已在 .gitignore 中，永远不会被提交。
+# 不用的渠道留空即可。
+
+# ── Discord ───────────────────────────────────────────────
+DISCORD_WEBHOOK_URL=
+
+# ── Slack ─────────────────────────────────────────────────
+SLACK_WEBHOOK_URL=
+SLACK_BOT_TOKEN=            # xoxb- 开头；配了才能测本地图片/文件上传
+SLACK_FILE_CHANNEL=         # 文件上传目标频道 ID，如 C0123456789
+
+# ── Telegram ──────────────────────────────────────────────
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# ── 企业微信 WeCom ────────────────────────────────────────
+WECOM_ROBOT_KEY=            # webhook 地址里 key= 后面那串
+
+# ── 钉钉 DingTalk ─────────────────────────────────────────
+DINGTALK_TOKEN=             # webhook 地址里 access_token= 后面那串
+DINGTALK_SECRET=            # 安全设置「加签」的 SEC 开头密钥
+
+# ── 飞书 / Lark ───────────────────────────────────────────
+LARK_WEBHOOK_URL=           # 完整 webhook URL
+LARK_SECRET=                # 可选：签名校验密钥
+LARK_APP_ID=                # 自建应用凭据；配了才能发图片
+LARK_APP_SECRET=
+
+# ── 电话 Twilio ───────────────────────────────────────────
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+TWILIO_FROM_NUMBER=         # 你的 Twilio 号码，如 +15550001111
+TWILIO_TO_NUMBER=           # 接听测试电话的手机号

pynotifyhub-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

pynotifyhub-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# notify-hub runtime artifacts
+notify-hub.log
+*.jsonl
+
+# Secrets — NEVER commit
+.env
+.env.local
+*.secret
+
+# OS
+.DS_Store

pynotifyhub-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-12
+
+### Added
+
+- Initial release: unified notification hub with level-based routing.
+- Channels: Slack, Discord, Telegram, WeCom (企业微信), DingTalk (钉钉),
+  Lark/Feishu (飞书), and voice calls via Twilio.
+- Async non-blocking `notify()` that works in both sync and asyncio host apps.
+- Attachment support (image/file from path, bytes, or URL) with per-channel
+  capability declarations and graceful degradation.
+- Structured notification log (text / JSON Lines, file or stdlib logger).
+- Anti-storm protection: fingerprint dedup window and per-channel rate limiting.
+- TOML / dict configuration with `${ENV_VAR}` secret expansion.
+- Lark image sending via optional `app_id`/`app_secret` (tenant token with
+  caching, image upload, image_key message).
+- WeCom accepts a bare key, the full webhook URL, or any `key=` fragment.
+- Credential redaction: tokens embedded in URLs are masked before error
+  strings reach results and the audit log.

pynotifyhub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allen-zjx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pynotifyhub-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: pynotifyhub
+Version: 0.1.0
+Summary: Unified multi-channel notification library: Slack, Discord, Telegram, WeCom, DingTalk, Lark/Feishu, and voice calls with level-based routing.
+Project-URL: Homepage, https://github.com/Allen-zjx/notify-hub
+Project-URL: Repository, https://github.com/Allen-zjx/notify-hub
+Project-URL: Changelog, https://github.com/Allen-zjx/notify-hub/blob/main/CHANGELOG.md
+Author: Allen-zjx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alert,dingtalk,discord,feishu,lark,notification,slack,telegram,twilio,wecom
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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 :: Communications
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# notify-hub
+
+Unified multi-channel notification library for Python.
+
+Send alerts to **Slack, Discord, Telegram, WeCom (企业微信), DingTalk (钉钉),
+Lark/Feishu (飞书), and phone voice calls (Twilio)** through one API, with
+level-based routing configured per application — so you never write
+notification glue code again.
+
+```python
+from notify_hub import Hub
+
+hub = Hub.from_config("notify-hub.toml")
+hub.notify("database is down", level="CRITICAL")   # returns in microseconds
+```
+
+What that one call does is decided entirely by config: which channels fire
+for which level, how attachments degrade per channel, retries, dedup,
+rate limits, and where the audit log goes.
+
+> 📖 **中文使用说明（30 秒跑通 + 全渠道接入指南）：[docs/usage.md](docs/usage.md)**
+
+## Features
+
+- **7 channels, one interface** — Slack, Discord, Telegram, WeCom, DingTalk,
+  Lark/Feishu, phone voice calls (Twilio, pluggable for other providers).
+- **Level-based routing** — builtin `DEBUG..CRITICAL` plus your own custom
+  levels (`TRADE_HALT = 45`); each app maps levels to channels in config,
+  matching rules are unioned.
+- **Never blocks your app** — `notify()` returns immediately in both sync
+  and asyncio hosts; fan-out runs concurrently on a lazily-started
+  background event loop. Await the handle (async) or `wait()` on it (sync)
+  only when you need the outcome.
+- **Failure isolation & retries** — one channel failing never affects the
+  others and never raises into your code; transient errors (429/5xx,
+  network) retry with exponential backoff + jitter.
+- **Attachments with graceful degradation** — images/files from a path,
+  bytes, or URL; channels declare capabilities and unsupported content is
+  dropped / linked / failed per your policy (phone calls read text via TTS).
+- **Anti-storm guards** — fingerprint dedup window (default 60 s) and
+  per-channel token-bucket rate limits, so a crash loop can't ring your
+  phone 1000 times.
+- **Audit log** — every send attempt recorded (per-channel status, attempts,
+  latency, errors) as JSON Lines or text, to a file and/or your own
+  `logging.Logger`.
+- **A well-behaved library** — stdlib dataclasses, one hard dependency
+  (`httpx`), zero threads until first use, nothing written or configured
+  unless you ask.
+
+## Installation
+
+```bash
+pip install pynotifyhub
+```
+
+Requires Python 3.10+. The distribution is named `pynotifyhub` (PyPI rejects
+`notify-hub` as too similar to an existing project); the import stays
+`notify_hub`.
+
+## Quickstart
+
+### 1. Configure once (TOML or a dict)
+
+```toml
+# notify-hub.toml
+[hub]
+default_channels = ["slack-ops"]
+
+[channels.slack-ops]
+type = "slack"
+webhook_url = "${SLACK_WEBHOOK_URL}"      # expanded from the environment
+
+[channels.oncall-phone]
+type = "phone"
+provider = "twilio"
+account_sid = "${TWILIO_ACCOUNT_SID}"
+auth_token = "${TWILIO_AUTH_TOKEN}"
+from_number = "+15550001111"
+to_numbers = ["+15552223333"]
+rate_limit = { per_minute = 2, burst = 1 }
+
+[[routes]]
+min_level = "WARNING"
+channels = ["slack-ops"]
+
+[[routes]]
+levels = ["CRITICAL"]
+channels = ["oncall-phone"]               # CRITICAL also matches the rule above
+```
+
+See [`examples/notify-hub.example.toml`](examples/notify-hub.example.toml)
+for every channel and option.
+
+### 2. Send
+
+```python
+from notify_hub import Attachment, Hub
+
+with Hub.from_config("notify-hub.toml") as hub:
+    hub.warning("disk at 85%")                          # fire-and-forget
+    hub.critical("db down")                             # slack + phone call
+
+    handle = hub.notify(
+        "deploy finished",
+        level="INFO",
+        title="Release v2.1",
+        attachments=[Attachment.image("https://example.com/chart.png")],
+    )
+    result = handle.wait(timeout=30)                    # only if you need it
+    print(result.ok)
+```
+
+Async hosts use the same hub:
+
+```python
+async with Hub.from_config("notify-hub.toml") as hub:
+    hub.error("worker crashed")                  # still instant
+    result = await hub.notify_async("done")      # or await the outcome
+```
+
+Custom levels:
+
+```python
+hub.levels.register("TRADE_HALT", 45)            # or [levels.custom] in TOML
+hub.notify("strategy halted", level="TRADE_HALT")
+```
+
+### 3. Observe
+
+With `[log]` enabled, every attempt is recorded:
+
+```json
+{"ts": "2026-06-11T12:00:00+00:00", "level": "CRITICAL", "fingerprint": "9f3a...",
+ "preview": "db down", "suppressed_by_dedup": false,
+ "channels": [{"id": "slack-ops", "ok": true, "attempts": 1, "latency_ms": 212.4,
+               "error": null, "degraded": [], "skipped_reason": null}]}
+```
+
+## Channel capability matrix
+
+| Channel | Text | Markdown | Image | File | Notes |
+|---|:---:|:---:|:---:|:---:|---|
+| Slack | ✅ | ✅ (mrkdwn) | ✅* | ✅* | *URL images free via blocks; uploads need `bot_token` + `file_channel` |
+| Discord | ✅ | ✅ | ✅ | ✅ | multipart, ≤10 files |
+| Telegram | ✅ | ✅ (HTML) | ✅ | ✅ | single image + short text sent as captioned photo |
+| WeCom 企业微信 | ✅ | ✅ | ✅ | ✅ | image ≤2 MB jpg/png; file via `upload_media` |
+| DingTalk 钉钉 | ✅ | ✅ | — | — | HMAC signing or keyword prefix |
+| Lark/Feishu 飞书 | ✅ | ✅ (post) | ✅* | — | *images need `app_id`+`app_secret` (custom app); both feishu.cn and larksuite.com |
+| Phone (Twilio) | ✅ (TTS) | — | — | — | text stripped of markdown/URLs, read aloud |
+
+Unsupported content degrades per `[degrade]` policy — by default it is
+dropped quietly and noted in the result, never failing the notification.
+
+## Writing your own channel
+
+```python
+from notify_hub import Capability, Channel, Message, register_channel
+
+@register_channel
+class MyChannel(Channel):
+    name = "mychannel"
+    capabilities = Capability.TEXT
+
+    async def send(self, message: Message) -> None:
+        ...  # raise ChannelSendError on failure; hub handles retry/logging
+```
+
+Or publish it as an entry point in the `notify_hub.channels` group.
+Voice providers (e.g. Vonage) subclass `VoiceProvider` the same way.
+
+## Design notes
+
+- The TOML schema and routing semantics are language-neutral by design —
+  they are the contract for planned Go and Rust ports.
+- v2 reserves `escalation` (ack + auto-escalate chains) and `digest`
+  (aggregation windows) fields in routing rules; they parse today and warn,
+  but do nothing yet.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                 # tests
+ruff check . && ruff format --check .
+mypy
+```
+
+## License
+
+MIT

pynotifyhub-0.1.0/README.md

@@ -0,0 +1,190 @@
+# notify-hub
+
+Unified multi-channel notification library for Python.
+
+Send alerts to **Slack, Discord, Telegram, WeCom (企业微信), DingTalk (钉钉),
+Lark/Feishu (飞书), and phone voice calls (Twilio)** through one API, with
+level-based routing configured per application — so you never write
+notification glue code again.
+
+```python
+from notify_hub import Hub
+
+hub = Hub.from_config("notify-hub.toml")
+hub.notify("database is down", level="CRITICAL")   # returns in microseconds
+```
+
+What that one call does is decided entirely by config: which channels fire
+for which level, how attachments degrade per channel, retries, dedup,
+rate limits, and where the audit log goes.
+
+> 📖 **中文使用说明（30 秒跑通 + 全渠道接入指南）：[docs/usage.md](docs/usage.md)**
+
+## Features
+
+- **7 channels, one interface** — Slack, Discord, Telegram, WeCom, DingTalk,
+  Lark/Feishu, phone voice calls (Twilio, pluggable for other providers).
+- **Level-based routing** — builtin `DEBUG..CRITICAL` plus your own custom
+  levels (`TRADE_HALT = 45`); each app maps levels to channels in config,
+  matching rules are unioned.
+- **Never blocks your app** — `notify()` returns immediately in both sync
+  and asyncio hosts; fan-out runs concurrently on a lazily-started
+  background event loop. Await the handle (async) or `wait()` on it (sync)
+  only when you need the outcome.
+- **Failure isolation & retries** — one channel failing never affects the
+  others and never raises into your code; transient errors (429/5xx,
+  network) retry with exponential backoff + jitter.
+- **Attachments with graceful degradation** — images/files from a path,
+  bytes, or URL; channels declare capabilities and unsupported content is
+  dropped / linked / failed per your policy (phone calls read text via TTS).
+- **Anti-storm guards** — fingerprint dedup window (default 60 s) and
+  per-channel token-bucket rate limits, so a crash loop can't ring your
+  phone 1000 times.
+- **Audit log** — every send attempt recorded (per-channel status, attempts,
+  latency, errors) as JSON Lines or text, to a file and/or your own
+  `logging.Logger`.
+- **A well-behaved library** — stdlib dataclasses, one hard dependency
+  (`httpx`), zero threads until first use, nothing written or configured
+  unless you ask.
+
+## Installation
+
+```bash
+pip install pynotifyhub
+```
+
+Requires Python 3.10+. The distribution is named `pynotifyhub` (PyPI rejects
+`notify-hub` as too similar to an existing project); the import stays
+`notify_hub`.
+
+## Quickstart
+
+### 1. Configure once (TOML or a dict)
+
+```toml
+# notify-hub.toml
+[hub]
+default_channels = ["slack-ops"]
+
+[channels.slack-ops]
+type = "slack"
+webhook_url = "${SLACK_WEBHOOK_URL}"      # expanded from the environment
+
+[channels.oncall-phone]
+type = "phone"
+provider = "twilio"
+account_sid = "${TWILIO_ACCOUNT_SID}"
+auth_token = "${TWILIO_AUTH_TOKEN}"
+from_number = "+15550001111"
+to_numbers = ["+15552223333"]
+rate_limit = { per_minute = 2, burst = 1 }
+
+[[routes]]
+min_level = "WARNING"
+channels = ["slack-ops"]
+
+[[routes]]
+levels = ["CRITICAL"]
+channels = ["oncall-phone"]               # CRITICAL also matches the rule above
+```
+
+See [`examples/notify-hub.example.toml`](examples/notify-hub.example.toml)
+for every channel and option.
+
+### 2. Send
+
+```python
+from notify_hub import Attachment, Hub
+
+with Hub.from_config("notify-hub.toml") as hub:
+    hub.warning("disk at 85%")                          # fire-and-forget
+    hub.critical("db down")                             # slack + phone call
+
+    handle = hub.notify(
+        "deploy finished",
+        level="INFO",
+        title="Release v2.1",
+        attachments=[Attachment.image("https://example.com/chart.png")],
+    )
+    result = handle.wait(timeout=30)                    # only if you need it
+    print(result.ok)
+```
+
+Async hosts use the same hub:
+
+```python
+async with Hub.from_config("notify-hub.toml") as hub:
+    hub.error("worker crashed")                  # still instant
+    result = await hub.notify_async("done")      # or await the outcome
+```
+
+Custom levels:
+
+```python
+hub.levels.register("TRADE_HALT", 45)            # or [levels.custom] in TOML
+hub.notify("strategy halted", level="TRADE_HALT")
+```
+
+### 3. Observe
+
+With `[log]` enabled, every attempt is recorded:
+
+```json
+{"ts": "2026-06-11T12:00:00+00:00", "level": "CRITICAL", "fingerprint": "9f3a...",
+ "preview": "db down", "suppressed_by_dedup": false,
+ "channels": [{"id": "slack-ops", "ok": true, "attempts": 1, "latency_ms": 212.4,
+               "error": null, "degraded": [], "skipped_reason": null}]}
+```
+
+## Channel capability matrix
+
+| Channel | Text | Markdown | Image | File | Notes |
+|---|:---:|:---:|:---:|:---:|---|
+| Slack | ✅ | ✅ (mrkdwn) | ✅* | ✅* | *URL images free via blocks; uploads need `bot_token` + `file_channel` |
+| Discord | ✅ | ✅ | ✅ | ✅ | multipart, ≤10 files |
+| Telegram | ✅ | ✅ (HTML) | ✅ | ✅ | single image + short text sent as captioned photo |
+| WeCom 企业微信 | ✅ | ✅ | ✅ | ✅ | image ≤2 MB jpg/png; file via `upload_media` |
+| DingTalk 钉钉 | ✅ | ✅ | — | — | HMAC signing or keyword prefix |
+| Lark/Feishu 飞书 | ✅ | ✅ (post) | ✅* | — | *images need `app_id`+`app_secret` (custom app); both feishu.cn and larksuite.com |
+| Phone (Twilio) | ✅ (TTS) | — | — | — | text stripped of markdown/URLs, read aloud |
+
+Unsupported content degrades per `[degrade]` policy — by default it is
+dropped quietly and noted in the result, never failing the notification.
+
+## Writing your own channel
+
+```python
+from notify_hub import Capability, Channel, Message, register_channel
+
+@register_channel
+class MyChannel(Channel):
+    name = "mychannel"
+    capabilities = Capability.TEXT
+
+    async def send(self, message: Message) -> None:
+        ...  # raise ChannelSendError on failure; hub handles retry/logging
+```
+
+Or publish it as an entry point in the `notify_hub.channels` group.
+Voice providers (e.g. Vonage) subclass `VoiceProvider` the same way.
+
+## Design notes
+
+- The TOML schema and routing semantics are language-neutral by design —
+  they are the contract for planned Go and Rust ports.
+- v2 reserves `escalation` (ack + auto-escalate chains) and `digest`
+  (aggregation windows) fields in routing rules; they parse today and warn,
+  but do nothing yet.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                 # tests
+ruff check . && ruff format --check .
+mypy
+```
+
+## License
+
+MIT