@nerxa/socketon 0.0.0-stage → 1.21.0

package/EXPERIMENTAL.md

@@ -0,0 +1,350 @@
+# Experimental
+
+Features reconstructed from the WhatsApp Web bundle rather than from an existing
+library. Each one lists where its wire format came from and how far it has been
+verified, so you know what to trust before shipping it.
+
+Verification levels used below:
+
+| Level | Meaning |
+|---|---|
+| **Live** | executed against WhatsApp's servers and answered as expected |
+| **Offline** | stanza, proto or parser verified locally, never sent to a server |
+| **Derived** | shape taken from the bundle, no execution at all |
+
+---
+
+## Newsletter status
+
+`sendNewsletterStatus`, `sendNewsletterStatusReaction`, `revokeNewsletterStatus`,
+`getNewsletterStatuses`.
+
+Source: the Web status-publish RPC — `WASmaxOutStatusPublishPostNewsletterStatusRequest`
+and its mixins, plus `WASmaxInStatusPublishStatusAckMixin` for the ack.
+
+The stanza is a single flat element; every mixin merges onto the same `<status>`:
+
+```xml
+<status to="123@newsletter" id="MSGID" type="text">
+  <plaintext>PROTO_MESSAGE</plaintext>
+</status>
+```
+
+Media adds `type="media" media_id="UPLOAD_HANDLE"` and `<plaintext mediatype="image">`.
+`media_id` is the `handle` field of the newsletter upload response, which the upload
+result now keeps. Questions ride on media with `<meta interaction_type="question"/>`,
+question responses are text statuses carrying the parent `server_id`, reaction revoke
+is `edit="7"` and status revoke is `edit="8"`.
+
+The payload is the plain message proto. WhatsApp Web never wraps an outgoing status in
+`newsletterAdminProfileStatusMessage`; that field is only a future-proof container on
+the receiving side. Every status carries
+`contextInfo.statusAttributions = [{ type: NEWSLETTER_STATUS }]` and
+`featureEligibilities.canBeReshared`, matching the Web client. Pass
+`statusAttribution: false` to omit them.
+
+The ack is `<ack from class="status" id t [server_id] [edit]>`; a negative ack adds
+`error` plus optional `application_error` and `backoff`.
+
+**Verification: Live (partly).** The server accepts the stanza and answers a positive
+ack with `class="status"`. It did **not** return `server_id`, and the published status
+did not appear in `getNewsletterStatuses` — consistent with the account lacking the
+`CHANNEL_STATUS_PRODUCER` capability, which gates posting. The transport is correct;
+whether the status is stored depends on that capability.
+
+> [!IMPORTANT]
+> Posting a channel status needs the `channel_status_creation` feature, admin or owner
+> rights, and `CHANNEL_STATUS_PRODUCER` in the channel capabilities. Check with
+> `newsletterAdminCapabilities` first — without it the server acks and discards.
+
+`server_id` is optional on the ack. When it is missing, read it back with
+`getNewsletterStatuses`; reactions and question responses need it as `parentServerId`.
+
+---
+
+## Newsletter questions and polls
+
+Newsletter questions never worked because the `<meta>` node they are keyed by was never
+sent. The Web client publishes them as:
+
+```xml
+<message to="123@newsletter" id="MSGID" type="text">
+  <meta questiontype="question"/>
+  <plaintext>PROTO</plaintext>
+</message>
+```
+
+`questiontype` is `question` when the channel asks, `response` when a follower answers,
+and `reply` when the channel answers back. The `questionReply` content shortcut was added
+for the third case; it wraps `questionReplyMessage` and carries
+`contextInfo.questionReplyQuotedMessage` with the question server id.
+
+Poll result snapshots were also mis-keyed: they now send `type="poll"` with
+`<meta polltype="result_snapshot">`. Valid `polltype` values are `creation`,
+`quiz_creation`, `vote` and `result_snapshot`.
+
+**Verification: Offline.** Message generation checked for all three question types;
+the meta node is derived from the message wrapper, never guessed.
+
+### Photo polls
+
+Give a poll option an `image` and the poll becomes a photo poll:
+
+```js
+await sock.sendMessage(jid, {
+  poll: {
+    name: 'Which cover?',
+    values: [
+      { name: 'Jakarta', image: { url: './jakarta.jpg' } },
+      { name: 'Bandung', image: { url: './bandung.jpg' } }
+    ],
+    selectableCount: 1
+  }
+})
+```
+
+Each image is uploaded once, `pollContentType` becomes `IMAGE`, and each option carries
+the hash the Web client derives. The option images follow the poll as
+`pollCreationOptionImageMessage` children associated by `MEDIA_POLL` with
+`<meta message_association_type="media_poll">`, while the poll is keyed
+`<meta polltype="creation" contenttype="image">`. String options still send a plain
+text poll and may be mixed with image options.
+
+**Verification: Offline.** The proto is verified — `pollContentType: IMAGE` with per
+option hashes. One detail is inferred rather than read: the option hash is
+`sha256(sha256hex(name) + base64(fileSha256))`, and the base64 representation of the
+file hash is the part that was not directly observable in the bundle.
+
+### Channel poll votes
+
+`newsletterSendPollVote(jid, pollServerId, ['Jakarta'])` sends the votes node newsletters
+use, where each `<vote>` is the raw sha256 of the option name rather than the encrypted
+vote used in chats.
+
+**Verification: Derived.**
+
+---
+
+## Newsletter queries
+
+All taken id-by-id from the persisted queries in the bundle.
+
+| Method | What it answers |
+|---|---|
+| `newsletterAdminCapabilities` | which channel features the server enabled for you |
+| `newsletterAdminInfo` | the channel admin profile |
+| `newsletterInsights` | admin analytics, per metric values with timestamps |
+| `newsletterFollowers` | the follower list |
+| `newsletterPendingAdminInvites` | admin invites still awaiting an answer |
+| `newsletterPinMessages` / `newsletterUnpinMessages` | pin by message server id |
+| `newsletterPollVoters` | voters grouped per vote hash |
+| `newsletterReactionSenders` | who reacted to a message |
+| `newsletterLabelAiContent` / `newsletterLabelPaidPartnership` | content labels |
+| `newsletterCreateAdminInvite` / `Revoke` / `Accept` | the admin invite mutations |
+| `newsletterQuestionResponseState` | hide or show a follower's answer |
+| `newsletterRecommended` / `newsletterSimilar` | discovery |
+| `newsletterDirectoryList` / `Search` / `Categories` | the channel directory |
+
+Directory views are `RECOMMENDED`, `NEW`, `POPULAR`, `FEATURED` and `TRENDING`.
+Categories are `BUSINESS`, `ENTERTAINMENT`, `LIFESTYLE`, `NEWS`, `ORGANIZATIONS`,
+`PEOPLE`, `SPORTS` and `SPECIAL_EVENTS` through `SPECIAL_EVENTS_5`.
+
+**Verification: `newsletterAdminCapabilities` is Live** — it answered with the capability
+list for a channel and `Not Authorized` for a channel the account does not administer.
+Everything else is **Derived**.
+
+For insights, only `NET_FOLLOWS` and `UNFOLLOWS` appear as string literals in the bundle
+and are the defaults; the metric list is a parameter so other names can be tried.
+`metrics_status: MISSING` means the server has no data for the window yet, not an error.
+
+> [!NOTE]
+> `newsletterSubscribers` uses query id `9783111038412085`, which in the current bundle
+> is the pending-admin-invites query, and its `xwa2_newsletter_subscribers` path does not
+> exist in that response. `newsletterFollowers` is what the Web client uses instead. The
+> old binding was left in place rather than silently repointed.
+
+---
+
+## Username, About and link preview
+
+| Method | Query |
+|---|---|
+| `getUsername` | `xwa2_username_get` |
+| `setUsername` / `removeUsername` | `xwa2_username_set` |
+| `setUsernamePin` | `xwa2_username_pin_set` |
+| `checkUsernameAvailability` | `xwa2_username_check`, with server suggestions |
+| `updateTextStatus` / `fetchTextStatus` | `xwa2_update_text_status`, `xwa2_text_status_list` |
+| `fetchAbout` | `xwa2_users_updates_since` |
+| `fetchServerLinkPreview` | `xwa2_newsletter_link_preview` |
+
+WhatsApp Web moved About to MEX, where it is `{ text, emoji: { content }, ephemeral_duration_sec }`
+— an About can now carry an emoji and expire on its own, which the classic `status` IQ
+cannot express. That IQ (`updateProfileStatus`) is untouched.
+
+`fetchServerLinkPreview` lets the server build the preview instead of scraping the page.
+
+**Verification: Derived.**
+
+---
+
+## Terms of service, opt-out and push
+
+| Method | Namespace |
+|---|---|
+| `fetchUserNotices` / `updateUserNoticeStage` | `tos` |
+| `fetchOptOutList` / `updateOptOut` | `optoutlist` |
+| `fetchPushSettings` | `urn:xmpp:whatsapp:push` |
+
+WhatsApp gates features behind notices — the channel terms notice among them — so a
+client that never answers them stays gated. `stage` is the server's own counter for a
+notice: read the current value from `fetchUserNotices` before advancing it.
+
+**Verification: Derived.**
+
+---
+
+## WAProto additions
+
+Four Message types the Web bundle declares and `WAProto` did not:
+
+| Field | Type |
+|---|---|
+| 128 | `splitPaymentUpdateMessage` — `splitId`, `participantJid` |
+| 129 | `musicMessage` — `embeddedMusic`, `songUri`, `artworkUri`, `style`, `contextInfo` |
+| 130 | `statusLinkPreviewMetadata` — `style` |
+| 131 | `botPlatformRegistrationSuccessMessage` — a `FutureProofMessage` |
+
+Without these, messages of those types decode incompletely on arrival; `musicMessage` is
+the one likely to be seen in practice.
+
+`statusLinkPreviewMetadata.style` is declared `int32` rather than an enum: the field is an
+enum in the bundle, but its value names were not resolvable there, and an int32 is wire
+compatible with an enum. `MusicMessage.style` is `int32` in the bundle itself.
+
+**Verification: Offline.** Each field was encoded and decoded again, and the field number
+on the wire was read back from the raw bytes to confirm 128 through 131.
+
+---
+
+## Proto gaps beyond Message
+
+Catching `Message` up to field 131 closed the top-level oneof, but the bundle also declares
+fields on other types. Those are now applied too — **34 fields across 21 types, plus the 24
+supporting types they reference**:
+
+| Type | Fields added |
+|---|---|
+| `PreKeySignalMessage`, `SessionStructure.PendingPreKey` | `kyberCiphertext`, `kyberPreKeyId` — post-quantum prekeys |
+| `ContextInfo` | `aiProvenance`, `instagramThreadLink` |
+| `MessageContextInfo` | `accountEncryptionAttestation`, `associatedPrimaryIdentityKey` |
+| `Message.ProtocolMessage` | `coexStateSync`, `markAsVerifiedAction` |
+| `SyncActionValue` | `bubbleLockMessageAction`, `businessFolderActivationAction`, `contactManagerMetadataAction`, `ctwaMessageReceivedAction`, `deviceCapabilitiesV2`, `labelSublistAction`, `sharedDeviceAllowlistAction` |
+| `DeviceCapabilities` | `aiFbidMigration`, `bizAiSettingsSync`, `contactRefresh` |
+| `Conversation` | `identityVerification` |
+| `Message.Call` | `callReason` |
+| `DeviceProps.HistorySyncConfig` | `supportNewsletter` |
+| `ReportingTokenInfo` | `reportingTagTimestamp` |
+
+The rest sit on `BotMetadata`, `BotAgentDeepLinkMetadata`,
+`BotSignatureVerificationUseCaseProof`, `Message.MessageHistoryNotice`,
+`Message.PaymentExtendedMetadata`, `PeerDataOperationResult`,
+`ContextInfo.BusinessInteractionPills`, `SyncActionValue.BusinessBroadcastListAction`,
+`SyncActionValue.SettingsSyncAction` and `RootSecretEntry`.
+
+Enum-typed fields are declared `int32`. The bundle carries enum member names in a form the
+extractor cannot resolve, and int32 is wire compatible with an enum, so the value arrives
+intact even though the name does not.
+
+`ExtendedTextMessage.faviconMmsMetadata` is **not** in that list: `WAProto` already had it
+as `faviconMMSMetadata`. The comparison is case-insensitive now so an acronym spelled
+differently on each side does not read as a missing field.
+
+167 types in the bundle have no `WAProto` counterpart at all. Almost all of them are the
+`ConsumerApplication` / Armadillo message family, which this library does not speak; they
+are counted in the report but never patched.
+
+Unknown proto fields are skipped on decode rather than fatal, so a gap shows up as data
+quietly missing from received messages, not as an error.
+
+---
+
+## Unmodelled MEX notifications
+
+WhatsApp Web routes 35 operations through its `w:mex` notification handler. This fork
+named 16 and shared 14 of them with the Web list; the remaining 21 fell into a `default`
+branch that logged and returned, so nothing downstream could ever see them:
+
+| Area | Operations |
+|---|---|
+| Events | `NotificationEventDelete`, `Invite`, `InviteRemove`, `Reminder`, `Rsvp`, `Update` |
+| Group properties | `NotificationGroupPropertyUpdate`, `GroupHiddenPropertyUpdate`, `GroupLimitSharingPropertyUpdate`, `GroupMemberLinkPropertyUpdate`, `GroupMemberShareGroupHistoryModePropertyUpdate`, `GroupSafetyCheckPropertyUpdate`, `GroupAppealStatusUpdate` |
+| Communities | `NotificationCommunityOwnerUpdate` |
+| Newsletters | `NotificationNewsletterAIContentUpdate`, `NotificationNewsletterAdminProfileUpdate`, `NotificationNewsletterPaidPartnershipUpdate` |
+| Scheduled messages | `NotificationScheduledMessagePost`, `NotificationScheduledMessageReveal` |
+| Integrity | `NotificationIntegrityChallengeRequest`, `NotificationUserBrigadingUpdate` |
+
+One of those is a plain name mismatch rather than a missing feature: the fork listened for
+`NotificationNewsletterPaidPartnership`, while the Web bundle sends
+`NotificationNewsletterPaidPartnershipUpdate`. Both names now route to the newsletter
+handler, so paid-partnership notifications reach it for the first time.
+
+The default branch now re-emits the rest instead:
+
+```js
+sock.ev.on('mex.notification', ({ operation, updates, data }) => {
+  console.log(operation, updates)
+})
+```
+
+Modelling each one properly means knowing its payload shape, which the bundle only gives
+for the operations WhatsApp Web itself renders. The passthrough is the honest middle
+ground: the data reaches you unchanged, typed as whatever the server sent, and anything
+worth modelling can be promoted to a real event later without breaking it.
+
+**Verification: Offline.** The operation list is read from the Web bundle's notification
+router; the payloads have not been observed on the wire.
+
+---
+
+## Keeping up with WhatsApp Web
+
+```bash
+npm run check:proto
+npm run sync:proto
+node ./script/verifyproto.js
+```
+
+`check:proto` downloads the current bundle, extracts every proto spec in it, and compares
+the `Message` oneof and every other type against `WAProto`. It prints the live and pinned
+client revisions and exits non-zero when WhatsApp declares fields this proto does not.
+
+`sync:proto` applies them — it patches the generated `WAProto/index.js` and `index.d.ts` in
+place, adding whatever supporting types the new fields reference. It is additive and
+idempotent: running it twice changes nothing the second time. It refuses to touch a gap in
+the `Message` oneof, because a new top-level message type warrants regenerating the proto
+by hand.
+
+`verifyproto.js` is the safety net. It encodes every field the bundle declares, reads the
+field number back off the wire, decodes it again and runs `toObject` — roughly 2,900 fields
+on the current bundle. A patch that writes the wrong tag or loses a value fails here.
+
+All three take `PROTO_BUNDLE_DIR` to read chunks off disk instead of the network;
+`script/fetchbundle.js` downloads them once.
+
+The `Proto Watch` workflow runs daily and chains them: fetch the bundle, compare, bump the
+client revision if it drifted, apply new fields, verify, and commit. If verification fails
+the proto patch is rolled back and an issue labelled `proto-watch` is opened instead, so a
+broken proto is never pushed.
+
+Commits are made as the repository owner. Push uses `GH_PAT` when that secret exists and
+falls back to `GITHUB_TOKEN` otherwise; with the fallback the commit is still authored by
+the owner, it is simply pushed by Actions. Run it by hand from the Actions tab with
+`apply: false` to get the report without any changes.
+
+---
+
+## Testing what is only Derived
+
+Most of the surface above has never been executed against a server. When something
+answers with a GraphQL error or an unexpected stanza, the error text usually names the
+field that is wrong, and the fix is normally a variable name rather than a redesign.

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2025 Rajeh Taher/WhiskeySockets
+Copyright (c) 2026 noxXza/luna-baileys
+Copyright (c) 2026 RexxHayanasi
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.