Metadata-Version: 2.4
Name: borgee-plugin-sdk
Version: 0.2.0
Summary: Async Python SDK for Borgee plugin runtimes
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets==15.0.1
Provides-Extra: test
Requires-Dist: build==1.2.2.post1; extra == "test"
Requires-Dist: mypy==1.17.0; extra == "test"
Requires-Dist: PyYAML==6.0.2; extra == "test"
Requires-Dist: pytest==9.0.3; extra == "test"
Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
Requires-Dist: pytest-timeout==2.4.0; extra == "test"
Requires-Dist: ruff==0.12.4; extra == "test"
Requires-Dist: twine==6.1.0; extra == "test"
Dynamic: license-file

# Borgee Plugin SDK for Python

`borgee-plugin-sdk` connects a Python runtime to Borgee over the Borgee Plugin
Protocol (BPP). It supports Python 3.11 through 3.13 and pins
`websockets==15.0.1` because the connection hardening depends on that exact
client implementation.

Build a wheel from this directory or install the source checkout for evaluation. The repository also provides a manual workflow for publishing to TestPyPI and PyPI.

```bash
python -m pip install .
```

```python
import asyncio

from borgee_plugin_sdk import BorgeePluginOptions, ReplayMode, create_borgee_plugin


async def main() -> None:
    client = create_borgee_plugin(
        BorgeePluginOptions(
            base_url="https://chat.example.com",
            api_key="bgr_example",
            replay_mode=ReplayMode.LATEST_N,
        )
    )
    async with client:
        async for delivery in client.deliveries():
            print(delivery.event)
            await delivery.checkpoint()


asyncio.run(main())
```

Every inbound message or replay summary is a `Delivery`. The iterator has one
consumer, and it will not advance until the consumer calls `checkpoint()` or
`fail()`. Actions fail while the connection is resuming; replay consumption
continues until the client becomes online.

For local development, insecure transport is restricted to loopback origins and
requires `allow_insecure_loopback=True`. API keys are sent only in the WebSocket
`Authorization` header. Redirects are rejected.

This package is licensed under the MIT License.
