# ExWapp v0.1.2 - Table of Contents

> Runtime-neutral WhatsApp Web client library for Elixir

## Pages

- [ExWapp](readme.md)
- [Architecture](architecture.md)
- [Design decisions](design-decisions.md)
- [Protocol flow](protocol-flow.md)
- [Protocol reference](protocol-reference.md)
- [Strengths and limitations](strengths-and-limitations.md)

## Modules

- [ExWapp.AppState.Crypto](ExWapp.AppState.Crypto.md): Cryptographic primitives for WhatsApp App State Sync.
- [ExWapp.AppState.Engine](ExWapp.AppState.Engine.md): Public façade for WhatsApp app-state sync.
- [ExWapp.AppState.Engine.Builders](ExWapp.AppState.Engine.Builders.md): Builders for outgoing app-state mutations.
- [ExWapp.AppState.Engine.Codec](ExWapp.AppState.Engine.Codec.md): Encoding and decoding helpers for app-state patches.
- [ExWapp.AppState.Engine.Dispatch](ExWapp.AppState.Engine.Dispatch.md): Applies decoded app-state mutations to local contact and chat state.
- [ExWapp.AppState.Engine.State](ExWapp.AppState.Engine.State.md): Persistence helpers for app-state hash-chain metadata.
- [ExWapp.AppState.Engine.Sync](ExWapp.AppState.Engine.Sync.md): Synchronization and transport helpers for app-state collections.
- [ExWapp.AppState.LTHash](ExWapp.AppState.LTHash.md): Linked-list Truncated Hash for WhatsApp App State integrity verification.
- [ExWapp.Application](ExWapp.Application.md): OTP Application for ExWapp.
- [ExWapp.Binary](ExWapp.Binary.md): WhatsApp binary node encoder/decoder (ported from whatsmeow).
- [ExWapp.Client.API](ExWapp.Client.API.md): Runtime-neutral operations for `ExWapp.Client`.
- [ExWapp.Client.Transport.Noop](ExWapp.Client.Transport.Noop.md): Default high-level transport adapter.
- [ExWapp.Client.Transport.RawWebSocket](ExWapp.Client.Transport.RawWebSocket.md): Diagnostic client adapter backed directly by the low-level WebSocket transport.
- [ExWapp.Client.Transport.Session](ExWapp.Client.Transport.Session.md): Built-in high-level transport backed by the full `ExWapp.Session` engine.
- [ExWapp.Client.Transport.WebSocket](ExWapp.Client.Transport.WebSocket.md): Deprecated compatibility name for `ExWapp.Client.Transport.RawWebSocket`.
- [ExWapp.Conn](ExWapp.Conn.md): Thin wrapper around the WhatsApp WebSocket transport.
- [ExWapp.Conn.State](ExWapp.Conn.State.md): Runtime state owned by `ExWapp.Conn`.
- [ExWapp.Debug](ExWapp.Debug.md): Provides interactive diagnostics for the WhatsApp WebSocket and Noise handshake.
- [ExWapp.Debug.DebugClient](ExWapp.Debug.DebugClient.md): WebSockex callback process used internally by `ExWapp.Debug` to inspect
handshake frames.

- [ExWapp.Debug.FullClient](ExWapp.Debug.FullClient.md): WebSockex callback process that drives a complete diagnostic Noise handshake
for `ExWapp.Debug`.

- [ExWapp.Domains.Contacts.Repository](ExWapp.Domains.Contacts.Repository.md): Persists normalized contacts in an `ExWapp.Store`.
- [ExWapp.Error.Ack](ExWapp.Error.Ack.md): Classifies the `error` attribute WhatsApp puts on a message acknowledgement.
- [ExWapp.Events.Noop](ExWapp.Events.Noop.md): Default event adapter that ignores events.

