Metadata-Version: 2.1
Name: bub-lark
Version: 0.1.0
Summary: Lark / Feishu channel plugin for Bub
Author: Bub contributors
License: Apache-2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Project-URL: Homepage, https://github.com/ximenzun/bub-lark
Project-URL: Repository, https://github.com/ximenzun/bub-lark
Project-URL: Documentation, https://github.com/ximenzun/bub
Project-URL: Issues, https://github.com/ximenzun/bub-lark/issues
Requires-Python: <4.0,>=3.12
Requires-Dist: bub>=0.3.0a1
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: loguru>=0.7.2
Requires-Dist: lark-oapi>=1.4.23
Requires-Dist: mistune>=3.1.4
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Description-Content-Type: text/markdown

# bub-lark

Lark / Feishu chat channel plugin for [Bub](https://github.com/ximenzun/bub).

`bub-lark` adds a native `lark` channel that can receive bot events and send replies through the Lark / Feishu Open Platform.

## Features

- inbound bot messages through event subscription
- outbound send, reply, edit, and card update flows
- text, post, interactive card, image, file, audio, media, and sticker-aware message parsing
- optional webhook mode for callback delivery
- bundled `lark` skill for proactive sends

## Install

Once published:

```bash
uv pip install bub-lark
```

For local development next to the Bub repo:

```bash
cd ../bub-lark
uv sync
```

## Usage

Configure a Feishu / Lark bot app with message receive events.

Common settings:

- `BUB_LARK_APP_ID`
- `BUB_LARK_APP_SECRET`
- `BUB_LARK_DOMAIN=feishu` or `BUB_LARK_DOMAIN=lark`
- `BUB_LARK_CONNECTION_MODE=websocket` or `BUB_LARK_CONNECTION_MODE=webhook`

Webhook mode only:

- `BUB_LARK_VERIFICATION_TOKEN`
- `BUB_LARK_ENCRYPT_KEY`
- `BUB_LARK_WEBHOOK_PORT`
- `BUB_LARK_WEBHOOK_PATH`

Start the channel:

```bash
uv run bub gateway --enable-channel lark
```

## Notes

- `websocket` mode is the default for the Feishu domain.
- `webhook` mode is available for deployments where callback delivery is preferred or required.
- Bub ordinary replies are routed through the native outbound path once the inbound message enters the framework.

## Research Basis

The plugin design follows Feishu / Lark's official bot-event and message-send model plus community integrations:

- Feishu article on custom bot message receiving: <https://www.feishu.cn/content/article/7602519239445974205>
- Feishu article on OpenClaw Feishu integration: <https://www.feishu.cn/content/article/7613711414611463386>
- OpenClaw Feishu plugin docs: <https://github.com/AlexAnys/openclaw-feishu>

## Development

```bash
uv run pytest -q
uv run ruff check .
uv build
```

## Release

Publishing is driven by GitHub Actions.
Create a GitHub Release on `main` with a tag like `v0.1.0` or `0.1.0`, and the release workflow will:

1. normalize the tag to a package version
2. build the sdist and wheel
3. publish to PyPI through Trusted Publishing (GitHub OIDC)

No long-lived `PYPI_TOKEN` secret is required when PyPI Trusted Publisher is configured for `.github/workflows/on-release-main.yml`.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the local workflow, verification commands, and pull request process.
