docs: update for rooms, messaging, sync modules + CLI

2026-05-23 12:08:39 -04:00
parent d5eefcb6a3
commit 756ebba120
1 changed files with 115 additions and 12 deletions
@@ -1,6 +1,7 @@
 # Matrix-Hermes

-Matrix bridge for Hermes Agent — provides authentication, client connectivity, and bridge utilities.
+Matrix bridge for Hermes Agent — provides authentication, client connectivity, bridge utilities,
+room management, messaging, and real-time sync.

 ## Quick Start

@@ -38,23 +39,121 @@ matrix-hermes login
 ## CLI Commands

 ```bash
-matrix-hermes login      # Authenticate with homeserver
-matrix-hermes whoami     # Validate current token
-matrix-hermes logout     # Invalidate token + remove session
-matrix-hermes check      # Check config from env
-matrix-hermes show-config # Show config as env vars
+# Authentication
+matrix-hermes login        # Authenticate with homeserver
+matrix-hermes whoami       # Validate current token
+matrix-hermes logout       # Invalidate token + remove session
+matrix-hermes check        # Check config from env
+matrix-hermes show-config   # Show config as env vars
+
+# Rooms
+matrix-hermes rooms list                         # List joined rooms
+matrix-hermes rooms create --name "My Room"      # Create a new room
+matrix-hermes rooms join !room:example.org       # Join a room
+matrix-hermes rooms leave !room:example.org      # Leave a room
+matrix-hermes rooms info !room:example.org       # Get room details
+matrix-hermes rooms members !room:example.org    # List room members
+matrix-hermes rooms invite !room:example.org @user:example.org
+
+# Messaging
+matrix-hermes send text !room:example.org "Hello Matrix!"
+matrix-hermes send image !room:example.org /tmp/photo.jpg --caption "Check this"
+matrix-hermes send file !room:example.org /tmp/report.pdf
+
+# Sync
+matrix-hermes sync listen                                      # Listen for all messages
+matrix-hermes sync listen --room !room:example.org             # Filter by room
+matrix-hermes sync listen --filter-type m.room.message         # Filter by type
+matrix-hermes sync listen --show-all                           # Show all event types
 ```

+## Python API
+
+```python
+import asyncio
+from matrix_hermes import MatrixConfig, MatrixClient
+
+async def main():
+    config = MatrixConfig.from_env()
+    async with MatrixClient(config) as client:
+        # Rooms
+        rooms = await client.get_joined_rooms()
+        ok = await client.join_room("!room:example.org")
+        
+        # Messages
+        result = await client.send_message("!room:example.org", "Hello from Hermes!")
+        
+        # Sync
+        from matrix_hermes import SyncEngine, SyncFilter
+        engine = SyncEngine(client._client)
+        
+        async def on_message(event):
+            print(f"[{event.room_id}] {event.sender}: {event.content.get('body')}")
+        
+        engine.on_event("m.room.message", on_message)
+        engine.start_background()
+        
+        # ... do other work ...
+        
+        await engine.stop()
+
+asyncio.run(main())
+```
+
+## Module Reference
+
+| Module | Purpose | Key exports |
+|--------|---------|-------------|
+| `auth` | Login, token, sessions | `login`, `login_from_config`, `logout`, `save_session` |
+| `config` | Env-based configuration | `MatrixConfig` |
+| `client` | Async mautrix wrapper | `MatrixClient`, `MatrixMessage`, `SendResult` |
+| `rooms` | Room management | `create_room`, `join_room`, `leave_room`, `get_room_info`, `get_room_members` |
+| `messaging` | Send messages, media | `send_text`, `send_image`, `send_file`, `edit_message`, `send_reaction` |
+| `sync` | Real-time event sync | `SyncEngine`, `SyncFilter`, `sync_once`, `extract_events`, `get_messages` |
+| `cli` | CLI entry point | `main` |
+
+### Room Management
+
+- `create_room()` — create rooms with presets, visibility, invites
+- `join_room()` / `leave_room()` / `forget_room()` — membership lifecycle
+- `get_joined_rooms()` — list joined rooms
+- `get_room_info()` — fetch room metadata (name, topic, member count, encryption)
+- `get_room_members()` — list members with display names
+- `invite_user()` / `kick_user()` / `ban_user()` / `unban_user()` — moderation
+- `set_room_name()` / `set_room_topic()` — room settings
+
+### Messaging
+
+- `send_text()` — plain text with optional HTML, reply, thread
+- `send_notice()` — m.notice (less intrusive)
+- `send_emote()` — m.emote (/me style)
+- `send_image()` / `send_file()` / `send_sticker()` — rich media
+- `edit_message()` — m.replace edits
+- `redact_message()` — message deletion
+- `send_reaction()` — emoji reactions
+- `send_typing()` / `send_read_receipt()` / `set_fully_read()` — presence
+
+### Sync Engine
+
+- `SyncEngine` — continuous sync with handler dispatch, exponential backoff
+- `SyncFilter` — filter by event type, room, sender
+- `sync_once()` — single sync call
+- `extract_events()` — parse sync response into event objects
+- `get_messages()` — paginated message history
+
 ## Project Structure

 ```
 src/matrix_hermes/
-├── __init__.py   # Package init
-├── auth.py       # Login, token, session persistence
-├── client.py     # Async MatrixClient (mautrix wrapper)
-├── config.py     # Env-based configuration
-└── cli.py        # CLI entry point
-tests/            # 60 unit tests
+├── __init__.py    # Package init, re-exports all public API
+├── auth.py        # Login, token, session persistence
+├── client.py      # Async MatrixClient (mautrix wrapper)
+├── config.py      # Env-based configuration
+├── rooms.py       # Room management (create/join/list/moderate)
+├── messaging.py   # Messaging (text/media/edit/react/typing)
+├── sync.py        # Sync engine (poll, filter, dispatch, history)
+└── cli.py         # CLI entry point (all commands)
+tests/             # 182 unit tests
 ```

 ## Dependencies
@@ -63,3 +162,7 @@ tests/            # 60 unit tests
 - mautrix >= 0.20.0
 - aiohttp >= 3.9
 - python-dotenv >= 1.0
+
+## Repository
+
+https://gitea.ourpad.casa/shawn/matrix-hermes