wechat-ilink-bot 0.1.0__tar.gz

wechat_ilink_bot-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+build/
+dist/
+*.egg-info/
+.coverage
+site/
+plans/

wechat_ilink_bot-0.1.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+mkdocs:
+  configuration: mkdocs.yml

wechat_ilink_bot-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Placeholder for upcoming changes.
+
+## [0.1.0] - 2026-03-28
+
+### Added
+
+- Initial public release of `wechat-ilink-bot`.
+- QR login flow with local credential persistence.
+- Long-polling runtime with handler registration and first-match dispatch model.
+- Proactive send APIs:
+  - `send_text`
+  - `send_image`
+  - `send_video`
+  - `send_file`
+- Message-context reply APIs:
+  - `reply`
+  - `reply_image`
+  - `reply_video`
+  - `reply_file`
+  - `send_typing`
+- Media upload and download helpers.
+- Webhook server (`/healthz`, `/send`) with API key support.
+- CLI command: `wechat-bot webhook`.
+- Owner-default recipient behavior with explicit `to` override support.
+- Account switching and local account listing support.
+- Read the Docs documentation scaffold (`MkDocs + mkdocstrings`).
+- CI/testing/lint/build packaging checks.
+
+### Changed
+
+- Unified package version source in `src/wechat_bot/_version.py`.
+- Standardized webhook response format:
+  - success: `{"status": 200}`
+  - error: `{"status": <code>, "detail": "..."}`
+- Improved recipient resolution and error clarity for missing owner state.
+- Improved local storage safety with atomic JSON writes and strict file permissions when supported.

