@codexverified/baileys 2.14.14 → 2.17.18

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

@@ -152,6 +152,64 @@ export const buildAdditionalBotMetadataContext = (submessages) => {
     }
     return { sources, mediaDetailsMetadataList };
 }
+export const prepareVideoGridMessage = ({ videos = [], verificationMetadata } = {}) => {
+    if (!Array.isArray(videos) || videos.length < 2) {
+        throw new Error('Video grid requires at least two videos');
+    }
+    const primitives = videos.map((video) => {
+        const url = typeof video === 'string' ? video : (video?.url || video?.videoUrl || video?.reelsUrl || '');
+        if (!url) throw new Error('Each video-grid item requires a video URL');
+        const item = typeof video === 'string' ? {} : video;
+        return {
+            post_id: item.postId == null ? undefined : String(item.postId),
+            reels_url: url,
+            reels_title: item.title,
+            thumbnail_url: item.thumbnailUrl || item.thumbnail,
+            creator: item.creator,
+            avatar_url: item.avatarUrl,
+            content_hash: item.contentHash,
+            likes_count: item.likes,
+            comments_count: item.comments,
+            shares_count: item.shares,
+            is_verified: item.isVerified,
+            source_app: item.sourceApp,
+            video_delivery_response: {
+                progressive_urls: (item.progressiveUrls || []).map((value) => ({
+                    progressive_url: value,
+                    __typename: 'GenAIProgressiveUrlResponse'
+                })),
+                dash_manifests: (item.dashManifests || []).map((value) => ({
+                    manifest_xml: value,
+                    __typename: 'GenAIDashManifestResponse'
+                })),
+                __typename: 'GenAIVideoDeliveryResponse'
+            },
+            __typename: 'GenAIVideoPrimitive'
+        };
+    });
+    const unified = {
+        response_id: randomUUID(),
+        sections: [{
+            view_model: {
+                primitives,
+                __typename: 'GenAIGridLayoutViewModel'
+            }
+        }]
+    };
+    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, suggested, richResponse, table, tapLinkUrl, title } = content;
     let submessages = [];
