@spec all_messages(ExWapp.Client.t(), String.t(), keyword()) ::
  read_result(Enumerable.t())

Returns a lazy stream over every locally retained message.

@spec connect(ExWapp.Client.t()) :: {:ok, ExWapp.Client.t()} | client_error()

Connects a client through its configured transport adapter.

Emits client connect telemetry and records a status event when the transport succeeds.

@spec create_contact(ExWapp.Client.t(), String.t(), String.t()) :: mutation_result()

Creates a contact through the configured transport adapter.

@spec delete_contact(ExWapp.Client.t(), String.t()) :: mutation_result()

Deletes a contact through the configured transport adapter.

@spec delete_messages(ExWapp.Client.t(), String.t(), [String.t()]) ::
  mutation_result()

Deletes selected local messages after durable wrapper persistence.

@spec diagnostics(ExWapp.Client.t()) :: map()

Returns a compact diagnostics map for logging, debugging, or health checks.

@spec disconnect(ExWapp.Client.t()) :: {:ok, ExWapp.Client.t()} | client_error()

Disconnects a client through its configured transport adapter.

@spec download_media(ExWapp.Client.t(), ExWapp.Media.Ref.t(), keyword()) ::
  download_result()

Downloads and decrypts a media reference through the configured transport.

@spec get_call(ExWapp.Client.t(), String.t()) :: read_result(ExWapp.Call.t())

Fetches one stored call log entry by call ID through the configured transport.

@spec get_chat(ExWapp.Client.t(), String.t()) :: read_result(ExWapp.Chat.chat())

Fetches one chat by JID through the configured transport adapter.

@spec get_contact(ExWapp.Client.t(), String.t()) ::
  read_result(ExWapp.Contact.t() | nil)

Fetches one contact by JID through the configured transport adapter.

@spec get_messages(ExWapp.Client.t(), String.t(), keyword()) ::
  read_result([ExWapp.Chat.message()])

Gets locally retained messages for a chat through the configured transport.

The :limit option accepts a non-negative integer or :all; :offset skips messages from the newest-first result.

@spec last_error(ExWapp.Client.t()) :: ExWapp.Error.t() | nil

Returns the most recent structured client error, if any.

@spec list_calls(
  ExWapp.Client.t(),
  keyword()
) :: read_result([ExWapp.Call.t()])

Lists locally stored call log entries through the configured transport.

Accepts the same options as ExWapp.Call.list/2 (:limit, :status, :since, ...).

@spec list_chats(ExWapp.Client.t()) :: read_result([ExWapp.Chat.chat()])

Lists chats through the configured transport adapter.

@spec list_contacts(ExWapp.Client.t()) :: read_result([ExWapp.Contact.t()])

Lists contacts through the configured transport adapter.

@spec list_groups(ExWapp.Client.t()) :: read_result([ExWapp.Chat.chat()])

Lists group chats through the configured transport adapter.

@spec pair(ExWapp.Client.t()) :: {:ok, ExWapp.Client.t(), term()} | client_error()

Starts pairing through the configured transport adapter.

On success the client moves to :pairing and a QR event is emitted with the transport payload.

@spec receive_message(ExWapp.Client.t(), term(), keyword()) ::
  {:ok, ExWapp.Client.t(), [ExWapp.Event.t()]} | client_error()

Handles an inbound transport payload and emits any returned events.

@spec send_audio(ExWapp.Client.t(), String.t(), ExWapp.Media.source(), keyword()) ::
  message_result()

Sends an audio message through the configured transport adapter.

@spec send_contact(ExWapp.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  message_result()

Sends a WhatsApp contact card through the configured transport adapter.

@spec send_document(ExWapp.Client.t(), String.t(), ExWapp.Media.source(), keyword()) ::
  message_result()

Sends a document message through the configured transport adapter.

@spec send_event(
  ExWapp.Client.t(),
  String.t(),
  String.t(),
  integer() | DateTime.t(),
  keyword()
) :: message_result()

Sends WhatsApp's calendar event message through the configured transport.

@spec send_image(ExWapp.Client.t(), String.t(), ExWapp.Media.source(), keyword()) ::
  message_result()

Sends an image message through the configured transport adapter.

@spec send_location(ExWapp.Client.t(), String.t(), number(), number(), keyword()) ::
  message_result()

Sends a GPS location through the configured transport adapter.

@spec send_message(
  ExWapp.Client.t(),
  keyword()
) :: message_result()

Sends a text message from keyword options.

Required options are :to and :text; remaining options are passed to ExWapp.Message.text/3.

@spec status(ExWapp.Client.t()) :: ExWapp.Client.status()

Returns the current client status.

@spec stream_messages(ExWapp.Client.t(), String.t(), keyword()) ::
  read_result(Enumerable.t())

Builds a lazy stream over locally retained messages.

The stream is oldest first by default and delegates cursor ownership to the configured adapter. It does not trigger remote WhatsApp history retrieval.

@spec sync_contacts(ExWapp.Client.t()) :: mutation_result()

Synchronizes contacts through the configured transport adapter.