docs: per-domain typed errors (whatsapp-rust#893) - #346
Conversation
Every public API now returns a typed domain-specific error instead of anyhow::Error. This updates all affected API reference pages and guides to reflect the new return types. Changes: - Add api/errors.mdx: new reference page with full hierarchy, type definitions for all 15 domain errors, and migration guide - Update api/send.mdx: all send-path methods now return SendError - Update api/groups.mdx: all methods now return GroupError (was anyhow + MexError) - Update api/blocking.mdx: all methods now return BlockingError (was IqError + anyhow) - Update api/chat-actions.mdx: all methods now return AppStateError - Update api/labels.mdx: all methods now return AppStateError - Update api/chatstate.mdx: all methods now return ChatStateError (was ClientError) - Update api/community.mdx: all methods now return CommunityError (was anyhow + MexError) - Update api/contacts.mdx: all methods now return ContactError - Update api/newsletter.mdx: all methods now return NewsletterError (was MexError + anyhow) - Update api/polls.mdx: create/vote now return PollError - Update api/profile.mdx: all methods now return ProfileError - Update api/presence.mdx: subscribe/unsubscribe now return PresenceError; PresenceError gains Client variant - Update api/signal.mdx: all methods now return SignalError - Update api/media-reupload.mdx: request now returns MediaReuploadError - Update api/bot.mdx: MessageContext methods now return SendError - Update guides/sending-messages.mdx: error handling example uses SendError - Update docs.json: add api/errors to navigation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
📝 WalkthroughWalkthroughAll ChangesTyped Domain Error Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bcceeadfe5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- CommunityError: replace Internal with Group(#[from] GroupError) - ContactError: replace InvalidRequest/Internal with InvalidJid only - ProfileError: rename InvalidRequest to InvalidArgument, add Iq variant - newsletter.mdx: fix metadata.id -> metadata.jid in example - polls.mdx: fix create() call args (&options, 1 not options, false) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api/blocking.mdx (1)
23-30:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate the stale missing-mapping error type.
Line 30 still says the call returns
IqError::EncodeError, but the documented signature now returnsBlockingError. Wrap the variant in the typed error, or name the actualBlockingErrorvariant callers should match.Proposed documentation fix
-- A LID↔PN mapping for the target must exist in the client's mapping store. If no mapping is available, the call returns `IqError::EncodeError`. +- A LID↔PN mapping for the target must exist in the client's mapping store. If no mapping is available, the call returns `BlockingError::Iq(IqError::EncodeError)`.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/blocking.mdx` around lines 23 - 30, Update the documentation for the block function's Requirements section to accurately reflect the return type. The current documentation states that the call returns IqError::EncodeError when no LID↔PN mapping is available, but the function signature shows it returns BlockingError. Replace the reference to IqError::EncodeError with the actual BlockingError variant that is returned in this error case, ensuring the documented error type matches what callers will actually receive when handling the Result.
🧹 Nitpick comments (3)
api/errors.mdx (1)
6-6: ⚡ Quick winRefactor the opening paragraph to follow style guidelines.
This line combines multiple independent ideas in a single sentence and uses passive voice. Per coding guidelines, use active voice, second person ("you"), and keep one idea per sentence.
Currently, the line bundles together: PR
#893change,#[non_exhaustive]attribute,std::error::Errorimplementation, and?propagation behavior.✨ Suggested revision
-As of PR `#893`, every public API returns a typed, domain-specific error instead of `anyhow::Error`. All types are `#[non_exhaustive]` and implement `std::error::Error`, so `?` into an `anyhow` context still compiles unchanged. +As of PR `#893`, you now receive typed, domain-specific errors instead of `anyhow::Error` from every public API. +All error types are `#[non_exhaustive]` and implement `std::error::Error`. +You can still use `?` to propagate errors into an `anyhow` context unchanged.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/errors.mdx` at line 6, The opening paragraph of the errors.mdx file combines multiple independent ideas into a single sentence and uses passive voice, which violates style guidelines. Refactor this paragraph to use active voice and second person ("you"), breaking it into separate sentences so that each sentence conveys only one idea. Specifically, separate the concepts of: the change introduced in PR `#893` (public APIs returning typed, domain-specific errors instead of anyhow::Error), the #[non_exhaustive] attribute on all types, the std::error::Error implementation, and the behavior of ? propagation into anyhow contexts. Use clear, direct language with you-focused phrasing throughout.Source: Coding guidelines
api/send.mdx (1)
1229-1229: ⚡ Quick winFormat the type heading as code.
SendErroris a Rust type reference, so wrap it in backticks.Suggested change
-### SendError +### `SendError`As per coding guidelines, use code formatting for file names, commands, paths, and code references in documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/send.mdx` at line 1229, The SendError type heading needs to be formatted as code to comply with documentation standards. In the heading that reads SendError, wrap the type name in backticks to format it as a code reference, so it displays as a code element rather than plain text. This applies the same code formatting convention used throughout the documentation for Rust type references, commands, and file names.Source: Coding guidelines
api/blocking.mdx (1)
139-139: ⚡ Quick winFormat the error type heading as code.
Line 139 names a Rust type, so wrap it in backticks for consistent MDX rendering.
Proposed documentation fix
-### BlockingError +### `BlockingError`As per coding guidelines, "Use code formatting for file names, commands, paths, and code references in documentation."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/blocking.mdx` at line 139, The heading for BlockingError at line 139 needs to be formatted as code to follow documentation guidelines for Rust type references. Modify the heading from "### BlockingError" to wrap the type name in backticks to render it as code formatting in MDX. This ensures consistent documentation style for all code references and type names throughout the file.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api/chat-actions.mdx`:
- Around line 595-609: Rewrite the error handling documentation in second-person
voice addressing the reader directly. Change the introductory text about what
"All methods return" to use "you" perspective. For the error descriptions
starting with "Common errors", replace the third-person explanations with
second-person active voice sentences. Break up the multi-example phrasing for
InvalidRequest and Internal variants into separate concise sentences, keeping
one idea per sentence. Reference the specific error types (InvalidRequest with
mute_chat_until and participant_jid examples, and Internal with sync key and
network error examples) while maintaining clarity and directness.
In `@api/chatstate.mdx`:
- Around line 30-36: The parameter and return value descriptions in the
documentation for the ChatStateType method use passive/generic language instead
of second-person active voice. Reword the descriptions for the `to` parameter,
`state: ChatStateType` parameter, and the `Result<(), ChatStateError>` return
value to speak directly to the reader using "you" and active voice. Apply the
same second-person phrasing updates to the equivalent section starting at line
352-357 for consistency across the documentation.
In `@api/community.mdx`:
- Around line 419-431: The CommunityError enum is missing the required derive
macro declarations for the thiserror macros to function. Add #[derive(Error,
Debug)] above the #[non_exhaustive] attribute on the CommunityError enum
definition to enable the #[error(...)] attributes to compile correctly.
In `@api/groups.mdx`:
- Around line 1448-1464: The GroupError enum is missing the required derive
macro for the Error trait implementation. Add the #[derive(Debug,
thiserror::Error)] attribute directly above the #[non_exhaustive] attribute on
the GroupError enum definition. Additionally, update the heading from "###
GroupError" to use code formatting like "### `GroupError`" to follow
documentation guidelines for code references.
In `@api/labels.mdx`:
- Around line 162-163: The documentation sentence combining the method return
type and validation behavior uses impersonal wording and combines multiple
ideas. Split the sentence into separate shorter sentences, convert passive voice
to active voice using second-person ("you"), and ensure each sentence conveys
one idea. Specifically, separate the statement about what methods return from
the statement about how empty label_id and name parameters are validated, and
rewrite using "you" language to make the validation behavior more scannable and
direct.
In `@api/media-reupload.mdx`:
- Around line 134-137: The enum definition includes a Client variant with
ClientError but the documentation list for error explanations is incomplete. Add
a new documentation entry for the Client variant in the explanatory list
alongside NotLoggedIn, InvalidRequest, Timeout, and Internal to provide a
complete reference for all error types that can be returned.
In `@api/newsletter.mdx`:
- Around line 523-552: The error handling example in the match statement uses
`metadata.id` when printing the joined newsletter metadata, but this is
inconsistent with other examples in the file (lines 90, 118, 139) which use
`metadata.jid` or `metadata.name`. Replace `metadata.id` in the success branch
of the match statement (the Ok case for the newsletter join operation) with
`metadata.jid` to maintain consistency with the field names used throughout the
documentation examples.
In `@api/polls.mdx`:
- Around line 405-432: In the error handling example showing the
client.polls().create() method call, there is a type mismatch where the fourth
argument is passed as false (boolean) but the method signature requires
selectable_count as a u32 type. Replace the false boolean value with an
appropriate u32 integer value. Additionally, add reference operators (&) to both
the jid and options parameters in the create() call to match the method
signature which expects reference parameters.
In `@api/presence.mdx`:
- Around line 256-259: Update the introductory scope text of the PresenceError
section to include subscribe and unsubscribe methods. The current text indicates
that PresenceError is returned only by set, set_available, and set_unavailable
methods, but the documentation at lines 77 and 101 shows that subscribe and
unsubscribe also return PresenceError. Modify the scope description (the text
before the Variants bullet points) to reflect that all five methods—set,
set_available, set_unavailable, subscribe, and unsubscribe—can return
PresenceError.
In `@api/profile.mdx`:
- Line 151: Update the documentation at line 151 in api/profile.mdx to
accurately describe the method return types. Change the statement from saying
methods return a `ProfileError` to properly documenting that they return a
`Result<T, ProfileError>` type, which represents either a successful value of
type T or a ProfileError on failure. This clarifies the actual return type
signature that users will see when calling these methods.
In `@api/send.mdx`:
- Around line 1233-1246: The SendError enum uses thiserror helper attributes
like #[error(...)] and #[from] but is missing the required derive macro that
registers these attributes. Add the #[derive(Debug, thiserror::Error)] macro
above the SendError enum definition to enable the thiserror crate to process the
helper attributes and make the enum compilable.
In `@api/signal.mdx`:
- Line 375: The heading for SignalError at line 375 is not using code formatting
even though it's a type reference. Wrap the SignalError text in backticks within
the heading (change `### SignalError` to `### \`SignalError\``) to properly
format it as code per documentation guidelines for code references.
In `@guides/sending-messages.mdx`:
- Around line 876-888: Update the documentation voice from third-person
("Callers") to second-person ("you") and split the sentence that combines two
separate ideas about error handling. In the code example, replace the import of
`SendError` with `use anyhow::Result;`, rename the function `send_with_retry` to
`send_and_return_id` (since it contains no actual retry logic), change the
return type from `Result<String, SendError>` to `Result<String>`, and remove the
unnecessary `clone()` call on the `jid` parameter to demonstrate proper `anyhow`
compatibility as described in the documentation.
---
Outside diff comments:
In `@api/blocking.mdx`:
- Around line 23-30: Update the documentation for the block function's
Requirements section to accurately reflect the return type. The current
documentation states that the call returns IqError::EncodeError when no LID↔PN
mapping is available, but the function signature shows it returns BlockingError.
Replace the reference to IqError::EncodeError with the actual BlockingError
variant that is returned in this error case, ensuring the documented error type
matches what callers will actually receive when handling the Result.
---
Nitpick comments:
In `@api/blocking.mdx`:
- Line 139: The heading for BlockingError at line 139 needs to be formatted as
code to follow documentation guidelines for Rust type references. Modify the
heading from "### BlockingError" to wrap the type name in backticks to render it
as code formatting in MDX. This ensures consistent documentation style for all
code references and type names throughout the file.
In `@api/errors.mdx`:
- Line 6: The opening paragraph of the errors.mdx file combines multiple
independent ideas into a single sentence and uses passive voice, which violates
style guidelines. Refactor this paragraph to use active voice and second person
("you"), breaking it into separate sentences so that each sentence conveys only
one idea. Specifically, separate the concepts of: the change introduced in PR
`#893` (public APIs returning typed, domain-specific errors instead of
anyhow::Error), the #[non_exhaustive] attribute on all types, the
std::error::Error implementation, and the behavior of ? propagation into anyhow
contexts. Use clear, direct language with you-focused phrasing throughout.
In `@api/send.mdx`:
- Line 1229: The SendError type heading needs to be formatted as code to comply
with documentation standards. In the heading that reads SendError, wrap the type
name in backticks to format it as a code reference, so it displays as a code
element rather than plain text. This applies the same code formatting convention
used throughout the documentation for Rust type references, commands, and file
names.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 64eeb39d-ea2c-444c-ab09-ff16c50f35e3
📒 Files selected for processing (18)
api/blocking.mdxapi/bot.mdxapi/chat-actions.mdxapi/chatstate.mdxapi/community.mdxapi/contacts.mdxapi/errors.mdxapi/groups.mdxapi/labels.mdxapi/media-reupload.mdxapi/newsletter.mdxapi/polls.mdxapi/presence.mdxapi/profile.mdxapi/send.mdxapi/signal.mdxdocs.jsonguides/sending-messages.mdx
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
6 issues found and verified against the latest diff
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api/polls.mdx">
<violation number="1" location="api/polls.mdx:428">
P1: Example passes `false` (bool) as `selectable_count` but the signature expects `u32`. Replace with `1` or another integer literal.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
|
||
| match client.polls().create(jid, "Question?", &options, 1).await { | ||
| Ok((result, secret)) => println!("Poll created: {}", result.message_id), | ||
| Err(PollError::InvalidPoll(msg)) => eprintln!("Invalid poll: {}", msg), |
There was a problem hiding this comment.
P1: Example passes false (bool) as selectable_count but the signature expects u32. Replace with 1 or another integer literal.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api/polls.mdx, line 428:
<comment>Example passes `false` (bool) as `selectable_count` but the signature expects `u32`. Replace with `1` or another integer literal.</comment>
<file context>
@@ -404,20 +404,30 @@ The `EncryptedEdit` type from v0.5 still exists as a `MessageEdit`-specific faç
+
+match client.polls().create(jid, "Question?", options, false).await {
+ Ok((result, secret)) => println!("Poll created: {}", result.message_id),
+ Err(PollError::InvalidPoll(msg)) => eprintln!("Invalid poll: {}", msg),
+ Err(PollError::Send(e)) => eprintln!("Send failed: {}", e),
+ Err(e) => eprintln!("Error: {}", e),
</file context>
Correctness: - blocking.mdx: IqError::EncodeError → BlockingError::Iq(IqError::EncodeError) - community.mdx: add #[derive(Debug, thiserror::Error)] to CommunityError snippet - groups.mdx: add #[derive(Debug, thiserror::Error)] to GroupError snippet - send.mdx: add #[derive(Debug, thiserror::Error)] to SendError snippet - presence.mdx: expand Client variant doc to include subscribe/unsubscribe - profile.mdx: fix "return a ProfileError" → "return Result<T, ProfileError>" - media-reupload.mdx: add missing Client variant to explanatory list - chat-actions.mdx: add #[derive(Debug, thiserror::Error)] to AppStateError snippet Style/nitpicks: - blocking.mdx, groups.mdx, send.mdx, signal.mdx: backtick-quote error type headings - errors.mdx: rewrite opening sentence in second-person active voice - chatstate.mdx, chat-actions.mdx, labels.mdx: second-person voice in error sections - sending-messages.mdx: rename send_with_retry → send_and_return_id, use anyhow::Result Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
… order Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 47fec504c7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Error handling | ||
|
|
||
| All methods return `Result<(), anyhow::Error>`. Common errors: | ||
| All methods return `Result<(), AppStateError>`: |
There was a problem hiding this comment.
This section now says all chat actions return AppStateError, and the #893 implementation does (Result<(), AppStateError>), but every signature on this page still shows bare Result<()> (e.g. archive_chat, pin_chat, mute_chat_until). Callers copying the API reference won't know the actual error type to import or match; update the method signatures as part of this typed-error migration.
Useful? React with 👍 / 👎.
| ## Error handling | ||
|
|
||
| All methods return `Result<(), anyhow::Error>`. Empty `label_id` (and empty `name` for `create_label`) is rejected before any network work. | ||
| All methods return `Result<(), AppStateError>`. If you pass an empty `label_id` (or an empty `name` to `create_label`), the call fails immediately with `AppStateError::InvalidRequest` before any network work is done. |
There was a problem hiding this comment.
Although this section says AppStateError, the method signatures above still show bare Result<()> for create_label, delete_label, add_chat_label, and remove_chat_label; the #893 implementation returns Result<(), AppStateError>. Users reading the signature snippets will miss the typed error and may keep importing anyhow::Result instead of matching AppStateError.
Useful? React with 👍 / 👎.
| ## Error handling | ||
|
|
||
| All methods return `Result<T, anyhow::Error>`. Common errors: | ||
| Send methods (`create`, `create_quiz`, `vote`) return `Result<T, PollError>`: |
There was a problem hiding this comment.
PollError is not limited to the send methods after #893: decrypt_vote and aggregate_votes also return PollError (their current signatures above are still untyped/old-shaped). By documenting only create, create_quiz, and vote, this section leaves the vote-decryption migration path incorrect for callers who need to handle PollError::Crypto.
Useful? React with 👍 / 👎.
- errors.mdx: narrow "every public API" claim — Client::connect and media upload/download are not covered by domain error types yet - chat-actions.mdx: update all 16 method signatures from Result<()> to Result<(), AppStateError> to match the implementation - labels.mdx: update all 4 method signatures from Result<()> to Result<(), AppStateError> to match the implementation - polls.mdx: update decrypt_vote/aggregate_votes signatures to include PollError; expand error section to cover all five poll methods Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1c49979c21
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Requirements:** | ||
| - A LID↔PN mapping for the target must exist in the client's mapping store. If no mapping is available, the call returns `IqError::EncodeError`. | ||
| - A LID↔PN mapping for the target must exist in the client's mapping store. If no mapping is available, the call returns `BlockingError::Iq(IqError::EncodeError)`. |
There was a problem hiding this comment.
When block() is called with a PN/LID that has no cached LID↔PN mapping, resolve_lid_pn returns BlockingError::InvalidJid("no LID↔PN mapping..."), not an IQ encode failure. This guidance sends callers to handle BlockingError::Iq(IqError::EncodeError), so code copied from the docs will miss the actual validation error for this local cache-miss case.
Useful? React with 👍 / 👎.
| #[error("client is already connected")] | ||
| AlreadyConnected, | ||
| #[error("client is not logged in")] | ||
| NotLoggedIn, | ||
| #[error("IQ request failed: {0}")] | ||
| Iq(#[from] IqError), | ||
| #[error(transparent)] | ||
| Internal(#[from] anyhow::Error), |
There was a problem hiding this comment.
For callers matching domain errors that wrap ClientError (for example PresenceError::Client or SendError::Client), this reference omits the public ClientError::Socket and ClientError::EncryptSend variants that #893 added for transport failures. A user copying the listed enum as the complete base error shape will not know how to handle those connection failures, even though they are surfaced directly by the public API.
Useful? React with 👍 / 👎.
| Disconnected, | ||
| ServerError, | ||
| EncodeError, | ||
| DecodeError, |
There was a problem hiding this comment.
The #893 IqError enum does not define DecodeError; parse failures are exposed as ParseError(#[from] anyhow::Error), and the enum also has public variants such as Socket, UnexpectedResponseType, and InternalChannelClosed. Since many domain errors wrap IqError, callers following this reference would write match arms for a variant that will not compile and miss real IQ failure modes.
Useful? React with 👍 / 👎.
- errors.mdx: replace nonexistent DecodeError with actual ParseError; add missing Socket, EncryptSend, UnexpectedResponseType, InternalChannelClosed variants to IqError; add Socket and EncryptSend to ClientError — all identified by Codex review - blocking.mdx: fix Requirements note: missing LID↔PN mapping returns BlockingError::InvalidJid, not BlockingError::Iq(IqError::EncodeError) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a2486c9525
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| | Error type | Returned by | Module | | ||
| |---|---|---| | ||
| | `SendError` | `send_message`, `revoke_message`, `edit_message`, `pin_message`, `send_reaction`, and all other send-path methods | `whatsapp_rust` | |
There was a problem hiding this comment.
This new SendError row says all send-path methods use SendError, but the API reference still documents several of those same public methods with anyhow::Error, including Client::send_message/send_text/edit_message/revoke_message in api/client.mdx and status posting/revoke methods in api/status.mdx. In the #893 source those paths return Result<..., SendError>, so readers who land on those pages will import or match the wrong error type unless they are updated as part of this migration.
Useful? React with 👍 / 👎.
| | `PollError` | `Polls::{create, create_quiz, vote}` | `whatsapp_rust` | | ||
| | `ProfileError` | All `Profile::*` methods | `whatsapp_rust` | | ||
| | `SignalError` | All `Signal::*` methods | `whatsapp_rust` | | ||
| | `TcTokenError` | All `TcToken::*` methods | `whatsapp_rust` | |
There was a problem hiding this comment.
This row introduces TcTokenError as the error for every TcToken method, but the linked api/tctoken.mdx page still shows issue_tokens returning IqError and the storage helpers returning anyhow::Error. The #893 implementation returns TcTokenError for all four methods, including store failures via TcTokenError::Store, so callers following the feature page will handle the wrong error shape.
Useful? React with 👍 / 👎.
…token pages - api/client.mdx: send_message, send_message_with_options, edit_message, revoke_message all return SendError (not anyhow::Error) since #893 - api/status.mdx: send_text, send_image, send_video, send_raw, revoke, send_reaction all return SendError (not anyhow::Error) since #893 - api/tctoken.mdx: issue_tokens returns TcTokenError (not IqError); prune_expired, get, get_all_jids return TcTokenError (not anyhow::Error); add TcTokenError type definition and error handling example Addresses Codex P2 findings on api/errors.mdx lines 35 and 46. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 79b08723a3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| server_id: u64, | ||
| reaction: &str, | ||
| ) -> Result<(), anyhow::Error> | ||
| ) -> Result<SendResult, SendError> |
There was a problem hiding this comment.
In the #893 source, Status only exposes status posting/revoke helpers (send_text, send_image, send_video, send_raw, and revoke); status reactions are handled by the send/reaction API, not by client.status(). Keeping this migrated signature makes users copy client.status().send_reaction(...), which does not compile; remove this section or redirect it to Client::send_reaction.
Useful? React with 👍 / 👎.
| ## Error hierarchy | ||
|
|
||
| ``` | ||
| ClientError (transport/connection base — embedded by all domain errors) |
There was a problem hiding this comment.
This says ClientError is embedded by all domain errors, but several documented domain enums do not contain a Client/ClientError variant at all, including AppStateError, SignalError, TcTokenError, and ContactError. Callers following this hierarchy will expect match arms such as SignalError::Client(_) or TcTokenError::Client(_) that do not compile, so the hierarchy should describe ClientError as used only by the domains that actually wrap it.
Useful? React with 👍 / 👎.
- status.mdx: send_reaction is on Client, not Status; update signature, accessor (client.send_reaction vs client.status().send_reaction), and example to use wa::MessageKey with status@broadcast - errors.mdx: ClientError hierarchy was missing Socket and EncryptSend variants; IqError had DecodeError (should be ParseError) and was missing Socket, UnexpectedResponseType, InternalChannelClosed; "all domain errors" overclaim corrected to "select domain errors" with AppStateError/SignalError called out as exceptions Addresses Codex P2 findings on PR #346. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6eeae3abd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `CommunityError` | All `Community::*` methods | `whatsapp_rust` | | ||
| | `ContactError` | All `Contacts::*` methods | `whatsapp_rust` | | ||
| | `NewsletterError` | All `Newsletter::*` methods | `whatsapp_rust` | | ||
| | `PollError` | `Polls::{create, create_quiz, vote}` | `whatsapp_rust` | |
There was a problem hiding this comment.
Although the poll page now correctly says decrypt_vote and aggregate_votes also return PollError, this central reference still narrows PollError to only the send/create paths. Callers using this table for the typed-error migration will miss the decryption/aggregation failure path, especially PollError::Crypto, and may continue handling those methods as non-domain errors.
Useful? React with 👍 / 👎.
The central error-types table omitted these two methods from the PollError row, which would cause callers following the migration guide to miss the PollError::Crypto path for decryption failures. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
api/status.mdx (1)
216-217: 💤 Low valueConsider using active voice for consistency.
Per coding guidelines, documentation should use active voice and second person. The phrase "Status reactions are sent via" uses passive voice.
Suggested rewrite:
-React to a status update with an emoji. Status reactions are sent via `Client::send_reaction` (not `client.status()`) using `status@broadcast` as the chat JID and a `wa::MessageKey` whose `participant` field identifies the status owner. +React to a status update with an emoji. You send status reactions via `Client::send_reaction` (not `client.status()`) using `status@broadcast` as the chat JID and a `wa::MessageKey` whose `participant` field identifies the status owner.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/status.mdx` around lines 216 - 217, The documentation at the status update reaction section uses passive voice ("Status reactions are sent via") which conflicts with the active voice style guidelines. Rewrite this sentence to use active voice and second person perspective, making it clear that the reader should use Client::send_reaction method with the specified parameters (status@broadcast as the chat JID and a wa::MessageKey with participant field).Source: Coding guidelines
api/tctoken.mdx (1)
125-125: ⚡ Quick winUse second-person wording in the error-handling prose.
These lines are informative but impersonal. Rewrite them to address the reader directly.
As per coding guidelines, use active voice and second person ("you") in documentation, and keep sentences concise — one idea per sentence.
Suggested edit
-All methods return `Result<T, TcTokenError>`: +When you call these methods, you get `Result<T, TcTokenError>`: **Variants:** -- `Iq` — The IQ requesting tokens from the server failed (timeout, server error, etc.) -- `Store` — A token store (persistence) operation failed +- `Iq` — You get this when requesting tokens from the server fails (timeout, server error, etc.). +- `Store` — You get this when token persistence fails.Also applies to: 138-139
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/tctoken.mdx` at line 125, Rewrite the error-handling documentation in the tctoken.mdx file to use second-person wording that addresses the reader directly. The line stating "All methods return `Result<T, TcTokenError>`:" should be changed to active voice using "you" to make it more personal and engaging. Apply the same second-person, active-voice approach to the related content at lines 138-139 to ensure consistent documentation style throughout the error-handling section.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api/polls.mdx`:
- Line 407: The documentation in api/polls.mdx claims that all five poll methods
(create, create_quiz, vote, decrypt_vote, and aggregate_votes) return PollError,
but api/errors.mdx only documents PollError as being returned by the first three
methods (create, create_quiz, vote). Update api/errors.mdx to include
decrypt_vote and aggregate_votes in the methods that return PollError, or
alternatively update api/polls.mdx to clarify which specific methods return
PollError and what error types the other methods return. Ensure both
documentation files consistently represent the actual public API contract.
- Line 407: The sentence starting with "All poll methods" at line 407 uses
third-person voice instead of addressing the reader directly. Reword this
sentence to use second-person voice by restructuring it to tell the reader what
they can expect when they use these methods. Instead of stating what "all poll
methods return," reframe it to explain to the reader (using "you") what return
type they will receive when they call these methods like create, create_quiz,
vote, decrypt_vote, and aggregate_votes.
In `@api/profile.mdx`:
- Around line 153-165: The ProfileError enum is missing the required derive
macros needed for the thiserror attributes to compile. Add #[derive(Debug,
thiserror::Error)] above the #[non_exhaustive] attribute on the ProfileError
enum definition to make the code snippet complete and compilable for users who
copy it.
---
Nitpick comments:
In `@api/status.mdx`:
- Around line 216-217: The documentation at the status update reaction section
uses passive voice ("Status reactions are sent via") which conflicts with the
active voice style guidelines. Rewrite this sentence to use active voice and
second person perspective, making it clear that the reader should use
Client::send_reaction method with the specified parameters (status@broadcast as
the chat JID and a wa::MessageKey with participant field).
In `@api/tctoken.mdx`:
- Line 125: Rewrite the error-handling documentation in the tctoken.mdx file to
use second-person wording that addresses the reader directly. The line stating
"All methods return `Result<T, TcTokenError>`:" should be changed to active
voice using "you" to make it more personal and engaging. Apply the same
second-person, active-voice approach to the related content at lines 138-139 to
ensure consistent documentation style throughout the error-handling section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: ca9a0e68-b7f8-49a4-b506-e480f7eaa8a1
📒 Files selected for processing (19)
api/blocking.mdxapi/chat-actions.mdxapi/chatstate.mdxapi/client.mdxapi/community.mdxapi/contacts.mdxapi/errors.mdxapi/groups.mdxapi/labels.mdxapi/media-reupload.mdxapi/newsletter.mdxapi/polls.mdxapi/presence.mdxapi/profile.mdxapi/send.mdxapi/signal.mdxapi/status.mdxapi/tctoken.mdxguides/sending-messages.mdx
✅ Files skipped from review due to trivial changes (2)
- guides/sending-messages.mdx
- api/errors.mdx
🚧 Files skipped from review as they are similar to previous changes (6)
- api/chatstate.mdx
- api/presence.mdx
- api/send.mdx
- api/blocking.mdx
- api/newsletter.mdx
- api/signal.mdx
- profile.mdx: add #[derive(Debug, thiserror::Error)] to ProfileError snippet so it compiles if copied directly - polls.mdx: rephrase error-handling intro for clarity - status.mdx: change passive to active voice in send_reaction description - tctoken.mdx: use active voice in error-handling section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 242fda6552
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| }; | ||
|
|
||
| // React to a status | ||
| client.send_reaction("status@broadcast", target_key.clone(), "💚").await?; |
There was a problem hiding this comment.
For callers copying this status-reaction example, the first argument does not satisfy the chat: impl Into<Jid> signature shown above: Jid parsing is fallible, so a string literal like "status@broadcast" is not an Into<Jid> value. This will fail to compile for both the react and remove calls; pass Jid::status_broadcast() or parse the string into a Jid first.
Useful? React with 👍 / 👎.
A string literal does not implement Into<Jid> since JID parsing is fallible. Replace the "status@broadcast" literal with Jid::status_broadcast() which is the correct infallible constructor for the broadcast JID. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PKWngYsD1xLRk76TobcyiD
2 participants
Summary
Reflects the breaking API change from whatsapp-rust#893, which replaced
anyhow::Errorand mixed error families with one typed error per feature domain.api/errors.mdx— central reference with the full error hierarchy, all 15 domain type definitions (SendError,GroupError,BlockingError,AppStateError,ChatStateError,CommunityError,ContactError,NewsletterError,PollError,ProfileError,SignalError,TcTokenError,MediaReuploadError,PresenceError), and a migration guide for callers moving fromanyhow::Errorsend,groups,blocking,chat-actions,labels,chatstate,community,contacts,newsletter,polls,profile,presence,signal,media-reupload,bot) — method signatures and error handling sections updated to the new return typesguides/sending-messages.mdx— error handling example now usesSendErrordocs.json—api/errorsadded to the Core navigation groupBreaking changes documented
Errvariant changed; callers using?intoanyhoware unaffectedIqError::ClientStateis nowBox<ClientError>— pattern matching needs dereferencingPresenceErrorgains aClientvariant coveringsubscribe/unsubscribeerrorsGenerated by Claude Code
Summary by cubic
Docs updated to use per-domain typed errors across
whatsapp_rust, added a central Error Types reference, and documented status reactions via theClientAPI. Low-level APIs likeClient::connectand media upload/download are not covered.New Features
api/errors.mdxwith the hierarchy, base types, and a short migration guide; includes all domain errors and lists all poll methods (create,create_quiz,vote,decrypt_vote,aggregate_votes).docs.jsonlinksapi/errorsunder Core.tctoken: all methods returnTcTokenErrorwithIqandStorevariants; added usage example.Bug Fixes
ClientErroraddsSocket/EncryptSend;IqErrorswitches toParseErrorand addsSocket,UnexpectedResponseType,InternalChannelClosed;ContactErrorusesInvalidJid;CommunityErrorembedsGroupError.Client(send_reaction(chat, wa::MessageKey, emoji) -> Result<SendResult, SendError>), withstatus@broadcastandparticipantset to the status owner; example now usesJid::status_broadcast().subscribe/unsubscribereturnPresenceError(includesClient), blocking mapping failures returnBlockingError::InvalidJid, newsletter usesmetadata.jid, polls example usescreate(&options, 1)and the error table includesdecrypt_vote/aggregate_votes, media-reupload error variants/order corrected, chat-actions/labels returnResult<(), AppStateError>, client send/edit/revoke returnSendError.#[derive(Debug, thiserror::Error)]to theProfileErrorsnippet; clarifiedsend_reactiondetails and tightened copy inpolls,status, andtctoken.Written for commit fee3654. Summary will update on new commits.
Summary by CodeRabbit
Release Notes
Documentation
Breaking Changes
Result<_, <Domain>Error>instead of generic/untyped errors (e.g.,SendError,GroupError,BlockingError,ChatStateError,CommunityError,ContactError, etc.).