feat: add inbound username support and USync username protocol

[rsalcara]

Aligns with Baileys upstream PR WhiskeySockets#2480. WhatsApp is rolling out an inbound username field that maps to the user's LID. This change is purely additive — it captures and propagates the new optional field through types, decoders, USync queries, and group/contact events.

Skipped intentionally to preserve InfiniteAPI's LID/PN customization:

• handleGroupNotification in messages-recv.ts (custom LID->PN flow on groups.upsert / participants.map). Username for these specific events still flows via process-message's emitParticipantsUpdate (reads message.key.participantUsername added in decode-wa-message).

Carousel/buttons code (messages.ts, messages-send.ts) untouched.

Summary by CodeRabbit

• New Features
  • Added username field support for contacts for improved identification.
  • Enriched group metadata with owner, subject-owner, and description-owner usernames.
  • Attached participant and remote-JID username metadata to messages for better tracking.
  • Included author/actor username in group-related event payloads for clearer attribution.
  • Improved contact sync to surface WhatsApp-provided usernames.
  • Added a username sync/query protocol and related APIs to enable username parsing.

[github-actions]

Thanks for opening this pull request and contributing to the project!

The next step is for the maintainers to review your changes. If everything looks good, it will be approved and merged into the main branch.

In the meantime, anyone in the community is encouraged to test this pull request and provide feedback.

✅ How to confirm it works

If you’ve tested this PR, please comment below with:

Tested and working ✅

This helps us speed up the review and merge process.

📦 To test this PR locally:

# NPM
npm install @whiskeysockets/baileys@rsalcara/InfiniteAPI#feat/username-inbound-support

# Yarn (v2+)
yarn add @whiskeysockets/baileys@rsalcara/InfiniteAPI#feat/username-inbound-support

# PNPM
pnpm add @whiskeysockets/baileys@rsalcara/InfiniteAPI#feat/username-inbound-support

If you encounter any issues or have feedback, feel free to comment as well.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 22d33659-f7ef-4e45-be42-5a1bbcf5b1ea

📥 Commits

Reviewing files that changed from the base of the PR and between 5351dce and b69ecc0.

📒 Files selected for processing (1)

• src/Socket/messages-recv.ts

---

📝 Walkthrough

Walkthrough

Adds username propagation and storage across the stack: type updates, message decoding and receipt, contact upserts, group metadata extraction, event payloads, and a new USyncUsernameProtocol with USyncUser username support.

Changes

Cohort / File(s)	Summary
Type definitions src/Types/Contact.ts, src/Types/Events.ts, src/Types/GroupMetadata.ts, src/Types/Message.ts	Added optional username-related fields: Contact.username, GroupMetadata.{ownerUsername,subjectOwnerUsername,descOwnerUsername,authorUsername}, event authorUsername?, and WAMessageKey.{remoteJidUsername,participantUsername}.
Socket processing src/Socket/groups.ts, src/Socket/messages-recv.ts	Group metadata extraction now captures owner/subject/description owner usernames and participant usernames; incoming notification keys include participantUsername and are preserved when converting to proto messages.
Message & contact utilities src/Utils/decode-wa-message.ts, src/Utils/process-message.ts, src/Utils/chat-utils.ts, src/Utils/history.ts, src/Utils/sync-action-utils.ts	Decode/processing now attach remoteJidUsername/participantUsername to message keys, propagate authorUsername in group events, and include username on contact upserts and history-derived contacts.
WAUSync protocols & models src/WAUSync/Protocols/USyncUsernameProtocol.ts, src/WAUSync/Protocols/USyncContactProtocol.ts, src/WAUSync/Protocols/index.ts, src/WAUSync/USyncQuery.ts, src/WAUSync/USyncUser.ts	Added USyncUsernameProtocol (query + parser), integrated it into USyncQuery via withUsernameProtocol(), and extended USyncUser with username and usernameKey and fluent setters.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 I nibble at bytes and hop through the code,
Names stitched in sockets along every node.
USync hums softly, contacts wear a name,
Group keys now whisper who sparked the flame.
Hooray—usernames hop into the frame! 🥕✨

🚥 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 clearly and specifically summarizes the main change: adding inbound username support and the USync username protocol implementation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/username-inbound-support

---

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

[Copilot]

Pull request overview

Adds support for WhatsApp’s inbound “username” fields (mapping to LID identity) and introduces a USync query protocol for retrieving usernames, propagating the optional field through decoding, contact/group models, and emitted events.

Changes:

• Extend core types (Contact, WAMessageKey, group/event payloads) to carry optional usernames.
• Decode and propagate inbound username attributes from message stanzas and group metadata.
• Add USyncUsernameProtocol and extend USync user/query builders to support username-based flows.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/WAUSync/USyncUser.ts	Adds username/usernameKey fields + fluent setters for USync user inputs.
src/WAUSync/USyncQuery.ts	Registers USyncUsernameProtocol and exposes withUsernameProtocol().
src/WAUSync/Protocols/index.ts	Re-exports the new username protocol.
src/WAUSync/Protocols/USyncUsernameProtocol.ts	New USync protocol to request/parse username results.
src/WAUSync/Protocols/USyncContactProtocol.ts	Adds username-based contact query encoding (username/pin/lid).
src/Utils/sync-action-utils.ts	Includes username in contacts derived from sync actions.
src/Utils/process-message.ts	Emits authorUsername for group participant/update events.
src/Utils/history.ts	Includes username on contacts produced from history sync conversations.
src/Utils/decode-wa-message.ts	Decodes remoteJidUsername/participantUsername from stanza attrs into WAMessageKey.
src/Utils/chat-utils.ts	Includes username for lidContactAction → contacts.upsert.
src/Types/Message.ts	Extends WAMessageKey with remoteJidUsername/participantUsername.
src/Types/GroupMetadata.ts	Extends group metadata with owner/subject/desc/author username fields.
src/Types/Events.ts	Extends group-related event payloads with optional authorUsername.
src/Types/Contact.ts	Extends Contact with optional username.
src/Socket/messages-recv.ts	Adds participantUsername into notification-derived message keys.
src/Socket/groups.ts	Extracts username fields from group metadata and participants list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5351dce3a5

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