@vanzxy/baileys 1.4.2 → 1.4.4

package/lib/Utils/MessageBuilder.js

@@ -1,7 +1,7 @@
 /**
  * lib/Utils/MessageBuilder.js — AIRich / Button / ButtonV2 / Carousel / Toolkit
  *
- * Part of @vanzxy/baileys 1.3.9. Third-party attribution for the base
+ * Part of @vanzxy/baileys 1.4.4. Third-party attribution for the base
  * implementation this file was adapted from is kept in /NOTICE.md
  * (not inline here) per the original author's license terms.
  *
@@ -9,11 +9,36 @@
  * @blurose/baileys 1.1.13 fork (base, feature-complete) with perf defaults
  * and message-authenticity fields backported from arslan-baileys 1.1.0 and
  * this project's own rich-message-utils.js. See changes tagged "Vanz@" below.
+ *
+ * Vanz@Merge 22-08-26 --- v4.6 -> v4.7. Button class hardened + extended:
+ *   - Bug fix: addCall() wrote its second arg into buttonParamsJson.id, but
+ *     the cta_call native-flow schema keys on `phone_number` (id is ignored
+ *     by WhatsApp for this button type). Confirmed against 3 independent
+ *     current Baileys-fork call sites before changing the wire shape.
+ *   - Required-field validation added to the CTA helpers that silently
+ *     produced a button WA would render but never route correctly
+ *     (empty id/url/copy_code/phone_number).
+ *   - New native-flow helpers for names WA recognises beyond the "mixed"
+ *     set (cta_catalog, open_webview, call_permission_request,
+ *     automated_greeting_message_view_catalog, payment_info,
+ *     review_and_pay, wa_payment_transaction_details, mpm) — see the
+ *     Button.#SPECIAL_FLOW map and each method's JSDoc for the
+ *     business/official-client gating caveat.
+ *   - send() now picks the correct <native_flow v=.. name=..> node per the
+ *     first button's name instead of always emitting v=9 name=mixed, which
+ *     is required for the special names above to have a chance of
+ *     rendering at all (mirrors the same class of bug already fixed for
+ *     lone single_select in 1.3.x).
+ *   - JSDoc added across Toolkit/BaseBuilder/Button/ButtonV2/Carousel/AIRich
+ *     for editor hover-docs; kept in sync with MessageBuilder.d.ts.
+ * All additions above are original implementations written against public
+ * Baileys-ecosystem documentation of the native-flow wire format, not
+ * copied from any third-party fork.
  */
 
 'use strict';
 
-const MESSAGE_BUILDER_VERSION = '4.6';
+const MESSAGE_BUILDER_VERSION = '4.7';
 
 import { generateWAMessageFromContent, prepareWAMessageMedia } from './messages.js';
 import { botMetadataSignature, botMetadataCertificate } from './rich-message-utils.js';
@@ -235,13 +260,16 @@ async function waitAllPromises(input) {
 	return deep(await input);
 }
 
