webex-message-handler 0.6.5__tar.gz → 0.6.7__tar.gz

{webex_message_handler-0.6.5 → webex_message_handler-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.5
+Version: 0.6.7
 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
@@ -71,6 +71,18 @@ async def on_message(msg):
 def on_deleted(data):
     print(f"Message {data.message_id} deleted by {data.person_id}")
 
+@handler.on("message:updated")
+async def on_updated(msg):
+    print(f"[EDIT] [{msg.person_email}] {msg.text}")
+
+@handler.on("attachmentAction:created")
+def on_card(action):
+    print(f"Card submitted by {action.person_email}: {action.inputs}")
+
+@handler.on("room:updated")
+def on_room_updated(room):
+    print(f"Room {room.room_id} updated by {room.actor_id}")
+
 @handler.on("connected")
 def on_connected():
     print("Connected to Webex")
@@ -214,6 +226,11 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 |-------|---------|-------------|
 | `message:created` | `DecryptedMessage` | New message received and decrypted |
 | `message:deleted` | `DeletedMessage` | Message was deleted |
+| `message:updated` | `DecryptedMessage` | Message was edited and re-decrypted |
+| `attachmentAction:created` | `AttachmentAction` | Adaptive Card submitted |
+| `room:created` | `RoomActivity` | New room/space created |
+| `room:updated` | `RoomActivity` | Room/space updated |
+| `membership:created` | `MembershipActivity` | Member added/removed or moderator changed |
 | `connected` | — | Connected/reconnected to Mercury |
 | `disconnected` | `reason: str` | Disconnected from Mercury |
 | `reconnecting` | `attempt: int` | Attempting to reconnect |
@@ -225,16 +242,64 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str
     person_email: str
     text: str
     created: str
     html: str | None
-    room_type: str | None   # "direct" | "group"
+    room_type: str | None        # "direct" | "group"
+    mentioned_people: list[str]  # Person UUIDs from <spark-mention> tags
+    mentioned_groups: list[str]  # e.g. ["all"] from group mentions
+    files: list[str]             # File attachment URLs
     raw: MercuryActivity | None
 ```
 
+### `AttachmentAction`
+
+Emitted when a user submits an Adaptive Card.
+
+```python
+@dataclass
+class AttachmentAction:
+    id: str               # Activity UUID
+    message_id: str       # Parent message containing the card
+    person_id: str        # Person who submitted
+    person_email: str
+    room_id: str
+    inputs: dict[str, Any]  # Card form data
+    created: str
+    raw: MercuryActivity
+```
+
+### `RoomActivity`
+
+Emitted for room lifecycle events.
+
+```python
+@dataclass
+class RoomActivity:
+    id: str             # Activity UUID
+    room_id: str
+    actor_id: str       # Person who triggered the event
+    action: str         # "create" or "update"
+    created: str
+    raw: MercuryActivity
+```
+
+### `parse_mentions(html)`
+
+Extracts mentions from decrypted HTML. Called automatically during decryption — the results populate `DecryptedMessage.mentioned_people` and `DecryptedMessage.mentioned_groups`. Exported for standalone use.
+
+```python
+from webex_message_handler import parse_mentions
+
+result = parse_mentions(msg.html)
+# result.mentioned_people: ["uuid-1", "uuid-2"]
+# result.mentioned_groups: ["all"]
+```
+
 ## Architecture
 
 ```

{webex_message_handler-0.6.5 → webex_message_handler-0.6.7}/README.md

@@ -39,6 +39,18 @@ async def on_message(msg):
 def on_deleted(data):
     print(f"Message {data.message_id} deleted by {data.person_id}")
 
+@handler.on("message:updated")
+async def on_updated(msg):
+    print(f"[EDIT] [{msg.person_email}] {msg.text}")
+
+@handler.on("attachmentAction:created")
+def on_card(action):
+    print(f"Card submitted by {action.person_email}: {action.inputs}")
+
+@handler.on("room:updated")
+def on_room_updated(room):
+    print(f"Room {room.room_id} updated by {room.actor_id}")
+
 @handler.on("connected")
 def on_connected():
     print("Connected to Webex")
@@ -182,6 +194,11 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 |-------|---------|-------------|
 | `message:created` | `DecryptedMessage` | New message received and decrypted |
 | `message:deleted` | `DeletedMessage` | Message was deleted |
+| `message:updated` | `DecryptedMessage` | Message was edited and re-decrypted |
+| `attachmentAction:created` | `AttachmentAction` | Adaptive Card submitted |
+| `room:created` | `RoomActivity` | New room/space created |
+| `room:updated` | `RoomActivity` | Room/space updated |
+| `membership:created` | `MembershipActivity` | Member added/removed or moderator changed |
 | `connected` | — | Connected/reconnected to Mercury |
 | `disconnected` | `reason: str` | Disconnected from Mercury |
 | `reconnecting` | `attempt: int` | Attempting to reconnect |
@@ -193,16 +210,64 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str
     person_email: str
     text: str
     created: str
     html: str | None
-    room_type: str | None   # "direct" | "group"
+    room_type: str | None        # "direct" | "group"
+    mentioned_people: list[str]  # Person UUIDs from <spark-mention> tags
+    mentioned_groups: list[str]  # e.g. ["all"] from group mentions
+    files: list[str]             # File attachment URLs
     raw: MercuryActivity | None
 ```
 
+### `AttachmentAction`
+
+Emitted when a user submits an Adaptive Card.
+
+```python
+@dataclass
+class AttachmentAction:
+    id: str               # Activity UUID
+    message_id: str       # Parent message containing the card
+    person_id: str        # Person who submitted
+    person_email: str
+    room_id: str
+    inputs: dict[str, Any]  # Card form data
+    created: str
+    raw: MercuryActivity
+```
+
+### `RoomActivity`
+
+Emitted for room lifecycle events.
+
+```python
+@dataclass
+class RoomActivity:
+    id: str             # Activity UUID
+    room_id: str
+    actor_id: str       # Person who triggered the event
+    action: str         # "create" or "update"
+    created: str
+    raw: MercuryActivity
+```
+
+### `parse_mentions(html)`
+
+Extracts mentions from decrypted HTML. Called automatically during decryption — the results populate `DecryptedMessage.mentioned_people` and `DecryptedMessage.mentioned_groups`. Exported for standalone use.
+
+```python
+from webex_message_handler import parse_mentions
+
+result = parse_mentions(msg.html)
+# result.mentioned_people: ["uuid-1", "uuid-2"]
+# result.mentioned_groups: ["all"]
+```
+
 ## Architecture
 
 ```

{webex_message_handler-0.6.5 → webex_message_handler-0.6.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.6.5"
+version = "0.6.7"
 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.5 → webex_message_handler-0.6.7}/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.5 → webex_message_handler-0.6.7}/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.7/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.5 → webex_message_handler-0.6.7}/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.5 → webex_message_handler-0.6.7}/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.5 → webex_message_handler-0.6.7}/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):