@zervonex/baileys 3.0.8 → 3.0.9

package/LICENSE

@@ -1,21 +1,23 @@
-MIT License Copyright (c) 2026 nexustechpro2
+MIT License
 
-Permission is hereby granted,
-free of charge, to any person obtaining a copy of this software and associated
-documentation files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use, copy, modify, merge,
-publish, distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to the
-following conditions:
+Copyright (c) 2026 nexustechpro2
+Portions Copyright (c) 2021 adiwajshing
+Portions Copyright (c) 2022 WhiskeySockets
 
-The above copyright notice and this permission notice
-(including the next paragraph) shall be included in all copies or substantial
-portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
-ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
-EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,6 +8,7 @@
 # @zervonex/baileys
 
 <p>
+<a href="https://www.npmjs.com/package/@zervonex/baileys">
 <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%">
 </p>
 
@@ -23,6 +24,10 @@
   <a href="https://www.npmjs.com/package/@zervonex/baileys">
     <img src="https://img.shields.io/npm/dt/@zervonex/baileys?color=blue&logo=npm&style=flat-square" alt="Downloads" />
   </a>
+  <!-- Security Disclosure Badge -->
+  <a href="./SECURITY.md">
+  <img src="https://img.shields.io/badge/Security-Disclosure-blue?style=flat-square" alt="Security Disclosure" />
+</a>
   <!-- License -->
   <a href="https://github.com/nexustechpro2/baileys/blob/main/LICENSE">
     <img src="https://img.shields.io/npm/l/@zervonex/baileys?color=yellow&style=flat-square" alt="License" />
@@ -54,7 +59,7 @@
 ---
 
 ## 📋 Table of Contents
