API Reference amarula v#0.1.0

Amarula — a WhatsApp Web client for Elixir.

A WhatsApp address — the consumer-facing way to name who/what a message is for or from. The boundary abstraction over the wire JID string.

Starts the library's process tree

Which upstream Baileys revision Amarula's port currently tracks.

A chat update derived from app-state sync — the consumer view of a mutation to a conversation. address is the chat (Amarula.Address: 1:1 or group); the other fields are the change carried by the mutation (nil = unchanged).

Connection config + the single source of truth for protocol/connection defaults.

A connection handle: everything Amarula knows about one connection, built once from its config at connect time and threaded through the protocol layer.

The per-connection process that owns the entire server conversation: the WebSocketClient, the noise cipher (frame encode/decode + counters), IQ correlation, login/handshake, send dispatch, and server-notification handling.

A contact update from app-state sync — the consumer view of a contactAction (a saved name) or the local push-name setting. address is the contact.

Contact discovery via USync. The consumer-facing half of Baileys' onWhatsApp / fetchStatus.

A group chat — the consumer-facing view of group metadata, with addresses as Amarula.Address. Built from the protocol metadata (Groups.Metadata) at the boundary; you get these from Amarula.group_metadata/2 and Amarula.list_groups/1.

A received message, in consumer terms — the friendly view of a decrypted %Proto.Message{}. This is what {:whatsapp, :messages_upsert, %{messages: [%Msg{}]}} carries, so a consumer never has to pattern-match the (large) WA protobuf.

Req-style plugin pipelines for a connection.

Example/reference plugin: a persistent message store.

