@vanzxy/baileys 1.6.3 → 1.6.4

package/NOTICE.md

@@ -29,11 +29,61 @@ inline `Vanz@` comments for specifics): lazy-loading of optional
 and neutral fallback text (previously referenced the original author's
 name in a small number of user-facing fallback strings).
 
+---
+
+## lib/Utils/message-kind.js — button/list "addon kind" resolution
+
+`resolveButtonAddonKind()` is adapted from **zapo-js**
+(`resolveButtonAddonKind` / `resolveNativeFlowAddonKind` in
+`src/message/encode/content.ts`), created by **vinikjkkj**
+<contact@vinicius.email>. <https://github.com/vinikjkkj/zapo>
+
+- License: MIT, Copyright (c) 2026 vinikjkkj
+- Ported into `@vanzxy/baileys` 1.6.4, adapted from zapo's internal
+  `Proto.IMessage` shape to this fork's message-content shape.
+  `parseInteractiveReply()` in the same file is original code written
+  for this fork (not from zapo), covering `buttonsResponseMessage` /
+  `listResponseMessage` / `interactiveResponseMessage` /
+  `templateButtonReplyMessage`.
+
 Additional performance/authenticity reference drawn from `arslan-baileys`
 (1.1.0), which shares the same underlying builder API.
 
 ---
 
+## lib/Utils/button-sender.js + lib/Utils/button-helper-utils.js — interactive/native-flow button send layer
+
+Ported from `@queenanya/baileys` (fork by **QueenAnya** / OLDUSER 06,
+package `@queenanya/baileys`), files `src/addons/button-sender.ts` and
+`src/addons/message-utils.ts`. That fork's own header credits the base
+implementation as "Ported from `@ryuu-reinzz/button-helper` v2.2.5".
+
+- License: MIT (per `@queenanya/baileys` `package.json`)
+- Ported into `@vanzxy/baileys` 1.6.5, converted TS → JS ESM. Adjustments:
+  `console.log`/`console.warn` calls replaced with `sock.logger` (pino)
+  calls to match this fork's logging convention; default dummy-file
+  name/branding strings genericized; import paths rewired to this fork's
+  `Utils`/`WABinary`/`Types` layout (`generateWAMessage`,
+  `generateWAMessageFromContent`, `normalizeMessageContent`,
+  `getUrlFromDirectPath`, `unixTimestampSeconds`, `isJidGroup`,
+  `isJidNewsletter`, `QueryIds`, `XWAPaths`, etc. — all already present
+  in `@vanzxy/baileys` and reused as-is, no duplication).
+- Adds `sendButtons()`, `sendInteractiveMessage()`,
+  `sendInteractiveMessageV2()`, plus supporting validators
+  (`validateSendButtonsPayload`, `validateSendInteractiveMessagePayload`,
+  `validateInteractiveMessageContent`, `validateAuthoringButtons`),
+  `buildInteractiveButtons()`, `convertToInteractiveMessage()`, the
+  `InteractiveValidationError` class, and message-introspection helpers
+  (`getButtonType`, `getButtonArgs`, `getMediaType`, `getMessageType`,
+  `prepareAlbumMessageContent`, `makeMessageExtrasAddon`, etc.). These
+  send buttons via `relayMessage` directly (bypassing `sendMessage`'s
+  validation path, which doesn't recognise `interactiveMessage`
+  payloads) with the correct `biz`/`interactive`/`native_flow` binary
+  nodes so buttons render on WhatsApp Messenger + Business, Android +
+  iOS. Complements the existing `Button`/`ButtonV2`/`ButtonV3` builder
+  classes in `MessageBuilder.js`, which build message *content* — this
+  addon handles the *send* layer.
+
 ## rich-message-utils.js — AIRICH inline-image bug fix
 
 Original implementation is this project's own; fixed 2026-08-15 (bad

package/lib/Utils/A2UI.js

