Metadata-Version: 2.4
Name: chattolib
Version: 0.4.3
Summary: Async Python client library for the Chatto webchat Connect API
Author-email: Felix <chatto@f3l1x.it>
License-Expression: MIT
Project-URL: Homepage, https://chat.chatto.run
Keywords: chatto,connect,connectrpc,async,webchat,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Framework :: AsyncIO
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: connectrpc>=0.11
Requires-Dist: protobuf>=5.28
Requires-Dist: httpx>=0.27
Provides-Extra: realtime
Requires-Dist: websockets>=13.0; extra == "realtime"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Dynamic: license-file

# chattolib

**Unofficial** async Python client library for the [Chatto](https://chat.chatto.run) webchat API.

> Chattolib versions track the Chatto server version they target. **0.4.2**
> targets Chatto 0.4.2's ConnectRPC API. The upstream server dropped GraphQL
> in favour of a protobuf-first Connect API (see ADR-042 in chattocorp/chatto),
> and this release is a full rewrite for that transport. Request/response
> traffic uses Connect JSON over HTTP; the realtime channel is a binary
> protobuf WebSocket at `/api/realtime` (needs the ``[realtime]`` extra).

## Install

```bash
pip install chattolib
```

## Quick start

```python
import asyncio
from chattolib import ChattoClient

async def main():
    # Public discovery — no auth required
    async with ChattoClient() as anon:
        profile, login = await anon.get_server()
        print(f"Chatto {profile.version}: {profile.name}")

    # Authenticated calls
    async with await ChattoClient.login("username", "password") as client:
        me = await client.me()
        print(f"Logged in as {me.display_name}")

        for entry in await client.list_rooms():
            if entry.room:
                print(f"  - {entry.room.name}")

asyncio.run(main())
```

## Realtime

Install with the extra:

```bash
pip install 'chattolib[realtime]'
```

Then stream live events:

```python
from chattolib import stream_events

async with await ChattoClient.login("username", "password") as client:
    async for event in stream_events(client):
        print(event.kind, event.actor_id, event.payload)
```

`event.kind` names the protobuf ``oneof`` case (`message_posted`,
`reaction_added`, `presence_changed`, `notification_created`, …).
`event.payload` is the concrete protobuf sub-message — access its fields
directly (e.g. `event.payload.room_id`). Realtime events are invalidation
signals; use the corresponding Connect RPC (`GetRoomEventsAround`,
`GetNotification`, `GetUser`, …) to hydrate the referenced resource.

## Escape hatch

`ChattoClient.call(service, method, request)` invokes any Connect RPC by full
service name, e.g.
`await client.call("chatto.api.v1.MessageService", "GetMessage", {"roomId": ..., "eventId": ...})`.

## License

MIT
