docs(pair-code): document companion_platform_display OS canonicalization

[jlucaso1]

Summary

Documents the behavior/API changes from whatsapp-rust#979 ("fix(pair-code): canonicalize companion_platform_display OS to a server-safe set"), which fixed the pair-code companion_hello server rejecting a non-OS companion_platform_display with bad-request.

Changes

concepts/authentication.mdx

• PairCodeOptions struct reference: added the new display_os: Option<String> field, and corrected the platform_id doc comment (the display is no longer always non-overridable).
• companion_platform_display section: replaced the "empty OS substitutes Linux, no browser whitelist" description with the new CompanionOs canonicalization behavior — a classification table (Windows/Mac OS/Linux/Android/iOS and their recognized aliases), the branding→Linux fallback, the one-time coercion warning, and the display_os escape hatch for advanced callers who need a real but non-canonical OS name (e.g. "Ubuntu") to ride through verbatim.
• Pair code errors section: added a note that PairError::RequestFailed carrying bad-request (400) can indicate server-side rate-limiting rather than a permanent validation failure, and that the backoff hint on IqError::ServerError is preserved.

api/bot.mdx

• with_pair_code example: added ..Default::default() to the PairCodeOptions struct literal (needed to keep compiling now that the struct has a new field).
• with_pair_code Tip: updated to describe the OS canonicalization and point at PairCodeOptions::display_os and the new classification table in concepts/authentication.mdx.

No changelog changes included, per instructions.

Test plan

• Docs site build/preview renders both pages correctly (Mintlify)
• Cross-links (/concepts/authentication#companion-platform-display, /api/errors#iqerror-base-type) resolve

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Summary by cubic

Documents OS canonicalization for pair-code companion_platform_display, adds the PairCodeOptions::display_os override, and restores the front-matter delimiter so Mintlify parses page metadata. Updates the with_pair_code example with ..Default::default() and clarifies that bad-request (400) may be rate limiting by default (unless display_os bypasses canonicalization), preserving any server backoff hint.

^{Written for commit 25f03f2. 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 4, 2026, 6:30 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: 54 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: 65813935-6d40-4363-aa02-bf1fc0597ed0

📥 Commits

Reviewing files that changed from the base of the PR and between 2b6f858 and 25f03f2.

📒 Files selected for processing (2)

• api/bot.mdx
• concepts/authentication.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.}

[greptile-apps]

Greptile Summary

Documents the OS canonicalization behavior introduced in whatsapp-rust#979 — covering the new PairCodeOptions::display_os escape hatch, the CompanionOs classification table, and the bad-request/rate-limiting Note for the pair-code error section.

• concepts/authentication.mdx replaces the old "empty OS → Linux" sentence with a Warning callout explaining server rejection, a full canonicalization table, and a documented escape hatch via display_os.
• api/bot.mdx adds ..Default::default() to the struct literal example (required now that display_os is a new field) and updates the <Tip> to summarize the canonicalization and point to the full table.

Confidence Score: 5/5

Documentation-only changes that accurately reflect the upstream library behavior; no code is modified.

Both files carry correct front matter, all internal links use root-relative paths and map to real anchors, the canonicalization table is self-consistent with the escape-hatch prose, and the struct example compiles cleanly with ..Default::default(). There are no factual inaccuracies or broken references introduced by this PR.

No files require special attention.

Important Files Changed

Filename	Overview
concepts/authentication.mdx	Adds display_os field to the PairCodeOptions struct docs, replaces the old "empty OS → Linux" description with a full CompanionOs canonicalization table and Warning callout, and adds a Note about bad-request rate-limiting. All content is internally consistent and technically accurate.
api/bot.mdx	Adds ..Default::default() to the PairCodeOptions struct literal to account for the new display_os field, and expands the Tip to describe OS canonicalization and the escape hatch. The Tip has grown dense but content is accurate.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App as App Code
    participant Lib as whatsapp-rust
    participant OS as CompanionOs::from_hint
    participant WA as WhatsApp Server

    App->>Lib: "pair_with_code(PairCodeOptions { display_os: None, ... })"
    Lib->>OS: classify(DeviceProps::os)
    alt recognized OS string
        OS-->>Lib: Windows / Mac OS / Linux / Android / iOS
    else unrecognized / branding string
        OS-->>Lib: Linux (fallback + warn! logged)
    end
    Lib->>WA: "companion_hello { companion_platform_display: Chrome (Linux) }"
    WA-->>Lib: OK (paired)

    Note over App,WA: Escape hatch: display_os = Some(Ubuntu)

    App->>Lib: "pair_with_code(PairCodeOptions { display_os: Some(Ubuntu), ... })"
    Lib->>WA: "companion_hello { companion_platform_display: Chrome (Ubuntu) }"
    alt server accepts the OS string
        WA-->>Lib: OK (paired)
    else non-OS string rejected
        WA-->>Lib: bad-request (400)
        Lib-->>App: PairError::RequestFailed
    end

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 App as App Code
    participant Lib as whatsapp-rust
    participant OS as CompanionOs::from_hint
    participant WA as WhatsApp Server

    App->>Lib: "pair_with_code(PairCodeOptions { display_os: None, ... })"
    Lib->>OS: classify(DeviceProps::os)
    alt recognized OS string
        OS-->>Lib: Windows / Mac OS / Linux / Android / iOS
    else unrecognized / branding string
        OS-->>Lib: Linux (fallback + warn! logged)
    end
    Lib->>WA: "companion_hello { companion_platform_display: Chrome (Linux) }"
    WA-->>Lib: OK (paired)

    Note over App,WA: Escape hatch: display_os = Some(Ubuntu)

    App->>Lib: "pair_with_code(PairCodeOptions { display_os: Some(Ubuntu), ... })"
    Lib->>WA: "companion_hello { companion_platform_display: Chrome (Ubuntu) }"
    alt server accepts the OS string
        WA-->>Lib: OK (paired)
    else non-OS string rejected
        WA-->>Lib: bad-request (400)
        Lib-->>App: PairError::RequestFailed
    end

Loading

_{Reviews (2): Last reviewed commit: "fix(docs): restore front matter delimite..." | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 4/5

• In concepts/authentication.mdx, the new pair-code error note appears to overstate that display-related bad-request is already eliminated by library canonicalization, which may be inaccurate now that PairCodeOptions... is introduced; merging as-is could mislead integrators about when this error can still occur and cause incorrect client-side handling—tighten the wording to reflect conditional behavior (or document the exact preconditions) before merging.

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Auto-approved: Pure documentation and comment update: adds docstrings, clarifies server behavior for companion_platform_display OS canonicalization, and updates an example with Default::default(). No production logic, configuration, or infrastructure changes.

Re-trigger cubic</sub>