@spec connect(
  Amarula.Conn.t(),
  keyword()
) :: {:ok, conn()} | {:error, {:already_running, pid()}} | {:error, term()}

Start a built Amarula.Conn and begin connecting. Returns the running conn handle (a pid). Pair with new/1:

{:ok, pid} = Amarula.new(config) |> Amarula.connect()

conn = Amarula.via(profile)          # always resolves to the current pid
Amarula.send_text(conn, jid, "hi")

Only one connection per profile may run at a time (within the registry's reach — one per node by default; see Amarula.ProfileRegistry). Connecting a profile that's already live returns {:error, {:already_running, pid}} — use whereis/1 to get the existing one.

opts:

• :parent_pid — process to receive {:amarula, ..} events (default: caller)
• :name — optional registered name for the connection

@spec connection_state(conn()) :: atom()

Current connection state (e.g. :disconnected, :connecting, :connected).

@spec disconnect(conn()) :: :ok | {:error, term()}

Close the connection's websocket without taking the supervision tree down. Pair with reconnect/1 to bring it back up; use stop/1 to release the profile entirely. Returns :ok | {:error, reason}.

@spec download_media(Amarula.Msg.t()) :: {:ok, binary()} | {:error, term()}

Download + decrypt an incoming media file. Inbound messages carry only media metadata (directPath/mediaKey), not the bytes — call this to fetch them lazily, passing a %Amarula.Msg{type: :media} (or its content.media struct

• kind). Returns {:ok, bytes} or {:error, reason} (:bad_mac on a failed integrity check).

  %Amarula.Msg{type: :media} = msg {:ok, bytes} = Amarula.download_media(msg)

@spec fetch_history(conn(), message_key(), integer(), non_neg_integer()) ::
  send_result()

Ask the phone for older history of a chat (a PEER_DATA_OPERATION on-demand request). oldest_key is the oldest message you already have, oldest_ts its millisecond timestamp, and count how many older messages to request. The history arrives asynchronously later via the normal :history_sync event. Returns {:ok, request_msg_id} or {:error, :not_authenticated}.

@spec keep_message(conn(), message_ref()) :: send_result()

Keep a message in a disappearing chat (exempt it from auto-delete). ref is a %Amarula.Msg{} or {jid, msg_id}.

@spec list_profiles(
  Amarula.Storage.Scope.t()
  | Amarula.Conn.t()
  | {module(), keyword()}
  | keyword()
) ::
  {:ok, [Amarula.Storage.profile()]} | {:error, term()}

List every profile that has stored credentials in storage.

Takes a storage source rather than a live connection: a Amarula.Storage.Scope.t/0, a built %Amarula.Conn{} (use its scope), or a {adapter, opts} / bare-opts storage spec (the same value new/1 accepts as :storage). Returns the profile names that have a :creds entry — what you'd pass as :profile to reconnect.

Amarula.list_profiles(root: "./amarula_data")
#=> {:ok, [:primary, "work"]}

{:error, :not_supported} if the storage adapter can't enumerate profiles.

@spec list_profiles_with_metadata(
  Amarula.Storage.Scope.t()
  | Amarula.Conn.t()
  | {module(), keyword()}
  | keyword()
) :: {:ok, [Amarula.Storage.profile_info()]} | {:error, term()}

Like list_profiles/1, but each entry carries the logged-in identity read from that profile's stored creds — for building a friendlier account picker:

Amarula.list_profiles_with_metadata(root: "./amarula_data")
#=> {:ok, [%{profile: :primary, jid: "5511...@s.whatsapp.net",
#           lid: "12345@lid", name: "Alice"}]}

Costs one extra storage read per profile. name/jid/lid are nil for a profile that hasn't finished pairing. Accepts the same storage sources as list_profiles/1.

@spec mark_read(conn(), jid(), [String.t(), ...], jid() | nil) :: :ok

Send a read receipt for message_ids in chat jid (pass participant for a group sender). Marks those messages read on the sender's side.

@spec new(map()) :: Amarula.Conn.t()

Build a connection value (Amarula.Conn) from config, without starting it.

This is the start of the Req-style builder: attach plugins, then connect/2.

Amarula.new(%{profile: :primary})
|> MyPlugin.attach(opts)
|> Amarula.connect()

Connection/protocol defaults are filled in (see Amarula.Config), so config need only carry :profile (+ :auth and any overrides).

Offline (sandbox) mode

offline: true runs the connection with no socket: it never reaches WhatsApp, and every send_* short-circuits to {:ok, msg_id} without encrypting or emitting a frame. Combined with Amarula.Testing.deliver_* (which feeds synthetic inbound messages), this lets you run your bot end to end — receive a message, reply to it — with no real-world effect. See Amarula.Testing.

@spec own_address(conn()) :: Amarula.Address.t()

This connection's own identity as an Amarula.Address — our phone-number address, carrying our companion device id (creds.me.id).

Always returns an Address: before login (no identity yet) it returns Amarula.Address.empty/0, so you never have to nil-check. own_address(conn).device is nil for the primary device / phone, or the linked-device number (e.g. 29) for a companion like this app.

Use it to detect messages this app/device itself sent — e.g. to ignore the agent's own self-chat sends and avoid a feedback loop. This does a call into the connection, and our own device is constant after login, so read it once and reuse the device:

own_device = Amarula.own_address(conn).device

# then, per received message:
if msg.from_me and msg.from.device == own_device do
  :ignore   # this device sent it
end

@spec own_chat?(conn(), Amarula.Msg.t()) :: boolean()

Whether msg is in our own chat (the "Message Yourself" chat): from_me and addressed to our own account. The check a self-chat command channel needs — drive an agent by messaging yourself.

Handles the LID/PN duality: the self chat may be addressed by our PN or our LID, so it matches msg.to against both of our own identities (see Amarula.Connection.own_chat?/2).

On a single connection there's no feedback loop — a reply this connection sends to the self chat is not delivered back to it (the sender's own device is excluded from delivery), so you don't need to filter your own sends. Dedupe by msg_id only when running two connections on the same account.