+/** Static grab-bag of media/text helpers shared by the builder classes above. */
 class Toolkit {
 	constructor() {}
 
+	/** Parse `[label](url)` hyperlinks, `[]()` citations, and `[expr]<img-url>` latex tags out of `text`. */
 	static extractIE(text, { extract = true, hyperlink = true, citation = true, latex = true } = {}) {
 		return extractIE(text, { extract, hyperlink, citation, latex });
 	}
 
+	/** Resize an image buffer to `x`×`y` via sharp (lazy-loaded; throws with an install hint if sharp isn't present). */
 	static async resize(buffer, x, y, fit = 'cover') {
 		const sharp = await getSharp();
 		return await sharp(buffer)
@@ -254,10 +282,12 @@ class Toolkit {
 			.toBuffer();
 	}
 
+	/** Deeply await every Promise nested in `input` (objects/arrays), resolving it into plain values. */
 	static async waitAllPromises(input) {
 		return await waitAllPromises(input);
 	}
 
+	/** Fetch `url` into a Buffer. @param {boolean} [silent] Return an empty Buffer instead of throwing on failure. */
 	static async fetchBuffer(url, options = {}, { silent = true } = {}) {
 		try {
 			let response = await fetch(url, options);
@@ -269,6 +299,7 @@ class Toolkit {
 		}
 	}
 
+	/** Upload media to WhatsApp's media server and return its `url`/`directPath` descriptor. */
 	static async toUrl(_client, path, mediaType = 'document') {
 		if (!path) throw new Error('Url or buffer needed');
 
@@ -285,6 +316,7 @@ class Toolkit {
 		return Object.values(media)[0]?.url;
 	}
 
+	/** Normalize a url/buffer/array of either into the requested `result` shape ('url' | 'buffer' | 'base64'), optionally resizing and/or uploading to WA's media server first. */
 	static async resolveMedia(_client, media, mediaType = 'image', { resolveUrl = false, resolveWAUrl = false, result = 'url', resize = false, width = 300, height = 300 } = {}) {
 		const isUrl = (str) => /^https?:\/\/.+/i.test(str);
 
@@ -305,8 +337,6 @@ class Toolkit {
 			);
 		}
 
-		const originalIsBuffer = Buffer.isBuffer(media);
-
 		if (typeof media === 'string' && isUrl(media)) {
 			if (isWAUrl(media)) {
 				if (resolveWAUrl) {
@@ -347,13 +377,14 @@ class Toolkit {
 			return media.toString('base64');
 		}
 
-		if (originalIsBuffer) {
-			return Toolkit.toUrl(_client, media, mediaType);
-		}
-
+		// Vanz@Fix 22-08-26 (v4.7) --- both branches of the old if/else here returned the exact
+		// same `Toolkit.toUrl(_client, media, mediaType)` call (dead branching left over from an
+		// earlier version that must have treated buffer vs non-buffer input differently). Collapsed
+		// to a single return; `originalIsBuffer` is now unused and removed below.
 		return Toolkit.toUrl(_client, media, mediaType);
 	}
 
+	/** Read an mp4 buffer's duration (seconds) straight from its moov atom, no ffprobe needed. */
 	static getMp4Duration(buffer, { silent = true } = {}) {
 		try {
 			if (!Buffer.isBuffer(buffer) || buffer.length < 8) {
@@ -431,6 +462,7 @@ class Toolkit {
 		}
 	}
 
+	/** Extract a single frame from an mp4 buffer as a thumbnail (ffmpeg lazy-loaded; throws with an install hint if missing). */
 	static getMp4Preview(videoBuffer, { time, result = 'buffer', resize = true, width = 300, height = 300, silent = true } = {}) {
 		return new Promise((resolve, reject) => {
 			const fail = (err) => {
@@ -491,6 +523,12 @@ class Toolkit {
 	}
 }
 
+/**
+ * Shared chaining base for Button/ButtonV2/Carousel/AIRich: title/subtitle/body/footer,
+ * contextInfo (quoted/mentions/etc.), and an escape-hatch payload merged verbatim
+ * into the generated message content.
+ * @abstract
+ */
 class BaseBuilder {
 	constructor() {
 		this._title = '';
@@ -501,6 +539,7 @@ class BaseBuilder {
 		this._extraPayload = {};
 	}
 
+	/** @param {string} title */
 	setTitle(title) {
 		if (typeof title !== 'string') {
 			throw new TypeError('Title must be a string');
@@ -509,6 +548,7 @@ class BaseBuilder {
 		return this;
 	}
 
+	/** @param {string} subtitle */
 	setSubtitle(subtitle) {
 		if (typeof subtitle !== 'string') {
 			throw new TypeError('Subtitle must be a string');
@@ -517,6 +557,7 @@ class BaseBuilder {
 		return this;
 	}
 
+	/** @param {string} body Main message text. */
 	setBody(body) {
 		if (typeof body !== 'string') {
 			throw new TypeError('Body must be a string');
@@ -525,6 +566,7 @@ class BaseBuilder {
 		return this;
 	}
 
+	/** @param {string} footer */
 	setFooter(footer) {
 		if (typeof footer !== 'string') {
 			throw new TypeError('Footer must be a string');
@@ -533,6 +575,7 @@ class BaseBuilder {
 		return this;
 	}
 
+	/** @param {Record<string, any>} obj Raw `contextInfo` (quotedMessage, mentionedJid, etc.), merged verbatim. */
 	setContextInfo(obj) {
 		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
 			throw new TypeError('ContextInfo must be a plain object');
@@ -542,6 +585,7 @@ class BaseBuilder {
 		return this;
 	}
 
+	/** Escape hatch: shallow-merge arbitrary keys into the generated message content, alongside whatever this builder produces. */
 	addPayload(obj) {
 		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
 			throw new TypeError('Payload must be a plain object');
@@ -553,9 +597,17 @@ class BaseBuilder {
 	}
 }
 
+/**
+ * Interactive (native-flow) message builder — header/body/footer + a mix of
+ * buttons (quick_reply, cta_url, cta_call, single_select, ...). Sends via
+ * `interactiveMessage` (or falls back to a legacy `listMessage` when the
+ * only button is a lone `single_select`, since WA doesn't render that
+ * combination as native-flow).
+ */
 class Button extends BaseBuilder {
 	#client;
 
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket (must expose `relayMessage`). */
 	constructor(client) {
 		super();
 		if (!client) {
@@ -570,24 +622,28 @@ class Button extends BaseBuilder {
 		this._params = {};
 	}
 
+	/** Attach a video as the interactive header. @param {string|Buffer} path Url or buffer. */
 	setVideo(path, options = {}) {
 		if (!path) throw new Error('Url or buffer needed');
 		Buffer.isBuffer(path) ? (this._data = { video: path, ...options }) : (this._data = { video: { url: path }, ...options });
 		return this;
 	}
 
+	/** Attach an image as the interactive header. @param {string|Buffer} path Url or buffer. */
 	setImage(path, options = {}) {
 		if (!path) throw new Error('Url or buffer needed');
 		Buffer.isBuffer(path) ? (this._data = { image: path, ...options }) : (this._data = { image: { url: path }, ...options });
 		return this;
 	}
 
+	/** Attach a document as the interactive header. @param {string|Buffer} path Url or buffer. */
 	setDocument(path, options = {}) {
 		if (!path) throw new Error('Url or buffer needed');
 		Buffer.isBuffer(path) ? (this._data = { document: path, ...options }) : (this._data = { document: { url: path }, ...options });
 		return this;
 	}
 
+	/** Set a raw pre-built header media object (bypasses setVideo/setImage/setDocument shorthands). */
 	setMedia(obj) {
 		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
 			throw new TypeError('Media must be a plain object');
@@ -597,17 +653,30 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Remove every button added so far (keeps title/body/footer/media). */
 	clearButtons() {
 		this._buttons = [];
 		return this;
 	}
 
+	/** Overwrite the message-level `nativeFlowMessage.messageParamsJson` payload wholesale. */
 	setParams(obj) {
 		this._params = obj;
 		return this;
 	}
 
+	/**
+	 * Low-level escape hatch: push a raw native-flow button by name. Prefer the
+	 * dedicated `add*()` helpers below when one exists — they validate the
+	 * required keys for that button type.
+	 * @param {string} name Native-flow button name, e.g. 'quick_reply', 'cta_url'.
+	 * @param {string|Record<string, any>} params Either a pre-stringified JSON payload or a plain object.
+	 */
 	addButton(name, params) {
+		if (typeof name !== 'string' || !name.trim()) {
+			throw new TypeError('addButton(name, params) requires a non-empty string name');
+		}
+
 		this._buttons.push({
 			name,
 			buttonParamsJson: typeof params === 'string' ? params : JSON.stringify(params),
@@ -616,16 +685,21 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Append a row to the section currently open on the last `addSelection()` (call `makeSection()` first). */
 	makeRow(header = '', title = '', description = '', id = '') {
 		if (this._currentSelectionIndex === -1 || this._currentSectionIndex === -1) {
 			throw new Error('You need to create a selection and a section first');
 		}
+		if (!title || !id) {
+			throw new TypeError('makeRow() requires both a title and an id');
+		}
 		const buttonParams = JSON.parse(this._buttons[this._currentSelectionIndex].buttonParamsJson);
 		buttonParams.sections[this._currentSectionIndex].rows.push({ header, title, description, id });
 		this._buttons[this._currentSelectionIndex].buttonParamsJson = JSON.stringify(buttonParams);
 		return this;
 	}
 
+	/** Open a new section on the `single_select` button added by the last `addSelection()` call. */
 	makeSection(title = '', highlight_label = '') {
 		if (this._currentSelectionIndex === -1) {
 			throw new Error('You need to create a selection first');
@@ -637,14 +711,24 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Start a `single_select` (in-button picker list) button. Follow with `makeSection()` + `makeRow()`. */
 	addSelection(title, options = {}) {
+		if (!title) throw new TypeError('addSelection(title) requires a non-empty title');
 		this._buttons.push({ ...options, name: 'single_select', buttonParamsJson: JSON.stringify({ title, sections: [] }) });
 		this._currentSelectionIndex = this._buttons.length - 1;
 		this._currentSectionIndex = -1;
 		return this;
 	}
 
+	/**
+	 * Add a `quick_reply` button — sends `id` back as the interactive-response id when tapped.
+	 * @param {string} display_text Button label.
+	 * @param {string} id Unique id returned on tap; required, WA silently drops replies without one.
+	 */
 	addReply(display_text = '', id = '', options = {}) {
+		if (!display_text || !id) {
+			throw new TypeError('addReply(display_text, id) requires both a label and a unique id');
+		}
 		this._buttons.push({
 			name: 'quick_reply',
 			buttonParamsJson: JSON.stringify({
@@ -656,19 +740,37 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
-	addCall(display_text = '', id = '', options = {}) {
+	/**
+	 * Add a `cta_call` (tap-to-dial) button.
+	 * @param {string} display_text Button label.
+	 * @param {string} phone_number Phone number to dial, e.g. '+15551234567'.
+	 */
+	// Vanz@Fix 22-08-26 (v4.7) --- second arg used to be written into buttonParamsJson.id, but
+	// the cta_call schema keys on `phone_number` (confirmed against @chatunity/baileys,
+	// @neoxr/wb, and a WhiskeySockets/Baileys#2626 working example) — `id` is simply ignored
+	// by WhatsApp for this button, so every button built with the old addCall() silently
+	// rendered with no dial action. Kept the same 2nd-positional-arg call shape so existing
+	// call sites keep working; only the wire key changed.
+	addCall(display_text = '', phone_number = '', options = {}) {
+		if (!display_text || !phone_number) {
+			throw new TypeError('addCall(display_text, phone_number) requires both a label and a phone number');
+		}
 		this._buttons.push({
 			name: 'cta_call',
 			buttonParamsJson: JSON.stringify({
 				display_text,
-				id,
+				phone_number,
 				...options,
 			}),
 		});
 		return this;
 	}
 
+	/** Add a `cta_reminder` button (schedules an in-chat reminder chip). */
 	addReminder(display_text = '', id = '', options = {}) {
+		if (!display_text || !id) {
+			throw new TypeError('addReminder(display_text, id) requires both a label and a unique id');
+		}
 		this._buttons.push({
 			name: 'cta_reminder',
 			buttonParamsJson: JSON.stringify({
@@ -680,7 +782,11 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a `cta_cancel_reminder` button, pairs with `addReminder()`. */
 	addCancelReminder(display_text = '', id = '', options = {}) {
+		if (!display_text || !id) {
+			throw new TypeError('addCancelReminder(display_text, id) requires both a label and a unique id');
+		}
 		this._buttons.push({
 			name: 'cta_cancel_reminder',
 			buttonParamsJson: JSON.stringify({
@@ -692,7 +798,11 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Add an `address_message` button (prompts the user's saved-address picker). */
 	addAddress(display_text = '', id = '', options = {}) {
+		if (!display_text || !id) {
+			throw new TypeError('addAddress(display_text, id) requires both a label and a unique id');
+		}
 		this._buttons.push({
 			name: 'address_message',
 			buttonParamsJson: JSON.stringify({
@@ -704,6 +814,7 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a `send_location` button (requests the user's live location). */
 	addLocation(options = {}) {
 		this._buttons.push({
 			name: 'send_location',
@@ -712,13 +823,26 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/**
+	 * Add a `cta_url` button.
+	 * @param {string} display_text Button label.
+	 * @param {string} url Url opened on tap.
+	 * @param {boolean} webview_interaction Open inside WhatsApp's in-app webview instead of the system browser.
+	 */
+	// Vanz@Add 22-08-26 (v4.7) --- `merchant_url` is present (and equal to `url`) on every
+	// cta_url button seen in captured client traffic, alongside `url`. Defaulted here rather
+	// than left for the caller to remember; still overridable via options if it should differ.
 	addUrl(display_text = '', url = '', webview_interaction = false, options = {}) {
+		if (!display_text || !url) {
+			throw new TypeError('addUrl(display_text, url) requires both a label and a url');
+		}
 		this._buttons.push({
 			...options,
 			name: 'cta_url',
 			buttonParamsJson: JSON.stringify({
 				display_text,
 				url,
+				merchant_url: url,
 				webview_interaction,
 				...options,
 			}),
@@ -726,7 +850,11 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a `cta_copy` button (copies `copy_code` to the user's clipboard on tap). */
 	addCopy(display_text = '', copy_code = '', options = {}) {
+		if (!display_text || !copy_code) {
+			throw new TypeError('addCopy(display_text, copy_code) requires both a label and the text to copy');
+		}
 		this._buttons.push({
 			name: 'cta_copy',
 			buttonParamsJson: JSON.stringify({
@@ -738,6 +866,138 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/**
+	 * Add an `open_webview` button — opens a titled in-app webview (distinct from
+	 * `cta_url`'s `webview_interaction` flag: this is its own native-flow name).
+	 * @param {string} title Webview title shown in the header bar.
+	 * @param {string} url Url loaded inside the webview.
+	 */
+	addOpenWebview(title = '', url = '', options = {}) {
+		if (!title || !url) {
+			throw new TypeError('addOpenWebview(title, url) requires both a title and a url');
+		}
+		this._buttons.push({
+			name: 'open_webview',
+			buttonParamsJson: JSON.stringify({
+				title,
+				link: { url },
+				...options,
+			}),
+		});
+		return this;
+	}
+
+	/**
+	 * Add a `cta_catalog` button (opens the sender's WhatsApp Business catalog).
+	 * Vanz@Add 22-08-26 (v4.7) --- WA only shows the catalog action for accounts
+	 * that actually have a catalog attached; on regular accounts the button may
+	 * render inert. See Button.#SPECIAL_FLOW for the native-flow node this name requires.
+	 */
+	addCatalog(display_text = '', options = {}) {
+		this._buttons.push({
+			name: 'cta_catalog',
+			buttonParamsJson: JSON.stringify({
+				...(display_text ? { display_text } : {}),
+				...options,
+			}),
+		});
+		return this;
+	}
+
+	/**
+	 * Add an `automated_greeting_message_view_catalog` button — the "View catalog"
+	 * action WhatsApp Business shows on the automated greeting message.
+	 * Vanz@Add 22-08-26 (v4.7). Business-account only; see Button.#SPECIAL_FLOW.
+	 */
+	addViewCatalog(options = {}) {
+		this._buttons.push({
+			name: 'automated_greeting_message_view_catalog',
+			buttonParamsJson: JSON.stringify(options),
+		});
+		return this;
+	}
+
+	/**
+	 * Add a `call_permission_request` button — asks the user to grant call
+	 * permission before a voice/video call can be placed.
+	 * Vanz@Add 22-08-26 (v4.7). See Button.#SPECIAL_FLOW.
+	 */
+	addCallPermission(display_text = '', options = {}) {
+		this._buttons.push({
+			name: 'call_permission_request',
+			buttonParamsJson: JSON.stringify({
+				...(display_text ? { display_text } : {}),
+				...options,
+			}),
+		});
+		return this;
+	}
+
+	/**
+	 * Add a `payment_info` button carrying a structured payment-settings payload
+	 * (e.g. a PIX static-code block). Payload shape is dictated by WhatsApp's
+	 * payment flows and is passed through as given — validate it yourself.
+	 * Vanz@Add 22-08-26 (v4.7). Business/payment-enabled accounts only.
+	 * @param {Record<string, any>} payload e.g. `{ payment_settings: [{ type: 'pix_static_code', pix_static_code: {...} }] }`.
+	 */
+	addPaymentInfo(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+			throw new TypeError('addPaymentInfo(payload) requires a plain object');
+		}
+		this._buttons.push({
+			name: 'payment_info',
+			buttonParamsJson: JSON.stringify(payload),
+		});
+		return this;
+	}
+
+	/**
+	 * Add a `review_and_pay` button (order/payment summary flow).
+	 * Vanz@Add 22-08-26 (v4.7). Server-validated by WhatsApp; malformed or
+	 * unauthorized payloads are typically ignored rather than erroring locally.
+	 * @param {Record<string, any>} payload Order/payment summary payload.
+	 */
+	addReviewAndPay(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+			throw new TypeError('addReviewAndPay(payload) requires a plain object');
+		}
+		this._buttons.push({
+			name: 'review_and_pay',
+			buttonParamsJson: JSON.stringify(payload),
+		});
+		return this;
+	}
+
+	/**
+	 * Add a `wa_payment_transaction_details` button referencing a prior transaction.
+	 * Vanz@Add 22-08-26 (v4.7). See Button.#SPECIAL_FLOW.
+	 */
+	addTransactionDetails(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+			throw new TypeError('addTransactionDetails(payload) requires a plain object');
+		}
+		this._buttons.push({
+			name: 'wa_payment_transaction_details',
+			buttonParamsJson: JSON.stringify(payload),
+		});
+		return this;
+	}
+
+	/**
+	 * Add an `mpm` (multi-product message) button referencing a set of catalog items.
+	 * Vanz@Add 22-08-26 (v4.7). Business-catalog accounts only; see Button.#SPECIAL_FLOW.
+	 */
+	addMultiProduct(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+			throw new TypeError('addMultiProduct(payload) requires a plain object');
+		}
+		this._buttons.push({
+			name: 'mpm',
+			buttonParamsJson: JSON.stringify(payload),
+		});
+		return this;
+	}
+
 	// Vanz@Fix (bug 43) --- paramsList documented the schema for these 3 message-level native flow
 	// params (limited_time_offer / bottom_sheet / tap_target_configuration) but no helper ever wrote
 	// them into this._params — only manual setParams() could, with zero validation against the
@@ -756,6 +1016,7 @@ class Button extends BaseBuilder {
 		}
 	}
 
+	/** Set the message-level "limited time offer" strip (countdown banner above the buttons). */
 	setLimitedTimeOffer({ text = '', url = '', copy_code = '', expiration_time } = {}) {
 		const data = { text, url, copy_code, expiration_time };
 		Button.#validateAgainstSchema(Button.paramsList.limited_time_offer, data, 'limited_time_offer');
@@ -763,6 +1024,7 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Configure how many buttons show inline before the rest collapse into a bottom sheet. */
 	setBottomSheet({ in_thread_buttons_limit, divider_indices = [], list_title = '', button_title = '' } = {}) {
 		const data = { in_thread_buttons_limit, divider_indices, list_title, button_title };
 		Button.#validateAgainstSchema(Button.paramsList.bottom_sheet, data, 'bottom_sheet');
@@ -770,6 +1032,7 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+	/** Configure the tap-target callout shown pointing at a specific button by index. */
 	setTapTargetConfiguration({ title = '', description = '', canonical_url = '', domain = '', buttonIndex = 0 } = {}) {
 		const data = { title, description, canonical_url, domain, buttonIndex };
 		Button.#validateAgainstSchema(Button.paramsList.tap_target_configuration, data, 'tap_target_configuration');
@@ -799,6 +1062,25 @@ class Button extends BaseBuilder {
 		},
 	};
 
+	// Vanz@Add 22-08-26 (v4.7) --- native-flow names WA treats specially: the client
+	// only recognises these when the *first* button's name matches AND the wrapping
+	// <native_flow> biz-node carries the right v/name for that name. Everything not
+	// listed here (quick_reply, cta_url, cta_call, cta_copy, single_select mixed with
+	// others, etc.) uses the generic v=9 name=mixed node, which is what send() emitted
+	// unconditionally before this change. Table cross-checked against the observed
+	// wire behaviour documented by zqdevelopers/zq_baileys_helper and @chatunity/baileys.
+	static #SPECIAL_FLOW = {
+		review_and_pay: { v: '1', name: 'order_details' },
+		payment_info: { v: '1', name: 'payment_info' },
+		mpm: { v: '2', name: 'mpm' },
+		cta_catalog: { v: '2', name: 'cta_catalog' },
+		send_location: { v: '2', name: 'send_location' },
+		call_permission_request: { v: '2', name: 'call_permission_request' },
+		wa_payment_transaction_details: { v: '2', name: 'wa_payment_transaction_details' },
+		automated_greeting_message_view_catalog: { v: '2', name: 'automated_greeting_message_view_catalog' },
+	};
+
+	/** Render this builder's header/body/footer/media/buttons/params into an `interactiveMessage`-shaped card (without the outer `interactiveMessage` wrapper or contextInfo). */
 	async toCard() {
 		return {
 			body: {
@@ -825,7 +1107,50 @@ class Button extends BaseBuilder {
 		};
 	}
 
+	// Vanz@Fix (bug: single_select alone doesn't render) --- WhatsApp only renders a
+	// `single_select` native_flow button when it's mixed with other native_flow buttons
+	// (biz node <native_flow v='9' name='mixed'>). 'single_select' is NOT in the set of
+	// button names WA treats as a standalone native_flow type (confirmed against
+	// itsliaaa/baileys WABinary/generic-utils.js getBizBinaryNode() — it special-cases
+	// message.listMessage separately, with its own biz node <list v='2' type='product_list'>,
+	// and never routes 'single_select' through the single-type native_flow path).
+	// A lone single_select must be sent as a legacy `listMessage` instead.
+	#isLoneSingleSelect() {
+		return this._buttons.length === 1 && this._buttons[0].name === 'single_select';
+	}
+
+	#toListMessage() {
+		const { title: buttonText, sections } = JSON.parse(this._buttons[0].buttonParamsJson);
+		return {
+			listMessage: {
+				title: this._title || undefined,
+				description: this._body || undefined,
+				footerText: this._footer || undefined,
+				buttonText: buttonText || undefined,
+				listType: 1,
+				sections: (sections || []).map((s) => ({
+					title: s.title,
+					rows: (s.rows || []).map((r) => ({
+						title: r.title || r.header || '',
+						description: r.description || '',
+						rowId: r.id || '',
+					})),
+				})),
+				contextInfo: this._contextInfo,
+			},
+		};
+	}
+
+	/** @returns {Record<string, any>} The final content object, without generating/wrapping a WAMessage. Useful when composing this interactive card into something else (e.g. Carousel). */
 	async build(jid, { ...options } = {}) {
+		if (this._buttons.length === 0) {
+			throw new Error('Button requires at least one button (use addReply/addUrl/addCall/addSelection/addButton/...)');
+		}
+
+		if (this.#isLoneSingleSelect()) {
+			return generateWAMessageFromContent(jid, { ...this._extraPayload, ...this.#toListMessage() }, { ...options });
+		}
+
 		const message = await this.toCard();
 
 		return generateWAMessageFromContent(
@@ -841,22 +1166,35 @@ class Button extends BaseBuilder {
 		);
 	}
 
+	// Vanz@Add 22-08-26 (v4.7) --- picks the native_flow node variant for the first
+	// button's name, per Button.#SPECIAL_FLOW. Falls back to the generic mixed node
+	// (previous unconditional behaviour) for anything not in that map.
+	#buildNativeFlowNode() {
+		const special = Button.#SPECIAL_FLOW[this._buttons[0]?.name];
+		return special ? { tag: 'native_flow', attrs: special } : { tag: 'native_flow', attrs: { v: '9', name: 'mixed' } };
+	}
+
+	/** Build and send this interactive message. @param {string} jid Destination chat/group jid. */
 	async send(jid, { ...options } = {}) {
 		const msg = await this.build(jid, options);
 
+		const bizContent = this.#isLoneSingleSelect()
+			? [{ tag: 'list', attrs: { v: '2', type: 'product_list' } }]
+			: [
+					{
+						tag: 'interactive',
+						attrs: { type: 'native_flow', v: '1' },
+						content: [this.#buildNativeFlowNode()],
+					},
+				];
+
 		await this.#client.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' } }],
-						},
-					],
+					content: bizContent,
 				},
 			],
 			...options,
@@ -865,9 +1203,15 @@ class Button extends BaseBuilder {
 	}
 }
 
+/**
+ * Legacy `buttonsMessage` builder (up to 3 simple quick-reply buttons under a
+ * media/location header). Simpler and more universally supported than
+ * `Button`'s native-flow messages, but capped to `type: 1` quick replies.
+ */
 class ButtonV2 extends BaseBuilder {
 	#client;
 
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket. */
 	constructor(client) {
 		super();
 		if (!client) {
@@ -880,7 +1224,9 @@ class ButtonV2 extends BaseBuilder {
 		this._buttons = [];
 	}
 
+	/** Add a simple quick-reply button. @param {string} displayText Label. @param {string} [buttonId] Defaults to a random uuid. */
 	addButton(displayText = '', buttonId = crypto.randomUUID()) {
+		if (!displayText) throw new TypeError('addButton(displayText) requires a non-empty label');
 		this._buttons.push({
 			buttonId,
 			buttonText: { displayText },
@@ -889,6 +1235,7 @@ class ButtonV2 extends BaseBuilder {
 		return this;
 	}
 
+	/** Push a raw pre-built button object, bypassing the `addButton()` shorthand. */
 	addRawButton(obj) {
 		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
 			throw new TypeError('Buttons must be a plain object');
@@ -898,12 +1245,14 @@ class ButtonV2 extends BaseBuilder {
 		return this;
 	}
 
+	/** Set the header thumbnail (used as a fallback location-header image when no `setMedia()` header is given). */
 	setThumbnail(path) {
 		if (!path) throw new Error('Url or buffer needed');
 		this._image = path;
 		return this;
 	}
 
+	/** Set a raw pre-built header media object for the buttons message. */
 	setMedia(obj) {
 		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
 			throw new TypeError('Media must be a plain object');
@@ -913,8 +1262,15 @@ class ButtonV2 extends BaseBuilder {
 		return this;
 	}
 
-	async build(jid, { ...options } = {}) {
-		let _thumbnail = this._image ? await Toolkit.resize(Buffer.isBuffer(this._image) ? this._image : await Toolkit.fetchBuffer(this._image, {}, { silent: true }), 300, 300) : null;
+	// Vanz@Fix 22-08-26 (v4.7) --- _thumbnail was computed unconditionally (fetch + resize) even
+	// when setMedia() is used, in which case the location-fallback header (the only place
+	// _thumbnail is used) never runs at all — wasted network/CPU work on every build() call.
+	// Now only computed when it'll actually be used. Also: `viewOnce` was hardcoded true with no
+	// way to opt out (kept as the default — some clients need it to render legacy buttonsMessage
+	// at all — but it's now a `{ viewOnce = true }` option instead of a hardcoded literal).
+	/** @returns {Promise<Record<string, any>>} The generated WAMessage (without sending). @param {boolean} [viewOnce] Default true — some clients require this for legacy buttonsMessage to render; pass false to send it as a normal (non-disappearing) message. */
+	async build(jid, { viewOnce = true, ...options } = {}) {
+		const _thumbnail = !this._data && this._image ? await Toolkit.resize(Buffer.isBuffer(this._image) ? this._image : await Toolkit.fetchBuffer(this._image, {}, { silent: true }), 300, 300) : null;
 		const msg = generateWAMessageFromContent(
 			jid,
 			{
@@ -934,7 +1290,7 @@ class ButtonV2 extends BaseBuilder {
 									jpegThumbnail: _thumbnail,
 								},
 							}),
-					viewOnce: true,
+					viewOnce,
 					contextInfo: this._contextInfo,
 					buttons: [...this._buttons],
 				},
@@ -944,6 +1300,7 @@ class ButtonV2 extends BaseBuilder {
 		return msg;
 	}
 
+	/** Build and send this buttons message. @param {string} jid Destination chat/group jid. */
 	async send(jid, { ...options } = {}) {
 		if (this._buttons.length < 1) throw new Error('ButtonV2 requires at least one button');
 		const msg = await this.build(jid, options);
@@ -969,9 +1326,16 @@ class ButtonV2 extends BaseBuilder {
 	}
 }
 
+/** Carousel of interactive cards (each with its own header media + optional buttons), scrollable horizontally in-chat. */
 class Carousel extends BaseBuilder {
 	#client;
 
+	// Vanz@Add 22-08-26 (v4.7) --- WhatsApp caps carousels at 10 cards; anything beyond
+	// that is silently truncated client-side, so failing fast here is more useful than
+	// shipping a carousel that quietly loses cards.
+	static MAX_CARDS = 10;
+
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket. */
 	constructor(client) {
 		super();
 		if (!client) {
@@ -982,6 +1346,11 @@ class Carousel extends BaseBuilder {
 		this._cards = [];
 	}
 
+	/**
+	 * Add one card, or an array of cards, to the carousel.
+	 * @param {Record<string, any>|Record<string, any>[]} card A card (or array of cards) with `header.hasMediaAttachment: true`
+	 *   — typically built via `new Button(client).setImage(...).addUrl(...).toCard()`.
+	 */
 	addCard(card) {
 		const cards = Array.isArray(card) ? card : [card];
 		const baseIndex = this._cards.length;
@@ -992,10 +1361,15 @@ class Carousel extends BaseBuilder {
 			}
 		}
 
+		if (this._cards.length + cards.length > Carousel.MAX_CARDS) {
+			throw new Error(`Carousel supports at most ${Carousel.MAX_CARDS} cards (got ${this._cards.length + cards.length})`);
+		}
+
 		this._cards.push(...cards);
 		return this;
 	}
 
+	/** @returns {Record<string, any>} The generated WAMessage (without sending). */
 	build(jid, { ...options } = {}) {
 		return generateWAMessageFromContent(
 			jid,
@@ -1017,7 +1391,10 @@ class Carousel extends BaseBuilder {
 		);
 	}
 
+	/** Build and send this carousel. @param {string} jid Destination chat/group jid. */
 	async send(jid, { ...options } = {}) {
+		if (this._cards.length === 0) throw new Error('Carousel requires at least one card (use addCard())');
+
 		const msg = this.build(jid, options);
 
 		await this.#client.relayMessage(msg.key.remoteJid, msg.message, {
@@ -1041,6 +1418,150 @@ class Carousel extends BaseBuilder {
 	}
 }
 
+/**
+ * Vanz@Add (v4.8) --- Chainable poll builder, wrapping the socket's own well-tested
+ * `sendMessage({ poll })` path (see messages.js) instead of hand-building
+ * pollCreationMessageV3/V5 over relayMessage. Two things from the traffic you sent were
+ * deliberately NOT implemented here because they can't be built with confidence:
+ *   1. Per-option poll images (`values: [{ name, image }]`) — the proto this fork ships
+ *      only has a plain `optionName` string per option; an image-poll option isn't a named
+ *      field anywhere in it. The one place an image-poll concept even appears
+ *      (`pollCreationOptionImageMessage`) is typed as an opaque `FutureProofMessage` (a
+ *      forward-compat envelope with no documented inner layout) — there's no field list to
+ *      target, so adding "support" for it would just be silently dropping the image and
+ *      guessing at a shape. Flagging instead of faking it.
+ *   2. Quiz-mode `correctAnswer.optionHash` built by hand — the one working example you
+ *      captured had a 65-character hex string where a sha256 digest should be 64, and this
+ *      builder's target `sendMessage({poll})` path (pollCreationMessageV5) already computes
+ *      quiz mode correctly from a plain `correctAnswer` string, so `setQuiz()` below defers to
+ *      that existing, already-tested logic rather than reimplementing the hash.
+ */
+class Poll extends BaseBuilder {
+	#client;
+
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket (must expose `sendMessage`). */
+	constructor(client) {
+		super();
+		if (!client) throw new Error('Socket is required');
+		this.#client = client;
+
+		this._name = '';
+		this._values = [];
+		this._selectableCount = 1;
+		this._hideVoter = false;
+		this._canAddOption = false;
+		this._toAnnouncementGroup = false;
+		this._correctAnswer;
+		this._endDate;
+	}
+
+	/** Set the poll question/title. */
+	setName(name) {
+		if (typeof name !== 'string' || !name) throw new TypeError('setName(name) requires a non-empty string');
+		this._name = name;
+		return this;
+	}
+
+	/** Append one option. Chainable — call repeatedly, or use `addOptions()` for an array. */
+	addOption(name) {
+		if (typeof name !== 'string' || !name) throw new TypeError('addOption(name) requires a non-empty string');
+		this._values.push(name);
+		return this;
+	}
+
+	/** Append several options at once. @param {string[]} names */
+	addOptions(names) {
+		if (!Array.isArray(names) || !names.length) throw new TypeError('addOptions(names) requires a non-empty array of strings');
+		names.forEach((name) => this.addOption(name));
+		return this;
+	}
+
+	/** How many options a voter can pick (default 1). Use `setMultiSelect()` for unlimited. */
+	setSelectable(count) {
+		if (typeof count !== 'number' || count < 0) throw new TypeError('setSelectable(count) requires a non-negative number');
+		this._selectableCount = count;
+		return this;
+	}
+
+	/** Shortcut for unlimited-choice polls (`selectableCount: 0`). Pass `false` to revert to single-select. */
+	setMultiSelect(canSelectMultiple = true) {
+		this._selectableCount = canSelectMultiple ? 0 : 1;
+		return this;
+	}
+
+	/** Hide voter names from other participants (where the client supports it). */
+	setHideVoter(hide = true) {
+		this._hideVoter = hide;
+		return this;
+	}
+
+	/** Allow voters to add their own options. */
+	setCanAddOption(allow = true) {
+		this._canAddOption = allow;
+		return this;
+	}
+
+	/** Mark this a community-announcement-group poll (pollCreationMessageV2 path). */
+	setAnnouncementGroup(isAnnouncement = true) {
+		this._toAnnouncementGroup = isAnnouncement;
+		return this;
+	}
+
+	/** Auto-close the poll at this date/time. */
+	setEndDate(date) {
+		this._endDate = date instanceof Date ? date : new Date(date);
+		return this;
+	}
+
+	/**
+	 * Turn this into a quiz: one option is marked correct. Delegates the actual hash/version
+	 * wiring to the socket's own `sendMessage({poll:{...correctAnswer}})` handling — see class
+	 * docblock for why this builder doesn't compute the hash itself.
+	 * @param {string} correctOptionName Must exactly match one of the strings passed to `addOption()`/`addOptions()`.
+	 */
+	setQuiz(correctOptionName) {
+		if (typeof correctOptionName !== 'string' || !correctOptionName) {
+			throw new TypeError('setQuiz(correctOptionName) requires a non-empty string');
+		}
+		this._correctAnswer = correctOptionName;
+		return this;
+	}
+
+	/** @returns {{poll: Record<string, any>}} The `sendMessage()`-shaped poll payload, without sending it. */
+	build() {
+		if (!this._name) throw new Error('Poll requires a name (use setName())');
+		if (this._values.length < 2) throw new Error('Poll requires at least 2 options (use addOption()/addOptions())');
+		if (this._correctAnswer && !this._values.includes(this._correctAnswer)) {
+			throw new Error('setQuiz(correctOptionName) must match one of the added options exactly');
+		}
+
+		return {
+			poll: {
+				name: this._name,
+				values: this._values,
+				selectableCount: this._selectableCount,
+				toAnnouncementGroup: this._toAnnouncementGroup,
+				hideVoter: this._hideVoter,
+				canAddOption: this._canAddOption,
+				...(this._endDate && { endDate: this._endDate }),
+				...(this._correctAnswer && { pollType: 1, correctAnswer: this._correctAnswer }),
+			},
+		};
+	}
+
+	/** Build and send via the socket's `sendMessage()`. */
+	async send(jid, options = {}) {
+		return this.#client.sendMessage(jid, this.build(), options);
+	}
+}
+
+/**
+ * "Rich AI-response" style message builder: text with hyperlink/citation/latex
+ * inline entities, code blocks, tables, sources, image/video attachments,
+ * inline product/post cards, tip banners and quick-reply suggestions —
+ * everything ChatGPT/Gemini-in-WhatsApp-style bots typically render.
+ * Also exported as `AIVanzxy` / `LeafRich` / `VanzxyAI` / `VanzxyRich` (identical class, alternate names).
+ */
 class AIRich extends BaseBuilder {
 	#client;
 
@@ -1062,6 +1583,7 @@ class AIRich extends BaseBuilder {
 		this._inlineImages = [];
 	}
 
+	/** Push a raw pre-built submessage block (escape hatch for shapes not covered by the add*() helpers). */
 	addSubmessage(submessage) {
 		const items = Array.isArray(submessage) ? submessage : [submessage];
 
@@ -1076,6 +1598,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Push a raw pre-built section wrapper around one or more submessages. */
 	addSection(section) {
 		const items = Array.isArray(section) ? section : [section];
 
@@ -1090,6 +1613,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a text block. `[label](url)` becomes a hyperlink, `[](url)` a numbered citation, `[expr]<img-url>` a rendered latex expression — toggle each via the options. */
 	addText(text, { hyperlink = true, citation = true, latex = true } = {}) {
 		if (typeof text != 'string') {
 			throw new TypeError('Text must be a string');
@@ -1119,6 +1643,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a syntax-highlighted code block. @param {string} language e.g. 'javascript', 'python'. */
 	addCode(language, code) {
 		if (typeof language !== 'string' || typeof code !== 'string') {
 			throw new TypeError('Language and code must be a string');
@@ -1145,6 +1670,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a table. @param {string[][]} table Row-major grid, first row treated as the header. */
 	addTable(table, { hyperlink = true, citation = true, latex = true } = {}) {
 		if (!Array.isArray(table)) {
 			throw new TypeError('Table must be an array');
@@ -1170,6 +1696,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a "Sources" strip. @param {string[]|string[][]} sources Flat list of urls, or `[title, url]` pairs. */
 	addSource(sources = []) {
 		if (!(Array.isArray(sources) && (sources.every((item) => typeof item === 'string') || sources.every((item) => Array.isArray(item) && item.every((v) => typeof v === 'string'))))) {
 			throw new TypeError('Sources must be a string array or an array of string arrays');
@@ -1202,6 +1729,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a horizontally-scrollable reel of image/video items. */
 	addReels(reelsItems = []) {
 		if (
 			!(
@@ -1271,6 +1799,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a full-width image (or grid of images if `imageUrl` is an array). */
 	addImage(imageUrl, { resolveUrl = false } = {}) {
 		if (!(typeof imageUrl === 'string' || Buffer.isBuffer(imageUrl) || (Array.isArray(imageUrl) && imageUrl.every((v) => typeof v === 'string' || Buffer.isBuffer(v))))) {
 			throw new TypeError('imageUrl must be string | buffer | array of string/buffer');
@@ -1329,6 +1858,7 @@ class AIRich extends BaseBuilder {
 	// GRID_IMAGE/GenAIImaginePrimitive section schema instead of GenAIInlineImageUXPrimitive),
 	// which broke client-side unifiedResponse rendering even though the submessage itself was fine.
 	// Mirrors RichSubMessageType.INLINE_IMAGE handling in rich-message-utils.js's toUnified().
+	/** Add an image inline with the surrounding text flow (falls back to a plain imageMessage on send() if the client can't render inline images — see skipImageFallback). */
 	addInlineImage(imageUrl, { text = '', alignment = 'center', tapLinkUrl = '', resolveUrl = false } = {}) {
 		if (!(typeof imageUrl === 'string' || Buffer.isBuffer(imageUrl) || (imageUrl && typeof imageUrl === 'object'))) {
 			throw new TypeError('imageUrl must be string | buffer | { imagePreviewUrl, imageHighResUrl, sourceUrl }');
@@ -1387,6 +1917,7 @@ class AIRich extends BaseBuilder {
 	// fetch-full-video + ffmpeg-frame-extraction + duration-parse round trip per video, which
 	// was the main source of blurose's slower response time. Pass { autoFill: true } to opt
 	// back into the complete/slow path (real thumbnail + duration + file_length).
+	/** Add a video block. */
 	addVideo(videoUrl, { autoFill = false } = {}) {
 		const isObjectVideo = (v) => v && typeof v === 'object' && v.url;
 
@@ -1467,11 +1998,18 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add an inline product card (or array of cards). Each item needs at least a `title`. */
 	addProduct(data = {}) {
 		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
 			throw new TypeError('Product items must be an object or an array of objects');
 		}
 
+		const itemsToCheck = Array.isArray(data) ? data : [data];
+		const missingTitleAt = itemsToCheck.findIndex((item) => !item.title);
+		if (missingTitleAt !== -1) {
+			throw new TypeError(`addProduct() item[${missingTitleAt}] is missing a required "title"`);
+		}
+
 		this._submessages.push({
 			messageType: 2,
 			messageText: '[ Produk tidak dapat dimuat ]',
@@ -1501,6 +2039,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add an inline social-post style card (or array of cards). */
 	addPost(data = {}) {
 		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
 			throw new TypeError('Post items must be an object or an array of objects');
@@ -1540,7 +2079,12 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** Add a small "tip" callout banner. @param {string} text */
 	addTip(text) {
+		if (typeof text !== 'string' || !text) {
+			throw new TypeError('addTip(text) requires a non-empty string');
+		}
+
 		this._submessages.push({
 			messageType: 2,
 			messageText: text,
@@ -1556,6 +2100,328 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	// Vanz@Add 22-08-26 (v4.7) --- addHeading/addImageCard/addWidget/addFooterAction: 4 primitives
+	// reverse-engineered from captured Meta-AI-in-WhatsApp traffic that this project's own crm/snip
+	// tooling (see rich-message-utils.js) dumps for study. Not in any public Baileys schema, so
+	// unknown enum values (kind/state on addWidget's ctas) are passed through as observed rather
+	// than guessed at, and documented as experimental below.
+
+	/** Add a large heading-style text block (`FOATextPrimitive`) — visually distinct from `addText()`'s regular paragraph text. */
+	addHeading(text) {
+		if (typeof text !== 'string' || !text) {
+			throw new TypeError('addHeading(text) requires a non-empty string');
+		}
+
+		this._submessages.push({
+			messageType: 2,
+			messageText: text,
+		});
+
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				text,
+				__typename: 'FOATextPrimitive',
+			})
+		);
+
+		return this;
+	}
+
+	/**
+	 * Add a "ready" static image card (`GenAIImagePrimitive`: preview + full-res, no generating/status
+	 * state) — distinct from `addImage()`'s AI-generation-style `GenAIImaginePrimitive`.
+	 * @param {string|Buffer} previewUrl Preview/thumbnail image.
+	 * @param {string|Buffer} [fullUrl] Full-resolution image; defaults to `previewUrl`.
+	 */
+	addImageCard(previewUrl, fullUrl = previewUrl, { resolveUrl = false } = {}) {
+		if (!(typeof previewUrl === 'string' || Buffer.isBuffer(previewUrl))) {
+			throw new TypeError('addImageCard(previewUrl) requires a string url or buffer');
+		}
+
+		const preview = Toolkit.resolveMedia(this.#client, previewUrl, 'image', { resolveUrl });
+		const full = fullUrl === previewUrl ? preview : Toolkit.resolveMedia(this.#client, fullUrl, 'image', { resolveUrl });
+
+		this._submessages.push({
+			messageType: 1,
+			gridImageMetadata: {
+				gridImageUrl: { imagePreviewUrl: preview },
+				imageUrls: [{ imagePreviewUrl: preview, imageHighResUrl: full, sourceUrl: full }],
+			},
+		});
+
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				preview_image: { url: preview, mime_type: 'image/jpeg', __typename: 'GenAIMediaItem' },
+				full_image: { url: full, mime_type: 'image/jpeg', __typename: 'GenAIMediaItem' },
+				__typename: 'GenAIImagePrimitive',
+			})
+		);
+
+		return this;
+	}
+
+	/**
+	 * Add a "3P extension" widget card (`GenAI3PExtWidgetPrimitive`) — a small panel with a title and
+	 * a row of tappable CTA chips. Per captured traffic these CTAs call back into a tool (`tool_call_id`)
+	 * rather than opening a url; `kind`/`state` semantics beyond the observed `'OTHER'`/`'PENDING'`
+	 * defaults aren't publicly documented, so treat this as experimental.
+	 *
+	 * Vanz@Add (v4.8) --- accepts an `{ layout }` override so consecutive `addWidget()` calls can
+	 * pick different renderings (e.g. one `HScroll` row, one `ActionRow` stack) instead of always
+	 * inferring HScroll-for-array/Single-for-object from the shape of `data`. Also accepts either
+	 * `ctas` (original key, matches the wire field) or `actions` (alias) on each item — whichever
+	 * is present is used; `ctas` wins if both are somehow given.
+	 * @param {Record<string, any>|Record<string, any>[]} data `{ title, ctas|actions: [{ label, tool_call_id?, kind?, state?, toast? }] }` (single or array).
+	 * @param {{layout?: 'Single'|'HScroll'|'ActionRow'|string}} [options] `layout` overrides the default single/array inference.
+	 */
+	addWidget(data = {}, { layout } = {}) {
+		const items = Array.isArray(data) ? data : [data];
+
+		items.forEach((item, i) => {
+			if (!item?.title) {
+				throw new TypeError(`addWidget() item[${i}] is missing a required "title"`);
+			}
+			const ctas = item.ctas ?? item.actions;
+			if (!Array.isArray(ctas) || !ctas.length) {
+				throw new TypeError(`addWidget() item[${i}] requires a non-empty "ctas" (or "actions") array`);
+			}
+		});
+
+		this._submessages.push({
+			messageType: 2,
+			messageText: items.map((item) => item.title).join(', '),
+		});
+
+		const widgets = items.map((item) => {
+			const ctas = item.ctas ?? item.actions;
+			return {
+				header: { title: item.title, __typename: 'GenAI3PExtWidgetStandardHeader' },
+				body: {
+					sections: item.sections ?? [],
+					ctas: ctas.map((cta, idx) => ({
+						label: cta.label ?? '',
+						state: cta.state ?? 'PENDING',
+						kind: cta.kind ?? 'OTHER',
+						tool_call_id: cta.tool_call_id ?? String(idx).padStart(2, '0'),
+						...(cta.toast !== false && {
+							toast: { label: typeof cta.toast === 'string' ? cta.toast : item.title, __typename: 'GenAI3PExtWidgetToast' },
+						}),
+						__typename: 'GenAI3PExtWidgetCTA',
+					})),
+					__typename: item.body_typename ?? 'GenAI3PExtCalendarEventList',
+				},
+				__typename: 'GenAI3PExtWidgetPrimitive',
+			};
+		});
+
+		const resolvedLayout = layout ?? (Array.isArray(data) ? 'HScroll' : 'Single');
+		const asArray = resolvedLayout !== 'Single';
+
+		this._sections.push(AIRich.newLayout(resolvedLayout, asArray ? widgets : widgets[0]));
+
+		return this;
+	}
+
+	/**
+	 * Add footer action link(s) (`GenAIFooterActionPrimitive`) — e.g. "Join our WhatsApp Group/Channel"
+	 * chips shown below the response, separate from `setFooter()`'s plain text footer.
+	 * @param {{text: string, url: string, type?: string}|{text: string, url: string, type?: string}[]} actions
+	 */
+	addFooterAction(actions) {
+		const items = Array.isArray(actions) ? actions : [actions];
+
+		items.forEach((item, i) => {
+			if (!item?.text || !item?.url) {
+				throw new TypeError(`addFooterAction() item[${i}] requires both "text" and "url"`);
+			}
+		});
+
+		const primitives = items.map((item) => ({
+			cta_text: item.text,
+			cta_type: item.type ?? 'OPEN_URL',
+			cta_url: item.url,
+			__typename: 'GenAIFooterActionPrimitive',
+		}));
+
+		this._sections.push(AIRich.newLayout('HScroll', primitives));
+
+		return this;
+	}
+
+	// Vanz@Add (v4.8) --- 8 primitives from the 20-item reference test script that had no
+	// add*() helper yet (Divider/Spacer/Task/ProgressStatus/ThinkingStatus/QuotaUpsell/FOABloks
+	// have no dedicated AIRichResponseSubMessageType — WA carries them purely in the
+	// unifiedResponse view-model JSON, so their submessage falls back to plain AI_RICH_RESPONSE_TEXT
+	// like addTip/addHeading already do. Latex is the one exception: it has a real proto type
+	// (AI_RICH_RESPONSE_LATEX = 8, confirmed in WAProto) with its own latexMetadata, so that one
+	// gets a proper submessage instead of the text fallback.
+
+	/** Add a plain horizontal divider line (`GenAIDividerPrimitive`, no content). */
+	addDivider() {
+		this._submessages.push({ messageType: 2, messageText: '---' });
+		this._sections.push(AIRich.newLayout('Single', { __typename: 'GenAIDividerPrimitive' }));
+		return this;
+	}
+
+	/** Add blank vertical spacing (`GenAISpacerPrimitive`). @param {number} [spacing=1] Spacing unit, per observed traffic. */
+	addSpacer(spacing = 1) {
+		if (typeof spacing !== 'number' || spacing < 0) {
+			throw new TypeError('addSpacer(spacing) requires a non-negative number');
+		}
+		this._submessages.push({ messageType: 2, messageText: `spasi ${spacing}` });
+		this._sections.push(AIRich.newLayout('Single', { spacing, __typename: 'GenAISpacerPrimitive' }));
+		return this;
+	}
+
+	/**
+	 * Add a rendered LaTeX expression (`GenAILatexUXPrimitive`), with a real `AI_RICH_RESPONSE_LATEX`
+	 * submessage (unlike most primitives in this block, this one has a proper proto type).
+	 * @param {string} expression LaTeX source, e.g. `'$$E = mc^2$$'`.
+	 */
+	addLatex(expression) {
+		if (typeof expression !== 'string' || !expression) {
+			throw new TypeError('addLatex(expression) requires a non-empty string');
+		}
+		this._submessages.push({
+			messageType: 8,
+			latexMetadata: { text: expression, expressions: [{ latexExpression: expression }] },
+		});
+		this._sections.push(AIRich.newLayout('Single', { latex_expression: expression, __typename: 'GenAILatexUXPrimitive' }));
+		return this;
+	}
+
+	/**
+	 * Add a task/checklist card (`GenAITaskPrimitive`).
+	 * @param {{task_id?: string, title: string, subtitle?: string, status?: string}} data
+	 */
+	addTask(data = {}) {
+		if (!data?.title) {
+			throw new TypeError('addTask() requires a "title"');
+		}
+		this._submessages.push({ messageType: 2, messageText: `Tugas: ${data.title}` });
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				task_id: data.task_id ?? '',
+				title: data.title,
+				subtitle: data.subtitle ?? '',
+				status: data.status ?? 'IN_PROGRESS',
+				__typename: 'GenAITaskPrimitive',
+			})
+		);
+		return this;
+	}
+
+	/**
+	 * Add a "searching/working" progress banner (`GenAIBotProgressStatusPrimitive`) — a one-shot
+	 * status chip (unlike `addSuggest`, this isn't tappable). Distinct from `addThinkingStatus()`'s
+	 * icon/typename.
+	 * @param {string} title
+	 * @param {{icon?: string, is_in_progress?: boolean}} [options]
+	 */
+	addProgressStatus(title, { icon = 'SEARCH', is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id } = {}) {
+		if (typeof title !== 'string' || !title) {
+			throw new TypeError('addProgressStatus(title) requires a non-empty string');
+		}
+		this._submessages.push({ messageType: 2, messageText: title });
+		const primitive = {
+			title,
+			icon,
+			is_in_progress,
+			meta_search_apps: [],
+			__typename: 'GenAIBotProgressStatusPrimitive',
+		};
+		// NOTE: these two fields must be OMITTED when unset, not sent as `null` —
+		// an explicit null here was reproducibly crashing the WA client renderer
+		// on group-open/media-download. Only include when the caller actually passes one.
+		if (target_secondary_screen_id != null) primitive.target_secondary_screen_id = target_secondary_screen_id;
+		if (target_secondary_screen_tab_id != null) primitive.target_secondary_screen_tab_id = target_secondary_screen_tab_id;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		return this;
+	}
+
+	/** Add a "thinking" status banner (`GenAIBotThinkingStatusPrimitive`). See `addProgressStatus()`. */
+	addThinkingStatus(title, { icon = 'THINKING', is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id, textFallback = true } = {}) {
+		if (typeof title !== 'string' || !title) {
+			throw new TypeError('addThinkingStatus(title) requires a non-empty string');
+		}
+		this._submessages.push({ messageType: 2, messageText: title });
+		const primitive = {
+			title,
+			icon,
+			is_in_progress,
+			meta_search_apps: [],
+			__typename: 'GenAIBotThinkingStatusPrimitive',
+		};
+		// Same crash-avoidance rule as addProgressStatus(): omit, never null.
+		if (target_secondary_screen_id != null) primitive.target_secondary_screen_id = target_secondary_screen_id;
+		if (target_secondary_screen_tab_id != null) primitive.target_secondary_screen_tab_id = target_secondary_screen_tab_id;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		// Safety net: stock WA client doesn't render this primitive's own view (it's meant
+		// as a transient spinner in the official app), so the card shows blank when forwarded.
+		// Append a plain text section so the title is still visible. Set { textFallback: false } to skip.
+		if (textFallback) {
+			this._sections.push(AIRich.newLayout('Single', { text: title, __typename: 'FOATextPrimitive' }));
+		}
+		return this;
+	}
+
+	/**
+	 * Add a subscription-quota-limit upsell card (`GenAIMetaSubsQuotaUpsellPrimitive`).
+	 * @param {{title: string, body?: string, body_line1?: string, body_line2?: string, buttons?: {label: string, action?: string, deeplink?: string}[]}} data
+	 */
+	addQuotaUpsell(data = {}) {
+		if (!data?.title) {
+			throw new TypeError('addQuotaUpsell() requires a "title"');
+		}
+		this._submessages.push({ messageType: 2, messageText: data.title });
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				title: data.title,
+				body: data.body ?? '',
+				body_line1: data.body_line1 ?? '',
+				body_line2: data.body_line2 ?? '',
+				buttons: (data.buttons ?? []).map((b) => ({
+					label: b.label ?? '',
+					action: b.action ?? 'OPEN_DEEPLINK',
+					deeplink: b.deeplink ?? '',
+				})),
+				__typename: 'GenAIMetaSubsQuotaUpsellPrimitive',
+			})
+		);
+		return this;
+	}
+
+	/**
+	 * Add a raw Bloks payload (`FOABloksPrimitive`) — Meta's internal UI-description format.
+	 * Escape hatch: field meaning beyond what's passed through is undocumented, so this is the
+	 * most experimental primitive in this block; pass whatever your captured traffic shows.
+	 * @param {{type: string, data: string, uuid?: string, initial_response?: any, versioning_id?: string}} data
+	 */
+	addBloks(data = {}) {
+		if (!data?.type) {
+			throw new TypeError('addBloks() requires a "type"');
+		}
+		this._submessages.push({ messageType: 2, messageText: 'Bloks' });
+		const primitive = {
+			type: data.type,
+			data: data.data ?? '{}',
+			uuid: data.uuid ?? '',
+			versioning_id: data.versioning_id ?? '',
+			__typename: 'FOABloksPrimitive',
+		};
+		// Omit initial_response entirely when unset — same null-field crash as addProgressStatus/addThinkingStatus.
+		if (data.initial_response != null) primitive.initial_response = data.initial_response;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		// Safety net: FOABloksPrimitive needs a real, client-registered Bloks screen to render
+		// anything — arbitrary/placeholder payloads show up blank. Append a plain text section
+		// so the card isn't empty. Set data.textFallback = false to skip.
+		if (data.textFallback !== false) {
+			this._sections.push(AIRich.newLayout('Single', { text: `Bloks: ${data.type}`, __typename: 'FOATextPrimitive' }));
+		}
+		return this;
+	}
+
+	/** Add tappable follow-up suggestion chips below the message. @param {string|string[]} suggestion */
 	addSuggest(suggestion, { scroll = true, layout } = {}) {
 		if (!(typeof suggestion === 'string' || (Array.isArray(suggestion) && suggestion.every((v) => typeof v === 'string')))) {
 			throw new TypeError('Suggestion must be a string or array of strings');
@@ -1582,6 +2448,7 @@ class AIRich extends BaseBuilder {
 		return this;
 	}
 
+	/** @returns {Promise<Record<string, any>>} The generated AI-rich message content (without wrapping/sending it). */
 	async build({ forwarded = true, notification = false, includesUnifiedResponse = true, includesSubmessages = true, quoted, quotedParticipant, ...options } = {}) {
 		const forward = forwarded
 			? {
@@ -1668,10 +2535,6 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
-	// Vanz@Fix (bug 42 / inline image fallback) --- WA won't render AIRichResponseInlineImageMetadata
-	// for bot-sent messages (confirmed: even a valid WA-CDN url with mediaKey stays blank), so any
-	// image added via addInlineImage() is sent here as a normal imageMessage instead. Pass
-	// { skipImageFallback: true } to opt out and send only the (image-less-looking) rich card.
 	// Vanz@Fix (bug 42 / inline image fallback) --- WA won't render AIRichResponseInlineImageMetadata
 	// for bot-sent messages (confirmed: even a valid WA-CDN url with mediaKey stays blank), so any
 	// image added via addInlineImage() is sent here as a normal imageMessage instead. Pass
@@ -1679,6 +2542,7 @@ class AIRich extends BaseBuilder {
 	// Vanz@Fix: don't spread relayMessage-shaped `options` into sendMessage()'s options param —
 	// the two calls expect different option shapes, so the fallback now only forwards `quoted`
 	// (the one option that clearly applies to both) instead of blindly spreading everything.
+	/** Build and send this AI-rich message. @param {string} jid Destination chat/group jid. @param {boolean} [skipImageFallback] Skip auto-resending inline images as a plain imageMessage. */
 	async send(jid, { forwarded, notification, includesUnifiedResponse, includesSubmessages, skipImageFallback = false, quoted, ...options } = {}) {
 		const msg = await this.build({ forwarded, notification, includesUnifiedResponse, includesSubmessages, quoted, ...options });
 
@@ -1696,6 +2560,7 @@ class AIRich extends BaseBuilder {
 		return await this.#client.relayMessage(jid, msg, { ...options });
 	}
 
+	/** Tokenize `code` into `{ type, value }` spans for syntax highlighting. Covers JS/TS/Python/Java and more; unsupported languages fall back to a single plain-text token. */
 	static tokenizer(code, lang = 'javascript') {
 		const keywordsMap = {
 			javascript: new Set([
@@ -2361,6 +3226,7 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
+	/** Convert a raw `string[][]` grid into the table metadata shape addTable()/addText() produce internally. */
 	static toTableMetadata(arr, { hyperlink = true, citation = true, latex = true } = {}) {
 		if (!Array.isArray(arr) || !arr.every((row) => Array.isArray(row) && row.every((cell) => typeof cell === 'string'))) {
 			throw new TypeError('Table must be a nested array of strings');
@@ -2409,6 +3275,7 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
+	/** Build a raw submessage layout block by name — escape hatch for layouts not covered by the add*() helpers. */
 	static newLayout(name, data, extra = {}) {
 		return {
 			...extra,
@@ -2420,4 +3287,21 @@ class AIRich extends BaseBuilder {
 	}
 }
 
-export { MESSAGE_BUILDER_VERSION, Button, ButtonV2, Carousel, AIRich, Toolkit };
+// Vanz@Alias --- AIRich diekspos ulang pake nama sendiri. Implementasi & referensi
+// internal (AIRich.newLayout/tokenizer/toTableMetadata) TETAP pake nama class asli
+// biar nggak perlu rewrite ratusan pemanggilan; ini cuma nge-alias binding exportnya.
+// Attribution buat base implementation tetep di NOTICE.md, gak kehapus cuma gara-gara
+// alias nama di sini.
+export {
+	MESSAGE_BUILDER_VERSION,
+	Button,
+	ButtonV2,
+	Carousel,
+	Poll,
+	AIRich,
+	AIRich as AIVanzxy,
+	AIRich as LeafRich,
+	AIRich as VanzxyAI,
+	AIRich as VanzxyRich,
+	Toolkit,
+};