@vanzxy/baileys 2.0.0

package/lib/Types/Socket.d.ts

@@ -0,0 +1,136 @@
+import type { Agent } from 'https';
+import type { URL } from 'url';
+import { proto } from '../../WAProto/index.js';
+import type { ILogger } from '../Utils/logger.js';
+import type { AuthenticationState, LIDMapping, SignalAuthState, TransactionCapabilityOptions } from './Auth.js';
+import type { GroupMetadata } from './GroupMetadata.js';
+import { type MediaConnInfo, type WAMessageKey } from './Message.js';
+import type { SignalRepositoryWithLIDStore } from './Signal.js';
+export type WAVersion = [number, number, number];
+export type WABrowserDescription = [string, string, string];
+export type CacheStore = {
+    /** get a cached key and change the stats */
+    get<T>(key: string): Promise<T> | T | undefined;
+    /** set a key in the cache */
+    set<T>(key: string, value: T): Promise<void> | void | number | boolean;
+    /** delete a key from the cache */
+    del(key: string): void | Promise<void> | number | boolean;
+    /** flush all data */
+    flushAll(): void | Promise<void>;
+    close?: () => void;
+};
+export type PossiblyExtendedCacheStore = CacheStore & {
+    mget?: <T>(keys: string[]) => Promise<Record<string, T | undefined>>;
+    mset?: <T>(entries: {
+        key: string;
+        value: T;
+    }[]) => Promise<void> | void | number | boolean;
+    mdel?: (keys: string[]) => void | Promise<void> | number | boolean;
+};
+export type PatchedMessageWithRecipientJID = proto.IMessage & {
+    recipientJid?: string;
+};
+export type SocketConfig = {
+    /** the WS url to connect to WA */
+    waWebSocketUrl: string | URL;
+    /** Fails the connection if the socket times out in this interval */
+    connectTimeoutMs: number;
+    /** Default timeout for queries, undefined for no timeout */
+    defaultQueryTimeoutMs: number | undefined;
+    /** ping-pong interval for WS connection */
+    keepAliveIntervalMs: number;
+    /** should baileys use the mobile api instead of the multi device api
+     * @deprecated This feature has been removed
+     */
+    mobile?: boolean;
+    /** proxy agent */
+    agent?: Agent;
+    /** logger */
+    logger: ILogger;
+    /** version to connect with */
+    version: WAVersion;
+    /** override browser config */
+    browser: WABrowserDescription;
+    /** Initial pushName carried in the registration ClientPayload (used by mock servers for deterministic phone assignment). */
+    pushName?: string;
+    /** agent used for fetch requests -- uploading/downloading media */
+    fetchAgent?: Agent;
+    /** should the QR be printed in the terminal
+     * @deprecated This feature has been removed
+     */
+    printQRInTerminal?: boolean;
+    /** should events be emitted for actions done by this socket connection */
+    emitOwnEvents: boolean;
+    /** custom upload hosts to upload media to */
+    customUploadHosts: MediaConnInfo['hosts'];
+    /** time to wait between sending new retry requests */
+    retryRequestDelayMs: number;
+    /** max retry count */
+    maxMsgRetryCount: number;
+    /** time to wait for the generation of the next QR in ms */
+    qrTimeout?: number;
+    /** provide an auth state object to maintain the auth state */
+    auth: AuthenticationState;
+    /** manage history processing with this control; by default will sync up everything */
+    shouldSyncHistoryMessage: (msg: proto.Message.IHistorySyncNotification) => boolean;
+    /** transaction capability options for SignalKeyStore */
+    transactionOpts: TransactionCapabilityOptions;
+    /** marks the client as online whenever the socket successfully connects */
+    markOnlineOnConnect: boolean;
+    /** alphanumeric country code (USA -> US) for the number used */
+    countryCode: string;
+    /** provide a cache to store media, so does not have to be re-uploaded */
+    mediaCache?: CacheStore;
+    /**
+     * map to store the retry counts for failed messages;
+     * used to determine whether to retry a message or not */
+    msgRetryCounterCache?: CacheStore;
+    /** provide a cache to store a user's device list */
+    userDevicesCache?: PossiblyExtendedCacheStore;
+    /** cache to store call offers */
+    callOfferCache?: CacheStore;
+    /** cache to track placeholder resends */
+    placeholderResendCache?: CacheStore;
+    /** width for link preview images */
+    linkPreviewImageThumbnailWidth: number;
+    /** Should Baileys ask the phone for full history, will be received async */
+    syncFullHistory: boolean;
+    /** Should baileys fire init queries automatically, default true */
+    fireInitQueries: boolean;
+    /**
+     * generate a high quality link preview,
+     * entails uploading the jpegThumbnail to WA
+     * */
+    generateHighQualityLinkPreview: boolean;
+    /** Enable automatic session recreation for failed messages */
+    enableAutoSessionRecreation: boolean;
+    /** Enable recent message caching for retry handling */
+    enableRecentMessageCache: boolean;
+    /**
+     * Returns if a jid should be ignored,
+     * no event for that jid will be triggered.
+     * Messages from that jid will also not be decrypted
+     * */
+    shouldIgnoreJid: (jid: string) => boolean | undefined;
+    /**
+     * Optionally patch the message before sending out
+     * */
+    patchMessageBeforeSending: (msg: proto.IMessage, recipientJids?: string[]) => Promise<PatchedMessageWithRecipientJID[] | PatchedMessageWithRecipientJID> | PatchedMessageWithRecipientJID[] | PatchedMessageWithRecipientJID;
+    /** verify app state MACs */
+    appStateMacVerification: {
+        patch: boolean;
+        snapshot: boolean;
+    };
+    /** options for HTTP fetch requests */
+    options: RequestInit;
+    /**
+     * fetch a message from your store
+     * implement this so that messages failed to send
+     * (solves the "this message can take a while" issue) can be retried
+     * */
+    getMessage: (key: WAMessageKey) => Promise<proto.IMessage | undefined>;
+    /** cached group metadata, use to prevent redundant requests to WA & speed up msg sending */
+    cachedGroupMetadata: (jid: string) => Promise<GroupMetadata | undefined>;
+    makeSignalRepository: (auth: SignalAuthState, logger: ILogger, pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>) => SignalRepositoryWithLIDStore;
+};
+//# sourceMappingURL=Socket.d.ts.map