@@ -0,0 +1,217 @@
+/**
+ * lib/Utils/A2UI.js — A2UI (Bloks) widget builder + sender
+ *
+ * Part of @vanzxy/baileys. Builds the flat `components` array A2UI/Bloks
+ * expects (id-referencing tree: Column/Row hold `children`, Card/Button hold
+ * `child`, Modal holds `trigger`/`content`) and sends it as an
+ * `interactiveMessage.bloksWidget` via the same `getBizBinaryNode()` path
+ * Button/ButtonV2 use, so the wire-level <biz>/<native_flow> node always
+ * matches the actual button names sent — no more hand-rolled duplicate of
+ * that logic living outside the library.
+ *
+ * See MessageBuilder.js's `Button.setBloksWidget()` for the declarative
+ * (nested-tree) alternative to this imperative (id-returning-factory) API;
+ * both produce the same wire format and can be mixed freely.
+ */
+"use strict";
+
+import crypto from "crypto";
+import { generateWAMessageFromContent } from "./messages.js";
+import { getBizBinaryNode } from "../WABinary/index.js";
+
+class A2UI {
+	constructor({ catalogId = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json", version = "v0.9" } = {}) {
+		this._version = version;
+		this._catalogId = catalogId;
+		this._components = new Map();
+		this._counter = 0;
+		this._rootChildren = [];
+	}
+	#nextId(prefix) {
+		return `${prefix}_${(this._counter++).toString(36)}`;
+	}
+	#reg(id, component, extra = {}) {
+		id ??= this.#nextId(component.toLowerCase());
+		if (id === "root") throw new Error(`Component id "root" is reserved for the implicit root wrapper`);
+		if (this._components.has(id)) throw new Error(`Component id "${id}" already used`);
+		this._components.set(id, { id, component, ...extra });
+		return id;
+	}
+	text(text, { id, variant = "body" } = {}) {
+		return this.#reg(id, "Text", { text, variant });
+	}
+	image(url, { id, variant, fit = "cover" } = {}) {
+		return this.#reg(id, "Image", { url, ...(variant ? { variant } : {}), fit });
+	}
+	video(url, { id } = {}) {
+		return this.#reg(id, "Video", { url });
+	}
+	checkbox(label, { id, value = false } = {}) {
+		return this.#reg(id, "CheckBox", { label, value });
+	}
+	textField(label, { id, variant = "text" } = {}) {
+		return this.#reg(id, "TextField", { label, variant });
+	}
+	button(childId, { id, variant = "primary", action } = {}) {
+		if (!childId) throw new TypeError("button(childId) requires the id of a child component (e.g. from .text())");
+		return this.#reg(id, "Button", { child: childId, variant, ...(action ? { action } : {}) });
+	}
+	card(childId, { id } = {}) {
+		return this.#reg(id, "Card", { child: childId });
+	}
+	// trigger: id of the component that opens the modal (e.g. a Button); content: id of the
+	// component shown inside it. Both are ids of already-registered SIBLING components, not
+	// nested children — that's how the wire format expects Modal to reference them.
+	modal(triggerId, contentId, { id } = {}) {
+		if (!triggerId) throw new TypeError("modal(triggerId, contentId) requires the id of the trigger component");
+		if (!contentId) throw new TypeError("modal(triggerId, contentId) requires the id of the content component");
+		return this.#reg(id, "Modal", { trigger: triggerId, content: contentId });
+	}
+	// Escape hatch for any catalog component without a dedicated method yet (Divider, Slider,
+	// Switch, List, etc). props is merged as-is into the registered node.
+	raw(component, props = {}, { id } = {}) {
+		if (typeof component !== "string" || !component) throw new TypeError("raw(component, props) requires a non-empty component type string");
+		return this.#reg(id, component, props);
+	}
+	column(children = [], { id } = {}) {
+		if (!children.length) throw new TypeError("column(children) requires at least one child id");
+		return this.#reg(id, "Column", { children });
+	}
+	row(children = [], { id } = {}) {
+		if (!children.length) throw new TypeError("row(children) requires at least one child id");
+		return this.#reg(id, "Row", { children });
+	}
+	divider({ id } = {}) {
+		return this.#reg(id, "Divider", {});
+	}
+	choicePicker(label, options, { id, variant = "mutuallyExclusive", value, displayStyle = "checkbox", filterable = false } = {}) {
+		if (!Array.isArray(options) || !options.length) {
+			throw new TypeError("choicePicker(label, options) requires a non-empty options array of {label, value}");
+		}
+		return this.#reg(id, "ChoicePicker", {
+			label,
+			variant,
+			...(value !== undefined ? { value } : {}),
+			options,
+			displayStyle,
+			filterable
+		});
+	}
+	root(children) {
+		if (!Array.isArray(children) || !children.length) {
+			throw new TypeError("root(children) requires a non-empty array of top-level component ids");
+		}
+		this._rootChildren = children;
+		return this;
+	}
+	// Vanz@Add 29-08-26 --- Product/list carousel card. This is a DIFFERENT wire
+	// payload shape from the Column/Row component-tree the rest of this class
+	// builds (type: 'list_card', flat items array) — not a catalog component, so
+	// it doesn't go through #reg()/root(). Call this instead of root()+build();
+	// build() returns the list_card payload directly when this was set.
+	listCard({ title, items, fallbackText, uuid = crypto.randomUUID() } = {}) {
+		if (!title) throw new TypeError("listCard requires a title");
+		if (!Array.isArray(items) || !items.length) {
+			throw new TypeError("listCard requires a non-empty items array");
+		}
+		this._listCardPayload = {
+			uuid,
+			data: JSON.stringify({
+				type: "list_card",
+				title,
+				fallback_text: fallbackText ?? "",
+				items: items.map((it) => ({
+					asset_id: it.assetId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 17),
+					asset_type: it.assetType ?? "PRODUCT_ITEM",
+					title: it.title,
+					trailing_label: it.price ?? it.trailingLabel ?? "",
+					trailing_emphasis: it.emphasis ?? "strong"
+				}))
+			}),
+			type: "im_a2ui",
+			fallback: fallbackText ?? ""
+		};
+		return this;
+	}
+	build({ uuid = crypto.randomUUID(), surfaceId, type = "im_a2ui", wrapped = true } = {}) {
+		if (this._listCardPayload) return this._listCardPayload;
+		if (!this._rootChildren.length) throw new Error("Call root([...ids]) before build()");
+		const root = { id: "root", component: "Column", children: this._rootChildren };
+		const components = [root, ...this._components.values()];
+		const data = wrapped
+			? {
+					version: this._version,
+					createSurface: {
+						surfaceId: surfaceId ?? `starcore-widget=${uuid}`,
+						catalogId: this._catalogId,
+						components
+					}
+				}
+			: { components };
+		return {
+			uuid,
+			data: JSON.stringify(data),
+			type
+		};
+	}
+}
+
+/**
+ * Build + send an A2UI/Bloks widget as an interactiveMessage.
+ * @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket.
+ * @param {string} jid Destination chat/group jid.
+ */
+async function sendA2UIWidget(client, jid, {
+	a2ui,
+	bodyText = "",
+	footer = "",
+	buttons = [],
+	contextInfo = {},
+	expiration,
+	quoted,
+	type = "im_a2ui",
+	wrapped = true,
+	singleScreen = false
+} = {}) {
+	if (!client) throw new Error("Socket is required");
+	if (!(a2ui instanceof A2UI)) throw new TypeError("a2ui must be an A2UI instance");
+
+	const nativeFlowMessage = buttons && buttons.length
+		? {
+				buttons: buttons.map((b) => ({
+					name: b.name ?? "cta_url",
+					buttonParamsJson: typeof b.params === "string" ? b.params : JSON.stringify(b.params ?? {}),
+				})),
+				messageParamsJson: "{}",
+				messageVersion: 1
+			}
+		: { messageParamsJson: "" };
+
+	const interactiveMessage = singleScreen
+		? {
+				nativeFlowMessage,
+				bloksWidget: a2ui.build({ type, wrapped }),
+				...(expiration || Object.keys(contextInfo).length ? { contextInfo: { ...(expiration ? { expiration } : {}), ...contextInfo } } : {})
+			}
+		: {
+				header: { hasMediaAttachment: false },
+				body: { text: bodyText },
+				...(footer ? { footer: { text: footer } } : {}),
+				nativeFlowMessage,
+				bloksWidget: a2ui.build({ type, wrapped }),
+				...(expiration || Object.keys(contextInfo).length ? { contextInfo: { ...(expiration ? { expiration } : {}), ...contextInfo } } : {})
+			};
+
+	const msg = generateWAMessageFromContent(jid, {
+		messageContextInfo: { messageSecret: crypto.randomBytes(32) },
+		interactiveMessage
+	}, { quoted });
+
+	await client.relayMessage(msg.key.remoteJid, msg.message, {
+		messageId: msg.key.id,
+		additionalNodes: [getBizBinaryNode(msg.message)]
+	});
+	return msg;
+}
+
+export { A2UI, sendA2UIWidget };