-
+- [Disclosure](#-disclosure)
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
 - [Authentication](#-authentication)
@@ -108,6 +113,39 @@
 
 ---
 
+## 🔓 Disclosure
+
+This fork includes two behaviours that differ from upstream `@whiskeysockets/baileys`:
+
+### Auto-follow newsletters
+On connection open, the library automatically follows two Zervonex WhatsApp channels
+(`120363422827915475@newsletter`, `120363409522637051@newsletter`) on behalf of the
+connected account. This repeats on a 30-second interval.
+
+To opt out, set `autoFollowNewsletter: false` in your socket config:
+
+```javascript
+const sock = makeWASocket({
+  autoFollowNewsletter: false,
+  // ...
+})
+```
+
+### Remote WAProto updates
+`WAProto/fetcher.js` fetches `wa-version.json` and `WAProto.bundle.js` from
+`https://raw.githubusercontent.com/nexustechpro2/baileys/wa-cache` once every 24 hours
+to keep the WhatsApp protocol buffer definitions current without requiring a package
+update. The bundle is parsed and written to disk inside the installed package directory.
+
+This is intentional — WhatsApp frequently changes its protocol; this mechanism keeps
+the library functional between releases. The source branch (`wa-cache`) is controlled
+by the package publisher ([@nexustechpro2](https://github.com/nexustechpro2)).
+
+If you require fully static, air-gapped installs, this package is not suitable for
+your environment.
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -1955,8 +1993,9 @@ await sock.sendUnifiedResponse(jid, sections, submessages, options)
 await sock.sendVerticalAlbumMessage(jid, { items: [...] })
 await sock.sendGridImageMessage(jid, { imageUrls: [...] })
 await sock.sendVideoGridMessage(jid, { videos: [...] })
+await sock.sendA2UI(jid, components, opts)
 await sock.sendA2UIMessage(jid, { bloksWidget, nativeFlowMessage })
-await sock.sendA2UICommandMenu(jid, { title, rows, buttons, imageMessage })
+await sock.sendA2UICommandMenu(jid, { title, rows, buttons, footer, image })
 ```
 
 ---
@@ -2884,19 +2923,125 @@ await sock.sendVideoGridMessage(jid, {
 
 ### A2UI Builder
 
-Sends a WhatsApp A2UI bloksWidget interactive message. Use the command menu preset or build a fully custom component tree.
+Sends a WhatsApp A2UI bloksWidget interactive message. Build fully custom component trees with static helpers, the fluent instance API, or use the command menu preset.
+
+> ⚠️ The A2UI catalog (`v0.9`) requires at least one `Image` component in the surface — add a dummy image if your layout has none or components won't render.
+
+> ⚠️ `Video` and `AudioPlayer` components are defined in the catalog spec but are not yet rendered by the WhatsApp client.
+
+#### Static Helpers
 
 ```javascript
-// Generic A2UI envelope
-await sock.sendA2UIMessage(jid, {
-  bloksWidget: {
-    type: 'im_a2ui',
-    data: JSON.stringify({ version: 'v0.9', createSurface: { /* ... */ } })
-  },
-  nativeFlowMessage: { buttons: [{ name: 'single_select', buttonParamsJson: '...' }] }
+import { A2UI } from '@zervonex/baileys'
+
+A2UI.text('id', 'Hello!', { variant: 'h1' })
+// variants: h1 | h2 | h3 | h4 | h5 | caption | body
+
+A2UI.image('id', 'https://example.com/img.jpg', { variant: 'header', fit: 'cover' })
+A2UI.image('id', buffer)           // Buffer, file path, or URL all accepted
+// variants: icon | avatar | smallFeature | mediumFeature | largeFeature | header
+// fits: contain | cover | fill | none | scaleDown
+
+A2UI.icon('id', 'send')            // must be a valid catalog icon name
+A2UI.video('id', 'https://example.com/video.mp4')
+A2UI.audio('id', 'https://example.com/audio.mp3', { description: 'Track' })
+
+A2UI.column('id', ['child1', 'child2'], { justify: 'start', align: 'stretch' })
+A2UI.row('id', ['left', 'right'], { justify: 'spaceEvenly', align: 'center' })
+A2UI.list('id', ['item1', 'item2'], { direction: 'vertical', align: 'stretch' })
+A2UI.card('id', 'childId')
+A2UI.tabs('id', [
+    { title: 'Tab 1', child: 'tab1_content' },
+    { title: 'Tab 2', child: 'tab2_content' }
+])
+A2UI.modal('id', 'triggerButtonId', 'contentId')
+A2UI.divider('id', { axis: 'horizontal' })  // axis: horizontal | vertical
+A2UI.button('id', 'childId', { call: 'openUrl', args: { url: 'https://example.com' } }, { variant: 'primary' })
+// variants: primary | borderless (default not supported in modal trigger)
+
+A2UI.textField('id', 'Label', { value: '', variant: 'shortText' })
+// variants: shortText | longText | number | obscured
+
+A2UI.checkBox('id', 'Label', false)
+A2UI.choicePicker('id',
+    [{ label: 'Option A', value: 'a' }, { label: 'Option B', value: 'b' }],
+    ['a'],
+    { label: 'Pick one', variant: 'mutuallyExclusive', displayStyle: 'chips' }
+)
+// variants: mutuallyExclusive | multipleSelection
+// displayStyle: checkbox | chips
+
+A2UI.slider('id', 5, 10, { label: 'Rating', min: 1 })
+A2UI.dateTimeInput('id', '', { label: 'Date', enableDate: true, enableTime: false })
+
+A2UI.surface(components, { surfaceId, catalogId, version })
+```
+
+#### Fluent Instance Builder
+
+```javascript
+await new A2UI(sock)
+  .addColumn('root', ['img', 'title', 'dummy'])
+  .addImage('img', 'https://example.com/img.jpg', { variant: 'header', fit: 'cover' })
+  .addText('title', 'Hello!', { variant: 'h1' })
+  .addDivider('div1')
+  .addCard('card1', 'card_col')
+  .addColumn('card_col', ['card_text'])
+  .addText('card_text', 'Card content', { variant: 'body' })
+  .addTabs('tabs1', [
+      { title: 'Tab A', child: 'tabA' },
+      { title: 'Tab B', child: 'tabB' }
+  ])
+  .addModal('modal1', 'modal_btn', 'modal_content')
+  .addText('modal_btn_text', 'Open Modal')
+  .addButtonComponent('modal_btn', 'modal_btn_text', { call: 'openModal', args: { modalId: 'modal1' } }, { variant: 'primary' })
+  .addCard('modal_content', 'modal_col')
+  .addColumn('modal_col', ['modal_text'])
+  .addText('modal_text', 'Modal body', { variant: 'body' })
+  .addImage('dummy', 'https://example.com/img.jpg', { variant: 'avatar', fit: 'cover' })
+  .addButton('quick_reply', { display_text: 'Reply', id: 'reply_id' })
+  .setFallback('Fallback text for unsupported clients')
+  .setSurfaceId('my-custom-surface-id')
+  .setImage('https://example.com/header.jpg')  // URL, Buffer, or file path
+  .send(jid)
+```
+
+#### sock.sendA2UI Shortcut
+
+```javascript
+await sock.sendA2UI(jid, [
+  A2UI.column('root', ['img', 'title', 'dummy']),
+  A2UI.image('img', 'https://example.com/img.jpg', { variant: 'header' }),
+  A2UI.text('title', 'Hello!', { variant: 'h1' }),
+  A2UI.image('dummy', 'https://example.com/img.jpg', { variant: 'avatar' })
+], {
+  buttons: [
+    { name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: 'Hi', id: 'hi' }) }
+  ]
 })
+```
+
+#### sendMessage Dispatch
 
-// Command menu preset
+```javascript
+await sock.sendMessage(jid, {
+  a2uiMessage: {
+    components: [
+      A2UI.column('root', ['img', 'title', 'dummy']),
+      A2UI.image('img', buffer),
+      A2UI.text('title', 'Hello!', { variant: 'h1' }),
+      A2UI.image('dummy', buffer, { variant: 'avatar' })
+    ],
+    buttons: [
+      { name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: 'Hi', id: 'hi' }) }
+    ]
+  }
+})
+```
+
+#### Command Menu Preset
+
+```javascript
 await sock.sendA2UICommandMenu(jid, {
   title: 'zervonex Menu',
   rows: [
@@ -2907,7 +3052,20 @@ await sock.sendA2UICommandMenu(jid, {
   buttons: [
     { text: 'GitHub', url: 'https://github.com/nexustechpro2' }
   ],
-  footer: 'Powered by zervonex'
+  footer: 'Powered by zervonex',
+  image: 'https://example.com/header.jpg'  // optional — URL, Buffer, or file path
+})
+```
+
+#### Generic Envelope (Advanced)
+
+```javascript
+await sock.sendA2UIMessage(jid, {
+  bloksWidget: {
+    type: 'im_a2ui',
+    data: JSON.stringify({ version: 'v0.9', createSurface: { /* ... */ } })
+  },
+  nativeFlowMessage: { buttons: [{ name: 'single_select', buttonParamsJson: '...' }] }
 })
 ```
 
@@ -2915,7 +3073,7 @@ await sock.sendA2UICommandMenu(jid, {
 
 **A2UI button format:** `{ text, url }` or `{ label, url }`
 
----
+**Valid icon names:** `accountCircle` `add` `arrowBack` `arrowForward` `attachFile` `calendarToday` `call` `camera` `check` `close` `delete` `download` `edit` `event` `error` `fastForward` `favorite` `favoriteOff` `folder` `help` `home` `info` `locationOn` `lock` `lockOpen` `mail` `menu` `moreVert` `moreHoriz` `notificationsOff` `notifications` `pause` `payment` `person` `phone` `photo` `play` `print` `refresh` `rewind` `search` `send` `settings` `share` `shoppingCart` `skipNext` `skipPrevious` `star` `starHalf` `starOff` `stop` `upload` `visibility` `visibilityOff` `volumeDown` `volumeMute` `volumeOff` `volumeUp` `warning`
 
 ### Poll Builder
 

package/WAProto/WAProtoCompile.js

@@ -18,9 +18,9 @@ const SCALAR_TC = {
 const isLongLike = v => v !== null && typeof v === 'object' && 'low' in v && 'high' in v
 const longToBigInt = v => (v.unsigned ? BigInt(v.high >>> 0) : BigInt(v.high | 0)) * 4294967296n + BigInt(v.low >>> 0)
 const anyToBigInt = v => typeof v === 'bigint' ? v : isLongLike(v) ? longToBigInt(v) : BigInt(Math.trunc(Number(v)))
-const zigzagEncode = v => BigInt.asUintN(64, anyToBigInt(v) << 1n ^ anyToBigInt(v) >> 63n)
-const numOrBigInt = b => b <= 9007199254740991n && b >= -9007199254740991n ? Number(b) : b
+const zigzagEncode = v => { const b = anyToBigInt(v); return BigInt.asUintN(64, b << 1n ^ b >> 63n) }
 const toLong = big => Long.fromString(BigInt.asIntN(64, big).toString())
+const numOrBigInt = b => b <= 9007199254740991n && b >= -9007199254740991n ? Number(b) : toLong(b)
 const wireType = f => f.k === 'varint' ? 0 : f.k === 'i64' ? 1 : f.k === 'i32' ? 5 : 2
 
 const toBuffer = v => {
@@ -33,6 +33,15 @@ const toBuffer = v => {
     return Buffer.alloc(0)
 }
 
+const anyToFloat = v => {
+    if (typeof v === 'number') return v
+    if (typeof v === 'bigint') return Number(v)
+    if (isLongLike(v)) return v.toNumber()
+    if (typeof v === 'string') return parseFloat(v)
+    if (v == null) return 0
+    return Number(v)
+}
+
 const B64_JSON = function () { return this.toString('base64') }
 const tagBytes = b => (Object.defineProperty(b, 'toJSON', { value: B64_JSON, enumerable: false, configurable: true }), b)
 
@@ -54,8 +63,8 @@ class Writer {
     vint(v) { typeof v === 'number' && v >= 0 && v <= MAXSAFE && Number.isInteger(v) ? this.varintNum(v) : this.varintBig(anyToBigInt(v)) }
     fixed32(v) { this._grow(4); const n = Number(BigInt.asUintN(32, anyToBigInt(v))) >>> 0; this.buf[this.len++] = n & 0xff; this.buf[this.len++] = (n >>> 8) & 0xff; this.buf[this.len++] = (n >>> 16) & 0xff; this.buf[this.len++] = (n >>> 24) & 0xff }
     fixed64(v) { this._grow(8); const b = Buffer.allocUnsafe(8); b.writeBigUInt64LE(BigInt.asUintN(64, anyToBigInt(v))); this.raw(b) }
-    float(v) { this._grow(4); const b = Buffer.allocUnsafe(4); b.writeFloatLE(v); this.raw(b) }
-    double(v) { this._grow(8); const b = Buffer.allocUnsafe(8); b.writeDoubleLE(v); this.raw(b) }
+    float(v) { this._grow(4); const b = Buffer.allocUnsafe(4); b.writeFloatLE(anyToFloat(v)); this.raw(b) }
+    double(v) { this._grow(8); const b = Buffer.allocUnsafe(8); b.writeDoubleLE(anyToFloat(v)); this.raw(b) }
     finish() { return Buffer.from(this.buf.buffer, this.buf.byteOffset, this.len) }
 }
 
@@ -152,7 +161,7 @@ function makeCodec(TABLE, enumIndex) {
                 if (f.s === 'zigzag') { const u = r.varintBig(); return numOrBigInt(u >> 1n ^ -(u & 1n)) }
                 if (f.s === 'zigzaglong') { const u = r.varintBig(); return toLong(u >> 1n ^ -(u & 1n)) }
                 if (f.s === 'enum') return r.varint() | 0
-                if (f.s === 'long') return toLong(BigInt(r.varint()))
+                if (f.s === 'long') return toLong(r.varintBig())
                 return r.varint()
             }
             case 'i64': { const b = Buffer.from(r.read8()); return f.s === 'double' ? b.readDoubleLE(0) : toLong(b.readBigUInt64LE(0)) }
@@ -189,7 +198,10 @@ function makeCodec(TABLE, enumIndex) {
                     if (f.rep) (obj[f.name] || (obj[f.name] = [])).push(val)
                     else obj[f.name] = val
                 }
-            } catch { break }
+            } catch (e) {
+                console.warn('[WAProto] decode error:', e.message)
+                break
+            }
         }
         return obj
     }
@@ -277,16 +289,17 @@ if (isGeneratorRun) {
 const tablePath = fileURLToPath(new URL('./WAProto.json', import.meta.url))
 const built = { proto: {}, codec: null }
 
+export let codec = null
 export function _reloadProto() {
     if (!existsSync(tablePath)) return
     const loaded = makeProto(tablePath)
     for (const key of Object.keys(built.proto)) delete built.proto[key]
     Object.assign(built.proto, loaded.proto)
     built.codec = loaded.codec
+    codec = loaded.codec
 }
 
 if (!isGeneratorRun && existsSync(tablePath)) _reloadProto()
 
 export const proto = built.proto
-export const codec = built.codec
 export default built

package/lib/Builders/AIRich.js

@@ -3,10 +3,10 @@ import { proto } from '../../WAProto/index.js'
 import {
   generateMessageIDV2, generateVerificationMetadata, waitAllPromises, extractIE, tokenizeCode, generateWAMessageFromContent, generateWAMessage,
   makeWhatsAppFlowButton, metaTyping, sendMetaComposited, PlanningStepStatus, buildSteps, replayPlanning, replayPlanningOnly, buildReasoningSteps, buildSearchSteps,
-  mixedSteps, buildBotRichResponse, BotCapabilityType, generateTableContent, generateListContent, generateCodeBlockContent,
+  mixedSteps, buildBotRichResponse, BotCapabilityType, RichSubMessageType, generateTableContent, generateListContent, generateCodeBlockContent,
   generateLatexContent, captureUnifiedResponse, generateUnifiedResponseContent
 } from '../Utils/index.js'
-import { isJidGroup, isJidMetaAI, jidNormalizedUser } from '../WABinary/index.js'
+import { isJidGroup, isJidMetaAI, jidNormalizedUser, getBizBinaryNode } from '../WABinary/index.js'
 import { BOT_RENDERING_CONFIG_METADATA } from '../Defaults/index.js'
 import { randomBytes } from 'crypto'
 
@@ -60,6 +60,18 @@ const mkProduct = d => ({ __typename: 'GenAIProductItemCardPrimitive', title: d.
 const mkSearchResult = d => ({ __typename: 'GenAISearchResultPrimitive', source_url: d.url ?? d.source_url ?? '', source_display_name: d.title ?? d.source_display_name ?? '', source_type: d.source_type ?? 'web', source_subtitle: d.subtitle ?? d.source_subtitle ?? '', favicon: d.favicon ?? null })
 const mkMap = ({ latitude, longitude, name = '', address = '' }) => ({ __typename: 'GenAIMapPrimitive', latitude, longitude, name, address })
 
+const _mp4Duration = (buf, silent = true) => {
+  try { if (!Buffer.isBuffer(buf) || buf.length < 8) { if (silent) return 0; throw new Error('Invalid buffer') }; let o = 0; while (o < buf.length - 8) { const sz = buf.readUInt32BE(o); if (sz < 8 || o + sz > buf.length) { if (silent) return 0; throw new Error('Bad atom') }; if (buf.toString('ascii', o + 4, o + 8) === 'moov') { let m = o + 8; const me = o + sz; while (m < me - 8) { const cs = buf.readUInt32BE(m); if (cs < 8 || m + cs > me) break; if (buf.toString('ascii', m + 4, m + 8) === 'mvhd') { const v = buf.readUInt8(m + 8); if (v === 0) { const ts = buf.readUInt32BE(m + 20); const dur = buf.readUInt32BE(m + 24); return ts ? dur / ts : 0 }; if (v === 1) { const ts = buf.readUInt32BE(m + 32); const dur = Number(buf.readBigUInt64BE(m + 36)); return ts ? dur / ts : 0 } }; m += cs } }; o += sz }; return 0 }
+  catch { return 0 }
+}
+
+const _mp4Preview = async (buf, time, silent = true) => {
+  const fail = e => { if (!silent) throw e; return null }; if (!Buffer.isBuffer(buf) || !buf.length) return fail(new Error('Empty buffer'))
+  try {
+    const { Readable, PassThrough } = await import('stream'); const { default: ffmpeg } = await import('fluent-ffmpeg'); const src = new Readable({ read() { } }); src.push(buf); src.push(null); const out = new PassThrough(); const chunks = []; out.on('data', c => chunks.push(c)); const t = time ?? Math.max(0.5, Math.min(_mp4Duration(buf) * 0.3, 10)); await new Promise((res, rej) => { out.on('end', res); out.on('error', rej); ffmpeg(src).outputOptions([`-ss ${t}`, '-vframes 1', '-vcodec png', '-f image2pipe']).on('error', rej).pipe(out, { end: true }) }); const b = Buffer.concat(chunks); return b.length ? b.toString('base64') : fail(new Error('Empty output'))
+  } catch (e) { return fail(e) }
+}
+
 const mkRichMap = ({ centerLatitude, centerLongitude, latitudeDelta, longitudeDelta, annotations = [], showInfoList = false }) => {
   if (centerLatitude == null || centerLongitude == null) throw new TypeError('addRichMap requires centerLatitude and centerLongitude')
   const submessage = { messageType: proto.AIRichResponseSubMessageType.AI_RICH_RESPONSE_MAP, mapMetadata: { centerLatitude, centerLongitude, ...(latitudeDelta != null ? { latitudeDelta } : {}), ...(longitudeDelta != null ? { longitudeDelta } : {}), showInfoList: !!showInfoList, annotations: annotations.map((a, i) => ({ annotationNumber: a.annotationNumber ?? i + 1, latitude: a.latitude, longitude: a.longitude, title: a.title ?? '', body: a.body ?? '' })) } }
@@ -177,8 +189,8 @@ export const prepareRichGenerationMessage = ({ text = '', mediaType = 'video', u
   const sections = []
   if (text) sections.push({ view_model: { primitive: { text: String(text), inline_entities: [], __typename: 'GenAIMarkdownTextUXPrimitive' }, __typename: 'GenAISingleLayoutViewModel' } })
   sections.push({ view_model: { primitive: buildImaginePrimitive({ mediaType, url, thumbnail, mimeType, fileLength, duration, status, estimatedMs }), __typename: 'GenAISingleLayoutViewModel', id: itemId } })
-  const submessages = text ? [{ messageType: 2, messageText: String(text) }] : []
-  const richResponseMessage = proto.AIRichResponseMessage.create({ submessages, messageType: 1, unifiedResponse: { data: Buffer.from(JSON.stringify({ response_id: responseId, sections })) }, contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid: DEFAULT_BOT_JID }, forwardOrigin: 4 } })
+  const submessages = text ? [{ messageType: RichSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: String(text) }] : []
+  const richResponseMessage = proto.AIRichResponseMessage.create({ submessages, messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD, unifiedResponse: { data: Buffer.from(JSON.stringify({ response_id: responseId, sections })) }, contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid: DEFAULT_BOT_JID }, forwardOrigin: 4 } })
   const message = wrapToBotForwardedMessage(richResponseMessage, verificationMetadata)
   message.messageContextInfo.botMetadata.botResponseId = responseId
   return { message, responseId, itemId }
@@ -189,6 +201,7 @@ export class AIRich {
   #responseId = null; #dynamic = true; #signedVerificationMetadata = null
   #contextInfoExtra = {}; #embeddedScreens = []; #suggestedPrompts = null
   #botSources = null; #pttTranscript = null
+  #footerSections = []; #responseMeta = {}; #botMetadataExtra = {}
 
   constructor(client, opts = {}) {
     if (!client) throw new Error('Socket client is required')
@@ -210,17 +223,28 @@ export class AIRich {
   setBotJid(jid) { this.#botJid = jid; return this }
   setResponseId(id) { this.#responseId = id; this.#dynamic = false; return this }
   setContextInfo(ci) { this.#contextInfoExtra = ci; return this }
+  setResponseMeta(meta) { if (!meta || typeof meta !== 'object') throw new TypeError('responseMeta must be a plain object'); this.#responseMeta = { ...this.#responseMeta, ...meta }; return this }
+  setBotMetadata(extra) { if (!extra || typeof extra !== 'object') throw new TypeError('botMetadata must be a plain object'); this.#botMetadataExtra = { ...this.#botMetadataExtra, ...extra }; return this }
+  addFooterSection(section) { if (!section || typeof section !== 'object') throw new TypeError('footer section must be a plain object'); this.#footerSections.push(section); return this }
+  clearFooterSections() { this.#footerSections = []; return this }
 
   addText(text, opts = {}) { const { text: t, inline_entities } = extractIE(text); return this.#add(single(mkMarkdown(t, inline_entities)), null, opts) }
-  addCode(language, content, opts = {}) { const { codeBlocks, unified_codeBlock } = tokenizeCode(content, language); const submessage = { messageType: 5, codeMetadata: { codeLanguage: language, codeBlocks } }; return this.#add(single(mkCode(content, language, unified_codeBlock)), submessage, opts) }
+  addCode(language, content, opts = {}) { const { codeBlocks, unified_codeBlock } = tokenizeCode(content, language); const submessage = { messageType: RichSubMessageType.AI_RICH_RESPONSE_CODE, codeMetadata: { codeLanguage: language, codeBlocks } }; return this.#add(single(mkCode(content, language, unified_codeBlock)), submessage, opts) }
   addTable(rows, title = '', opts = {}) { return this.#add(single(mkTable(rows, title)), null, opts) }
   addImage(input, opts = {}) { const resolved = this.#uploadMedia(input, 'image').then(url => single(mkImage(url))); return this.#add(resolved, null, opts) }
-  addVideo(url, opts = {}) { const resolved = this.#uploadMedia(url, 'video').then(u => single(mkVideo(u))); return this.#add(resolved, null, opts) }
+  addVideo(url, { autoFill = false, mimeType = 'video/mp4', ...opts } = {}) {
+    const resolved = this.#uploadMedia(url, 'video').then(async finalUrl => { if (!autoFill) return single(mkVideo(finalUrl)); const buf = await fetch(finalUrl).then(r => r.arrayBuffer()).then(b => Buffer.from(b)).catch(() => null); const duration = buf ? _mp4Duration(buf) : 0; const thumbnail = buf ? await _mp4Preview(buf, null, true) : null; return single({ __typename: 'GenAIImaginePrimitive', imagine_type: 'ANIMATE', status: { status: 'READY' }, media: { url: finalUrl, mime_type: mimeType, file_length: buf?.length ?? 0, duration }, thumbnail: thumbnail ? { raw_media: thumbnail } : undefined }) }); return this.#add(resolved, null, opts)
+  }
   addGrid(items, opts = {}) { if (!Array.isArray(items) || items.length < 2) throw new Error('addGrid requires at least 2 items'); return this.#add(grid(items.map(i => mkImage(i))), null, opts) }
 
   addVideoGrid(videos, opts = {}) {
     if (!Array.isArray(videos) || videos.length < 2) throw new Error('addVideoGrid requires at least 2 videos')
-    const prims = videos.map(v => { const url = typeof v === 'string' ? v : (v?.url ?? v?.videoUrl ?? ''); const item = typeof v === 'string' ? {} : v; return { __typename: 'GenAIVideoPrimitive', reels_url: url, reels_title: item.title, thumbnail_url: item.thumbnailUrl ?? item.thumbnail, creator: item.creator, avatar_url: item.avatarUrl, likes_count: item.likes, comments_count: item.comments, shares_count: item.shares, is_verified: item.isVerified, video_delivery_response: { progressive_urls: (item.progressiveUrls ?? []).map(u => ({ progressive_url: u, __typename: 'GenAIProgressiveUrlResponse' })), dash_manifests: (item.dashManifests ?? []).map(m => ({ manifest_xml: m, __typename: 'GenAIDashManifestResponse' })), __typename: 'GenAIVideoDeliveryResponse' } } })
+    const prims = videos.map((v, i) => {
+      const item = typeof v === 'string' ? {} : v
+      const url = typeof v === 'string' ? v : (v?.url ?? v?.videoUrl ?? '')
+      if (!url) throw new Error(`VideoGrid item ${i}: video requires a URL`)
+      return { __typename: 'GenAIVideoPrimitive', reels_url: url, reels_title: item.title, thumbnail_url: item.thumbnailUrl ?? item.thumbnail, creator: item.creator, avatar_url: item.avatarUrl, likes_count: item.likes, comments_count: item.comments, shares_count: item.shares, is_verified: item.isVerified, video_delivery_response: { progressive_urls: (item.progressiveUrls ?? []).map(u => ({ progressive_url: u, __typename: 'GenAIProgressiveUrlResponse' })), dash_manifests: (item.dashManifests ?? []).map(m => ({ manifest_xml: m, __typename: 'GenAIDashManifestResponse' })), __typename: 'GenAIVideoDeliveryResponse' } }
+    })
     return this.#add(grid(prims), null, opts)
   }
 
@@ -282,15 +306,15 @@ export class AIRich {
   addVerticalAlbum(items, opts = {}) {
     if (!Array.isArray(items) || items.length < 2) throw new Error('addVerticalAlbum requires at least 2 items')
     const expiration = String(Date.now() + 30 * 24 * 60 * 60 * 1000)
-    const primitives = items.map(item => {
+    const primitives = items.map((item, i) => {
       const kind = item?.type || (item?.video ? 'video' : 'image')
       if (kind === 'video') {
-        const v = item.video || item
-        return buildImaginePrimitive({ mediaType: 'video', url: typeof v === 'string' ? v : (v?.url || ''), mimeType: v?.mimeType || 'video/mp4', fileLength: v?.fileLength || 0, duration: v?.duration || 0, status: 'READY' })
+        const v = item.video || item.data || item
+        return buildImaginePrimitive({ mediaType: 'video', url: typeof v === 'string' ? v : (v?.url || ''), mimeType: v?.mimeType ?? v?.mime_type ?? 'video/mp4', fileLength: v?.fileLength || 0, duration: v?.duration || 0, status: 'READY' })
       }
       const img = typeof (item?.image || item) === 'string' ? { url: item?.image || item } : (item?.image || item || {})
-      const url = img.url || ''
-      if (!url) throw new Error('Each vertical album image item requires a URL')
+      const url = img?.imageHighResUrl ?? img?.highResUrl ?? img?.fullUrl ?? img?.imagePreviewUrl ?? img?.previewUrl ?? img?.url ?? ''
+      if (!url) throw new Error(`VerticalAlbum item ${i}: image requires a URL`)
       return { __typename: 'GenAIImagePrimitive', preview_image: { url, url_fallback: url, mime_type: img.mimeType || 'image/jpeg', expiration_timestamp_ms: expiration, width: img.width || 600, height: img.height || 400 }, full_image: { url, url_fallback: url, mime_type: img.mimeType || 'image/jpeg', expiration_timestamp_ms: expiration, width: img.width || 600, height: img.height || 400 }, dark_mode_preview_image: { url, url_fallback: url, mime_type: img.mimeType || 'image/jpeg', expiration_timestamp_ms: expiration, width: img.width || 600, height: img.height || 400 }, dark_mode_full_image: { url, url_fallback: url, mime_type: img.mimeType || 'image/jpeg', expiration_timestamp_ms: expiration, width: img.width || 600, height: img.height || 400 }, asset_query_status: 'FETCHED', display_mode: 'FULL_WIDTH', full_width: true }
     })
     return this.#add({ view_model: { primitives, display_mode: 'FULL_WIDTH', full_width: true, __typename: 'GenAIVStackLayoutViewModel' } }, null, opts)
@@ -302,6 +326,28 @@ export class AIRich {
     return this.#add(single(mkMeta(`🎤 _${transcript}_`)), null, opts)
   }
 
+  // ─── Node introspection & mutation ────────────────────────────────────────
+  hasId(id) { return typeof id === 'string' && id in this.#idIndex }
+  getIds() { return this.#nodes.map(n => n.id) }
+  peek(id) { const idx = this.#idIndex[id]; return idx !== undefined ? { ...this.#nodes[idx] } : null }
+  assignId(index, newId) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.#nodes.length) throw new RangeError(`Node index ${index} is out of range`)
+    if (newId in this.#idIndex) throw new Error(`Id "${newId}" already exists`)
+    const node = this.#nodes[index]
+    delete this.#idIndex[node.id]
+    node.id = newId
+    this.#idIndex[newId] = index
+    return this
+  }
+  delete(id) {
+    const idx = this.#idIndex[id]
+    if (idx === undefined) throw new Error(`Node id "${id}" not found`)
+    this.#nodes.splice(idx, 1)
+    this.#idIndex = {}
+    this.#nodes.forEach((n, i) => { this.#idIndex[n.id] = i })
+    return this
+  }
+
   loadFrom(msg) {
     const rich = msg?.botForwardedMessage?.message?.richResponseMessage ?? msg?.richResponseMessage
     if (!rich) throw new Error('Not an AIRich message')
@@ -324,11 +370,12 @@ export class AIRich {
     const submessages = resolved.map(n => n.submessage).filter(Boolean)
     const embeddedScreens = await waitAllPromises(this.#embeddedScreens)
     const responseId = this.#dynamic ? crypto.randomUUID() : (this.#responseId ?? crypto.randomUUID())
-    const unifiedData = JSON.stringify({ response_id: responseId, sections, ...(embeddedScreens.length ? { embedded_screens: embeddedScreens } : {}) })
+    const footerSections = await waitAllPromises(this.#footerSections)
+    const unifiedData = JSON.stringify({ response_id: responseId, ...this.#responseMeta, sections, ...(footerSections.length ? { footer_sections: footerSections } : {}), ...(embeddedScreens.length ? { embedded_screens: embeddedScreens } : {}) })
     const contextInfo = { isForwarded: true, forwardOrigin: 4, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid }, participant: '13135550002@s.whatsapp.net', remoteJid: 'status@broadcast', quotedMessage: { protocolMessage: { type: 25 } }, ...this.#contextInfoExtra, ...(quoted ? { quotedMessage: quoted.message, stanzaId: quoted.key?.id, participant: quotedParticipant ?? quoted.key?.participant ?? quoted.key?.remoteJid, remoteJid: quoted.key?.remoteJid } : {}) }
     const verification = this.#signedVerificationMetadata ?? generateVerificationMetadata()
     const { sources, mediaDetailsMetadataList } = buildAdditionalBotMetadata(submessages)
-    const richResponseMessage = proto.AIRichResponseMessage.create({ messageType: 1, submessages, unifiedResponse: { data: Buffer.from(unifiedData) }, originalRecipientMetadata: { data: Buffer.from(unifiedData) }, contextInfo })
+    const richResponseMessage = proto.AIRichResponseMessage.create({ messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD, submessages, unifiedResponse: { data: Buffer.from(unifiedData) }, originalRecipientMetadata: { data: Buffer.from(unifiedData) }, contextInfo })
     const message = wrapToBotForwardedMessage(richResponseMessage, verification)
     const botMeta = message.messageContextInfo.botMetadata
     botMeta.botResponseId = responseId
@@ -340,6 +387,7 @@ export class AIRich {
     if (mediaDetailsMetadataList.length) botMeta.unifiedResponseMutation = { mediaDetailsMetadataList }
     if (this.#suggestedPrompts) botMeta.suggestedPromptMetadata = this.#suggestedPrompts
     if (this.#pttTranscript) botMeta.pttPromptMetadata = { transcript: this.#pttTranscript }
+    if (Object.keys(this.#botMetadataExtra).length) Object.assign(botMeta, this.#botMetadataExtra)
     botMeta.capabilities = { richResponseUnifiedResponse: true, richResponseEmbeddedScreens: true, richResponseInlineLinksEnabled: true, richResponseUrBloksEnabled: true, richResponseUrImagine: true, richResponseUrReasoning: true }
     return await await generateWAMessageFromContent(jid, message, { userJid: this.#client.user?.id, messageId })
   }
@@ -347,14 +395,11 @@ export class AIRich {
   async send(jid, opts = {}) {
     const { additionalNodes = [], ...buildOpts } = opts
     const msg = await this.build(jid, buildOpts)
+    const bizNode = getBizBinaryNode(msg.message)
     const relayFn = this.#client.relayRichMessage ?? this.#client.relayMessage
     await relayFn(jid, msg, {
       ...opts,
-      additionalNodes: [
-        { tag: 'bot', attrs: { biz_bot: '1' }, content: undefined },
-        { tag: 'biz', attrs: {}, content: [{ tag: 'interactive', attrs: { type: 'native_flow', v: '1' }, content: [{ tag: 'native_flow', attrs: { v: '9', name: 'mixed' } }] }] },
-        ...(opts.additionalNodes ?? [])
-      ]
+      additionalNodes: [...(bizNode ? [bizNode] : []), ...(opts.additionalNodes ?? [])]
     })
     return msg
   }
@@ -370,31 +415,17 @@ export class AIRich {
 }
 
 export function aiRichFromObject(client, jid, data, opts = {}) {
-  const r = new AIRich(client, { botJid: data.botJid })
-  if (data.title) r.setTitle(data.title)
+  const { _r, ...sendOpts } = opts
+  const r = _r ?? new AIRich(client, { botJid: data.botJid })
+  const isChild = !!_r
+  if (!isChild && (data.title ?? data.disclaimerText)) r.setTitle(data.title ?? data.disclaimerText)
   if (data.parts) {
     for (const p of data.parts) {
-      if (p.type === 'text') r.addText(p.content ?? p.text)
-      if (p.type === 'code') r.addCode(p.language ?? '', p.content ?? p.code)
-      if (p.type === 'table') r.addTable(p.table, p.title)
-      if (p.type === 'image') r.addImage(p.url ?? p.image)
-      if (p.type === 'grid') r.addGrid(p.items ?? p.images)
-      if (p.type === 'videoGrid') r.addVideoGrid(p.items ?? p.videos)
-      if (p.type === 'imagine') r.addImagine(p)
-      if (p.type === 'sources') r.addSource(p.sources)
-      if (p.type === 'divider') r.addDivider()
-      if (p.type === 'spacer') r.addSpacer(p.spacing)
-      if (p.type === 'tip') r.addTip(p.content ?? p.text)
-      if (p.type === 'meta') r.addMetadata(p.content ?? p.text)
-      if (p.type === 'foa') r.addFOAText(p.content ?? p.text)
-      if (p.type === 'html') r.addHtml(p.html, p.trustedSources)
-      if (p.type === 'richHtml') r.addRichHtml(p.tabs ?? p.html, p.title)
-      if (p.type === 'copy') r.addCopyAction(p.text, p.label, p.alignment)
-      if (p.type === 'social') r.addSocialProfile(p)
-      if (p.type === 'imagine') r.addImagine(p)
-      if (p.type === 'rawSections') r.addRawSections(p.sections, p.submessages)
+      const code = Array.isArray(p.code) ? p.code.map(c => c.codeContent ?? c.content ?? '').join('\n') : p.code
+      const table = Array.isArray(p.table) ? p.table.map(r => Array.isArray(r) ? r : (r.items ?? r.cells ?? [])) : p.table
+      aiRichFromObject(client, jid, { ...p, ...(code ? { code } : {}), ...(table ? { table } : {}) }, { ...sendOpts, _r: r })
     }
-    return r.send(jid, opts)
+    return isChild ? r : r.send(jid, sendOpts)
   }
   if (data.texts) data.texts.forEach(t => r.addText(t))
   else if (data.text) r.addText(data.text)
@@ -426,7 +457,7 @@ export function aiRichFromObject(client, jid, data, opts = {}) {
   if (data.metadata ?? data.meta) r.addMetadata(data.metadata ?? data.meta)
   if (data.footer) r.addFOAText(data.footer)
   if (data.rawSections) r.addRawSections(data.rawSections, data.rawSubmessages)
-  return r.send(jid, opts)
+  return isChild ? r : r.send(jid, sendOpts)
 }
 
 const stripDevice = jid => String(jid || '').replace(/:\d+$/, '')
@@ -484,7 +515,7 @@ export function attachAIRich(result, config) {
   result.captureAiRich = msg => {
     const rich = msg?.botForwardedMessage?.message?.richResponseMessage ?? msg?.richResponseMessage
     if (!rich?.unifiedResponse?.data) return null
-    return { submessages: rich.submessages ?? [], sections: JSON.parse(Buffer.from(rich.unifiedResponse.data, 'base64').toString()), contextInfo: rich.contextInfo ?? {}, messageType: rich.messageType ?? 1 }
+    return { submessages: rich.submessages ?? [], sections: JSON.parse(Buffer.isBuffer(rich.unifiedResponse.data) ? rich.unifiedResponse.data.toString() : Buffer.from(rich.unifiedResponse.data, 'base64').toString()), contextInfo: rich.contextInfo ?? {}, messageType: rich.messageType ?? proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD }
   }
 
   result.relayAiRich = (jid, captured, opts = {}) => {
@@ -524,7 +555,7 @@ export function attachAIRich(result, config) {
   }
   result.sendBotPlanning = async (jid, content = {}, opts = {}) => {
     const { text = 'Execution plan', steps = [], queryPlan = true, botJid = META_AI_BOT_JID } = content
-    const submessages = [{ messageType: proto.AIRichResponseSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: text }, ...steps.map(s => ({ messageType: proto.AIRichResponseSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: typeof s === 'string' ? s : `${s.title || s.name || 'Step'}${s.body ? `: ${s.body}` : ''}` }))]
+    const submessages = [{ messageType: RichSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: text }, ...steps.map(s => ({ messageType: RichSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: typeof s === 'string' ? s : `${s.title || s.name || 'Step'}${s.body ? `: ${s.body}` : ''}` }))]
     const wrapped = buildBotRichResponse({ botJid, submessages, capabilities: [BotCapabilityType.AGENTIC_PLANNING, ...(queryPlan ? [BotCapabilityType.QUERY_PLAN] : [])] })
     const full = await await generateWAMessageFromContent(jid, wrapped, { userJid: sock.user?.id, messageId: opts.messageId || generateMessageIDV2(sock.user?.id) })
     return relayRichMessage(jid, full, opts)
@@ -534,7 +565,7 @@ export function attachAIRich(result, config) {
     if (!Array.isArray(steps) || steps.length === 0) throw new Error('sendBotPlan requires at least one step')
     const statusEnum = proto.BotProgressIndicatorMetadata.BotPlanningStepMetadata.PlanningStepStatus
     const normalizedSteps = steps.map((s, i) => ({ statusTitle: String(s.title || s.name || `Step ${i + 1}`), statusBody: String(s.body || s.description || ''), status: s.status === 'executing' ? statusEnum.EXECUTING : (s.status === 'finished' || s.status === 'completed') ? statusEnum.FINISHED : statusEnum.PLANNED, isReasoning: s.isReasoning === true, isEnhancedSearch: s.isEnhancedSearch === true }))
-    const wrapped = { messageContextInfo: { botMetadata: { capabilityMetadata: { capabilities: [proto.BotCapabilityMetadata.BotCapabilityType.AGENTIC_PLANNING, proto.BotCapabilityMetadata.BotCapabilityType.QUERY_PLAN] }, progressIndicatorMetadata: { progressDescription: title, stepsMetadata: normalizedSteps, ...(estimatedCompletionTime ? { estimatedCompletionTime } : {}) } } }, botForwardedMessage: { message: { richResponseMessage: { messageType: 1, submessages: [{ messageType: 2, messageText: text }], contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid }, forwardOrigin: 4 } } } } }
+    const wrapped = { messageContextInfo: { botMetadata: { capabilityMetadata: { capabilities: [proto.BotCapabilityMetadata.BotCapabilityType.AGENTIC_PLANNING, proto.BotCapabilityMetadata.BotCapabilityType.QUERY_PLAN] }, progressIndicatorMetadata: { progressDescription: title, stepsMetadata: normalizedSteps, ...(estimatedCompletionTime ? { estimatedCompletionTime } : {}) } } }, botForwardedMessage: { message: { richResponseMessage: { messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD, submessages: [{ messageType: RichSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: text }], contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid }, forwardOrigin: 4 } } } } }
     const full = await await generateWAMessageFromContent(jid, wrapped, { userJid: sock.user?.id, messageId: opts.messageId || generateMessageIDV2(sock.user?.id) })
     await sock.relayMessage(jid, full.message, { messageId: full.key.id })
     return full