package/lib/Types/Socket.js

@@ -0,0 +1,2 @@
+import { proto } from '../../WAProto/index.js';
+//# sourceMappingURL=Socket.js.map

package/lib/Types/State.d.ts

@@ -0,0 +1,5 @@
+export const SyncState: any;
+export const ReachoutTimelockEnforcementType: any;
+export const NewChatMessageCappingStatusType: any;
+export const NewChatMessageCappingMVStatusType: any;
+export const NewChatMessageCappingOTEStatusType: any;

package/lib/Types/State.js

@@ -0,0 +1,56 @@
+import { Boom } from '@hapi/boom';
+export var SyncState;
+(function (SyncState) {
+    /** The socket is connecting, but we haven't received pending notifications yet. */
+    SyncState[SyncState["Connecting"] = 0] = "Connecting";
+    /** Pending notifications received. Buffering events until we decide whether to sync or not. */
+    SyncState[SyncState["AwaitingInitialSync"] = 1] = "AwaitingInitialSync";
+    /** The initial app state sync (history, etc.) is in progress. Buffering continues. */
+    SyncState[SyncState["Syncing"] = 2] = "Syncing";
+    /** Initial sync is complete, or was skipped. The socket is fully operational and events are processed in real-time. */
+    SyncState[SyncState["Online"] = 3] = "Online";
+})(SyncState || (SyncState = {}));
+export var ReachoutTimelockEnforcementType;
+(function (ReachoutTimelockEnforcementType) {
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_ALCOHOL"] = "BIZ_COMMERCE_VIOLATION_ALCOHOL";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_ADULT"] = "BIZ_COMMERCE_VIOLATION_ADULT";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_ANIMALS"] = "BIZ_COMMERCE_VIOLATION_ANIMALS";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_BODY_PARTS_FLUIDS"] = "BIZ_COMMERCE_VIOLATION_BODY_PARTS_FLUIDS";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_DATING"] = "BIZ_COMMERCE_VIOLATION_DATING";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_DIGITAL_SERVICES_PRODUCTS"] = "BIZ_COMMERCE_VIOLATION_DIGITAL_SERVICES_PRODUCTS";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_DRUGS"] = "BIZ_COMMERCE_VIOLATION_DRUGS";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_DRUGS_ONLY_OTC"] = "BIZ_COMMERCE_VIOLATION_DRUGS_ONLY_OTC";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_GAMBLING"] = "BIZ_COMMERCE_VIOLATION_GAMBLING";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_HEALTHCARE"] = "BIZ_COMMERCE_VIOLATION_HEALTHCARE";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_REAL_FAKE_CURRENCY"] = "BIZ_COMMERCE_VIOLATION_REAL_FAKE_CURRENCY";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_SUPPLEMENTS"] = "BIZ_COMMERCE_VIOLATION_SUPPLEMENTS";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_TOBACCO"] = "BIZ_COMMERCE_VIOLATION_TOBACCO";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_VIOLENT_CONTENT"] = "BIZ_COMMERCE_VIOLATION_VIOLENT_CONTENT";
+    ReachoutTimelockEnforcementType["BIZ_COMMERCE_VIOLATION_WEAPONS"] = "BIZ_COMMERCE_VIOLATION_WEAPONS";
+    ReachoutTimelockEnforcementType["BIZ_QUALITY"] = "BIZ_QUALITY";
+    /** This means there is no restriction */
+    ReachoutTimelockEnforcementType["DEFAULT"] = "DEFAULT";
+    ReachoutTimelockEnforcementType["WEB_COMPANION_ONLY"] = "WEB_COMPANION_ONLY";
+})(ReachoutTimelockEnforcementType || (ReachoutTimelockEnforcementType = {}));
+export var NewChatMessageCappingStatusType;
+(function (NewChatMessageCappingStatusType) {
+    NewChatMessageCappingStatusType["NONE"] = "NONE";
+    NewChatMessageCappingStatusType["FIRST_WARNING"] = "FIRST_WARNING";
+    NewChatMessageCappingStatusType["SECOND_WARNING"] = "SECOND_WARNING";
+    NewChatMessageCappingStatusType["CAPPED"] = "CAPPED";
+})(NewChatMessageCappingStatusType || (NewChatMessageCappingStatusType = {}));
+export var NewChatMessageCappingMVStatusType;
+(function (NewChatMessageCappingMVStatusType) {
+    NewChatMessageCappingMVStatusType["NOT_ELIGIBLE"] = "NOT_ELIGIBLE";
+    NewChatMessageCappingMVStatusType["NOT_ACTIVE"] = "NOT_ACTIVE";
+    NewChatMessageCappingMVStatusType["ACTIVE"] = "ACTIVE";
+    NewChatMessageCappingMVStatusType["ACTIVE_UPGRADE_AVAILABLE"] = "ACTIVE_UPGRADE_AVAILABLE";
+})(NewChatMessageCappingMVStatusType || (NewChatMessageCappingMVStatusType = {}));
+export var NewChatMessageCappingOTEStatusType;
+(function (NewChatMessageCappingOTEStatusType) {
+    NewChatMessageCappingOTEStatusType["NOT_ELIGIBLE"] = "NOT_ELIGIBLE";
+    NewChatMessageCappingOTEStatusType["ELIGIBLE"] = "ELIGIBLE";
+    NewChatMessageCappingOTEStatusType["ACTIVE_IN_CURRENT_CYCLE"] = "ACTIVE_IN_CURRENT_CYCLE";
+    NewChatMessageCappingOTEStatusType["EXHAUSTED"] = "EXHAUSTED";
+})(NewChatMessageCappingOTEStatusType || (NewChatMessageCappingOTEStatusType = {}));
+//# sourceMappingURL=State.js.map

