plogme 2.0.1 → 2.0.3

package/README.md

@@ -291,29 +291,36 @@ await sock.sendMessage(jid, {
 
 ### Albums
 
-Use at least two image or video items. Albums are sent as a parent message followed by separately encrypted media children.
+Albums now use the AIRich `GRID_IMAGE` unified-response layout. Provide at least two image URLs; the client receives one forwarded rich message containing preview, full-resolution, and dark-mode image primitives. The old `albumMessage` parent/child collection is no longer generated.
 
 ```js
 await sock.sendAlbumMessage(jid, [
-  { type: 'image', data: { url: './one.jpg' } },
-  { type: 'image', data: { url: './two.jpg' } }
-], {
-  caption: 'Trip photos'
-})
+  { type: 'image', data: { url: 'https://example.com/one.jpg', width: 1200, height: 800 } },
+  {
+    image: {
+      sourceUrl: 'https://example.com/two-preview.jpg',
+      imageHighResUrl: 'https://example.com/two.jpg',
+      darkModePreviewUrl: 'https://example.com/two-dark-preview.jpg',
+      darkModeHighResUrl: 'https://example.com/two-dark.jpg',
+      width: 1200,
+      height: 800
+    }
+  }
+])
 ```
 
-The general `sendMessage` album form is also supported:
+The general `sendMessage` album form delegates to the same GRID_IMAGE implementation:
 
 ```js
 await sock.sendMessage(jid, {
   album: [
-    { image: { url: './one.jpg' }, caption: 'First' },
-    { video: { url: './clip.mp4' }, caption: 'Second' }
+    { image: { url: 'https://example.com/one.jpg' } },
+    { image: { url: 'https://example.com/two.jpg' } }
   ]
 })
 ```
 
-Rich-response and bot-forwarded messages cannot be nested as album children. Send them as separate messages.
+GRID_IMAGE albums support images only. Video items and local `Buffer`/file inputs are rejected because this layout carries fetchable image URLs rather than uploaded album children.
 
 ## Interactive messages
 
@@ -475,6 +482,79 @@ await sock.sendRichAIResponse(jid, {
 
 `sendRichAIResponse` also accepts `list`, `codeBlock`, and `latex` content objects. For a pre-existing Meta AI response, `captureAndResendUnifiedResponse(jid, message, quoted)` captures and resends its unified response.
 
+### One unified Plogme response
+
+Use `sendPlogmeMessage` when a response may contain several optional sections. It combines every section that is present into one AIRich `unifiedResponse`; omitted sections are ignored, so callers do not need to construct a different payload for every result shape.
+
+```js
+const result = await sock.sendPlogmeMessage(jid, {
+  headerText: 'CODY AI result',
+  contentText: 'The deployment completed successfully.',
+
+  // Optional highlighted code section.
+  code: 'const status = "online"',
+  language: 'javascript',
+
+  // Optional table section. The first row is treated as the heading by default.
+  title: 'Service status',
+  table: [
+    ['Service', 'State'],
+    ['API', 'Online'],
+    ['Worker', 'Online']
+  ],
+  noHeading: false,
+
+  // Optional carousel/content items or reels.
+  items: [
+    { title: 'API documentation', url: 'https://example.com/docs' }
+  ],
+  reels: [
+    {
+      title: 'Release notes',
+      url: 'https://example.com/release.mp4',
+      thumbnail_url: 'https://example.com/release.jpg'
+    }
+  ],
+
+  // Optional inline media and LaTeX sections.
+  inlineImage: 'https://example.com/status.jpg',
+  imageText: 'Deployment status',
+  alignment: 2,
+  latex: [
+    { latexExpression: 'E = mc^2', url: 'https://example.com/equation.png' }
+  ],
+
+  // Optional sources/links, posts, products, or suggested prompts.
+  links: [
+    {
+      text: 'Open the deployment logs',
+      url: 'https://example.com/logs',
+      title: 'Deployment logs',
+      displayName: 'Logs'
+    }
+  ],
+  suggested: true,
+  footerText: 'Generated by CODY AI'
+}, undefined, {
+  // The compatibility relay is enabled by default. It sends the rich
+  // envelope normally, then uses WhatsApp's type-14 edit protocol so
+  // compatible clients render it immediately instead of showing Download.
+  renderRichResponse: true
+})
+
+console.log('Sent message:', result.key.id)
+```
+
+Every field in the example is optional. A minimal response is valid as well:
+
+```js
+await sock.sendPlogmeMessage(jid, {
+  contentText: 'Only the text section is available right now.'
+})
+```
+
+The compatibility edit can be disabled for a specific send with `{ renderRichResponse: false }`. This sends the generated rich envelope once without the follow-up edit.
+
 ## Rich menus, reels, and grids
 
 ### Original Gen4 rich menu

package/lib/Socket/messages-send.js

@@ -3,9 +3,9 @@ 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, buildLinkPreview, decryptMediaRetryData, DEF_MEDIA_HOST, delay, encodeNewsletterMessage, encodeSignedDeviceIdentity, encodeWAMessage, encryptMediaRetryRequest, extractDeviceJids, extractImageThumb, generateMessageIDV2, generateParticipantHashV2, generateWAMessage, generateWAMessageFromContent, getStatusCodeForMediaRetry, makeWhatsAppFlowButton, getUrlFromDirectPath, getWAUploadToServer, hasValidAlbumMedia, MessageRetryManager, normalizeMessageContent, parseAndInjectE2ESessions, prepareWAMessageMedia, shouldIncludeBizBinaryNode, unixTimestampSeconds } from '../Utils/index.js';
+import { aggregateMessageKeysNotFromMe, assertMediaContent, assertMeId, bindWaitForEvent, buildLinkPreview, decryptMediaRetryData, DEF_MEDIA_HOST, delay, encodeNewsletterMessage, encodeSignedDeviceIdentity, encodeWAMessage, encryptMediaRetryRequest, extractDeviceJids, extractImageThumb, generateMessageIDV2, generateParticipantHashV2, generateWAMessage, generateWAMessageFromContent, getStatusCodeForMediaRetry, makeWhatsAppFlowButton, getUrlFromDirectPath, getWAUploadToServer, MessageRetryManager, normalizeMessageContent, parseAndInjectE2ESessions, prepareWAMessageMedia, shouldIncludeBizBinaryNode, unixTimestampSeconds } from '../Utils/index.js';
 import { getUrlInfo } from '../Utils/link-preview.js';
-import { prepareRichMenuMessage, prepareRichResponseMessage, prepareRichGenerationMessage, prepareCopyToClipboardMessage, prepareRichTextMessage, prepareRichQuoteMessage, prepareRichImageMessage, prepareRichLinkMessage, prepareHtmlMessage, prepareRichHtmlMessage } from '../Utils/rich-message-utils.js';
+import { prepareRichMenuMessage, prepareRichResponseMessage, prepareRichGenerationMessage, prepareCopyToClipboardMessage, prepareRichTextMessage, prepareRichQuoteMessage, prepareRichImageMessage, prepareRichLinkMessage, prepareGridImageMessage, prepareHtmlMessage, prepareRichHtmlMessage, attachBotVerificationProofs, hasVerifiableProofs } from '../Utils/rich-message-utils.js';
 import { generateSlotMachineHtml } from '../Utils/games/slot-machine.js';
 import { generateMiniAppHtml } from '../Utils/games/miniapp.js';
 import { generateWebsitePreviewHtml, generateLinkPreviewHtml } from '../Utils/games/website-preview.js';
@@ -555,7 +555,18 @@ export const makeMessagesSocket = (config) => {
             };
         }
         const applyForwarded = m => {
+            // Auto-inject trusted verification proofs configured once on the socket
+            // (config.metaAiRendering.verificationMetadata). Per-message proofs win:
+            // an envelope that already carries verificationMetadata is left untouched.
+            // The second target covers edited rich envelopes (protocolMessage.editedMessage,
+            // used by updateRichGeneration) so an in-place rich update keeps its proofs too.
+            const edited = m?.botForwardedMessage?.message?.protocolMessage?.editedMessage;
             const rich = m?.botForwardedMessage?.message?.richResponseMessage || m?.richResponseMessage;
+            if (!rich && !edited) return m;
+            if (hasVerifiableProofs(config?.metaAiRendering?.verificationMetadata)) {
+                attachBotVerificationProofs(m, config.metaAiRendering.verificationMetadata);
+                attachBotVerificationProofs(edited, config.metaAiRendering.verificationMetadata);
+            }
             if (!rich) return m;
             rich.contextInfo = { ...rich.contextInfo, isForwarded: true, forwardOrigin: 4 };
             return m.botForwardedMessage ? m : { botForwardedMessage: { message: m } };
@@ -1022,6 +1033,53 @@ export const makeMessagesSocket = (config) => {
         return msgId;
     };
 
+    /**
+     * Relay a rich envelope and then replay it as a type-14 edit. Some
+     * WhatsApp clients otherwise show a Download prompt before rendering the
+     * AIRich unifiedResponse. The edit is only applied to bot-forwarded rich
+     * envelopes, so ordinary messages are never duplicated accidentally.
+     * Set renderRichResponse: false for callers that explicitly do not want
+     * the compatibility replay.
+     */
+    const relayRichMessage = async (jid, fullMsg, options = {}) => {
+        const relayOptions = {
+            messageId: fullMsg.key.id,
+            useCachedGroupMetadata: options.useCachedGroupMetadata,
+            statusJidList: options.statusJidList,
+            ...options.relayOptions,
+        };
+        await relayMessage(jid, fullMsg.message, relayOptions);
+
+        const richEnvelope = fullMsg.message?.botForwardedMessage?.message?.richResponseMessage;
+        if (options.renderRichResponse !== false && richEnvelope) {
+            const editContent = proto.Message.fromObject({
+                botForwardedMessage: {
+                    message: {
+                        protocolMessage: {
+                            key: {
+                                remoteJid: jid,
+                                fromMe: true,
+                                id: fullMsg.key.id,
+                            },
+                            type: proto.Message.ProtocolMessage.Type.MESSAGE_EDIT,
+                            editedMessage: fullMsg.message,
+                        },
+                    },
+                },
+            });
+            const editMessage = generateWAMessageFromContent(jid, editContent, {
+                logger,
+                userJid: authState.creds.me?.id,
+                messageId: generateMessageIDV2(authState.creds.me?.id || jid),
+            });
+            await relayMessage(jid, editMessage.message, {
+                ...relayOptions,
+                messageId: editMessage.key.id,
+            });
+        }
+        return fullMsg;
+    };
+
     const getMessageType = (message) => {
         if (!message)
             return 'text';
@@ -1380,11 +1438,7 @@ export const makeMessagesSocket = (config) => {
                 quoted,
                 ...options
             });
-            await relayMessage(jid, generated.message, {
-                messageId: generated.key.id,
-                useCachedGroupMetadata: options.useCachedGroupMetadata,
-                statusJidList: options.statusJidList
-            });
+            await relayRichMessage(jid, generated, options);
             return { ...generated, messageId: generated.key.id };
         },
         /**
@@ -1397,9 +1451,15 @@ export const makeMessagesSocket = (config) => {
                 responseId: options.responseId,
                 forwarded: options.forwarded !== false
             });
-            const messageId = generateMessageIDV2(jid);
-            await relayMessage(jid, generated.message, { messageId, quoted });
-            return { ...generated, messageId };
+            const fullMsg = generateWAMessageFromContent(jid, generated.message, {
+                logger,
+                userJid: authState.creds.me?.id,
+                messageId: options.messageId || generated.messageId || generateMessageIDV2(jid),
+                quoted,
+                ...options,
+            });
+            await relayRichMessage(jid, fullMsg, options);
+            return { ...generated, messageId: fullMsg.key.id };
         },
         /**
          * Replace the generation primitive in an existing rich response.
@@ -1465,14 +1525,47 @@ export const makeMessagesSocket = (config) => {
                 quoted,
                 ...options
             });
-            await relayMessage(jid, fullMsg.message, {
-                messageId: fullMsg.key.id,
-                useCachedGroupMetadata: options.useCachedGroupMetadata,
-                statusJidList: options.statusJidList
+            await relayRichMessage(jid, fullMsg, options);
+            return fullMsg;
+        },
+        /**
+         * Send one tolerant AIRich/unified response containing every supported
+         * section present in `content`. Missing sections are intentionally
+         * ignored by prepareRichResponseMessage instead of causing a partial
+         * response to fail. This is the stable entry point for Plogme/CODY
+         * callers that may receive optional text, links, media, products,
+         * reels, tables, code, latex, or suggestion data.
+         */
+        sendPlogmeMessage: async (jid, content = {}, quoted, options = {}) => {
+            if (!jid) throw new Boom('sendPlogmeMessage requires a target JID', { statusCode: 400 });
+            if (!content || typeof content !== 'object' || Array.isArray(content)) {
+                throw new Boom('sendPlogmeMessage content must be an object', { statusCode: 400 });
+            }
+
+            const wrapped = prepareRichResponseMessage({
+                ...content,
+                // Avoid silently appending the library donation link to a
+                // unified response unless the caller explicitly opts in.
+                noDonation: options.noDonation ?? true,
             });
+            const fullMsg = generateWAMessageFromContent(jid, wrapped, {
+                logger,
+                userJid: authState.creds.me?.id,
+                messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id || jid),
+                quoted,
+                ...options,
+            });
+
+            await relayRichMessage(jid, fullMsg, options);
+
+            if (config.emitOwnEvents) {
+                process.nextTick(async () => {
+                    await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
+                });
+            }
             return fullMsg;
         },
-        captureAndResendUnifiedResponse: async (jid, metaAiMsg, quoted) => {
+        captureAndResendUnifiedResponse: async (jid, metaAiMsg, quoted, options = {}) => {
             const captured = captureUnifiedResponse(metaAiMsg);
             if (!captured) {
                 throw new Boom('captureAndResendUnifiedResponse: message contains no unifiedResponse data');
@@ -1484,11 +1577,7 @@ export const makeMessagesSocket = (config) => {
                 messageId: generated.messageId || generateMessageIDV2(jid),
                 quoted
             });
-            await relayMessage(jid, fullMsg.message, {
-                messageId: fullMsg.key.id,
-                useCachedGroupMetadata: options?.useCachedGroupMetadata,
-                statusJidList: options?.statusJidList
-            });
+            await relayRichMessage(jid, fullMsg, options);
             return fullMsg;
         },
         updateMediaMessage: async (message) => {
@@ -2028,6 +2117,9 @@ export const makeMessagesSocket = (config) => {
             }
             // ── NORMAL MESSAGE HANDLING ──
             else {
+                if ('album' in content) {
+                    return socket.sendAlbumMessage(jid, content.album, options);
+                }
                 const fullMsg = await generateWAMessage(jid, content, {
                     logger,
                     userJid,
@@ -2116,13 +2208,6 @@ export const makeMessagesSocket = (config) => {
                     delete content.ai;
                 }
 
-                if ('album' in content) {
-                    if (!Array.isArray(content.album) || content.album.length < 2) {
-                        throw new Boom('Album requires at least two image or video items', { statusCode: 400 });
-                    }
-                    fullMsg.message.messageContextInfo ||= {};
-                    fullMsg.message.messageContextInfo.messageSecret ||= randomBytes(32);
-                }
                 await relayMessage(jid, fullMsg.message, {
                     messageId: fullMsg.key.id,
                     useCachedGroupMetadata: options.useCachedGroupMetadata,
@@ -2139,55 +2224,6 @@ export const makeMessagesSocket = (config) => {
                     });
                 }
 
-                if ('album' in content) {
-                    const { delayMs = 1500 } = options;
-                    for (const [messageIndex, albumMedia] of content.album.entries()) {
-                        // Give the album collection stanza time to register before
-                        // its associated media children are relayed. This mirrors
-                        // the ordering used by WhatsApp clients and avoids the
-                        // children being treated as unrelated media messages.
-                        await delay(delayMs);
-                        const albumMsg = await generateWAMessage(jid, albumMedia, {
-                            logger,
-                            userJid,
-                            upload: waUploadToServer,
-                            mediaCache: config.mediaCache,
-                            options: config.options,
-                            ...options,
-                            messageId: generateMessageIDV2(userJid)
-                        });
-                        if (!hasValidAlbumMedia(normalizeMessageContent(albumMsg.message))) {
-                            throw new Boom('Invalid message type for album', { statusCode: 400 });
-                        }
-                        albumMsg.message.messageContextInfo ||= {};
-                        // WhatsApp expects an encrypted context secret on each album
-                        // child. Without it, clients may show the album as an
-                        // unsupported message or fail to group the media together.
-                        albumMsg.message.messageContextInfo.messageSecret ||= randomBytes(32);
-                        albumMsg.message.messageContextInfo.messageAssociation = {
-                            parentMessageKey: fullMsg.key,
-                            // WhatsApp album child messages use association type 1.
-                            // The generated MEDIA_ALBUM enum value (63) is a message
-                            // category, not the child-association wire value.
-                            associationType: 1,
-                            messageIndex
-                        };
-                        await relayMessage(jid, albumMsg.message, {
-                            messageId: albumMsg.key.id,
-                            useCachedGroupMetadata: options.useCachedGroupMetadata,
-                            addBizAttributes: isNeedBizAttrs,
-                            statusJidList: options.statusJidList,
-                            additionalAttributes,
-                            additionalNodes
-                        });
-                        if (config.emitOwnEvents) {
-                            process.nextTick(async () => {
-                                await messageMutex.mutex(() => upsertMessage(albumMsg, 'append'));
-                            });
-                        }
-                    }
-                }
-
                 return fullMsg;
             }
         }
@@ -2205,11 +2241,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options,
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList,
-        });
+        await relayRichMessage(jid, fullMsg, options);
         if (config.emitOwnEvents) {
             process.nextTick(async () => {
                 await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
@@ -2230,11 +2262,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options,
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList,
-        });
+        await relayRichMessage(jid, fullMsg, options);
         if (config.emitOwnEvents) {
             process.nextTick(async () => {
                 await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
@@ -2248,7 +2276,7 @@ export const makeMessagesSocket = (config) => {
         if (!content.copyText) throw new Boom('sendRichTextCopy requires copyText content', { statusCode: 400 });
         const wrapped = prepareRichQuoteMessage(content);
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /** Sends Markdown text containing blockquotes in a forwarded GenAI rich response. */
@@ -2256,7 +2284,7 @@ export const makeMessagesSocket = (config) => {
         if (!jid) throw new Boom('sendMarkdownQuote requires a target JID', { statusCode: 400 });
         const wrapped = prepareRichQuoteMessage(content);
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /** Sends Markdown blockquotes followed by a GenAI COPY_TO_CLIPBOARD action. */
@@ -2265,7 +2293,7 @@ export const makeMessagesSocket = (config) => {
         if (!content.copyText) throw new Boom('sendQuoteCopy requires copyText content', { statusCode: 400 });
         const wrapped = prepareRichQuoteMessage(content);
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /**
@@ -2280,11 +2308,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options,
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList,
-        });
+        await relayRichMessage(jid, fullMsg, options);
         if (config.emitOwnEvents) {
             process.nextTick(async () => {
                 await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
@@ -2304,11 +2328,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options,
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList,
-        });
+        await relayRichMessage(jid, fullMsg, options);
         if (config.emitOwnEvents) {
             process.nextTick(async () => {
                 await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
@@ -2325,11 +2345,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options,
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList,
-        });
+        await relayRichMessage(jid, fullMsg, options);
         if (config.emitOwnEvents) {
             process.nextTick(async () => {
                 await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
@@ -2346,7 +2362,7 @@ export const makeMessagesSocket = (config) => {
             botForwardedMessage: { message: { richResponseMessage: { messageType: 1, submessages: [{ messageType: 2, messageText: text }], contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid }, forwardOrigin: 4 } } } }
         };
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /** Sends a rich response with experimental BotCommandMetadata. */
@@ -2355,7 +2371,7 @@ export const makeMessagesSocket = (config) => {
         const { text = 'Bot command test', commandName = '', commandDescription = '', commandPrompt = '', botJid = '867051314767696@bot' } = content;
         const wrapped = buildBotRichResponse({ text, botJid, botMetadata: { commandMetadata: { commandName, commandDescription, commandPrompt } } });
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /** Sends a planning/execution-plan rich response with WAProto capabilities. */
@@ -2378,7 +2394,7 @@ export const makeMessagesSocket = (config) => {
             ]
         });
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     /** Sends a rich response with experimental BotResolvedToolCallMetadata. */
@@ -2397,7 +2413,7 @@ export const makeMessagesSocket = (config) => {
             }
         });
         const fullMsg = await generateWAMessageFromContent(jid, wrapped, { logger, userJid: authState.creds.me?.id, messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id), ...options });
-        await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
     socket.sendStatus = async (content, options = {}) => {
@@ -2600,25 +2616,53 @@ export const makeMessagesSocket = (config) => {
 
 
     /**
-     * Sends an experimental WhatsApp album. The parent album header and each
-     * image/video child are relayed separately and associated by parent key.
-     * Accepts [{ image: ... }, { video: ... }] or [{ type: 'image', data: ... }].
+     * Sends an AIRich GRID_IMAGE album. Unlike the legacy albumMessage
+     * collection, this is one forwarded unified-response message containing
+     * the requested image primitives.
      */
     socket.sendAlbumMessage = async (jid, medias = [], options = {}) => {
         if (!jid) throw new Boom('sendAlbumMessage requires a target JID', { statusCode: 400 });
         if (!Array.isArray(medias) || medias.length < 2) {
             throw new Boom('sendAlbumMessage requires at least two media items', { statusCode: 400 });
         }
-        const album = medias.map((media, index) => {
-            const normalized = media?.type && media?.data
-                ? { [media.type]: media.data }
-                : { ...media };
-            if (index === 0 && options.caption && !normalized.caption) {
-                normalized.caption = options.caption;
+        const imageUrls = medias.map((media) => {
+            const raw = media?.type && media?.data ? media.data : (media?.image ?? media);
+            if (media?.video || media?.type === 'video') {
+                throw new Boom('GRID_IMAGE albums support images only', { statusCode: 400 });
             }
-            return normalized;
+            const sourceUrl = typeof raw === 'string' ? raw : (raw?.sourceUrl || raw?.url || '');
+            if (!sourceUrl) {
+                throw new Boom('Each GRID_IMAGE album item requires an image URL', { statusCode: 400 });
+            }
+            return {
+                sourceUrl,
+                imagePreviewUrl: raw?.imagePreviewUrl || raw?.previewUrl || sourceUrl,
+                imageHighResUrl: raw?.imageHighResUrl || raw?.highResUrl || raw?.url || sourceUrl,
+                darkModePreviewUrl: raw?.darkModePreviewUrl,
+                darkModeHighResUrl: raw?.darkModeHighResUrl,
+                width: raw?.width || media?.width || 600,
+                height: raw?.height || media?.height || 400,
+                darkWidth: raw?.darkWidth || media?.darkWidth,
+                darkHeight: raw?.darkHeight || media?.darkHeight
+            };
+        });
+        const wrapped = prepareGridImageMessage({
+            imageUrls,
+            verificationMetadata: options.verificationMetadata
+        });
+        const fullMsg = generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id || jid),
+            ...options
         });
-        return socket.sendMessage(jid, { album }, options);
+        await relayRichMessage(jid, fullMsg, options);
+        if (config.emitOwnEvents) {
+            process.nextTick(async () => {
+                await messageMutex.mutex(() => upsertMessage(fullMsg, 'append'));
+            });
+        }
+        return fullMsg;
     };
 
 
@@ -2677,11 +2721,7 @@ export const makeMessagesSocket = (config) => {
             messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
             ...options
         });
-        await relayMessage(jid, fullMsg.message, {
-            messageId: fullMsg.key.id,
-            useCachedGroupMetadata: options.useCachedGroupMetadata,
-            statusJidList: options.statusJidList
-        });
+        await relayRichMessage(jid, fullMsg, options);
         return fullMsg;
     };
 

package/lib/Utils/bot-planning-replay.js

@@ -24,7 +24,6 @@ import {
     buildPlainPlaceholder,
     PlanningStepStatus
 } from './meta-compositing.js';
-import { botMetadataSignature, botMetadataCertificate } from './rich-message-utils.js';
 import { BOT_RENDERING_CONFIG_METADATA } from '../Defaults/index.js';
 import { delay } from './generics.js';
 

package/lib/Utils/messages.js

@@ -1061,30 +1061,8 @@ export const generateWAMessageContent = async (message, options) => {
         };
         delete m.orderMessage.orderText;
     }
-    // Lia@Changes 31-01-26 --- Add support for album messages
     else if (hasNonNullishProperty(message, 'album')) {
-        if (!Array.isArray(message.album)) {
-            throw new Boom('Invalid album type. Expected an array.', { statusCode: 400 });
-        }
-        let videoCount = 0;
-        for (let i = 0; i < message.album.length; i++) {
-            if (message.album[i].video)
-                videoCount++;
-        }
-        ;
-        let imageCount = 0;
-        for (let i = 0; i < message.album.length; i++) {
-            if (message.album[i].image)
-                imageCount++;
-        }
-        ;
-        if ((videoCount + imageCount) < 2) {
-            throw new Boom('Minimum provide 2 media to upload album message', { statusCode: 400 });
-        }
-        m.albumMessage = {
-            expectedImageCount: imageCount,
-            expectedVideoCount: videoCount
-        };
+        throw new Boom('Legacy albumMessage is removed; use socket.sendAlbumMessage() for an AIRich GRID_IMAGE album', { statusCode: 400 });
     }
     else if (hasNonNullishProperty(message, 'sharePhoneNumber')) {
         m.protocolMessage = {

package/lib/Utils/rich-message-utils.js

@@ -5,7 +5,7 @@
  * If you use or copy this code, please credit my name or project. AND DO NOT CHANGE THIS NOTE
  */
 import { getRandomValues, randomUUID, randomBytes } from 'crypto';
-import { DONATE_URL, LEXER_REGEX } from '../Defaults/index.js';
+import { BOT_RENDERING_CONFIG_METADATA, DONATE_URL, LEXER_REGEX } from '../Defaults/index.js';
 import { LANGUAGE_KEYWORDS } from '../WABinary/constants.js';
 import { CodeHighlightType, RichSubMessageType } from '../Types/RichType.js';
 import { proto } from '../../WAProto/index.js';
@@ -62,6 +62,30 @@ export const toUnified = (submessages, uuid) => ({
                     }
                 };
             }
+            case RichSubMessageType.GRID_IMAGE: {
+                const imageUrls = submessage.gridImageMetadata?.imageUrls || [];
+                if (!imageUrls.length) return null;
+                const expiration = String(Date.now() + 30 * 24 * 60 * 60 * 1000);
+                const primitives = imageUrls.map(img => {
+                    const previewUrl = img.imagePreviewUrl || img.sourceUrl || '';
+                    const fullUrl = img.imageHighResUrl || img.imagePreviewUrl || img.sourceUrl || '';
+                    const width = img.width || 600;
+                    const height = img.height || 400;
+                    const darkPreviewUrl = img.darkModePreviewUrl || previewUrl;
+                    const darkFullUrl = img.darkModeHighResUrl || img.darkModePreviewUrl || fullUrl;
+                    const darkWidth = img.darkWidth || width;
+                    const darkHeight = img.darkHeight || height;
+                    return {
+                        preview_image: { url: previewUrl, mime_type: 'image/png', expiration_timestamp_ms: expiration, width, height },
+                        full_image: { url: fullUrl, mime_type: 'image/png', expiration_timestamp_ms: expiration, width, height },
+                        dark_mode_preview_image: { url: darkPreviewUrl, mime_type: 'image/png', expiration_timestamp_ms: expiration, width: darkWidth, height: darkHeight },
+                        dark_mode_full_image: { url: darkFullUrl, mime_type: 'image/png', expiration_timestamp_ms: expiration, width: darkWidth, height: darkHeight },
+                        asset_query_status: 'FETCHED',
+                        __typename: 'GenAIImagePrimitive'
+                    };
+                });
+                return { view_model: { primitives, __typename: 'GenAIGridLayoutViewModel' } };
+            }
             case RichSubMessageType.CONTENT_ITEMS: {
                 const items = submessage.contentItemsMetadata?.itemsMetadata || [];
                 const primitives = items.map((item) => {
@@ -196,7 +220,8 @@ export const prepareRichGenerationMessage = ({
     estimatedMs,
     itemId = `imagine_${randomUUID()}`,
     responseId = randomUUID(),
-    forwarded = true
+    forwarded = true,
+    verificationMetadata
 } = {}) => {
     const sections = [];
     if (text) {
@@ -210,7 +235,7 @@ export const prepareRichGenerationMessage = ({
         unifiedResponse: { data: Buffer.from(JSON.stringify({ response_id: responseId, sections })) },
         contextInfo: forwarded ? { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' }, forwardOrigin: 4 } : {}
     });
-    const message = wrapToBotForwardedMessage(richResponseMessage);
+    const message = wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
     message.messageContextInfo = message.messageContextInfo || {};
     message.messageContextInfo.botMetadata = {
         ...(message.messageContextInfo.botMetadata || {}),
@@ -220,56 +245,72 @@ export const prepareRichGenerationMessage = ({
 };
 
 // Lia@Note 17-04-26 --- WIP
+/**
+ * A preview-media descriptor is only meaningful when the client can locate and
+ * decrypt the media. A descriptor without a key, hash and direct path describes
+ * media that cannot be fetched, so it is dropped rather than shipped
+ * present-but-empty (which is what previously produced `''` crypto fields and a
+ * hard-coded `image/jpeg` mimetype on every reel).
+ *
+ * Callers that upload real media supply it as `previewMedia` on the reel item or
+ * LaTeX expression: `{ fileSha256, mediaKey, fileEncSha256, directPath, mimetype?, mediaKeyTimestamp?, mediaId? }`.
+ */
+const normalizePreviewMedia = (media) => {
+    if (!media || typeof media !== 'object') return null;
+    const { fileSha256, mediaKey, fileEncSha256, directPath, mimetype, mediaKeyTimestamp } = media;
+    if (!fileSha256 || !mediaKey || !fileEncSha256 || !directPath) return null;
+    return {
+        fileSha256,
+        mediaKey,
+        fileEncSha256,
+        directPath,
+        mediaKeyTimestamp: mediaKeyTimestamp ?? unixTimestampSeconds(),
+        mimetype: mimetype || 'image/jpeg'
+    };
+};
+
 export const buildAdditionalBotMetadataContext = (submessages) => {
     const sources = [];
     const mediaDetailsMetadataList = [];
-    for (let i = 0; i < submessages.length; i++) {
-        const submessage = submessages[i];
+    for (const submessage of submessages) {
         switch (submessage.messageType) {
             case RichSubMessageType.CONTENT_ITEMS: {
                 const itemsMetadata = submessage.contentItemsMetadata?.itemsMetadata || [];
-                for (let n = 0; n < itemsMetadata.length; n++) {
-                    const reelItem = itemsMetadata[n]?.reelItem || itemsMetadata[n] || {};
+                for (const item of itemsMetadata) {
+                    const reelItem = item?.reelItem || item || {};
                     sources.push({
                         provider: 0,
                         thumbnailCdnUrl: reelItem.thumbnailUrl || reelItem.thumbnail_url || '',
                         sourceProviderUrl: reelItem.videoUrl || reelItem.reels_url || reelItem.url || '',
                         sourceQuery: '',
                         faviconCdnUrl: reelItem.profileIconUrl || reelItem.avatar_url || '',
-                        citationNumber: i + 1,
+                        // 1-based source ordinal, not the submessage index.
+                        citationNumber: sources.length + 1,
                         sourceTitle: reelItem.title || reelItem.reels_title || reelItem.creator || ''
                     });
-                    mediaDetailsMetadataList.push({
-                        id: randomBytes(32).toString('hex'),
-                        previewMedia: {
-                            fileSha256: '',
-                            mediaKey: '',
-                            fileEncSha256: '',
-                            directPath: '',
-                            mediaKeyTimestamp: unixTimestampSeconds(),
-                            mimetype: 'image/jpeg'
-                        }
-                    });
+                    const previewMedia = normalizePreviewMedia(reelItem.previewMedia);
+                    if (previewMedia) {
+                        mediaDetailsMetadataList.push({
+                            id: reelItem.mediaId || reelItem.previewMedia?.mediaId || randomBytes(32).toString('hex'),
+                            previewMedia
+                        });
+                    }
                 }
                 break;
             }
-            case RichSubMessageType.LATEX:
-                const expressions = submessage.latexMetadata.expressions;
-                for (let n = 0; n < expressions.length; n++) {
-                    const expression = expressions[n];
-                    mediaDetailsMetadataList.push({
-                        id: randomBytes(32).toString('hex'),
-                        previewMedia: {
-                            fileSha256: '',
-                            mediaKey: '',
-                            fileEncSha256: '',
-                            directPath: '',
-                            mediaKeyTimestamp: unixTimestampSeconds(),
-                            mimetype: 'image/jpeg'
-                        }
-                    });
+            case RichSubMessageType.LATEX: {
+                const expressions = submessage.latexMetadata?.expressions || [];
+                for (const expression of expressions) {
+                    const previewMedia = normalizePreviewMedia(expression?.previewMedia);
+                    if (previewMedia) {
+                        mediaDetailsMetadataList.push({
+                            id: expression.mediaId || expression.previewMedia?.mediaId || randomBytes(32).toString('hex'),
+                            previewMedia
+                        });
+                    }
                 }
                 break;
+            }
         }
     }
     return { sources, mediaDetailsMetadataList };
@@ -336,7 +377,7 @@ const richMenuButton = (button, toast = '') => {
  * buttonsMessage/nativeFlowMessage payload.
  */
 export const prepareRichMenuMessage = (content = {}) => {
-    const { header = {}, body = {}, footer = {} } = content || {};
+    const { header = {}, body = {}, footer = {}, verificationMetadata } = content || {};
     const sections = [];
     const title = header?.title || '';
     if (title) {
@@ -418,7 +459,7 @@ export const prepareRichMenuMessage = (content = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 /**
@@ -432,7 +473,7 @@ export const prepareRichMenuMessage = (content = {}) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareCopyToClipboardMessage = (options = {}) => {
-    const { text = '', label, alignment = 'END' } = options;
+    const { text = '', label, alignment = 'END', verificationMetadata } = options;
     const displayText = label || text;
     const sections = [
         {
@@ -458,7 +499,7 @@ export const prepareCopyToClipboardMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 /**
@@ -470,7 +511,7 @@ export const prepareCopyToClipboardMessage = (options = {}) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareRichTextMessage = (options = {}) => {
-    const { text = '' } = options;
+    const { text = '', verificationMetadata } = options;
     const sections = [
         {
             __typename: 'GenAIUnifiedResponseSection',
@@ -491,12 +532,12 @@ export const prepareRichTextMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 /** Builds Markdown text with an optional GenAI COPY_TO_CLIPBOARD action section. */
 export const prepareRichQuoteMessage = (options = {}) => {
-    const { text = '', copyText, copyLabel = copyText, alignment = 'END' } = options;
+    const { text = '', copyText, copyLabel = copyText, alignment = 'END', verificationMetadata } = options;
     const sections = [{
         __typename: 'GenAIUnifiedResponseSection',
         view_model: {
@@ -522,7 +563,7 @@ export const prepareRichQuoteMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 /**
@@ -535,7 +576,7 @@ export const prepareRichQuoteMessage = (options = {}) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareRichImageMessage = (options = {}) => {
-    const { url = '', mimeType = 'image/png' } = options;
+    const { url = '', mimeType = 'image/png', verificationMetadata } = options;
     const media = {
         __typename: 'GenAIMediaItem',
         mime_type: mimeType,
@@ -562,7 +603,7 @@ export const prepareRichImageMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 
@@ -575,7 +616,7 @@ export const prepareRichImageMessage = (options = {}) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareRichLinkMessage = (options = {}) => {
-    const { links = [], text: fallbackText } = options;
+    const { links = [], text: fallbackText, verificationMetadata } = options;
     const sections = [];
     const allInlineEntities = [];
     let combinedText = '';
@@ -629,11 +670,35 @@ export const prepareRichLinkMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
+};
+
+/** Build an AIRich GRID_IMAGE album instead of the legacy albumMessage collection. */
+export const prepareGridImageMessage = ({ imageUrls = [], verificationMetadata } = {}) => {
+    if (!Array.isArray(imageUrls) || imageUrls.length < 2) {
+        throw new Error('GRID_IMAGE album requires at least two images');
+    }
+    const submessages = [{
+        messageType: RichSubMessageType.GRID_IMAGE,
+        gridImageMetadata: { imageUrls }
+    }];
+    const unified = toUnified(submessages, randomUUID());
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        submessages,
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
+        contextInfo: {
+            isForwarded: true,
+            forwardingScore: 1,
+            forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' },
+            forwardOrigin: 4
+        }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 export const prepareRichResponseMessage = (content) => {
-    const { alignment, code, contentText, disclaimerText, footerText, headerText, imageText, inlineImage, inlineVideo, items, language, latex, links, noDonation, noHeading, posts, products, reels, sources: sourceInputs, suggested, richResponse, table, tapLinkUrl, title } = content;
+    const { alignment, code, contentText, disclaimerText, footerText, headerText, imageText, inlineImage, inlineVideo, items, language, latex, links, noDonation, noHeading, posts, products, reels, sources: sourceInputs, suggested, richResponse, table, tapLinkUrl, title, verificationMetadata } = content;
     let submessages = [];
     if (Array.isArray(richResponse)) {
         submessages = richResponse.map((submessage) => {
@@ -753,7 +818,10 @@ export const prepareRichResponseMessage = (content) => {
             reelSource: reel?.reelSource || reel?.reel_source || 'IG',
             isVerified: !!(reel?.isVerified ?? reel?.is_verified)
         } })) : [];
-        const resolvedItems = items || reelItems;
+        const resolvedItems = [
+            ...(Array.isArray(items) ? items : []),
+            ...reelItems
+        ];
         if (resolvedItems?.length) {
             submessages.push({
                 messageType: RichSubMessageType.CONTENT_ITEMS,
@@ -879,7 +947,7 @@ export const prepareRichResponseMessage = (content) => {
             forwardOrigin: 4
         }
     });
-    const message = wrapToBotForwardedMessage(richResponseMessage);
+    const message = wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
     const botMetadata = message.messageContextInfo.botMetadata;
     // Lia@Note 13-05-26 --- Add disclaimer text on richResponseMessage
     if (disclaimerText) {
@@ -898,6 +966,11 @@ export const prepareRichResponseMessage = (content) => {
     return message;
 };
 // Lia@Note 17-04-26 --- signature and certificateChain for proofs[] field
+/**
+ * @deprecated Generates random bytes that verify against nothing. Kept only for
+ * experimental tooling; the library no longer attaches generated proofs to
+ * messages. Pass real proofs through the `verificationMetadata` option instead.
+ */
 export const botMetadataSignature = () => {
     const signature = new Uint8Array(64);
     getRandomValues(signature);
@@ -923,7 +996,7 @@ export const botMetadataCertificate = (length = 685) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareHtmlMessage = (options = {}) => {
-    const { html = '', trustedSources = [] } = options;
+    const { html = '', trustedSources = [], verificationMetadata } = options;
     const sections = [
         {
             __typename: 'GenAIUnifiedResponseSection',
@@ -944,7 +1017,7 @@ export const prepareHtmlMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 },
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
 /**
@@ -959,7 +1032,8 @@ export const prepareRichHtmlMessage = (options = {}) => {
         url = '',
         title = 'Preview',
         tabHeader = 'HTML',
-        tabs
+        tabs,
+        verificationMetadata
     } = options;
     const tabItems = Array.isArray(tabs) && tabs.length
         ? tabs
@@ -1003,26 +1077,55 @@ export const prepareRichHtmlMessage = (options = {}) => {
         unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
         contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
     });
-    return wrapToBotForwardedMessage(richResponseMessage);
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
+};
+
+/**
+ * Proofs are forwarded only when the caller supplies real, verifiable proofs.
+ * The library never fabricates a certificate chain or signature: an unverifiable
+ * proof is worse than none, because it asserts provenance the caller cannot back.
+ */
+export const hasVerifiableProofs = (verificationMetadata) =>
+    Array.isArray(verificationMetadata?.proofs) && verificationMetadata.proofs.length > 0;
+
+/**
+ * Attach trusted verification proofs to an already-built rich envelope.
+ *
+ * Pure, null-safe, and idempotent: returns the envelope untouched when no
+ * verifiable proofs are supplied or when the envelope carries no botMetadata.
+ * Used by the send pipeline (`relayMessage`) to auto-inject proofs configured
+ * once on the socket as `config.metaAiRendering.verificationMetadata`, so every
+ * rich message (menu, reels, rich text/image/link, HTML) is covered without each
+ * send method needing to thread the config through.
+ */
+export const attachBotVerificationProofs = (envelope, verificationMetadata) => {
+    if (!envelope || !hasVerifiableProofs(verificationMetadata))
+        return envelope;
+    const botMetadata = envelope?.messageContextInfo?.botMetadata;
+    if (!botMetadata || botMetadata.verificationMetadata)
+        return envelope;
+    botMetadata.verificationMetadata = verificationMetadata;
+    return envelope;
 };
 
-export const wrapToBotForwardedMessage = (richResponseMessage) => ({
+/**
+ * Wrap a rich response in the bot-forwarded envelope.
+ *
+ * @param {Object} richResponseMessage - proto.AIRichResponseMessage
+ * @param {Object} [verificationMetadata] - Trusted proofs supplied by the caller
+ *   (typically `config.metaAiRendering.verificationMetadata`). Omitted when absent
+ *   or empty, so no fabricated provenance is ever sent.
+ */
+export const wrapToBotForwardedMessage = (richResponseMessage, verificationMetadata) => ({
     messageContextInfo: {
         botMetadata: {
-            // Lia@Note 09-04-26 --- TODO: Fill verificationMetadata field
-            verificationMetadata: {
-                proofs: [
-                    {
-                        certificateChain: [
-                            botMetadataCertificate(),
-                            botMetadataCertificate(892)
-                        ],
-                        version: 1,
-                        useCase: 1,
-                        signature: botMetadataSignature()
-                    }
-                ]
-            }
+            pluginMetadata: {},
+            ...(hasVerifiableProofs(verificationMetadata) ? { verificationMetadata } : {}),
+            // Lia@Fix --- The Bloks rendering config is required for the client to resolve
+            // and verify rich media. Without it, rich messages attach media the client
+            // treats as unverified: "WhatsApp can't verify the security of this media",
+            // tapping Download crashes the app, and reel previews stop rendering.
+            botRenderingConfigMetadata: BOT_RENDERING_CONFIG_METADATA
         }
     },
     botForwardedMessage: {

package/lib/index.d.ts

@@ -224,7 +224,17 @@ export interface RelayMessageOptions {
 
 export interface AlbumMediaInput {
     image?: unknown;
-    video?: unknown;
+    type?: 'image';
+    data?: unknown;
+    sourceUrl?: string;
+    imagePreviewUrl?: string;
+    imageHighResUrl?: string;
+    darkModePreviewUrl?: string;
+    darkModeHighResUrl?: string;
+    width?: number;
+    height?: number;
+    darkWidth?: number;
+    darkHeight?: number;
     caption?: string;
     [key: string]: unknown;
 }
@@ -238,7 +248,7 @@ export interface AnimatedWallpaperInput {
 
 export interface WASocket {
     sendMessage(jid: string | string[], content: StatusContent | GroupStatusContent | Record<string, unknown>, options?: Partial<StatusOptions> & Record<string, unknown>): Promise<unknown>;
-    /** Send at least two image/video items as an experimental WhatsApp album. */
+    /** Send at least two image URL items as an AIRich GRID_IMAGE album. */
     sendAlbumMessage(jid: string, medias: AlbumMediaInput[], options?: Record<string, unknown>): Promise<unknown>;
     /** Update the connected account's WhatsApp About/profile status. */
     updateProfileStatus(status: string): Promise<void>;
@@ -270,6 +280,8 @@ export interface WASocket {
     sendBotPlanning(jid: string, content?: { text?: string; steps?: Array<string | { title?: string; name?: string; body?: string }>; queryPlan?: boolean; botJid?: string }, options?: Record<string, unknown>): Promise<unknown>;
     /** Send a rich response with experimental resolved tool-call metadata. */
     sendBotToolResult(jid: string, content?: { text?: string; toolCallId?: string; resolutionData?: unknown; resolutionDataSerialized?: string; botJid?: string }, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send one tolerant AIRich response containing every supported section supplied in content. */
+    sendPlogmeMessage(jid: string, content?: Record<string, unknown>, quoted?: unknown, options?: Record<string, unknown>): Promise<unknown>;
     /** Resolve a WhatsApp Channel invite code or invite URL to channel metadata. */
     newsletterGetInviteInfo(inviteCodeOrUrl: string): Promise<Record<string, unknown> | null>;
     /** React to a Channel post; pass an empty string, null, or undefined to remove the reaction. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plogme",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Production-ready Baileys fork ⚉ with AI groups, Meta AI prompting, safe compositing fallbacks, rich responses, interactive messages, albums, newsletters, and communities — without antiban wrappers.",
   "main": "lib/index.js",
   "type": "module",