@spec pin_message(conn(), message_ref()) :: send_result()

Pin a message for everyone in the chat. ref is a %Amarula.Msg{} or {jid, msg_id}.

@spec reconnect(conn()) :: :ok | {:error, term()}

(Re)open the connection's websocket on an already-started connection — the inverse of disconnect/1. Runs the handshake and logs in again with the profile's stored credentials. Returns :ok | {:error, reason}.

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

Request a link-code (phone-number) pairing code for phone (E.164 digits; any +, spaces, or dashes are stripped).

Call this during the QR window while unregistered — on the first :connection_update carrying a qr. Returns {:ok, code} with an 8-char code the user types into WhatsApp → Linked Devices → "Link with phone number". Amarula finishes the handshake internally; the usual 515 restart then logs in (watch for :pairing_success then connection: :open). The same code is also delivered as a :pairing_code event.

opts: :custom_code — a fixed 8-char code to use instead of a random one.

@spec resolve_quoted(conn(), Amarula.Msg.t()) ::
  {:ok, Amarula.Msg.t()} | {:requested, String.t()} | {:error, term()}

Resolve the original message a reply quotes.

1. If the reply carries the inline copy WhatsApp ships (msg.quoted.message), return it immediately — {:ok, %Amarula.Msg{}}.
2. Otherwise ask the server to re-deliver the original — {:requested, id}; it re-arrives async via :messages_upsert.

{:error, :not_a_reply} if msg doesn't quote anything.

Amarula does not keep an inbound-message store — delivery ends at :messages_upsert (the message, its mentions, and the inline quote are all there). If you want to resolve a quote from your own history, look it up in whatever store you keep and skip this; this function only handles the inline copy and the server round-trip.

@spec send_album(conn(), jid(), [{:image | :video, binary(), keyword()}]) ::
  {:ok, String.t()} | {:error, term()}

Send an album (grouped media) to jid. items is a list of {type, data, opts} (same shape as send_media/5), where type is :image or :video. Sends the album parent first, then each item referencing it.

Returns {:ok, parent_msg_id} once the parent and all items are sent, or {:error, {:album_item, index, reason}} if an item fails (the parent and earlier items have already been sent).

WhatsApp expects ≥2 items, all images/videos.

@spec send_chatstate(conn(), jid(), :composing | :recording | :paused) :: :ok

Send a typing indicator to jid: :composing, :recording, or :paused.

@spec send_contact(conn(), jid(), String.t(), String.t()) :: send_result()

Send a contact (display_name + vCard string) to jid.

@spec send_contacts(conn(), jid(), String.t(), [{String.t(), String.t()}, ...]) ::
  send_result()

Send multiple contacts to jid: pairs is [{display_name, vcard}, ...].

@spec send_edit(conn(), message_ref(), String.t()) :: send_result()

Edit a message we sent, replacing its text. ref is a %Amarula.Msg{} or a {jid, msg_id} tuple.

@spec send_event(conn(), jid(), String.t(), keyword()) :: send_result()

Send an event to jid (a group or 1:1). name is the title. opts: :description, :location ({lat, lng} or [lat:, lng:, name:, address:]), :join_link, :start_time / :end_time (unix seconds), :extra_guests_allowed.

Responding to an event (RSVP) is not yet supported — the response is an encrypted EncEventResponseMessage, a separate crypto seam (like poll votes).

@spec send_group_invite(conn(), jid(), String.t(), String.t(), keyword()) ::
  send_result()

Send a group-invite message to jid — a tap-to-join card for group_jid using code (from Amarula.Group.invite_code/2). opts: :group_name, :caption, :expiration (unix ms).

