mud_server.db.chat_repo
=======================

.. py:module:: mud_server.db.chat_repo

.. autoapi-nested-parse::

   Chat repository operations for the SQLite backend.

   This module isolates room/whisper chat persistence from the compatibility
   facade in ``mud_server.db.database``.



Functions
---------

.. autoapisummary::

   mud_server.db.chat_repo.add_chat_message
   mud_server.db.chat_repo.prune_chat_messages
   mud_server.db.chat_repo.get_room_messages


Module Contents
---------------

.. py:function:: add_chat_message(character_name, message, room, recipient_character_name = None, recipient = None, *, world_id)

   Insert a chat message row for room chat or whispers.

   Compatibility behavior:
   - ``recipient`` alias is still accepted and mapped to
     ``recipient_character_name``.
   - Sender and recipient names require explicit character identities.


.. py:function:: prune_chat_messages(max_age_hours, *, world_id = None, room = None)

   Delete chat messages older than max_age_hours.

   :param max_age_hours: Delete messages with timestamp older than this many hours.
                         Must be a positive integer (>= 1).
   :param world_id: If provided, restrict deletion to this world only.
   :param room: If provided (requires world_id), restrict to a single room.

   :returns: Number of rows deleted.

   :raises ValueError: If max_age_hours < 1 or room is provided without world_id.
   :raises DatabaseWriteError: On SQLite failure.


.. py:function:: get_room_messages(room, *, limit = 50, character_name = None, username = None, world_id)

   Return recent room messages with whisper visibility filtering.

   When a character identity is provided, this returns:
   - public messages in the room,
   - whispers to that character,
   - whispers sent by that character.