- [ExWapp.Events.Telemetry](ExWapp.Events.Telemetry.md): Event adapter that forwards high-level ExWapp events to `:telemetry`.
- [ExWapp.JID](ExWapp.JID.md): Minimal representation of a WhatsApp JID.
- [ExWapp.Live](ExWapp.Live.md): Manual integration helper for running a real WhatsApp Web session in IEx.
- [ExWapp.MapPath](ExWapp.MapPath.md): Map path helpers that tolerate both atom and string keys.

- [ExWapp.Media.Crypto](ExWapp.Media.Crypto.md): WhatsApp media encryption and decryption helpers.
- [ExWapp.Media.Download](ExWapp.Media.Download.md): Downloaded and decrypted media payload.
- [ExWapp.Media.HTTP](ExWapp.Media.HTTP.md): Minimal WhatsApp media upload/download client.
- [ExWapp.Media.Ref](ExWapp.Media.Ref.md): Downloadable media reference extracted from an inbound message or upload.
- [ExWapp.Media.Retry](ExWapp.Media.Retry.md): Implements WhatsApp's media re-upload protocol.
- [ExWapp.Media.Upload](ExWapp.Media.Upload.md): Metadata returned after uploading encrypted media to WhatsApp.
- [ExWapp.Message.Content](ExWapp.Message.Content.md): Canonical content contract for inbound WhatsApp messages.
- [ExWapp.Message.Handler.Call](ExWapp.Message.Handler.Call.md): Turns inbound `<call>` stanzas into call-log records and live call events.
- [ExWapp.Message.Handler.Common](ExWapp.Message.Handler.Common.md): Provides shared normalization and lookup helpers for inbound node handlers.
- [ExWapp.Message.Handler.Inbound](ExWapp.Message.Handler.Inbound.md): Coordinates the inbound message pipeline after a `<message>` node reaches a
session.
- [ExWapp.Message.Handler.Inbound.Content](ExWapp.Message.Handler.Inbound.Content.md): Decodes inbound plaintext into the canonical message-content contract.
- [ExWapp.Message.Handler.Inbound.Decryptor](ExWapp.Message.Handler.Inbound.Decryptor.md): Signal and sender-key decryption for inbound message envelopes.
- [ExWapp.Message.Handler.Inbound.Envelope](ExWapp.Message.Handler.Inbound.Envelope.md): Inbound envelope normalization and sender/payload candidate resolution.
- [ExWapp.Message.Handler.Inbound.Projection](ExWapp.Message.Handler.Inbound.Projection.md): Applies inbound presentation metadata to the local chat projection.
- [ExWapp.Message.Handler.Inbound.Publisher](ExWapp.Message.Handler.Inbound.Publisher.md): Projects normalized inbound data into the public chat message and event stream.
- [ExWapp.Message.Handler.Inbound.Receipts](ExWapp.Message.Handler.Inbound.Receipts.md): Builds delivery, retry, placeholder-resend, and Signal-session actions.
- [ExWapp.Message.Handler.Inbound.Sync](ExWapp.Message.Handler.Inbound.Sync.md): Ingests protocol messages that update local synchronized state.
- [ExWapp.Message.Handler.Notification](ExWapp.Message.Handler.Notification.md): Handles server notifications and translates them into session actions.
- [ExWapp.Message.Handler.Receipt](ExWapp.Message.Handler.Receipt.md): Handles inbound delivery/read receipts and message acknowledgements.
- [ExWapp.Message.Handler.Wire](ExWapp.Message.Handler.Wire.md): Compatibility façade for inbound XML-envelope and protobuf wire helpers.
- [ExWapp.Message.Handler.Wire.ContentDecoder](ExWapp.Message.Handler.Wire.ContentDecoder.md): Pure decoder for supported WhatsApp message content.
- [ExWapp.Message.Handler.Wire.Fields](ExWapp.Message.Handler.Wire.Fields.md): Pure protobuf wire-field primitives, independent of the generated protos.
- [ExWapp.MessageHandler](ExWapp.MessageHandler.md): High-level router for incoming WhatsApp nodes.
- [ExWapp.Messages](ExWapp.Messages.md): High-level helpers for constructing and sending WhatsApp messages.
- [ExWapp.Noise](ExWapp.Noise.md): Implements the Noise_XX_25519_AESGCM_SHA256 handshake used by WhatsApp Web.
- [ExWapp.Noise.Certificate](ExWapp.Noise.Certificate.md): Validates the WhatsApp Noise certificate chain presented during handshake.
- [ExWapp.Noise.ClientPayload](ExWapp.Noise.ClientPayload.md): Builds the protobuf client payload encrypted into the Noise handshake.
- [ExWapp.Noise.Engine](ExWapp.Noise.Engine.md): Pure Elixir implementation of the Noise handshake engine.

