@spec add_message(target(), String.t() | ExWapp.JID.t(), message()) ::
  :ok | {:error, term()}

Adds a message to a chat.

@spec all_messages(target(), String.t() | ExWapp.JID.t(), keyword()) :: Enumerable.t()

Returns a lazy stream over every locally retained message, oldest first.

@spec archive(target(), String.t()) :: :ok

Archives a chat.

@spec delete(target(), String.t()) :: :ok | {:error, term()}

Deletes a chat.

@spec delete_messages(target(), String.t() | ExWapp.JID.t(), [String.t()]) ::
  :ok | {:error, term()}

Deletes selected local messages after they have been persisted elsewhere.

@spec find_message(target(), String.t() | ExWapp.JID.t(), String.t()) ::
  message() | nil

Finds one locally stored message in a chat.

@spec find_message_by_id(target(), String.t()) :: {String.t(), message()} | nil

Finds one locally stored message by ID across all chats.

@spec get(target(), String.t() | ExWapp.JID.t()) ::
  {:ok, chat()} | {:error, :not_found}

Gets a specific chat by JID.

@spec get_or_create(target(), String.t() | ExWapp.JID.t(), keyword()) :: chat()

Gets or creates a chat for a JID.

@spec list(target()) :: [chat()]

Lists all chats for a session.

Returns a list of chat structs sorted by last message timestamp (most recent first).

@spec list_groups(target()) :: [chat()]

Lists only group chats for a session.

@spec mark_read(target(), String.t() | ExWapp.JID.t()) :: :ok

Marks all messages in a chat as read.

@spec mark_read_from_sync(target(), String.t(), map()) :: :ok

Mark chat as read/unread from app state sync dispatch.

@spec merge_messages(target(), String.t() | ExWapp.JID.t(), [message()]) ::
  :ok | {:error, term()}

Merges a batch of messages into a chat, deduplicating by message ID.

@spec merge_metadata(target(), String.t() | ExWapp.JID.t(), map() | keyword()) :: :ok

Upserts metadata fields for a chat from sync/notification payloads.

Supported keys:

• :name
• :unread_count
• :last_message_timestamp
• :pinned
• :muted_until
• :archived
• :is_group

@spec messages(target(), String.t() | ExWapp.JID.t(), keyword()) :: [message()]

Gets a materialized page of locally retained messages, newest first.

Message payloads live in the configured message store rather than in the chat struct. Use stream_messages/3 for an unbounded, lazy traversal.

@spec new_chat(
  String.t(),
  keyword()
) :: chat()

Creates a new chat struct.

@spec parse_message_node(ExWapp.Binary.Node.t()) ::
  {:ok, String.t(), message()} | {:error, term()}

Parses a received message node into a message struct.

@spec pin(target(), String.t()) :: :ok

Pins a chat.

@spec stream_messages(target(), String.t() | ExWapp.JID.t(), keyword()) ::
  Enumerable.t()

Builds a lazy stream over locally retained messages.

The default order is oldest first so a wrapper can persist history in chronological order. The stream reads one indexed record at a time and does not first load the complete chat history.

This is local history only; it does not request older messages from WhatsApp.

@spec unarchive(target(), String.t()) :: :ok

Unarchives a chat.

@spec unpin(target(), String.t()) :: :ok

Unpins a chat.

@spec update_archived(target(), String.t(), boolean()) :: :ok

Update archived state from app state sync dispatch.

@spec update_message_status(
  target(),
  String.t() | ExWapp.JID.t(),
  String.t(),
  message_status()
) ::
  :ok | {:error, term()}

Updates a message status.

@spec update_message_status_by_id(target(), String.t(), message_status()) ::
  :ok | {:error, term()}

Updates a message status by message ID across all chats.

Useful for ACK nodes that do not provide a chat JID we can trust.

@spec update_muted(target(), String.t(), map()) :: :ok

Update muted state from app state sync dispatch.

@spec update_name(target(), String.t(), String.t()) :: :ok

Updates the chat name (for contacts that send push names).

@spec update_pinned(target(), String.t(), boolean()) :: :ok

Update pinned state from app state sync dispatch.