Signal

let signal = client.signal();

pub async fn encrypt_message(
    &self,
    jid: &Jid,
    plaintext: &[u8],
) -> Result<(EncType, Vec<u8>), SignalError>

use whatsapp_rust::EncType;

let plaintext = b"Hello, world!";
let (enc_type, ciphertext) = client.signal().encrypt_message(&jid, plaintext).await?;

match enc_type {
    EncType::PreKeyMessage => println!("New session established"),
    EncType::Message => println!("Existing session used"),
    _ => {}
}

pub async fn decrypt_message(
    &self,
    jid: &Jid,
    enc_type: EncType,
    ciphertext: &[u8],
) -> Result<Vec<u8>, SignalError>

let plaintext = client.signal().decrypt_message(
    &sender_jid,
    EncType::Message,
    &ciphertext,
).await?;

pub async fn encrypt_group_message(
    &self,
    group_jid: &Jid,
    plaintext: &[u8],
) -> Result<(Option<Vec<u8>>, Vec<u8>), SignalError>

let (skdm, ciphertext) = client.signal().encrypt_group_message(
    &group_jid,
    &plaintext,
).await?;

if let Some(skdm_bytes) = skdm {
    // Distribute SKDM to all group participants
    println!("New sender key created, SKDM must be distributed");
}

pub async fn decrypt_group_message(
    &self,
    group_jid: &Jid,
    sender_jid: &Jid,
    ciphertext: &[u8],
) -> Result<Vec<u8>, SignalError>

let plaintext = client.signal().decrypt_group_message(
    &group_jid,
    &sender_jid,
    &ciphertext,
).await?;

pub async fn sender_key_distribution(
    &self,
    group_jid: &Jid,
    sender_jid: &Jid,
) -> Result<Vec<u8>, SignalError>

let distribution = client.signal().sender_key_distribution(&group_jid, &my_jid).await?;
// Send `distribution` to the new participant, e.g. wrapped in a SenderKeyDistributionMessage protocol node

pub async fn process_sender_key_distribution(
    &self,
    group_jid: &Jid,
    sender_jid: &Jid,
    distribution: &[u8],
) -> Result<(), SignalError>

client.signal().process_sender_key_distribution(
    &group_jid,
    &sender_jid,
    &distribution_bytes,
).await?;

pub async fn has_sender_key(
    &self,
    group_jid: &Jid,
    sender_jid: &Jid,
) -> Result<bool, SignalError>

if !client.signal().has_sender_key(&group_jid, &author_jid).await? {
    // No chain yet — process the SKDM before decrypting skmsg from this sender
}

pub async fn delete_sender_key(
    &self,
    group_jid: &Jid,
    sender_jid: &Jid,
) -> Result<(), SignalError>

// On leaving a group, drop the local copy of your own sender key chain
client.signal().delete_sender_key(&group_jid, &my_jid).await?;

pub async fn validate_session(&self, jid: &Jid) -> Result<bool, SignalError>

if client.signal().validate_session(&jid).await? {
    println!("Session exists for {}", jid);
} else {
    println!("No session — need to establish one first");
}

pub async fn session_info(&self, jid: &Jid) -> Result<Option<SignalSessionInfo>, SignalError>

if let Some(info) = client.signal().session_info(&jid).await? {
    println!("registration_id={} base_key_len={}", info.registration_id, info.base_key.len());
}

pub async fn delete_sessions(&self, jids: &[Jid]) -> Result<(), SignalError>

// Delete sessions for specific contacts
client.signal().delete_sessions(&[jid1, jid2]).await?;

pub async fn install_prekey_bundle(
    &self,
    jid: &Jid,
    bundle: &PreKeyBundle,
) -> Result<IdentityChange, SignalError>

let bundle: PreKeyBundle = /* fetched via a custom IQ */;
let identity_change = client.signal().install_prekey_bundle(&jid, &bundle).await?;

if identity_change == IdentityChange::ReplacedExisting {
    println!("warning: {jid}'s identity key changed");
}

pub async fn migrate_sessions(
    &self,
    from: &Jid,
    to: &Jid,
) -> Result<SignalSessionMigration, SignalError>

let outcome = client.signal().migrate_sessions(&pn_jid, &lid_jid).await?;

if outcome.has_state_changes() {
    println!(
        "migrated {} sessions, {} identities",
        outcome.migrated, outcome.migrated_identities
    );
}

