fix: recover ciphertext messages via PLACEHOLDER_MESSAGE_RESEND (PDO type 4) (#182677)

* fix: recover ciphertext messages via PLACEHOLDER_MESSAGE_RESEND

Add automatic recovery for ciphertext messages using WhatsApp's built-in
PLACEHOLDER_MESSAGE_RESEND (PDO type 4). Override the AB test gate and
send recovery requests after a 5s grace period.

Also adds message_ciphertext_failed event at 15s and fixes incorrect
JSDoc on onAddMessageCiphertextEvent.

* fix: skip message event when ciphertext resolves to revoked

when a ciphertext message is revoked before it decrypts, WhatsApp's
internal revoke handler calls model.set({ type: 'revoked', ... }) on
the existing model in place. This triggers change:type on the ciphertext
model, which fired the deferred listener and emitted a spurious message
event with type === 'revoked'.

add an early return in the once('change:type') callback to skip
onaddmessageevent when the resolved type is revoked.

fixes wwebjs/whatsapp-web.js#201668

* fix: use handlePlaceholderMsgsSeen for ciphertext recovery

replace the manual sendPeerDataOperationRequest call with a direct call
to handlePlaceholderMsgsSeen. This adds subtype filtering (skips
bot_unavailable_fanout, hosted_unavailable_fanout,
view_once_unavailable_fanout), an age check (14 day limit via the
placeholder_message_resend_maximum_days_limit AB prop), and internal
deduplication so the same message doesn't get multiple PDO requests.

the true second argument is the 'is visible' flag the function expects.
since the gate override is already in place earlier in the evaluate
block, the function passes its own internal gate check and proceeds
normally.

suggested by @sofi-ans in review.

* fix: batch ciphertext PDO requests instead of sending per-message

handleplaceholdermsgsseen has built-in chunking (batches of 32 per PDO)
but calling it with [msg] per message from Msg.on('add') bypasses that.
collect ciphertext messages into a shared buffer and flush them in a
single call after the 5s grace period.

also guard the failTimer to skip if the message type already changed.

* fix: replace silent catch blocks with established patterns

address reviewer feedback - remove catch (_) { // comment } pattern:
- Gate override now uses injectToFunction (existing utility)
- PDO call uses direct require without silent error swallowing

* fix(types): add on() overload for message_ciphertext_failed event

* fix: skip unavailable fanout placeholders from ciphertext recovery

unavailable fanout placeholders (view_once, hosted, bot) are
unrecoverable - WhatsApp's handlePlaceholderMsgsSeen explicitly
skips them and won't resend via PDO. Without this check, the
15s failTimer fires message_ciphertext_failed as a false positive.

index.d.ts

@@ -546,6 +546,15 @@ declare namespace WAWebJS {
             ) => void,
         ): this;
 
+        /** Emitted when a ciphertext message failed to decrypt after recovery attempt */
+        on(
+            event: 'message_ciphertext_failed',
+            listener: (
+                /** The message that failed to decrypt */
+                message: Message,
+            ) => void,
+        ): this;
+
         /** Emitted when a message is deleted for everyone in the chat */
         on(
             event: 'message_revoke_everyone',
@@ -999,6 +1008,7 @@ declare namespace WAWebJS {
         CHAT_ARCHIVED = 'chat_archived',
         MESSAGE_RECEIVED = 'message',
         MESSAGE_CIPHERTEXT = 'message_ciphertext',
+        MESSAGE_CIPHERTEXT_FAILED = 'message_ciphertext_failed',
         MESSAGE_CREATE = 'message_create',
         MESSAGE_REVOKED_EVERYONE = 'message_revoke_everyone',
         MESSAGE_REVOKED_ME = 'message_revoke_me',

src/Client.js

@@ -980,7 +980,7 @@ class Client extends EventEmitter {
             'onAddMessageCiphertextEvent',
             (msg) => {
                 /**
-                 * Emitted when messages are edited
+                 * Emitted when a message is received as ciphertext (not yet decrypted)
                  * @event Client#message_ciphertext
                  * @param {Message} message
                  */
@@ -988,6 +988,22 @@ class Client extends EventEmitter {
             },
         );
 
+        await exposeFunctionIfAbsent(
+            this.pupPage,
+            'onCiphertextFailedEvent',
+            (msg) => {
+                /**
+                 * Emitted when a ciphertext message failed to decrypt after recovery attempt
+                 * @event Client#message_ciphertext_failed
+                 * @param {Message} message
+                 */
+                this.emit(
+                    Events.MESSAGE_CIPHERTEXT_FAILED,
+                    new Message(this, msg),
+                );
+            },
+        );
+
         await exposeFunctionIfAbsent(
             this.pupPage,
             'onPollVoteEvent',
@@ -1007,6 +1023,11 @@ class Client extends EventEmitter {
             const { Msg, Chat, WAWebCallCollection } =
                 window.require('WAWebCollections');
             const AppState = window.require('WAWebSocketModel').Socket;
+
+            // Enable placeholder message resend (recovery for ciphertext messages)
+            const gatingUtils = window.require('WAWebSyncGatingUtils');
+            gatingUtils.isPlaceholderMessageResendEnabled = () => true;
+
             Msg.on('change', (msg) => {
                 window.onChangeMessageEvent(window.WWebJS.getMessageModel(msg));
             });
@@ -1068,24 +1089,59 @@ class Client extends EventEmitter {
                     prevState,
                 );
             });
+            const pendingResend = new Set();
+            let resendFlush = null;
+
+            function requestResend(msg) {
+                pendingResend.add(msg);
+                if (resendFlush) return;
+                resendFlush = setTimeout(() => {
+                    resendFlush = null;
+                    const msgs = [...pendingResend];
+                    pendingResend.clear();
+                    if (msgs.length === 0) return;
+                    window
+                        .require(
+                            'WAWebNonMessageDataRequestPlaceholderMessageResendUtils',
+                        )
+                        .handlePlaceholderMsgsSeen(msgs, true);
+                }, 5000);
+            }
+
             Msg.on('add', (msg) => {
-                if (msg.isNewMsg) {
-                    if (msg.type === 'ciphertext') {
-                        // defer message event until ciphertext is resolved (type changed)
-                        msg.once('change:type', (_msg) =>
+                if (!msg.isNewMsg) return;
+
+                if (msg.type !== 'ciphertext') {
                     window.onAddMessageEvent(
-                                window.WWebJS.getMessageModel(_msg),
-                            ),
+                        window.WWebJS.getMessageModel(msg),
                     );
+                    return;
+                }
+
                 window.onAddMessageCiphertextEvent(
                     window.WWebJS.getMessageModel(msg),
                 );
-                    } else {
-                        window.onAddMessageEvent(
+
+                if (msg.subtype && msg.subtype.endsWith('_unavailable_fanout'))
+                    return;
+
+                requestResend(msg);
+
+                const failTimer = setTimeout(() => {
+                    if (msg.type !== 'ciphertext') return;
+                    window.onCiphertextFailedEvent(
                         window.WWebJS.getMessageModel(msg),
                     );
-                    }
-                }
+                }, 15000);
+
+                msg.once('change:type', (_msg) => {
+                    clearTimeout(failTimer);
+                    pendingResend.delete(_msg);
+                    if (_msg.type === 'revoked') return;
+                    window.onAddMessageEvent(
+                        window.WWebJS.getMessageModel(_msg),
+                    );
+                });
             });
             Chat.on('change:unreadCount', (chat) => {
                 window.onChatUnreadCountEvent(chat);

src/util/Constants.js

@@ -51,6 +51,7 @@ exports.Events = {
     CHAT_ARCHIVED: 'chat_archived',
     MESSAGE_RECEIVED: 'message',
     MESSAGE_CIPHERTEXT: 'message_ciphertext',
+    MESSAGE_CIPHERTEXT_FAILED: 'message_ciphertext_failed',
     MESSAGE_CREATE: 'message_create',
     MESSAGE_REVOKED_EVERYONE: 'message_revoke_everyone',
     MESSAGE_REVOKED_ME: 'message_revoke_me',