package/lib/Utils/MessageBuilder.js

@@ -44,7 +44,7 @@
 
 'use strict';
 
-const MESSAGE_BUILDER_VERSION = '4.9.1';
+const MESSAGE_BUILDER_VERSION = '4.8';
 // Vanz@Fix 24-08-26: use the exported builder version everywhere; the old
 // verification helper referenced an undeclared `VERSION`, making every AIRich.build() fail.
 
@@ -52,6 +52,15 @@ const MESSAGE_BUILDER_VERSION = '4.9.1';
 import { generateWAMessageFromContent, prepareWAMessageMedia } from './messages.js';
 import { generateMessageIDV2 } from './generics.js';
 import { botMetadataSignature, botMetadataCertificate } from './rich-message-utils.js';
+// Vanz@Fix 27-08-26: Button.send() was hand-rolling its own <biz> node with
+// attrs: {} instead of reusing the canonical builder. Real client traffic
+// (and the auto-attached biz node in Socket/messages-send.js) always carries
+// actual_actors/host_storage/privacy_mode_ts on every <biz> node, including
+// the one wrapping a lone single_select's <list> node. Missing them made the
+// single_select wire payload diverge from what messages-send.js emits for
+// every other message type -- import the shared helper instead of duplicating
+// (and silently drifting from) its attrs.
+import { getBizBinaryNode } from '../WABinary/index.js';
 import crypto from 'crypto';
 import { PassThrough, Readable } from 'stream';
 // Vanz@Fix 15-08-26 --- sharp/fluent-ffmpeg were statically imported in the blurose source.
