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
    # contentType of each attachment, in the order Signal listed them.
    # Empty for a text-only message.
    attachment_types: tuple[str, ...] = ()
    # The server-side id of each attachment. A parallel tuple
    # rather than a richer attachment_types, so counting.media_kind,
    # counting.should_count and stats.recorder keep reading exactly what they
    # always read. !add_photo is the only thing that needs the id: it is what
    # GET /v1/attachments/{id} fetches and what DELETE removes afterwards.
    attachment_ids: tuple[str, ...] = ()
    # True when this message quotes another one.
    is_reply: bool = False
    # True when the bot's own account sent this. Taken from *which* envelope
    # branch carried the payload, not from comparing identities: the account
    # is spelled as a uuid on some frames and a +E.164 number on others, so
    # any comparison misses one of them. syncMessage.sentMessage means "this
    # account sent it", exactly, on every frame shape.
    is_own: bool = False

    @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]) -> tuple[dict[str, Any], bool] | None:
    """Return the message body and whether the bot's own account sent it.

    signal-cli reports other people under ``dataMessage`` and this account's
    own outgoing messages under ``syncMessage.sentMessage``. Which branch
    matched is the only reliable "did we send this" signal, so it is returned
    rather than re-derived downstream.
    """
    data = envelope.get("dataMessage")
    if isinstance(data, dict):
        return data, False
    sync = envelope.get("syncMessage")
    if isinstance(sync, dict):
        sent = sync.get("sentMessage")
        if isinstance(sent, dict):
            return sent, True
    return None


def _attachment_items(payload: dict[str, Any]) -> list[dict[str, Any]]:
    """The attachment objects on this payload, read off the top level only.

    Never out of ``quote``: a reply carries the *quoted* message's media in
    ``quote.attachments``, so a search for "attachments" anywhere in the
    payload would let "!add_photo" steal a photo somebody else posted.
    """
    items = payload.get("attachments")
    if not isinstance(items, list):
        return []
    return [item for item in items if isinstance(item, dict)]


def _attachments(payload: dict[str, Any]) -> tuple[str, ...]:
    """Return each attachment's contentType, in the order Signal listed them."""
    return tuple(str(item.get("contentType", "")) for item in _attachment_items(payload))


def _attachment_ids(payload: dict[str, Any]) -> tuple[str, ...]:
    """Return the server-side id of every attachment that has one.

    An attachment with no id is dropped rather than carried as "": the id is
    only ever used to fetch bytes, and a blank one is a request that cannot
    succeed. That means this tuple can be shorter than attachment_types, so
    the two are not safe to zip -- nothing does, and nothing should.
    """
    return tuple(str(item["id"]) for item in _attachment_items(payload) if str(item.get("id", "")))


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

    resolved = _payload(envelope)
    if resolved is None:
        return None
    payload, is_own = resolved

    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),
        attachment_types=_attachments(payload),
        attachment_ids=_attachment_ids(payload),
        is_reply=isinstance(payload.get("quote"), dict),
        is_own=is_own,
    )