ExWapp.Session (ExWapp v0.1.2)

Copy Markdown View Source

Internal facade for the built-in WhatsApp session engine.

The GenServer implementation lives in ExWapp.Session.Worker. This module is used by ExWapp.Client.Transport.Session; it is documented for maintainers and custom transport authors, but it is not part of ExWapp's stable public API. Applications should use the %ExWapp.Client{} API through ExWapp.

Summary

Types

qr_event()

Human readable events emitted during the pairing flow.

status()

Session status

t()

Functions

archive_chat(server, jid)

See ExWapp.Session.AppStateCommands.archive_chat/2.

child_spec(arg)

See ExWapp.Session.Worker.child_spec/1.

connect(server)
create_contact(server, jid, name)

See ExWapp.Session.AppStateCommands.create_contact/3.

delete_chat(server, jid)

See ExWapp.Session.AppStateCommands.delete_chat/2.

delete_contact(server, jid)

See ExWapp.Session.AppStateCommands.delete_contact/2.

disconnect(server)

See ExWapp.Session.Worker.disconnect/1.

download_media(server, ref, opts \\ [])
export_snapshot(server)

Flushes the session store and exports its complete local snapshot.

flush_store(server)
get_chat_info(server, jid)

See ExWapp.Session.Worker.get_chat_info/2.

get_contact(server, jid)

Gets one contact from the session store, or nil when it is unknown.

get_session_id(server)

See ExWapp.Session.Worker.get_session_id/1.

health_status(server)

See ExWapp.Session.Worker.get_health_status/1.

list_contacts(server)

Lists contacts currently present in the session store.

message_stream(server)

See ExWapp.Session.Worker.message_stream/1.

pause_sends(server)

See ExWapp.Session.Worker.pause_sends/1.

policy_status(server)

See ExWapp.Session.Worker.get_policy_status/1.

qr_stream(server)

See ExWapp.Session.Worker.qr_stream/1.

request_pairing_code(server, phone, opts \\ [])

Requests an eight-character phone-number pairing code.

resume_sends(server)

See ExWapp.Session.Worker.resume_sends/1.

retry_media(server, message_id, opts \\ [])

Asks the sender's phone to re-upload an expired media object.

runtime_config(server)

See ExWapp.Session.Worker.get_runtime_config/1.

send_app_state(server, patch_info)

See ExWapp.Session.Worker.send_app_state/2.

send_audio(server, jid, source, opts \\ [])
send_contact(server, jid, display_name, vcard, opts \\ [])
send_document(server, jid, source, opts \\ [])
send_event(server, jid, name, start_time, opts \\ [])
send_image(server, jid, source, opts \\ [])
send_location(server, jid, latitude, longitude, opts \\ [])
send_message(server, message)

Sends a canonical outbound message through the session engine.

send_text(server, jid, text, opts \\ [])
send_typing(server, jid, composing \\ true)
start_link(opts)

See ExWapp.Session.Worker.start_link/1.

state(server)

See ExWapp.Session.Worker.state/1.

stats(server)

See ExWapp.Session.Worker.stats/1.

stop_worker(server)

See ExWapp.Session.Worker.stop_worker/1.

subscribe_qr(server)

See ExWapp.Session.Worker.subscribe_qr/1.

sync_contacts(server)

Refreshes contact-related app-state data from the server.

unarchive_chat(server, jid)

See ExWapp.Session.AppStateCommands.unarchive_chat/2.

unsubscribe_qr(server, ref)

See ExWapp.Session.Worker.unsubscribe_qr/2.

Types

qr_event()

@type qr_event() ::
  {:code, String.t()}
  | {:pairing_code, String.t()}
  | :success
  | {:error, term()}

Human readable events emitted during the pairing flow.

status()

@type status() ::
  :idle | :connecting | :handshaking | :syncing | :connected | :disconnected

Session status

t()

@opaque t()

Functions

archive_chat(server, jid)

@spec archive_chat(GenServer.server(), String.t()) :: :ok | {:error, term()}

See ExWapp.Session.AppStateCommands.archive_chat/2.

child_spec(arg)

@spec child_spec(term()) :: Supervisor.child_spec()

See ExWapp.Session.Worker.child_spec/1.

connect(server)

@spec connect(GenServer.server()) :: :ok

create_contact(server, jid, name)

@spec create_contact(GenServer.server(), String.t(), String.t()) ::
  :ok | {:error, term()}

See ExWapp.Session.AppStateCommands.create_contact/3.

delete_chat(server, jid)

@spec delete_chat(GenServer.server(), String.t()) :: :ok | {:error, term()}

See ExWapp.Session.AppStateCommands.delete_chat/2.

delete_contact(server, jid)

@spec delete_contact(GenServer.server(), String.t()) :: :ok | {:error, term()}

See ExWapp.Session.AppStateCommands.delete_contact/2.

disconnect(server)

@spec disconnect(GenServer.server()) :: :ok

See ExWapp.Session.Worker.disconnect/1.

download_media(server, ref, opts \\ [])

@spec download_media(GenServer.server(), ExWapp.Media.Ref.t(), keyword()) ::
  {:ok, ExWapp.Media.Download.t()} | {:error, term()}

export_snapshot(server)

@spec export_snapshot(GenServer.server()) :: {:ok, map()} | {:error, term()}

Flushes the session store and exports its complete local snapshot.

