docs: add USync typed query engine reference - #420
Conversation
…ng newline) References oxidezap/whatsapp-rust#1063
📝 WalkthroughWalkthroughThe documentation adds the typed ChangesUSync API
Estimated code review effort: 2 (Simple) | ~10 minutes 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 |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
| Filename | Overview |
|---|---|
| api/usync.mdx | Adds the typed USync reference and corrects the specialized device lookup reference. |
| api/client.mdx | Documents the direct Client::query_usync feature API. |
| api/store.mdx | Documents hosted device metadata, constructors, and migration effects. |
| concepts/storage.mdx | Updates the storage model and persistence guidance for hosted devices. |
| api/wacore.mdx | Expands the USync module description and links its reference. |
| docs.json | Adds the USync reference to API navigation. |
Reviews (6): Last reviewed commit: "docs: fix incorrect SignalManager refere..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@api/usync.mdx`:
- Around line 35-44: Format Rust API identifiers as inline code in both
documentation sites: in api/usync.mdx lines 35-44, wrap UsyncMode and
UsyncContext in backticks and apply the same treatment to analogous headings on
that page; in api/client.mdx line 881, change the heading to use inline code for
query_usync.
🪄 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: 1e37e154-7b6d-441c-a478-9c1d74939020
📒 Files selected for processing (5)
api/client.mdxapi/store.mdxapi/usync.mdxapi/wacore.mdxdocs.json
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Addresses CodeRabbit nitpick on #420
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
Addresses CodeRabbit nitpick on #420
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
Previous commit dropped the file's final newline during transcription.
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
![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: e4db7c31e7
ℹ️ 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".
| The `raw_id` field stores the ADV (Account Device Verification) key index list `raw_id` from device notifications. When this value changes for a user, it indicates an identity change (e.g., the user reinstalled WhatsApp). The client uses this to detect identity changes and clear Signal sessions for that user's non-primary devices. Per-device sender key tracking is **not** wiped globally on identity change — that would empty the tracker too aggressively and feed the no-distribution path on the next group send. SKDM redistribution is instead driven per-group/per-device by retry receipts (matching WhatsApp Web's `WAWebUpdateLocalSignalSession`/`markForgetSenderKey` behavior). | ||
|
|
||
| <Note> | ||
| **Breaking change:** `DeviceInfo` gained the `is_hosted` field (marks whether the device belongs to WhatsApp's hosted PN/LID address space, populated from usync device-list results). Struct-literal construction (`DeviceInfo { device_id, key_index }`) no longer compiles — use `DeviceInfo::new(device_id, key_index).with_hosting(is_hosted)` instead. Persisted JSON without `is_hosted` still deserializes correctly (it defaults to `false`); only Rust struct-literal call sites are affected. See [USync](/api/usync#hosted-addressing) for how `is_hosted` is used with `Jid::with_device_hosting`. |
There was a problem hiding this comment.
This breaking-change documentation leaves concepts/storage.mdx:550-554 showing the obsolete two-field DeviceInfo definition. Readers implementing the documented device registry from that page can copy a struct literal that no longer compiles because is_hosted is required. Update that reference with the new field and constructor guidance as well.
Useful? React with 👍 / 👎.
| DeviceInfo::new(device_id, key_index).with_hosting(is_hosted) | ||
| UsyncDevice::new(device, key_index).with_hosting(is_hosted) | ||
| ``` | ||
| Persisted `DeviceInfo` JSON without `is_hosted` still deserializes correctly (`is_hosted` defaults to `false`) — this only affects Rust struct-literal call sites, not on-disk data. |
There was a problem hiding this comment.
When downstream code exhaustively destructures DeviceInfo, such as let DeviceInfo { device_id, key_index } = info, adding is_hosted also causes a compile error. The claim that this “only affects Rust struct-literal call sites” therefore understates the breaking change and leaves those users without applicable migration guidance; describe construction and exhaustive pattern matching as affected.
Useful? React with 👍 / 👎.
| ) -> Result<Self, UsyncValidationError> | ||
| ``` | ||
|
|
||
| `UsyncQuery::new` validates the whole query before it reaches the network — non-empty protocols/users, no duplicate protocol kinds, and per-user field consistency (e.g. a `tc_token` requires the `Status` protocol to be selected; `device_sync` requires `DevicesV2`). Deserializing a `UsyncQuery` from an external source runs the same validation, so a serialized input can't bypass it. |
There was a problem hiding this comment.
This paragraph combines the constructor's validation categories, two protocol-dependency examples, and the deserialization guarantee into two dense sentences. Split these ideas into concise sentences so readers can distinguish the checks and the separate serde behavior, as required by the project's documentation style.
AGENTS.md reference: AGENTS.md:L24-L25
Useful? React with 👍 / 👎.
Addresses Codex review comments on #420
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
Addresses Codex review comment on #420
Addresses Codex review comment on #420
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5035103d5b
ℹ️ 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".
| `Client::query_usync` exposes the same typed query engine directly, for protocol combinations the specialized helpers don't cover — for example fetching a bot's profile, resolving a username, or reading `disappearing_mode`/`text_status` in the same request as a device-list lookup. | ||
|
|
||
| <Note> | ||
| Prefer the specialized helpers ([`Contacts`](/api/contacts), [`SignalManager::get_user_devices`](/api/signal#get_user_devices)) for common lookups — they also handle cache population and persistence. `query_usync` is a neutral operation: it only returns decoded wire data. |
There was a problem hiding this comment.
The linked API exposes get_user_devices on the Signal struct returned by client.signal(), not on a SignalManager type. Readers searching for or importing SignalManager will find no such public API, so refer to Signal::get_user_devices or client.signal().get_user_devices(...) here.
Useful? React with 👍 / 👎.
Addresses Codex review comment on #420
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
1 participant
Summary
Documents the typed USync query engine added in oxidezap/whatsapp-rust#1063 ("feat(core): add typed USync query engine").
api/usync.mdx— full reference forClient::query_usync, theUsyncQuery/UsyncUser/UsyncProtocolbuilders, theUsyncResponse/UsyncOutcome<T>/UsyncProtocolResultresponse model (including bot profile, username, text status, disappearing mode, and feature-flag subprotocols), the phone-number canonicalization behavior, theUsyncValidationErrorvariants, and hosted PN/LID addressing viaJid::with_device_hosting.api/client.mdx— added aquery_usyncentry under Feature APIs, alongside the existingsignal()/contacts()accessors, pointing to the new page.api/store.mdx— documented the newis_hostedfield andDeviceInfo::new/with_hostingconstructors, and called out the breaking change (struct-literalDeviceInfoconstruction no longer compiles; persisted JSON is unaffected).api/wacore.mdx— expanded theusyncmodule bullet to mention the typed model and link to the new page.docs.json— addedapi/usyncto the API Reference → Features navigation group.Breaking changes covered
DeviceInfo(wacore::store::traits) andUsyncDevice(wacore::usync) both gained anis_hosted: boolfield — struct-literal construction no longer compiles; use the new::new()/with_hosting()constructors. Persisted JSON deserializes unaffected (is_hosteddefaults tofalse).UsyncMode::DeltaandUsyncContext::Voipare new enum variants on non-#[non_exhaustive]enums — an exhaustivematchover either will fail to compile until the new arms are handled.Out of scope
No
changelog/entries were added or modified per standing instructions (changelog is human-maintained).Generated by Claude Code
Summary by cubic
Adds a USync typed query engine reference and links it across the docs so developers can call
Client::query_usyncdirectly. Also documents hosted device addressing, clarifiesDeviceInfodestructuring impact and new enum variants, and fixes a mistakenSignalManagerreference toSignalon the USync page.New Features
api/usync.mdx: reference forClient::query_usync,UsyncQuery/UsyncUser/UsyncProtocol, response types, subprotocols (bot profile, username, text status, disappearing mode, features), phone canonicalization, validation errors, and hosted PN/LID addressing viaJid::with_device_hosting.api/client.mdx(addsquery_usync),api/wacore.mdx(typed model blurb + link), anddocs.json(navigation).api/store.mdxandconcepts/storage.mdx: documentDeviceInfo::new/with_hosting, the newis_hostedfield, and the destructuring/pattern-matching impact.Migration
DeviceInfoandUsyncDeviceconstruction: use::new(...).with_hosting(...)instead of struct literals; persisted JSON remains compatible (is_hosteddefaults tofalse).DeviceInfo: include..or matchis_hostedas well.UsyncMode::DeltaandUsyncContext::Voip.Written for commit 0962dab. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation