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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.1.0
+Version: 0.2.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.2.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.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.1.0"
+version = "0.2.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.2.0/src/webex_message_handler/device_manager.py

@@ -0,0 +1,150 @@
+"""WDM device registration, refresh, and unregistration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import aiohttp
+
+from .errors import AuthError, DeviceRegistrationError
+from .logger import Logger, noop_logger
+from .types import DeviceRegistration
+
+WDM_API_BASE = "https://wdm-a.wbx2.com/wdm/api/v1/devices"
+
+_DEVICE_BODY = {
+    "deviceName": "webex-message-handler",
+    "deviceType": "DESKTOP",
+    "localizedModel": "python",
+    "model": "python",
+    "name": "webex-message-handler",
+    "systemName": "webex-message-handler",
+    "systemVersion": "1.0.0",
+}
+
+
+class DeviceManager:
+    """Manages WDM device registration lifecycle."""
+
+    def __init__(
+        self,
+        *,
+        logger: Logger | None = None,
+        connector: aiohttp.BaseConnector | None = None,
+    ) -> None:
+        self._logger: Logger = logger or noop_logger  # type: ignore[assignment]
+        self._connector = connector
+        self._device_url: str | None = None
+
+    async def register(self, token: str) -> DeviceRegistration:
+        """Register a new device with WDM."""
+        self._logger.debug("Registering device with WDM")
+
+        try:
+            async with aiohttp.ClientSession(connector=self._connector) as session, session.post(
+                WDM_API_BASE,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json",
+                },
+                json=_DEVICE_BODY,
+            ) as response:
+                if response.status == 401:
+                    self._logger.error("Device registration failed: Unauthorized")
+                    raise AuthError("Unauthorized to register device")
+
+                if not response.ok:
+                    self._logger.error(f"Device registration failed with status {response.status}")
+                    raise DeviceRegistrationError("Failed to register device", response.status)
+
+                data = await response.json()
+                self._device_url = data["url"]
+                registration = self._parse_device_response(data)
+                self._logger.info("Device registered successfully")
+                return registration
+
+        except (AuthError, DeviceRegistrationError):
+            raise
+        except Exception as exc:
+            self._logger.error(f"Device registration error: {exc}")
+            raise DeviceRegistrationError("Failed to register device") from exc
+
+    async def refresh(self, token: str) -> DeviceRegistration:
+        """Refresh an existing device registration."""
+        if not self._device_url:
+            raise DeviceRegistrationError("Device not registered. Call register() first.")
+
+        self._logger.debug("Refreshing device registration")
+
+        try:
+            async with aiohttp.ClientSession(connector=self._connector) as session, session.put(
+                self._device_url,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json",
+                },
+                json=_DEVICE_BODY,
+            ) as response:
+                if response.status == 401:
+                    self._logger.error("Device refresh failed: Unauthorized")
+                    raise AuthError("Unauthorized to refresh device")
+
+                if not response.ok:
+                    self._logger.error(f"Device refresh failed with status {response.status}")
+                    raise DeviceRegistrationError("Failed to refresh device", response.status)
+
+                data = await response.json()
+                registration = self._parse_device_response(data)
+                self._logger.info("Device refreshed successfully")
+                return registration
+
+        except (AuthError, DeviceRegistrationError):
+            raise
+        except Exception as exc:
+            self._logger.error(f"Device refresh error: {exc}")
+            raise DeviceRegistrationError("Failed to refresh device") from exc
+
+    async def unregister(self, token: str) -> None:
+        """Unregister the device from WDM."""
+        if not self._device_url:
+            raise DeviceRegistrationError("Device not registered. Call register() first.")
+
+        self._logger.debug("Unregistering device")
+
+        try:
+            async with aiohttp.ClientSession(connector=self._connector) as session, session.delete(
+                self._device_url,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json",
+                },
+            ) as response:
+                if response.status == 401:
+                    self._logger.error("Device unregistration failed: Unauthorized")
+                    raise AuthError("Unauthorized to unregister device")
+
+                if not response.ok:
+                    self._logger.error(f"Device unregistration failed with status {response.status}")
+                    raise DeviceRegistrationError("Failed to unregister device", response.status)
+
+                self._device_url = None
+                self._logger.info("Device unregistered successfully")
+
+        except (AuthError, DeviceRegistrationError):
+            raise
+        except Exception as exc:
+            self._logger.error(f"Device unregistration error: {exc}")
+            raise DeviceRegistrationError("Failed to unregister device") from exc
+
+    def _parse_device_response(self, data: dict[str, Any]) -> DeviceRegistration:
+        services: dict[str, str] = data.get("services", {})
+        if not isinstance(services, dict):
+            services = {}
+
+        return DeviceRegistration(
+            web_socket_url=data["webSocketUrl"],
+            device_url=data["url"],
+            user_id=data["userId"],
+            services=services,
+            encryption_service_url=services.get("encryptionServiceUrl", ""),
+        )