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

Returns stored messages for a specific chat JID.

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

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

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

Returns currently known chats from local storage.

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

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

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

Lists supervised session IDs and their PIDs.

@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 QR svg output path (default: /tmp/whatsapp_qr.svg)
• :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.

@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
• :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)

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

Sends a text message to a user or group JID.

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

Stops a supervised session started with run_session/2.