@vanzxy/baileys 2.0.0 → 2.0.2

package/lib/Builders/ButtonV2.js

@@ -0,0 +1,144 @@
+import { BaseBuilder, Toolkit, RowBuilder, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2, crypto } from './shared.js';
+class ButtonV2 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._image;
+		this._data;
+		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 },
+			type: 1,
+		});
+		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');
+		}
+
+		this._buttons.push(obj);
+		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');
+		}
+
+		this._data = obj;
+		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.
+	// 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,
+			{
+				...this._extraPayload,
+				buttonsMessage: {
+					contentText: this._body,
+					footerText: this._footer,
+					...(this._data
+						? this._data
+						: {
+								headerType: 6,
+								locationMessage: {
+									degreesLatitude: 0,
+									degreesLongitude: 0,
+									name: this._title,
+									address: this._subtitle,
+									jpegThumbnail: _thumbnail,
+								},
+							}),
+					viewOnce,
+					contextInfo: this._contextInfo,
+					buttons: [...this._buttons],
+				},
+			},
+			{ ...options }
+		);
+		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);
+
+		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' } }],
+						},
+					],
+				},
+			],
+			...options,
+		});
+		return msg;
+	}
+}
+
+/**
+ * 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.
+ */
+export { ButtonV2 };

package/lib/Builders/ButtonV3.js

@@ -0,0 +1,184 @@
+import { BaseBuilder, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2, crypto } from './shared.js';
+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. */
+export { ButtonV3 };

package/lib/Builders/Carousel.js

@@ -0,0 +1,111 @@
+import { BaseBuilder, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2, crypto } from './shared.js';
+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) {
+			throw new Error('Socket is required');
+		}
+
+		this.#client = client;
+		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;
+
+		for (const [index, c] of cards.entries()) {
+			if (!c?.header?.hasMediaAttachment) {
+				throw new Error(`Card [${baseIndex + index}] must include an image or video in header`);
+			}
+		}
+
+		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,
+			{
+				...this._extraPayload,
+				interactiveMessage: {
+					header: {
+						hasMediaAttachment: false,
+					},
+					body: { text: this._body },
+					footer: { text: this._footer },
+					contextInfo: this._contextInfo,
+					carouselMessage: {
+						cards: this._cards,
+					},
+				},
+			},
+			{ ...options }
+		);
+	}
+
+	/** 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, {
+			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' } }],
+						},
+					],
+				},
+			],
+			...options,
+		});
+		return msg;
+	}
+}
+
+/**
+ * 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.
+ */
+export { Carousel };

package/lib/Builders/Contact.js

@@ -0,0 +1,83 @@
+import { BaseBuilder, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2, crypto } from './shared.js';
+
+/**
+ * Contact-card message builder — one contact sends as `contactMessage`, two or
+ * more as `contactsArrayMessage` (both handled by the existing `message.contacts`
+ * shorthand in Utils/messages.js). Accepts either a raw vCard string via
+ * `addRawVcard()` or plain fields via `addContact()`, which builds a minimal
+ * VCARD 3.0 block itself.
+ */
+class Contact 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._contacts = [];
+		this._displayName;
+	}
+
+	/** Name shown on the card when sending more than one contact (`contactsArrayMessage.displayName`). Ignored for a single contact. */
+	setDisplayName(name) {
+		this._displayName = name;
+		return this;
+	}
+
+	/**
+	 * Add a contact from plain fields — builds a minimal VCARD 3.0 block.
+	 * @param {{name: string, phone?: string|string[], org?: string, email?: string, waid?: string}} fields
+	 * `waid` (digits-only, no `+`) makes the number tappable to chat/call on WhatsApp; without it the number is still shown but may not be tappable on every client.
+	 */
+	addContact({ name, phone, org, email, waid } = {}) {
+		if (typeof name !== 'string' || !name) throw new TypeError('addContact({name, ...}) requires a non-empty name');
+
+		const phones = phone === undefined ? [] : Array.isArray(phone) ? phone : [phone];
+		const lines = ['BEGIN:VCARD', 'VERSION:3.0', `FN:${name}`, `N:${name};;;;`];
+		phones.forEach((number, i) => {
+			const type = waid && i === 0 ? `TYPE=CELL,WAID=${waid}` : 'TYPE=CELL';
+			lines.push(`TEL;${type}:${number}`);
+		});
+		if (org) lines.push(`ORG:${org}`);
+		if (email) lines.push(`EMAIL:${email}`);
+		lines.push('END:VCARD');
+
+		this._contacts.push({ displayName: name, vcard: lines.join('\n') });
+		return this;
+	}
+
+	/** Add a contact from a pre-built vCard string (bypasses `addContact()`'s auto-generation). */
+	addRawVcard(displayName, vcard) {
+		if (typeof displayName !== 'string' || !displayName) throw new TypeError('addRawVcard(displayName, vcard) requires a non-empty displayName');
+		if (typeof vcard !== 'string' || !vcard) throw new TypeError('addRawVcard(displayName, vcard) requires a non-empty vcard string');
+		this._contacts.push({ displayName, vcard });
+		return this;
+	}
+
+	/** Remove every contact added so far. */
+	clearContacts() {
+		this._contacts = [];
+		return this;
+	}
+
+	/** @returns {{contacts: Record<string, any>}} The `sendMessage()`-shaped payload, without sending it. */
+	build() {
+		if (!this._contacts.length) throw new Error('Contact requires at least one contact (use addContact()/addRawVcard())');
+
+		return {
+			contacts: {
+				...(this._displayName !== undefined && { displayName: this._displayName }),
+				contacts: this._contacts,
+			},
+		};
+	}
+
+	/** Build and send via the socket's `sendMessage()`. */
+	async send(jid, options = {}) {
+		return this.#client.sendMessage(jid, this.build(), options);
+	}
+}
+
+export { Contact };