@@ -444,6 +502,78 @@ export const wrapToBotForwardedMessage = (richResponseMessage) => ({
  * @param {{text?: string, label?: string, alignment?: 'END'|'START'|'CENTER'}} options
  * @returns {{messageContextInfo: object, botForwardedMessage: object}}
  */
+/** 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 = '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');
+    const safeRows = rows.map((row, index) => ({ command: String(row?.[0] ?? row?.command ?? `command_${index + 1}`), description: String(row?.[1] ?? row?.description ?? '') }));
+    const table = ['Command | Function', '--- | ---', ...safeRows.map((row) => `${row.command} | ${row.description}`)].join('\n');
+    const inlineEntities = latexImage ? [{ key: 'NGA', metadata: { latex_expression: String(latexExpression), latex_image: { url: String(latexImage), width: 400, height: 400 }, font_height: 83.333, padding: 15, __typename: 'GenAILatexItem' } }] : [];
+    const text = [String(title), subtitle && String(subtitle), code && `Code: ${String(code)}`, '## Command List', table, footer && String(footer)].filter(Boolean).join('\n');
+    const imagePrimitive = { __typename: 'GenAIImagePrimitive', preview_image: { __typename: 'GenAIMediaItem', mime_type: 'image/png', url: String(image) }, full_image: { __typename: 'GenAIMediaItem', mime_type: 'image/png', url: String(image) } };
+    const ctas = buttons.map((button, index) => ({ label: String(button?.text || button?.label || `Button ${index + 1}`), state: 'PENDING', kind: 'OTHER', tool_call_id: String(button?.id || `airich_menu_${index + 1}`), toast: { label: String(button?.toast || ''), __typename: 'GenAIExtWidgetToast' }, __typename: 'GenAI3PExtWidgetCTA' }));
+    const footerPrimitives = buttons.map((button, index) => ({ cta_text: String(button?.text || button?.label || `Button ${index + 1}`), cta_type: 'OPEN_URL', cta_url: String(button?.url || ''), __typename: 'GenAIFooterActionPrimitive' }));
+    footerPrimitives.push({ cta_text: '☷ OPEN MENU', cta_type: 'OPEN_URL', cta_url: String(buttons[0]?.url || ''), __typename: 'GenAIFooterActionPrimitive' });
+    const sections = [
+        { __typename: 'GenAIUnifiedResponseSection', view_model: { __typename: 'GenAISingleLayoutViewModel', primitive: imagePrimitive } },
+        ...(ctas.length ? [{ __typename: 'GenAIUnifiedResponseSection', view_model: { primitives: [{ __typename: 'GenAI3PExtWidgetPrimitive', header: { __typename: 'GenAI3PExtWidgetStandardHeader', title: 'Command List' }, body: { __typename: 'GenAIExtCalendarEventList', ctas, sections: [] } }], __typename: 'GenAIActionRowLayoutViewModel' } }] : []),
+        { __typename: 'GenAIUnifiedResponseSection', view_model: { primitive: { text: `{{NGA}}${text}{{/NGA}}`, inline_entities: inlineEntities, __typename: 'GenAIMarkdownTextUXPrimitive' }, __typename: 'GenAISingleLayoutViewModel' } },
+        { __typename: 'GenAIUnifiedResponseSection', view_model: { primitives: footerPrimitives, __typename: 'GenAIActionRowLayoutViewModel' } }
+    ];
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        submessages: [{ messageType: RichSubMessageType.TEXT, messageText: text }],
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: { data: Buffer.from(JSON.stringify({ response_id: randomUUID(), sections })) },
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' }, forwardOrigin: 4 }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage);
+};
+
+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) => ({
+        title: String(row?.[0] ?? row?.title ?? `Command ${index + 1}`),
+        description: String(row?.[1] ?? row?.description ?? ''),
+        id: String(row?.[2] ?? row?.id ?? row?.[0] ?? `command_${index + 1}`)
+    }));
+    const safeButtons = buttons.map((button, index) => ({ id: `a2ui_button_${index + 1}`, label: String(button?.text || button?.label || `Button ${index + 1}`), url: String(button?.url || '') }));
+    const componentIds = ['title', 'divider', 'tableCard', 'footer', ...(safeButtons.length ? ['buttonRow'] : [])];
+    const components = [
+        { id: 'root', component: 'Column', align: 'center', children: componentIds },
+        { id: 'title', component: 'Text', text: String(title), variant: 'h2' },
+        { id: 'divider', component: 'Divider' },
+        { id: 'tableCard', component: 'Card', child: 'tableColumn' },
+        { id: 'tableColumn', component: 'Column', children: ['headerRow', ...safeRows.flatMap((_, index) => [`divider_${index}`, `row_${index}`])] },
+        { id: 'headerRow', component: 'Row', children: ['headerCommand', 'headerFunction'] },
+        { id: 'headerCommand', component: 'Text', text: 'Command', variant: 'h5' },
+        { id: 'headerFunction', component: 'Text', text: 'Function', variant: 'h5' },
+        ...safeRows.flatMap((row, index) => [
+            { id: `divider_${index}`, component: 'Divider' },
+            { id: `row_${index}`, component: 'Row', children: [`command_${index}`, `description_${index}`] },
+            { id: `command_${index}`, component: 'Text', text: row.title },
+            { id: `description_${index}`, component: 'Text', text: row.description }
+        ]),
+        { 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}`]) });
+        safeButtons.forEach((button, index) => {
+            components.push({ id: `buttonLabel_${index}`, component: 'Text', text: button.label });
+            components.push({ id: `button_${index}`, component: 'Button', child: `buttonLabel_${index}`, variant: 'primary', action: { call: 'openUrl', args: { url: button.url } } });
+        });
+    }
+    return {
+        interactiveMessage: {
+            ...(imageMessage ? { header: { imageMessage, hasMediaAttachment: true } } : {}),
+            bloksWidget: { type: 'im_a2ui', data: JSON.stringify({ version: 'v0.9', createSurface: { surfaceId: 'codex-a2ui-command-menu', catalogId: 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json', components } }), fallback: String(fallback || title) },
+            nativeFlowMessage: { messageParamsJson: JSON.stringify({ limited_time_offer: { text: String(title), url: safeButtons[0]?.url || '', copy_code: String(title), expiration_time: Date.now() * 1000 } }), buttons: [{ name: 'single_select', buttonParamsJson: JSON.stringify({ title: String(title), sections: [{ title: 'Available Commands', rows: safeRows }] }) }] }
+        }
+    };
+};
+
 export const prepareCopyToClipboardMessage = (options = {}) => {
     const text = String(options.text ?? '');
     const label = String(options.label ?? text);
@@ -535,6 +665,63 @@ export const prepareSlotMachineMessage = async (options = {}) => {
  * The payload is useful for displaying generation progress without making any
  * network request or enabling a hidden background process.
  */
+/** Build a full-width vertical album with one large media item per row. */
+export const prepareVerticalAlbumMessage = ({ items = [], verificationMetadata } = {}) => {
+    if (!Array.isArray(items) || items.length < 2) {
+        throw new Error('Vertical album requires at least two media items');
+    }
+    const expiration = String(Date.now() + 30 * 24 * 60 * 60 * 1000);
+    const primitives = items.map((item) => {
+        const kind = item?.type || (item?.video ? 'video' : 'image');
+        if (kind === 'video') {
+            const video = item.video || item.data || item;
+            const url = typeof video === 'string' ? video.trim() : String(video?.url || video?.videoUrl || '').trim();
+            if (!url) throw new Error('Each video album item requires a video URL');
+            return buildImaginePrimitive({
+                mediaType: 'video',
+                url,
+                thumbnail: video?.thumbnail || video?.thumbnailUrl,
+                mimeType: video?.mimeType || video?.mime_type || 'video/mp4',
+                fileLength: video?.fileLength || video?.file_length || 0,
+                duration: video?.duration || 0,
+                status: 'READY'
+            });
+        }
+        const image = item?.image || item?.data || item;
+        const sourceUrl = typeof image === 'string' ? image.trim() : String(image?.sourceUrl || image?.url || '').trim();
+        if (!sourceUrl) throw new Error('Each image album item requires an image URL');
+        const previewUrl = image?.imagePreviewUrl || image?.previewUrl || sourceUrl;
+        const fullUrl = image?.imageHighResUrl || image?.highResUrl || image?.url || sourceUrl;
+        const width = image?.width || item?.width || 600;
+        const height = image?.height || item?.height || 400;
+        const mimeType = image?.mimeType || image?.mime_type || 'image/jpeg';
+        return {
+            preview_image: { url: previewUrl, mime_type: mimeType, expiration_timestamp_ms: expiration, width, height },
+            full_image: { url: fullUrl, mime_type: mimeType, expiration_timestamp_ms: expiration, width, height },
+            dark_mode_preview_image: { url: image?.darkModePreviewUrl || previewUrl, mime_type: mimeType, expiration_timestamp_ms: expiration, width, height },
+            dark_mode_full_image: { url: image?.darkModeHighResUrl || image?.darkModePreviewUrl || fullUrl, mime_type: mimeType, expiration_timestamp_ms: expiration, width, height },
+            asset_query_status: 'FETCHED',
+            __typename: 'GenAIImagePrimitive'
+        };
+    });
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        submessages: [],
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: {
+            data: Buffer.from(JSON.stringify({
+                response_id: randomUUID(),
+                sections: [{ view_model: { primitives, __typename: 'GenAIVStackLayoutViewModel' } }]
+            }))
+        },
+        contextInfo: {
+            isForwarded: true,
+            forwardingScore: 1,
+            forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' },
+            forwardOrigin: 4
+        }
+    });
+    return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
+};
 export const buildImaginePrimitive = ({
     mediaType = 'video',
     url = '',
@@ -560,4 +747,322 @@ export const buildImaginePrimitive = ({
         ...(estimatedMs !== undefined ? { estimated_ms: Number(estimatedMs) } : {})
     };
 };
-                                                                    
+
+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/Utils/source-grep.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const DEFAULT_DIRS = ['lib', 'WAProto'];
+const DEFAULT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.d.ts', '.proto', '.md', '.json']);
+
+const walk = (directory, files) => {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) walk(fullPath, files);
+        else if (DEFAULT_EXTENSIONS.has(path.extname(entry.name))) files.push(fullPath);
+    }
+};
+
+/**
+ * Find a literal or regular-expression pattern in package source.
+ * Returns exact relative file, line, column, and matching source line.
+ */
+export const grepSource = (pattern, options = {}) => {
+    if (typeof pattern !== 'string' || !pattern.trim()) {
+        throw new TypeError('grepSource requires a non-empty search string');
+    }
+    const expression = options.regex ? new RegExp(pattern, options.flags || 'i') : null;
+    const needle = options.caseSensitive ? pattern : pattern.toLowerCase();
+    const files = [];
+    for (const relativeDir of options.dirs || DEFAULT_DIRS) walk(path.resolve(PACKAGE_ROOT, relativeDir), files);
+    if (options.includeReadme) files.push(path.resolve(PACKAGE_ROOT, 'README.md'));
+    const matches = [];
+    for (const file of files.sort()) {
+        const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+        lines.forEach((line, index) => {
+            const found = expression ? expression.test(line) : (options.caseSensitive ? line.includes(pattern) : line.toLowerCase().includes(needle));
+            if (found) {
+                const column = expression ? Math.max(0, line.search(expression)) : (options.caseSensitive ? line.indexOf(pattern) : line.toLowerCase().indexOf(needle));
+                matches.push({ file: path.relative(PACKAGE_ROOT, file), line: index + 1, column: column + 1, text: line.trim() });
+            }
+            if (expression) expression.lastIndex = 0;
+        });
+    }
+    return matches.slice(0, Math.max(1, options.maxResults || 200));
+};
+