wechat_ilink_bot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,292 @@
+# Contributing Guide
+
+Thanks for contributing to `wechat-ilink-bot`.
+
+This project is a Python SDK for the WeChat iLink Bot API. Contributions are welcome across runtime code, examples, tests, packaging, and public documentation. Please keep changes small, well-scoped, and aligned with current runtime behavior.
+
+## Development Environment
+
+### Requirements
+
+- Python 3.10+
+- A local environment that can install editable dependencies
+- Optional: a real WeChat/iLink account only if you want to manually verify login or message delivery flows
+
+### Install development dependencies
+
+```bash
+python -m pip install -e .[dev]
+```
+
+This installs the core SDK plus the development toolchain used in this repository:
+
+- `pytest` / `pytest-asyncio`
+- `ruff`
+- `mypy`
+- `build`
+- `twine`
+- webhook-related optional packages already included in `dev`
+
+### Optional extras for focused development
+
+If you are validating a specific distribution scenario, you may also want to test these install paths explicitly:
+
+```bash
+python -m pip install -e .[qrcode]
+python -m pip install -e .[socks]
+python -m pip install -e .[webhook]
+```
+
+## Repository Layout
+
+```text
+src/wechat_bot/     Core SDK implementation
+examples/           Runnable usage examples
+tests/              Automated test suite
+plans/              Execution/research plans used during maintenance
+dist/               Build artifacts
+```
+
+Some important modules:
+
+- `src/wechat_bot/bot.py` — high-level user-facing bot API
+- `src/wechat_bot/client.py` — low-level async iLink API client
+- `src/wechat_bot/polling.py` — long-poll loop, retry, backoff, session recovery
+- `src/wechat_bot/storage.py` — local state directory, credentials, sync cursor, context tokens
+- `src/wechat_bot/webhook.py` — FastAPI webhook server integration
+- `src/wechat_bot/context.py` — handler context helpers for reply, typing, media download
+
+## What to Keep in Sync
+
+When behavior changes, do not update code in isolation. Keep the following layers aligned:
+
+- Runtime implementation in `src/wechat_bot/`
+- Examples in `examples/`
+- Tests in `tests/`
+- Public docs such as `README.md`, `SECURITY.md`, and changelog entries
+
+As a rule of thumb:
+
+- If you change user-visible behavior, update `README.md`
+- If you change example usage, update the corresponding script under `examples/`
+- If you change runtime behavior, add or update tests
+- If you change release-facing behavior, update `CHANGELOG.md` under `Unreleased`
+
+## Development Workflow
+
+A typical contribution flow looks like this:
+
+1. Install the dev environment
+2. Make a focused change
+3. Add or update tests
+4. Update examples/docs if behavior changed
+5. Run the verification commands below
+6. Update `CHANGELOG.md` when appropriate
+7. Open a small, reviewable pull request
+
+## Verification Commands
+
+Run these checks before opening a PR:
+
+```bash
+python -m ruff check src tests examples
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+If you are touching typing-sensitive areas, you may also run:
+
+```bash
+python -m mypy src
+```
+
+## Verification Matrix
+
+Use the following matrix to decide what to run and what files to inspect.
+
+### 1. Lint and import hygiene
+
+Command:
+
+```bash
+python -m ruff check src tests examples
+```
+
+Use this for:
+
+- formatting-adjacent issues
+- unused imports/variables
+- obvious correctness and style regressions
+
+### 2. Behavior validation
+
+Command:
+
+```bash
+python -m pytest -q
+```
+
+Use this for any runtime behavior change.
+
+Particularly relevant test files:
+
+- `tests/test_bot.py` — account loading, recipient resolution, send behavior, runtime helpers
+- `tests/test_polling.py` — session expiry and recovery flow
+- `tests/test_storage.py` — state persistence, permissions, current user behavior
+- `tests/test_webhook.py` — webhook routing, auth, response format, error behavior
+- `tests/test_auth.py` — QR login flow smoke behavior
+- `tests/test_examples_smoke.py` — examples importability and basic callable paths
+
+### 3. Packaging validation
+
+Commands:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Use these when you modify:
+
+- `pyproject.toml`
+- package metadata
+- README content that affects package rendering
+- distribution-facing extras or entry points
+
+## Change-Type Guidance
+
+### If you modify bot runtime behavior
+
+Examples:
+
+- account selection
+- owner-default recipient logic
+- handler dispatch
+- send APIs
+- session recovery behavior
+
+Expected follow-up:
+
+- update `tests/test_bot.py`
+- update `tests/test_polling.py` if polling/session behavior changed
+- update `README.md` if user-facing behavior changed
+
+### If you modify storage or local credential behavior
+
+Examples:
+
+- state directory layout
+- `current_user.json`
+- `credentials.json`
+- file permissions
+- atomic write strategy
+
+Expected follow-up:
+
+- update `tests/test_storage.py`
+- update `README.md` if local state behavior is user-visible
+- update `SECURITY.md` if the security posture changed
+
+### If you modify webhook or CLI behavior
+
+Examples:
+
+- request schema
+- response shape
+- API key behavior
+- host/port/default flags
+- GET/POST route behavior
+
+Expected follow-up:
+
+- update `tests/test_webhook.py`
+- update `tests/test_cli.py` if CLI behavior changed
+- update `README.md`
+- update `SECURITY.md` if exposure or auth behavior changed
+
+### If you modify examples
+
+Expected follow-up:
+
+- keep examples runnable and consistent with the current public API
+- ensure `tests/test_examples_smoke.py` still reflects the intended import/call path
+- update `README.md` example references if script purpose or invocation changed
+
+## Code Style Expectations
+
+- Prefer small, focused pull requests
+- Keep public API changes backward-compatible when possible
+- Favor clear names and explicit behavior over implicit magic
+- Preserve current async-first design unless a change is clearly justified
+- Handle errors carefully, especially around auth, polling, storage, and webhook responses
+- Avoid leaking sensitive implementation details in externally exposed error surfaces
+
+## Documentation Expectations
+
+This repository treats documentation as part of the product surface.
+
+Please update docs when you change:
+
+- installation flow
+- example commands
+- webhook usage
+- account selection behavior
+- state directory behavior
+- security-relevant behavior
+
+When updating terms, keep wording consistent across:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+
+Important terms that should stay consistent include:
+
+- `account_id`
+- `user_id`
+- `owner-default`
+- `current_user.json`
+- `context_token`
+- `webhook key`
+- `session expired`
+
+## Changelog Policy
+
+If your change affects users, add an entry under `## [Unreleased]` in `CHANGELOG.md`.
+
+Typical cases:
+
+- new features
+- behavior changes
+- breaking or compatibility-sensitive adjustments
+- docs that materially affect onboarding or operational use
+- security-related changes
+
+Try to place changes under the existing categories such as `Added` or `Changed`.
+
+## Pull Request Checklist
+
+Before opening a PR, confirm the following:
+
+- [ ] The change is focused and reviewable
+- [ ] Lint passes locally
+- [ ] Tests pass locally
+- [ ] Examples were updated if usage changed
+- [ ] Public docs were updated if behavior changed
+- [ ] `CHANGELOG.md` was updated under `Unreleased` when appropriate
+- [ ] No sensitive local state or credentials were added to the repository
+
+## Reporting Bugs
+
+If you are opening a bug report, please include:
+
+- Python version
+- OS/platform
+- minimal reproducible code
+- relevant logs or error output
+- whether the issue affects login, polling, sending, webhook, storage, or packaging
+
+Open regular bugs in the repository issue tracker.
+
+For suspected security vulnerabilities, do **not** open a public issue. Follow the private disclosure guidance in `SECURITY.md`.