- [ExWapp.Noise.Engine.State](ExWapp.Noise.Engine.State.md): Mutable state passed between Noise XX handshake steps.
- [ExWapp.Noise.Handshake](ExWapp.Noise.Handshake.md): Implements the Noise_XX handshake primitives used by WhatsApp Web.
- [ExWapp.Noise.HandshakeSecrets](ExWapp.Noise.HandshakeSecrets.md): Immutable container for the transport keys and metadata derived from a Noise handshake.

- [ExWapp.Pairing](ExWapp.Pairing.md): Implements the QR-code based pairing handshake used by WhatsApp Web.

- [ExWapp.Pairing.ADV](ExWapp.Pairing.ADV.md): Helpers for parsing and validating WhatsApp ADV (Account Device Verification) payloads.
- [ExWapp.Pairing.LinkCode](ExWapp.Pairing.LinkCode.md): Implements WhatsApp's phone-number (link-code) companion pairing protocol.
- [ExWapp.Prekeys](ExWapp.Prekeys.md): Handles prekey generation and upload to WhatsApp servers.
- [ExWapp.PrivacyToken](ExWapp.PrivacyToken.md): Validates trusted-contact privacy tokens used by direct-message sends.
- [ExWapp.Proto.HistorySync](ExWapp.Proto.HistorySync.md): Extracts WhatsApp history sync payloads embedded in protocol messages.
- [ExWapp.Quota](ExWapp.Quota.md): Tracks configurable daily outbound-message quotas.
- [ExWapp.RateLimiter](ExWapp.RateLimiter.md): Applies configurable token-bucket throttling before outbound sends.
- [ExWapp.Session](ExWapp.Session.md): Internal facade for the built-in WhatsApp session engine.
- [ExWapp.Session.Account](ExWapp.Session.Account.md): Account/state helpers for session send flows.

- [ExWapp.Session.AppStateCommands](ExWapp.Session.AppStateCommands.md): Chat and contact commands that reach the server through app-state sync.
- [ExWapp.Session.DeviceCache](ExWapp.Session.DeviceCache.md): Persists recently observed multi-device fanout targets.
- [ExWapp.Session.IQ](ExWapp.Session.IQ.md): Builders/parsers for IQ stanzas used in send session setup (USync + prekeys).

- [ExWapp.Session.InboundRouter](ExWapp.Session.InboundRouter.md): Decouples transport ingestion from session node processing.
- [ExWapp.Session.JIDUtils](ExWapp.Session.JIDUtils.md): Pure JID helpers used by session send/decrypt flows.
- [ExWapp.Session.MessageNode](ExWapp.Session.MessageNode.md): Builders/parsers for encrypted message participant nodes.

