# `ExWapp.Client.API`
[🔗](https://github.com/elchemista/ex_wapp/blob/v0.1.5/lib/ex_wapp/client/api.ex#L1)

Runtime-neutral operations for `ExWapp.Client`.

This module contains the high-level client workflow used by the public
`ExWapp` facade. It coordinates transport adapters, client status updates,
telemetry, tracing, and event emission without depending on a session process
directly.

# `client_error`

```elixir
@type client_error() :: {:error, ExWapp.Error.t(), ExWapp.Client.t()}
```

# `download_result`

```elixir
@type download_result() ::
  {:ok, ExWapp.Client.t(), ExWapp.Media.Download.t()} | client_error()
```

# `message_result`

```elixir
@type message_result() :: {:ok, ExWapp.Client.t(), String.t()} | client_error()
```

# `mutation_result`

```elixir
@type mutation_result() :: {:ok, ExWapp.Client.t()} | client_error()
```

# `all_messages`

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

Returns a lazy stream over every locally retained message.

# `connect`

```elixir
@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.

# `create_contact`

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

Creates a contact through the configured transport adapter.

# `delete_contact`

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

Deletes a contact through the configured transport adapter.

# `delete_messages`

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

Deletes selected local messages after durable wrapper persistence.

# `diagnostics`

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

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

# `disconnect`

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

Disconnects a client through its configured transport adapter.

# `download_media`

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

Downloads and decrypts a media reference through the configured transport.

# `get_call`

```elixir
@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.

# `get_chat`

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

Fetches one chat by JID through the configured transport adapter.

# `get_contact`

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

Fetches one contact by JID through the configured transport adapter.

# `get_messages`

```elixir
@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.

# `last_error`

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

Returns the most recent structured client error, if any.

# `list_calls`

```elixir
@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`, ...).

# `list_chats`

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

Lists chats through the configured transport adapter.

# `list_contacts`

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

Lists contacts through the configured transport adapter.

# `list_groups`

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

Lists group chats through the configured transport adapter.

# `pair`

```elixir
@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.

# `receive_message`

```elixir
@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.

# `send_audio`

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

Sends an audio message through the configured transport adapter.

# `send_contact`

```elixir
@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.

# `send_document`

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

Sends a document message through the configured transport adapter.

# `send_event`

```elixir
@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.

# `send_image`

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

Sends an image message through the configured transport adapter.

# `send_location`

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

Sends a GPS location through the configured transport adapter.

# `send_message`

```elixir
@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`.

# `status`

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

Returns the current client status.

# `stream_messages`

```elixir
@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.

# `sync_contacts`

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

Synchronizes contacts through the configured transport adapter.

---

*Consult [api-reference.md](api-reference.md) for complete listing*