wechat_ilink_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wechat-bot contributors
+
+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.

wechat_ilink_bot-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: wechat-ilink-bot
+Version: 0.1.0
+Summary: Python SDK for WeChat iLink Bot API — send and receive WeChat messages programmatically.
+Project-URL: Homepage, https://github.com/hkslover/wechat-ilink-bot
+Project-URL: Repository, https://github.com/hkslover/wechat-ilink-bot
+Project-URL: Issues, https://github.com/hkslover/wechat-ilink-bot/issues
+Project-URL: Documentation, https://wechat-ilink-bot.readthedocs.io/en/latest/
+Project-URL: Changelog, https://github.com/hkslover/wechat-ilink-bot/blob/main/CHANGELOG.md
+Author: hkslover
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot,ilink,sdk,wechat,weixin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: fastapi>=0.111; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pymdown-extensions>=10.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.8; extra == 'docs'
+Provides-Extra: qrcode
+Requires-Dist: qrcode[pil]; extra == 'qrcode'
+Provides-Extra: socks
+Requires-Dist: httpx[socks]; extra == 'socks'
+Provides-Extra: webhook
+Requires-Dist: fastapi>=0.111; extra == 'webhook'
+Requires-Dist: uvicorn>=0.30; extra == 'webhook'
+Description-Content-Type: text/markdown
+
+# wechat-ilink-bot
+
+轻量、实用的 Python SDK，用于接入 WeChat iLink Bot API。
+
+支持扫码登录、长轮询收消息、文本/图片/视频/文件发送，以及一键 webhook 发送。
+
+## 核心能力
+
+- 收消息：长轮询 + handler
+- 主动发送文本：`send_text`
+- 主动发送图片/视频/文件：`send_image` / `send_video` / `send_file`
+- 会话内回复文本：`ctx.reply`
+- 会话内回复图片/视频/文件：`ctx.reply_image` / `ctx.reply_video` / `ctx.reply_file`
+- Webhook 触发发送（当前为文本）
+
+<p>
+  <a href="https://wechat-ilink-bot.readthedocs.io/en/latest/" target="_blank">
+    <strong>Read the Docs: https://wechat-ilink-bot.readthedocs.io/en/latest/</strong>
+  </a>
+</p>
+
+## 安装
+
+PyPI 安装：
+
+```bash
+pip install wechat-ilink-bot
+```
+
+源码安装（开发/调试推荐）：
+
+```bash
+git clone https://github.com/hkslover/wechat-ilink-bot.git
+cd wechat-ilink-bot
+pip install -e .
+```
+
+可选依赖：
+
+```bash
+# 终端二维码打印
+pip install "wechat-ilink-bot[qrcode]"
+
+# webhook
+pip install "wechat-ilink-bot[webhook]"
+```
+
+## 快速开始
+
+### 1) 扫码登录并持久化账号
+
+```python
+import asyncio
+
+from wechat_bot import Bot
+
+
+async def main() -> None:
+    bot = Bot(use_current_user=False)
+    result = await bot.login()
+    print(f"login ok: account_id={result.account_id}, user_id={result.user_id}")
+    await bot.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2) 最小 Echo Bot
+
+```python
+from wechat_bot import Bot, Filter
+
+bot = Bot()
+
+
+@bot.on_message(Filter.text())
+async def echo(ctx):
+    await ctx.reply(f"Echo: {ctx.text}")
+
+
+if __name__ == "__main__":
+    bot.run()
+```
+
+### 3) 主动发送（owner-default 或显式目标）
+
+```python
+import asyncio
+
+from wechat_bot import Bot
+
+
+async def main() -> None:
+    bot = Bot()
+
+    # owner-default（不传 to）
+    await bot.send_text(text="Hello from wechat-ilink-bot!")
+
+    # 或者显式目标
+    # await bot.send_text(to="o9xxx@im.wechat", text="Hello")
+
+    await bot.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 4) 主动发送富媒体（图片 / 视频 / 文件）
+
+```python
+import asyncio
+
+from wechat_bot import Bot
+
+
+async def main() -> None:
+    bot = Bot()
+
+    # owner-default（不传 to）
+    await bot.send_image(file_path="/path/to/image.png", caption="image")
+    await bot.send_video(file_path="/path/to/video.mp4", caption="video")
+    await bot.send_file(file_path="/path/to/file.pdf", caption="file")
+
+    # 显式目标（需要时）
+    # await bot.send_image(to="o9xxx@im.wechat", file_path="/path/to/image.png")
+
+    await bot.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 5) 会话内回复富媒体（ctx.reply_*）
+
+```python
+from wechat_bot import Bot, Filter
+
+bot = Bot()
+
+
+@bot.on_message(Filter.text_startswith("/image"))
+async def reply_image(ctx):
+    await ctx.reply_image("/path/to/image.png", caption="image")
+
+
+@bot.on_message(Filter.text_startswith("/video"))
+async def reply_video(ctx):
+    await ctx.reply_video("/path/to/video.mp4", caption="video")
+
+
+@bot.on_message(Filter.text_startswith("/file"))
+async def reply_file(ctx):
+    await ctx.reply_file("/path/to/file.pdf", caption="file")
+
+
+if __name__ == "__main__":
+    bot.run()
+```
+
+## Webhook 快速使用
+
+启动：
+
+```bash
+wechat-bot webhook --api-key your-secret
+```
+
+请求示例：
+
+```bash
+# GET
+curl "http://127.0.0.1:8787/send?text=hello&key=your-secret"
+
+# POST
+curl -X POST "http://127.0.0.1:8787/send" \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Key: your-secret" \
+  -d '{"text":"hello from webhook"}'
+```
+
+> Webhook `/send` 当前用于发送文本。  
+> 图片/视频/文件发送请使用 `Bot.send_image` / `Bot.send_video` / `Bot.send_file`。
+
+## Examples
+
+更多完整脚本请查看：
+
+- [examples/login_bot.py](examples/login_bot.py)
+- [examples/echo_bot.py](examples/echo_bot.py)
+- [examples/command_bot.py](examples/command_bot.py)
+- [examples/media_bot.py](examples/media_bot.py)
+- [examples/proactive_send.py](examples/proactive_send.py)
+- [examples/account_switch.py](examples/account_switch.py)
+- [examples/webhook_server.py](examples/webhook_server.py)
+
+## 本地文档预览
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs serve
+```
+
+## 参与贡献
+
+- [Contributing Guide](CONTRIBUTING.md)
+- [Security Policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT