@codexverified/baileys 2.17.17 → 2.17.18

package/README.md

@@ -58,13 +58,14 @@ The package is maintained by **Codex** under the **CodexVerified** organization.
 - [Comparison references](#comparison-references)
 - [Additional functional compatibility helpers](#additional-functional-compatibility-helpers)
 - [AI generation primitive](#ai-generation-primitive)
+- [New AIRich metadata helpers](#new-airich-metadata-helpers)
 
 ## At a glance
 
 | Property | Value |
 | --- | --- |
 | Package | `@codexverified/baileys` |
-| Version | `2.17.17` |
+| Version | `2.17.18` |
 | Runtime | Node.js 20 or newer |
 | Module format | ESM, with CommonJS compatibility where supported |
 | Type declarations | Included at `lib/index.d.ts` |
@@ -78,7 +79,7 @@ The package is maintained by **Codex** under the **CodexVerified** organization.
 | Method | Command | Notes |
 | --- | --- | --- |
 | From npm | `npm install @codexverified/baileys` | Standard install when published under your organization |
-| From local archive | `npm install ./codex-baileys-2.17.17.tgz` | Place the `.tgz` beside your application |
+| From local archive | `npm install ./codex-baileys-2.17.18.tgz` | Place the `.tgz` beside your application |
 | Source audit (no scripts) | `npm install --ignore-scripts` | Skips install hooks for local review |
 
 Both npm and archive installs use the same import name:
@@ -859,6 +860,81 @@ await sock.sendMiniApp(jid, {
 
 The package also exports `BotCapabilityType`, `normalizeBotCapabilities`, `buildBotCapabilityMetadata`, and `buildBotRichResponse` for applications that need to construct compatible bot metadata.
 
+
+## New AIRich metadata helpers
+
+The package includes experimental helpers for protocol-backed rich clients. Rendering depends on the recipient's WhatsApp client version; these helpers do not call Meta AI or any private backend.
+
+```js
+await sock.sendA2UIMessage(jid, {
+  type: 'im_a2ui',
+  data: {
+    version: 'v0.9',
+    createSurface: {
+      surfaceId: 'custom-card',
+      catalogId: 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json',
+      components: [{ id: 'root', component: 'Column', children: ['title'] }]
+    }
+  }
+})
+
+await sock.sendRichMap(jid, {
+  centerLatitude: 6.5244,
+  centerLongitude: 3.3792,
+  annotations: [{ latitude: 6.53, longitude: 3.38, title: 'Lagos', body: 'Nigeria' }],
+  showInfoList: true
+})
+
+await sock.sendBotPromptSuggestions(jid, {
+  text: 'Choose a follow-up',
+  suggestions: ['Summarize this', 'Translate this', 'Explain further'],
+  selectedPromptId: 'translate'
+})
+
+await sock.sendBotSources(jid, {
+  text: 'Relevant sources:',
+  sources: [{
+    provider: 2,
+    url: 'https://example.com/docs',
+    query: 'baileys proto',
+    title: 'Documentation',
+    citationNumber: 1
+  }]
+})
+
+await sock.sendRichDynamicMedia(jid, {
+  type: 'IMAGE',
+  url: 'https://example.com/image.jpg',
+  version: 1
+})
+
+await sock.sendBotPttTranscript(jid, {
+  text: 'Voice transcript',
+  transcript: 'Hello, this text came from a voice message.'
+})
+
+await sock.sendSocialEntity(jid, {
+  platform: 'YOUTUBE',
+  username: 'example',
+  title: 'Example creator',
+  imageUrl: 'https://example.com/avatar.png',
+  entityUrl: 'https://www.youtube.com/@example',
+  isVerified: true,
+  resultText: 'See results'
+})
+
+await sock.sendInstagramProfile(jid, {
+  username: 'example',
+  title: 'Example profile',
+  imageUrl: 'https://example.com/avatar.png',
+  entityUrl: 'https://www.instagram.com/example',
+  isVerified: true,
+  resultText: 'See results'
+})
+```
+
+The map, prompt, source, dynamic-media, transcript, A2UI, and social/entity payloads are serialized from the generated `WAProto` structures. Validate URLs, button identifiers, and any user-supplied metadata in your own application before sending.
+
 <div align="center">
 
 <sub>Thanks for reading my README.</sub>

package/lib/Socket/messages-send.js

@@ -12,7 +12,7 @@ import { areJidsSameUser, getBinaryNodeChild, getBinaryNodeChildren, getBizBinar
 import { USyncQuery, USyncUser } from '../WAUSync/index.js';
 import { captureUnifiedResponse, generateButtonGridContent, generateCodeBlockContent, generateLatexContent, generateListContent, generateRichMenuContent, generateTableContent, generateUnifiedResponseContent } from '../Utils/message-composer.js';
 import { Baron } from './interactive-handler.js';
-import { prepareRichResponseMessage, prepareRichGenerationMessage, prepareRichTextMessage, prepareRichImageMessage, prepareRichLinkMessage, prepareA2UICommandMenu, prepareAIRichCommandMenu, prepareVideoGridMessage, prepareVerticalAlbumMessage, prepareHtmlMessage, prepareRichHtmlMessage } from '../Utils/rich-message-utils.js';
+import { prepareRichResponseMessage, prepareRichGenerationMessage, prepareRichTextMessage, prepareRichImageMessage, prepareRichLinkMessage, prepareA2UICommandMenu, prepareAIRichCommandMenu, prepareVideoGridMessage, prepareVerticalAlbumMessage, prepareHtmlMessage, prepareRichHtmlMessage, prepareA2UIMessage, prepareBotPromptSuggestionsMessage, prepareBotPttTranscriptMessage, prepareBotSourcesMessage, prepareInstagramProfileMessage, prepareRichDynamicMediaMessage, prepareRichMapMessage, prepareSocialEntityMessage } 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/website-preview.js';
@@ -1322,6 +1322,111 @@ export const makeMessagesSocket = (config) => {
             await relayMessage(jid, fullMsg.message, { messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata, statusJidList: options.statusJidList });
             return fullMsg;
         },
+        sendA2UIMessage: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendA2UIMessage requires a target JID', { statusCode: 400 });
+        const { image, ...payload } = content || {};
+        let imageMessage;
+        if (image) {
+            const prepared = await prepareWAMessageMedia({ image }, { upload: waUploadToServer });
+            imageMessage = prepared.imageMessage;
+        }
+        const wrapped = prepareA2UIMessage({ ...payload, imageMessage });
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id || jid),
+            ...options,
+        });
+        await relayRichMessage(jid, fullMsg, { ...options, forceRichEdit: true });
+        if (config.emitOwnEvents) process.nextTick(async () => { await messageMutex.mutex(() => upsertMessage(fullMsg, 'append')); });
+        return fullMsg;
+    },
+        sendBotPromptSuggestions: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendBotPromptSuggestions requires a target JID', { statusCode: 400 });
+        const wrapped = prepareBotPromptSuggestionsMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        return fullMsg;
+    },
+        sendBotPttTranscript: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendBotPttTranscript requires a target JID', { statusCode: 400 });
+        const wrapped = prepareBotPttTranscriptMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        return fullMsg;
+    },
+        sendBotSources: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendBotSources requires a target JID', { statusCode: 400 });
+        const wrapped = prepareBotSourcesMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        return fullMsg;
+    },
+        sendInstagramProfile: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendInstagramProfile requires a target JID', { statusCode: 400 });
+        const wrapped = prepareInstagramProfileMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id || jid),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        if (config.emitOwnEvents) process.nextTick(async () => { await messageMutex.mutex(() => upsertMessage(fullMsg, 'append')); });
+        return fullMsg;
+        },
+        sendRichDynamicMedia: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendRichDynamicMedia requires a target JID', { statusCode: 400 });
+        const wrapped = prepareRichDynamicMediaMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        return fullMsg;
+    },
+        sendRichMap: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendRichMap requires a target JID', { statusCode: 400 });
+        const wrapped = prepareRichMapMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id),
+            ...options
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        return fullMsg;
+    },
+        sendSocialEntity: async (jid, content = {}, options = {}) => {
+        if (!jid) throw new Boom('sendSocialEntity requires a target JID', { statusCode: 400 });
+        const wrapped = prepareSocialEntityMessage(content);
+        const fullMsg = await generateWAMessageFromContent(jid, wrapped, {
+            logger,
+            userJid: authState.creds.me?.id,
+            messageId: options.messageId || generateMessageIDV2(authState.creds.me?.id || jid),
+            ...options,
+        });
+        await relayRichMessage(jid, fullMsg, options);
+        if (config.emitOwnEvents) process.nextTick(async () => { await messageMutex.mutex(() => upsertMessage(fullMsg, 'append')); });
+        return fullMsg;
+    },
         /** Send the large A2UI command menu with an uploaded image header, rows, and URL buttons. */
         /** Sends the manually serialized AIRich command card shown in the screenshot. */
         sendAIRichCommandMenu: async (jid, content = {}, options = {}) => {

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

@@ -504,7 +504,7 @@ export const wrapToBotForwardedMessage = (richResponseMessage) => ({
  */
 /** Build the A2UI interactive command menu used by the full-size card layout. */
 /** Build the manually serialized AIRich command menu shown in the screenshot. */
-export const prepareAIRichCommandMenu = ({ image, title = 'CODY AI', subtitle = '', code = '', rows = [], buttons = [], footer = 'Developed by - CODY AI', latexImage, latexExpression = '' } = {}) => {
+export const prepareAIRichCommandMenu = ({ image, title = 'CODEX AI', subtitle = '', code = '', rows = [], buttons = [], footer = 'Developed by - CODEX AI', latexImage, latexExpression = '' } = {}) => {
     if (!image) throw new Error('AIRich command menu requires an image URL');
     if (!Array.isArray(rows)) throw new Error('AIRich command-menu rows must be an array');
     if (!Array.isArray(buttons)) throw new Error('AIRich command-menu buttons must be an array');
@@ -531,7 +531,7 @@ export const prepareAIRichCommandMenu = ({ image, title = 'CODY AI', subtitle =
     return wrapToBotForwardedMessage(richResponseMessage);
 };
 
-export const prepareA2UICommandMenu = ({ imageMessage, title = 'CODY AI', rows = [], buttons = [], fallback = '' } = {}) => {
+export const prepareA2UICommandMenu = ({ imageMessage, title = 'CODEX AI', rows = [], buttons = [], fallback = '' } = {}) => {
     if (!Array.isArray(rows)) throw new Error('A2UI command-menu rows must be an array');
     if (!Array.isArray(buttons)) throw new Error('A2UI command-menu buttons must be an array');
     const safeRows = rows.map((row, index) => ({
@@ -556,7 +556,7 @@ export const prepareA2UICommandMenu = ({ imageMessage, title = 'CODY AI', rows =
             { id: `command_${index}`, component: 'Text', text: row.title },
             { id: `description_${index}`, component: 'Text', text: row.description }
         ]),
-        { id: 'footer', component: 'Text', text: 'Developed by - CODY AI', variant: 'caption' }
+        { id: 'footer', component: 'Text', text: 'Developed by - CODEX AI', variant: 'caption' }
     ];
     if (safeButtons.length) {
         components.push({ id: 'buttonRow', component: 'Row', justify: 'spaceEvenly', children: safeButtons.flatMap((button, index) => [`buttonLabel_${index}`, `button_${index}`]) });
@@ -748,4 +748,321 @@ export const buildImaginePrimitive = ({
     };
 };
 
-                                                                    
+export const prepareSocialEntityMessage = ({
+    username = '',
+    platform = 'GENERIC',
+    title = 'CODEX AI',
+    subtitle = '⚉',
+    imageUrl = '',
+    entityId,
+    entityUrl = '',
+    entityType,
+    fullName = 'NOT found',
+    isVerified = false,
+    resultText = 'See results',
+    botJid = '867051314767696@bot',
+    responseId
+} = {}) => {
+    const normalizedPlatform = String(platform || 'GENERIC').toUpperCase();
+    const profileUrl = entityUrl || (username ? `https://www.${normalizedPlatform.toLowerCase()}.com/${encodeURIComponent(username)}` : '');
+    const resolvedType = entityType || (normalizedPlatform === 'INSTAGRAM' ? 'IG_PROFILE' : 'SOCIAL_PROFILE');
+    const displayName = username || fullName || 'Profile';
+    const sections = [
+        {
+            view_model: {
+                primitives: [{
+                    title,
+                    subtitle,
+                    ...(imageUrl ? { image: { url: imageUrl, mime_type: 'image/png' } } : {}),
+                    entity_id: String(entityId ?? username ?? ''),
+                    entity_url: profileUrl,
+                    entity_type: 'WEBSITE',
+                    action_type: 'OPEN_URL',
+                    is_verified: !!isVerified,
+                    __typename: 'GenAICompactEntityPrimitive'
+                }],
+                __typename: 'GenAIActionRowLayoutViewModel'
+            }
+        },
+        {
+            view_model: {
+                primitives: [{ type: 'HORIZONTAL_LINE', __typename: 'GenAIDividerPrimitive' }],
+                __typename: 'GenAIVStackLayoutViewModel'
+            }
+        },
+        {
+            view_model: {
+                primitives: [
+                    { __typename: 'GenAISpacerPrimitive' },
+                    {
+                        text: `# {{social_entity_1}}${resultText}\0{{/social_entity_1}}    `,
+                        inline_entities: [{
+                            key: 'social_entity_1',
+                            metadata: {
+                                __typename: 'GenAISocialEntityItem',
+                                entity_id: String(entityId ?? username ?? ''),
+                                entity_name: displayName,
+                                entity_full_name: fullName,
+                                platform: String(platform || 'GENERIC').toUpperCase(),
+                                entity_picture_url: imageUrl,
+                                entity_url: profileUrl,
+                                entity_type: resolvedType,
+                                platform: normalizedPlatform,
+                                is_verified: !!isVerified
+                            }
+                        }],
+                        __typename: 'GenAIMarkdownTextUXPrimitive'
+                    },
+                    { __typename: 'GenAISpacerPrimitive' }
+                ],
+                __typename: 'GenAIActionRowLayoutViewModel'
+            }
+        }
+    ];
+    return {
+        botForwardedMessage: {
+            message: {
+                richResponseMessage: {
+                    messageType: 1,
+                    submessages: [],
+                    unifiedResponse: {
+                        response_id: responseId || randomUUID(),
+                        data: Buffer.from(JSON.stringify({ sections })).toString('base64')
+                    },
+                    contextInfo: {
+                        isForwarded: true,
+                        forwardOrigin: 4,
+                        forwardedAiBotMessageInfo: { botJid }
+                    }
+                }
+            }
+        }
+    };
+};
+
+/** Dedicated Instagram profile card using the universal social-entity wire format. */
+
+export const prepareInstagramProfileMessage = (content = {}) => prepareSocialProfileMessage({
+    ...content,
+    platform: 'INSTAGRAM',
+    entityType: 'IG_PROFILE',
+    entityUrl: content.entityUrl || (content.username ? `https://www.instagram.com/${encodeURIComponent(content.username)}` : undefined)
+});
+
+export const prepareSocialProfileMessage = (options = {}) => {
+    const {
+        username,
+        platform = 'instagram',
+        title = 'CODEX AI',
+        subtitle = '⚉',
+        imageUrl = '',
+        entityId = username,
+        entityUrl = `https://www.${platform}.com/${username || ''}`,
+        entityType = platform === 'instagram' ? 'IG_PROFILE' : `${String(platform).toUpperCase()}_PROFILE`,
+        fullName = 'NOT found',
+        isVerified = false,
+        resultText = 'See results'
+    } = options;
+    if (!username || typeof username !== 'string') {
+        throw new Boom('sendSocialProfile requires a username', { statusCode: 400 });
+    }
+    const image = imageUrl ? { url: imageUrl, mime_type: 'image/png' } : undefined;
+    const sections = [
+        {
+            view_model: {
+                primitives: [{
+                    title,
+                    subtitle,
+                    ...(image ? { image } : {}),
+                    entity_id: String(entityId || username),
+                    entity_url: entityUrl,
+                    entity_type: 'WEBSITE',
+                    action_type: 'OPEN_URL',
+                    is_verified: Boolean(isVerified),
+                    __typename: 'GenAICompactEntityPrimitive'
+                }],
+                __typename: 'GenAIActionRowLayoutViewModel'
+            }
+        },
+        {
+            view_model: {
+                primitives: [{ type: 'HORIZONTAL_LINE', __typename: 'GenAIDividerPrimitive' }],
+                __typename: 'GenAIVStackLayoutViewModel'
+            }
+        },
+        {
+            view_model: {
+                primitives: [
+                    { __typename: 'GenAISpacerPrimitive' },
+                    {
+                        text: `# {{social_entity_1}}${resultText}\0{{/social_entity_1}}    `,
+                        inline_entities: [{
+                            key: 'social_entity_1',
+                            metadata: {
+                                __typename: 'GenAISocialEntityItem',
+                                entity_id: username,
+                                entity_name: username,
+                                entity_full_name: fullName,
+                                platform: String(platform || 'GENERIC').toUpperCase(),
+                                entity_picture_url: imageUrl,
+                                entity_url: entityUrl,
+                                entity_type: entityType,
+                                is_verified: Boolean(isVerified)
+                            }
+                        }],
+                        __typename: 'GenAIMarkdownTextUXPrimitive'
+                    },
+                    { __typename: 'GenAISpacerPrimitive' }
+                ],
+                __typename: 'GenAIActionRowLayoutViewModel'
+            }
+        }
+    ];
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        submessages: [],
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: { data: Buffer.from(JSON.stringify({ sections })) },
+        contextInfo: { isForwarded: true, forwardOrigin: 4 }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage);
+};
+
+
+/**
+ * Builds a generic unified-response envelope without reducing its sections to
+ * plain text. This is the extension point for newer WhatsApp primitives that
+ * are present in WAProto but do not yet have a dedicated convenience helper.
+ */
+
+export const prepareRichMapMessage = ({ centerLatitude, centerLongitude, latitudeDelta, longitudeDelta, annotations = [], showInfoList = false, verificationMetadata } = {}) => {
+    if (!Number.isFinite(Number(centerLatitude)) || !Number.isFinite(Number(centerLongitude))) {
+        throw new Boom('prepareRichMapMessage requires centerLatitude and centerLongitude', { statusCode: 400 });
+    }
+    const submessages = [{
+        messageType: RichSubMessageType.MAP,
+        mapMetadata: {
+            centerLatitude: Number(centerLatitude),
+            centerLongitude: Number(centerLongitude),
+            ...(latitudeDelta == null ? {} : { latitudeDelta: Number(latitudeDelta) }),
+            ...(longitudeDelta == null ? {} : { longitudeDelta: Number(longitudeDelta) }),
+            showInfoList: Boolean(showInfoList),
+            annotations: (Array.isArray(annotations) ? annotations : []).map((annotation, index) => ({
+                annotationNumber: annotation.annotationNumber ?? index + 1,
+                latitude: Number(annotation.latitude),
+                longitude: Number(annotation.longitude),
+                title: String(annotation.title || ''),
+                body: String(annotation.body || '')
+            }))
+        }
+    }];
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        submessages,
+        unifiedResponse: { data: Buffer.from(JSON.stringify(toUnified(submessages, randomUUID()))) },
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
+};
+
+/** Build a rich response carrying BotSuggestedPromptMetadata from WAProto. */
+
+export const prepareBotPromptSuggestionsMessage = ({ text = '', suggestions = [], selectedPromptIndex, selectedPromptId, verificationMetadata } = {}) => {
+    if (!Array.isArray(suggestions) || suggestions.length === 0) {
+        throw new Boom('prepareBotPromptSuggestionsMessage requires at least one suggestion', { statusCode: 400 });
+    }
+    const envelope = wrapToBotForwardedMessage(proto.AIRichResponseMessage.create({
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        submessages: [{ messageType: RichSubMessageType.TEXT, messageText: String(text) }],
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
+    }), verificationMetadata);
+    envelope.messageContextInfo.botMetadata.suggestedPromptMetadata = {
+        suggestedPrompts: suggestions.map(String),
+        ...(selectedPromptIndex == null ? {} : { selectedPromptIndex: Number(selectedPromptIndex) }),
+        ...(selectedPromptId == null ? {} : { selectedPromptId: String(selectedPromptId) })
+    };
+    return envelope;
+};
+
+/** Build a rich response carrying BotSourcesMetadata for citations/search results. */
+
+export const prepareBotSourcesMessage = ({ text = '', sources = [], verificationMetadata } = {}) => {
+    if (!Array.isArray(sources) || sources.length === 0) {
+        throw new Boom('prepareBotSourcesMessage requires at least one source', { statusCode: 400 });
+    }
+    const envelope = wrapToBotForwardedMessage(proto.AIRichResponseMessage.create({
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        submessages: [{ messageType: RichSubMessageType.TEXT, messageText: String(text) }],
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
+    }), verificationMetadata);
+    envelope.messageContextInfo.botMetadata.richResponseSourcesMetadata = {
+        sources: sources.map((source, index) => ({
+            provider: source.provider ?? proto.BotSourcesMetadata.BotSourceItem.SourceProvider.OTHER,
+            thumbnailCdnUrl: source.thumbnailCdnUrl || source.thumbnailUrl || '',
+            sourceProviderUrl: source.sourceProviderUrl || source.url || '',
+            sourceQuery: source.sourceQuery || source.query || '',
+            faviconCdnUrl: source.faviconCdnUrl || source.faviconUrl || '',
+            citationNumber: source.citationNumber ?? index + 1,
+            sourceTitle: source.sourceTitle || source.title || ''
+        }))
+    };
+    return envelope;
+};
+
+/** Build an AIRich dynamic image/GIF submessage from WAProto metadata. */
+
+export const prepareRichDynamicMediaMessage = ({ url = '', type = 'IMAGE', version = 1, loopCount, verificationMetadata } = {}) => {
+    if (!url || typeof url !== 'string') throw new Boom('prepareRichDynamicMediaMessage requires a URL', { statusCode: 400 });
+    const dynamicTypes = proto.AIRichResponseDynamicMetadata.AIRichResponseDynamicMetadataType;
+    const normalizedType = String(type).toUpperCase();
+    const dynamicMetadata = {
+        type: normalizedType === 'GIF'
+            ? dynamicTypes.AI_RICH_RESPONSE_DYNAMIC_METADATA_TYPE_GIF
+            : dynamicTypes.AI_RICH_RESPONSE_DYNAMIC_METADATA_TYPE_IMAGE,
+        version: Number(version),
+        url,
+        ...(loopCount == null ? {} : { loopCount: Number(loopCount) })
+    };
+    const submessages = [{ messageType: RichSubMessageType.DYNAMIC, dynamicMetadata }];
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        submessages,
+        unifiedResponse: { data: Buffer.from(JSON.stringify(toUnified(submessages, randomUUID()))) },
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
+};
+
+/** Build a rich response carrying the exact BotPttPromptMetadata transcript field. */
+
+export const prepareBotPttTranscriptMessage = ({ text = '', transcript = '', verificationMetadata } = {}) => {
+    if (!transcript || typeof transcript !== 'string') {
+        throw new Boom('prepareBotPttTranscriptMessage requires a transcript', { statusCode: 400 });
+    }
+    const envelope = wrapToBotForwardedMessage(proto.AIRichResponseMessage.create({
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        submessages: [{ messageType: RichSubMessageType.TEXT, messageText: String(text || transcript) }],
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardOrigin: 4 }
+    }), verificationMetadata);
+    envelope.messageContextInfo.botMetadata.pttPromptMetadata = { transcript };
+    return envelope;
+};
+
+export const prepareA2UIMessage = ({ imageMessage, bloksWidget = {}, nativeFlowMessage, fallback = '', ...interactiveFields } = {}) => ({
+    interactiveMessage: {
+        ...interactiveFields,
+        ...(imageMessage ? { header: { imageMessage, hasMediaAttachment: true } } : {}),
+        bloksWidget: {
+            type: bloksWidget.type || 'im_a2ui',
+            data: typeof bloksWidget.data === 'string' ? bloksWidget.data : JSON.stringify(bloksWidget.data || {}),
+            ...(bloksWidget.fallback || fallback ? { fallback: String(bloksWidget.fallback || fallback) } : {})
+        },
+        ...(nativeFlowMessage ? {
+            nativeFlowMessage: {
+                ...nativeFlowMessage,
+                ...(nativeFlowMessage.buttons ? { buttons: nativeFlowMessage.buttons } : {})
+            }
+        } : {})
+    }
+});
+
+/** Build the A2UI interactive command menu used by the full-size card layout. */

package/lib/index.d.ts

@@ -121,6 +121,83 @@ export interface AIPromptOptions {
     [key: string]: unknown;
 }
 
+export interface SocialEntityContent {
+    username?: string;
+    platform?: string;
+    title?: string;
+    subtitle?: string;
+    imageUrl?: string;
+    entityId?: string | number;
+    entityUrl?: string;
+    entityType?: string;
+    fullName?: string;
+    isVerified?: boolean;
+    resultText?: string;
+    botJid?: string;
+    responseId?: string;
+}
+
+export interface RichMapAnnotation {
+    annotationNumber?: number;
+    latitude: number;
+    longitude: number;
+    title?: string;
+    body?: string;
+}
+
+export interface RichMapContent {
+    centerLatitude: number;
+    centerLongitude: number;
+    latitudeDelta?: number;
+    longitudeDelta?: number;
+    annotations?: RichMapAnnotation[];
+    showInfoList?: boolean;
+    verificationMetadata?: Record<string, unknown>;
+}
+
+export interface BotPromptSuggestionsContent {
+    text?: string;
+    suggestions: string[];
+    selectedPromptIndex?: number;
+    selectedPromptId?: string;
+    verificationMetadata?: Record<string, unknown>;
+}
+
+export interface BotSourceContent {
+    provider?: number;
+    thumbnailCdnUrl?: string;
+    thumbnailUrl?: string;
+    sourceProviderUrl?: string;
+    url?: string;
+    sourceQuery?: string;
+    query?: string;
+    faviconCdnUrl?: string;
+    faviconUrl?: string;
+    citationNumber?: number;
+    sourceTitle?: string;
+    title?: string;
+}
+
+export interface BotSourcesContent {
+    text?: string;
+    sources: BotSourceContent[];
+    verificationMetadata?: Record<string, unknown>;
+}
+
+export interface RichDynamicMediaContent {
+    url: string;
+    type?: 'IMAGE' | 'GIF' | string;
+    version?: number;
+    loopCount?: number;
+    verificationMetadata?: Record<string, unknown>;
+}
+
+export interface BotPttTranscriptContent {
+    transcript: string;
+    text?: string;
+    verificationMetadata?: Record<string, unknown>;
+}
+
 export interface RelayMessageOptions {
     messageId?: string;
     /** Recipient-only delivery: skip the sender’s own devices in a one-to-one chat. */
@@ -305,6 +382,22 @@ export interface WASocket {
     sendQuoteCopy(jid: string, content: { text?: string; copyText: string; copyLabel?: string; alignment?: 'END' | 'START' | 'CENTER' }, options?: Record<string, unknown>): Promise<unknown>;
     /** Send a full-width stacked AIRich album with at least two image/video URL items. */
     sendAlbumMessage(jid: string, medias: Array<Record<string, unknown>>, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send a provider-neutral AIRich social/entity result card. */
+    sendSocialEntity(jid: string, content?: SocialEntityContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send a protocol-backed AIRich map with optional numbered annotations. */
+    sendRichMap(jid: string, content: RichMapContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send BotSuggestedPromptMetadata with a rich-response text fallback. */
+    sendBotPromptSuggestions(jid: string, content: BotPromptSuggestionsContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send BotSourcesMetadata for citation-aware bot responses. */
+    sendBotSources(jid: string, content: BotSourcesContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send an experimental AIRich dynamic image/GIF submessage. */
+    sendRichDynamicMedia(jid: string, content: RichDynamicMediaContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send BotPttPromptMetadata containing a caller-provided transcript. */
+    sendBotPttTranscript(jid: string, content: BotPttTranscriptContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send the primary Instagram profile result using the universal social/entity format. */
+    sendInstagramProfile(jid: string, content: SocialEntityContent, options?: Record<string, unknown>): Promise<unknown>;
+    /** Send arbitrary A2UI/interactive payloads with immediate relay/edit rendering. */
+    sendA2UIMessage(jid: string, content?: A2UIMessageContent, options?: Record<string, unknown>): Promise<unknown>;
     /** Send the large A2UI command/function menu with an image header and URL buttons. */
     sendA2UICommandMenu(jid: string, content?: { image?: unknown; title?: string; rows?: Array<[string, string, string?] | { title?: string; description?: string; id?: string }>; buttons?: Array<{ text?: string; label?: string; url?: string }>; fallback?: string }, options?: Record<string, unknown>): Promise<unknown>;
     /** Send the manually serialized AIRich command card with image, Markdown, widget CTAs, and footer actions. */
@@ -451,4 +544,5 @@ export declare function buildBotRichResponse(options?: Record<string, unknown>):
 export declare function prepareVerticalAlbumMessage(options?: { items?: Array<Record<string, unknown>>; verificationMetadata?: Record<string, unknown> }): Record<string, unknown>;
 export declare function prepareAIRichCommandMenu(options?: { image?: string; title?: string; subtitle?: string; code?: string; rows?: Array<[string, string] | Record<string, unknown>>; buttons?: Array<Record<string, unknown>>; footer?: string; latexImage?: string; latexExpression?: string }): Record<string, unknown>;
 export declare function prepareVideoGridMessage(options?: { videos?: Array<string | Record<string, unknown>>; verificationMetadata?: Record<string, unknown> }): Record<string, unknown>;
+
                                                             

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@codexverified/baileys",
-   "version": "2.17.17",
+   "version": "2.17.18",
    "description": "CODEX TECHNOLOGY  a premium Baileys developed and built by Dev Codex, with Meta compositing, bot planning replay, welcome flow, rich messages, interactive messages, albums, and more.",
    "main": "lib/index.js",
    "type": "module",