docs: update event examples for the event-payload API freeze (whatsapp-rust#1004) - #399
Conversation
Reflects PR #1004 in oxidezap/whatsapp-rust, "refactor(events): complete the event-payload API freeze": event payload structs are now #[non_exhaustive] with bon::Builder construction, and PairingQrCode, PairingCode, and PairingCodeRefresh moved from inline enum-variant fields to newtype-wrapped structs.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughDocumentation across the site is updated to reflect that event payload structs (Connected, Disconnected, InboundMessage, Receipt, PairingQrCode, PairingCode, and others) are now ChangesEvent payload non-exhaustive documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
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 |
|
| Filename | Overview |
|---|---|
| concepts/events.mdx | Primary event reference updated comprehensively: enum listing rewritten for newtype pairing variants, all affected struct definitions gain derive + non_exhaustive, capacity/interest widening noted, and all InboundMessage destructuring patterns updated with .. rest. |
| concepts/authentication.mdx | QR/pair-code/pair-code-refresh sections fully rewritten for newtype shapes; PairSuccess/PairError/LoggedOut construction examples updated to builder syntax; PairPasskey structs noted as non_exhaustive; Best Practices event-handling snippet updated consistently. |
| api/receipt.mdx | Receipt struct shown as #[non_exhaustive] only — the #[derive(Debug, Clone, Serialize, bon::Builder)] line present in concepts/events.mdx for the same struct was not added here, leaving the definition inconsistent between the two pages. |
| api/bot.mdx | Three pattern sites updated: InboundMessage .. rest (two locations) and PairingCode/PairingQrCode newtype destructuring; imports extended to include the new struct types. |
| guides/receiving-messages.mdx | Five InboundMessage destructuring sites updated; PairingQrCode enum-variant updated in the illustrative Event enum listing; all changes accurate. |
| advanced/inbound-durability.mdx | InboundMessage struct definition gains derive + non_exhaustive annotation; single mechanical change, correct. |
| pt/quickstart.mdx | Portuguese quickstart updated: PairingQrCode/PairingCode newtype patterns and InboundMessage .. rest applied consistently across all four code snippets; PairingCode import correctly added to the pair-code section. |
| api/client.mdx | Single InboundMessage destructuring pattern updated with .. rest; change is minimal and correct. |
| guides/communities.mdx | Single InboundMessage destructuring updated with .. rest; mechanical and correct. |
| guides/media-handling.mdx | Single InboundMessage destructuring updated with .. rest; mechanical and correct. |
| guides/sending-messages.mdx | Single InboundMessage destructuring updated with .. rest; mechanical and correct. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Event dispatched] --> B{Event variant}
B --> C["Event::Messages(MessageBatch)"]
B --> D["Event::PairingQrCode(PairingQrCode)"]
B --> E["Event::PairingCode(PairingCode)"]
B --> F["Event::PairingCodeRefresh(PairingCodeRefresh)"]
B --> G["Event::Connected(Connected {})"]
B --> H["Event::Disconnected(Disconnected)"]
B --> I["Event::Receipt(Receipt)"]
B --> J[Other sealed structs ...]
C --> C1["for InboundMessage { message, info, .. } in batch.iter()"]
D --> D1["PairingQrCode { code, timeout, .. }"]
E --> E1["PairingCode { code, timeout, .. }"]
F --> F1["PairingCodeRefresh { force_manual, .. }"]
G --> G1["Connected::builder().build()"]
H --> H1["Disconnected::builder().reason(r).build()"]
I --> I1["Receipt { source, r#type, .. } — needs .."]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[Event dispatched] --> B{Event variant}
B --> C["Event::Messages(MessageBatch)"]
B --> D["Event::PairingQrCode(PairingQrCode)"]
B --> E["Event::PairingCode(PairingCode)"]
B --> F["Event::PairingCodeRefresh(PairingCodeRefresh)"]
B --> G["Event::Connected(Connected {})"]
B --> H["Event::Disconnected(Disconnected)"]
B --> I["Event::Receipt(Receipt)"]
B --> J[Other sealed structs ...]
C --> C1["for InboundMessage { message, info, .. } in batch.iter()"]
D --> D1["PairingQrCode { code, timeout, .. }"]
E --> E1["PairingCode { code, timeout, .. }"]
F --> F1["PairingCodeRefresh { force_manual, .. }"]
G --> G1["Connected::builder().build()"]
H --> H1["Disconnected::builder().reason(r).build()"]
I --> I1["Receipt { source, r#type, .. } — needs .."]
Reviews (2): Last reviewed commit: "docs: add bon::Builder derive to Inbound..." | Re-trigger Greptile
…(follow-up to #1004 event freeze)
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
advanced/inbound-durability.mdx (1)
107-112: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAlso show the
bon::Builderderive forInboundMessage.
#[non_exhaustive]is added without the derive line.concepts/events.mdxdocumentsInboundMessageas#[derive(Debug, Clone, Serialize, bon::Builder)]with#[non_exhaustive], so include the derive here for consistency and to signal that external construction goes through the builder.📝 Proposed alignment
+#[derive(Debug, Clone, Serialize, bon::Builder)] #[non_exhaustive] pub struct InboundMessage { pub message: Arc<wa::Message>, pub info: Arc<MessageInfo>, }🤖 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 `@advanced/inbound-durability.mdx` around lines 107 - 112, The InboundMessage definition is missing the bon::Builder derive, so update the struct declaration to match the documented shape used elsewhere. In the InboundMessage block, add the derive list alongside the existing non_exhaustive attribute so it includes bon::Builder (and the other documented traits if present), matching the InboundMessage symbol referenced in concepts/events.mdx. This keeps external construction aligned with the builder pattern and consistent across the docs.
🤖 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.
Outside diff comments:
In `@advanced/inbound-durability.mdx`:
- Around line 107-112: The InboundMessage definition is missing the bon::Builder
derive, so update the struct declaration to match the documented shape used
elsewhere. In the InboundMessage block, add the derive list alongside the
existing non_exhaustive attribute so it includes bon::Builder (and the other
documented traits if present), matching the InboundMessage symbol referenced in
concepts/events.mdx. This keeps external construction aligned with the builder
pattern and consistent across the docs.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 4dc84024-7dce-46d1-b051-cc552b0e1288
📒 Files selected for processing (10)
advanced/inbound-durability.mdxapi/bot.mdxapi/client.mdxapi/receipt.mdxconcepts/authentication.mdxconcepts/events.mdxguides/communities.mdxguides/media-handling.mdxguides/sending-messages.mdxpt/quickstart.mdx
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found and verified against the latest diff
Confidence score: 4/5
- In
concepts/authentication.mdx, the updated event-handling snippet uses unqualifiedPairingQrCode,PairingCode, andPairingCodeRefreshtypes, which can fail to compile (or mislead readers) if those names are not already in scope; merging as-is risks a broken docs example and avoidable developer confusion — qualify or import the payload types in the snippet before merging.
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="concepts/authentication.mdx">
<violation number="1" location="concepts/authentication.mdx:100">
P2: The updated best-practices event-handling snippet introduces three unqualified payload type names (`PairingQrCode`, `PairingCode`, `PairingCodeRefresh`) that now must be in scope for the pattern to compile. Before the API freeze, matching on inline enum-variant fields only required `Event` to be imported. Consider adding an `use` line (e.g., `use wacore::types::events::{Event, PairingQrCode, PairingCode, PairingCodeRefresh};`) above the snippet or qualifying the types, so the example remains copy-pasteable for readers.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| .on_event(|event, _client| async move { | ||
| match &*event { | ||
| Event::PairingQrCode { code, timeout } => { | ||
| Event::PairingQrCode(PairingQrCode { code, timeout, .. }) => { |
There was a problem hiding this comment.
P2: The updated best-practices event-handling snippet introduces three unqualified payload type names (PairingQrCode, PairingCode, PairingCodeRefresh) that now must be in scope for the pattern to compile. Before the API freeze, matching on inline enum-variant fields only required Event to be imported. Consider adding an use line (e.g., use wacore::types::events::{Event, PairingQrCode, PairingCode, PairingCodeRefresh};) above the snippet or qualifying the types, so the example remains copy-pasteable for readers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At concepts/authentication.mdx, line 100:
<comment>The updated best-practices event-handling snippet introduces three unqualified payload type names (`PairingQrCode`, `PairingCode`, `PairingCodeRefresh`) that now must be in scope for the pattern to compile. Before the API freeze, matching on inline enum-variant fields only required `Event` to be imported. Consider adding an `use` line (e.g., `use wacore::types::events::{Event, PairingQrCode, PairingCode, PairingCodeRefresh};`) above the snippet or qualifying the types, so the example remains copy-pasteable for readers.</comment>
<file context>
@@ -97,7 +97,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
.on_event(|event, _client| async move {
match &*event {
- Event::PairingQrCode { code, timeout } => {
+ Event::PairingQrCode(PairingQrCode { code, timeout, .. }) => {
println!("Scan this QR code (valid for {}s):", timeout.as_secs());
println!("{}", code);
</file context>
….mdx Addresses CodeRabbit review comment on #399 — the struct shown was missing the derive line shown elsewhere for the same (now-sealed) InboundMessage struct.
There was a problem hiding this comment.
0 issues found across 1 file (changes from recent commits).
Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.
Re-trigger cubic
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
2 participants
What
Updates the docs to reflect
oxidezap/whatsapp-rust#1004— "refactor(events): complete the event-payload API freeze" — which:Receipt,InboundMessage,MessageBatch,UndecryptableMessage,LoggedOut,Disconnected,PairSuccess,PairError, the threePairPasskey*structs,DeviceListUpdate/DeviceNotificationInfo,IdentityChange,BusinessStatusUpdate,DisappearingModeChanged,MexNotification,NewsletterLiveUpdate(+Message/+Reaction),TemporaryBan,ConnectFailure,StreamError,OfflineSyncPreview,OfflineSyncCompleted) with#[non_exhaustive]+ a generatedbonbuilder.Eventenum-variant fields to sealed newtype structs:Event::PairingQrCode { code, timeout }→Event::PairingQrCode(PairingQrCode)(and likewise forPairingCode,PairingCodeRefresh).Connected,ClientOutdated,QrScannedWithoutMultidevice,StreamReplaced) to empty sealed structs built viaX::builder().build().EventInterestfromu64tou128(EventKind::CAPACITY64 → 128).ConnectFailure.messagefromString(empty-string sentinel) toOption<String>.All of these are breaking changes for consumers who pattern-match on the old shapes or construct these payloads directly.
Doc changes
concepts/events.mdx— the primary reference: updated theEventenum listing, the payload-stability note (freeze is now complete, not "rolling out"), every affected struct definition (added#[non_exhaustive]+bon::Builder), the three pairing-event sections (rewritten for the newtype shape), theEventKind/EventInterestcapacity note (64→128), and everyInboundMessage { .. }/Disconnected { .. }destructuring example to add the now-required..rest.concepts/authentication.mdx— QR/pair-code/pair-code-refresh sections rewritten for the newtype shape (struct defs, construction via.builder()…build(), match patterns);PairSuccess/PairError/LoggedOutconstruction examples updated to builder syntax; added breaking-change notes.api/bot.mdx,api/receipt.mdx— updated matching examples and struct sealing notes.guides/receiving-messages.mdx,guides/communities.mdx,guides/sending-messages.mdx,guides/media-handling.mdx,api/client.mdx,advanced/inbound-durability.mdx,pt/quickstart.mdx— mechanical fix: added the..rest toInboundMessage { .. }destructuring patterns (now required since the struct is#[non_exhaustive]).No changes to
changelog/(per project convention, that's maintained by a human).Test plan
concepts/events.mdxandconcepts/authentication.mdxfor formattingGenerated by Claude Code
Summary by cubic
Updates docs to reflect
oxidezap/whatsapp-rust#1004event-payload API freeze. Examples now use sealed#[non_exhaustive]payloads withbonbuilders, newtype-wrapped pairing events, widenedEventInterest(u128),ConnectFailure.message: Option<String>, and add the missingbon::Builderderive to theInboundMessagesnippet inadvanced/inbound-durability.mdx.Event::PairingQrCode(PairingQrCode { code, timeout, .. }),Event::PairingCode(PairingCode { .. }),Event::PairingCodeRefresh(PairingCodeRefresh { .. })...when destructuring sealed structs, e.g.InboundMessage { message, info, .. },Disconnected { reason, .. },Receipt { source, r#type, .. }.Type::builder()…build(); unit markers are empty sealed structs (e.g.,Connected::builder().build()).ConnectFailure.messageasOption<String>(not an empty-string sentinel).EventInterestis now au128mask (capacity 128); public helpers are unchanged.Written for commit e8bb62b. Summary will update on new commits.
Summary by CodeRabbit
.., helping readers avoid breakage when payloads gain new fields.