plogme 2.1.0 → 2.1.2

package/lib/Socket/aigroups.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/aigroups.js
+ * About: Aigroups module for the Plogme WhatsApp protocol client.
+ * Important exports: META_AI_BOT_JID, isMetaAIBotResponse, collectMetaAIBotParticipantJids, makeAIGroupsSocket, extractAIGroupMetadata
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { WAMessageAddressingMode } from '../Types/index.js';
 import { generateMessageIDV2, normalizeMessageContent } from '../Utils/index.js';
 import { getBinaryNodeChild, getBinaryNodeChildren, getBinaryNodeChildString, isJidGroup, isJidMetaAI, isLidUser, isPnUser, jidEncode, jidNormalizedUser } from '../WABinary/index.js';

package/lib/Socket/ban-checker.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/ban-checker.js
+ * About: Ban checker module for the Plogme WhatsApp protocol client.
+ * Important exports: checkStatusWA, getBanDetails, normalizePhone
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { randomBytes, randomUUID } from 'crypto';
 import { initAuthCreds } from '../Utils/auth-utils.js';
 import { Curve, md5, signedKeyPair } from '../Utils/crypto.js';

package/lib/Socket/business.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/business.js
+ * About: Business module for the Plogme WhatsApp protocol client.
+ * Important exports: makeBusinessSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { unlink } from 'node:fs/promises';
 import { getRawMediaUploadData } from '../Utils/index.js';
 import { parseCatalogNode, parseCollectionsNode, parseOrderDetailsNode, parseProductNode, toProductNode, uploadingNecessaryImagesOfProduct } from '../Utils/business.js';

package/lib/Socket/chats.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/chats.js
+ * About: Chats module for the Plogme WhatsApp protocol client.
+ * Important exports: makeChatsSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import NodeCache from '@cacheable/node-cache';
 import { Boom } from '@hapi/boom';
 import { proto } from '../../WAProto/index.js';

package/lib/Socket/communities.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/communities.js
+ * About: Communities module for the Plogme WhatsApp protocol client.
+ * Important exports: makeCommunitiesSocket, extractCommunityMetadata
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { proto } from '../../WAProto/index.js';
 import { WAMessageStubType } from '../Types/index.js';
 import { generateMessageID, generateMessageIDV2, unixTimestampSeconds } from '../Utils/index.js';

package/lib/Socket/graphql.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/graphql.js
+ * About: Graphql module for the Plogme WhatsApp protocol client.
+ * Important exports: executeWWWGraphQL, executeFacebookGraphQL, executeWamoGraphQL, makeGraphQLSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { Boom } from '@hapi/boom';
 
 // Endpoints confirmed from APX.java and WamoGraphQLExecutor.java

package/lib/Socket/groups.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/groups.js
+ * About: Groups module for the Plogme WhatsApp protocol client.
+ * Important exports: buildReportNode, buildGroupStatusRevokeMessage, makeGroupsSocket, extractGroupMetadata
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { Boom } from '@hapi/boom';
 import { proto } from '../../WAProto/index.js';
 import { WAMessageAddressingMode, WAMessageStubType } from '../Types/index.js';

package/lib/Socket/index.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/index.js
+ * About: Socket module for the Plogme WhatsApp protocol client.
+ * Important exports: checkStatusWA
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { DEFAULT_CONNECTION_CONFIG } from '../Defaults/index.js';
 import { makeCommunitiesSocket } from './communities.js';
 import { makeInteropSocket } from './interop.js';

