webex-message-handler 0.1.0__tar.gz

webex_message_handler-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.log
+.DS_Store
+Thumbs.db

webex_message_handler-0.1.0/API.md

@@ -0,0 +1,291 @@
+# webex-message-handler API Reference
+
+Lightweight, standalone package for receiving and decrypting Webex messages over a persistent WebSocket. No full Webex SDK required — just provide a bot token.
+
+## Installation
+
+```bash
+pip install webex-message-handler
+```
+
+## Quick Start
+
+```python
+import asyncio
+from webex_message_handler import WebexMessageHandler, WebexMessageHandlerConfig, console_logger
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(token="YOUR_BOT_TOKEN", logger=console_logger)
+)
+
+@handler.on("message:created")
+async def on_message(msg):
+    print(f"[{msg.person_email}] {msg.text}")
+
+handler.on("error", lambda err: print(f"Error: {err}"))
+
+async def main():
+    await handler.connect()
+
+asyncio.run(main())
+```
+
+---
+
+## Public API Surface
+
+| Method | Purpose |
+|---|---|
+| `await connect()` | Start the connection (device registration, WebSocket, KMS handshake). |
+| `await disconnect()` | Tear down the connection cleanly. |
+| `await reconnect(new_token)` | Update the token and re-establish everything from scratch. |
+| `status()` | Health check — returns structured connection state of all subsystems. |
+| `connected` | Quick boolean: is the handler connected and WebSocket open? |
+| `on(event, callback)` | Subscribe to events. Can also be used as `@handler.on(event)` decorator. |
+| `off(event, callback)` | Unsubscribe from events. |
+
+---
+
+## WebexMessageHandler
+
+### Constructor
+
+```python
+WebexMessageHandler(config: WebexMessageHandlerConfig)
+```
+
+**`WebexMessageHandlerConfig` fields:**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `token` | `str` | Yes | — | Webex bot or user access token. |
+| `logger` | `Logger` | No | silent | Logger implementation (`console_logger` provided). |
+| `ping_interval` | `float` | No | `15.0` | WebSocket heartbeat ping interval in seconds. |
+| `pong_timeout` | `float` | No | `14.0` | How long to wait for pong before triggering reconnect. |
+| `reconnect_backoff_max` | `float` | No | `32.0` | Max backoff delay between reconnection attempts. |
+| `max_reconnect_attempts` | `int` | No | `10` | Max consecutive reconnection attempts before giving up. |
+
+### Methods
+
+#### `await connect()`
+
+Establishes the full connection pipeline:
+
+1. Registers a virtual device with Webex WDM (Web Device Management)
+2. Opens a Mercury WebSocket and authenticates
+3. Performs KMS ECDH key exchange (for end-to-end message encryption)
+4. Begins listening for encrypted messages, decrypting them automatically
+
+```python
+await handler.connect()
+```
+
+#### `await disconnect()`
+
+Tears down the connection cleanly:
+
+1. Closes the Mercury WebSocket (stops heartbeat, cancels auto-reconnection)
+2. Unregisters the virtual device with WDM
+3. Clears KMS context and decryption keys from memory
+
+```python
+await handler.disconnect()
+```
+
+#### `await reconnect(new_token: str)`
+
+Updates the access token and re-establishes the connection from scratch.
+
+```python
+fresh_token = await my_auth_system.refresh_token()
+await handler.reconnect(fresh_token)
+```
+
+#### `status() -> HandlerStatus`
+
+Returns a structured health check of all connection subsystems.
+
+```python
+health = handler.status()
+```
+
+**`HandlerStatus` fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | `ConnectionStatus` | `'connected'`, `'connecting'`, `'reconnecting'`, or `'disconnected'`. |
+| `web_socket_open` | `bool` | Whether the Mercury WebSocket is currently open. |
+| `kms_initialized` | `bool` | Whether the KMS encryption context has been established. |
+| `device_registered` | `bool` | Whether a virtual device is registered with WDM. |
+| `reconnect_attempt` | `int` | Current auto-reconnect attempt number (`0` if not reconnecting). |
+
+#### `connected: bool` (property)
+
+Quick boolean shorthand. Returns `True` only when fully connected.
+
+### Events
+
+Subscribe with `handler.on(event, callback)` or `@handler.on(event)` decorator. Remove with `handler.off(event, callback)`.
+
+#### `'message:created'`
+
+```python
+@handler.on("message:created")
+async def on_message(msg: DecryptedMessage):
+    msg.id            # str — unique message ID
+    msg.room_id       # str — conversation/room ID
+    msg.person_id     # str — sender's Webex user ID
+    msg.person_email  # str — sender's email address
+    msg.text          # str — decrypted plain text
+    msg.html          # str | None — decrypted HTML content
+    msg.created       # str — ISO 8601 timestamp
+    msg.room_type     # 'direct' | 'group' | None
+    msg.raw           # MercuryActivity — full decrypted activity
+```
+
+#### `'message:deleted'`
+
+```python
+@handler.on("message:deleted")
+def on_deleted(data: DeletedMessage):
+    data.message_id  # str — ID of the deleted message
+    data.room_id     # str — conversation/room ID
+    data.person_id   # str — who deleted it
+```
+
+#### `'connected'`
+
+```python
+@handler.on("connected")
+def on_connected():
+    print("Ready to receive messages")
+```
+
+#### `'disconnected'`
+
+| Reason | Meaning | Action |
+|---|---|---|
+| `'client'` | You called `disconnect()`. | None — intentional. |
+| `'auth-failed'` | Token is invalid or expired (code 4401). | Call `reconnect(new_token)`. |
+| `'permanent-failure'` | Server rejected permanently (code 4400/4403). | Investigate. |
+| `'max-attempts-exceeded'` | Auto-reconnect gave up. | Call `reconnect(new_token)`. |
+| `'manual'` | WebSocket closed, reconnection disabled. | None. |
+
+#### `'reconnecting'`
+
+```python
+@handler.on("reconnecting")
+def on_reconnecting(attempt: int):
+    print(f"Reconnect attempt {attempt}...")
+```
+
+#### `'error'`
+
+```python
+@handler.on("error")
+def on_error(err: Exception):
+    print(f"Handler error: {err}")
+```
+
+---
+
+## Logger Interface
+
+Any object with `debug`, `info`, `warning`, and `error` methods works. Python's `logging.Logger` is directly compatible.
+
+```python
+import logging
+logger = logging.getLogger("my_bot")
+handler = WebexMessageHandler(WebexMessageHandlerConfig(token="...", logger=logger))
+```
+
+**Built-in loggers:**
+
+| Export | Behavior |
+|---|---|
+| `noop_logger` | Silent. All methods are no-ops. This is the default. |
+| `console_logger` | Logs via `logging.getLogger("webex_message_handler")`. |
+
+---
+
+## Error Classes
+
+All errors extend `WebexError` which extends `Exception`. Each has a `.code` string.
+
+| Class | `.code` | When |
+|---|---|---|
+| `AuthError` | `AUTH_ERROR` | Token is invalid, expired, or unauthorized. |
+| `DeviceRegistrationError` | `DEVICE_REGISTRATION_ERROR` | WDM operations failed. Has `.status_code`. |
+| `MercuryConnectionError` | `MERCURY_CONNECTION_ERROR` | WebSocket connection failed. Has `.close_code`. |
+| `KmsError` | `KMS_ERROR` | KMS key exchange or key retrieval failed. |
+| `DecryptionError` | `DECRYPTION_ERROR` | Message decryption failed. |
+
+```python
+from webex_message_handler import AuthError, KmsError
+
+@handler.on("error")
+def on_error(err):
+    if isinstance(err, AuthError):
+        # token issue — reconnect with fresh token
+        pass
+    elif isinstance(err, KmsError):
+        # KMS issue — will auto-recover on reconnect
+        pass
+```
+
+---
+
+## Type Exports
+
+All types are dataclasses:
+
+```python
+from webex_message_handler import (
+    WebexMessageHandlerConfig,
+    DeviceRegistration,
+    MercuryActor,
+    MercuryObject,
+    MercuryTarget,
+    MercuryActivity,
+    MercuryEnvelope,
+    DecryptedMessage,
+    DeletedMessage,
+    HandlerStatus,
+    ConnectionStatus,
+)
+```
+
+---
+
+## Connection Lifecycle
+
+```
+    +-----------+       +----------+       +----------+       +---------+
+    |  register |  -->  | Mercury  |  -->  |   KMS    |  -->  |  ready  |
+    |  device   |       | connect  |       |  ECDH    |       |         |
+    +-----------+       +----------+       +----------+       +---------+
+         |                   |                  |                  |
+         |              heartbeat           encrypts           emits:
+         |              ping/pong           messages        message:created
+         |                   |                  |           message:deleted
+         |                   v                  |                  |
+         |            (connection drop)         |                  |
+         |                   |                  |                  |
+         |                   v                  v                  |
+         |             +-----------+    +------------+            |
+         |             | auto      |--> | re-init    |----------->+
+         |             | reconnect |    | KMS + WDM  |
+         |             +-----------+    +------------+
+         |
+    reconnect(new_token) --> disconnect() --> connect() with new token
+```
+
+---
+
+## Notes for Implementers
+
+- **Async throughout**: All I/O uses `asyncio` + `aiohttp`. Run inside an async context.
+- **Memory**: Encryption keys are cached. On auto-reconnect, the key cache is preserved.
+- **One instance per token**: Each instance registers its own virtual device.
+- **No outbound messaging**: This package only *receives* messages. To send messages, use the Webex REST API.
+- **Heartbeat**: Ping every `ping_interval` seconds. Pong timeout triggers auto-reconnect.

