signal-bot/signal_bot/models.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Parsing of signal-cli-rest-api envelopes into a flat, typed message."""

from __future__ import annotations

import json
from dataclasses import dataclass
from typing import Any


@dataclass(frozen=True, slots=True)
class IncomingMessage:
    """One inbound Signal message, normalised across envelope shapes.

    signal-cli reports messages from other people under ``dataMessage`` and
    the account's own outgoing messages under ``syncMessage.sentMessage``.
    The two carry the same fields at different depths; everything downstream
    works on this flattened form instead of re-deriving the nesting.
    """

    source_uuid: str
    source_name: str
    group_id: str | None
    text: str | None
    has_sticker: bool
    is_reaction: bool
    # The sender's +E.164 number. "source" carries it too, but only
    # sometimes: live envelopes have shown a display name there and the
    # number here, so this is the field a trust decision may rely on.
    source_number: str = ""
    # A group membership change rather than a message: this is the only
    # frame that names who added the bot to a group.
    is_group_update: bool = False
    # The sent timestamp, which is the id Signal quotes a message by.
    # Without it a reply can only be addressed to the room.
    timestamp: int = 0

    @property
    def is_direct_message(self) -> bool:
        """True when the message did not arrive via a group.

        A linked device receives every direct conversation on the account, so
        this is the discriminator that keeps the bot scoped to its group.
        """
        return self.group_id is None


def _timestamp(payload: dict[str, Any], envelope: dict[str, Any]) -> int:
    """The sent timestamp, preferring the payload's own over the envelope's.

    They agree on every frame seen so far, but a quote must point at the
    message, so the message's own value wins where they ever differ.
    """
    for source in (payload, envelope):
        value = source.get("timestamp")
        if isinstance(value, int):
            return value
    return 0


def _payload(envelope: dict[str, Any]) -> dict[str, Any] | None:
    """Return the dataMessage or sentMessage body, whichever is present."""
    data = envelope.get("dataMessage")
    if isinstance(data, dict):
        return data
    sync = envelope.get("syncMessage")
    if isinstance(sync, dict):
        sent = sync.get("sentMessage")
        if isinstance(sent, dict):
            return sent
    return None


def _group_id(payload: dict[str, Any]) -> str | None:
    """Return the group id, or None for a direct message."""
    info = payload.get("groupInfo")
    if not isinstance(info, dict):
        return None
    group_id = info.get("groupId")
    if not isinstance(group_id, str) or not group_id:
        return None
    return group_id


def _group_type(payload: dict[str, Any]) -> str:
    """Return the groupInfo type ("DELIVER", "UPDATE", ...), or ""."""
    info = payload.get("groupInfo")
    if not isinstance(info, dict):
        return ""
    group_type = info.get("type")
    return group_type if isinstance(group_type, str) else ""


def _text(payload: dict[str, Any]) -> str | None:
    """Return the message body, or None when there is no text."""
    message = payload.get("message")
    if not isinstance(message, str):
        return None
    return message


def parse_envelope(raw: str | bytes) -> IncomingMessage | None:
    """Parse one raw websocket frame.

    Args:
        raw: The JSON frame exactly as received.

    Returns:
        The normalised message, or None when the frame carries no message
        body at all (receipts, typing indicators, malformed JSON).
    """
    try:
        decoded = json.loads(raw)
    except json.JSONDecodeError, UnicodeDecodeError:
        return None
    if not isinstance(decoded, dict):
        return None

    envelope = decoded.get("envelope")
    if not isinstance(envelope, dict):
        return None

    payload = _payload(envelope)
    if payload is None:
        return None

    return IncomingMessage(
        source_uuid=str(envelope.get("sourceUuid", "")),
        source_name=str(envelope.get("sourceName", "")),
        group_id=_group_id(payload),
        text=_text(payload),
        # The original bot looked for the sticker under dataMessage even when
        # the envelope was a syncMessage, so its own stickers were never
        # filtered. Reading it off the resolved payload fixes both shapes.
        has_sticker=isinstance(payload.get("sticker"), dict),
        is_reaction=isinstance(payload.get("reaction"), dict),
        source_number=str(envelope.get("sourceNumber", "")),
        is_group_update=_group_type(payload) == "UPDATE",
        timestamp=_timestamp(payload, envelope),
    )