package/lib/Types/USync.d.ts

@@ -0,0 +1,26 @@
+import type { BinaryNode } from '../WABinary/index.js';
+import { USyncUser } from '../WAUSync/index.js';
+/**
+ * Defines the interface for a USyncQuery protocol
+ */
+export interface USyncQueryProtocol {
+    /**
+     * The name of the protocol
+     */
+    name: string;
+    /**
+     * Defines what goes inside the query part of a USyncQuery
+     */
+    getQueryElement: () => BinaryNode;
+    /**
+     * Defines what goes inside the user part of a USyncQuery
+     */
+    getUserElement: (user: USyncUser) => BinaryNode | null;
+    /**
+     * Parse the result of the query
+     * @param data Data from the result
+     * @returns Whatever the protocol is supposed to return
+     */
+    parser: (data: BinaryNode) => unknown;
+}
+//# sourceMappingURL=USync.d.ts.map

package/lib/Types/USync.js

@@ -0,0 +1,2 @@
+import { USyncUser } from '../WAUSync/index.js';
+//# sourceMappingURL=USync.js.map

package/lib/Types/index.d.ts

@@ -0,0 +1,66 @@
+export * from './Auth.js';
+export * from './GroupMetadata.js';
+export * from './Chat.js';
+export * from './Contact.js';
+export * from './State.js';
+export * from './Message.js';
+export * from './Socket.js';
+export * from './Events.js';
+export * from './Product.js';
+export * from './Call.js';
+export * from './Signal.js';
+export * from './Mex.js';
+import type { AuthenticationState } from './Auth.js';
+import type { SocketConfig } from './Socket.js';
+export type UserFacingSocketConfig = Partial<SocketConfig> & {
+    auth: AuthenticationState;
+};
+export type BrowsersMap = {
+    ubuntu(browser: string): [string, string, string];
+    macOS(browser: string): [string, string, string];
+    baileys(browser: string): [string, string, string];
+    windows(browser: string): [string, string, string];
+    android(browser: string): [string, string, string];
+    appropriate(browser: string): [string, string, string];
+};
+export declare enum DisconnectReason {
+    connectionClosed = 428,
+    connectionLost = 408,
+    connectionReplaced = 440,
+    timedOut = 408,
+    loggedOut = 401,
+    badSession = 500,
+    restartRequired = 515,
+    multideviceMismatch = 411,
+    forbidden = 403,
+    unavailableService = 503
+}
+export type WAInitResponse = {
+    ref: string;
+    ttl: number;
+    status: 200;
+};
+export type WABusinessHoursConfig = {
+    day_of_week: string;
+    mode: string;
+    open_time?: number;
+    close_time?: number;
+};
+export type WABusinessProfile = {
+    description: string;
+    email: string | undefined;
+    business_hours: {
+        timezone?: string;
+        config?: WABusinessHoursConfig[];
+        business_config?: WABusinessHoursConfig[];
+    };
+    website: string[];
+    category?: string;
+    wid?: string;
+    address?: string;
+};
+export type CurveKeyPair = {
+    private: Uint8Array;
+    public: Uint8Array;
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/Types/index.js

@@ -0,0 +1,26 @@
+export * from './Auth.js';
+export * from './GroupMetadata.js';
+export * from './Chat.js';
+export * from './Contact.js';
+export * from './State.js';
+export * from './Message.js';
+export * from './Socket.js';
+export * from './Events.js';
+export * from './Product.js';
+export * from './Call.js';
+export * from './Signal.js';
+export * from './Mex.js';
+export var DisconnectReason;
+(function (DisconnectReason) {
+    DisconnectReason[DisconnectReason["connectionClosed"] = 428] = "connectionClosed";
+    DisconnectReason[DisconnectReason["connectionLost"] = 408] = "connectionLost";
+    DisconnectReason[DisconnectReason["connectionReplaced"] = 440] = "connectionReplaced";
+    DisconnectReason[DisconnectReason["timedOut"] = 408] = "timedOut";
+    DisconnectReason[DisconnectReason["loggedOut"] = 401] = "loggedOut";
+    DisconnectReason[DisconnectReason["badSession"] = 500] = "badSession";
+    DisconnectReason[DisconnectReason["restartRequired"] = 515] = "restartRequired";
+    DisconnectReason[DisconnectReason["multideviceMismatch"] = 411] = "multideviceMismatch";
+    DisconnectReason[DisconnectReason["forbidden"] = 403] = "forbidden";
+    DisconnectReason[DisconnectReason["unavailableService"] = 503] = "unavailableService";
+})(DisconnectReason || (DisconnectReason = {}));
+//# sourceMappingURL=index.js.map

package/lib/Utils/A2UI.js

@@ -0,0 +1,277 @@
+/**
+ * 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, prepareWAMessageMedia } 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;
+	}
+	// Vanz@Add 30-08-26 --- send(): terminal method so A2UI can be used as a one-liner like
+	// the other builders (Button/ButtonV2/AIRich `.send()`), instead of always needing the
+	// separate `sendA2UIWidget()` call. Thin wrapper only — root([...ids])/listCard() must
+	// still be called first, same as before build(); this doesn't change the id-returning
+	// factory API (child methods still return ids, not `this`, since sibling nodes need to
+	// reference each other by id when wiring children/trigger/content).
+	async send(client, jid, opts = {}) {
+		return sendA2UIWidget(client, jid, { ...opts, a2ui: this });
+	}
+	// Vanz@Add 30-08-26 --- validates that every structural id-reference (child/children on
+	// Button/Card/Column/Row, trigger/content on Modal) points at a component that was
+	// actually registered. Without this, a typo'd id just gets written into the wire payload
+	// as-is and the failure only surfaces as a broken/blank widget on the WA client, with no
+	// error on this end. Only covers the dedicated methods' known reference keys — raw()'s
+	// free-form props aren't inspected, since there's no way to know which of those are id
+	// references vs plain data.
+	#validateRefs(components) {
+		const validIds = new Set(components.map((c) => c.id));
+		for (const c of components) {
+			for (const key of ["child", "trigger", "content"]) {
+				if (c[key] !== undefined && !validIds.has(c[key])) {
+					throw new Error(`A2UI: component "${c.id}" (${c.component}) references unknown id "${c[key]}" via "${key}"`);
+				}
+			}
+			if (Array.isArray(c.children)) {
+				for (const childId of c.children) {
+					if (!validIds.has(childId)) {
+						throw new Error(`A2UI: component "${c.id}" (${c.component}) references unknown id "${childId}" in "children"`);
+					}
+				}
+			}
+		}
+	}
+	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()];
+		this.#validateRefs(components);
+		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,
+	// Vanz@Add 30-08-26 --- optional header media, mirroring Button/ButtonV2's toCard()
+	// pattern (prepareWAMessageMedia + client.waUploadToServer). { title, subtitle, image
+	// | video | document: path/buffer/{url} } — media is mutually exclusive, image wins if
+	// more than one is passed. Falls back to a title/subtitle-only header (no attachment)
+	// when no media is given, same shape as before this change.
+	header
+} = {}) {
+	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 headerMediaData = header?.image
+		? { image: header.image }
+		: header?.video
+			? { video: header.video }
+			: header?.document
+				? { document: header.document }
+				: null;
+
+	const headerBlock = {
+		...(header?.title !== undefined ? { title: header.title } : {}),
+		...(header?.subtitle !== undefined ? { subtitle: header.subtitle } : {}),
+		hasMediaAttachment: !!headerMediaData,
+		...(headerMediaData
+			? await prepareWAMessageMedia(headerMediaData, { upload: client.waUploadToServer }).catch((e) => {
+					if (String(e).includes("Invalid media type")) return headerMediaData;
+					throw e;
+				})
+			: {})
+	};
+
+	const interactiveMessage = singleScreen
+		? {
+				nativeFlowMessage,
+				bloksWidget: a2ui.build({ type, wrapped }),
+				...(expiration || Object.keys(contextInfo).length ? { contextInfo: { ...(expiration ? { expiration } : {}), ...contextInfo } } : {})
+			}
+		: {
+				header: headerBlock,
+				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 };