Profile reads and writes: fetch a profile-picture URL, set/remove your (or a group's) picture, and set your status/bio. The consumer-facing half of Baileys' profilePictureUrl / updateProfilePicture / removeProfilePicture / updateProfileStatus.

The app-level profile -> Connection pid registry: the seam that enforces one connection per profile and lets a consumer refer to a connection by its :profile (restart-safe) rather than a raw pid.

Expand an app-state-sync key into the five mutation sub-keys, ported from Baileys mutationKeys/expandAppStateKeys (pre-WASM chat-utils.ts)

LT Hash — the summation hash that keeps app-state integrity across mutations. Ported from Baileys' pre-WASM pure-JS impl (src/Utils/lt-hash.ts before the rust bridge). Adding/removing a mutation gives the same hash as if the whole sequence had been applied in order, so patches can be verified incrementally.

App-state MAC + value crypto, ported from Baileys (pre-WASM chat-utils.ts): generateMac / generateSnapshotMac / generatePatchMac and the AES-256-CBC value decrypt. Pure given the expanded Amarula.Protocol.AppState.Keys.

Decode app-state syncd mutations/patches into SyncActionData mutations and the next LTHash collection state. Ported from Baileys decodeSyncdMutations / decodeSyncdPatch (chat-utils.ts).

App-state sync orchestration helpers, ported from Baileys resyncAppState (src/Socket/chats.ts). Builds the patch-request IQ, extracts the per-collection patches from the reply, and decodes them through AppState.Patch + AppState.SyncAction into consumer changes — given a key lookup and the prior collection state.

Turn a decoded app-state mutation (Amarula.Protocol.AppState.Patch output) into a consumer-facing change, ported from Baileys processSyncAction (chat-utils.ts).

Authentication utilities for WhatsApp credential generation and management.

Utility to load Baileys-formatted credentials into Amarula format.

Helpers for the link-code (phone-number) pairing flow.

The pairing device-identity crypto: verify the primary's signed device identity, counter-sign it with our key, and derive the companion's signal identity. Pure (takes auth creds + the received identity, returns values) — extracted from Connection so the connection process keeps only socket/state concerns.

QR Code Generator for WhatsApp authentication.

Authentication types and data structures for WhatsApp protocol.

WhatsApp binary protocol constants. Ported from src/WABinary/constants.ts

Binary decoder for WhatsApp protocol.

Binary encoder for WhatsApp protocol.

JID (Jabber ID) utilities for WhatsApp protocol. Ported from src/WABinary/jid-utils.ts

Binary node structure for WhatsApp protocol.

Utility functions for working with binary nodes.

WhatsApp protocol constants for Noise protocol implementation.

Cryptographic utilities for WhatsApp Noise protocol implementation.

Noise protocol handler for WhatsApp WebSocket communication.

XEd25519 signatures over Curve25519 (X25519) keys, compatible with libsignal's curve25519_sign / curve25519_verify — what Baileys calls Curve.sign / Curve.verify.

Group metadata: build the w:g2 query IQ and parse its result into the bits a group send needs. Port of Baileys groupQuery/extractGroupMetadata (src/Socket/groups.ts), trimmed to the send-relevant fields (participants + addressing mode); description/community/etc. are skipped until a consumer needs them.

Parse a w:gp2 group notification into a structured update, ported from the group branch of Baileys handleGroupNotification (Socket/messages-recv.ts).

Group management operations: build the w:g2 IQs that CHANGE a group, and parse their replies. Port of the group op builders in Baileys groups.ts (the write side; Groups.Metadata is the read side).

Per-recipient send process. One ConversationSender exists per recipient JID; all sends to that recipient funnel through it and run one at a time, which serializes Signal ratchet advance for that recipient's session (no per-address lock needed). Different recipients run in parallel under the DynamicSupervisor.

Download + decode the history-sync blob a HISTORY_SYNC_NOTIFICATION points to, ported from Baileys downloadHistory/processHistoryMessage (Utils/history.ts).

WhatsApp media encryption + upload, ported from Baileys src/Utils/messages-media.ts.

Classify a decrypted %Proto.Message{} into a tagged tuple so consumers don't have to pattern-match the (large) proto. The inverse of the builders in MessageEncoder.

Decrypts the <enc> payloads of an incoming message node, ported from the routing in src/Utils/decode-wa-message.ts (decryptMessageNode).

Encode an outgoing Proto.Message to the padded plaintext bytes that the Signal cipher encrypts, ported from Baileys encodeWAMessage (src/Utils/generics.ts)

Poll vote tally, ported from Baileys getAggregateVotesInPollMessage (src/Utils/messages.ts).

Decrypt poll votes, ported from Baileys decryptPollVote (src/Utils/process-message.ts).

Parse an inbound <receipt> into a delivery/read status update, ported from the status side of Baileys handleReceipt (Socket/messages-recv.ts) + getStatusFromReceiptType (Utils/generics.ts).

Build the outbound <message> stanza for a 1:1 send, ported from the single-device path of Baileys relayMessage (src/Socket/messages-send.ts).

Type definitions for WhatsApp messages.

Build presence / chat-state stanzas, ported from Baileys sendPresenceUpdate and presenceSubscribe (src/Socket/chats.ts).

Profile operations: build the IQs that read/change your (or a target's) profile picture and status, and parse their replies. Port of the profile-picture/status builders in Baileys chats.ts (profilePictureUrl, updateProfilePicture, removeProfilePicture, updateProfileStatus).

Build read receipts, ported from Baileys sendReceipt (type: "read", src/Socket/messages-send.ts).

Crypto primitives for the Signal v3 session cipher, ported byte-for-byte from node_modules/libsignal/src/crypto.js (the implementation Baileys runs).

Per-user cache of a contact's device list, ported from Baileys' userDevicesCache (the getUSyncDevices cache). Lets a send skip the USync round-trip when we already know a user's devices.

Handles encryption and decryption of group messages using the Signal protocol.

Group Session Builder for Signal Protocol.

Key Helper utilities for Signal Protocol group encryption, ported from src/Signal/Group/keyhelper.ts.

Represents a sender chain key for group encryption.

Sender key distribution message, ported from src/Signal/Group/sender-key-distribution-message.ts.

Sender key message for group encryption, ported from src/Signal/Group/sender-key-message.ts.

Represents a sender key name for group encryption.

Represents a sender key record containing multiple sender key states.

Represents the state of a sender key for group encryption.

File-backed sender key store for group Signal sessions.

Behaviour for sender key storage operations.

Represents a sender message key for group encryption.

Behaviour for key store operations used by LID mapping store.

LID (Local ID) mapping types and utilities.

LID mapping store for managing Phone Number to Local ID mappings.

File-backed LID ↔ PN mapping store, ported from Baileys LIDMappingStore.storeLIDPNMappings / getLIDForPN / getPNForLID.

One-time prekey generation and the encrypt IQ that uploads them, ported from the prekey helpers in src/Utils/signal.ts (generateOrGetPreKeys, getNextPreKeysNode, xmppPreKey, xmppSignedPreKey).

Signal Protocol Repository - Main interface for Signal protocol operations.

Behaviour for a Signal Protocol Sender Key Store.

X3DH responder session establishment, ported from node_modules/libsignal/src/session_builder.js.

Signal v3 Double-Ratchet decryption, ported from node_modules/libsignal/src/session_cipher.js (decrypt path only).

Parse an encrypt/get prekey-bundle IQ result and build outgoing sessions, ported from Baileys parseAndInjectE2ESessions (src/Utils/signal.ts) + repository.injectE2ESession.

Signal session storage, ported from node_modules/libsignal/src/session_record.js.

Storage glue for the 1:1 Signal session cipher.

Core Signal Protocol types and data structures.

Minimal protobuf decode for the two Signal v3 message types (libsignal WhisperTextProtocol). These are tiny — a few bytes/uint32 fields — so we decode them directly rather than dragging them through the WAProto build.

Per-connection supervision tree. One ConnectionSupervisor owns everything for a single WhatsApp connection instance

Static validation functions for WhatsApp WebSocket handshake.

IQ request/response correlation, extracted from Connection as a pure module over the pending-IQ map. CM stays the only process and owns the socket, timers, and the tracked-kind continuations; this module decides what to do with a reply/timeout and returns an effect for CM to perform.

The Noise XX handshake + login-bootstrap stanza builders, extracted from Connection. Pure: these compute frames/nodes from inputs and return values — they do NOT touch the websocket, timers, or emit events. CM stays the process: it sends the frames/nodes, transitions state, and emits updates.

Pure routing decision for inbound server nodes — cluster 3 of the Connection split (see docs/plans/CM_SPLIT.plan.md).

Owns the per-connection retry-cache ETS table, created once at init — BEFORE the Connection that reads it starts, since it's an early child of the ConnectionSupervisor.

Types and behaviors for WebSocket layer implementation.

WebSocket client implementation using websockex.

USync (user sync) query builder and result parser.

Turn a parsed USync result into the concrete list of device JIDs to encrypt for. Port of Baileys extractDeviceJids (src/Utils/signal.ts).

USync protocol definitions.

Pluggable cache of recently-sent messages, so the library can re-encrypt and resend when a recipient asks for a retry (<receipt type="retry">).

On-disk Amarula.RetryCache adapter — survives restart.

In-memory Amarula.RetryCache adapter — the default.

A retry-cache scope: the resolved adapter plus its state. Handed to a cache adapter (with the connection profile) on each call. Mirrors Amarula.Storage.Scope but for the separate retry-cache concern.

The built-in send-pipeline step that records each outgoing message in the Amarula.RetryCache, so it can be re-encrypted and resent if the recipient asks for a retry. Attached by default (see Amarula.Conn); a side-effect step that never transforms or halts.

Pluggable, connection-scoped persistence for a connection's protocol state.

Ergonomic base for writing an Amarula.Storage adapter.

DETS Amarula.Storage adapter for durable account state — a peer to Amarula.Storage.File.

Filesystem Amarula.Storage adapter — the default plugin.

A storage scope: the resolved adapter plus its per-connection state.

:telemetry events emitted by Amarula — the operational-observability surface.

Test support for consumers of Amarula — drive your bot with synthetic inbound messages, with no WhatsApp connection.