package/lib/Socket/interactive-handler.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/interactive-handler.js
+ * About: Interactive handler module for the Plogme WhatsApp protocol client.
+ * Important exports: Baron
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { randomBytes } from 'crypto';
 import { proto } from '../../WAProto/index.js';
 import {

package/lib/Socket/interop.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/interop.js
+ * About: Interop module for the Plogme WhatsApp protocol client.
+ * Important exports: makeInteropSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { getBinaryNodeChild, getBinaryNodeChildren, S_WHATSAPP_NET } from '../WABinary/index.js';
 import { executeWMexQuery } from './mex.js';
 

package/lib/Socket/managed-account.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/managed-account.js
+ * About: Managed account module for the Plogme WhatsApp protocol client.
+ * Important exports: makeManagedAccountSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import { executeWMexQuery } from './mex.js';
 
 const MANAGED_ACCOUNT_MEX_IDS = {

package/lib/Socket/messages-recv.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/messages-recv.js
+ * About: Messages recv module for the Plogme WhatsApp protocol client.
+ * Important exports: buildGroupCallStanza, buildGroupCallCancelStanza, makeMessagesRecvSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import NodeCache from '@cacheable/node-cache';
 import { Boom } from '@hapi/boom';
 import { randomBytes } from 'crypto';

package/lib/Socket/messages-send.js

@@ -1,9 +1,21 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Socket/messages-send.js
+ * About: Messages send module for the Plogme WhatsApp protocol client.
+ * Important exports: normalizeStatusJidList, makeMessagesSocket
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 import NodeCache from '@cacheable/node-cache';
 import { Boom } from '@hapi/boom';
 import { randomBytes, randomUUID } 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, 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, generateWAMessageFromImagePoll, generateWAMessageFromLivePhoto, getStatusCodeForMediaRetry, makeWhatsAppFlowButton, getUrlFromDirectPath, getWAUploadToServer, MessageRetryManager, normalizeMessageContent, parseAndInjectE2ESessions, prepareWAMessageMedia, shouldIncludeBizBinaryNode, unixTimestampSeconds } from '../Utils/index.js';
 import { getUrlInfo } from '../Utils/link-preview.js';
 import { prepareRichMenuMessage, prepareA2UIMessage, prepareA2UICommandMenu, prepareAIRichCommandMenu, prepareSocialEntityMessage, prepareInstagramProfileMessage, prepareRichResponseMessage, prepareRichGenerationMessage, prepareCopyToClipboardMessage, prepareRichTextMessage, prepareRichQuoteMessage, prepareRichImageMessage, prepareRichLinkMessage, prepareSocialProfileMessage, prepareUnifiedResponseMessage, prepareRichMapMessage, prepareBotPromptSuggestionsMessage, prepareBotSourcesMessage, prepareRichDynamicMediaMessage, prepareBotPttTranscriptMessage, prepareGridImageMessage, prepareVerticalAlbumMessage, prepareVideoGridMessage, prepareHtmlMessage, prepareRichHtmlMessage, buildRichLabelMessage, attachBotVerificationProofs, hasVerifiableProofs } from '../Utils/rich-message-utils.js';
 import { generateSlotMachineHtml } from '../Utils/games/slot-machine.js';
@@ -1093,6 +1105,69 @@ export const makeMessagesSocket = (config) => {
         return fullMsg;
     };
 
+    const sendImagePoll = async (jid, poll, sendOptions = {}) => {
+        const userJid = authState.creds.me.id;
+        const { additionalNodes: _callerNodes, ...relayBaseOptions } = sendOptions;
+        return generateWAMessageFromImagePoll(jid, poll, async (message, relayOptions, fullMessage) => {
+            await relayMessage(jid, message, {
+                ...relayBaseOptions,
+                useCachedGroupMetadata: sendOptions.useCachedGroupMetadata,
+                statusJidList: sendOptions.statusJidList,
+                statusPrivacy: sendOptions.statusPrivacy,
+                ...relayOptions
+            });
+            if (config.emitOwnEvents && fullMessage) {
+                process.nextTick(async () => {
+                    await messageMutex.mutex(() => upsertMessage(fullMessage, 'append'));
+                });
+            }
+        }, {
+            logger,
+            userJid,
+            upload: waUploadToServer,
+            mediaCache: config.mediaCache,
+            options: config.options,
+            ...sendOptions
+        });
+    };
+    const sendLivePhoto = async (jid, content, quoted, sendOptions = {}) => {
+        const userJid = authState.creds.me?.id;
+        const {
+            relayOptions: callerRelayOptions = {},
+            photo_live: _photoLive,
+            photoLive: _photoLiveCamel,
+            thumbnail: _thumbnail,
+            image: _image,
+            videoThumbnail: _videoThumbnail,
+            motionPhotoPresentationOffsetMs: _motionOffset,
+            presentationOffsetMs: _presentationOffset,
+            ...transportOptions
+        } = sendOptions;
+        const mediaOptions = {
+            logger,
+            userJid,
+            upload: waUploadToServer,
+            mediaCache: config.mediaCache,
+            options: config.options,
+            ...transportOptions,
+            ...(quoted ? { quoted } : {})
+        };
+        return generateWAMessageFromLivePhoto(jid, content, async (message, relayOpts, fullMessage) => {
+            await relayMessage(jid, message, {
+                ...transportOptions,
+                ...callerRelayOptions,
+                useCachedGroupMetadata: sendOptions.useCachedGroupMetadata,
+                statusJidList: sendOptions.statusJidList,
+                statusPrivacy: sendOptions.statusPrivacy,
+                messageId: relayOpts.messageId
+            });
+            if (config.emitOwnEvents && fullMessage) {
+                process.nextTick(async () => {
+                    await messageMutex.mutex(() => upsertMessage(fullMessage, 'append'));
+                });
+            }
+        }, mediaOptions);
+    };
     const getMessageType = (message) => {
         if (!message)
             return 'text';
@@ -1323,26 +1398,37 @@ export const makeMessagesSocket = (config) => {
             await relayRichMessage(jid, fullMsg, options);
             return fullMsg;
         },
-        sendCarousel: async (jid, cards, options = {}) => {
+        sendCarousel: async (jid, cards, quotedOrOptions = {}, maybeOptions = undefined) => {
             if (!Array.isArray(cards) || cards.length === 0) {
                 throw new Boom('sendCarousel requires a non-empty card array', { statusCode: 400 });
             }
+            // Support both Plogme's original (jid, cards, options) form and
+            // the compatibility form used by working carousel helpers:
+            // (jid, cards, quoted, options).
+            const hasQuotedSignature = maybeOptions !== undefined;
+            const quoted = hasQuotedSignature ? quotedOrOptions : undefined;
+            const options = hasQuotedSignature ? (maybeOptions || {}) : (quotedOrOptions || {});
             const normalizedCards = cards.map(card => ({
                 ...card,
                 text: card.text ?? card.body?.text,
                 caption: card.caption ?? card.body?.text,
                 footer: card.footer?.text ?? card.footer,
                 buttons: card.buttons ?? card.nativeFlowMessage?.buttons,
+                ...(card.header?.imageMessage ? { image: typeof card.header.imageMessage === 'string' ? { url: card.header.imageMessage } : card.header.imageMessage } : {}),
+                ...(card.header?.videoMessage ? { video: typeof card.header.videoMessage === 'string' ? { url: card.header.videoMessage } : card.header.videoMessage } : {}),
                 ...(card.media?.image ? { image: card.media.image } : {}),
                 ...(card.media?.video ? { video: card.media.video } : {}),
-                ...(card.media?.document ? { document: card.media.document } : {})
+                ...(card.media?.document ? { document: card.media.document } : {}),
+                ...(card.header?.title ? { title: card.title ?? card.header.title } : {}),
+                ...(card.header?.subtitle ? { subtitle: card.subtitle ?? card.header.subtitle } : {}),
+                ...(card.nativeFlowMessage?.buttons ? { nativeFlow: card.nativeFlow || card.nativeFlowMessage.buttons } : {})
             }));
-            const { text, footer, ...messageOptions } = options;
+            const { text, content, footer, ...messageOptions } = options;
             const fullMsg = await generateWAMessage(jid, {
                 ...messageOptions,
                 cards: normalizedCards,
                 ...(options.carouselCardType != null ? { carouselCardType: options.carouselCardType } : {}),
-                ...(text !== undefined ? { text } : {}),
+                ...((text ?? content) !== undefined ? { text: text ?? content } : {}),
                 ...(footer !== undefined ? { footer } : {})
             }, {
                 logger,
@@ -1351,11 +1437,244 @@ export const makeMessagesSocket = (config) => {
                 mediaCache: config.mediaCache,
                 options: config.options,
                 ...options,
+                ...(quoted ? { quoted } : {}),
                 messageId: options.messageId || generateMessageIDV2(jid)
             });
             await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, ...options });
             return fullMsg;
         },
+        /** Send legacy reply buttons with an optional single media or location header. */
+        replyButton: async (jid, buttons, quotedOrOptions = {}, maybeOptions = undefined) => {
+            if (!jid) throw new Boom('replyButton requires a target JID', { statusCode: 400 });
+            if (!Array.isArray(buttons) || buttons.length === 0) {
+                throw new Boom('replyButton requires at least one button', { statusCode: 400 });
+            }
+            const hasQuotedSignature = !!(quotedOrOptions?.key && quotedOrOptions?.message);
+            const quoted = hasQuotedSignature ? quotedOrOptions : undefined;
+            const options = hasQuotedSignature ? (maybeOptions || {}) : (maybeOptions || quotedOrOptions || {});
+            const normalizeButton = (button, index) => {
+                if (!button || typeof button !== 'object') {
+                    throw new Boom(`replyButton button ${index + 1} must be an object`, { statusCode: 400 });
+                }
+                const label = button.text || button.buttonText || button.displayText || `Option ${index + 1}`;
+                if (button.sections) {
+                    return {
+                        name: 'single_select',
+                        paramsJson: JSON.stringify({ title: label, sections: button.sections })
+                    };
+                }
+                if (button.name) {
+                    return {
+                        ...button,
+                        paramsJson: typeof button.paramsJson === 'string'
+                            ? button.paramsJson
+                            : JSON.stringify(button.params || {})
+                    };
+                }
+                if (button.url) {
+                    return {
+                        name: 'cta_url',
+                        paramsJson: JSON.stringify({
+                            display_text: label,
+                            url: button.url,
+                            merchant_url: button.merchantUrl || button.url
+                        })
+                    };
+                }
+                if (button.call || button.phoneNumber) {
+                    return {
+                        name: 'cta_call',
+                        paramsJson: JSON.stringify({ display_text: label, phone_number: button.call || button.phoneNumber })
+                    };
+                }
+                if (button.copy || button.copyCode) {
+                    return {
+                        name: 'cta_copy',
+                        paramsJson: JSON.stringify({ display_text: label, copy_code: button.copy || button.copyCode })
+                    };
+                }
+                const id = button.command || button.id || button.buttonId;
+                if (!id) throw new Boom(`replyButton button ${index + 1} needs an id, command, or native-flow action`, { statusCode: 400 });
+                return { text: label, id, ...(button.type != null ? { type: button.type } : {}) };
+            };
+            const location = options.location;
+            const documentOptions = options.document && typeof options.document === 'object' ? options.document : {};
+            const media = options.media ?? options.image ?? options.video ?? options.document?.url;
+            const hasExplicitMedia = options.image != null || options.video != null || options.document != null || options.media != null;
+            if (location && hasExplicitMedia) {
+                throw new Boom('replyButton accepts one header attachment; choose either location or media', { statusCode: 400 });
+            }
+            if (hasExplicitMedia && media == null) {
+                throw new Boom('replyButton media header requires an image, video, or document source', { statusCode: 400 });
+            }
+            const content = { buttons: buttons.map(normalizeButton) };
+            if (options.footer !== undefined) content.footer = options.footer;
+            if (options.title !== undefined) content.title = options.title;
+            const text = options.text ?? options.caption ?? '';
+            if (location) {
+                content.location = {
+                    ...location,
+                    ...(location.description && !location.address ? { address: location.description } : {})
+                };
+                content.caption = text;
+            }
+            else if (hasExplicitMedia) {
+                const source = media == null ? options.document : media;
+                const sourceName = String(options.filename || documentOptions.filename || (typeof source === 'string' ? source : source?.url || '')).toLowerCase();
+                const mimeType = options.mimetype || documentOptions.mimetype || source?.mimetype || '';
+                const extension = sourceName.split(/[?#]/)[0].split('.').pop();
+                let mediaType = options.mediaType || (options.document ? 'document' : options.video ? 'video' : undefined);
+                if (!mediaType) {
+                    mediaType = mimeType.startsWith('video/') || ['mp4', 'mov', 'm4v', '3gp'].includes(extension) ? 'video' : 'image';
+                }
+                if (!['image', 'video', 'document'].includes(mediaType)) {
+                    throw new Boom('replyButton mediaType must be image, video, or document', { statusCode: 400 });
+                }
+                const mediaInput = typeof source === 'string' ? { url: source } : source;
+                content[mediaType] = mediaInput;
+                if (mediaType === 'document') {
+                    content.fileName = options.filename || documentOptions.filename || 'file';
+                    if (mimeType) content.mimetype = mimeType;
+                }
+                content.caption = text;
+            }
+            else {
+                content.text = text;
+            }
+            const {
+                text: _text, caption: _caption, footer: _footer, title: _title,
+                location: _location, media: _media, image: _image, video: _video,
+                document: _document, filename: _filename, mimetype: _mimetype,
+                mediaType: _mediaType, sendOptions: nestedSendOptions = {},
+                ...transportOptions
+            } = options;
+            return socket.sendMessage(jid, content, {
+                ...transportOptions,
+                ...nestedSendOptions,
+                ...(quoted ? { quoted } : {})
+            });
+        },
+        /** Send a motion photo from its video and optional still image/thumbnail. */
+        sendPhotoLive: async (jid, content, quoted, options = {}) => {
+            if (!jid) throw new Boom('sendPhotoLive requires a target JID', { statusCode: 400 });
+            return sendLivePhoto(jid, content, quoted, options);
+        },
+        /** Send a file; `photo_live: true` pairs a still with its motion-video child. */
+        sendFile: async (jid, media, filename = '', caption = '', quoted, options = {}) => {
+            if (!jid) throw new Boom('sendFile requires a target JID', { statusCode: 400 });
+            if (options.photo_live || options.photoLive) {
+                return sendLivePhoto(jid, {
+                    video: media,
+                    image: options.image,
+                    thumbnail: options.thumbnail,
+                    videoThumbnail: options.videoThumbnail,
+                    caption,
+                    motionPhotoPresentationOffsetMs: options.motionPhotoPresentationOffsetMs ?? options.presentationOffsetMs
+                }, quoted, options);
+            }
+            const sourceName = String(filename || options.fileName || (typeof media === 'string' ? media : media?.url || '')).toLowerCase();
+            const extension = sourceName.split(/[?#]/)[0].split('.').pop();
+            const mimeType = options.mimetype || media?.mimetype || '';
+            const mediaType = options.mediaType || (options.document ? 'document' : mimeType.startsWith('image/') ? 'image' : mimeType.startsWith('video/') ? 'video' : mimeType.startsWith('audio/') ? 'audio' : ['jpg', 'jpeg', 'png', 'gif', 'webp', 'heic'].includes(extension) ? 'image' : ['mp4', 'mov', 'm4v', '3gp', 'webm'].includes(extension) ? 'video' : ['mp3', 'ogg', 'opus', 'wav', 'm4a', 'aac'].includes(extension) ? 'audio' : 'document');
+            if (!['image', 'video', 'audio', 'document'].includes(mediaType)) {
+                throw new Boom('sendFile mediaType must be image, video, audio, or document', { statusCode: 400 });
+            }
+            const source = typeof media === 'string' ? { url: media } : media;
+            const message = {
+                [mediaType]: source,
+                caption,
+                ...(filename || options.fileName ? { fileName: filename || options.fileName } : {}),
+                ...(mimeType ? { mimetype: mimeType } : {}),
+                ...(mediaType === 'audio' && options.ptt ? { ptt: true } : {})
+            };
+            const { photo_live: _photoLive, photoLive: _photoLiveCamel, thumbnail: _thumbnail, ...sendOptions } = options;
+            return socket.sendMessage(jid, message, {
+                ...sendOptions,
+                ...(quoted ? { quoted } : {})
+            });
+        },
+        /** Send or edit a textual progress bar; pass messageKey to update in place. */
+        sendProgress: async (jid, text, quotedOrOptions = {}, maybeOptions = undefined) => {
+            if (!jid) throw new Boom('sendProgress requires a target JID', { statusCode: 400 });
+            const hasQuotedSignature = !!(quotedOrOptions?.key && quotedOrOptions?.message);
+            const quoted = hasQuotedSignature ? quotedOrOptions : undefined;
+            const options = hasQuotedSignature ? (maybeOptions || {}) : (maybeOptions || quotedOrOptions || {});
+            const progress = Number(options.progress ?? 0);
+            if (!Number.isFinite(progress) || progress < 0 || progress > 100) {
+                throw new Boom('sendProgress progress must be between 0 and 100', { statusCode: 400 });
+            }
+            const width = Math.max(4, Math.min(40, Math.floor(Number(options.width) || 12)));
+            const percent = Math.round(progress);
+            const filled = Math.round(width * percent / 100);
+            const bar = `[${'█'.repeat(filled)}${'░'.repeat(width - filled)}] ${percent}%`;
+            const content = { text: `${String(text || '')}${text ? '\n' : ''}${bar}` };
+            const messageKey = options.messageKey || options.editKey;
+            if (messageKey) content.edit = messageKey;
+            const {
+                progress: _progress, width: _width, messageKey: _messageKey, editKey: _editKey,
+                sendOptions: nestedSendOptions = {}, ...sendOptions
+            } = options;
+            return socket.sendMessage(jid, content, {
+                ...sendOptions,
+                ...nestedSendOptions,
+                ...(quoted ? { quoted } : {})
+            });
+        },
+        /** Send text with a custom external preview card (thumbnail, title, URL and attribution). */
+        sendMessageModify: async (jid, text, quotedOrOptions = {}, maybeOptions = undefined) => {
+            if (!jid) throw new Boom('sendMessageModify requires a target JID', { statusCode: 400 });
+            const hasQuotedSignature = !!(quotedOrOptions?.key && quotedOrOptions?.message);
+            const quoted = hasQuotedSignature ? quotedOrOptions : undefined;
+            const options = hasQuotedSignature ? (maybeOptions || {}) : (maybeOptions || quotedOrOptions || {});
+            const thumbnail = options.thumbnail;
+            const thumbnailSource = typeof thumbnail === 'string' ? thumbnail : thumbnail?.url;
+            const thumbnailUrl = thumbnailSource && /^https?:\/\//i.test(thumbnailSource)
+                ? thumbnailSource
+                : options.thumbnailUrl || options.originalImageUrl;
+            let thumbnailBuffer;
+            if (Buffer.isBuffer(thumbnail) || thumbnail instanceof Uint8Array) {
+                thumbnailBuffer = Buffer.from(thumbnail);
+            }
+            else if (typeof thumbnailSource === 'string' && !/^https?:\/\//i.test(thumbnailSource)) {
+                try {
+                    thumbnailBuffer = (await extractImageThumb(thumbnailSource, 192)).buffer;
+                }
+                catch (error) {
+                    throw new Boom(`sendMessageModify could not read thumbnail: ${error.message}`, { statusCode: 400 });
+                }
+            }
+            const externalAdReply = {
+                title: options.title || '',
+                body: options.description || options.body || '',
+                mediaType: thumbnailBuffer || thumbnailUrl ? 1 : 0,
+                ...(thumbnailBuffer ? { thumbnail: thumbnailBuffer } : {}),
+                ...(thumbnailUrl ? { thumbnailUrl, originalImageUrl: thumbnailUrl } : {}),
+                ...(options.url ? { mediaUrl: options.url, sourceUrl: options.url } : {}),
+                showAdAttribution: options.ads ?? false,
+                renderLargerThumbnail: options.largeThumb ?? options.largeThumbnail ?? true
+            };
+            const message = {
+                text: String(text ?? ''),
+                externalAdReply,
+                ...(options.icon ? { favicon: typeof options.icon === 'string' ? { url: options.icon } : options.icon } : {})
+            };
+            const {
+                title: _title, description: _description, body: _body, url: _url,
+                thumbnail: _thumbnailValue, thumbnailUrl: _thumbnailUrl,
+                originalImageUrl: _originalImageUrl, icon: _icon,
+                ads: _ads, largeThumb: _largeThumb, largeThumbnail: _largeThumbnail,
+                ratio: _ratio, type: _type, sendOptions: nestedSendOptions = {},
+                ...transportOptions
+            } = options;
+            return socket.sendMessage(jid, message, {
+                ...transportOptions,
+                ...nestedSendOptions,
+                ...(quoted ? { quoted } : {})
+            });
+        },
+        /** Compatibility alias for sendMessageModify. */
+        sendMessageModifyV2: async (jid, text, quotedOrOptions = {}, maybeOptions = undefined) =>
+            socket.sendMessageModify(jid, text, quotedOrOptions, maybeOptions),
         sendLatex: async (jid, quoted, options = {}) => {
             const { message, messageId } = generateLatexContent(quoted, { expressions: [], ...options });
             const fullMsg = generateWAMessageFromContent(jid, message, {
@@ -1471,7 +1790,7 @@ export const makeMessagesSocket = (config) => {
             await relayMessage(jid, message, relayOptions);
             return msgId;
         },
-        // Additive Nexus-compatible AI-rich helpers. Existing Gen4/table/grid/carousel APIs remain unchanged.
+        // Additive New-compatible AI-rich helpers. Existing Gen4/table/grid/carousel APIs remain unchanged.
         sendRichMedia: async (jid, content = {}, quoted, options = {}) => {
             const contentMessage = prepareRichResponseMessage({ ...content, noDonation: options.noDonation ?? true });
             const generated = generateWAMessageFromContent(jid, contentMessage, {
@@ -1484,6 +1803,13 @@ export const makeMessagesSocket = (config) => {
             await relayRichMessage(jid, generated, options);
             return { ...generated, messageId: generated.key.id };
         },
+        /**
+         * Send native Plogme rich media with the additive New compatibility field
+         * compatibility sections enabled. The native serializer is retained.
+         */
+        sendNewRichMedia: async (jid, content = {}, quoted, options = {}) => {
+            return socket.sendRichMedia(jid, { ...content, compatibility: 'both' }, quoted, options);
+        },
         /**
          * Send a native AI image/video generation card. The returned messageId
          * is required by updateRichGeneration() for an in-place edit.
@@ -1576,7 +1902,7 @@ export const makeMessagesSocket = (config) => {
          * 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,
+         * callers that may receive optional text, HTML, links, media, products,
          * reels, tables, code, latex, or suggestion data.
          */
         sendPlogmeMessage: async (jid, content = {}, quoted, options = {}) => {
@@ -1807,6 +2133,10 @@ export const makeMessagesSocket = (config) => {
         },
         sendMessage: async (jid, content, options = {}) => {
             const userJid = authState.creds.me.id;
+            const pollValues = content?.poll?.values;
+            if (Array.isArray(pollValues) && pollValues.some(value => value && typeof value === 'object' && value.image)) {
+                return sendImagePoll(jid, content.poll, options);
+            }
             if (content?.groupStatus === true && !isJidGroup(jid)) {
                 throw new Boom('groupStatus requires a valid group JID', { statusCode: 400 });
             }
@@ -3025,6 +3355,27 @@ export const makeMessagesSocket = (config) => {
         return fullMsg;
     };
 
+    /**
+     * Send a native group status. `content.private` adds WhatsApp's
+     * statusAudienceMetadata without creating a group message or changing
+     * group membership.
+     */
+    socket.sendGroupStatus = async (jid, content = {}, options = {}) => {
+        if (!jid || !isJidGroup(jid)) {
+            throw new Boom('sendGroupStatus requires a valid group JID', { statusCode: 400 });
+        }
+        if (!content || typeof content !== 'object' || Array.isArray(content)) {
+            throw new Boom('sendGroupStatus content must be a message object', { statusCode: 400 });
+        }
+        const { private: privateAudience, ...statusContent } = content;
+        const audience = privateAudience ?? options.private;
+        return socket.sendMessage(
+            jid,
+            { ...statusContent, groupStatus: true, ...(audience !== undefined ? { private: audience } : {}) },
+            options
+        );
+    };
+
 
     /**
      * Sends an HTML message — renders raw HTML inside the chat bubble.