@spec send_location(conn(), jid(), float(), float(), keyword()) :: send_result()

Send a location to jid. opts: :name, :address, :url, :is_live.

@spec send_media(conn(), jid(), media_type(), binary(), keyword()) :: send_result()

Send media of type (:image/:video/:audio/:document/:sticker).

data is the raw file bytes — not a path, not base64. Read the file yourself first:

bytes = File.read!("photo.jpg")
Amarula.send_media(conn, jid, :image, bytes, caption: "hi")

Amarula encrypts and uploads the bytes for you. opts may carry :mimetype (auto-detected per type if omitted), :caption, :width, :height, :seconds, :ptt (voice note), :file_name, :title, plus:

• :quoted / :mentions — reply to / tag (see send_text/4).
• :view_once — send as view-once (the recipient can open it once).
• :ptv — for :video, send as a round video note (PTV).

@spec send_poll(conn(), jid(), String.t(), [String.t(), ...], keyword()) ::
  {:ok, String.t(), binary()} | {:error, term()}

Send a poll to jid. Returns {:ok, msg_id, message_secret} — keep the message_secret to tally incoming votes (Amarula.Protocol.Messages.Poll). opts: :selectable (max picks, default 1), :announcement, :message_secret.

@spec send_poll_vote(conn(), message_ref(), binary(), [String.t()], keyword()) ::
  send_result()

Cast a vote on an existing poll. poll is a message_ref for the poll-creation message (a %Amarula.Msg{} or {jid, msg_id} tuple); message_secret is the poll's 32-byte secret (from send_poll/5, or the poll's messageContextInfo); option_names are the chosen options. The vote is encrypted under the secret.

The poll's creator is taken from the ref (a %Amarula.Msg{}'s sender, or the {jid, _} chat for a 1:1 poll). For a group poll referenced by tuple, pass the creator explicitly with :creator in opts.

@spec send_reaction(conn(), message_ref(), String.t()) :: send_result()

React to a message with emoji (empty string removes the reaction). ref is a %Amarula.Msg{} or a {jid, msg_id} tuple.

@spec send_revoke(conn(), message_ref()) :: send_result()

Delete a message for everyone (revoke). ref is a %Amarula.Msg{} or a {jid, msg_id} tuple.

@spec send_text(conn(), jid(), String.t(), keyword()) :: send_result()

Send a 1:1/group text message to jid. opts:

• :quoted — reply to an %Amarula.Msg{} (threads the quote).
• :mentions — list of jids/%Amarula.Address{} to tag (@mention).

@spec set_presence(conn(), :available | :unavailable) :: :ok | {:error, term()}

Set your global presence: :available (online) or :unavailable. Needs a profile name.

@spec stop(conn() | profile()) :: :ok | {:error, :not_found}

Stop a connection entirely — the whole supervision tree — and release its profile so it can be started again (here or, with a cluster registry, on another node).

Unlike disconnect/1 (which only closes the websocket; the supervised tree stays up and may reconnect), stop/1 takes the tree down and frees the profile slot. Accepts a connection pid or a profile (resolved via the default registry). Returns :ok | {:error, :not_found}.

@spec subscribe_presence(conn(), jid()) :: :ok

Subscribe to a contact's presence updates.

@spec unkeep_message(conn(), message_ref()) :: send_result()

Undo a previous keep (let the message disappear again). ref is a %Amarula.Msg{} or {jid, msg_id}.

@spec unpin_message(conn(), message_ref()) :: send_result()

Unpin a previously pinned message. ref is a %Amarula.Msg{} or {jid, msg_id}.

@spec via(profile()) :: {:via, module(), {atom(), profile()}}

A :via handle for profile — usable anywhere a conn() is accepted, so calls route to whatever pid currently holds the profile (restart-safe). Assumes the default registry; for a custom one, build it from the Conn via Amarula.ProfileRegistry.via/2.

@spec whereis(profile()) :: pid() | nil

The live connection pid for profile, or nil. A restart-safe handle: the pid changes if the connection restarts, but the profile resolves to the current one.

Assumes the default Amarula.ProfileRegistry. With a custom :registry config, pass the Conn (or config) as the first arg: whereis(conn, profile).

@spec whereis(Amarula.Conn.t() | map(), profile()) :: pid() | nil

As whereis/1, but resolves through conn_or_config's :registry.

@spec wipe_credentials(conn()) :: :ok | {:error, term()}

Destructively forget this connection's profile: unlink the companion on WhatsApp's side (the phone drops the device), wipe all local storage for it (creds, sessions, keys, mappings), then disconnect. After this the profile must be re-paired to use again.

For a non-destructive teardown that keeps the credentials, use disconnect/1 (websocket only) or stop/1 (the whole tree, freeing the profile slot).