docs: per-domain typed errors (whatsapp-rust#893)

api/blocking.mdx

@@ -20,7 +20,7 @@ let blocking = client.blocking();
 Block a contact. Accepts either a LID or a PN JID; the client resolves the LID↔PN pair from its mapping cache and emits a stanza carrying both (`jid=LID`, `pn_jid=PN`). Modern WhatsApp servers reject PN-only block requests.
 
 ```rust
-pub async fn block(&self, jid: &Jid) -> Result<(), IqError>
+pub async fn block(&self, jid: &Jid) -> Result<(), BlockingError>
 ```
 
 **Parameters:**
@@ -46,7 +46,7 @@ println!("Blocked {}", contact);
 Unblock a previously blocked contact. Accepts either a LID or a PN JID; PN input is internally resolved to the LID required on the wire.
 
 ```rust
-pub async fn unblock(&self, jid: &Jid) -> Result<(), IqError>
+pub async fn unblock(&self, jid: &Jid) -> Result<(), BlockingError>
 ```
 
 **Parameters:**
@@ -64,7 +64,7 @@ println!("Unblocked {}", contact);
 Retrieve the full list of blocked contacts.
 
 ```rust
-pub async fn get_blocklist(&self) -> Result<Vec<BlocklistEntry>, anyhow::Error>
+pub async fn get_blocklist(&self) -> Result<Vec<BlocklistEntry>, BlockingError>
 ```
 
 **Returns:**
@@ -94,7 +94,7 @@ for entry in blocklist {
 Check if a specific contact is blocked. Accepts either a LID or a PN JID; the client resolves the LID↔PN pair from its mapping cache so a PN-input query correctly matches a LID-keyed blocklist entry (and vice versa).
 
 ```rust
-pub async fn is_blocked(&self, jid: &Jid) -> Result<bool, anyhow::Error>
+pub async fn is_blocked(&self, jid: &Jid) -> Result<bool, BlockingError>
 ```
 
 **Parameters:**
@@ -136,22 +136,26 @@ The timestamp may be `None` if the server doesn't provide it.
 
 ## Error Types
 
-### IqError
+### BlockingError
 
-Returned by `block()` and `unblock()` operations:
+All methods return `Result<T, BlockingError>`:
 
 ```rust
-pub enum IqError {
-    // Network/protocol errors
-    Timeout,
-    InvalidResponse,
-    // ... other variants
+#[non_exhaustive]
+pub enum BlockingError {
+    #[error(transparent)]
+    Iq(#[from] IqError),
+    #[error("invalid blocklist target: {0}")]
+    InvalidJid(String),
+    #[error(transparent)]
+    Internal(#[from] anyhow::Error),
 }
 ```
 
-### anyhow::Error
-
-Returned by `get_blocklist()` and `is_blocked()` for general errors.
+**Variants:**
+- `Iq` — Wraps an IQ request failure (timeout, server error, etc.)
+- `InvalidJid` — The provided JID was not a valid blocklist target
+- `Internal` — Internal error (network, encoding, etc.)
 
 ## Wire Format
 
@@ -297,17 +301,17 @@ for contact in contacts_to_block {
 ## Error Handling
 
 ```rust
-use whatsapp_rust::request::IqError;
+use whatsapp_rust::BlockingError;
 
 let contact: Jid = "15551234567@s.whatsapp.net".parse()?;
 
 match client.blocking().block(&contact).await {
     Ok(_) => println!("Blocked successfully"),
-    Err(IqError::Timeout) => {
-        eprintln!("Request timed out");
+    Err(BlockingError::Iq(e)) => {
+        eprintln!("IQ request failed: {}", e);
     }
-    Err(IqError::InvalidResponse) => {
-        eprintln!("Invalid response from server");
+    Err(BlockingError::InvalidJid(msg)) => {
+        eprintln!("Invalid JID: {}", msg);
     }
     Err(e) => eprintln!("Error: {}", e),
 }

api/bot.mdx

@@ -666,7 +666,7 @@ Extracts a `MessageContext` from an `Event`. Returns `None` if the event is not
 ### send_message
 
 ```rust
-pub async fn send_message(&self, message: wa::Message) -> Result<SendResult, anyhow::Error>
+pub async fn send_message(&self, message: wa::Message) -> Result<SendResult, SendError>
 ```
 
 Sends a message to the same chat. Returns a [`SendResult`](/api/send#sendresult) containing the `message_id` and `to` JID.
@@ -711,7 +711,7 @@ pub async fn edit_message(
     &self,
     original_message_id: impl Into<String>,
     new_message: wa::Message
-) -> Result<String, anyhow::Error>
+) -> Result<String, SendError>
 ```
 
 Edits a message in the same chat.
@@ -723,15 +723,15 @@ pub async fn revoke_message(
     &self,
     message_id: String,
     revoke_type: RevokeType
-) -> Result<(), anyhow::Error>
+) -> Result<(), SendError>
 ```
 
 Deletes a message in the same chat.
 
 ### react
 
 ```rust
-pub async fn react(&self, emoji: &str) -> Result<SendResult, anyhow::Error>
+pub async fn react(&self, emoji: &str) -> Result<SendResult, SendError>
 ```
 
 Sends an emoji reaction to the incoming message. The chat JID, target message ID, and group/status `participant` are taken from the context — you only supply the emoji. Pass an empty string (`""`) to remove a previously sent reaction.

api/chat-actions.mdx

@@ -592,17 +592,29 @@ use wacore::types::events::Event;
 
 ## Error handling
 
-All methods return `Result<(), anyhow::Error>`. Common errors:
+All methods return `Result<(), AppStateError>`:
 
-- No app state sync key available (sync not complete)
-- Invalid timestamp for `mute_chat_until`
-- Missing `participant_jid` for group star/delete operations
-- Network errors
+```rust
+#[non_exhaustive]
+pub enum AppStateError {
+    #[error("invalid app-state request: {0}")]
+    InvalidRequest(String),
+    #[error(transparent)]
+    Internal(#[from] anyhow::Error),
+}
+```
+
+Common errors:
+- `InvalidRequest` — invalid timestamp for `mute_chat_until`, missing `participant_jid` for group operations
+- `Internal` — no app state sync key available (sync not complete), network errors
 
 ```rust
+use whatsapp_rust::AppStateError;
+
 match client.chat_actions().mute_chat_until(&jid, 0).await {
     Ok(_) => println!("Muted"),
-    Err(e) => eprintln!("Failed: {}", e), // Timestamp validation error
+    Err(AppStateError::InvalidRequest(msg)) => eprintln!("Validation error: {}", msg),
+    Err(e) => eprintln!("Failed: {}", e),
 }
 ```
 

api/chatstate.mdx

@@ -24,15 +24,15 @@ pub async fn send(
     &self,
     to: &Jid,
     state: ChatStateType,
-) -> Result<(), ClientError>
+) -> Result<(), ChatStateError>
 ```
 
 **Parameters:**
 - `to` - Recipient JID (user or group)
 - `state: ChatStateType` - Type of chat state to send
 
 **Returns:**
-- `Result<(), ClientError>` - Success or client error
+- `Result<(), ChatStateError>` - Success or client error
 
 **Example:**
 ```rust
@@ -55,7 +55,7 @@ client.chatstate().send(&recipient, ChatStateType::Paused).await?;
 Convenience method to send typing indicator.
 
 ```rust
-pub async fn send_composing(&self, to: &Jid) -> Result<(), ClientError>
+pub async fn send_composing(&self, to: &Jid) -> Result<(), ChatStateError>
 ```
 
 **Example:**
@@ -69,7 +69,7 @@ client.chatstate().send_composing(&recipient).await?;
 Convenience method to send audio recording indicator.
 
 ```rust
-pub async fn send_recording(&self, to: &Jid) -> Result<(), ClientError>
+pub async fn send_recording(&self, to: &Jid) -> Result<(), ChatStateError>
 ```
 
 **Example:**
@@ -84,7 +84,7 @@ println!("Showing 'recording audio' indicator");
 Convenience method to send paused/stopped typing indicator.
 
 ```rust
-pub async fn send_paused(&self, to: &Jid) -> Result<(), ClientError>
+pub async fn send_paused(&self, to: &Jid) -> Result<(), ChatStateError>
 ```
 
 **Example:**
@@ -349,21 +349,21 @@ client.send_message(group_jid.clone(), message).await?;
 
 ## Error Handling
 
-All methods return `Result<(), ClientError>`. Common errors:
+All methods return `Result<(), ChatStateError>`. Common errors:
 
 - **Not connected**: Client not connected to WhatsApp
 - **Invalid JID**: Malformed recipient JID
 - **Network errors**: Connection issues
 
 ```rust
-use whatsapp_rust::client::ClientError;
+use whatsapp_rust::ChatStateError;
 
 let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;
 
 match client.chatstate().send_composing(&recipient).await {
     Ok(_) => println!("Sent typing indicator"),
-    Err(ClientError::NotConnected) => {
-        eprintln!("Not connected to WhatsApp");
+    Err(ChatStateError::Client(e)) => {
+        eprintln!("Client error: {}", e);
     }
     Err(e) => eprintln!("Error: {}", e),
 }

api/community.mdx

@@ -23,7 +23,7 @@ Create a new community.
 pub async fn create(
     &self,
     options: CreateCommunityOptions,
-) -> Result<CreateCommunityResult, anyhow::Error>
+) -> Result<CreateCommunityResult, CommunityError>
 ```
 
 **Parameters:**
@@ -56,7 +56,7 @@ Since v0.6, `community().create()` returns the full `GroupMetadata` instead of j
 Deactivate (delete) a community. Subgroups are unlinked but not deleted.
 
 ```rust
-pub async fn deactivate(&self, community_jid: &Jid) -> Result<(), anyhow::Error>
+pub async fn deactivate(&self, community_jid: &Jid) -> Result<(), CommunityError>
 ```
 
 **Parameters:**
@@ -76,7 +76,7 @@ pub async fn link_subgroups(
     &self,
     community_jid: &Jid,
     subgroup_jids: &[Jid],
-) -> Result<LinkSubgroupsResult, anyhow::Error>
+) -> Result<LinkSubgroupsResult, CommunityError>
 ```
 
 **Parameters:**
@@ -113,7 +113,7 @@ pub async fn unlink_subgroups(
     community_jid: &Jid,
     subgroup_jids: &[Jid],
     remove_orphan_members: bool,
-) -> Result<UnlinkSubgroupsResult, anyhow::Error>
+) -> Result<UnlinkSubgroupsResult, CommunityError>
 ```
 
 **Parameters:**
@@ -141,7 +141,7 @@ Fetch all subgroups of a community via MEX (GraphQL).
 pub async fn get_subgroups(
     &self,
     community_jid: &Jid,
-) -> Result<Vec<CommunitySubgroup>, MexError>
+) -> Result<Vec<CommunitySubgroup>, CommunityError>
 ```
 
 **Parameters:**
@@ -170,7 +170,7 @@ Fetch participant counts per subgroup via MEX (GraphQL).
 pub async fn get_subgroup_participant_counts(
     &self,
     community_jid: &Jid,
-) -> Result<Vec<(Jid, u32)>, MexError>
+) -> Result<Vec<(Jid, u32)>, CommunityError>
 ```
 
 **Parameters:**
@@ -199,7 +199,7 @@ pub async fn query_linked_group(
     &self,
     community_jid: &Jid,
     subgroup_jid: &Jid,
-) -> Result<GroupMetadata, anyhow::Error>
+) -> Result<GroupMetadata, CommunityError>
 ```
 
 **Parameters:**
@@ -227,7 +227,7 @@ pub async fn join_subgroup(
     &self,
     community_jid: &Jid,
     subgroup_jid: &Jid,
-) -> Result<GroupMetadata, anyhow::Error>
+) -> Result<GroupMetadata, CommunityError>
 ```
 
 **Parameters:**
@@ -254,7 +254,7 @@ Get all participants across all linked groups of a community.
 pub async fn get_linked_groups_participants(
     &self,
     community_jid: &Jid,
-) -> Result<Vec<GroupParticipant>, anyhow::Error>
+) -> Result<Vec<GroupParticipant>, CommunityError>
 ```
 
 **Parameters:**
