@vanzxysenpai/baileys 0.0.0-stage → 0.0.2

package/lib/Utils/meta-ai-msmsg.d.ts

@@ -0,0 +1,3 @@
+export function decodeDecryptedMsmsgMessage(decrypted: any): proto.Message;
+export function decryptMsmsgBotMessage(messageSecret: any, messageKey: any, msMsg: any): Promise<any>;
+import { proto } from '../../WAProto/index.js';

package/lib/Utils/meta-ai-msmsg.js

@@ -0,0 +1,132 @@
+// Vanz@Port (v2.0.3) --- ported from @nexustechpro/baileys 2.2.7 (MIT, Copyright (c) 2026 nexustechpro2), lib/Utils/meta-ai-msmsg.js. See NOTICE.md.
+//
+// EXPERIMENTAL / NOT WIRED INTO THE SOCKET. These are pure helpers only. Two reasons this is not hooked into
+// messages-recv.js:
+//  1. The `messageKey` field names (botEditTargetId, targetId, ...) and the HKDF `info`/AAD layout come from the
+//     source fork and are unverified against a real Meta AI `msmsg` stanza.
+//  2. nexustech feeds `authState.creds.myAppStateKeyId` in as the message secret, which is an app-state key ID and
+//     not a per-message secret (that would be `messageContextInfo.messageSecret` of the message you sent).
+// Use them to experiment with a secret you obtained yourself; the socket still NACKs `msmsg` as before.
+import { hkdf, aesDecryptGCM } from './crypto.js'
+import { unpadRandomMax16 } from './generics.js'
+import { jidNormalizedUser } from '../WABinary/index.js'
+import { proto } from '../../WAProto/index.js'
+
+const BOT_MESSAGE_INFO = 'Bot Message'
+const KEY_LENGTH = 32
+const AUTH_TAG_LENGTH = 16
+const MSG_ID_HEX_RE = /^[0-9A-Fa-f]{32}$/
+
+const toBuffer = value => {
+    if (Buffer.isBuffer(value)) return value
+    if (value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+    return Buffer.from(value)
+}
+
+const buildMessageIdRepresentations = messageId => {
+    const ascii = Buffer.from(messageId)
+    const binary = MSG_ID_HEX_RE.test(messageId) ? Buffer.from(messageId, 'hex') : ascii
+    return [{ label: 'msgIdAscii', value: ascii }, ...(binary.equals(ascii) ? [] : [{ label: 'msgIdBinary', value: binary }])]
+}
+
+const pushUnique = (items, seen, item) => {
+    const key = JSON.stringify([item.messageId, item.idSource, item.idSources, item.infoSource, item.aadSource, item.info.toString('hex'), item.aad.toString('hex')])
+    if (!seen.has(key)) { seen.add(key); items.push(item) }
+}
+
+const getCandidateIds = messageKey => {
+    const ordered = [
+        messageKey?.botType === 'full' ? { source: 'stanzaId', messageId: messageKey?.stanzaId } : { source: 'botEditTargetId', messageId: messageKey?.botEditTargetId },
+        { source: 'targetId', messageId: messageKey?.targetId },
+        { source: 'metaTargetId', messageId: messageKey?.metaTargetId },
+        { source: 'stanzaId', messageId: messageKey?.stanzaId }
+    ]
+    const candidates = Array.isArray(messageKey?.targetIdCandidates) ? messageKey.targetIdCandidates : []
+    for (let i = 0; i < candidates.length; i++) ordered.push({ source: `targetIdCandidates[${i}]`, messageId: candidates[i] })
+    const grouped = new Map()
+    for (const c of ordered) {
+        if (!c.messageId) continue
+        const id = String(c.messageId)
+        const existing = grouped.get(id)
+        if (existing) { if (!existing.idSources.includes(c.source)) existing.idSources.push(c.source) }
+        else grouped.set(id, { messageId: id, idSource: c.source, idSources: [c.source] })
+    }
+    return Array.from(grouped.values())
+}
+
+const getJidCandidates = messageKey => {
+    const ordered = [
+        { source: 'meId', jid: messageKey?.meId },
+        { source: 'conversationJid', jid: messageKey?.conversationJid },
+        { source: 'senderJid', jid: messageKey?.senderJid },
+        { source: 'meLidNormalized', jid: jidNormalizedUser(messageKey?.meLid) }
+    ]
+    const seen = new Set()
+    const result = []
+    for (const c of ordered) {
+        if (!c.jid) continue
+        const jid = String(c.jid)
+        if (!seen.has(jid)) { seen.add(jid); result.push({ source: c.source, jid, value: Buffer.from(jid) }) }
+    }
+    return result
+}
+
+const buildMsmsgDecryptionStrategies = messageKey => {
+    const botJid = String(messageKey?.participant || '')
+    const botJidBuffer = Buffer.from(botJid)
+    const targetIds = getCandidateIds(messageKey)
+    const jidCandidates = getJidCandidates(messageKey)
+    const primaryJid = jidCandidates[0]
+    const alternateJid = jidCandidates.find(c => c.source !== primaryJid?.source && c.jid !== botJid)
+    const strategies = [], seen = new Set()
+    for (const idCandidate of targetIds) {
+        for (const idForm of buildMessageIdRepresentations(idCandidate.messageId)) {
+            pushUnique(strategies, seen, { mode: '2step', idSource: idCandidate.idSource, idSources: idCandidate.idSources, infoSource: `${idForm.label}+meId+botJid`, aadSource: `${idForm.label}+0+botJid`, authTagLayout: 'trailing', messageId: idCandidate.messageId, info: Buffer.concat([idForm.value, primaryJid.value, botJidBuffer, Buffer.alloc(0)]), aad: Buffer.concat([idForm.value, Buffer.from([0]), botJidBuffer]), attemptLabel: `${idCandidate.idSource}:${idForm.label}:primary` })
+            if (alternateJid) pushUnique(strategies, seen, { mode: '2step', idSource: idCandidate.idSource, idSources: idCandidate.idSources, infoSource: `${idForm.label}+${alternateJid.source}+botJid`, aadSource: `${idForm.label}+0+${alternateJid.source}`, authTagLayout: 'trailing', messageId: idCandidate.messageId, info: Buffer.concat([idForm.value, alternateJid.value, botJidBuffer, Buffer.alloc(0)]), aad: Buffer.concat([idForm.value, Buffer.from([0]), alternateJid.value]), attemptLabel: `${idCandidate.idSource}:${idForm.label}:${alternateJid.source}` })
+        }
+    }
+    return strategies.slice(0, 12)
+}
+
+const assertRequired = (value, label) => {
+    if (!value || (Buffer.isBuffer(value) && value.length === 0) || (value instanceof Uint8Array && value.byteLength === 0)) throw new Error(`Missing required ${label} for msmsg decryption`)
+}
+
+const decryptWithStrategy = (messageSecret, msMsg, strategy) => {
+    const baseSecret = Buffer.from(hkdf(toBuffer(messageSecret), KEY_LENGTH, { info: BOT_MESSAGE_INFO }))
+    const key = Buffer.from(hkdf(baseSecret, KEY_LENGTH, { info: strategy.info }))
+    const payload = toBuffer(msMsg.encPayload)
+    const ciphertextWithTag = Buffer.concat([payload.slice(0, -AUTH_TAG_LENGTH), payload.slice(-AUTH_TAG_LENGTH)])
+    return Buffer.from(aesDecryptGCM(ciphertextWithTag, key, toBuffer(msMsg.encIv), strategy.aad))
+}
+
+export const decodeDecryptedMsmsgMessage = decrypted => {
+    const messageBuffer = toBuffer(decrypted)
+    try {
+        const unpadded = Buffer.from(unpadRandomMax16(messageBuffer))
+        const decoded = proto.Message.decode(unpadded)
+        const hasContent = Object.keys(decoded).some(key => key !== 'messageContextInfo' && decoded[key] != null)
+        if (hasContent) return decoded
+    } catch { }
+    return proto.Message.decode(messageBuffer)
+}
+
+export const decryptMsmsgBotMessage = async (messageSecret, messageKey, msMsg) => {
+    assertRequired(messageSecret, 'messageSecret')
+    assertRequired(messageKey?.participant, 'participant')
+    assertRequired(messageKey?.meId, 'meId')
+    assertRequired(msMsg?.encIv, 'encIv')
+    assertRequired(msMsg?.encPayload, 'encPayload')
+    if (getCandidateIds(messageKey).length === 0) throw new Error('Missing required target message id for msmsg decryption')
+    const strategies = buildMsmsgDecryptionStrategies(messageKey)
+    const attemptedStrategies = []
+    let lastError
+    for (const strategy of strategies) {
+        try { return decryptWithStrategy(messageSecret, msMsg, strategy) }
+        catch (error) { attemptedStrategies.push({ idSource: strategy.idSource, idSources: strategy.idSources, infoSource: strategy.infoSource, aadSource: strategy.aadSource, messageId: strategy.messageId }); lastError = error }
+    }
+    const error = new Error('Failed to decrypt msmsg with bounded deterministic strategies')
+    error.attemptedStrategies = attemptedStrategies
+    error.cause = lastError
+    throw error
+}

package/lib/Utils/meta-ai.d.ts

@@ -0,0 +1,4 @@
+export function askMetaAI(sock: any, prompt: any, opts1?: { [key: string]: any; 
+    timeoutMs?: number;
+    jid?: "13135550002@c.us";
+}): Promise<any>;

package/lib/Utils/meta-ai.js

@@ -0,0 +1,75 @@
+// Vanz@Port (v2.0.3) --- ported from @japofc/baileys 2.4.1 (MIT, author JAPofc / J.AP), lib/Utils/meta-ai.js. See NOTICE.md.
+/**
+ * JAP@Add --- Meta AI chat helper (EXPERIMENTAL).
+ *
+ * Sends a prompt to Meta AI's official JID (`13135550002@c.us`, override via
+ * `opts.jid` — e.g. the newer `11111111111@bot`) and waits for its reply.
+ * This relies on Meta AI being available for the linked account/region —
+ * expect timeouts where Meta AI is not rolled out.
+ *
+ * ```js
+ * const { text } = await askMetaAI(sock, 'Jelaskan black hole!')
+ * // or: await sock.askMetaAI('...')
+ * ```
+ */
+import { Boom } from '@hapi/boom';
+import { META_AI_JID } from '../WABinary/index.js';
+import { normalizeMessageContent } from './messages.js';
+const extractReplyText = (webMessage) => {
+    if (!webMessage?.message) {
+        return '';
+    }
+    const content = normalizeMessageContent(webMessage.message);
+    return content?.conversation
+        || content?.extendedTextMessage?.text
+        || content?.imageMessage?.caption
+        || content?.videoMessage?.caption
+        || '';
+};
+/**
+ * Ask Meta AI something. Resolves `{ sent, reply, text }`.
+ * Rejects with 408 on timeout (default 60s).
+ */
+export const askMetaAI = async (sock, prompt, { timeoutMs = 60000, jid = META_AI_JID } = {}) => {
+    if (!sock || typeof sock.sendMessage !== 'function' || typeof sock.ev?.on !== 'function') {
+        throw new Boom('askMetaAI(sock, ...) requires an active Baileys socket', { statusCode: 400 });
+    }
+    if (!prompt || typeof prompt !== 'string') {
+        throw new Boom('askMetaAI(prompt) requires a non-empty string', { statusCode: 400 });
+    }
+    const sent = await sock.sendMessage(jid, { text: prompt });
+    const sentId = sent?.key?.id;
+    const startedAt = Date.now();
+    return new Promise((resolve, reject) => {
+        const done = (fn) => (...args) => {
+            clearTimeout(timer);
+            try {
+                sock.ev.off('messages.upsert', onUpsert);
+            }
+            catch { }
+            fn(...args);
+        };
+        const timer = setTimeout(done(() => reject(new Boom('askMetaAI: timed out waiting for Meta AI reply', { statusCode: 408 }))), timeoutMs);
+        const succeed = done(resolve);
+        const onUpsert = ({ messages } = {}) => {
+            for (const m of messages || []) {
+                if (!m || m.key?.fromMe || m.key?.remoteJid !== jid || !m.message) {
+                    continue;
+                }
+                // Ignore stale history replayed on (re)connect.
+                const msgMs = Number(m.messageTimestamp || 0) * 1000;
+                if (msgMs && msgMs < startedAt - 5000) {
+                    continue;
+                }
+                // Prefer a reply that quotes our prompt; otherwise take the first fresh message.
+                const quotedId = m.message?.extendedTextMessage?.contextInfo?.stanzaId;
+                if (quotedId && sentId && quotedId !== sentId) {
+                    continue;
+                }
+                succeed({ sent, reply: m, text: extractReplyText(m) });
+                return;
+            }
+        };
+        sock.ev.on('messages.upsert', onUpsert);
+    });
+};

package/lib/Utils/migrate-auth-state.d.ts

@@ -0,0 +1,23 @@
+export function migrateAuthState(opts1: { [key: string]: any; 
+    from: any;
+    to: any;
+    batchSize?: number;
+    skipExisting?: boolean;
+    logger: any;
+    verify?: boolean;
+}): Promise<{
+    creds: {
+        copied: boolean;
+    };
+    counts: {};
+    verified: boolean;
+    warnings: any[];
+}>;
+/**
+ * Full AuthenticationState migration helper.
+ *
+ * Adapted from the MIT-licensed WhiskeySockets/Baileys migration utility.
+ * Vanzxy version is intentionally JS/runtime-focused and only relies on the
+ * optional list/listIds methods added to SignalKeyStore.
+ */
+export const ALL_TYPES: string[];

package/lib/Utils/migrate-auth-state.js

@@ -0,0 +1,126 @@
+/**
+ * Full AuthenticationState migration helper.
+ *
+ * Adapted from the MIT-licensed WhiskeySockets/Baileys migration utility.
+ * Vanzxy version is intentionally JS/runtime-focused and only relies on the
+ * optional list/listIds methods added to SignalKeyStore.
+ */
+const ALL_TYPES = [
+    'pre-key',
+    'session',
+    'sender-key',
+    'sender-key-memory',
+    'app-state-sync-key',
+    'app-state-sync-version',
+    'lid-mapping',
+    'device-list',
+    'tctoken',
+    'identity-key'
+];
+
+export async function migrateAuthState({ from, to, batchSize = 100, skipExisting = true, logger, verify = true }) {
+    if (!from?.keys?.list && !from?.keys?.listIds) {
+        throw new Error('migrateAuthState: source store does not implement list(type) or listIds(type)');
+    }
+    if (!to?.keys?.set) {
+        throw new Error('migrateAuthState: destination store does not implement set(data)');
+    }
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+        throw new TypeError('migrateAuthState: batchSize must be a positive integer');
+    }
+    const result = { creds: { copied: false }, counts: {}, verified: false, warnings: [] };
+    Object.assign(to.creds, from.creds);
+    result.creds.copied = true;
+    logger?.info?.('migrateAuthState: creds copied');
+
+    for (const type of ALL_TYPES) {
+        let existingIds = null;
+        if (skipExisting && to.keys.listIds) {
+            existingIds = new Set();
+            try {
+                for await (const id of to.keys.listIds(type)) existingIds.add(id);
+            }
+            catch (error) {
+                result.warnings.push(`failed to enumerate existing destination ids for ${type}: ${String(error)}`);
+                existingIds = null;
+            }
+        }
+        const batch = {};
+        let total = 0;
+        const flush = async () => {
+            const ids = Object.keys(batch);
+            if (!ids.length) return;
+            await to.keys.set({ [type]: { ...batch } });
+            for (const id of ids) delete batch[id];
+            total += ids.length;
+        };
+        try {
+            if (from.keys.list) {
+                for await (const [id, value] of from.keys.list(type)) {
+                    if (existingIds?.has(id)) continue;
+                    batch[id] = value;
+                    if (Object.keys(batch).length >= batchSize) await flush();
+                }
+            }
+            else {
+                for await (const id of from.keys.listIds(type)) {
+                    if (existingIds?.has(id)) continue;
+                    const data = await from.keys.get(type, [id]);
+                    if (data[id] !== undefined) batch[id] = data[id];
+                    if (Object.keys(batch).length >= batchSize) await flush();
+                }
+            }
+        }
+        catch (error) {
+            result.warnings.push(`failed to enumerate source records for ${type}: ${String(error)}`);
+        }
+        await flush();
+        result.counts[type] = total;
+        logger?.info?.({ type, count: total }, 'migrateAuthState: copied type');
+    }
+    if (verify) result.verified = await verifyMigration(from, to, result.warnings, logger);
+    logger?.info?.({ counts: result.counts, verified: result.verified, warnings: result.warnings.length }, 'migrateAuthState: done');
+    return result;
+}
+
+async function collectIds(state, type) {
+    try {
+        const out = new Set();
+        if (state.keys.listIds) {
+            for await (const id of state.keys.listIds(type)) out.add(id);
+        }
+        else if (state.keys.list) {
+            for await (const [id] of state.keys.list(type)) out.add(id);
+        }
+        else return null;
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+
+async function verifyMigration(from, to, warnings, logger) {
+    let ok = true;
+    for (const type of ALL_TYPES) {
+        const fromIds = await collectIds(from, type);
+        const toIds = await collectIds(to, type);
+        if (!fromIds || !toIds) {
+            warnings.push(`verification skipped for ${type}: unable to enumerate one side`);
+            ok = false;
+            continue;
+        }
+        for (const id of fromIds) if (!toIds.has(id)) {
+            warnings.push(`destination missing ${type}:${id}`);
+            ok = false;
+        }
+        for (const id of toIds) if (!fromIds.has(id)) {
+            warnings.push(`destination has unexpected ${type}:${id}`);
+            ok = false;
+        }
+    }
+    logger?.info?.({ ok }, 'migrateAuthState: verification complete');
+    return ok;
+}
+
+export { ALL_TYPES };

package/lib/Utils/mini-app.d.ts

@@ -0,0 +1,20 @@
+export const MINI_APP_DEFAULT_BUTTON_TEXT: "\uD83D\uDE80 Open App";
+export function buildMiniAppContent(opts4?: { [key: string]: any; 
+    buttons?: any[];
+    useWebview?: boolean;
+}): Promise<{
+    text: string;
+    footer: any;
+    nativeFlow: any[];
+}>;
+export function sendMiniApp(sock: any, jid: any, miniApp: any, options?: {}): Promise<any>;
+export function createMiniAppLink(baseUrl: any, params?: {}, opts1?: { [key: string]: any; }): string;
+export function parseMiniAppParams(link: any, opts2?: { [key: string]: any; }): {};
+export function buildFlowDataExchange(action: any, data?: {}, opts3?: { [key: string]: any; 
+    version?: string;
+}): {
+    token?: any;
+    version: string;
+    action: string;
+    data: {};
+};

package/lib/Utils/mini-app.js

@@ -0,0 +1,215 @@
+// Vanz@Port --- ported from @japofc/baileys 2.4.1 (mini-app.js). Creator credits untouched. See NOTICE.md.
+/**
+ * JAP@Add --- "Mini App" sender.
+ *
+ * Two delivery modes (both are real WhatsApp "mini app" patterns):
+ *
+ * 1. `url` — rich interactive card + CTA button opening your web app
+ *    (in-app webview when supported, else the system browser). Optional
+ *    `params` are appended as query string, so the app knows who opened it.
+ * 2. `flow` — WhatsApp Flows button (`flow_action`): a TRUE native in-chat
+ *    mini app (forms/screens rendered inside WhatsApp, no browser at all).
+ *    Requires a flow ID registered & published in Flows Manager. Both modes
+ *    can be combined — the card then carries two buttons.
+ *
+ * ```js
+ * import { sendMiniApp } from '@japofc/baileys'
+ * await sendMiniApp(sock, jid, {
+ *   title: 'My Mini App',
+ *   body: 'Tap the button to open the app 👇',
+ *   url: 'https://myapp.example.com',
+ *   params: { ref: 'wa-bot' },          // → ?ref=wa-bot
+ *   flow: { id: '123456789', cta: '📝 Isi Form', screen: 'WELCOME' }, // optional
+ *   thumbnail: 'https://myapp.example.com/icon.png', // url or Buffer (optional)
+ * })
+ * ```
+ */
+import { Boom } from '@hapi/boom';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { fetchWithTimeout } from './fetch-timeout.js';
+export const MINI_APP_DEFAULT_BUTTON_TEXT = '🚀 Open App';
+const MAX_THUMBNAIL_BYTES = 512 * 1024;
+const resolveThumbnail = async (thumbnail) => {
+    if (!thumbnail) {
+        return undefined;
+    }
+    if (Buffer.isBuffer(thumbnail)) {
+        return thumbnail;
+    }
+    if (typeof thumbnail === 'string') {
+        let res;
+        try {
+            res = await fetchWithTimeout(thumbnail);
+        }
+        catch (err) {
+            throw new Boom(`miniApp.thumbnail: failed to fetch ${thumbnail} (${err?.message || err})`, { statusCode: 400 });
+        }
+        if (!res.ok) {
+            throw new Boom(`miniApp.thumbnail: fetch failed with HTTP ${res.status}`, { statusCode: 400 });
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (!buf.length || buf.length > MAX_THUMBNAIL_BYTES) {
+            throw new Boom(`miniApp.thumbnail: must be 1–${MAX_THUMBNAIL_BYTES} bytes`, { statusCode: 400 });
+        }
+        return buf;
+    }
+    throw new Boom('miniApp.thumbnail must be a Buffer or a URL string', { statusCode: 400 });
+};
+const normalizeFlowConfig = (flow) => {
+    if (!flow) {
+        return undefined;
+    }
+    const cfg = typeof flow === 'string' ? { id: flow } : flow;
+    if (!cfg || typeof cfg !== 'object' || !cfg.id || typeof cfg.id !== 'string') {
+        throw new Boom('miniApp.flow.id is required (your published WhatsApp Flow ID)', { statusCode: 400 });
+    }
+    return cfg;
+};
+const appendUrlParams = (link, params) => {
+    if (!params || typeof params !== 'object' || !Object.keys(params).length) {
+        return link;
+    }
+    let u;
+    try {
+        u = new URL(link);
+    }
+    catch {
+        throw new Boom(`miniApp.url is not a valid URL: ${link}`, { statusCode: 400 });
+    }
+    for (const [k, v] of Object.entries(params)) {
+        u.searchParams.set(k, String(v));
+    }
+    return u.toString();
+};
+/**
+ * Build `sendMessage`-ready content for a Mini App card.
+ * Needs `url`, `flow`, or both. Thumbnail failures are non-fatal: the card is
+ * still built, just without the image.
+ */
+export const buildMiniAppContent = async ({ title, body, text, url, appUrl, flow, params, buttonText, buttons = [], footer, thumbnail, useWebview = true, onThumbnailError, ...passthrough } = {}) => {
+    const link = url || appUrl;
+    const flowCfg = normalizeFlowConfig(flow);
+    if ((!link || typeof link !== 'string') && !flowCfg) {
+        throw new Boom('miniApp needs either `url` (webview app) or `flow` (WhatsApp Flow) — or both', { statusCode: 400 });
+    }
+    const mainText = body || text;
+    if (!mainText || typeof mainText !== 'string') {
+        throw new Boom('miniApp.body (or text) is required', { statusCode: 400 });
+    }
+    const finalUrl = link ? appendUrlParams(link, params) : undefined;
+    let thumb;
+    try {
+        thumb = await resolveThumbnail(thumbnail);
+    }
+    catch (err) {
+        if (typeof onThumbnailError === 'function') {
+            try {
+                onThumbnailError(err);
+            }
+            catch { }
+        }
+    }
+    const cardTitle = title || 'Mini App';
+    const nativeFlow = [
+        ...(finalUrl ? [{ buttonText: buttonText || MINI_APP_DEFAULT_BUTTON_TEXT, url: finalUrl, useWebview }] : []),
+        ...(flowCfg ? [{ buttonText: flowCfg.cta || '📝 Open', flow: flowCfg }] : []),
+        ...buttons
+    ];
+    const content = {
+        text: mainText,
+        footer: footer ?? cardTitle,
+        nativeFlow,
+        ...passthrough
+    };
+    // NOTE: only attach `thumbnail` when we actually have one — the ad-reply
+    // builder throws on a present-but-non-Buffer thumbnail value.
+    if (finalUrl) {
+        const externalAdReply = {
+            title: cardTitle,
+            body: mainText.slice(0, 120),
+            url: finalUrl,
+            mediaType: 1,
+            largeThumbnail: !!thumb
+        };
+        if (thumb) {
+            externalAdReply.thumbnail = thumb;
+        }
+        content.externalAdReply = content.externalAdReply || externalAdReply;
+    }
+    return content;
+};
+/**
+ * Standalone sender (same style as `sendButtons` / `sendInteractiveMessage`):
+ * `sendMiniApp(sock, jid, miniApp, options?)`. A `sock.sendMiniApp` alias exists too.
+ */
+export const sendMiniApp = async (sock, jid, miniApp, options = {}) => {
+    if (!sock || typeof sock.sendMessage !== 'function') {
+        throw new Boom('sendMiniApp(sock, ...) requires an active Baileys socket', { statusCode: 400 });
+    }
+    return sock.sendMessage(jid, await buildMiniAppContent(miniApp), options);
+};
+
+/**
+ * JAP@Add --- build a mini-app deep link with optional HMAC-signed params, so
+ * your web app can verify the opener came from your bot untampered.
+ * `createMiniAppLink('https://app.example.com', { uid: '123' }, { secret })`
+ * → `'https://app.example.com/?uid=123&sig=…'`.
+ */
+export const createMiniAppLink = (baseUrl, params = {}, { secret } = {}) => {
+    let u;
+    try {
+        u = new URL(baseUrl);
+    }
+    catch {
+        throw new Boom(`miniApp.url is not a valid URL: ${baseUrl}`, { statusCode: 400 });
+    }
+    for (const [k, v] of Object.entries(params || {})) {
+        u.searchParams.set(k, String(v));
+    }
+    if (secret) {
+        const payload = [...u.searchParams.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `${k}=${v}`).join('&');
+        u.searchParams.set('sig', createHmac('sha256', secret).update(payload).digest('hex'));
+    }
+    return u.toString();
+};
+
+/**
+ * JAP@Add --- parse + (optionally) verify a mini-app link's params.
+ * Throws when `secret` is given and the signature is missing/invalid.
+ */
+export const parseMiniAppParams = (link, { secret } = {}) => {
+    let u;
+    try {
+        u = new URL(link);
+    }
+    catch {
+        throw new Boom(`miniApp.url is not a valid URL: ${link}`, { statusCode: 400 });
+    }
+    const out = {};
+    for (const [k, v] of u.searchParams.entries()) {
+        if (k !== 'sig') {
+            out[k] = v;
+        }
+    }
+    if (secret) {
+        const sig = u.searchParams.get('sig') || '';
+        const payload = Object.entries(out).sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `${k}=${v}`).join('&');
+        const expect = createHmac('sha256', secret).update(payload).digest('hex');
+        const ok = sig.length === expect.length && (() => { try { return timingSafeEqual(Buffer.from(sig), Buffer.from(expect)); } catch { return false; } })();
+        if (!ok) {
+            throw new Boom('miniApp.params: invalid signature', { statusCode: 403 });
+        }
+    }
+    return out;
+};
+
+/**
+ * JAP@Add --- build a WhatsApp Flows `data_exchange` action payload
+ * (`{ version, action, data, token? }`) for the `flow.actionPayload` shortcut.
+ */
+export const buildFlowDataExchange = (action, data = {}, { version = '3.0', token } = {}) => {
+    if (!action || typeof action !== 'string') {
+        throw new Boom('flow action is required (e.g. navigate, data_exchange)', { statusCode: 400 });
+    }
+    return { version, action, data, ...(token ? { token } : {}) };
+};

package/lib/Utils/mock-socket.d.ts

@@ -0,0 +1,67 @@
+export function createMockSocket(options?: {}): {
+    sock: {
+        ev: {
+            on: (event: any, listener: any) => /*elided*/ any;
+            off: (event: any, listener: any) => /*elided*/ any;
+            once: (event: any, listener: any) => /*elided*/ any;
+            removeAllListeners: (event: any) => /*elided*/ any;
+            emit: (event: any, data: any) => any;
+            process: (handler: any) => () => any;
+            buffer: () => void;
+            flush: () => boolean;
+            isBuffering: () => boolean;
+        };
+        user: {
+            id: any;
+            name: any;
+        };
+        authState: {
+            creds: {
+                me: {
+                    id: any;
+                    name: any;
+                };
+                registered: boolean;
+            };
+        };
+        type: string;
+        ws: {
+            readyState: number;
+            close: () => void;
+        };
+        sendMessage: (jid: any, content: any, opts?: {}) => Promise<import("../index.js").proto.WebMessageInfo>;
+        readMessages: (keys: any) => Promise<void>;
+        sendPresenceUpdate: (type: any, toJid: any) => Promise<void>;
+        presenceSubscribe: () => Promise<void>;
+        groupMetadata: (jid: any) => Promise<{
+            id: any;
+            subject: string;
+            owner: any;
+            participants: {
+                id: any;
+                admin: string;
+            }[];
+            creation: number;
+        }>;
+        onWhatsApp: (...jids: any[]) => Promise<{
+            jid: any;
+            exists: boolean;
+        }[]>;
+        profilePictureUrl: () => Promise<any>;
+        updateMediaMessage: (msg: any) => Promise<any>;
+        relayMessage: (jid: any, content: any, opts?: {}) => Promise<any>;
+        end: () => void;
+        logout: () => Promise<void>;
+    };
+    outbox: any[];
+    eventLog: any[];
+    readReceipts: any[];
+    presenceLog: any[];
+    receiveText: (fromJid: any, text: any, opts?: {}) => Promise<any>;
+    receiveMessage: (msg: any) => Promise<any>;
+    waitForReply: (filter: any, timeoutMs?: number) => Promise<any>;
+    connect: () => void;
+    disconnect: (error: any) => void;
+    reset: () => void;
+    readonly connectionState: string;
+};