webex-message-handler 0.1.0__tar.gz → 0.3.0__tar.gz

{webex_message_handler-0.1.0 → webex_message_handler-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.1.0
+Version: 0.3.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
@@ -99,6 +99,51 @@ asyncio.run(main())
 
 See `examples/basic_bot.py` for a complete working example.
 
+## Proxy Support (Enterprise)
+
+For corporate environments behind a proxy, pass a configured connector:
+
+```python
+import aiohttp
+from aiohttp_socks import ProxyConnector
+
+# Using HTTP/HTTPS proxy
+connector = ProxyConnector.from_url(
+    "http://proxy.example.com:8080"
+)
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token="YOUR_BOT_TOKEN",
+        connector=connector,  # Pass configured connector
+        logger=console_logger,
+    )
+)
+
+await handler.connect()
+```
+
+Or using environment variables:
+
+```python
+import os
+import aiohttp
+from aiohttp_socks import ProxyConnector
+
+proxy_url = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+connector = ProxyConnector.from_url(proxy_url) if proxy_url else None
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token=os.getenv("WEBEX_BOT_TOKEN"),
+        connector=connector,
+        logger=console_logger,
+    )
+)
+```
+
+Requires: `pip install aiohttp-socks[asyncio]`
+
 ## API Reference
 
 ### `WebexMessageHandler`
@@ -117,6 +162,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 |--------|------|---------|-------------|
 | `token` | `str` | required | Webex bot access token |
 | `logger` | `Logger` | noop | Custom logger (`console_logger` provided) |
+| `connector` | `aiohttp.BaseConnector` | `None` | HTTP/HTTPS connector for proxy support |
 | `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) |

{webex_message_handler-0.1.0 → webex_message_handler-0.3.0}/README.md

@@ -1,141 +1,187 @@
-# 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
+
+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.
+
+## Proxy Support (Enterprise)
+
+For corporate environments behind a proxy, pass a configured connector:
+
+```python
+import aiohttp
+from aiohttp_socks import ProxyConnector
+
+# Using HTTP/HTTPS proxy
+connector = ProxyConnector.from_url(
+    "http://proxy.example.com:8080"
+)
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token="YOUR_BOT_TOKEN",
+        connector=connector,  # Pass configured connector
+        logger=console_logger,
+    )
+)
+
+await handler.connect()
+```
+
+Or using environment variables:
+
+```python
+import os
+import aiohttp
+from aiohttp_socks import ProxyConnector
+
+proxy_url = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+connector = ProxyConnector.from_url(proxy_url) if proxy_url else None
+
+handler = WebexMessageHandler(
+    WebexMessageHandlerConfig(
+        token=os.getenv("WEBEX_BOT_TOKEN"),
+        connector=connector,
+        logger=console_logger,
+    )
+)
+```
+
+Requires: `pip install aiohttp-socks[asyncio]`
+
+## 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) |
+| `connector` | `aiohttp.BaseConnector` | `None` | HTTP/HTTPS connector for proxy support |
+| `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 → webex_message_handler-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.1.0"
+version = "0.3.0"
 description = "Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK"
 readme = "README.md"
 license = "MIT"

{webex_message_handler-0.1.0 → webex_message_handler-0.3.0}/src/webex_message_handler/__init__.py

@@ -19,13 +19,19 @@ from .types import (
     DecryptedMessage,
     DeletedMessage,
     DeviceRegistration,
+    FetchFunction,
+    FetchRequest,
+    FetchResponse,
     HandlerStatus,
+    InjectedWebSocket,
     MercuryActivity,
     MercuryActor,
     MercuryEnvelope,
     MercuryObject,
     MercuryTarget,
+    NetworkMode,
     WebexMessageHandlerConfig,
+    WebSocketFactory,
 )
 
 __all__ = [
@@ -59,4 +65,11 @@ __all__ = [
     "DeletedMessage",
     "HandlerStatus",
     "ConnectionStatus",
+    # Networking types
+    "NetworkMode",
+    "FetchRequest",
+    "FetchResponse",
+    "FetchFunction",
+    "InjectedWebSocket",
+    "WebSocketFactory",
 ]