package/lib/Builders/Location.js

@@ -0,0 +1,151 @@
+import { BaseBuilder, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2, crypto } from './shared.js';
+import { proto } from '../../WAProto/index.js';
+
+/**
+ * Location message builder — static pin via the existing `message.location`
+ * shorthand (see Utils/messages.js, `hasNonNullishProperty(message, 'location')`),
+ * or a live/moving location. There is no `liveLocation` shorthand in
+ * `generateWAMessageContent` yet, so the live path goes through the `raw: true`
+ * escape hatch (same file, top of `generateWAMessageContent`) with a hand-built
+ * `liveLocationMessage`.
+ */
+class Location 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._lat;
+		this._lng;
+		this._name;
+		this._address;
+		this._url;
+		this._thumbnail;
+		this._live = false;
+		this._accuracy;
+		this._speed;
+		this._degrees;
+		this._caption;
+		this._sequence;
+		this._timeOffset;
+	}
+
+	/** Set the pin's coordinates. Required. */
+	setCoordinates(lat, lng) {
+		if (typeof lat !== 'number' || typeof lng !== 'number') throw new TypeError('setCoordinates(lat, lng) requires two numbers');
+		this._lat = lat;
+		this._lng = lng;
+		return this;
+	}
+
+	/** Place name shown above the address (static location only). */
+	setName(name) {
+		this._name = name;
+		return this;
+	}
+
+	/** Address line shown under the name (static location only). */
+	setAddress(address) {
+		this._address = address;
+		return this;
+	}
+
+	/** External map URL attached to the pin (static location only). */
+	setUrl(url) {
+		this._url = url;
+		return this;
+	}
+
+	/** Raw jpeg thumbnail bytes for the map preview. */
+	setThumbnail(buffer) {
+		this._thumbnail = buffer;
+		return this;
+	}
+
+	/** Switch between a static pin (default) and a live/moving location. */
+	setLive(isLive = true) {
+		this._live = isLive;
+		return this;
+	}
+
+	/** GPS accuracy radius in meters (live location only). */
+	setAccuracy(meters) {
+		this._accuracy = meters;
+		return this;
+	}
+
+	/** Current speed in meters/second (live location only). */
+	setSpeed(mps) {
+		this._speed = mps;
+		return this;
+	}
+
+	/** Heading in degrees clockwise from magnetic north (live location only). */
+	setDegrees(degreesClockwiseFromMagneticNorth) {
+		this._degrees = degreesClockwiseFromMagneticNorth;
+		return this;
+	}
+
+	/** Caption text shown with a live location update. */
+	setCaption(text) {
+		this._caption = text;
+		return this;
+	}
+
+	/** Ordinal of this update within a live-location session — bump it on each subsequent send so clients render the latest pin instead of stacking old ones. */
+	setSequence(n) {
+		this._sequence = n;
+		return this;
+	}
+
+	/** Seconds since the live-location session started. */
+	setTimeOffset(n) {
+		this._timeOffset = n;
+		return this;
+	}
+
+	/** @returns {Record<string, any>} The `sendMessage()`-shaped payload, without sending it. */
+	build() {
+		if (typeof this._lat !== 'number' || typeof this._lng !== 'number') {
+			throw new Error('Location requires setCoordinates(lat, lng)');
+		}
+
+		if (!this._live) {
+			return {
+				location: {
+					degreesLatitude: this._lat,
+					degreesLongitude: this._lng,
+					...(this._name !== undefined && { name: this._name }),
+					...(this._address !== undefined && { address: this._address }),
+					...(this._url !== undefined && { url: this._url }),
+					...(this._thumbnail !== undefined && { jpegThumbnail: this._thumbnail }),
+				},
+			};
+		}
+
+		return {
+			raw: true,
+			liveLocationMessage: proto.Message.LiveLocationMessage.create({
+				degreesLatitude: this._lat,
+				degreesLongitude: this._lng,
+				...(this._accuracy !== undefined && { accuracyInMeters: this._accuracy }),
+				...(this._speed !== undefined && { speedInMps: this._speed }),
+				...(this._degrees !== undefined && { degreesClockwiseFromMagneticNorth: this._degrees }),
+				...(this._caption !== undefined && { caption: this._caption }),
+				...(this._sequence !== undefined && { sequenceNumber: this._sequence }),
+				...(this._timeOffset !== undefined && { timeOffset: this._timeOffset }),
+				...(this._thumbnail !== undefined && { jpegThumbnail: this._thumbnail }),
+			}),
+		};
+	}
+
+	/** Build and send via the socket's `sendMessage()`. Call again with a higher `setSequence()` to push live-location updates. */
+	async send(jid, options = {}) {
+		return this.#client.sendMessage(jid, this.build(), options);
+	}
+}
+
+export { Location };