docs: document typed stanza ack/reject/retry API

[jlucaso1]

Summary

Documents the public API added in oxidezap/whatsapp-rust#1069 ("feat(core): expose typed stanza responses and retries").

• advanced/binary-protocol.mdx — new "Manual stanza acknowledgement" section documenting Client::acknowledge_stanza and Client::reject_stanza, plus the StanzaRejection / StanzaResponseError types, for callers that intercept raw stanzas themselves (custom transports, replay tooling, mock servers).
• guides/receiving-messages.mdx — new "Requesting a retry manually" subsection documenting Client::request_message_retry and the RetryRequestOptions / RetryRequestOutcome / RetryRequestError types, plus a note on the retry key-bundle inclusion policy (retry_count >= 2, explicit force_include_keys, or a stateless/hosted destination — the diagnostic RetryReason no longer affects wire shape).
• concepts/architecture.mdx — one-line addition noting that malformed <message> stanzas now receive an explicit <ack error="487"> (NackReason::ParsingError) instead of being silently dropped, and that parse_message_info is now fail-fast on invalid/missing id/from/participant.

No changelog entry included, per standing instructions that changelog entries are added by a human.

Test plan

• Cross-checked every documented method signature, type, and behavior against the PR's actual diff in the whatsapp-rust repo (not just its description).
• Mintlify build/link-check (no local mint tooling available in this session).

🤖 Generated with Claude Code

https://claude.ai/code/session_01ExpD4zYrxBMPK5TYuH7qML

---

Generated by Claude Code

---

Summary by cubic

Adds docs for manual stanza ack/nack and manual retry APIs so custom transports and replay tools can respond to stanzas directly. Clarifies retry key-bundle inclusion, the group/status participant requirement for manual retries, and that malformed messages now get an explicit nack.

• New Features
  • Added "Manual stanza acknowledgement": Client::acknowledge_stanza, Client::reject_stanza, StanzaRejection, StanzaResponseError.
  • Added "Requesting a retry manually": Client::request_message_retry, RetryRequestOptions, RetryRequestOutcome, RetryRequestError; documents key-bundle inclusion rules, that transport acks remain caller-owned, and that group/status paths require a valid participant or return RetryRequestError::InvalidStanza.
  • Architecture note: malformed <message> stanzas are nacked with error 487; parse_message_info is fail-fast; RetryReason no longer changes wire shape for retries.

^{Written for commit 7f758ff. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Added guidance for manually acknowledging or rejecting intercepted stanzas, including available response types and error handling.
  • Clarified automatic handling of malformed message stanzas and parsing failures.
  • Documented manual message-decryption retry requests, retry options, outcomes, and exported retry reasons.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation adds manual stanza acknowledgement and rejection APIs, clarifies parsing-error acknowledgements for malformed messages, and documents exported retry reasons plus caller-controlled message retry requests.

Changes

Protocol response and retry documentation

Layer / File(s)	Summary
Manual stanza responses advanced/binary-protocol.mdx, concepts/architecture.mdx	Documents explicit stanza acknowledgement/rejection APIs, typed response errors, and immediate parsing-error acknowledgements for malformed message stanzas.
Manual message retries guides/receiving-messages.mdx	Documents exported RetryReason values and Client::request_message_retry, including validation, options, outcomes, and key-material rules.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: greptile-apps, cubic-dev-ai

Poem

I’m a rabbit with docs in my paws,
Acking each stanza by protocol laws.
Retry paths now sparkle and shine,
With reasons and outcomes aligned.
Hop through the guide—everything’s clear!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main documentation change: typed stanza acknowledge, reject, and retry APIs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
whatsapp-rust	🟢 Ready	View Preview	Jul 22, 2026, 1:42 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1e0fb952b3

ℹ️ 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".

[greptile-apps]

Greptile Summary

This PR documents the typed stanza response and retry APIs. The main changes are:

• Manual acknowledgement and rejection methods, validation rules, and error types.
• Manual retry options, outcomes, counter behavior, and key-bundle policy.
• Explicit parsing-error nacks for malformed message stanzas.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed documentation.
• The new sections are internally consistent and their cross-links target matching headings.

Important Files Changed

Filename	Overview
advanced/binary-protocol.mdx	Adds manual stanza acknowledgement and rejection API documentation with consistent cross-links.
concepts/architecture.mdx	Documents explicit parsing-error nacks and fail-fast message metadata parsing.
guides/receiving-messages.mdx	Adds manual retry API documentation, outcome semantics, and key-inclusion rules.

_{Reviews (1): Last reviewed commit: "docs: document conditional participant r..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@advanced/binary-protocol.mdx`:
- Around line 976-1006: Revise the documentation at advanced/binary-protocol.mdx
lines 976-1006, concepts/architecture.mdx line 456, and
guides/receiving-messages.mdx lines 449-476 to consistently address readers as
“you,” use active voice, and keep one idea per sentence. In binary-protocol.mdx
and receiving-messages.mdx, split dense API, validation, and outcome rules into
shorter sentences; in architecture.mdx, separate parsing behavior from
acknowledgement behavior. Preserve all existing technical details and behavior.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 72a03f4d-b1c6-4e6c-a9cf-3ae4cd909163

📥 Commits

Reviewing files that changed from the base of the PR and between cea3a00 and 7f758ff.

📒 Files selected for processing (3)

• advanced/binary-protocol.mdx
• concepts/architecture.mdx
• guides/receiving-messages.mdx