@@ -414,18 +414,29 @@ let gtype = group_type(&metadata);
 
 ## Error handling
 
-Mutation methods (`create`, `deactivate`, `link_subgroups`, `unlink_subgroups`, `query_linked_group`, `join_subgroup`, `get_linked_groups_participants`) return `anyhow::Error`.
+All community methods return `Result<T, CommunityError>`:
 
-MEX-based query methods (`get_subgroups`, `get_subgroup_participant_counts`) return `MexError`:
+```rust
+#[non_exhaustive]
+pub enum CommunityError {
+    #[error(transparent)]
+    Iq(#[from] IqError),
+    #[error(transparent)]
+    Mex(#[from] MexError),
+    #[error(transparent)]
+    Group(#[from] GroupError),
+    #[error("invalid community request: {0}")]
+    InvalidRequest(String),
+}
+```
 
 ```rust
-use whatsapp_rust::features::mex::MexError;
+use whatsapp_rust::CommunityError;
 
-match client.community().get_subgroups(&community_jid).await {
-    Ok(subgroups) => println!("Found {} subgroups", subgroups.len()),
-    Err(MexError::PayloadParsing(msg)) => {
-        eprintln!("Parse error: {}", msg);
-    }
+match client.community().deactivate(&community_jid).await {
+    Ok(_) => println!("Community deactivated"),
+    Err(CommunityError::Iq(e)) => eprintln!("Server error: {}", e),
+    Err(CommunityError::Mex(e)) => eprintln!("MEX error: {}", e),
     Err(e) => eprintln!("Error: {}", e),
 }
 ```