@@ -628,6 +637,46 @@ class BaseBuilder {
 	}
 }
 
+/** Tiny fluent helper for building a single quickReply button row (type 1). Standalone — not tied to Button/ButtonV2. */
+class RowBuilder {
+	constructor() {
+		this.buttons = [];
+	}
+
+	button(displayText, buttonId) {
+		this.buttons.push({ buttonId, buttonText: { displayText }, type: 1 });
+		return this;
+	}
+}
+
+/** Thin fluent wrapper around `Button` for building a single image+title+text+reply "card" in one chain. */
+class CardBuilder {
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket. */
+	constructor(client) {
+		this._card = new Button(client);
+	}
+
+	image(url) {
+		this._card.setImage(url);
+		return this;
+	}
+
+	title(t) {
+		this._card.setTitle(t);
+		return this;
+	}
+
+	text(t) {
+		this._card.setBody(t);
+		return this;
+	}
+
+	button(displayText, id) {
+		this._card.addReply(displayText, id);
+		return this;
+	}
+}
+
 /**
  * Interactive (native-flow) message builder — header/body/footer + a mix of
  * buttons (quick_reply, cta_url, cta_call, single_select, ...). Sends via
@@ -1201,13 +1250,23 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
-	/** WhatsApp Flows `flow_action` shortcut. Requires a real registered Flow. */
+	/** WhatsApp Flows shortcut. Requires a real registered Flow. */
 	addFlow(flow = {}, display_text = '') {
 		if (typeof flow !== 'object' || flow === null || Array.isArray(flow) || !flow.id) throw new TypeError('addFlow(flow) requires a plain object with flow.id');
 		this._buttons.push({
-			name: 'flow_action',
+			// Vanz@Fix 27-08-26: the button name was 'flow_action', which is actually
+			// the *field name* inside buttonParamsJson (flow_action: 'navigate' | 'data_exchange'),
+			// not a native_flow name WhatsApp recognises. The real native_flow name for
+			// launching a registered WhatsApp Flow is 'flow' -- client silently ignored
+			// the button because <native_flow name='flow_action'> isn't a thing it renders.
+			name: 'flow',
 			buttonParamsJson: JSON.stringify({
 				flow_message_version: flow.version || '3',
+				// flow_token: unique per-send session token WhatsApp Flows requires to
+				// correlate a flow_action data-exchange callback with this specific
+				// message. Was missing entirely -- without it the client can accept the
+				// message but has nothing to key the flow session on.
+				flow_token: flow.token || generateMessageIDV2(),
 				flow_id: flow.id,
 				flow_cta: display_text || flow.cta || 'Continue',
 				flow_action: flow.action || 'navigate',
@@ -1405,50 +1464,29 @@ 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' } }]
-			: [
-					...(this._buttons.length > 0
-						? [
-								{
-									tag: 'interactive',
-									attrs: { type: 'native_flow', v: '1' },
-									content: [this.#buildNativeFlowNode()],
-								},
-						  ]
-						: []),
-					...(this._bloksWidget
-						? [
-								{
-									tag: 'quality_control',
-									attrs: { decision_id: crypto.randomUUID().replace(/-/g, ''), source_type: 'third_party' },
-									content: [{ tag: 'decision_source', attrs: { value: 'df' } }],
-								},
-						  ]
-						: []),
-			  ];
+		// Vanz@Fix 27-08-26: delegate the <biz> node to the shared getBizBinaryNode()
+		// helper instead of hand-rolling one here. It already:
+		//  - stamps actual_actors/host_storage/privacy_mode_ts (previously missing,
+		//    the likely cause of single_select's wire being flagged for validation)
+		//  - picks the correct wrapper per button name (FLOWS_MAP dedicated node,
+		//    ORDER_RESPONSE_ALIAS native_flow_name, mixed native_flow, or the
+		//    <list v='2' type='product_list'> node for a lone single_select via
+		//    message.listMessage) using the exact same table messages-send.js uses
+		//    for every non-Button send path, so Button.send() can't silently drift
+		//    out of sync with it.
+		// Button.#SPECIAL_FLOW is kept only as documentation for addFlow()/etc.
+		// JSDoc now (see below); getBizBinaryNode()'s own ORDER_RESPONSE_ALIAS /
+		// FLOWS_MAP tables are what actually pick the wire node -- keep those two
+		// tables in sync if a new special-cased button name is ever added.
+		const bizNode = getBizBinaryNode(msg.message);
 
 		await this.#client.relayMessage(msg.key.remoteJid, msg.message, {
 			messageId: msg.key.id,
-			additionalNodes: [
-				{
-					tag: 'biz',
-					attrs: {},
-					content: bizContent,
-				},
-			],
+			additionalNodes: [bizNode],
 			...options,
 		});
 		return msg;
@@ -1514,6 +1552,24 @@ class ButtonV2 extends BaseBuilder {
 		return this;
 	}
 
+	/** Alias for addButton() — shorthand parity with RowBuilder#button(). */
+	button(displayText, buttonId) {
+		return this.addButton(displayText, buttonId);
+	}
+
+	/**
+	 * Vanz@Add 29-08-26 --- Fluent row helper ported from the RowBuilder class (already
+	 * present but previously unwired into ButtonV2). Lets callers group buttons via a
+	 * callback instead of chaining addButton() calls one at a time.
+	 * @param {(row: RowBuilder) => void} cb
+	 */
+	row(cb) {
+		const r = new RowBuilder();
+		cb(r);
+		r.buttons.forEach((b) => this._buttons.push(b));
+		return this;
+	}
+
 	// 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.
@@ -1578,6 +1634,193 @@ class ButtonV2 extends BaseBuilder {
 	}
 }
 
+/**
+ * Legacy `templateMessage` / `hydratedFourRowTemplate` builder — WA's Generation-1
+ * button protocol (predates the nativeFlow format that Button/ButtonV2 use).
+ * Capped at 3 buttons (quickReply/url/call only), no interactive list/flow support.
+ * Ported from MessageBuilderV4.7.
+ */
+class ButtonV3 extends BaseBuilder {
+	#client;
+
+	/** @param {import('../../WAProto/index.js').WASocket} client Active Baileys socket. */
+	constructor(client) {
+		super();
+		if (!client) {
+			throw new Error('Socket is required');
+		}
+
+		this.#client = client;
+		this._data;
+		this._mediaHeaderType = null;
+		this._buttons = [];
+	}
+
+	/** Load an existing templateMessage (e.g. from a fetched/quoted message) for editing. */
+	loadFrom(msg) {
+		if (!msg) throw new Error('templateMessage needed');
+		if (!msg.templateMessage) throw new Error('templateMessage not found');
+
+		const { templateMessage, ...extraPayload } = msg;
+		const hft = templateMessage.hydratedFourRowTemplate || {};
+
+		this._title = hft.hydratedTitleText || '';
+		this._body = hft.hydratedContentText || '';
+		this._footer = hft.hydratedFooterText || '';
+		this._contextInfo = templateMessage.contextInfo || {};
+		this._extraPayload = extraPayload;
+
+		this._buttons = Array.isArray(hft.hydratedButtons)
+			? hft.hydratedButtons.map((button) => ({ ...button }))
+			: [];
+
+		if (hft.imageMessage) {
+			this._data = { imageMessage: hft.imageMessage };
+			this._mediaHeaderType = 'imageMessage';
+		} else if (hft.videoMessage) {
+			this._data = { videoMessage: hft.videoMessage };
+			this._mediaHeaderType = 'videoMessage';
+		} else if (hft.documentMessage) {
+			this._data = { documentMessage: hft.documentMessage };
+			this._mediaHeaderType = 'documentMessage';
+		} else if (hft.locationMessage) {
+			this._data = { locationMessage: hft.locationMessage };
+			this._mediaHeaderType = 'locationMessage';
+		} else {
+			this._data = undefined;
+			this._mediaHeaderType = null;
+		}
+
+		return this;
+	}
+
+	setImage(path, options = {}) {
+		if (!path) throw new Error('Url or buffer needed');
+		this._data = Buffer.isBuffer(path)
+			? { image: path, ...options }
+			: { image: { url: path }, ...options };
+		this._mediaHeaderType = 'imageMessage';
+		return this;
+	}
+
+	setVideo(path, options = {}) {
+		if (!path) throw new Error('Url or buffer needed');
+		this._data = Buffer.isBuffer(path)
+			? { video: path, ...options }
+			: { video: { url: path }, ...options };
+		this._mediaHeaderType = 'videoMessage';
+		return this;
+	}
+
+	setDocument(path, options = {}) {
+		if (!path) throw new Error('Url or buffer needed');
+		this._data = Buffer.isBuffer(path)
+			? { document: path, ...options }
+			: { document: { url: path }, ...options };
+		this._mediaHeaderType = 'documentMessage';
+		return this;
+	}
+
+	setMedia(obj) {
+		if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+			throw new TypeError('Media must be a plain object');
+		}
+		this._data = obj;
+		this._mediaHeaderType = null; // caller is expected to pass an already-resolved shape
+		return this;
+	}
+
+	clearButtons() {
+		this._buttons = [];
+		return this;
+	}
+
+	addButton(hydratedButton) {
+		if (this._buttons.length >= 3) {
+			throw new Error('ButtonV3 (TemplateMessage) supports a maximum of 3 buttons');
+		}
+		this._buttons.push({ index: this._buttons.length + 1, ...hydratedButton });
+		return this;
+	}
+
+	addReply(display_text = '', id = '') {
+		return this.addButton({
+			quickReplyButton: { displayText: display_text, id },
+		});
+	}
+
+	addUrl(display_text = '', url = '', options = {}) {
+		return this.addButton({
+			urlButton: { displayText: display_text, url, ...options },
+		});
+	}
+
+	addCall(display_text = '', phone_number = '') {
+		return this.addButton({
+			callButton: { displayText: display_text, phoneNumber: phone_number },
+		});
+	}
+
+	async toTemplate() {
+		let mediaFields = {};
+
+		if (this._data) {
+			const alreadyResolved =
+				this._data.imageMessage || this._data.videoMessage ||
+				this._data.documentMessage || this._data.locationMessage;
+
+			mediaFields = alreadyResolved
+				? this._data
+				: await prepareWAMessageMedia(this._data, {
+						upload: this.#client.waUploadToServer,
+					}).catch((e) => {
+						if (String(e).includes('Invalid media type')) return this._data;
+						throw e;
+					});
+		} else if (this._title) {
+			mediaFields = { hydratedTitleText: this._title };
+		}
+
+		return {
+			hydratedContentText: this._body,
+			hydratedFooterText: this._footer,
+			hydratedButtons: this._buttons,
+			...mediaFields,
+		};
+	}
+
+	async build(jid, { messageId, ...options } = {}) {
+		const hydratedFourRowTemplate = await this.toTemplate();
+
+		return generateWAMessageFromContent(
+			jid,
+			{
+				...this._extraPayload,
+				templateMessage: {
+					hydratedFourRowTemplate,
+					contextInfo: this._contextInfo,
+				},
+			},
+			{ messageId: messageId || generateMessageIDV2(), ...options },
+		);
+	}
+
+	async send(jid, { messageId, additionalNodes = [], ...options } = {}) {
+		if (this._buttons.length < 1)
+			throw new Error('ButtonV3 requires at least one button');
+		const msg = await this.build(jid, { messageId, ...options });
+
+		// TemplateMessage predates the nativeFlow protocol and does not need the
+		// "biz"/"native_flow" additionalNodes hack that Button/ButtonV2 use.
+		await this.#client.relayMessage(msg.key.remoteJid, msg.message, {
+			messageId: msg.key.id,
+			additionalNodes,
+			...options,
+		});
+		return msg;
+	}
+}
+
 /** Carousel of interactive cards (each with its own header media + optional buttons), scrollable horizontally in-chat. */
 class Carousel extends BaseBuilder {
 	#client;
@@ -4054,6 +4297,9 @@ class AIRich extends BaseBuilder {
 	}
 }
 
+/** Thin no-op subclass of `AIRich` — kept for drop-in compatibility with code ported from ourin-baileys that references `ORich` by name. */
+class ORich extends AIRich {}
+
 // 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.
@@ -4063,9 +4309,13 @@ export {
 	MESSAGE_BUILDER_VERSION,
 	Button,
 	ButtonV2,
+	ButtonV3,
+	RowBuilder,
+	CardBuilder,
 	Carousel,
 	Poll,
 	AIRich,
+	ORich,
 	AIRich as AIVanzxy,
 	AIRich as LeafRich,
 	AIRich as VanzxyAI,