@violetix/baileys 0.3.18 → 0.4.0

package/README.md

@@ -381,6 +381,14 @@ and the sections after it.
 - 🔢 `version` accepts a resolver function, and a `405 client_too_old` failure fetches the live WA Web build and applies it on the next reconnect. `fetchLatestWaWebVersion()` now times out after 10s (`timeoutMs` / `signal` options).
 - 🔐 Passkey-gated (Shortcake) accounts are surfaced: `connection.update { passkeyRequired: true }` plus a warning when the server sends `passkey_prologue_request`. Expired pairing codes (`refresh_code`) are re-registered automatically with the same code, or surfaced as `connection.update { pairingCodeExpired: true }`.
 - 🏢 `onWhatsAppUsername()` also reports `isBusiness` / `pnJid`; the USync business parser treats a `<error/>` child as "not a business" instead of failing the whole query, and `withBusinessProtocol(null)` asks for the verified name only.
+- 🖼️ Added [image polls](#%EF%B8%8F-image-poll): `sendMessage(jid, { imagePoll })` uploads one image per option, hashes each option over its uploaded `fileSha256`, sends the `pollCreationMessageV3` parent with `pollContentType: IMAGE`, then one `pollCreationOptionImageMessage` child per option associated back by `MEDIA_POLL`. `hashImagePollOption()` is exported separately. Ported from [`@rennzsync/baileys`](https://github.com/RennZSync/baileys).
+- 🧩 Added [A2UI widgets](#-a2ui-widget): `sendMessage(jid, { a2ui })` with a declarative builder (`Text`, `Image`, `Video`, `Button`, `Card`, `Column`, `Row`, `Divider`, `CheckBox`, `TextField`, `ChoicePicker`, plus `listCard`) compiled into `interactiveMessage.bloksWidget`. Ported from [`@rennzsync/baileys`](https://github.com/RennZSync/baileys), rebuilt on this fork's own interactive path so the `<biz>` node and button shapes are the existing ones.
+- 🙊 Added the [`exclusive`](#-exclusive-message) send option: a group message addressed to a single member (`to=<group> participant=<member>`, per-device encryption instead of the group sender key), so no other member receives the stanza. The recipient comes from the quoted message's author, or from an explicit jid.
+- 🚫 Added [`sock.ignoreKey()`](#-ignoring-inbound-stanzas): drops matching inbound stanzas before any handler — including the decryption and persistence paths — while still acking so the server stops redelivering. Matches by `remoteJid` / `fromMe` / `id` / `participant` (PN ↔ LID alt attributes included) or by predicate, over `message`, `receipt`, `notification`, `presence`, `chatstate` and `call`. `category='peer'` traffic from your own devices is never dropped, so an app-state key share cannot be filtered away by accident.
+- 🛡️ Added [`createAnchorGuard()`](#%EF%B8%8F-anchor-guard) / `detectBug()`: flags payloads that force-close WhatsApp clients — invisible and combining character floods, mention bombs, oversized native-flow / list / carousel payloads, broken `buttonParamsJson`, over-deep or circular structures — then deletes them and optionally blocks the sender or kicks on burst. Ported from [`@rexxhayanasi/elaina-anchorguard`](https://www.npmjs.com/package/@rexxhayanasi/elaina-anchorguard) (MIT) via [`@rennzsync/baileys`](https://github.com/RennZSync/baileys).
+- 🗓️ Sent `encEventResponseMessage` and `EVENT_EDIT` secrets as `type=event`. Only `eventMessage` was matched, so event responses went out as `type=text` — a pairing a real client never sends, and the server validates stanza shape.
+- 🧾 Stamped `mediatype=group_history` on `messageHistoryBundle` sends, which previously carried no media type at all.
+- 🔑 `useMultiFileAuthState(folder, logger)` and `useSingleFileAuthState(file, logger)` accept a logger. Credential write failures were swallowed entirely (the internal logger was hard-wired to `null`), so a full disk or a permission error lost the session and looked like a random logout on the next boot. Corrupt or unreadable key files are reported too, and `_destroy()` releases the process exit hooks a long-lived multi-session host would otherwise leak.
 
 ## 📨 Messages Handling & Compatibility
 
@@ -390,6 +398,8 @@ and the sections after it.
   - 👉🏻 [Interactive Message](#-sending-interactive-messages) (buttons, lists, native flows, templates, carousels).
   - 🎞️ [Status Mention Message](#%EF%B8%8F-status-mention)
   - 📦 [Sticker Pack Message](#-sticker-pack)
+  - 🖼️ [Image Poll](#%EF%B8%8F-image-poll)
+  - 🧩 [A2UI Widget](#-a2ui-widget)
   - ✨ [Rich Response Message](#-rich-response)
   - 🧾 [Message with Code Blocks](#-message-with-code-block)
   - [🌏 Message with Inline Entities](#-message-with-inline-entities)
@@ -406,6 +416,7 @@ and the sections after it.
   - 📣 [`mentionAll`](#-mention) - Mention all group participants without requiring their JIDs in `mentions` or `mentionedJid`
   - 🔧 [`ephemeral`](#-ephemeral), [`groupStatus`](#%E2%80%8D%E2%80%8D-group-status), [`isLottie`](#-lottie-sticker), [`spoiler`](#-spoiler), [`viewOnce`](#%EF%B8%8F-view-once), [`viewOnceV2`](#%EF%B8%8F-view-once-v2), [`viewOnceV2Extension`](#%EF%B8%8F-view-once-v2-extension), [`interactiveAsTemplate`](#%EF%B8%8F-interactive) - Message wrappers
   - 🔒 [`secureMetaServiceLabel`](#%EF%B8%8F-secure-meta-service-label) - Secure meta service label on message
+  - 🙊 [`exclusive`](#-exclusive-message) - Send into a group addressed to one member only
   - 📄 [`raw`](#-raw) - Build your message manually **(DO NOT USE FOR EXPLOITATION)**
   - 🎞️ [`statusPrivacy`](#%EF%B8%8F-status-mention) - Control who receives a status broadcast (`contacts` | `allowlist` | `denylist`)
 
@@ -768,6 +779,30 @@ sock.sendMessage(jid, {
 })
 ```
 
+### 🖼️ Image Poll
+
+A poll whose options are images instead of text.
+
+```javascript
+sock.sendMessage(jid, {
+   imagePoll: {
+      name: '🖼️ Pick your favourite',
+      selectableCount: 1, // --- Optional, defaults to 1
+      options: [
+         { name: 'Gambar 1', image: { url: 'https://example.com/1.jpg' } },
+         { name: 'Gambar 2', image: { url: 'https://example.com/2.jpg' } }
+      ]
+   }
+}, {
+   quoted: message
+})
+```
+
+Each option's image is uploaded first, because the option hash covers the uploaded media's `fileSha256` — `sha256(hex(sha256(name)) + base64(fileSha256))`, exported as `hashImagePollOption(name, fileSha256)` if you need it on its own. The parent goes out as `pollCreationMessageV3` with `pollContentType: IMAGE` carrying only the names and hashes; the images follow as one `pollCreationOptionImageMessage` each, tied back to the parent by a `MEDIA_POLL` association (the same mechanism albums use). A vote carries the hash, not the name.
+
+> [!WARNING]
+> This is a client-side implementation of a message type WhatsApp's proto defines but no Baileys fork ships a builder for. Treat it as experimental and check how it renders on your target client before relying on it.
+
 ### 💭 Button Response
 
 ```javascript
@@ -2708,6 +2743,145 @@ sock.CLIENT_PERSIST_GQL_IDS;
 > [!WARNING]
 > These calls leave the WhatsApp WebSocket and hit Meta's HTTPS endpoints directly. They have no built-in timeout, so wrap them in your own if a hung request would stall your bot.
 
+### 🧩 A2UI Widget
+
+Declarative widgets sent as `interactiveMessage.bloksWidget`. Every builder method registers a component and returns its id, so a tree is written bottom-up.
+
+```javascript
+import { A2UI } from "@violetix/baileys";
+
+const ui = new A2UI();
+const title = ui.text("Halo!", { variant: "h1" });
+const button = ui.button(ui.text("Klik saya"), { action: { name: "noop" } });
+ui.root([ui.card(ui.column([title, button]))]);
+
+await sock.sendMessage(jid, { a2ui: ui, text: "Widget", footer: "A2UI" });
+
+// --- product list shortcut, its own payload shape
+const list = new A2UI().listCard({
+   title: "Menu",
+   items: [{ title: "Nasi Goreng", price: "Rp15.000" }, { title: "Es Teh", price: "Rp5.000" }]
+});
+await sock.sendMessage(jid, { a2ui: list, text: "Pesan menu" });
+
+// --- widget as the whole message, plus native flow buttons
+await sock.sendMessage(jid, {
+   a2ui: ui,
+   singleScreen: true,
+   nativeFlow: [{ text: "🌐 Visit", url: "https://example.com" }]
+});
+```
+
+| Component      | Builder                                                                  |
+| -------------- | ------------------------------------------------------------------------ |
+| `Text`         | `ui.text(text, { variant })` — `variant` defaults to `body`               |
+| `Image`        | `ui.image(url, { variant, fit })` — `fit` defaults to `cover`             |
+| `Video`        | `ui.video(url)`                                                          |
+| `Button`       | `ui.button(childId, { variant, action })`                                |
+| `Card` / `Column` / `Row` | `ui.card(childId)`, `ui.column(ids, { justify, align })`, `ui.row(ids)` |
+| `CheckBox` / `TextField` / `ChoicePicker` / `Divider` | `ui.checkbox(label, { value })`, `ui.textField(label, { variant })`, `ui.choicePicker(label, options, { variant, displayStyle, filterable })`, `ui.divider()` |
+
+Send options on the content: `text` (body), `footer`, `singleScreen` (no bubble around the widget), `nativeFlow` (this fork's usual [button shapes](#%EF%B8%8F-interactive)), `messageSecret`, `a2uiType`, `a2uiWrapped: false` (emit a bare `{ components }` payload instead of the `createSurface` envelope). `nativeFlowMessage` is always attached — it is what keys the interactive render and what makes the `<biz>` node go out.
+
+> [!WARNING]
+> Internal WhatsApp format. A send can succeed with no error while the widget renders as nothing on the recipient's client. Test on a throwaway number first.
+
+### 🙊 Exclusive Message
+
+Sends into a group but addressed to **one member**. Other members never receive the stanza at all, so there is nothing for them to see or decrypt.
+
+```javascript
+// the quoted message names the recipient — its author
+await sock.sendMessage(m.chat, { text: "Hi, only you can see this." }, { quoted: m, exclusive: true });
+
+// or address someone else explicitly, in the group's own addressing mode
+await sock.sendMessage(groupJid, { text: "psst" }, { exclusive: "43411111111111@lid" });
+```
+
+`exclusive: true` requires `quoted` — the quoted message's author is the only place the recipient comes from, and it already carries the group's addressing mode (a LID-addressed group quotes `@lid`, a PN one quotes `@s.whatsapp.net`), so nothing has to be mapped. Without a quote, or with a quote that has no `participant` (a 1:1 quote), the send throws. So does `exclusive` outside a group.
+
+How it works: the stanza goes out as `to=<group> participant=<member>` with per-device `pkmsg`/`msg` encryption instead of the group sender key, reusing the retry-resend path. A `skmsg` stanza is fanned out to the whole group by the server, so sender-key sends can never be targeted. One stanza per device of the recipient, all sharing the message id.
+
+> [!NOTE]
+> Your own linked devices are not addressed, so the message does not appear in the group on your phone — only `messages.upsert` fires locally (via `emitOwnEvents`). The recipient sees an ordinary group message; nothing marks it as private on their side.
+
+### 🚫 Ignoring Inbound Stanzas
+
+`sock.ignoreKey(input)` drops matching inbound stanzas **before any handler runs** — including the decryption and persistence paths. The ack is still sent, so the server stops redelivering them. It returns an unregister function.
+
+```javascript
+// --- Descriptor: drop everything from one peer
+const off = sock.ignoreKey({ remoteJid: "6281111111111@s.whatsapp.net" });
+
+// Only that peer's messages; receipts and presence still arrive
+sock.ignoreKey({ remoteJid: "6281111111111@s.whatsapp.net", only: ["message"] });
+
+// Several chats at once (array entries OR)
+sock.ignoreKey({ remoteJid: ["111111@g.us", "222222@g.us"] });
+
+// Your own outbound echoes from other devices
+sock.ignoreKey({ fromMe: true, only: ["message"] });
+
+off(); // unregister
+
+// --- Predicate: anything the descriptor cannot express
+sock.ignoreKey((m) => m.kind === "message" && isJidGroup(m.remoteJid ?? ""));
+sock.ignoreKey((m) => isJidStatusBroadcast(m.remoteJid ?? ""));
+```
+
+| Field         | Type                                                                                    | Notes                                                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `remoteJid`   | `string \| string[]`                                                                    | Chat JID. Array entries OR. Also matched against the alt `sender_pn` / `sender_lid` attributes, so one JID form catches the other. |
+| `fromMe`      | `boolean`                                                                               | Whether the stanza was sent by this account, resolved against both your PN and LID.                                            |
+| `id`          | `string`                                                                                | Stanza id.                                                                                                                     |
+| `participant` | `string`                                                                                | Author in groups / broadcasts. Alt forms are matched too.                                                                      |
+| `only`        | `('message' \| 'receipt' \| 'notification' \| 'presence' \| 'chatstate' \| 'call')[]`   | Restrict to specific tags. Default: all six.                                                                                   |
+
+Top-level fields AND together; the `remoteJid` array ORs. At least one of `remoteJid` / `fromMe` / `id` / `participant` is required — empty descriptors throw, as do unknown `only` values.
+
+A predicate receives the already-parsed stanza: `{ kind, remoteJid, fromMe, id, participant }`, with `remoteJid` and `participant` device-stripped so they line up with `event.key.remoteJid`. Return `true` to drop. A predicate that throws is logged and the stanza is kept.
+
+> [!IMPORTANT]
+> `category='peer'` messages from your own devices are **never** dropped, whatever the filter says. They carry app-state key shares, history sync and PDO responses between your devices, so a `{ fromMe: true }` filter would otherwise swallow the app-state key share and leave the collections blocked on a key they re-request on every sync. The exemption applies only when the sender really is this account, so a foreign stanza cannot dodge a filter by stamping the attribute. Stream control and the auth-critical `success` / `failure` tags bypass filters as well.
+
+### 🛡️ Anchor Guard
+
+Detects payloads that force-close WhatsApp clients, deletes them, and optionally blocks the sender.
+
+```javascript
+import { createAnchorGuard, detectBug } from "@violetix/baileys";
+
+const guard = createAnchorGuard(sock, {
+  blockOnBug: true,
+  guardOutgoing: true, // also reject your own crash payloads before they are sent
+  onDetect: ({ direction, jid, reasons }) => console.log("🛡️", direction, jid, reasons),
+});
+
+// one-off check without attaching anything
+const { flagged, reasons } = detectBug(msg.message);
+
+guard.stop(); // detach listeners and unwrap sendMessage
+```
+
+Flags invisible and combining character floods, mention bombs, oversized native-flow / list / carousel payloads, `buttonParamsJson` that is broken or huge, excessive newlines, over-deep, over-wide and circular structures, and — when you pass `proto` — an encoded size over `maxBytes`.
+
+| Option                            | Default  | Description                                                                              |
+| --------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `autoDelete`                      | `true`   | Delete a flagged inbound message.                                                        |
+| `deleteMode`                      | `'auto'` | `'auto'` revokes your own messages and deletes others locally; `'everyone'` always revokes. |
+| `guardIncoming`                   | `true`   | Guard `messages.upsert`.                                                                 |
+| `guardOutgoing`                   | `false`  | Wrap `sock.sendMessage` and throw on a crash payload.                                    |
+| `blockOnBug`                      | `false`  | Block the sender of a flagged message.                                                   |
+| `selfOnly`                        | `false`  | Only guard your own chats.                                                               |
+| `burstThreshold` / `burstWindowMs` | `0` / `4000` | Messages from one sender inside the window before it counts as a burst. `0` disables. |
+| `kickOnBurst`                     | `false`  | Remove the sender from the group on burst (needs admin).                                 |
+| `guardGroupAdds`                  | `false`  | Flag / kick when a burst-flagged inviter adds you to a group.                             |
+| `metaAiNumbers`                   | `false`  | Guard Meta AI's own numbers instead of exempting them.                                   |
+| `thresholds`                      | `{}`     | Override any of `ANCHORGUARD_DEFAULTS`.                                                  |
+
+> [!NOTE]
+> `guardOutgoing` replaces `sock.sendMessage` with a wrapper, which is why it is off by default — turn it on knowingly if your own code also wraps `sendMessage`. `stop()` only unwinds its own wrapper, so a wrapper you installed afterwards survives.
+
 ### 📡 Events
 
 ```javascript

package/lib/Socket/index.d.ts

@@ -636,6 +636,7 @@ declare function makeWASocket(config: import('../Types/Socket.js').SocketConfig)
     updateMemberLabel: (jid: any, memberLabel: any) => Promise<any>;
     updateMediaMessage: (message: any) => Promise<any>;
     sendMessage: (jid: any, content: any, options?: {}) => Promise<import("../index.js").proto.WebMessageInfo | undefined>;
+    groupStatus: (jid: any, content?: any, options?: {}) => Promise<import("../index.js").proto.WebMessageInfo | undefined>;
     executeWMexQuery: (variables: any, queryId: any, dataPath: any) => Promise<any>;
     newsletterCreate: (name: any, description: any) => Promise<{
         id: any;
@@ -875,6 +876,12 @@ declare function makeWASocket(config: import('../Types/Socket.js').SocketConfig)
     signalRepository: any;
     user: any;
     generateMessageTag: () => string;
+    /**
+     * Drops matching inbound stanzas before any handler — including the decryption and
+     * persistence paths — sees them. The ack is still sent so the server stops re-delivering.
+     * Returns an unregister function.
+     */
+    ignoreKey: (input: import('../Utils/ignore-key.js').WaIgnoreKeyInput) => () => void;
     query: (node: any, timeoutMs: any) => Promise<any>;
     waitForMessage: (msgId: any, timeoutMs?: any) => Promise<any>;
     waitForSocketOpen: () => Promise<void>;

package/lib/Socket/messages-send.js

@@ -3,7 +3,7 @@ import { Boom } from '@hapi/boom';
 import { randomBytes } from 'crypto';
 import { proto } from '../../WAProto/index.js';
 import { BIZ_BOT_SUPPORT_PAYLOAD, DEFAULT_CACHE_TTLS, WA_DEFAULT_EPHEMERAL } from '../Defaults/index.js';
-import { aggregateMessageKeysNotFromMe, assertMediaContent, assertMeId, bindWaitForEvent, decryptMediaRetryData, DEF_MEDIA_HOST, delay, encodeNewsletterMessage, encodeSignedDeviceIdentity, encodeWAMessage, encryptMediaRetryRequest, extractDeviceJids, generateMessageIDV2, generateParticipantHashV2, generateWAMessage, generateWAMessageFromContent, getStatusCodeForMediaRetry, getUrlFromDirectPath, getWAUploadToServer, hasValidAlbumMedia, MessageRetryManager, normalizeMessageContent, parseAndInjectE2ESessions, shouldIncludeBizBinaryNode, unixTimestampSeconds } from '../Utils/index.js';
+import { aggregateMessageKeysNotFromMe, assertMediaContent, assertMeId, bindWaitForEvent, decryptMediaRetryData, DEF_MEDIA_HOST, delay, encodeNewsletterMessage, encodeSignedDeviceIdentity, encodeWAMessage, encryptMediaRetryRequest, extractDeviceJids, generateMessageIDV2, generateParticipantHashV2, generateWAMessage, generateWAMessageFromContent, getStatusCodeForMediaRetry, getUrlFromDirectPath, getWAUploadToServer, hashImagePollOption, hasValidAlbumMedia, MessageRetryManager, normalizeMessageContent, parseAndInjectE2ESessions, prepareWAMessageMedia, shouldIncludeBizBinaryNode, unixTimestampSeconds } from '../Utils/index.js';
 import { AssociationType } from '../Types/index.js';
 import { setBotMessageSecret } from '../Utils/decode-wa-message.js';
 import { getUrlInfo } from '../Utils/link-preview.js';
@@ -1041,6 +1041,79 @@ export const makeMessagesSocket = (config) => {
             throw err;
         }
     };
+    /**
+     * Uploads one image per poll option and returns the hashed options for the parent poll
+     * alongside the prepared media the children will carry. The hash covers the uploaded
+     * media's `fileSha256`, so the upload has to happen before the parent is built.
+     */
+    const prepareImagePollOptions = async (imagePoll, genOptions) => {
+        if (!Array.isArray(imagePoll.options) || !imagePoll.options.length) {
+            throw new Boom('Invalid imagePoll options', { statusCode: 400 });
+        }
+        const optionMedia = [];
+        const options = [];
+        for (const option of imagePoll.options) {
+            if (!option?.image) {
+                throw new Boom('every imagePoll option needs an image', { statusCode: 400 });
+            }
+            const media = await prepareWAMessageMedia({ image: option.image }, genOptions);
+            optionMedia.push(media);
+            options.push({
+                optionName: option.name,
+                optionHash: hashImagePollOption(option.name, media.imageMessage?.fileSha256)
+            });
+        }
+        return { optionMedia, options };
+    };
+    /**
+     * Picks the single group member an exclusive message is addressed to.
+     *
+     * `exclusive: true` reads the author of the quoted message, which is why a quote is required:
+     * it is the only place the recipient can come from, and it already carries the group's own
+     * addressing mode (a LID-addressed group quotes `@lid`, a PN one quotes `@s.whatsapp.net`),
+     * so no mapping is needed. Pass a jid instead to address someone else — in the group's mode.
+     */
+    const resolveExclusiveTarget = (options) => {
+        if (typeof options.exclusive === 'string') {
+            return options.exclusive;
+        }
+        const quoted = options.quoted;
+        return quoted?.key?.participant || quoted?.participant || undefined;
+    };
+    /**
+     * Sends into a group but addressed to one member: the stanza goes out as
+     * `to=<group> participant=<member>`, so the server routes it to that member's devices and no
+     * other member receives anything at all. Reuses the retry-resend path — per-device pkmsg/msg
+     * instead of the group sender key, which is what makes the targeting possible: a `skmsg`
+     * stanza is fanned out to the whole group by the server.
+     *
+     * One stanza per device of the recipient, all sharing the message id, because a group
+     * `participant` attribute addresses a device and not an account.
+     */
+    const relayExclusive = async (jid, message, options, relayOpts) => {
+        if (!isJidGroup(jid)) {
+            throw new Boom('exclusive messages are only supported in groups', { statusCode: 400 });
+        }
+        const target = resolveExclusiveTarget(options);
+        if (!target) {
+            throw new Boom('exclusive requires a quoted message to pick the recipient, or an explicit jid', { statusCode: 400 });
+        }
+        const targetUser = jidNormalizedUser(target);
+        const deviceJids = (await getUSyncDevices([targetUser], relayOpts.useUserDevicesCache !== false, false))
+            .map(device => device.jid)
+            .filter(Boolean);
+        // No device list means the member is unknown to usync; addressing the bare jid still
+        // reaches their primary device rather than failing the send outright.
+        const targets = deviceJids.length ? deviceJids : [targetUser];
+        logger.debug({ jid, target: targetUser, devices: targets.length }, 'sending exclusive group message');
+        for (const deviceJid of targets) {
+            await relayMessage(jid, message, {
+                ...relayOpts,
+                participant: { jid: deviceJid, count: 0 }
+            });
+        }
+        return targets;
+    };
     const getMessageType = (message) => {
         if (!message)
             return 'text';
@@ -1055,7 +1128,12 @@ export const makeMessagesSocket = (config) => {
             message.pollUpdateMessage) {
             return 'poll';
         }
-        if (message.eventMessage) {
+        // An event response and an EVENT_EDIT secret both belong to the event thread. Only
+        // `eventMessage` was matched here, so those two went out as `media`/`text`; the server
+        // validates stanza shape, which is a pairing a real client never sends.
+        if (message.eventMessage ||
+            message.encEventResponseMessage ||
+            message.secretEncryptedMessage?.secretEncType === proto.Message.SecretEncryptedMessage.SecretEncType.EVENT_EDIT) {
             return 'event';
         }
         if (getMediaType(message) !== '') {
@@ -1115,6 +1193,9 @@ export const makeMessagesSocket = (config) => {
         else if (message.extendedTextMessage?.matchedText || message.groupInviteMessage) {
             return 'url';
         }
+        else if (message.messageHistoryBundle) {
+            return 'group_history';
+        }
         // Lia@Note 02-02-26 --- Add more message type here
         else if ((message.extendedTextMessage?.text || message.conversation || '').includes('://wa.me/c/')) {
             return 'cataloglink';
@@ -1327,7 +1408,23 @@ export const makeMessagesSocket = (config) => {
                 await groupToggleEphemeral(jid, value);
             }
             else {
-                const fullMsg = await generateWAMessage(jid, content, {
+                // An image poll uploads one image per option before the parent is built: the
+                // parent only carries each option's hash, and the hash covers the uploaded
+                // media's fileSha256. The images follow as children once the parent has a key.
+                let imagePollOptionMedia;
+                let sendContent = content;
+                if ('imagePoll' in content && content.imagePoll) {
+                    const prepared = await prepareImagePollOptions(content.imagePoll, {
+                        logger,
+                        upload: waUploadToServer,
+                        mediaCache: config.mediaCache,
+                        options: config.options,
+                        ...options
+                    });
+                    imagePollOptionMedia = prepared.optionMedia;
+                    sendContent = { ...content, imagePoll: { ...content.imagePoll, options: prepared.options } };
+                }
+                const fullMsg = await generateWAMessage(jid, sendContent, {
                     logger,
                     userJid,
                     getUrlInfo: text => getUrlInfo(text, {
@@ -1354,7 +1451,7 @@ export const makeMessagesSocket = (config) => {
                 const isEditMsg = 'edit' in content && !!content.edit;
                 const isPinMsg = 'pin' in content && !!content.pin;
                 const isKeepMsg = 'keep' in content && !!content.keep;
-                const isPollMsg = 'poll' in content && !!content.poll;
+                const isPollMsg = ('poll' in content && !!content.poll) || !!imagePollOptionMedia;
                 const isQuizMsg = 'poll' in content && !!content.poll.pollType;
                 const isAiMsg = 'ai' in content && !!content.ai;
                 const isNeedBizAttrs = 'secureMetaServiceLabel' in content && !!content.secureMetaServiceLabel;
@@ -1417,7 +1514,7 @@ export const makeMessagesSocket = (config) => {
                     });
                     delete content.ai;
                 }
-                await relayMessage(jid, fullMsg.message, {
+                const relayOpts = {
                     messageId: fullMsg.key.id,
                     useCachedGroupMetadata: options.useCachedGroupMetadata,
                     addBizAttributes: isNeedBizAttrs,
@@ -1425,10 +1522,43 @@ export const makeMessagesSocket = (config) => {
                     statusPrivacy: options.statusPrivacy,
                     additionalAttributes,
                     additionalNodes
-                });
+                };
+                if (options.exclusive) {
+                    await relayExclusive(jid, fullMsg.message, options, relayOpts);
+                }
+                else {
+                    await relayMessage(jid, fullMsg.message, relayOpts);
+                }
                 if (config.emitOwnEvents) {
                     setImmediate(() => emitOwnUpsert(fullMsg));
                 }
+                // The option images follow the parent, each pointing back at it. Same shape as
+                // the album loop below, with MEDIA_POLL instead of MEDIA_ALBUM.
+                if (imagePollOptionMedia?.length) {
+                    for (const media of imagePollOptionMedia) {
+                        const optionMsg = generateWAMessageFromContent(jid, {
+                            pollCreationOptionImageMessage: { message: media },
+                            messageContextInfo: {
+                                messageAssociation: {
+                                    parentMessageKey: fullMsg.key,
+                                    associationType: AssociationType.MEDIA_POLL
+                                }
+                            }
+                        }, {
+                            userJid,
+                            messageId: generateMessageIDV2(userJid)
+                        });
+                        await relayMessage(jid, optionMsg.message, {
+                            messageId: optionMsg.key.id,
+                            useCachedGroupMetadata: options.useCachedGroupMetadata,
+                            additionalAttributes,
+                            additionalNodes: []
+                        });
+                        if (config.emitOwnEvents) {
+                            process.nextTick(() => emitOwnUpsert(optionMsg));
+                        }
+                    }
+                }
                 // Lia@Changes 31-01-26 --- Add support for album messages
                 // Lia@Note 06-02-26 --- Refactored to reduce high RSS usage (⁠╥⁠﹏⁠╥⁠)
                 if ('album' in content) {

package/lib/Socket/socket.d.ts

@@ -25,6 +25,12 @@ export function makeSocket(config: any): {
     signalRepository: any;
     readonly user: any;
     generateMessageTag: () => string;
+    /**
+     * Drops matching inbound stanzas before any handler — including the decryption and
+     * persistence paths — sees them. The ack is still sent so the server stops re-delivering.
+     * Returns an unregister function.
+     */
+    ignoreKey: (input: import('../Utils/ignore-key.js').WaIgnoreKeyInput) => () => void;
     query: (node: any, timeoutMs: any) => Promise<any>;
     waitForMessage: (msgId: any, timeoutMs?: any) => Promise<any>;
     waitForSocketOpen: () => Promise<void>;

package/lib/Socket/socket.js

@@ -7,6 +7,8 @@ import { DEF_CALLBACK_PREFIX, DEF_TAG_PREFIX, INITIAL_PREKEY_COUNT, MIN_PREKEY_C
 import { QueryIds, ReachoutTimelockEnforcementType } from '../Types/index.js';
 import { DisconnectReason, XWAPaths } from '../Types/index.js';
 import { addTransactionCapability, aesEncryptCTR, bindWaitForConnectionUpdate, buildPairingQRData, bytesToCrockford, configureSuccessfulPairing, Curve, derivePairingCodeKey, fetchLatestWaWebVersion, generateLoginNode, generateMdTagPrefix, generateRegistrationNode, getCodeFromWSError, getErrorCodeFromStreamError, getNextPreKeysNode, getPairingCodePlatform, invalidPairingCodeChars, makeEventBuffer, makeNoiseHandler, normalizePairingCode, PAIRING_CODE_ALPHABET, promiseTimeout, signedKeyPair, xmppSignedPreKey } from '../Utils/index.js';
+import { ignoredStanzaNeedsAck, makeIgnoreKeyRegistry } from '../Utils/ignore-key.js';
+import { buildAckStanza } from '../Utils/stanza-ack.js';
 import { assertNodeErrorFree, binaryNodeToString, encodeBinaryNode, getAllBinaryNodeChildren, getBinaryNodeChild, getBinaryNodeChildren, isLidUser, jidDecode, jidEncode, S_WHATSAPP_NET } from '../WABinary/index.js';
 import { BinaryInfo } from '../WAM/BinaryInfo.js';
 import { USyncQuery, USyncUser } from '../WAUSync/index.js';
@@ -560,6 +562,11 @@ export const makeSocket = (config) => {
             // Don't throw - allow connection to continue even if pre-key check fails
         }
     };
+    const ignoreKeyRegistry = makeIgnoreKeyRegistry({
+        getMeId: () => authState.creds.me?.id,
+        getMeLid: () => authState.creds.me?.lid,
+        logger
+    });
     const onMessageReceived = async (data) => {
         await noise.decodeFrame(data, frame => {
             lastDateRecv = new Date();
@@ -570,6 +577,16 @@ export const makeSocket = (config) => {
                 if (logger.level === 'trace') {
                     logger.trace({ xml: binaryNodeToString(frame), msg: 'recv xml' });
                 }
+                // Filters run before every other handler, so a dropped stanza never reaches the
+                // decryption or persistence paths. The ack still goes out, otherwise the server
+                // keeps re-delivering what the host just asked to ignore.
+                if (ignoreKeyRegistry.shouldDrop(frame)) {
+                    logger.debug({ tag: frame.tag, id: msgId, from: frame.attrs.from }, 'stanza dropped by ignoreKey');
+                    if (ignoredStanzaNeedsAck(frame.tag)) {
+                        sendNode(buildAckStanza(frame, undefined, authState.creds.me?.id)).catch(err => logger.error({ err, id: msgId }, 'failed to ack ignored stanza'));
+                    }
+                    return;
+                }
                 anyTriggered = ws.emit(`${DEF_TAG_PREFIX}${msgId}`, frame) || anyTriggered;
                 const l0 = frame.tag;
                 const l1 = frame.attrs || {};
@@ -1227,6 +1244,7 @@ export const makeSocket = (config) => {
             return authState.creds.me;
         },
         generateMessageTag,
+        ignoreKey: ignoreKeyRegistry.register,
         query,
         waitForMessage,
         waitForSocketOpen,

package/lib/Utils/a2ui.d.ts

@@ -0,0 +1,50 @@
+export type A2UIWidget = {
+    uuid: string;
+    data: string;
+    type: string;
+    fallback?: string;
+};
+export type A2UIBuildOptions = {
+    uuid?: string;
+    surfaceId?: string;
+    type?: string;
+    /** `false` emits a bare `{ components }` payload instead of the `createSurface` envelope. */
+    wrapped?: boolean;
+};
+export type A2UIChoice = {
+    label: string;
+    value: unknown;
+};
+export type A2UIListCardItem = {
+    title: string;
+    price?: string;
+    trailingLabel?: string;
+    assetId?: string;
+    assetType?: string;
+    emphasis?: string;
+};
+/** Every method registers a component and returns its id; container methods take those ids. */
+export declare class A2UI {
+    constructor(options?: { catalogId?: string; version?: string });
+    text(text: string, options?: { id?: string; variant?: string }): string;
+    image(url: string, options?: { id?: string; variant?: string; fit?: string }): string;
+    video(url: string, options?: { id?: string }): string;
+    checkbox(label: string, options?: { id?: string; value?: boolean }): string;
+    textField(label: string, options?: { id?: string; variant?: string }): string;
+    button(childId: string, options?: { id?: string; variant?: string; action?: any }): string;
+    card(childId: string, options?: { id?: string }): string;
+    column(children: string[], options?: { id?: string; justify?: string; align?: string }): string;
+    row(children: string[], options?: { id?: string }): string;
+    divider(options?: { id?: string }): string;
+    choicePicker(label: string, options: A2UIChoice[], extra?: {
+        id?: string;
+        variant?: string;
+        value?: unknown;
+        displayStyle?: string;
+        filterable?: boolean;
+    }): string;
+    root(children: string[]): this;
+    listCard(input: { title: string; items: A2UIListCardItem[]; fallbackText?: string; uuid?: string }): this;
+    build(options?: A2UIBuildOptions): A2UIWidget;
+}
+export declare const buildA2UIWidget: (a2ui: A2UI | A2UIWidget, options?: A2UIBuildOptions) => A2UIWidget;