# `ExWapp.Live`
[🔗](https://github.com/elchemista/ex_wapp/blob/v0.1.5/lib/ex_wapp/live.ex#L1)

Manual integration helper for running a real WhatsApp Web session in IEx.

This module is intentionally side-effectful and focused on debugging:
- connect + pair (QR saved to disk)
- send messages
- list chats and groups
- read stored chat messages
- wait for new incoming messages from the running session

# `get_messages`

```elixir
@spec get_messages(pid(), String.t(), keyword()) :: [ExWapp.Chat.message()]
```

Returns stored messages for a specific chat JID.

# `list_calls`

```elixir
@spec list_calls(pid(), keyword()) :: [ExWapp.Call.t()]
```

Returns the locally stored call log for this session, newest first.

# `list_chats`

```elixir
@spec list_chats(pid()) :: [ExWapp.Chat.chat()]
```

Returns currently known chats from local storage.

# `list_groups`

```elixir
@spec list_groups(pid()) :: [ExWapp.Chat.chat()]
```

Returns currently known groups from local chat storage for this session.

# `list_sessions`

```elixir
@spec list_sessions() :: [{term(), pid()}]
```

Lists supervised session IDs and their PIDs.

# `run`

```elixir
@spec run(keyword()) :: {:ok, map()} | {:error, term()}
```

Runs a live session flow (connect + pair if needed), then returns
the session and currently known chats/groups.

Options:
- `:store_path` persisted store path (default: `/tmp/ex_wapp/live_test_session.etf`)
- `:qr_path` rendered QR output path (default: `/tmp/whatsapp_qr.svg`)
- `:qr_renderer` module implementing `ExWapp.QR.Renderer`, defaults to
  `config :ex_wapp, :qr_renderer` (required when pairing is needed)
- `:qr_options` options passed to the renderer (default: `[]`)
- `:pair_timeout_ms` QR pairing timeout (default: `15000`)
- `:connect_timeout_ms` connect timeout (default: `15000`)
- `:sync_wait_ms` wait after connect before reading chats (default: `15000`)
- `:name` optional GenServer name (default: `ExWapp.Live.Session`)
- `:replace_existing` stop existing named session before start (default: `true`)

To run multiple sessions safely, use `run_session/2`.

# `run_session`

```elixir
@spec run_session(term(), keyword()) :: {:ok, map()} | {:error, term()}
```

Runs a supervised multi-session flow keyed by `session_id`.

This is the preferred way to run multiple sessions concurrently.
Each session should use a unique store file to avoid stream conflicts.

Options:
- `:store_path` defaults to `/tmp/ex_wapp/sessions/<session_id>.etf`
- `:qr_path` defaults to `/tmp/ex_wapp/qr/<session_id>.svg`
- `:qr_renderer` module implementing `ExWapp.QR.Renderer`, defaults to
  `config :ex_wapp, :qr_renderer` (required when pairing is needed)
- `:qr_options` options passed to the renderer (default: `[]`)
- `:pair_timeout_ms` QR pairing timeout (default: `15000`)
- `:connect_timeout_ms` connect timeout (default: `15000`)
- `:sync_wait_ms` wait after connect before reading chats (default: `15000`)
- `:replace_existing` stop existing session with same `session_id` before start (default: `true`)

# `send_message`

```elixir
@spec send_message(pid(), String.t(), iodata()) ::
  {:ok, String.t()} | {:error, term()}
```

Sends a text message to a user or group JID.

# `stop_session`

```elixir
@spec stop_session(term()) :: :ok | {:error, :not_found}
```

Stops a supervised session started with `run_session/2`.

---

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