docs(events): document ServerAck event and pre-1.0 payload stability

[jlucaso1]

What

Documents the Event::ServerAck variant, which was never covered in these docs, and the pre-1.0 event payload stability policy.

Why

Follow-up to oxidezap/whatsapp-rust#1000, which changed ServerAck.class from String to Option<String> and added a stability note to the Event enum doc in wacore/src/types/events.rs. The ServerAck event itself was introduced earlier in #989 but was never added to concepts/events.mdx, so consumers had no reference for it at all. This documents it using the final (post-#1000) shape.

Changes

• concepts/events.mdx:
  • Added ServerAck(ServerAck) to the Event enum listing (Messages group).
  • Added a ### ServerAck section under Message Events describing the struct fields (id, class: Option<String>, from, timestamp, error), when it's dispatched, and the allocation-free dispatch-gating behavior, with a usage example.
  • Added a <Note> next to the existing #[non_exhaustive] note documenting the pre-1.0 payload stability convention: fields may be added in minor releases, a maybe-absent field is always Option<T> (never a sentinel), and payload sealing is deferred to the 1.0 API freeze.

No changelog entry added, per instructions that changelog entries are human-authored.

---

Generated by Claude Code

---

Summary by cubic

Documents Event::ServerAck and the pre-1.0 payload stability policy. Also clarifies that the timestamp note references the Go whatsmeow project.

• New Features
  • Documented ServerAck: added to the Event enum, described fields (id, class: Option<String>, from, timestamp, error), when it emits, a short example, and that dispatch is gated to avoid allocations when no handler is registered.
  • Clarified pre-1.0 payload stability: payloads may add fields in minor releases; maybe-absent data is always Option<T>; prefer reading needed fields or .. destructuring. Clarified the timestamp cross-reference to the Go whatsmeow project.

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
whatsapp-rust	🟢 Ready	View Preview	Jul 7, 2026, 3:50 PM

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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@jlucaso1, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 58 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1db7a199-bb38-4fa1-8d8a-91ae70c3ceab

📥 Commits

Reviewing files that changed from the base of the PR and between 1c399a7 and f023b29.

📒 Files selected for processing (1)

• concepts/events.mdx

---

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.}

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Auto-approved: Documentation-only: adds docs for ServerAck event and pre-1.0 payload stability policy.

Re-trigger cubic</sub>

[greptile-apps]

Greptile Summary

This PR fills a documentation gap by adding the ServerAck event to concepts/events.mdx, including its struct definition, field descriptions, dispatch semantics, a usage example, and a pre-1.0 payload stability note. The changes are purely additive to the docs and accurately reflect the post-PR#1000 struct shape where class is Option<String>.

Confidence Score: 5/5

Documentation-only PR; no executable code is changed, so there is no risk of runtime regression.

The single changed file adds descriptive text and a code snippet to existing docs. The struct definition, field descriptions, and example code all match the post-PR#1000 shape (class: Option). The pre-1.0 stability note is accurate and helpful. No logic paths, APIs, or schemas are modified.

No files require special attention.

Important Files Changed

Filename	Overview
concepts/events.mdx	Documents ServerAck event (struct fields, dispatch semantics, example) and adds a pre-1.0 payload stability note; changes are additive and accurate

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Server as WhatsApp Server
    participant Client as whatsapp-rust Client
    participant EventBus as Event Dispatcher
    participant Handler as User Handler

    Server->>Client: "<ack> stanza (id, class, t, error?)"
    Client->>Client: Parse stanza → ServerAck struct
    Client->>EventBus: Check: is ServerAck handler registered?
    alt Handler registered
        EventBus->>Handler: "Event::ServerAck(ServerAck { id, class, from, timestamp, error })"
        Handler->>Handler: Filter on class, inspect error
    else No handler
        EventBus-->>Client: No-op (zero allocation)
    end
    Client->>Client: Resolve internal send-waiter (independent path)

Loading

%%{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"}}}%%
sequenceDiagram
    participant Server as WhatsApp Server
    participant Client as whatsapp-rust Client
    participant EventBus as Event Dispatcher
    participant Handler as User Handler

    Server->>Client: "<ack> stanza (id, class, t, error?)"
    Client->>Client: Parse stanza → ServerAck struct
    Client->>EventBus: Check: is ServerAck handler registered?
    alt Handler registered
        EventBus->>Handler: "Event::ServerAck(ServerAck { id, class, from, timestamp, error })"
        Handler->>Handler: Filter on class, inspect error
    else No handler
        EventBus-->>Client: No-op (zero allocation)
    end
    Client->>Client: Resolve internal send-waiter (independent path)

Loading

_{Reviews (2): Last reviewed commit: "docs(events): clarify whatsmeow cross-re..." | Re-trigger Greptile}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Auto-approved: Documentation-only change adding ServerAck event docs and stability policy. No code, config, or logic changes; low risk.

Re-trigger cubic</sub>