- [ExWapp.Session.Outbound.DeviceDiscovery](ExWapp.Session.Outbound.DeviceDiscovery.md): Pure device-discovery decisions for outbound messages.
- [ExWapp.Session.Outbound.Direct](ExWapp.Session.Outbound.Direct.md): Direct-message and self-chat outbound orchestration decisions.
- [ExWapp.Session.Outbound.Encryptor](ExWapp.Session.Outbound.Encryptor.md): Encrypts one outbound payload for all resolved target devices.
- [ExWapp.Session.Outbound.Fanout](ExWapp.Session.Outbound.Fanout.md): Resolves direct-message fanout targets.
- [ExWapp.Session.Outbound.Group](ExWapp.Session.Outbound.Group.md): Group-specific outbound transformations and routing decisions.
- [ExWapp.Session.Outbound.IQRequests](ExWapp.Session.Outbound.IQRequests.md): Effect boundary for outbound USync, prekey, and group-info IQ requests.
- [ExWapp.Session.Outbound.Prekeys](ExWapp.Session.Outbound.Prekeys.md): Prekey target decisions and Signal-session bootstrap for outbound messages.
- [ExWapp.Session.OutboundQueue](ExWapp.Session.OutboundQueue.md): Per-session outbound command queue.
- [ExWapp.Session.RetryCounters](ExWapp.Session.RetryCounters.md): Bounded bookkeeping for the per-message retry counters in the session state.
- [ExWapp.Session.Supervisor](ExWapp.Session.Supervisor.md): DynamicSupervisor for managing multiple WhatsApp sessions.
- [ExWapp.Session.Targets](ExWapp.Session.Targets.md): Target resolution helpers for direct-message fanout.

- [ExWapp.Session.Worker](ExWapp.Session.Worker.md): Coordinates the lifecycle of a WhatsApp Web connection.
- [ExWapp.Session.Worker.Connection](ExWapp.Session.Worker.Connection.md): The session's connection lifecycle: opening the transport, reacting to what it
reports, tearing it down and deciding when to try again.
- [ExWapp.Session.Worker.Events](ExWapp.Session.Worker.Events.md): What the session tells the outside world: telemetry, lifecycle metadata and
the QR notifications that carry an error.
- [ExWapp.Session.Worker.Inbound](ExWapp.Session.Worker.Inbound.md): Converts inbound message handler outputs into sendable action nodes.

- [ExWapp.Session.Worker.NodeHandler](ExWapp.Session.Worker.NodeHandler.md): Dispatches inbound `Binary.Node` stanzas received after the Noise handshake.
- [ExWapp.Session.Worker.Outbound](ExWapp.Session.Worker.Outbound.md): Coordinates outbound sends from the session worker.
- [ExWapp.Session.Worker.OutboundConfirmation](ExWapp.Session.Worker.OutboundConfirmation.md): Tracks outbound message delivery confirmation and handles the
silent-drop fallback strategy for self-chat messages.

- [ExWapp.Session.Worker.PostAuth](ExWapp.Session.Worker.PostAuth.md): Post-authentication helpers triggered after the `success` node is received.
- [ExWapp.Session.Worker.ReceiptBuilder](ExWapp.Session.Worker.ReceiptBuilder.md): Builds receipt and retry-receipt nodes for inbound message acknowledgement.

- [ExWapp.Session.Worker.Resilience](ExWapp.Session.Worker.Resilience.md): Reconnect/backoff policy for session workers.

- [ExWapp.Session.Worker.Retry](ExWapp.Session.Worker.Retry.md): Outbound retry and message lookup helpers for Session.

- [ExWapp.Session.Worker.Safety](ExWapp.Session.Worker.Safety.md): Implements the session's outbound safety circuit breaker.
- [ExWapp.Session.Worker.SendHealth](ExWapp.Session.Worker.SendHealth.md): Tracks how well outbound sending is going, and decides when to trip the guard.
- [ExWapp.Session.Worker.SendRecovery](ExWapp.Session.Worker.SendRecovery.md): What the session does when a send does not land.
- [ExWapp.Session.Worker.SignalSessions](ExWapp.Session.Worker.SignalSessions.md): Keeps the session's Signal sessions loaded, pruned and persisted.
- [ExWapp.Session.Worker.Subscribers](ExWapp.Session.Worker.Subscribers.md): Subscriber bookkeeping for QR and message streams.

