@openclaw/whatsapp 2026.5.2 → 2026.5.3-beta.1

package/dist/creds-files-_2V8jzQa.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region extensions/whatsapp/src/creds-files.ts
+function resolveWebCredsPath(authDir) {
+	return path.join(authDir, "creds.json");
+}
+function resolveWebCredsBackupPath(authDir) {
+	return path.join(authDir, "creds.json.bak");
+}
+function hasWebCredsSync(authDir) {
+	try {
+		const stats = fs.statSync(resolveWebCredsPath(authDir));
+		return stats.isFile() && stats.size > 1;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { resolveWebCredsBackupPath as n, resolveWebCredsPath as r, hasWebCredsSync as t };

package/dist/directory-config-DVs4ffXu.js

@@ -0,0 +1,37 @@
+import { t as __exportAll } from "./rolldown-runtime-RkAeH_Qm.js";
+import { t as resolveMergedWhatsAppAccountConfig } from "./account-config-CNQ33oav.js";
+import { s as normalizeWhatsAppTarget, t as isWhatsAppGroupJid } from "./normalize-target-BPVHNsM5.js";
+import "./normalize-CWYiGkXw.js";
+import { listResolvedDirectoryGroupEntriesFromMapKeys, listResolvedDirectoryUserEntriesFromAllowFrom } from "openclaw/plugin-sdk/directory-config-runtime";
+//#region extensions/whatsapp/src/directory-config.ts
+var directory_config_exports = /* @__PURE__ */ __exportAll({
+	listWhatsAppDirectoryGroupsFromConfig: () => listWhatsAppDirectoryGroupsFromConfig,
+	listWhatsAppDirectoryPeersFromConfig: () => listWhatsAppDirectoryPeersFromConfig
+});
+function resolveWhatsAppDirectoryAccount(cfg, accountId) {
+	return resolveMergedWhatsAppAccountConfig({
+		cfg,
+		accountId
+	});
+}
+async function listWhatsAppDirectoryPeersFromConfig(params) {
+	return listResolvedDirectoryUserEntriesFromAllowFrom({
+		...params,
+		resolveAccount: resolveWhatsAppDirectoryAccount,
+		resolveAllowFrom: (account) => account.allowFrom,
+		normalizeId: (entry) => {
+			const normalized = normalizeWhatsAppTarget(entry);
+			if (!normalized || isWhatsAppGroupJid(normalized)) return null;
+			return normalized;
+		}
+	});
+}
+async function listWhatsAppDirectoryGroupsFromConfig(params) {
+	return listResolvedDirectoryGroupEntriesFromMapKeys({
+		...params,
+		resolveAccount: resolveWhatsAppDirectoryAccount,
+		resolveGroups: (account) => account.groups
+	});
+}
+//#endregion
+export { listWhatsAppDirectoryGroupsFromConfig as n, listWhatsAppDirectoryPeersFromConfig as r, directory_config_exports as t };

package/dist/directory-contract-api.js

@@ -0,0 +1,2 @@
+import { n as listWhatsAppDirectoryGroupsFromConfig, r as listWhatsAppDirectoryPeersFromConfig } from "./directory-config-DVs4ffXu.js";
+export { listWhatsAppDirectoryGroupsFromConfig, listWhatsAppDirectoryPeersFromConfig };

package/dist/doctor-A9tXm9Om.js

@@ -0,0 +1,48 @@
+//#region extensions/whatsapp/src/doctor.ts
+function normalizeCompatibilityConfig({ cfg }) {
+	const legacyAckReaction = cfg.messages?.ackReaction?.trim();
+	if (!legacyAckReaction || cfg.channels?.whatsapp === void 0) return {
+		config: cfg,
+		changes: []
+	};
+	if (cfg.channels.whatsapp?.ackReaction !== void 0) return {
+		config: cfg,
+		changes: []
+	};
+	const legacyScope = cfg.messages?.ackReactionScope ?? "group-mentions";
+	let direct = true;
+	let group = "mentions";
+	if (legacyScope === "all") {
+		direct = true;
+		group = "always";
+	} else if (legacyScope === "direct") {
+		direct = true;
+		group = "never";
+	} else if (legacyScope === "group-all") {
+		direct = false;
+		group = "always";
+	} else if (legacyScope === "group-mentions") {
+		direct = false;
+		group = "mentions";
+	}
+	return {
+		config: {
+			...cfg,
+			channels: {
+				...cfg.channels,
+				whatsapp: {
+					...cfg.channels?.whatsapp,
+					ackReaction: {
+						emoji: legacyAckReaction,
+						direct,
+						group
+					}
+				}
+			}
+		},
+		changes: [`Copied messages.ackReaction → channels.whatsapp.ackReaction (scope: ${legacyScope}).`]
+	};
+}
+const whatsappDoctor = { normalizeCompatibilityConfig };
+//#endregion
+export { whatsappDoctor as n, normalizeCompatibilityConfig as t };

package/dist/doctor-contract-api.js

@@ -0,0 +1,10 @@
+import { t as normalizeCompatibilityConfig$1 } from "./doctor-A9tXm9Om.js";
+//#region extensions/whatsapp/src/doctor-contract.ts
+function normalizeCompatibilityConfig({ cfg }) {
+	return normalizeCompatibilityConfig$1({ cfg });
+}
+//#endregion
+//#region extensions/whatsapp/doctor-contract-api.ts
+const legacyConfigRules = [];
+//#endregion
+export { legacyConfigRules, normalizeCompatibilityConfig };

package/dist/group-session-contract-B8QBn0I2.js

@@ -0,0 +1,15 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+//#region extensions/whatsapp/src/group-session-contract.ts
+function resolveLegacyGroupSessionKey(ctx) {
+	const from = typeof ctx.From === "string" ? ctx.From.trim() : "";
+	const normalized = normalizeLowercaseStringOrEmpty(from);
+	if (!from || from.includes(":") || !normalized.endsWith("@g.us")) return null;
+	return {
+		key: `whatsapp:group:${normalized}`,
+		channel: "whatsapp",
+		id: normalized,
+		chatType: "group"
+	};
+}
+//#endregion
+export { resolveLegacyGroupSessionKey as t };

package/dist/identity-QHAlV7Fu.js

@@ -0,0 +1,75 @@
+import { i as jidToE164, t as text_runtime_exports } from "./text-runtime-C1zNiZeO.js";
+//#region extensions/whatsapp/src/identity.ts
+const WHATSAPP_LID_RE = /@(lid|hosted\.lid)$/i;
+function normalizeDeviceScopedJid(jid) {
+	return jid ? jid.replace(/:\d+/, "") : null;
+}
+function isLidJid(jid) {
+	return Boolean(jid && WHATSAPP_LID_RE.test(jid));
+}
+function resolveComparableIdentity(identity, authDir) {
+	const rawJid = normalizeDeviceScopedJid(identity?.jid);
+	const lid = normalizeDeviceScopedJid(identity?.lid) ?? (isLidJid(rawJid) ? rawJid : null);
+	const jid = rawJid && !isLidJid(rawJid) ? rawJid : null;
+	const e164 = identity?.e164 != null ? (0, text_runtime_exports.normalizeE164)(identity.e164) : (jid ? jidToE164(jid, authDir ? { authDir } : void 0) : null) ?? (lid ? jidToE164(lid, authDir ? { authDir } : void 0) : null);
+	return {
+		...identity,
+		jid,
+		lid,
+		e164
+	};
+}
+function getComparableIdentityValues(identity) {
+	const resolved = resolveComparableIdentity(identity);
+	return [
+		resolved.e164,
+		resolved.jid,
+		resolved.lid
+	].filter((value) => Boolean(value));
+}
+function identitiesOverlap(left, right) {
+	const leftValues = new Set(getComparableIdentityValues(left));
+	if (leftValues.size === 0) return false;
+	return getComparableIdentityValues(right).some((value) => leftValues.has(value));
+}
+function getSenderIdentity(msg, authDir) {
+	return resolveComparableIdentity(msg.sender ?? {
+		jid: msg.senderJid ?? null,
+		e164: msg.senderE164 ?? null,
+		name: msg.senderName ?? null
+	}, authDir);
+}
+function getSelfIdentity(msg, authDir) {
+	return resolveComparableIdentity(msg.self ?? {
+		jid: msg.selfJid ?? null,
+		lid: msg.selfLid ?? null,
+		e164: msg.selfE164 ?? null
+	}, authDir);
+}
+function getReplyContext(msg, authDir) {
+	if (msg.replyTo) return {
+		...msg.replyTo,
+		sender: resolveComparableIdentity(msg.replyTo.sender, authDir)
+	};
+	if (!msg.replyToBody) return null;
+	return {
+		id: msg.replyToId,
+		body: msg.replyToBody,
+		sender: resolveComparableIdentity({
+			jid: msg.replyToSenderJid ?? null,
+			e164: msg.replyToSenderE164 ?? null,
+			label: msg.replyToSender ?? null
+		}, authDir)
+	};
+}
+function getMentionJids(msg) {
+	return msg.mentions ?? msg.mentionedJids ?? [];
+}
+function getMentionIdentities(msg, authDir) {
+	return getMentionJids(msg).map((jid) => resolveComparableIdentity({ jid }, authDir));
+}
+function getPrimaryIdentityId(identity) {
+	return identity?.e164 || identity?.jid?.trim() || identity?.lid || null;
+}
+//#endregion
+export { getSelfIdentity as a, resolveComparableIdentity as c, getReplyContext as i, getMentionIdentities as n, getSenderIdentity as o, getPrimaryIdentityId as r, identitiesOverlap as s, getComparableIdentityValues as t };

package/dist/index.js

@@ -0,0 +1,18 @@
+import { defineBundledChannelEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+//#region extensions/whatsapp/index.ts
+var whatsapp_default = defineBundledChannelEntry({
+	id: "whatsapp",
+	name: "WhatsApp",
+	description: "WhatsApp channel plugin",
+	importMetaUrl: import.meta.url,
+	plugin: {
+		specifier: "./channel-plugin-api.js",
+		exportName: "whatsappPlugin"
+	},
+	runtime: {
+		specifier: "./runtime-api.js",
+		exportName: "setWhatsAppRuntime"
+	}
+});
+//#endregion
+export { whatsapp_default as default };

package/dist/legacy-session-surface-api.js

@@ -0,0 +1,8 @@
+import { r as isLegacyGroupSessionKey, t as canonicalizeLegacySessionKey } from "./session-contract-B0efQf9P.js";
+//#region extensions/whatsapp/legacy-session-surface-api.ts
+const whatsappLegacySessionSurface = {
+	isLegacyGroupSessionKey,
+	canonicalizeLegacySessionKey
+};
+//#endregion
+export { whatsappLegacySessionSurface };

package/dist/legacy-state-migrations-api.js

@@ -0,0 +1,2 @@
+import { t as detectWhatsAppLegacyStateMigrations } from "./state-migrations-DnCdvoYD.js";
+export { detectWhatsAppLegacyStateMigrations };

package/dist/light-runtime-api.js

@@ -0,0 +1,5 @@
+import { n as getStatusCode, t as formatError } from "./session-errors-CSuKZPub.js";
+import { t as createWhatsAppLoginTool } from "./agent-tools-login-DpRxLNRB.js";
+import { a as getWebAuthAgeMs, b as webAuthExists, c as pickWebChannel, h as readWebSelfId, o as logWebSelfId, s as logoutWeb, t as WA_WEB_AUTH_DIR } from "./auth-store-BjCb50Ry.js";
+import { t as getActiveWebListener } from "./active-listener-N7GFKsuN.js";
+export { WA_WEB_AUTH_DIR, createWhatsAppLoginTool, formatError, getActiveWebListener, getStatusCode, getWebAuthAgeMs, logWebSelfId, logoutWeb, pickWebChannel, readWebSelfId, webAuthExists };

package/dist/login-DymdrKca.js

@@ -0,0 +1,52 @@
+import { t as __exportAll } from "./rolldown-runtime-RkAeH_Qm.js";
+import { a as resolveWhatsAppAccount } from "./accounts-BDqgpFEB.js";
+import { y as restoreCredsFromBackupIfNeeded } from "./auth-store-BjCb50Ry.js";
+import { a as waitForWhatsAppLoginResult, i as closeWaSocketSoon, l as resolveWhatsAppSocketTiming, o as createWaSocket } from "./connection-controller-BiHAsTM8.js";
+import { logInfo } from "openclaw/plugin-sdk/text-runtime";
+import { formatCliCommand } from "openclaw/plugin-sdk/cli-runtime";
+import { danger, defaultRuntime, success } from "openclaw/plugin-sdk/runtime-env";
+import { getRuntimeConfig } from "openclaw/plugin-sdk/runtime-config-snapshot";
+//#region extensions/whatsapp/src/login.ts
+var login_exports = /* @__PURE__ */ __exportAll({ loginWeb: () => loginWeb });
+async function loginWeb(verbose, waitForConnection, runtime = defaultRuntime, accountId) {
+	const cfg = getRuntimeConfig();
+	const account = resolveWhatsAppAccount({
+		cfg,
+		accountId
+	});
+	const socketTiming = resolveWhatsAppSocketTiming(cfg);
+	const restoredFromBackup = await restoreCredsFromBackupIfNeeded(account.authDir);
+	let sock = await createWaSocket(true, verbose, {
+		authDir: account.authDir,
+		...socketTiming
+	});
+	logInfo("Waiting for WhatsApp connection...", runtime);
+	try {
+		const result = await waitForWhatsAppLoginResult({
+			sock,
+			authDir: account.authDir,
+			isLegacyAuthDir: account.isLegacyAuthDir,
+			verbose,
+			runtime,
+			waitForConnection,
+			socketTiming,
+			onSocketReplaced: (replacementSock) => {
+				sock = replacementSock;
+			}
+		});
+		if (result.outcome === "connected") {
+			console.log(success(result.restarted ? "✅ Linked after restart; web session ready." : restoredFromBackup ? "✅ Recovered from creds.json.bak; web session ready." : "✅ Linked! Credentials saved for future sends."));
+			return;
+		}
+		if (result.outcome === "logged-out") {
+			console.error(danger(`WhatsApp reported the session is logged out. Cleared cached web session; please rerun ${formatCliCommand("openclaw channels login")} and scan the QR again.`));
+			throw new Error("Session logged out; cache cleared. Re-run login.", { cause: result.error });
+		}
+		console.error(danger(`WhatsApp Web connection ended before fully opening. ${result.message}`));
+		throw new Error(result.message, { cause: result.error });
+	} finally {
+		closeWaSocketSoon(sock);
+	}
+}
+//#endregion
+export { login_exports as n, loginWeb as t };

package/dist/login-qr-DIS0Iv-7.js

@@ -0,0 +1,378 @@
+import { a as resolveWhatsAppAccount } from "./accounts-BDqgpFEB.js";
+import { d as readWebAuthExistsForDecision, h as readWebSelfId, n as WHATSAPP_AUTH_UNSTABLE_CODE } from "./auth-store-BjCb50Ry.js";
+import { a as waitForWhatsAppLoginResult, l as resolveWhatsAppSocketTiming, o as createWaSocket, r as closeWaSocket, t as WHATSAPP_LOGGED_OUT_QR_MESSAGE } from "./connection-controller-BiHAsTM8.js";
+import { logInfo } from "openclaw/plugin-sdk/text-runtime";
+import { danger, defaultRuntime, info, success } from "openclaw/plugin-sdk/runtime-env";
+import { renderQrPngDataUrl } from "openclaw/plugin-sdk/media-runtime";
+import { randomUUID } from "node:crypto";
+import { getRuntimeConfig } from "openclaw/plugin-sdk/runtime-config-snapshot";
+//#region extensions/whatsapp/src/login-qr.ts
+function waitForNextTask() {
+	return new Promise((resolve) => setImmediate(resolve));
+}
+const ACTIVE_LOGIN_TTL_MS = 3 * 6e4;
+const MAX_QR_RENDER_CHASES = 10;
+const activeLogins = /* @__PURE__ */ new Map();
+function closeSocket(sock) {
+	closeWaSocket(sock);
+}
+async function resetActiveLogin(accountId, reason) {
+	const login = activeLogins.get(accountId);
+	if (login) {
+		closeSocket(login.sock);
+		activeLogins.delete(accountId);
+	}
+	if (reason) logInfo(reason);
+}
+function isLoginFresh(login) {
+	return Date.now() - login.startedAt < ACTIVE_LOGIN_TTL_MS;
+}
+function resetQrUpdateSignal(login) {
+	login.qrUpdatePromise = new Promise((resolve) => {
+		login.resolveQrUpdate = resolve;
+	});
+}
+function notifyQrUpdate(login) {
+	const resolve = login.resolveQrUpdate;
+	resetQrUpdateSignal(login);
+	resolve?.();
+}
+function updateLoginQrState(login, qr) {
+	login.qr = qr;
+	login.qrVersion += 1;
+	return login.qrVersion;
+}
+async function ensureQrDataUrl(params) {
+	const current = activeLogins.get(params.accountId);
+	if (current?.id !== params.loginId || current.qrVersion !== params.qrVersion || current.qr !== params.qr) return await renderQrPngDataUrl(params.qr);
+	if (current.qrDataUrl && current.qrDataUrlVersion === params.qrVersion) return current.qrDataUrl;
+	if (current.qrRenderPromise) return await current.qrRenderPromise;
+	const renderPromise = (async () => {
+		for (let attempt = 0; attempt < MAX_QR_RENDER_CHASES; attempt += 1) {
+			const latest = activeLogins.get(params.accountId);
+			if (!latest || latest.id !== params.loginId || !latest.qr) throw new Error("WhatsApp QR is no longer active.");
+			if (latest.qrDataUrl && latest.qrDataUrlVersion === latest.qrVersion) return latest.qrDataUrl;
+			const qr = latest.qr;
+			const qrVersion = latest.qrVersion;
+			const dataUrl = await renderQrPngDataUrl(qr);
+			const refreshed = activeLogins.get(params.accountId);
+			if (!refreshed || refreshed.id !== params.loginId) return dataUrl;
+			if (refreshed.qrVersion === qrVersion && refreshed.qr === qr) {
+				refreshed.qrDataUrl = dataUrl;
+				refreshed.qrDataUrlVersion = qrVersion;
+				notifyQrUpdate(refreshed);
+				return dataUrl;
+			}
+		}
+		throw new Error("WhatsApp QR kept refreshing before the latest image could render.");
+	})();
+	current.qrRenderPromise = renderPromise;
+	try {
+		return await renderPromise;
+	} finally {
+		const latest = activeLogins.get(params.accountId);
+		if (latest?.id === params.loginId && latest.qrRenderPromise === renderPromise) latest.qrRenderPromise = null;
+	}
+}
+function renderLatestQrDataUrlInBackground(params) {
+	ensureQrDataUrl(params).catch(() => {});
+}
+function attachLoginWaiter(accountId, login) {
+	login.waitPromise = waitForWhatsAppLoginResult({
+		sock: login.sock,
+		authDir: login.authDir,
+		isLegacyAuthDir: login.isLegacyAuthDir,
+		verbose: login.verbose,
+		runtime: login.runtime,
+		socketTiming: login.socketTiming,
+		onQr: (qr) => {
+			const current = activeLogins.get(accountId);
+			if (!current || current.id !== login.id) return;
+			const qrVersion = updateLoginQrState(current, qr);
+			renderLatestQrDataUrlInBackground({
+				accountId,
+				loginId: login.id,
+				qr,
+				qrVersion
+			});
+		},
+		onSocketReplaced: (sock) => {
+			const current = activeLogins.get(accountId);
+			if (current?.id === login.id) {
+				current.sock = sock;
+				current.connected = false;
+				current.error = void 0;
+				current.errorStatus = void 0;
+			}
+		}
+	}).then((result) => {
+		const current = activeLogins.get(accountId);
+		if (current?.id !== login.id) return;
+		if (result.outcome === "connected") {
+			current.sock = result.sock;
+			current.connected = true;
+			return;
+		}
+		current.error = result.message;
+		current.errorStatus = result.statusCode;
+	}).catch((err) => {
+		const current = activeLogins.get(accountId);
+		if (current?.id !== login.id) return;
+		current.error = err instanceof Error ? err.message : String(err);
+		current.errorStatus = void 0;
+	});
+}
+async function waitForQrOrRecoveredLogin(params) {
+	const qrResult = params.qrPromise.then((qr) => ({
+		outcome: "qr",
+		qr
+	}), (err) => ({
+		outcome: "failed",
+		message: `Failed to get QR: ${String(err)}`
+	}));
+	const loginResult = params.login.waitPromise.then(async () => {
+		if (activeLogins.get(params.accountId)?.id !== params.login.id) return {
+			outcome: "failed",
+			message: "WhatsApp login was replaced by a newer request."
+		};
+		await waitForNextTask();
+		const latest = activeLogins.get(params.accountId);
+		if (latest?.id !== params.login.id) return {
+			outcome: "failed",
+			message: "WhatsApp login was replaced by a newer request."
+		};
+		if (latest.qr) return {
+			outcome: "qr",
+			qr: latest.qr
+		};
+		if (latest.connected) return { outcome: "connected" };
+		return {
+			outcome: "failed",
+			message: latest.error ? `WhatsApp login failed: ${latest.error}` : "WhatsApp login failed."
+		};
+	});
+	return await Promise.race([qrResult, loginResult]);
+}
+async function startWebLoginWithQr(opts = {}) {
+	const runtime = opts.runtime ?? defaultRuntime;
+	const cfg = getRuntimeConfig();
+	const account = resolveWhatsAppAccount({
+		cfg,
+		accountId: opts.accountId
+	});
+	const socketTiming = resolveWhatsAppSocketTiming(cfg);
+	const authState = await readWebAuthExistsForDecision(account.authDir);
+	if (authState.outcome === "unstable") return {
+		code: WHATSAPP_AUTH_UNSTABLE_CODE,
+		message: "WhatsApp auth state is still stabilizing. Retry login in a moment."
+	};
+	if (authState.exists && !opts.force) {
+		const selfId = readWebSelfId(account.authDir);
+		return { message: `WhatsApp is already linked (${selfId.e164 ?? selfId.jid ?? "unknown"}). Say “relink” if you want a fresh QR.` };
+	}
+	const existing = activeLogins.get(account.accountId);
+	if (existing && isLoginFresh(existing) && existing.qrDataUrl) return {
+		qrDataUrl: existing.qrDataUrl,
+		message: "QR already active. Scan it in WhatsApp → Linked Devices."
+	};
+	await resetActiveLogin(account.accountId);
+	let resolveQr = null;
+	let rejectQr = null;
+	const qrPromise = new Promise((resolve, reject) => {
+		resolveQr = resolve;
+		rejectQr = reject;
+	});
+	const qrTimer = setTimeout(() => {
+		rejectQr?.(/* @__PURE__ */ new Error("Timed out waiting for WhatsApp QR"));
+	}, Math.max(opts.timeoutMs ?? 3e4, 5e3));
+	let sock;
+	let pendingQr = null;
+	const loginId = randomUUID();
+	try {
+		sock = await createWaSocket(false, Boolean(opts.verbose), {
+			authDir: account.authDir,
+			...socketTiming,
+			onQr: (qr) => {
+				pendingQr = qr;
+				const current = activeLogins.get(account.accountId);
+				if (current && current.id === loginId) {
+					const qrVersion = updateLoginQrState(current, qr);
+					renderLatestQrDataUrlInBackground({
+						accountId: account.accountId,
+						loginId,
+						qr,
+						qrVersion
+					});
+				}
+				if (resolveQr) {
+					clearTimeout(qrTimer);
+					resolveQr(qr);
+					resolveQr = null;
+					rejectQr = null;
+				}
+				runtime.log(info("WhatsApp QR received."));
+			}
+		});
+	} catch (err) {
+		clearTimeout(qrTimer);
+		await resetActiveLogin(account.accountId);
+		return { message: `Failed to start WhatsApp login: ${String(err)}` };
+	}
+	const login = {
+		accountId: account.accountId,
+		authDir: account.authDir,
+		isLegacyAuthDir: account.isLegacyAuthDir,
+		id: loginId,
+		sock,
+		startedAt: Date.now(),
+		connected: false,
+		waitPromise: Promise.resolve(),
+		qrVersion: 0,
+		qrUpdatePromise: Promise.resolve(),
+		resolveQrUpdate: null,
+		qrRenderPromise: null,
+		verbose: Boolean(opts.verbose),
+		runtime,
+		socketTiming
+	};
+	resetQrUpdateSignal(login);
+	activeLogins.set(account.accountId, login);
+	if (pendingQr) {
+		const qrVersion = updateLoginQrState(login, pendingQr);
+		renderLatestQrDataUrlInBackground({
+			accountId: account.accountId,
+			loginId: login.id,
+			qr: pendingQr,
+			qrVersion
+		});
+	}
+	attachLoginWaiter(account.accountId, login);
+	const loginStartResult = await waitForQrOrRecoveredLogin({
+		accountId: account.accountId,
+		login,
+		qrPromise
+	});
+	clearTimeout(qrTimer);
+	if (loginStartResult.outcome === "connected") {
+		const selfId = readWebSelfId(account.authDir);
+		const who = selfId.e164 ?? selfId.jid ?? "unknown";
+		await resetActiveLogin(account.accountId);
+		return {
+			message: `WhatsApp recovered the existing linked session (${who}).`,
+			connected: true
+		};
+	}
+	if (loginStartResult.outcome === "failed") {
+		await resetActiveLogin(account.accountId);
+		return { message: loginStartResult.message };
+	}
+	const qr = login.qr ?? loginStartResult.qr;
+	const qrVersion = login.qrVersion;
+	if (qrVersion === 0) {
+		await resetActiveLogin(account.accountId);
+		return { message: "Failed to capture the active WhatsApp QR. Ask me to generate a new one." };
+	}
+	let qrDataUrl;
+	try {
+		qrDataUrl = await ensureQrDataUrl({
+			accountId: account.accountId,
+			loginId: login.id,
+			qr,
+			qrVersion
+		});
+	} catch (err) {
+		const message = err instanceof Error ? `Failed to render the WhatsApp QR: ${err.message}` : String(err);
+		await resetActiveLogin(account.accountId, message);
+		return { message };
+	}
+	return {
+		qrDataUrl,
+		message: "Scan this QR in WhatsApp → Linked Devices."
+	};
+}
+async function waitForWebLogin(opts = {}) {
+	const runtime = opts.runtime ?? defaultRuntime;
+	const account = resolveWhatsAppAccount({
+		cfg: getRuntimeConfig(),
+		accountId: opts.accountId
+	});
+	const activeLogin = activeLogins.get(account.accountId);
+	if (!activeLogin) return {
+		connected: false,
+		message: "No active WhatsApp login in progress."
+	};
+	const login = activeLogin;
+	if (!isLoginFresh(login)) {
+		await resetActiveLogin(account.accountId);
+		return {
+			connected: false,
+			message: "The login QR expired. Ask me to generate a new one."
+		};
+	}
+	const timeoutMs = Math.max(opts.timeoutMs ?? 12e4, 1e3);
+	const deadline = Date.now() + timeoutMs;
+	const currentQrDataUrl = opts.currentQrDataUrl;
+	while (true) {
+		if (login.error) {
+			if (login.errorStatus === 401) {
+				const message = WHATSAPP_LOGGED_OUT_QR_MESSAGE;
+				await resetActiveLogin(account.accountId, message);
+				runtime.log(danger(message));
+				return {
+					connected: false,
+					message
+				};
+			}
+			const message = `WhatsApp login failed: ${login.error}`;
+			await resetActiveLogin(account.accountId, message);
+			runtime.log(danger(message));
+			return {
+				connected: false,
+				message
+			};
+		}
+		if (login.connected) {
+			const message = "✅ Linked! WhatsApp is ready.";
+			runtime.log(success(message));
+			await resetActiveLogin(account.accountId);
+			return {
+				connected: true,
+				message
+			};
+		}
+		if (login.qrDataUrl && currentQrDataUrl && login.qrDataUrl !== currentQrDataUrl) return {
+			connected: false,
+			message: "QR refreshed. Scan the latest code in WhatsApp → Linked Devices.",
+			qrDataUrl: login.qrDataUrl
+		};
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) return {
+			connected: false,
+			message: "Still waiting for the QR scan. Let me know when you’ve scanned it."
+		};
+		const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), remaining));
+		const result = await Promise.race([
+			login.waitPromise.then(() => "done"),
+			login.qrUpdatePromise.then(() => "qr-update"),
+			timeout
+		]);
+		if (result === "timeout") return {
+			connected: false,
+			message: "Still waiting for the QR scan. Let me know when you’ve scanned it."
+		};
+		if (result === "qr-update") continue;
+		if (result === "done") {
+			if (login.connected || login.error) continue;
+			return {
+				connected: false,
+				message: "Login ended without a connection."
+			};
+		}
+		return {
+			connected: false,
+			message: "Login ended without a connection."
+		};
+	}
+}
+//#endregion
+export { startWebLoginWithQr, waitForWebLogin };

package/dist/login-qr-api.js

@@ -0,0 +1,2 @@
+import { startWebLoginWithQr, waitForWebLogin } from "./login-qr-runtime.js";
+export { startWebLoginWithQr, waitForWebLogin };