@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 here are process/runtime wiring, distinct from the config map passed to new/1 (the WhatsApp/protocol settings like :mark_online_on_connect):

• :parent — the event sink (Amarula.Connection.sink/0): a pid, a registered name, a {:via, …} tuple, or {name, node}. A name survives the consumer's restart (it re-resolves to the current holder); a raw pid does not. Default: the caller's pid. Re-point a live connection's sink with set_parent/2.
• :parent_pid — legacy alias for :parent (a pid). :parent wins if both given.
• :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() | Amarula.Content.Media.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, an %Amarula.Content.Media{}). Returns {:ok, bytes} or {:error, reason} (:bad_mac on a failed integrity check, :invalid_media on a malformed descriptor).

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

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

Ask the phone for older history of a chat (a PEER_DATA_OPERATION on-demand request). oldest identifies the oldest message you already have — pass the %Amarula.Msg{} you received (most accurate) or a {jid, msg_id} tuple. oldest_ts is that message's 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}.

A {jid, msg_id} tuple can't know from_me/participant, so prefer the %Amarula.Msg{} for a message you sent or a group message.

@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 | {:error, :not_connected}

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).

Commonly-used options

config is a map; only :profile is required. The options you'll reach for most (full list + defaults in Amarula.Config):

• :profile — required. Names this connection's stored credentials, so it reconnects without re-pairing. Any term (e.g. :primary, "acct-42").
• :mark_online_on_connect (default true) — send presence-available on connect. Set false to stay offline to others; the primary phone then keeps receiving push notifications (live messages are queued offline rather than pushed to this session).
• :browser (default ["Mac OS", "Chrome", "14.4.1"]) — the [os, client, version] triple shown in the user's Linked devices. A "Android" client element opts into Android registration (can receive view-once media; see Amarula.Config).
• :sync_full_history (default true) — request full history on link.
• :auth — explicit creds (advanced; normally Amarula loads/persists these for you from :profile).
• :offline (default false) — sandbox mode (below).

Every per-connection setting can be overridden here and wins over the default — see the full table in Amarula.Config.

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.

Options

• :custom_code (String.t/0) - 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 | {:error, :not_connected}

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.

Options

• :description (String.t/0) - event description.

• :location (term/0) - {lat, lng} or [lat:, lng:, name:, address:].

• :join_link (String.t/0) - a call/meeting link to join.

• :start_time (integer/0) - event start (unix seconds).

• :end_time (integer/0) - event end (unix seconds).

• :extra_guests_allowed (boolean/0) - whether guests may invite others.

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).

Options

• :group_name (String.t/0) - group name shown on the card.

• :caption (String.t/0) - text shown with the invite.

• :expiration (non_neg_integer/0) - invite expiry (unix ms).

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

Send a location to jid.

Options

• :name (String.t/0) - place name shown on the card.

• :address (String.t/0) - street address shown under the name.

• :url (String.t/0) - link attached to the location.

• :is_live (boolean/0) - send as a live (updating) location.

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

Options

• :mimetype (String.t/0) - content type; auto-detected per type if omitted.

• :caption (String.t/0) - text shown under the media.

• :width (non_neg_integer/0) - image/video width in px.

• :height (non_neg_integer/0) - image/video height in px.

• :seconds (non_neg_integer/0) - duration; required for :audio (see the warning above).

• :ptt (boolean/0) - send :audio as a voice note.

• :waveform (String.t/0) - amplitude preview (raw bytes) for a voice note.

• :file_name (String.t/0) - document file name.

• :title (String.t/0) - document title.

• :view_once (boolean/0) - send as view-once (the recipient can open it once).

• :ptv (boolean/0) - for :video, send as a round video note (PTV).

• :quoted - reply to a message: an %Amarula.Msg{} (full quote), or a {msg_id, participant} tuple (lightweight — threads by id, no inline preview if the recipient lacks the original).

• :mentions - jids / %Amarula.Address{} to tag (@mention).

@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).

Options

• :selectable (non_neg_integer/0) - max options a voter may pick. The default value is 1.

• :announcement (boolean/0) - send as an announcement-group poll.

• :message_secret (String.t/0) - 32-byte secret to encrypt votes under (generated if omitted).

@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).

Options

• :creator - poll creator's jid / %Amarula.Address{} (required for a group poll given as a {jid, msg_id} tuple).

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

Options

• :quoted - reply to a message: an %Amarula.Msg{} (full quote), or a {msg_id, participant} tuple (lightweight — threads by id, no inline preview if the recipient lacks the original).

• :mentions - jids / %Amarula.Address{} to tag (@mention).

@spec set_parent(conn(), Amarula.Connection.sink()) :: :ok

Re-attach the consumer event sink of a live connection to sink without bouncing the websocket — the recovery path when the process that called connect/2 restarts while the connection survives in the registry.

conn is any connection handle (a pid, or via/1 of a profile); sink is a Amarula.Connection.sink/0. Pass a registered name (not a raw pid) for a sink that also survives the connection's own restart. Returns :ok.

Amarula.set_parent(Amarula.via(:primary), self())

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

Set your global presence: :available (online) or :unavailable.

@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 | {:error, :not_connected}

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 update_member_tag(conn(), jid(), String.t()) ::
  send_result() | {:error, :member_tag_too_long}

Set your own member tag (per-group self-label) in group, or clear it with "". The tag is capped at 30 characters — a longer one is rejected with {:error, :member_tag_too_long} (we don't silently truncate). Relayed to the group; other members see it via a %Amarula.Content.MemberTag{} message (label "" = removed). Also available as Amarula.Group.update_member_tag/3.

@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).