- [ExWapp.Signal](ExWapp.Signal.md): Manages Signal protocol key material and session state.
- [ExWapp.Signal.Adapter](ExWapp.Signal.Adapter.md): Pure Elixir Signal adapter.
- [ExWapp.Signal.Encryption](ExWapp.Signal.Encryption.md): High-level Signal encryption/decryption for WhatsApp messages.
- [ExWapp.Signal.Keys](ExWapp.Signal.Keys.md): Generates Signal Curve25519 key material and implements XEdDSA signatures.
- [ExWapp.Signal.PrekeyFetcher](ExWapp.Signal.PrekeyFetcher.md): Fetches prekey bundles from WhatsApp server for establishing Signal sessions.

- [ExWapp.Signal.SenderKey](ExWapp.Signal.SenderKey.md): Group sender-key support for WhatsApp `skmsg` payloads.
- [ExWapp.Signal.Session](ExWapp.Signal.Session.md): Signal Protocol session management for WhatsApp encryption.
- [ExWapp.Signal.SessionStore](ExWapp.Signal.SessionStore.md): Manages Signal sessions for multiple recipients.
- [ExWapp.Signal.SessionStore.Ref](ExWapp.Signal.SessionStore.Ref.md): Reference to an ETS-backed Signal session store.
- [ExWapp.Signal.WireFormat](ExWapp.Signal.WireFormat.md): Signal Protocol wire format implementation.
- [ExWapp.Store.Codec](ExWapp.Store.Codec.md): Versioned codec for persisted ExWapp store data.
- [ExWapp.Store.Ets](ExWapp.Store.Ets.md): ETS-backed store with file persistence.
- [ExWapp.Store.Memory](ExWapp.Store.Memory.md): In-memory store adapter for testing.
- [ExWapp.Store.MessageTable](ExWapp.Store.MessageTable.md): Indexed message storage used by the built-in store adapters.
- [ExWapp.Telemetry](ExWapp.Telemetry.md): Telemetry helpers and canonical event list for ExWapp.
- [ExWapp.Transport](ExWapp.Transport.md): Behaviour for wire-level WhatsApp protocol transports.
- [ExWapp.Transport.Frame](ExWapp.Transport.Frame.md): WhatsApp-specific websocket frame encoding.
- [ExWapp.Transport.WebSocket](ExWapp.Transport.WebSocket.md): Optional wire-level WebSocket/Noise process for WhatsApp Web.
- [ExWapp.Transport.WebSocket.State](ExWapp.Transport.WebSocket.State.md): Holds runtime state for the WhatsApp WebSocket transport.

- Public client API
  - [ExWapp](ExWapp.md): Stable public client facade for ExWapp.
  - [ExWapp.Call](ExWapp.Call.md): Call log storage and queries.
  - [ExWapp.Chat](ExWapp.Chat.md): Chat and conversation management.
  - [ExWapp.Client](ExWapp.Client.md): High-level, runtime-neutral ExWapp client.
  - [ExWapp.Contact](ExWapp.Contact.md): Contact struct and local CRUD operations.
  - [ExWapp.Event](ExWapp.Event.md): Runtime-neutral events emitted by the high-level client API.
  - [ExWapp.JSON](ExWapp.JSON.md): Configurable JSON boundary used by ExWapp.
  - [ExWapp.Media](ExWapp.Media.md): Public media helpers shared by send and receive flows.
  - [ExWapp.Message](ExWapp.Message.md): User-facing WhatsApp message struct.

- Extension points
  - [ExWapp.Client.Transport](ExWapp.Client.Transport.md): Behaviour for high-level, runtime-neutral ExWapp client adapters.
  - [ExWapp.Events](ExWapp.Events.md): Behaviour for delivering high-level ExWapp events.
  - [ExWapp.JSON.Library](ExWapp.JSON.Library.md): Contract expected from the configured JSON implementation.
  - [ExWapp.Store](ExWapp.Store.md): Persistence adapter behaviour for WhatsApp session state.

- Exceptions
  - [ExWapp.Error](ExWapp.Error.md): Structured error returned by high-level ExWapp client operations.