webex_message_handler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ergon Copeland
+
+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.

webex_message_handler-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: webex-message-handler
+Version: 0.1.0
+Summary: Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK
+Project-URL: Homepage, https://github.com/3rg0n/webex-message-handler
+Project-URL: Repository, https://github.com/3rg0n/webex-message-handler
+Author: Ergon Copeland
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot,kms,mercury,messaging,webex,websocket
+Classifier: Development Status :: 4 - Beta
+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
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: jwcrypto>=1.5
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# webex-message-handler
+
+Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages — no Webex SDK required.
+
+Python port of the [TypeScript webex-message-handler](https://github.com/ecopelan/webex-message-handler).
+
+## Why?
+
+- **The Webex Python SDK has heavy dependencies and limited WebSocket support**
+- **Bots behind corporate firewalls need persistent connections, not webhooks**
+- **This package extracts only the essential Mercury + KMS logic (~2 dependencies)**
+
+## Install
+
+```bash
+pip install webex-message-handler
+```
+
+## Quick Start
+
+```python
+import asyncio
+from webex_message_handler import WebexMessageHandler, WebexMessageHandlerConfig, console_logger
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token="YOUR_BOT_TOKEN",
+        logger=console_logger,
+    )
+)
+
+@handler.on("message:created")
+async def on_message(msg):
+    print(f"[{msg.person_email}] {msg.text}")
+    if msg.html:
+        print(f"  HTML: {msg.html}")
+
+@handler.on("message:deleted")
+def on_deleted(data):
+    print(f"Message {data.message_id} deleted by {data.person_id}")
+
+@handler.on("connected")
+def on_connected():
+    print("Connected to Webex")
+
+@handler.on("disconnected")
+def on_disconnected(reason):
+    print(f"Disconnected: {reason}")
+
+@handler.on("reconnecting")
+def on_reconnecting(attempt):
+    print(f"Reconnecting (attempt {attempt})...")
+
+@handler.on("error")
+def on_error(err):
+    print(f"Error: {err}")
+
+async def main():
+    await handler.connect()
+    # Keep running until interrupted
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await handler.disconnect()
+
+asyncio.run(main())
+```
+
+See `examples/basic_bot.py` for a complete working example.
+
+## API Reference
+
+### `WebexMessageHandler`
+
+Main class for receiving and decrypting Webex messages.
+
+#### Constructor
+
+```python
+WebexMessageHandler(config: WebexMessageHandlerConfig)
+```
+
+**Configuration options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `str` | required | Webex bot access token |
+| `logger` | `Logger` | noop | Custom logger (`console_logger` provided) |
+| `ping_interval` | `float` | `15.0` | Mercury ping interval (seconds) |
+| `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |
+| `reconnect_backoff_max` | `float` | `32.0` | Max reconnect backoff (seconds) |
+| `max_reconnect_attempts` | `int` | `10` | Max reconnect attempts |
+
+#### Methods
+
+- **`await connect()`** — Connects to Webex (registers device, initializes KMS, opens Mercury WebSocket)
+- **`await disconnect()`** — Gracefully disconnects (closes WebSocket, unregisters device)
+- **`await reconnect(new_token)`** — Update token and re-establish connection
+- **`status()`** — Returns `HandlerStatus` health check
+- **`connected`** — `bool` property: whether currently connected
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message:created` | `DecryptedMessage` | New message received and decrypted |
+| `message:deleted` | `DeletedMessage` | Message was deleted |
+| `connected` | — | Connected/reconnected to Mercury |
+| `disconnected` | `reason: str` | Disconnected from Mercury |
+| `reconnecting` | `attempt: int` | Attempting to reconnect |
+| `error` | `Exception` | Error occurred |
+
+### `DecryptedMessage`
+
+```python
+@dataclass
+class DecryptedMessage:
+    id: str
+    room_id: str
+    person_id: str
+    person_email: str
+    text: str
+    created: str
+    html: str | None
+    room_type: str | None   # "direct" | "group"
+    raw: MercuryActivity | None
+```
+
+## Architecture
+
+```
+WebexMessageHandler (orchestrator)
+├── DeviceManager  — WDM registration
+├── MercurySocket  — WebSocket + ping/pong + reconnect
+├── KmsClient      — ECDH handshake + key retrieval
+└── MessageDecryptor — JWE decryption
+```
+
+## License
+
+MIT

webex_message_handler-0.1.0/README.md

@@ -0,0 +1,141 @@
+# webex-message-handler
+
+Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages — no Webex SDK required.
+
+Python port of the [TypeScript webex-message-handler](https://github.com/ecopelan/webex-message-handler).
+
+## Why?
+
+- **The Webex Python SDK has heavy dependencies and limited WebSocket support**
+- **Bots behind corporate firewalls need persistent connections, not webhooks**
+- **This package extracts only the essential Mercury + KMS logic (~2 dependencies)**
+
+## Install
+
+```bash
+pip install webex-message-handler
+```
+
+## Quick Start
+
+```python
+import asyncio
+from webex_message_handler import WebexMessageHandler, WebexMessageHandlerConfig, console_logger
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token="YOUR_BOT_TOKEN",
+        logger=console_logger,
+    )
+)
+
+@handler.on("message:created")
+async def on_message(msg):
+    print(f"[{msg.person_email}] {msg.text}")
+    if msg.html:
+        print(f"  HTML: {msg.html}")
+
+@handler.on("message:deleted")
+def on_deleted(data):
+    print(f"Message {data.message_id} deleted by {data.person_id}")
+
+@handler.on("connected")
+def on_connected():
+    print("Connected to Webex")
+
+@handler.on("disconnected")
+def on_disconnected(reason):
+    print(f"Disconnected: {reason}")
+
+@handler.on("reconnecting")
+def on_reconnecting(attempt):
+    print(f"Reconnecting (attempt {attempt})...")
+
+@handler.on("error")
+def on_error(err):
+    print(f"Error: {err}")
+
+async def main():
+    await handler.connect()
+    # Keep running until interrupted
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await handler.disconnect()
+
+asyncio.run(main())
+```
+
+See `examples/basic_bot.py` for a complete working example.
+
+## API Reference
+
+### `WebexMessageHandler`
+
+Main class for receiving and decrypting Webex messages.
+
+#### Constructor
+
+```python
+WebexMessageHandler(config: WebexMessageHandlerConfig)
+```
+
+**Configuration options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `str` | required | Webex bot access token |
+| `logger` | `Logger` | noop | Custom logger (`console_logger` provided) |
+| `ping_interval` | `float` | `15.0` | Mercury ping interval (seconds) |
+| `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |
+| `reconnect_backoff_max` | `float` | `32.0` | Max reconnect backoff (seconds) |
+| `max_reconnect_attempts` | `int` | `10` | Max reconnect attempts |
+
+#### Methods
+
+- **`await connect()`** — Connects to Webex (registers device, initializes KMS, opens Mercury WebSocket)
+- **`await disconnect()`** — Gracefully disconnects (closes WebSocket, unregisters device)
+- **`await reconnect(new_token)`** — Update token and re-establish connection
+- **`status()`** — Returns `HandlerStatus` health check
+- **`connected`** — `bool` property: whether currently connected
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message:created` | `DecryptedMessage` | New message received and decrypted |
+| `message:deleted` | `DeletedMessage` | Message was deleted |
+| `connected` | — | Connected/reconnected to Mercury |
+| `disconnected` | `reason: str` | Disconnected from Mercury |
+| `reconnecting` | `attempt: int` | Attempting to reconnect |
+| `error` | `Exception` | Error occurred |
+
+### `DecryptedMessage`
+
+```python
+@dataclass
+class DecryptedMessage:
+    id: str
+    room_id: str
+    person_id: str
+    person_email: str
+    text: str
+    created: str
+    html: str | None
+    room_type: str | None   # "direct" | "group"
+    raw: MercuryActivity | None
+```
+
+## Architecture
+
+```
+WebexMessageHandler (orchestrator)
+├── DeviceManager  — WDM registration
+├── MercurySocket  — WebSocket + ping/pong + reconnect
+├── KmsClient      — ECDH handshake + key retrieval
+└── MessageDecryptor — JWE decryption
+```
+
+## License
+
+MIT