@nerxa/socketon 0.0.0-stage → 1.21.0

package/src/MessageBuilder/extras.js

@@ -0,0 +1,1356 @@
+import { randomUUID } from 'crypto'
+import { AIRich } from './index.js'
+import { extractMessageContent, generateWAMessageFromContent, prepareWAMessageMedia } from '../Utils/messages.js'
+import { checkHtmlApp } from '../Utils/html-app.js'
+
+export const AI_RICH_LAYOUTS = Object.freeze([
+    'Single',
+    'HScroll',
+    'ActionRow',
+    'VStack',
+    'Grid',
+    'FlexibleCountGrid',
+    'RichListItem',
+    'AddonAction',
+    'MultipleResponse',
+    'IGSuggestedBloomCard'
+])
+
+export const AI_RICH_PRIMITIVES = Object.freeze([
+    'GenAIMarkdownTextUXPrimitive',
+    'GenAICodeUXPrimitive',
+    'GenATableUXPrimitive',
+    'GenAIMetadataTextPrimitive',
+    'GenAISearchResultPrimitive',
+    'GenAIReelPrimitive',
+    'GenAIPostPrimitive',
+    'GenAIProductItemCardPrimitive',
+    'GenAIImaginePrimitive',
+    'GenAIFollowUpSuggestionPillPrimitive',
+    'FOATextPrimitive',
+    'FOABloksPrimitive',
+    'GenAIImagePrimitive',
+    'GenAIDividerPrimitive',
+    'GenAISpacerPrimitive',
+    'GenAITaskPrimitive',
+    'GenAILatexUXPrimitive',
+    'GenAIBotThinkingStatusPrimitive',
+    'GenAIBotProgressStatusPrimitive',
+    'GenAIMetaSubsQuotaUpsellPrimitive',
+    'GenAIMapPrimitive',
+    'GenAIVideoPrimitive',
+    'GenAIReminderPrimitive',
+    'GenAICommentPrimitive',
+    'GenAICompactEntityPrimitive',
+    'GenAIActionListPrimitive',
+    'GenAISportsWidgetPrimitive',
+    'GenAISearchAdPrimitive',
+    'GenAISearchResultV2Primitive',
+    'GenAISearchPlannerStepsPrimitive',
+    'GenAISearchPlannerStepSnippetPrimitive',
+    'GenAIChainOfThoughtStepPrimitive',
+    'GenAIChainingSuggestionPrimitive',
+    'GenAILocationPermissionPrimitive',
+    'GenAITimestampPlaceholderPrimitive',
+    'GenAIP13NTransparencyPrimitive',
+    'GenAIProfessionalConsentPrimitive',
+    'GenAI3PAccountLinkingUpsellPrimitive',
+    'GenAI3PExtWidgetPrimitive',
+    'GenAIFilePrimitive',
+    'GenAIFileLinkPrimitive',
+    'GenAIFooterActionPrimitive',
+    'GenAIClippyWidgetPrimitive',
+    'GenAIClippyFollowUpPrimitive',
+    'GenAIaeacdsnwHtmlPrimitive',
+    'GenAIQuizPrimitive',
+    'GenAIActionGroupPrimitive',
+    'GenAIFusedComparisonTablePrimitive'
+])
+
+export const AI_RICH_PRIMITIVE_INTERFACE = 'GenAIUXPrimitive'
+
+export const AI_RICH_PRIMITIVES_WITHOUT_SCHEMA = Object.freeze([
+    'GenAIClippyWidgetPrimitive',
+    'GenAIClippyFollowUpPrimitive'
+])
+
+export const AI_RICH_ITEMS = Object.freeze([
+    'GenAIMediaItem',
+    'GenAIPlaceDetailsItem',
+    'GenAIPlaceEntityItem',
+    'GenAISocialEntityItem',
+    'GenAIProductEntityItem',
+    'GenAISourcedItem',
+    'GenAITopicLinkItem',
+    'GenAIThreadSurfingItem',
+    'GenAISideBySideSurveyItem',
+    'GenAIIGCoachSuggestedPromptItem',
+    'GenAI3PExtCalendarEventItem',
+    'GenAI3PAccountLinkingBottomsheetAppItem',
+    'GenAIActionListRow',
+    'GenAISportsTeam',
+    'GenAISportsVenue',
+    'GenAISportsGroup',
+    'GenAIContextualSourcesViewModel'
+])
+
+export const AI_RICH_HTML_PRIMITIVE = 'GenAIaeacdsnwHtmlPrimitive'
+export const AI_RICH_HTML_PRIMITIVE_CLASS = 'FOAHtmlPrimitive'
+
+export const AI_RICH_INLINE_ENTITIES = Object.freeze([
+    'GenAIInlineLinkItem',
+    'GenAISearchCitationItem',
+    'GenAILatexItem',
+    'GenAIDeeplinkItem'
+])
+
+export const AI_RICH_PRIMITIVES_WEB_RENDERED = Object.freeze([
+    'GenAIMarkdownTextUXPrimitive',
+    'GenAICodeUXPrimitive',
+    'GenAILatexUXPrimitive',
+    'GenATableUXPrimitive',
+    'GenAIMetadataTextPrimitive',
+    'GenAIDividerPrimitive',
+    'GenAISpacerPrimitive',
+    'GenAIImagePrimitive',
+    'GenAIImaginePrimitive',
+    'GenAIReelPrimitive',
+    'GenAIPostPrimitive',
+    'GenAIProductItemCardPrimitive',
+    'GenAISearchResultPrimitive',
+    'GenAIBotThinkingStatusPrimitive',
+    'GenAIBotProgressStatusPrimitive',
+    'GenAIMetaSubsQuotaUpsellPrimitive',
+    'FOATextPrimitive',
+    'FOABloksPrimitive'
+])
+
+export const DividerType = Object.freeze({ DOT: 'DOT', HORIZONTAL_LINE: 'HORIZONTAL_LINE' })
+export const ImagineType = Object.freeze({ IMAGINE: 'IMAGINE', ANIMATE: 'ANIMATE', MEMU: 'MEMU' })
+export const ImagineStatus = Object.freeze({ GENERATING: 'GENERATING', READY: 'READY', FAILED: 'FAILED' })
+export const ThinkingIcon = Object.freeze({ THINKING: 'THINKING', WEB_SEARCH: 'WEB_SEARCH', META_SEARCH: 'META_SEARCH' })
+export const TaskStatus = Object.freeze({ PENDING: 'PENDING', RUNNING: 'RUNNING', DONE: 'DONE' })
+export const FooterActionType = Object.freeze({
+    OPEN_FULL_VIEW: 'OPEN_FULL_VIEW',
+    DOWNLOAD_MEDIA: 'DOWNLOAD_MEDIA',
+    GENERATE_IMAGE: 'GENERATE_IMAGE',
+    CANCEL_REASONING: 'CANCEL_REASONING',
+    UPGRADE_TO_SUBS: 'UPGRADE_TO_SUBS',
+    COPY_LINK: 'COPY_LINK',
+    REMIX_MEDIA: 'REMIX_MEDIA',
+    USE_TEMPLATE: 'USE_TEMPLATE'
+})
+export const AddonActionType = Object.freeze({
+    COPY_TO_CLIPBOARD: 'COPY_TO_CLIPBOARD',
+    SEND_TO_CHAT: 'SEND_TO_CHAT',
+    FOLLOW_UP_PROMPT: 'FOLLOW_UP_PROMPT'
+})
+
+const trimEmpty = (object) => {
+    for (const key of Object.keys(object)) {
+        if (object[key] === undefined) {
+            delete object[key]
+        }
+    }
+    return object
+}
+
+export const dividerSection = ({ dividerType = DividerType.HORIZONTAL_LINE } = {}) =>
+    AIRich.newLayout('Single', {
+        divider_type: dividerType,
+        __typename: 'GenAIDividerPrimitive'
+    })
+
+export const spacerSection = ({ spacing = 1 } = {}) =>
+    AIRich.newLayout('Single', {
+        spacing,
+        __typename: 'GenAISpacerPrimitive'
+    })
+
+export const imageSection = (url, { fallbackUrl, previewUrl, previewFallbackUrl } = {}) =>
+    AIRich.newLayout('Single', {
+        full_image: { url, url_fallback: fallbackUrl ?? '' },
+        preview_image: { url: previewUrl ?? url, url_fallback: previewFallbackUrl ?? fallbackUrl ?? '' },
+        __typename: 'GenAIImagePrimitive'
+    })
+
+export const taskSection = ({ taskId, title = '', subtitle = '', status = TaskStatus.PENDING }) => {
+    if (!taskId) {
+        throw new TypeError('taskSection requires taskId, an empty id makes WhatsApp drop the item')
+    }
+    return AIRich.newLayout('Single', {
+        task_id: String(taskId),
+        title,
+        subtitle,
+        status,
+        __typename: 'GenAITaskPrimitive'
+    })
+}
+
+export const latexSection = (expression, { image, width = 100, height = 100, fontHeight = 83.333333333333, padding = 15 } = {}) =>
+    AIRich.newLayout('Single', {
+        latex_expression: expression,
+        ...(image
+            ? {
+                latex_image: { url: image, width, height },
+                font_height: fontHeight,
+                padding
+            }
+            : {}),
+        __typename: 'GenAILatexUXPrimitive'
+    })
+
+const statusSection = (typename) => (title, { icon = ThinkingIcon.THINKING, inProgress = true, metaSearchApps = [], thoughtDurationSec } = {}) =>
+    AIRich.newLayout('Single', trimEmpty({
+        title,
+        icon,
+        is_in_progress: inProgress,
+        meta_search_apps: metaSearchApps,
+        thought_duration_sec: thoughtDurationSec === undefined ? undefined : Number(thoughtDurationSec),
+        __typename: typename
+    }))
+
+export const thinkingSection = statusSection('GenAIBotThinkingStatusPrimitive')
+export const progressSection = statusSection('GenAIBotProgressStatusPrimitive')
+
+export const lockHeight = (height) => {
+    const px = Number(height)
+    if (!Number.isFinite(px) || px <= 0) {
+        throw new TypeError('height must be a positive number of pixels')
+    }
+    return '<style>html,body{margin:0;padding:0;height:' + px + 'px;max-height:' + px + 'px;overflow:hidden}'
+        + '#__wrap{height:' + px + 'px;overflow-y:auto;-webkit-overflow-scrolling:touch;touch-action:pan-y}</style>'
+        + '<script>document.addEventListener("DOMContentLoaded",function(){'
+        + 'var w=document.createElement("div");w.id="__wrap";'
+        + 'while(document.body.firstChild)w.appendChild(document.body.firstChild);'
+        + 'document.body.appendChild(w)});<' + '/script>'
+}
+
+export const HTML_APP_BRIDGE = 'AndroidBridge'
+
+export const dataUri = (bytes, mimetype) => {
+    if (typeof mimetype !== 'string' || !mimetype.includes('/')) {
+        throw new TypeError('dataUri needs a mimetype like video/mp4')
+    }
+    const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+    if (!buffer.length) {
+        throw new TypeError('dataUri needs a non-empty buffer')
+    }
+    return 'data:' + mimetype + ';base64,' + buffer.toString('base64')
+}
+
+const MEDIA_TAGS = new Set(['video', 'audio', 'img'])
+
+export const htmlMedia = (bytes, { mimetype, tag = 'video', label = 'Tap untuk memuat media', poster, id = 'm' + randomUUID().slice(0, 8), attributes = '' } = {}) => {
+    if (!MEDIA_TAGS.has(tag)) {
+        throw new TypeError('htmlMedia tag must be one of ' + [...MEDIA_TAGS].join(', '))
+    }
+    if (typeof id !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(id)) {
+        throw new TypeError('htmlMedia id must start with a letter and stay alphanumeric')
+    }
+
+    const uri = dataUri(bytes, mimetype)
+    const controls = tag === 'img' ? '' : ' controls preload="none" playsinline'
+    const cover = poster && tag === 'video' ? ' poster="' + String(poster).replace(/"/g, '&quot;') + '"' : ''
+    const json = JSON.stringify(uri).replace(/</g, '\\u003c').replace(/>/g, '\\u003e')
+
+    return '<' + tag + ' id="' + id + '"' + controls + cover + (attributes ? ' ' + attributes : '') + '></' + tag + '>'
+        + '<button id="' + id + '_go" type="button">' + String(label).replace(/[<>&]/g, c => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' })[c]) + '</button>'
+        + '<script>(function(){'
+        + 'var src=' + json + ',el=document.getElementById(' + JSON.stringify(id) + '),go=document.getElementById(' + JSON.stringify(id + '_go') + ');'
+        + 'go.addEventListener("click",function(){'
+        + 'if(el.src)return;el.src=src;go.disabled=true;go.textContent="\\u2713";'
+        + 'if(el.play)el.play().catch(function(){})});'
+        + '})();<' + '/script>'
+}
+
+export const scrollControls = ({ target = '#__wrap', step = 140, holdMs = 70, size = 36, side = 'right', inset = 6 } = {}) => {
+    const px = Number(step)
+    const hold = Number(holdMs)
+    const box = Number(size)
+    const edge = Number(inset)
+    if (typeof target !== 'string' || target.trim() === '') {
+        throw new TypeError('scrollControls target must be a CSS selector')
+    }
+    if (!Number.isFinite(px) || px <= 0) {
+        throw new TypeError('scrollControls step must be a positive number of pixels')
+    }
+    if (!Number.isFinite(hold) || hold < 16) {
+        throw new TypeError('scrollControls holdMs must be at least 16')
+    }
+    if (!Number.isFinite(box) || box < 24) {
+        throw new TypeError('scrollControls size must be at least 24 pixels')
+    }
+    if (side !== 'right' && side !== 'left') {
+        throw new TypeError('scrollControls side must be "right" or "left"')
+    }
+    if (!Number.isFinite(edge) || edge < 0) {
+        throw new TypeError('scrollControls inset must not be negative')
+    }
+    return '<style>'
+        + '#__sc{position:fixed;' + side + ':' + edge + 'px;bottom:' + edge + 'px;z-index:2147483647;'
+        + 'display:none;flex-direction:column;gap:' + Math.round(box / 6) + 'px}'
+        + '#__sc button{width:' + box + 'px;height:' + box + 'px;padding:0;border:0;'
+        + 'border-radius:' + Math.round(box / 4) + 'px;background:rgba(0,0,0,.6);color:#fff;'
+        + 'font:' + Math.round(box / 2) + 'px/1 system-ui;touch-action:none;cursor:pointer;'
+        + '-webkit-tap-highlight-color:transparent}'
+        + '#__sc button:disabled{opacity:.3}'
+        + '</style>'
+        + '<script>(function(){'
+        + 'var STEP=' + px + ',HOLD=' + hold + ',SEL=' + JSON.stringify(target) + ';'
+        + 'var box,up,down,timer=null;'
+        + 'function pane(){return document.querySelector(SEL)||document.scrollingElement||document.body}'
+        + 'function room(){var p=pane();return p?p.scrollHeight-p.clientHeight:0}'
+        + 'function sync(){if(!box)return;var p=pane(),r=room();'
+        + 'box.style.display=r>4?"flex":"none";if(r<=4)return;'
+        + 'up.disabled=p.scrollTop<=0;down.disabled=p.scrollTop>=r-1}'
+        + 'function move(by){var p=pane();if(!p)return;p.scrollTop+=by;sync()}'
+        + 'function stop(){if(timer!==null){clearInterval(timer);timer=null}}'
+        + 'function press(e,by){e.preventDefault();e.stopPropagation();stop();move(by);'
+        + 'timer=setInterval(function(){move(by)},HOLD)}'
+        + 'function make(label,by){var b=document.createElement("button");b.type="button";'
+        + 'b.textContent=label;b.setAttribute("aria-label",by<0?"scroll up":"scroll down");'
+        + 'b.addEventListener("touchstart",function(e){press(e,by)},{passive:false});'
+        + 'b.addEventListener("touchend",function(e){e.preventDefault();stop()},{passive:false});'
+        + 'b.addEventListener("touchcancel",stop);'
+        + 'b.addEventListener("mousedown",function(e){press(e,by)});'
+        + 'b.addEventListener("mouseup",stop);b.addEventListener("mouseleave",stop);'
+        + 'b.addEventListener("click",function(e){e.preventDefault();e.stopPropagation()});'
+        + 'return b}'
+        + 'function start(){if(box)return;'
+        + 'box=document.createElement("div");box.id="__sc";'
+        + 'up=make("\\u25b2",-STEP);down=make("\\u25bc",STEP);'
+        + 'box.appendChild(up);box.appendChild(down);document.body.appendChild(box);'
+        + 'var p=pane();if(p&&p.addEventListener)p.addEventListener("scroll",sync,{passive:true});'
+        + 'if(typeof ResizeObserver==="function"){try{new ResizeObserver(sync).observe(document.body)}catch(e){}}'
+        + 'addEventListener("load",sync);sync()}'
+        + 'if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",start);else start();'
+        + 'window.__scrollControls={by:move,sync:sync};'
+        + '})();<' + '/script>'
+}
+
+export const autoHeight = ({ min = 60, max = 900, settleMs = 120, maxReports = 24 } = {}) => {
+    const low = Number(min)
+    const high = Number(max)
+    const wait = Number(settleMs)
+    const cap = Number(maxReports)
+    if (!Number.isFinite(low) || low <= 0) {
+        throw new TypeError('autoHeight min must be a positive number of pixels')
+    }
+    if (!Number.isFinite(high) || high <= low) {
+        throw new TypeError('autoHeight max must be greater than min')
+    }
+    if (!Number.isFinite(wait) || wait < 0) {
+        throw new TypeError('autoHeight settleMs must not be negative')
+    }
+    if (!Number.isFinite(cap) || cap < 1) {
+        throw new TypeError('autoHeight maxReports must be at least 1')
+    }
+    return '<style>html,body{margin:0;padding:0}</style>'
+        + '<script>(function(){'
+        + 'var LOW=' + low + ',HIGH=' + high + ',WAIT=' + wait + ',CAP=' + cap + ';'
+        + 'var sent=[],timer=null,stopped=false;'
+        + 'function measure(){var d=document.documentElement,b=document.body;'
+        + 'var h=Math.max(d?d.scrollHeight:0,b?b.scrollHeight:0,b?b.offsetHeight:0);'
+        + 'return Math.min(HIGH,Math.max(LOW,Math.ceil(h)))}'
+        + 'function report(){if(stopped)return;var h=measure();'
+        + 'if(sent.length&&sent[sent.length-1]===h)return;'
+        + 'if(sent.length>=2&&sent[sent.length-2]===h){stopped=true;return}'
+        + 'sent.push(h);if(sent.length>=CAP)stopped=true;'
+        + 'try{window.AndroidBridge.updateSize(h)}catch(e){stopped=true}}'
+        + 'function schedule(){if(stopped)return;'
+        + 'if(timer!==null)clearTimeout(timer);timer=setTimeout(function(){timer=null;report()},WAIT)}'
+        + 'function start(){report();'
+        + 'if(typeof ResizeObserver==="function"&&document.body){'
+        + 'try{new ResizeObserver(schedule).observe(document.body)}catch(e){}}'
+        + 'addEventListener("load",schedule)}'
+        + 'if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",start);else start();'
+        + '})();<' + '/script>'
+}
+
+export const htmlSection = (html, { trustedSources = [], height, typename = AI_RICH_HTML_PRIMITIVE } = {}) => {
+    if (typeof html !== 'string' || html.trim() === '') {
+        throw new TypeError('htmlSection requires a non-empty HTML string')
+    }
+    if (!Array.isArray(trustedSources)) {
+        throw new TypeError('htmlSection trustedSources must be an array of strings')
+    }
+    if (typeof typename !== 'string' || typename.trim() === '') {
+        throw new TypeError('htmlSection typename must be a non-empty string')
+    }
+    return AIRich.newLayout('Single', {
+        payload: height === undefined ? html : lockHeight(height) + html,
+        trusted_sources: trustedSources.map(String),
+        __typename: typename
+    })
+}
+
+export const sendHtmlApp = async (sock, jid, html, { title = '', label, trustedSources, height, autoHeight: auto, scrollButtons, typename, id, bypassDownload = false, guard = 'warn', ...options } = {}) => {
+    if (!sock) {
+        throw new TypeError('sendHtmlApp requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendHtmlApp requires a target jid')
+    }
+    if (auto && height !== undefined) {
+        throw new TypeError('sendHtmlApp takes either height or autoHeight, not both')
+    }
+
+    if (auto) {
+        html = autoHeight(auto === true ? undefined : auto) + html
+    }
+
+    if (scrollButtons) {
+        html += scrollControls(scrollButtons === true ? undefined : scrollButtons)
+    }
+
+    if (guard !== false) {
+        const report = checkHtmlApp(html, { height })
+        if (!report.ok && guard === true) {
+            throw new TypeError('this html app will not behave in the WebView:\n  ' + report.problems.join('\n  '))
+        }
+        if (guard === 'warn') {
+            for (const problem of report.problems) {
+                sock.logger?.warn({ jid }, 'html app: ' + problem)
+            }
+            for (const warning of report.warnings) {
+                sock.logger?.warn({ jid }, 'html app: ' + warning)
+            }
+        }
+    }
+
+    const rich = new AIRich(sock)
+
+    if (title) {
+        rich.setTitle(title)
+    }
+
+    rich._addContent(
+        htmlSection(html, { trustedSources, height, ...(typename ? { typename } : {}) }),
+        label ? { messageType: 2, messageText: String(label) } : undefined,
+        id ? { id } : {}
+    )
+
+    return rich.send(jid, { bypassDownload, ...options })
+}
+
+export const HTML_MIME_TYPE = 'text/html'
+
+export const sendHtmlDocument = async (sock, jid, html, { fileName = 'app.html', caption, ...options } = {}) => {
+    if (!sock) {
+        throw new TypeError('sendHtmlDocument requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendHtmlDocument requires a target jid')
+    }
+    if (typeof html !== 'string' || html.trim() === '') {
+        throw new TypeError('sendHtmlDocument requires a non-empty HTML string')
+    }
+    const name = String(fileName)
+    if (!/\.html?$/i.test(name)) {
+        throw new TypeError('sendHtmlDocument fileName must end with .html or .htm')
+    }
+    return sock.sendMessage(jid, {
+        document: Buffer.from(html, 'utf-8'),
+        mimetype: HTML_MIME_TYPE,
+        fileName: name,
+        ...(caption ? { caption: String(caption) } : {}),
+        ...options
+    })
+}
+
+const fileArtifact = (typename) => (url, { title = '', fileExtension = 'html', fileLength = 0, pageCount, previewImage } = {}) => {
+    if (typeof url !== 'string' || url.trim() === '') {
+        throw new TypeError('a file section requires a non-empty url')
+    }
+    return AIRich.newLayout('Single', trimEmpty({
+        title: String(title),
+        url,
+        file_extension: String(fileExtension).replace(/^\./, ''),
+        file_length: Number(fileLength) || 0,
+        page_count: pageCount === undefined ? undefined : Number(pageCount) || 0,
+        preview_image: previewImage,
+        __typename: typename
+    }))
+}
+
+export const fileSection = fileArtifact('GenAIFilePrimitive')
+export const fileLinkSection = fileArtifact('GenAIFileLinkPrimitive')
+
+const b64 = (value) => (value === undefined || value === null ? undefined : Buffer.isBuffer(value) || value instanceof Uint8Array ? Buffer.from(value).toString('base64') : String(value))
+
+export const botMediaMetadata = (documentMessage) => {
+    if (!documentMessage) {
+        throw new TypeError('botMediaMetadata requires a prepared document message')
+    }
+    return trimEmpty({
+        fileSha256: b64(documentMessage.fileSha256),
+        mediaKey: b64(documentMessage.mediaKey),
+        fileEncSha256: b64(documentMessage.fileEncSha256),
+        directPath: documentMessage.directPath,
+        mediaKeyTimestamp: documentMessage.mediaKeyTimestamp ? Number(documentMessage.mediaKeyTimestamp) : undefined,
+        mimetype: documentMessage.mimetype
+    })
+}
+
+export const prepareFileArtifact = async (sock, content, { mimetype = HTML_MIME_TYPE, fileName = 'app.html', title, id } = {}) => {
+    if (!sock) {
+        throw new TypeError('prepareFileArtifact requires a socket as the first argument')
+    }
+    const body = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content
+    if (!Buffer.isBuffer(body) && !(body instanceof Uint8Array)) {
+        throw new TypeError('prepareFileArtifact content must be a string or a buffer')
+    }
+
+    const prepared = await prepareWAMessageMedia(
+        { document: Buffer.from(body), mimetype, fileName },
+        { upload: sock.waUploadToServer }
+    )
+    const documentMessage = prepared.documentMessage
+    const media = botMediaMetadata(documentMessage)
+    const mediaId = id ?? randomUUID()
+
+    return {
+        mediaId,
+        media,
+        documentMessage,
+        section: AIRich.newLayout('Single', {
+            title: String(title || fileName),
+            url: documentMessage.url ?? '',
+            file_extension: fileName.includes('.') ? fileName.split('.').pop() : '',
+            file_length: Number(documentMessage.fileLength) || 0,
+            preview_image: {
+                media_id: mediaId,
+                mime_type: mimetype,
+                url: documentMessage.url ?? '',
+                url_fallback: ''
+            },
+            __typename: 'GenAIFilePrimitive'
+        }),
+        mediaDetails: { id: mediaId, previewMedia: media, highResMedia: media }
+    }
+}
+
+export const sendHtmlArtifact = async (sock, jid, html, { fileName = 'app.html', title, label, id, bypassDownload = false, ...options } = {}) => {
+    if (!jid) {
+        throw new TypeError('sendHtmlArtifact requires a target jid')
+    }
+
+    const artifact = await prepareFileArtifact(sock, html, { mimetype: HTML_MIME_TYPE, fileName, title, id })
+    const rich = new AIRich(sock)
+
+    if (title) {
+        rich.setTitle(title)
+    }
+    rich.setBotMetadata({ unifiedResponseMutation: { mediaDetailsMetadataList: [artifact.mediaDetails] } })
+    rich._addContent(
+        artifact.section,
+        label ? { messageType: 2, messageText: String(label) } : undefined,
+        {}
+    )
+
+    const message = await rich.send(jid, { bypassDownload, ...options })
+    return { message, mediaId: artifact.mediaId }
+}
+
+export const SourceProvider = Object.freeze({ UNKNOWN: 0, BING: 1, GOOGLE: 2, SUPPORT: 3, OTHER: 4 })
+
+export const botSourcesMetadata = (sources) => {
+    if (!Array.isArray(sources) || sources.length === 0) {
+        throw new TypeError('botSourcesMetadata requires a non-empty array of sources')
+    }
+    return {
+        sources: sources.map((source, index) => {
+            if (!source || typeof source !== 'object' || Array.isArray(source)) {
+                throw new TypeError('each source must be a plain object')
+            }
+            if (!source.url) {
+                throw new TypeError('each source requires a url')
+            }
+            return trimEmpty({
+                provider: source.provider ?? SourceProvider.OTHER,
+                sourceProviderUrl: String(source.url),
+                sourceTitle: source.title === undefined ? undefined : String(source.title),
+                sourceQuery: source.query === undefined ? undefined : String(source.query),
+                faviconCdnUrl: source.favicon === undefined ? undefined : String(source.favicon),
+                thumbnailCdnUrl: source.thumbnail === undefined ? undefined : String(source.thumbnail),
+                citationNumber: source.citation === undefined ? index + 1 : Number(source.citation)
+            })
+        })
+    }
+}
+
+export const EMBEDDED_SCREEN_PRESENTATION = Object.freeze({
+    HALF_HEIGHT: 'HALF_HEIGHT',
+    FULL_HEIGHT: 'FULL_HEIGHT'
+})
+
+export const EMBEDDED_SCREEN_TYPENAME = 'FOAUnifiedResponseEmbeddedScreen'
+export const EMBEDDED_SCREEN_TABBED_TYPENAME = 'FOAEmbeddedScreenContentTabbed'
+export const EMBEDDED_SCREEN_SINGLE_TYPENAME = 'FOAEmbeddedSingleScreen'
+export const EMBEDDED_SCREEN_CONTEXTUAL_TYPENAME = 'GenAIEmbeddedContextualScreenContent'
+export const EMBEDDED_SCREEN_TAB_TYPENAME = 'FOAUnifiedResponseTab'
+export const AI_RICH_SECTION_TYPENAME = AIRich.SECTION_TYPENAME
+export const AI_RICH_UNIFIED_RESPONSE_TYPENAME = AIRich.UNIFIED_RESPONSE_TYPENAME
+export const AI_RICH_UNIFIED_RESPONSE_TYPENAME_APP = 'GenAIUnifiedResponse'
+export const AI_RICH_NESTED_UNIFIED_RESPONSE_TYPENAME = 'GenAINestedUnifiedResponse'
+
+export const AI_RICH_NODES = Object.freeze([
+    'GenAIQuizQuestion',
+    'GenAIActionButton',
+    'GenAIFusedComparisonColumn',
+    'GenAIFusedComparisonRow',
+    'GenAIFusedComparisonCTA',
+    'FOAEmbeddedSingleScreen',
+    'GenAI3PAccountLinkingBottomsheet',
+    'GenAI3PExtArtifactConfirmation',
+    'GenAI3PExtCalendarAttendee',
+    'GenAI3PExtCalendarDateSection',
+    'GenAI3PExtCalendarEventList',
+    'GenAI3PExtConnectorPendingToolCall',
+    'GenAI3PExtWidgetCTA',
+    'GenAI3PExtWidgetStandardHeader',
+    'GenAI3PExtWidgetToast',
+    'GenAIAmericanFootballGameContent',
+    'GenAIChainOfThoughtStepMarkdownText',
+    'GenAICodeBlockData',
+    'GenAIEmbeddedContextualScreenContent',
+    'GenAIImaginePrimitiveStatusUpdate',
+    'GenAIImagineThumbnail',
+    'GenAIMapItemLocation',
+    'GenAIMapItemStaticMap',
+    'GenAIMarketplaceMetadata',
+    'GenAIMetaSubsQuotaUpsellButton',
+    'GenAINestedUnifiedResponse',
+    'GenAIP13nUiSignalValue',
+    'GenAIP13nUiSignals',
+    'GenAIPlaceDetailsItemCategory',
+    'GenAIPlaceDetailsItemOpeningHours',
+    'GenAIPlaceDetailsItemOpeningHoursTime',
+    'GenAIPlaceDetailsItemRating',
+    'GenAISearchPlannerInstruction',
+    'GenAISearchPlannerStep',
+    'GenAISoccerGameContent',
+    'GenAISportsTeamIcon',
+    'GenAISportsTeamRecord',
+    'GenAIStepDeepResearchEntry',
+    'GenAIStepSkillEntry',
+    'GenAIStepSubagentEntry',
+    'GenAIStepThoughtEntry',
+    'GenAIStepWebLinkSource',
+    'GenAITableCell',
+    'GenAITableRow',
+    'GenAITextInlineEntity',
+    'GenAIThreadSurfingPrompt',
+    'GenAIUnifiedResponse',
+    'GenAIVideoMusicClipInfo',
+    'GenAIVideoTextToSpeechInfo',
+    'GenAIWidgetPlacesItemAddress'
+])
+
+const readTypename = (label, value) => {
+    if (value === undefined) {
+        return undefined
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(label + ' typename must be a non-empty string')
+    }
+    return value
+}
+
+export const embeddedTab = ({ id, header, tabHeader, sections = [], typename } = {}) => {
+    if (!Array.isArray(sections)) {
+        throw new TypeError('embeddedTab sections must be an array of sections')
+    }
+    return trimEmpty({
+        __typename: readTypename('embeddedTab', typename),
+        id: id ?? randomUUID(),
+        header,
+        tab_header: tabHeader,
+        sections
+    })
+}
+
+export const embeddedTabbedContent = (tabs, { typename = EMBEDDED_SCREEN_TABBED_TYPENAME } = {}) => {
+    if (!Array.isArray(tabs)) {
+        throw new TypeError('embeddedTabbedContent tabs must be an array of tabs')
+    }
+    return { __typename: readTypename('embeddedTabbedContent', typename), tabs }
+}
+
+export const AI_RICH_RESPONSE_KEYS = Object.freeze([
+    'chunk_id', 'surface', 'product', 'thread_type', 'is_forwarded', 'is_optimistic', 'nested_responses'
+])
+
+export const embeddedScreen = ({ id, title, content, tabs, tabsTypename, typename, header, body, artifacts, steps, stepEntries, sources, pollId } = {}) => {
+    if (content !== undefined && !Array.isArray(content)) {
+        throw new TypeError('embeddedScreen content must be an array of sections')
+    }
+    if (tabs !== undefined && !Array.isArray(tabs)) {
+        throw new TypeError('embeddedScreen tabs must be an array of tabs')
+    }
+    for (const [name, value] of [['artifacts', artifacts], ['steps', steps], ['stepEntries', stepEntries], ['sources', sources]]) {
+        if (value !== undefined && !Array.isArray(value)) {
+            throw new TypeError('embeddedScreen ' + name + ' must be an array')
+        }
+    }
+    const entries = content === undefined ? [] : [...content]
+    if (tabs !== undefined) {
+        entries.push(embeddedTabbedContent(tabs, { typename: tabsTypename ?? EMBEDDED_SCREEN_TABBED_TYPENAME }))
+    }
+    return trimEmpty({
+        __typename: readTypename('embeddedScreen', typename),
+        id: id ?? randomUUID(),
+        title: title === undefined ? undefined : String(title),
+        content: entries.length ? entries : undefined,
+        header,
+        body,
+        artifacts,
+        steps,
+        step_entries: stepEntries,
+        sources,
+        poll_id: pollId
+    })
+}
+
+export const readEmbeddedTabs = (screen) => {
+    const tabs = []
+    if (Array.isArray(screen?.tabs)) {
+        tabs.push(...screen.tabs)
+    }
+    for (const entry of Array.isArray(screen?.content) ? screen.content : []) {
+        if (Array.isArray(entry?.tabs)) {
+            tabs.push(...entry.tabs)
+        }
+    }
+    return tabs
+}
+
+export const readEmbeddedSections = (screen) => {
+    const sections = []
+    for (const entry of Array.isArray(screen?.content) ? screen.content : []) {
+        if (entry?.view_model) {
+            sections.push(entry)
+            continue
+        }
+        for (const section of Array.isArray(entry?.sections) ? entry.sections : []) {
+            sections.push(section)
+        }
+    }
+    for (const tab of readEmbeddedTabs(screen)) {
+        for (const section of Array.isArray(tab?.sections) ? tab.sections : []) {
+            sections.push(section)
+        }
+    }
+    return sections
+}
+
+export const footerActionSection = (actionType, { buttonText = '', url } = {}) => {
+    if (!Object.values(FooterActionType).includes(actionType)) {
+        throw new TypeError('footerActionSection actionType must be one of ' + Object.values(FooterActionType).join(', '))
+    }
+    return AIRich.newLayout('Single', {
+        cta_text: String(buttonText),
+        cta_type: actionType,
+        ...(url ? { cta_url: String(url) } : {}),
+        __typename: 'GenAIFooterActionPrimitive'
+    })
+}
+
+export const BLOKS_A2UI_TYPE = 'im_a2ui'
+export const BLOKS_A2UI_REPLY_ACTION = 'a2ui_reply_action'
+export const BLOKS_A2UI_SUPPORTED_ELEMENTS = Object.freeze(['info_card', 'list_card'])
+
+const bloksPayloadData = (data) => {
+    if (data === undefined || data === null) {
+        return ''
+    }
+    if (typeof data === 'string') {
+        return data
+    }
+    if (typeof data !== 'object' || Array.isArray(data)) {
+        throw new TypeError('bloks data must be a JSON string or a plain object')
+    }
+    return JSON.stringify(data)
+}
+
+const bloksType = (type, caller) => {
+    if (typeof type !== 'string' || type.trim() === '') {
+        throw new TypeError(caller + ' requires a non-empty bloks type')
+    }
+    return type
+}
+
+export const bloksSection = (type, data, { uuid, initialResponse = '', versioningId = '' } = {}) =>
+    AIRich.newLayout('Single', {
+        type: bloksType(type, 'bloksSection'),
+        data: bloksPayloadData(data),
+        uuid: uuid ?? randomUUID(),
+        initial_response: String(initialResponse),
+        versioning_id: String(versioningId),
+        __typename: 'FOABloksPrimitive'
+    })
+
+export const bloksWidget = ({ type, data, uuid, fallback = '' } = {}) => ({
+    type: bloksType(type, 'bloksWidget'),
+    data: bloksPayloadData(data),
+    uuid: uuid ?? randomUUID(),
+    fallback: String(fallback)
+})
+
+export const A2UI_VERSION = 'v0.9'
+export const A2UI_BASIC_CATALOG = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json'
+export const A2UI_ROOT_ID = 'root'
+
+const a2uiNode = (component) => (id, extra = {}) => {
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new TypeError('every a2ui component needs a non-empty id')
+    }
+    return trimEmpty({ id, component, ...extra })
+}
+
+export const a2uiText = (id, text, { variant = 'body' } = {}) =>
+    a2uiNode('Text')(id, { text: String(text), variant })
+
+export const a2uiImage = (id, url, { variant = 'header', fit = 'cover' } = {}) => {
+    if (typeof url !== 'string' || url.trim() === '') {
+        throw new TypeError('a2uiImage requires a url')
+    }
+    return a2uiNode('Image')(id, { url, variant, fit })
+}
+
+const a2uiContainer = (component) => (id, children = []) => {
+    if (!Array.isArray(children)) {
+        throw new TypeError('a2ui container children must be an array of component ids')
+    }
+    return a2uiNode(component)(id, { children: children.map(String) })
+}
+
+export const a2uiColumn = a2uiContainer('Column')
+export const a2uiRow = a2uiContainer('Row')
+
+export const a2uiCard = (id, child) => {
+    if (typeof child !== 'string' || child.trim() === '') {
+        throw new TypeError('a2uiCard takes the id of one child component, not an array')
+    }
+    return a2uiNode('Card')(id, { child })
+}
+
+const a2uiElement = (type) => (element = {}) => {
+    if (element === null || typeof element !== 'object' || Array.isArray(element)) {
+        throw new TypeError('a2ui ' + type + ' element must be a plain object')
+    }
+    return { type, ...element }
+}
+
+export const a2uiInfoCard = a2uiElement('info_card')
+export const a2uiListCard = a2uiElement('list_card')
+
+const A2UI_FALLBACK_KEYS = Object.freeze(['text', 'title', 'label', 'body'])
+
+export const a2uiFallback = (components) => {
+    const list = Array.isArray(components)
+        ? components
+        : (components && typeof components === 'object' ? [components] : [])
+    return list
+        .map(component => A2UI_FALLBACK_KEYS
+            .map(key => component?.[key])
+            .find(value => typeof value === 'string' && value.trim() !== '') ?? '')
+        .filter(Boolean)
+        .join('\n')
+}
+
+export const a2uiSurface = (components, { surfaceId, root = A2UI_ROOT_ID, catalogId, sendDataModel, version = A2UI_VERSION, type, title } = {}) => {
+    if (!Array.isArray(components) || components.length === 0) {
+        throw new TypeError('a2uiSurface requires at least one component')
+    }
+    if (!components.some(component => component?.id === root)) {
+        throw new TypeError('a2ui components must include one with id "' + root + '" to serve as the root')
+    }
+    return trimEmpty({
+        version,
+        type,
+        title,
+        createSurface: trimEmpty({
+            surfaceId: surfaceId ?? 'card-' + randomUUID(),
+            root,
+            catalogId,
+            sendDataModel: sendDataModel === undefined ? undefined : !!sendDataModel,
+            components
+        })
+    })
+}
+
+export const a2uiWidget = (components, { uuid, surfaceId, root, catalogId, sendDataModel, version, type, title, fallback, data } = {}) => {
+    const id = uuid ?? randomUUID()
+    const payload = data ?? a2uiSurface(components, { surfaceId: surfaceId ?? 'card-' + id, root, catalogId, sendDataModel, version, type, title })
+    return bloksWidget({
+        type: BLOKS_A2UI_TYPE,
+        uuid: id,
+        fallback: fallback === undefined ? a2uiFallback(Array.isArray(components) && components.length ? components : payload) : fallback,
+        data: payload
+    })
+}
+
+export const sendA2UI = async (sock, jid, components, { buttons = [], contextInfo, messageId, additionalNodes = [], ...options } = {}) => {
+    if (!sock) {
+        throw new TypeError('sendA2UI requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendA2UI requires a target jid')
+    }
+    if (!Array.isArray(buttons)) {
+        throw new TypeError('sendA2UI buttons must be an array of native flow buttons')
+    }
+
+    const widget = a2uiWidget(components, options)
+    const text = widget.fallback
+
+    const msg = generateWAMessageFromContent(
+        jid,
+        {
+            interactiveMessage: trimEmpty({
+                nativeFlowMessage: { buttons, messageParamsJson: JSON.stringify({}), messageVersion: 1 },
+                bloksWidget: widget,
+                ...(text ? { body: { text } } : {}),
+                contextInfo
+            })
+        },
+        { messageId, ...options }
+    )
+
+    await sock.relayMessage(msg.key.remoteJid, msg.message, {
+        messageId: msg.key.id,
+        additionalNodes: [
+            {
+                tag: 'biz',
+                attrs: {},
+                content: [{ tag: 'interactive', attrs: { type: 'native_flow', v: '1' }, content: [{ tag: 'native_flow', attrs: { v: '9', name: 'mixed' } }] }]
+            },
+            ...additionalNodes
+        ],
+        ...options
+    })
+
+    return msg
+}
+
+export const buildA2UISection = (components, { uuid, surfaceId, root, catalogId, sendDataModel, version, type, title, data, initialResponse, versioningId } = {}) =>
+    bloksSection(
+        BLOKS_A2UI_TYPE,
+        data ?? a2uiSurface(components, { surfaceId, root, catalogId, sendDataModel, version, type, title }),
+        { uuid, initialResponse, versioningId }
+    )
+
+export const sendA2UIBloks = async (sock, jid, components, { uuid, surfaceId, root, catalogId, sendDataModel, version, type, title, data, initialResponse, versioningId, ...options } = {}) => {
+    if (!sock) {
+        throw new TypeError('sendA2UIBloks requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendA2UIBloks requires a target jid')
+    }
+
+    const rich = new AIRich(sock)
+    rich.addSection(buildA2UISection(components, { uuid, surfaceId, root, catalogId, sendDataModel, version, type, title, data, initialResponse, versioningId }))
+
+    return rich.send(jid, options)
+}
+
+export const AI_RICH_SUBMESSAGE_TEXT = 2
+export const AI_RICH_SUBMESSAGE_INLINE_IMAGE = 3
+export const AI_RICH_SUBMESSAGE_TABLE = 4
+export const AI_RICH_SUBMESSAGE_CONTENT_ITEMS = 9
+
+const AIRICH_TYPENAME = 'FOABloksPrimitive'
+
+const AI_RICH_SUBMESSAGE_FACTORIES = Object.freeze({
+    text: (text) => ({
+        messageType: AI_RICH_SUBMESSAGE_TEXT,
+        messageText: String(text)
+    }),
+    inline_image: ({ previewUrl, highResUrl, sourceUrl, text = '', alignment, tapLinkUrl } = {}) => {
+        if (typeof previewUrl !== 'string' || previewUrl.trim() === '') {
+            throw new TypeError('inline_image requires a previewUrl')
+        }
+        return {
+            messageType: AI_RICH_SUBMESSAGE_INLINE_IMAGE,
+            imageMetadata: trimEmpty({
+                imageUrl: trimEmpty({
+                    imagePreviewUrl: previewUrl,
+                    imageHighResUrl: highResUrl,
+                    sourceUrl
+                }),
+                imageText: text,
+                alignment,
+                tapLinkUrl
+            })
+        }
+    },
+    table: ({ rows, title } = {}) => {
+        if (!Array.isArray(rows) || rows.length === 0) {
+            throw new TypeError('table requires a non-empty rows array')
+        }
+        return {
+            messageType: AI_RICH_SUBMESSAGE_TABLE,
+            tableMetadata: trimEmpty({
+                rows: rows.map(row => ({ items: row.items.map(String), isHeading: !!row.isHeading })),
+                title
+            })
+        }
+    },
+    content_items: ({ items, ...rest } = {}) => {
+        if (!Array.isArray(items) || items.length === 0) {
+            throw new TypeError('content_items requires a non-empty items array')
+        }
+        return {
+            messageType: AI_RICH_SUBMESSAGE_CONTENT_ITEMS,
+            contentItemsMetadata: { ...rest, items }
+        }
+    }
+})
+
+export const AI_RICH_SUBMESSAGE_KINDS = Object.freeze(Object.keys(AI_RICH_SUBMESSAGE_FACTORIES))
+
+export const aiRichSubmessage = (kind, payload = {}) => {
+    const factory = AI_RICH_SUBMESSAGE_FACTORIES[kind]
+
+    if (!factory) {
+        throw new TypeError('unknown AIRich submessage kind "' + kind + '"; expected one of ' + AI_RICH_SUBMESSAGE_KINDS.join(', '))
+    }
+
+    return factory(payload)
+}
+
+export const aiRichText = (text) => aiRichSubmessage('text', text)
+
+export const aiRichInlineImage = (image) => aiRichSubmessage('inline_image', image)
+
+export const aiRichTable = (table) => aiRichSubmessage('table', table)
+
+export const aiRichContentItems = (content) => aiRichSubmessage('content_items', content)
+
+export const AIRichMessage = {
+    SUBMESSAGE_KINDS: AI_RICH_SUBMESSAGE_KINDS,
+    text: aiRichText,
+    inlineImage: aiRichInlineImage,
+    table: aiRichTable,
+    contentItems: aiRichContentItems,
+    submessage: aiRichSubmessage,
+    textSection: (text) => AIRich.newLayout('Single', {
+        __typename: AIRICH_TYPENAME,
+        messageText: String(text)
+    }),
+    nativeFlowSection: (name, params, { uuid, initialResponse = '', versioningId = '' } = {}) =>
+        bloksSection(name, params, { uuid, initialResponse, versioningId })
+}
+
+export const sendAIRichMessage = async (
+    sock,
+    jid,
+    { sections = [], text, nativeFlow, submessages = [], forwardWrapper, ...options } = {}
+) => {
+    if (!sock) {
+        throw new TypeError('sendAIRichMessage requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendAIRichMessage requires a target jid')
+    }
+
+    const rich = new AIRich(sock)
+    let sectionCount = 0
+
+    if (text !== undefined && text !== null && String(text) !== '') {
+        rich.addSection(AIRichMessage.textSection(text))
+        sectionCount += 1
+    }
+    for (const section of sections) {
+        rich.addSection(section)
+        sectionCount += 1
+    }
+    if (nativeFlow !== undefined) {
+        if (!nativeFlow || typeof nativeFlow !== 'object') {
+            throw new TypeError('sendAIRichMessage nativeFlow must be { name, params }')
+        }
+        rich.addSection(AIRichMessage.nativeFlowSection(nativeFlow.name, nativeFlow.params ?? {}))
+        sectionCount += 1
+    }
+    for (const submessage of submessages) {
+        rich.addSubmessage(submessage)
+    }
+    if (sectionCount === 0 && !submessages.length) {
+        throw new TypeError('sendAIRichMessage needs at least one section, text, nativeFlow, or submessage')
+    }
+
+    return rich.send(jid, { ...(forwardWrapper === undefined ? {} : { forwardWrapper }), ...options })
+}
+
+export const sendBloksWidget = async (sock, jid, { type, data, uuid, fallback = '', body, contextInfo, messageId, additionalNodes = [], ...options } = {}) => {
+    if (!sock) {
+        throw new TypeError('sendBloksWidget requires a socket as the first argument')
+    }
+    if (!jid) {
+        throw new TypeError('sendBloksWidget requires a target jid')
+    }
+
+    const widget = bloksWidget({ type, data, uuid, fallback })
+    const text = body === undefined ? widget.fallback : String(body)
+
+    const msg = generateWAMessageFromContent(
+        jid,
+        {
+            interactiveMessage: {
+                bloksWidget: widget,
+                ...(text ? { body: { text } } : {}),
+                ...(contextInfo ? { contextInfo } : {})
+            }
+        },
+        { messageId, ...options }
+    )
+
+    await sock.relayMessage(msg.key.remoteJid, msg.message, {
+        messageId: msg.key.id,
+        additionalNodes: [
+            {
+                tag: 'biz',
+                attrs: {},
+                content: [{ tag: 'interactive', attrs: { type: 'native_flow', v: '1' }, content: [{ tag: 'native_flow', attrs: { v: '9', name: 'mixed' } }] }]
+            },
+            ...additionalNodes
+        ],
+        ...options
+    })
+
+    return msg
+}
+
+export const decodeBloksWidget = (msg) => {
+    const message = msg?.message ?? msg
+    const interactive =
+        message?.interactiveMessage ??
+        message?.viewOnceMessage?.message?.interactiveMessage ??
+        message?.viewOnceMessageV2?.message?.interactiveMessage
+
+    const widget = interactive?.bloksWidget
+    if (!widget) {
+        return null
+    }
+
+    let params = null
+    try {
+        params = widget.data ? JSON.parse(widget.data) : null
+    }
+    catch {
+        params = null
+    }
+
+    return {
+        type: widget.type ?? '',
+        uuid: widget.uuid ?? '',
+        fallback: widget.fallback ?? '',
+        data: widget.data ?? '',
+        params
+    }
+}
+
+export const collectTypenames = (root, { limit = 20000 } = {}) => {
+    const found = new Set()
+    const stack = [root]
+    let seen = 0
+
+    while (stack.length && seen < limit) {
+        const node = stack.pop()
+        seen++
+        if (Array.isArray(node)) {
+            for (const entry of node) {
+                if (entry && typeof entry === 'object') {
+                    stack.push(entry)
+                }
+            }
+            continue
+        }
+        if (!node || typeof node !== 'object') {
+            continue
+        }
+        if (typeof node.__typename === 'string' && node.__typename) {
+            found.add(node.__typename)
+        }
+        for (const value of Object.values(node)) {
+            if (value && typeof value === 'object') {
+                stack.push(value)
+            }
+        }
+    }
+
+    return [...found].sort()
+}
+
+export const decodeAIRich = (msg) => {
+    const message = msg?.message ?? msg
+    const rich =
+        message?.botForwardedMessage?.message?.richResponseMessage ??
+        message?.botForwardedMessage?.richResponseMessage ??
+        message?.richResponseMessage
+
+    if (!rich) {
+        return null
+    }
+
+    let unified = null
+    const data = rich.unifiedResponse?.data
+    if (data) {
+        try {
+            unified = JSON.parse(Buffer.from(data, 'base64').toString('utf-8'))
+        }
+        catch {
+            unified = null
+        }
+    }
+
+    const sections = Array.isArray(unified?.sections) ? unified.sections : []
+    const footerSections = Array.isArray(unified?.footer_sections) ? unified.footer_sections : []
+    const embeddedScreens = Array.isArray(unified?.embedded_screens) ? unified.embedded_screens : []
+
+    const readPrimitives = (section) => {
+        const view = section?.view_model
+        if (Array.isArray(view?.primitives)) return view.primitives
+        if (view?.primitive) return [view.primitive]
+        return []
+    }
+
+    return {
+        responseId: unified?.response_id,
+        layouts: sections.map(section => String(section?.view_model?.__typename ?? '').replace(/^GenAI(.*)LayoutViewModel$/, '$1')),
+        typenames: [...new Set(sections.flatMap(section => readPrimitives(section).map(primitive => primitive?.__typename).filter(Boolean)))],
+        footerTypenames: [...new Set(footerSections.flatMap(section => readPrimitives(section).map(primitive => primitive?.__typename).filter(Boolean)))],
+        allTypenames: collectTypenames(unified),
+        sections,
+        footerSections,
+        embeddedScreens,
+        embeddedTabs: embeddedScreens.flatMap(readEmbeddedTabs),
+        embeddedSections: embeddedScreens.flatMap(readEmbeddedSections),
+        submessages: rich.submessages ?? [],
+        unified
+    }
+}
+
+const A2UI_TEXT_KEYS = Object.freeze(['text', 'label', 'title'])
+
+const readPrimitiveText = (primitive) => {
+    if (!primitive || typeof primitive !== 'object') {
+        return ''
+    }
+    if (typeof primitive.text === 'string') {
+        return primitive.text
+    }
+    if (typeof primitive.title === 'string') {
+        return primitive.title
+    }
+    return ''
+}
+
+const readA2UIText = (components) => components
+    .filter(component => component?.component === 'Text' || component?.component === 'Heading')
+    .map(component => A2UI_TEXT_KEYS.map(key => component[key]).find(value => typeof value === 'string') ?? '')
+    .filter(Boolean)
+
+const parseBloksParams = (data) => {
+    if (!data || typeof data !== 'string') {
+        return null
+    }
+    try {
+        return JSON.parse(data)
+    }
+    catch {
+        return null
+    }
+}
+
+export const readRichMessage = (msg) => {
+    const raw = msg?.message ?? msg
+    if (!raw || typeof raw !== 'object') {
+        return null
+    }
+
+    const content = extractMessageContent(raw) ?? raw
+    const rich = decodeAIRich(raw)
+    const widget = decodeBloksWidget(raw)
+    const interactive =
+        content?.interactiveMessage ??
+        raw?.interactiveMessage ??
+        raw?.viewOnceMessage?.message?.interactiveMessage ??
+        raw?.viewOnceMessageV2?.message?.interactiveMessage
+
+    if (!rich && !widget && !interactive) {
+        return null
+    }
+
+    const buttons = (interactive?.nativeFlowMessage?.buttons ?? []).map(button => {
+        let params = null
+        try {
+            params = button?.buttonParamsJson ? JSON.parse(button.buttonParamsJson) : null
+        }
+        catch {
+            params = null
+        }
+        return { name: button?.name ?? '', params }
+    })
+
+    const isA2UIWidget = widget?.type === BLOKS_A2UI_TYPE
+
+    const sectionPrimitives = sections => sections.flatMap(section => {
+        const view = section?.view_model
+        if (Array.isArray(view?.primitives)) return view.primitives
+        return view?.primitive ? [view.primitive] : []
+    })
+
+    const primitives = sectionPrimitives(rich?.sections ?? [])
+    const embeddedPrimitives = sectionPrimitives(rich?.embeddedSections ?? [])
+
+    const richBloks = primitives.find(primitive => primitive?.__typename === 'FOABloksPrimitive' && primitive?.type === BLOKS_A2UI_TYPE)
+    const a2uiParams = isA2UIWidget ? widget.params : parseBloksParams(richBloks?.data)
+    const surface = a2uiParams?.createSurface
+    const a2uiComponents = Array.isArray(surface?.components) ? surface.components : []
+    const a2uiElement = !surface && a2uiParams && typeof a2uiParams === 'object' ? a2uiParams : undefined
+    const isA2UI = isA2UIWidget || !!richBloks
+
+    const a2uiTextLines = readA2UIText(a2uiComponents)
+    const bodyText = interactive?.body?.text ?? ''
+    const widgetFallback = widget?.fallback ?? ''
+    const bodyDuplicatesWidget = bodyText !== '' && bodyText === widgetFallback
+
+    const lines = [
+        ...primitives.filter(primitive => primitive !== richBloks).map(readPrimitiveText),
+        ...a2uiTextLines,
+        bodyDuplicatesWidget && a2uiTextLines.length ? '' : bodyText,
+        interactive?.footer?.text ?? ''
+    ].filter(Boolean)
+
+    const kind = isA2UI ? 'a2ui' : widget ? 'bloks' : rich ? 'airich' : 'interactive'
+
+    return trimEmpty({
+        kind,
+        text: lines.join('\n'),
+        title: raw?.messageContextInfo?.botMetadata?.messageDisclaimerText || interactive?.header?.title || '',
+        buttons,
+        html: [...primitives, ...embeddedPrimitives].filter(p => typeof p?.payload === 'string').map(p => p.payload),
+        typenames: rich?.typenames ?? [],
+        sections: rich?.sections ?? [],
+        footerSections: rich?.footerSections ?? [],
+        embeddedScreens: rich?.embeddedScreens ?? [],
+        embeddedTabs: rich?.embeddedTabs ?? [],
+        submessages: rich?.submessages ?? [],
+        responseId: rich?.responseId,
+        a2ui: isA2UI
+            ? trimEmpty({
+                surfaceId: surface?.surfaceId,
+                root: surface?.root,
+                catalogId: surface?.catalogId,
+                version: a2uiParams?.version,
+                type: a2uiParams?.type,
+                components: a2uiComponents.length ? a2uiComponents : undefined,
+                element: a2uiElement
+            })
+            : undefined,
+        bloks: widget ? { type: widget.type, uuid: widget.uuid, fallback: widget.fallback, params: widget.params } : undefined
+    })
+}