pub async fn create_participant_nodes(
    &self,
    recipient_jids: &[Jid],
    message: &waproto::whatsapp::Message,
) -> Result<(Vec<Node>, bool), SignalError>

use waproto::whatsapp as wa;

let message = wa::Message {
    conversation: Some("Hello!".to_string()),
    ..Default::default()
};

let (nodes, include_identity) = client.signal().create_participant_nodes(
    &[recipient_jid],
    &message,
).await?;

pub async fn assert_sessions(&self, jids: &[Jid]) -> Result<(), SignalError>

// Ensure sessions exist before manual encryption
client.signal().assert_sessions(&[jid1, jid2]).await?;

pub async fn get_user_devices(&self, jids: &[Jid]) -> Result<Vec<Jid>, SignalError>

let devices = client.signal().get_user_devices(&[user_jid]).await?;
println!("User has {} devices", devices.len());

pub enum EncType {
    /// Standard Signal message (existing session)
    Message,
    /// PreKey Signal message (new session establishment)
    PreKeyMessage,
    /// Sender key message (group encryption)
    SenderKey,
    /// Bot message secret (`<enc type="msmsg">`) — Meta AI / fbid bot
    /// replies. Decrypted with the outbound `messageSecret`, not a Signal
    /// session. See [Bot message decryption](#bot-message-decryption-msmsg).
    MessageSecret,
}

pub struct SignalSessionInfo {
    /// Local base key identifying the active session state.
    pub base_key: Vec<u8>,
    /// Remote registration identifier recorded by the session.
    pub registration_id: u32,
}

#[non_exhaustive]
pub struct SignalSessionMigration {
    /// Pairwise sessions moved to the destination namespace.
    pub migrated: usize,
    /// Pairwise session lookups skipped after a storage error.
    pub skipped: usize,
    /// Pairwise sessions found or unsuccessfully queried.
    pub total: usize,
    /// Identity records moved when the destination had no identity.
    pub migrated_identities: usize,
    /// Source identity records removed in favor of an existing destination.
    pub discarded_identities: usize,
    /// Identity lookups skipped after a storage error.
    pub skipped_identities: usize,
}

// Ensure a session exists
client.signal().assert_sessions(&[recipient_jid.clone()]).await?;

// Encrypt
let plaintext = b"Secret message";
let (enc_type, ciphertext) = client.signal().encrypt_message(
    &recipient_jid,
    plaintext,
).await?;

// The recipient would decrypt with:
// let decrypted = client.signal().decrypt_message(&sender_jid, enc_type, &ciphertext).await?;

let has_session = client.signal().validate_session(&jid).await?;

if !has_session {
    // Establish session first
    client.signal().assert_sessions(&[jid.clone()]).await?;
}

let (enc_type, ciphertext) = client.signal().encrypt_message(&jid, plaintext).await?;

let (skdm, ciphertext) = client.signal().encrypt_group_message(
    &group_jid,
    &plaintext,
).await?;

if skdm.is_some() {
    // First message in this group or after key rotation.
    // The SKDM must be distributed to all participants
    // so they can decrypt future messages.
}

// New member needs the current sender key chain to decrypt future skmsg
if !client.signal().has_sender_key(&group_jid, &my_jid).await? {
    // Nothing sent to this group yet — no chain to distribute
} else {
    let distribution = client.signal().sender_key_distribution(&group_jid, &my_jid).await?;
    // Send `distribution` to the new participant
}

// Delete the corrupted session
client.signal().delete_sessions(&[jid.clone()]).await?;

// Re-establish
client.signal().assert_sessions(&[jid.clone()]).await?;

// Now encryption should work again
let (enc_type, ciphertext) = client.signal().encrypt_message(&jid, plaintext).await?;

// Migrate first — session_info(&pn_jid) would trigger this same migration as a
// side effect, which would leave nothing here for migrate_sessions to move.
let outcome = client.signal().migrate_sessions(&pn_jid, &lid_jid).await?;
if outcome.has_state_changes() {
    println!("moved {} session(s) to LID addressing", outcome.migrated);
}

// Inspect the session under its new LID address
if let Some(info) = client.signal().session_info(&lid_jid).await? {
    println!("registration_id={}", info.registration_id);
}

#[non_exhaustive]
pub enum SignalError {
    #[error("{0}")]
    Protocol(#[from] SignalProtocolError),
    #[error("unsupported signal operation: {0}")]
    Unsupported(String),
    #[error("invalid signal input: {0}")]
    InvalidInput(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}