webex-message-handler 0.6.4__tar.gz → 0.6.6__tar.gz

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.4
+Version: 0.6.6
 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
@@ -155,6 +155,26 @@ handler = WebexMessageHandler(
 
 Requires: `pip install aiohttp-socks[asyncio]`
 
+## Threading & Message IDs
+
+Mercury uses raw activity UUIDs while the Webex REST API uses base64-encoded IDs. Use the conversion utilities to bridge them:
+
+```python
+from webex_message_handler import to_rest_id, from_rest_id
+
+@handler.on("message:created")
+async def on_message(msg):
+    # Convert Mercury UUID to REST API ID for GET requests
+    rest_id = to_rest_id(msg.id, "MESSAGE")
+
+    # Thread replies: msg.parent_id contains the parent activity UUID
+    if msg.parent_id:
+        # Use msg.parent_id as parentId in POST /v1/messages
+        pass
+```
+
+Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
+
 ## API Reference
 
 ### `WebexMessageHandler`

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/README.md

@@ -123,6 +123,26 @@ handler = WebexMessageHandler(
 
 Requires: `pip install aiohttp-socks[asyncio]`
 
+## Threading & Message IDs
+
+Mercury uses raw activity UUIDs while the Webex REST API uses base64-encoded IDs. Use the conversion utilities to bridge them:
+
+```python
+from webex_message_handler import to_rest_id, from_rest_id
+
+@handler.on("message:created")
+async def on_message(msg):
+    # Convert Mercury UUID to REST API ID for GET requests
+    rest_id = to_rest_id(msg.id, "MESSAGE")
+
+    # Thread replies: msg.parent_id contains the parent activity UUID
+    if msg.parent_id:
+        # Use msg.parent_id as parentId in POST /v1/messages
+        pass
+```
+
+Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
+
 ## API Reference
 
 ### `WebexMessageHandler`

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/pyproject.toml

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

@@ -13,9 +13,11 @@ from .handler import WebexMessageHandler
 from .id_utils import from_rest_id, to_rest_id
 from .kms_client import KmsClient
 from .logger import Logger, console_logger, noop_logger
+from .mention_parser import ParsedMentions, parse_mentions
 from .mercury_socket import MercurySocket
 from .message_decryptor import MessageDecryptor
 from .types import (
+    AttachmentAction,
     ConnectionStatus,
     DecryptedMessage,
     DeletedMessage,
@@ -33,6 +35,7 @@ from .types import (
     MercuryParent,
     MercuryTarget,
     NetworkMode,
+    RoomActivity,
     WebexMessageHandlerConfig,
     WebSocketFactory,
 )
@@ -45,6 +48,9 @@ __all__ = [
     "MercurySocket",
     "KmsClient",
     "MessageDecryptor",
+    # Mention parsing
+    "ParsedMentions",
+    "parse_mentions",
     # Errors
     "WebexError",
     "AuthError",
@@ -71,6 +77,8 @@ __all__ = [
     "DecryptedMessage",
     "DeletedMessage",
     "MembershipActivity",
+    "AttachmentAction",
+    "RoomActivity",
     "HandlerStatus",
     "ConnectionStatus",
     # Networking types

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/src/webex_message_handler/handler.py

@@ -12,9 +12,11 @@ import aiohttp
 from .device_manager import DeviceManager
 from .kms_client import KmsClient
 from .logger import Logger, noop_logger
+from .mention_parser import parse_mentions
 from .mercury_socket import MercurySocket
 from .message_decryptor import MessageDecryptor
 from .types import (
+    AttachmentAction,
     ConnectionStatus,
     DecryptedMessage,
     DeletedMessage,
@@ -26,6 +28,7 @@ from .types import (
     InjectedWebSocket,
     MembershipActivity,
     MercuryActivity,
+    RoomActivity,
     WebexMessageHandlerConfig,
     WebSocketFactory,
 )
@@ -135,8 +138,12 @@ class WebexMessageHandler:
         # Event listeners
         self._listeners: dict[str, list[EventCallback]] = {
             "message:created": [],
+            "message:updated": [],
             "message:deleted": [],
             "membership:created": [],
+            "attachmentAction:created": [],
+            "room:created": [],
+            "room:updated": [],
             "connected": [],
             "disconnected": [],
             "reconnecting": [],
@@ -455,13 +462,14 @@ class WebexMessageHandler:
         if len(self._recent_activity_ids) % 100 == 0:
             self._sweep_old_activity_ids()
 
-        # message:created — verb=post + objectType=comment
-        if activity.verb == "post" and activity.object.object_type == "comment":
+        # message:created or message:updated — verb=post/update + objectType=comment
+        if activity.verb in ("post", "update") and activity.object.object_type == "comment":
             if not self._message_decryptor:
                 self._logger.warning("Received activity but decryptor not initialized")
                 return
 
             decrypted = await self._message_decryptor.decrypt_activity(activity)
+            mentions = parse_mentions(decrypted.object.content)
             message = DecryptedMessage(
                 id=decrypted.id,
                 room_id=decrypted.target.id,
@@ -470,6 +478,9 @@ class WebexMessageHandler:
                 text=decrypted.object.display_name or "",
                 created=decrypted.published,
                 parent_id=decrypted.parent.id if decrypted.parent else None,
+                mentioned_people=mentions.mentioned_people,
+                mentioned_groups=mentions.mentioned_groups,
+                files=decrypted.object.files or [],
                 html=decrypted.object.content,
                 room_type=self._infer_room_type(decrypted),
                 raw=decrypted,
@@ -483,7 +494,8 @@ class WebexMessageHandler:
                 self._logger.debug(f"Ignoring self-message from bot ({self._bot_person_id})")
                 return
 
-            self._emit("message:created", message)
+            event_name = "message:updated" if activity.verb == "update" else "message:created"
+            self._emit(event_name, message)
             return
 
         # message:deleted — verb=delete + objectType=activity
@@ -515,6 +527,39 @@ class WebexMessageHandler:
                     raw=activity,
                 ),
             )
+            return
+
+        # attachmentAction:created — verb=cardAction + objectType=submit
+        if activity.verb == "cardAction" and activity.object.object_type == "submit":
+            self._emit(
+                "attachmentAction:created",
+                AttachmentAction(
+                    id=activity.id,
+                    message_id=activity.parent.id if activity.parent else "",
+                    person_id=activity.actor.id,
+                    person_email=activity.actor.email_address or "",
+                    room_id=activity.target.id,
+                    inputs=activity.object.inputs or {},
+                    created=activity.published,
+                    raw=activity,
+                ),
+            )
+            return
+
+        # room:created or room:updated — verb=create/update + object.objectType=conversation
+        if activity.verb in ("create", "update") and activity.object.object_type == "conversation":
+            event_name = "room:created" if activity.verb == "create" else "room:updated"
+            self._emit(
+                event_name,
+                RoomActivity(
+                    id=activity.id,
+                    room_id=activity.target.id,
+                    actor_id=activity.actor.id,
+                    action="created" if activity.verb == "create" else "updated",
+                    created=activity.published,
+                    raw=activity,
+                ),
+            )
 
     @staticmethod
     def _infer_room_type(activity: MercuryActivity) -> str | None:

webex_message_handler-0.6.6/src/webex_message_handler/mention_parser.py

@@ -0,0 +1,59 @@
+"""Parse Webex ``<spark-mention>`` tags from decrypted HTML."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParsedMentions:
+    """Mentions extracted from message HTML."""
+
+    mentioned_people: list[str] = field(default_factory=list)
+    mentioned_groups: list[str] = field(default_factory=list)
+
+
+_MENTION_RE = re.compile(
+    r'<spark-mention[^>]*data-object-type="([^"]*)"[^>]*>', re.IGNORECASE
+)
+_PERSON_ID_RE = re.compile(r'data-object-id="([^"]*)"', re.IGNORECASE)
+_GROUP_TYPE_RE = re.compile(r'data-group-type="([^"]*)"', re.IGNORECASE)
+
+
+def parse_mentions(html: str | None) -> ParsedMentions:
+    """Extract mentioned people and groups from decrypted HTML.
+
+    Parses ``<spark-mention>`` tags to find person UUIDs and group
+    mention types (e.g. ``"all"``). Duplicates are removed.
+
+    Args:
+        html: Decrypted HTML content from a Webex message.
+
+    Returns:
+        ParsedMentions with ``mentioned_people`` and ``mentioned_groups``.
+    """
+    result = ParsedMentions()
+    if not html:
+        return result
+
+    seen: set[str] = set()
+
+    for match in _MENTION_RE.finditer(html):
+        tag = match.group(0)
+        object_type = match.group(1)
+
+        if object_type == "person":
+            id_match = _PERSON_ID_RE.search(tag)
+            if id_match and id_match.group(1) and id_match.group(1) not in seen:
+                seen.add(id_match.group(1))
+                result.mentioned_people.append(id_match.group(1))
+        elif object_type == "groupMention":
+            group_match = _GROUP_TYPE_RE.search(tag)
+            if group_match and group_match.group(1):
+                key = f"group:{group_match.group(1)}"
+                if key not in seen:
+                    seen.add(key)
+                    result.mentioned_groups.append(group_match.group(1))
+
+    return result

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/src/webex_message_handler/mercury_socket.py

@@ -411,6 +411,8 @@ def _parse_activity(raw: dict[str, Any]) -> MercuryActivity:
             display_name=object_raw.get("displayName"),
             content=object_raw.get("content"),
             encryption_key_url=object_raw.get("encryptionKeyUrl"),
+            inputs=object_raw.get("inputs"),
+            files=object_raw.get("files"),
         ),
         target=MercuryTarget(
             id=target_raw.get("id", ""),

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/src/webex_message_handler/types.py

@@ -158,6 +158,11 @@ class MercuryObject:
     display_name: str | None = None
     content: str | None = None
     encryption_key_url: str | None = None
+    inputs: dict[str, Any] | None = None
+    """Card form input values (present on cardAction/submit activities)."""
+
+    files: list[str] | None = None
+    """File URLs attached to the message (present on file-share messages)."""
 
 
 @dataclass
@@ -222,6 +227,15 @@ class DecryptedMessage:
     parent_id: str | None = None
     """Parent activity UUID for threaded replies. None if not a thread reply."""
 
+    mentioned_people: list[str] = field(default_factory=list)
+    """Person UUIDs mentioned via @mention in the message."""
+
+    mentioned_groups: list[str] = field(default_factory=list)
+    """Group mention types (e.g. 'all') in the message."""
+
+    files: list[str] = field(default_factory=list)
+    """File URLs attached to the message."""
+
     html: str | None = None
     """Decrypted HTML content (rich text messages)."""
 
@@ -270,6 +284,58 @@ class MembershipActivity:
     """Full raw activity for advanced use."""
 
 
+@dataclass
+class AttachmentAction:
+    """An adaptive card submission from Mercury."""
+
+    id: str
+    """Activity ID."""
+
+    message_id: str
+    """ID of the message the card was attached to."""
+
+    person_id: str
+    """ID of the person who submitted the card."""
+
+    person_email: str
+    """Email of the person who submitted the card."""
+
+    room_id: str
+    """Conversation/space ID."""
+
+    inputs: dict[str, Any]
+    """Card form input values."""
+
+    created: str
+    """ISO 8601 timestamp."""
+
+    raw: MercuryActivity | None = None
+    """Full raw activity for advanced use."""
+
+
+@dataclass
+class RoomActivity:
+    """A room event from Mercury."""
+
+    id: str
+    """Activity ID."""
+
+    room_id: str
+    """Conversation/space ID."""
+
+    actor_id: str
+    """ID of the person who performed the action."""
+
+    action: str
+    """Room action: 'created' or 'updated'."""
+
+    created: str
+    """ISO 8601 timestamp."""
+
+    raw: MercuryActivity | None = None
+    """Full raw activity for advanced use."""
+
+
 # --- Status ---
 
 ConnectionStatus = Literal["connected", "connecting", "reconnecting", "disconnected"]

{webex_message_handler-0.6.4 → webex_message_handler-0.6.6}/tests/test_handler.py

@@ -276,16 +276,19 @@ class TestMessageHandling:
     async def test_ignores_non_message_activities(self):
         handler = _make_handler()
         handler._message_decryptor = MagicMock()
-        handler._message_decryptor.decrypt_activity = AsyncMock(return_value=_make_activity(verb="update"))
+        handler._message_decryptor.decrypt_activity = AsyncMock(return_value=_make_activity(verb="acknowledge"))
 
         messages = []
+        updated = []
         deleted = []
         handler.on("message:created", lambda msg: messages.append(msg))
+        handler.on("message:updated", lambda msg: updated.append(msg))
         handler.on("message:deleted", lambda d: deleted.append(d))
 
-        await handler._handle_activity(_make_activity(verb="update"))
+        await handler._handle_activity(_make_activity(verb="acknowledge"))
 
         assert len(messages) == 0
+        assert len(updated) == 0
         assert len(deleted) == 0
 
     async def test_ignores_post_non_comment(self):