webex-message-handler 0.6.9__tar.gz → 0.6.10__tar.gz

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.9
+Version: 0.6.10
 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
@@ -234,6 +234,27 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 - **`await reconnect(new_token)`** — Update token and re-establish connection
 - **`status()`** — Returns `HandlerStatus` health check
 - **`connected`** — `bool` property: whether currently connected
+- **`device_registration()`** — Read-only copy of the WDM registration (`None` before connect)
+- **`service_url(name)`** — Look up a single WDM service URL by name (`None` if unknown)
+
+##### Outbound calls from wrappers
+
+This library is **inbound-only** — it never makes outbound calls. If your wrapper
+needs to send something back to Webex (e.g. a Conversation-service read-receipt),
+discover the service base URL from the WDM catalog the library already holds
+rather than hardcoding cluster hostnames (which vary across clusters and orgs):
+
+```python
+# Resolve a cluster-correct service URL after connect()
+conv_url = handler.service_url("conversationServiceUrl")
+if conv_url:
+    # Build your outbound acknowledge/activity request against conv_url.
+    # The activity URL needed for the acknowledge object is msg.url.
+    ...
+
+# Or grab the whole (read-only) registration:
+reg = handler.device_registration()  # None before connect()
+```
 
 #### Events
 
@@ -257,6 +278,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    url: str | None         # Conversation-service activity URL (when present)
     parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/README.md

@@ -202,6 +202,27 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 - **`await reconnect(new_token)`** — Update token and re-establish connection
 - **`status()`** — Returns `HandlerStatus` health check
 - **`connected`** — `bool` property: whether currently connected
+- **`device_registration()`** — Read-only copy of the WDM registration (`None` before connect)
+- **`service_url(name)`** — Look up a single WDM service URL by name (`None` if unknown)
+
+##### Outbound calls from wrappers
+
+This library is **inbound-only** — it never makes outbound calls. If your wrapper
+needs to send something back to Webex (e.g. a Conversation-service read-receipt),
+discover the service base URL from the WDM catalog the library already holds
+rather than hardcoding cluster hostnames (which vary across clusters and orgs):
+
+```python
+# Resolve a cluster-correct service URL after connect()
+conv_url = handler.service_url("conversationServiceUrl")
+if conv_url:
+    # Build your outbound acknowledge/activity request against conv_url.
+    # The activity URL needed for the acknowledge object is msg.url.
+    ...
+
+# Or grab the whole (read-only) registration:
+reg = handler.device_registration()  # None before connect()
+```
 
 #### Events
 
@@ -225,6 +246,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    url: str | None         # Conversation-service activity URL (when present)
     parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.6.9"
+version = "0.6.10"
 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.6.9 → webex_message_handler-0.6.10}/src/webex_message_handler/handler.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import time
 from collections.abc import Callable
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any
 
 import aiohttp
@@ -208,7 +209,16 @@ class WebexMessageHandler:
     ) -> WebSocketFactory:
         """Create WebSocket adapter using native aiohttp."""
         async def ws_factory(url: str) -> InjectedWebSocket:
-            session = aiohttp.ClientSession(connector=connector)
+            # When a shared connector is provided, don't let the session close it
+            # when the WebSocket is rotated on reconnect — otherwise the next HTTP
+            # call (and every subsequent reconnect) fails with "Connector is closed".
+            # When no connector is provided, let the session own (and close) the
+            # auto-created one. Mirrors _create_native_http_adapter's ownership logic.
+            session = aiohttp.ClientSession(
+                connector=connector,
+                connector_owner=connector is None,
+                trust_env=True,
+            )
             ws = await session.ws_connect(url, max_msg_size=1 * 1024 * 1024)  # 1MB
 
             # Attach session for cleanup
@@ -389,6 +399,34 @@ class WebexMessageHandler:
             reconnect_attempt=reconnect_attempt,
         )
 