The result includes decoded :data, the serialized :blob, and a SHA-256 :checksum. This is useful for backups or wrapper-level database imports. It reflects local state only and does not request additional server history.

flush_store(server)

@spec flush_store(GenServer.server()) :: :ok | {:error, term()}

get_chat_info(server, jid)

@spec get_chat_info(GenServer.server(), String.t()) ::
  {:ok, ExWapp.Chat.chat()} | {:error, :not_found}

See ExWapp.Session.Worker.get_chat_info/2.

get_contact(server, jid)

@spec get_contact(GenServer.server(), String.t()) :: ExWapp.Contact.t() | nil

Gets one contact from the session store, or nil when it is unknown.

get_session_id(server)

@spec get_session_id(GenServer.server()) :: term() | nil

See ExWapp.Session.Worker.get_session_id/1.

health_status(server)

@spec health_status(GenServer.server()) :: map()

See ExWapp.Session.Worker.get_health_status/1.

list_contacts(server)

@spec list_contacts(GenServer.server()) :: [ExWapp.Contact.t()]

Lists contacts currently present in the session store.

message_stream(server)

@spec message_stream(GenServer.server()) :: Enumerable.t()

See ExWapp.Session.Worker.message_stream/1.

pause_sends(server)

@spec pause_sends(GenServer.server()) :: :ok

See ExWapp.Session.Worker.pause_sends/1.

policy_status(server)

@spec policy_status(GenServer.server()) :: map()

See ExWapp.Session.Worker.get_policy_status/1.

qr_stream(server)

@spec qr_stream(GenServer.server()) :: Enumerable.t()

See ExWapp.Session.Worker.qr_stream/1.

request_pairing_code(server, phone, opts \\ [])

@spec request_pairing_code(GenServer.server(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Requests an eight-character phone-number pairing code.

Call this after connect/1, once the Noise transport has entered the handshaking state. :custom_code may be supplied and must contain exactly eight bytes.

resume_sends(server)

@spec resume_sends(GenServer.server()) :: :ok

See ExWapp.Session.Worker.resume_sends/1.

retry_media(server, message_id, opts \\ [])

@spec retry_media(GenServer.server(), String.t(), keyword()) ::
  {:ok, ExWapp.Media.Ref.t()} | {:error, term()}

Asks the sender's phone to re-upload an expired media object.

The message must still exist in the local message store so its media key and conversation envelope can be authenticated on the wire.

runtime_config(server)

@spec runtime_config(GenServer.server()) :: map()

See ExWapp.Session.Worker.get_runtime_config/1.

send_app_state(server, patch_info)

@spec send_app_state(GenServer.server(), map()) ::
  {:ok, map(), map()} | {:error, term()}

See ExWapp.Session.Worker.send_app_state/2.

send_audio(server, jid, source, opts \\ [])

@spec send_audio(GenServer.server(), binary(), ExWapp.Media.source(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_contact(server, jid, display_name, vcard, opts \\ [])

@spec send_contact(GenServer.server(), binary(), String.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_document(server, jid, source, opts \\ [])

@spec send_document(GenServer.server(), binary(), ExWapp.Media.source(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_event(server, jid, name, start_time, opts \\ [])

@spec send_event(
  GenServer.server(),
  binary(),
  String.t(),
  integer() | DateTime.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

send_image(server, jid, source, opts \\ [])

@spec send_image(GenServer.server(), binary(), ExWapp.Media.source(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_location(server, jid, latitude, longitude, opts \\ [])

@spec send_location(GenServer.server(), binary(), number(), number(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_message(server, message)

@spec send_message(GenServer.server(), ExWapp.Message.t()) ::
  {:ok, String.t()} | {:error, term()}

Sends a canonical outbound message through the session engine.

The message ID, when present, is preserved through encryption and transport.

send_text(server, jid, text, opts \\ [])

@spec send_text(GenServer.server(), binary(), iodata(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

send_typing(server, jid, composing \\ true)

@spec send_typing(GenServer.server(), binary(), boolean()) :: :ok | {:error, term()}

start_link(opts)

@spec start_link(keyword() | ExWapp.Session.Options.t()) :: GenServer.on_start()

See ExWapp.Session.Worker.start_link/1.

state(server)

@spec state(GenServer.server()) :: status()

See ExWapp.Session.Worker.state/1.

stats(server)

@spec stats(GenServer.server()) :: map()

See ExWapp.Session.Worker.stats/1.

stop_worker(server)

@spec stop_worker(GenServer.server()) :: :ok

See ExWapp.Session.Worker.stop_worker/1.

subscribe_qr(server)

@spec subscribe_qr(GenServer.server()) :: {:ok, reference()}

See ExWapp.Session.Worker.subscribe_qr/1.

sync_contacts(server)

@spec sync_contacts(GenServer.server()) :: :ok | {:error, term()}

Refreshes contact-related app-state data from the server.

This operation updates contacts only; it does not request complete chat history.

unarchive_chat(server, jid)

@spec unarchive_chat(GenServer.server(), String.t()) :: :ok | {:error, term()}

See ExWapp.Session.AppStateCommands.unarchive_chat/2.

unsubscribe_qr(server, ref)

@spec unsubscribe_qr(GenServer.server(), reference()) :: :ok

See ExWapp.Session.Worker.unsubscribe_qr/2.