+    def device_registration(self) -> DeviceRegistration | None:
+        """Return a read-only copy of the WDM registration obtained at connect
+        time, or None if not yet connected.
+
+        This library stays inbound-only — it does not make outbound calls. This
+        accessor exists so wrapper code can perform its own outbound calls (e.g.
+        a Conversation-service read-receipt) using the service catalog the
+        library already holds. Resolve outbound URLs from ``services`` rather
+        than hardcoding cluster hostnames, which vary across clusters and orgs.
+
+        The returned value is a copy: mutating it does not affect internal state.
+        """
+        if self._registration is None:
+            return None
+        return replace(self._registration, services=dict(self._registration.services))
+
+    def service_url(self, name: str) -> str | None:
+        """Return the URL for a named WDM service from the registration's
+        service catalog (e.g. ``"conversationServiceUrl"``), or None if not yet
+        connected or the service is unknown.
+
+        Use this to discover outbound service base URLs instead of hardcoding
+        cluster hostnames. See :meth:`device_registration` for the rationale.
+        """
+        if self._registration is None:
+            return None
+        return self._registration.services.get(name)
+
     async def _fetch_bot_person_id(self) -> None:
         """Fetch the bot's person ID for self-message filtering.
 
@@ -490,6 +528,7 @@ class WebexMessageHandler:
             mentions = parse_mentions(decrypted.object.content)
             message = DecryptedMessage(
                 id=decrypted.id,
+                url=decrypted.url,
                 room_id=decrypted.target.id,
                 person_id=decrypted.actor.id,
                 person_email=decrypted.actor.email_address or "",

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/src/webex_message_handler/mercury_socket.py

@@ -421,6 +421,7 @@ def _parse_activity(raw: dict[str, Any]) -> MercuryActivity:
             tags=target_raw.get("tags", []),
         ),
         published=raw.get("published", ""),
+        url=raw.get("url"),
         encryption_key_url=raw.get("encryptionKeyUrl"),
         parent=parent,
     )

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/src/webex_message_handler/types.py

@@ -188,6 +188,9 @@ class MercuryActivity:
     object: MercuryObject
     target: MercuryTarget
     published: str
+    url: str | None = None
+    """Full Conversation-service activity URL, when present on the raw activity."""
+
     encryption_key_url: str | None = None
     parent: MercuryParent | None = None
 
@@ -227,6 +230,11 @@ class DecryptedMessage:
     created: str
     """ISO 8601 timestamp."""
 
+    url: str | None = None
+    """Full Conversation-service activity URL, when present on the raw Mercury
+    activity (e.g. for an outbound "acknowledge" read-receipt). None if Mercury
+    did not include it."""
+
     parent_id: str | None = None
     """Parent activity UUID for threaded replies. None if not a thread reply."""
 

{webex_message_handler-0.6.9 → webex_message_handler-0.6.10}/tests/test_handler.py

@@ -7,6 +7,7 @@ import pytest
 from webex_message_handler.handler import WebexMessageHandler
 from webex_message_handler.types import (
     DeviceRegistration,
+    FetchRequest,
     MercuryActivity,
     MercuryActor,
     MercuryObject,
@@ -109,6 +110,83 @@ class TestModeValidation:
             _make_handler(mode="invalid")
 
 
+class TestNativeConnectorOwnership:
+    """Regression tests for issue #20: a shared connector must survive WebSocket
+    rotation on reconnect. The WS session must not own (and therefore close) a
+    caller-provided connector."""
+
+    async def test_ws_adapter_does_not_own_shared_connector(self):
+        shared_connector = MagicMock()
+        handler = _make_handler(mode="native", connector=shared_connector)
+
+        captured = {}
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def ws_connect(self, *args, **kwargs):
+                return MagicMock()
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._ws_factory("wss://mercury.example.com/socket")
+
+        # The WS session must not own the shared connector, otherwise closing the
+        # session on reconnect drags the shared connector down with it.
+        assert captured["connector"] is shared_connector
+        assert captured["connector_owner"] is False
+
+    async def test_ws_adapter_owns_auto_created_connector(self):
+        handler = _make_handler(mode="native")  # no connector → auto-created
+
+        captured = {}
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def ws_connect(self, *args, **kwargs):
+                return MagicMock()
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._ws_factory("wss://mercury.example.com/socket")
+
+        # With no shared connector, the session owns the auto-created one and
+        # is responsible for closing it.
+        assert captured["connector"] is None
+        assert captured["connector_owner"] is True
+
+    async def test_http_adapter_does_not_own_shared_connector(self):
+        shared_connector = MagicMock()
+        handler = _make_handler(mode="native", connector=shared_connector)
+
+        captured = {}
+
+        class FakeResponse:
+            status = 200
+
+            async def read(self):
+                return b"{}"
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def request(self, *args, **kwargs):
+                return FakeResponse()
+
+            async def close(self):
+                pass
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._http_do(
+                FetchRequest(url="https://example.com", method="GET", headers={})
+            )
+
+        assert captured["connector"] is shared_connector
+        assert captured["connector_owner"] is False
+
+
 class TestConnect:
     @patch("webex_message_handler.handler.MessageDecryptor")
     @patch("webex_message_handler.handler.KmsClient")
@@ -256,6 +334,22 @@ class TestMessageHandling:
         assert msg.id == "msg-123"
         assert msg.parent_id == "parent-activity-uuid"
 
+    async def test_handle_message_propagates_url(self):
+        handler = _make_handler()
+        handler._message_decryptor = MagicMock()
+        activity = _make_activity(
+            url="https://conv-a.wbx2.com/conversation/api/v1/activities/msg-123",
+        )
+        handler._message_decryptor.decrypt_activity = AsyncMock(return_value=activity)
+
+        messages = []
+        handler.on("message:created", lambda msg: messages.append(msg))
+
+        await handler._handle_activity(activity)
+
+        assert len(messages) == 1
+        assert messages[0].url == "https://conv-a.wbx2.com/conversation/api/v1/activities/msg-123"
+
     async def test_handle_message_deleted(self):
         handler = _make_handler()
         activity = _make_activity(
@@ -458,3 +552,42 @@ class TestEventSystem:
         handler.on("connected", callback)
         handler.off("connected", callback)
         assert callback not in handler._listeners["connected"]
+
+
+class TestDeviceRegistrationAccessor:
+    """Issue #23: expose the WDM services catalog read-only so wrappers can make
+    outbound calls without hardcoding cluster hostnames."""
+
+    def test_returns_none_before_connect(self):
+        handler = _make_handler()
+        assert handler.device_registration() is None
+        assert handler.service_url("conversationServiceUrl") is None
+
+    def test_returns_registration_after_connect(self):
+        handler = _make_handler()
+        handler._registration = MOCK_REGISTRATION
+
+        reg = handler.device_registration()
+        assert reg is not None
+        assert reg.user_id == "user-123"
+        assert reg.services["encryptionServiceUrl"] == "https://encryption.example.com"
+        assert handler.service_url("messenger") == "https://messenger.example.com"
+        assert handler.service_url("nonexistent") is None
+
+    def test_returned_copy_is_isolated(self):
+        handler = _make_handler()
+        handler._registration = DeviceRegistration(
+            web_socket_url="wss://mercury.example.com/socket",
+            device_url="https://device.example.com",
+            user_id="user-123",
+            services={"encryptionServiceUrl": "https://encryption.example.com"},
+            encryption_service_url="https://encryption.example.com",
+        )
+
+        reg = handler.device_registration()
+        reg.services["encryptionServiceUrl"] = "https://evil.example.com"
+        reg.user_id = "tampered"
+
+        # Internal state must be unaffected by mutating the returned copy.
+        assert handler._registration.services["encryptionServiceUrl"] == "https://encryption.example.com"
+        assert handler._registration.user_id == "user-123"