@japofc/baileys 2.1.0

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

@@ -0,0 +1,13 @@
+/**
+ * JAP@Add --- Type declarations for the Meta AI helper (experimental).
+ */
+export interface AskMetaAIOptions {
+    timeoutMs?: number;
+    jid?: string;
+}
+export interface AskMetaAIResult {
+    sent: any;
+    reply: any;
+    text: string;
+}
+export declare const askMetaAI: (sock: any, prompt: string, opts?: AskMetaAIOptions) => Promise<AskMetaAIResult>;

package/lib/Utils/meta-ai.js

@@ -0,0 +1,74 @@
+/**
+ * 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/mini-app.d.ts

@@ -0,0 +1,35 @@
+/**
+ * JAP@Add --- Type declarations for the Mini App sender.
+ */
+export declare const MINI_APP_DEFAULT_BUTTON_TEXT: string;
+export interface MiniAppFlowOptions {
+    id: string;
+    cta?: string;
+    screen?: string;
+    data?: any;
+    action?: string;
+    actionPayload?: any;
+    version?: string;
+    token?: string;
+}
+export interface MiniAppOptions {
+    title?: string;
+    body?: string;
+    text?: string;
+    url?: string;
+    appUrl?: string;
+    flow?: string | MiniAppFlowOptions;
+    params?: Record<string, string | number | boolean>;
+    buttonText?: string;
+    buttons?: any[];
+    footer?: string;
+    thumbnail?: Buffer | string;
+    useWebview?: boolean;
+    onThumbnailError?: (err: any) => void;
+    [key: string]: any;
+}
+export declare const buildMiniAppContent: (opts?: MiniAppOptions) => Promise<any>;
+export declare const sendMiniApp: (sock: any, jid: any, miniApp: MiniAppOptions, options?: any) => Promise<any>;
+export declare const createMiniAppLink: (baseUrl: string, params?: Record<string, string | number | boolean>, opts?: { secret?: string }) => string;
+export declare const parseMiniAppParams: (link: string, opts?: { secret?: string }) => Record<string, string>;
+export declare const buildFlowDataExchange: (action: string, data?: any, opts?: { version?: string; token?: string }) => any;

package/lib/Utils/mini-app.js

@@ -0,0 +1,213 @@
+/**
+ * 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';
+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 fetch(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/noise-handler.d.ts

@@ -0,0 +1,20 @@
+export function makeNoiseHandler({ keyPair: { private: privateKey, public: publicKey }, NOISE_HEADER, logger, routingInfo }: {
+    keyPair: {
+        private: any;
+        public: any;
+    };
+    NOISE_HEADER: any;
+    logger: any;
+    routingInfo: any;
+}): {
+    encrypt: (plaintext: any) => any;
+    decrypt: (ciphertext: any) => any;
+    authenticate: (data: any) => void;
+    mixIntoKey: (data: any) => void;
+    finishInit: () => Promise<void>;
+    processHandshake: ({ serverHello }: {
+        serverHello: any;
+    }, noiseKey: any) => any;
+    encodeFrame: (data: any) => any;
+    decodeFrame: (newData: any, onFrame: any) => Promise<void>;
+};

package/lib/Utils/noise-handler.js

@@ -0,0 +1,200 @@
+import { Boom } from '@hapi/boom';
+import { proto } from '../../WAProto/index.js';
+import { NOISE_MODE, WA_CERT_DETAILS } from '../Defaults/index.js';
+import { decodeBinaryNode } from '../WABinary/index.js';
+import { aesDecryptGCM, aesEncryptGCM, Curve, hkdf, sha256 } from './crypto.js';
+const IV_LENGTH = 12;
+const EMPTY_BUFFER = Buffer.alloc(0);
+const generateIV = (counter) => {
+    const iv = new ArrayBuffer(IV_LENGTH);
+    new DataView(iv).setUint32(8, counter);
+    return new Uint8Array(iv);
+};
+class TransportState {
+    constructor(encKey, decKey) {
+        this.encKey = encKey;
+        this.decKey = decKey;
+        this.readCounter = 0;
+        this.writeCounter = 0;
+        this.iv = new Uint8Array(IV_LENGTH);
+    }
+    encrypt(plaintext) {
+        const c = this.writeCounter++;
+        this.iv[8] = (c >>> 24) & 0xff;
+        this.iv[9] = (c >>> 16) & 0xff;
+        this.iv[10] = (c >>> 8) & 0xff;
+        this.iv[11] = c & 0xff;
+        return aesEncryptGCM(plaintext, this.encKey, this.iv, EMPTY_BUFFER);
+    }
+    decrypt(ciphertext) {
+        const c = this.readCounter++;
+        this.iv[8] = (c >>> 24) & 0xff;
+        this.iv[9] = (c >>> 16) & 0xff;
+        this.iv[10] = (c >>> 8) & 0xff;
+        this.iv[11] = c & 0xff;
+        return aesDecryptGCM(ciphertext, this.decKey, this.iv, EMPTY_BUFFER);
+    }
+}
+export const makeNoiseHandler = ({ keyPair: { private: privateKey, public: publicKey }, NOISE_HEADER, logger, routingInfo }) => {
+    logger = logger.child({ class: 'ns' });
+    const data = Buffer.from(NOISE_MODE);
+    let hash = data.byteLength === 32 ? data : sha256(data);
+    let salt = hash;
+    let encKey = hash;
+    let decKey = hash;
+    let counter = 0;
+    let sentIntro = false;
+    let inBytes = Buffer.alloc(0);
+    let transport = null;
+    let isWaitingForTransport = false;
+    let pendingOnFrame = null;
+    let introHeader;
+    if (routingInfo) {
+        introHeader = Buffer.alloc(7 + routingInfo.byteLength + NOISE_HEADER.length);
+        introHeader.write('ED', 0, 'utf8');
+        introHeader.writeUint8(0, 2);
+        introHeader.writeUint8(1, 3);
+        introHeader.writeUint8(routingInfo.byteLength >> 16, 4);
+        introHeader.writeUint16BE(routingInfo.byteLength & 65535, 5);
+        introHeader.set(routingInfo, 7);
+        introHeader.set(NOISE_HEADER, 7 + routingInfo.byteLength);
+    }
+    else {
+        introHeader = Buffer.from(NOISE_HEADER);
+    }
+    const authenticate = (data) => {
+        if (!transport) {
+            hash = sha256(Buffer.concat([hash, data]));
+        }
+    };
+    const encrypt = (plaintext) => {
+        if (transport) {
+            return transport.encrypt(plaintext);
+        }
+        const result = aesEncryptGCM(plaintext, encKey, generateIV(counter++), hash);
+        authenticate(result);
+        return result;
+    };
+    const decrypt = (ciphertext) => {
+        if (transport) {
+            return transport.decrypt(ciphertext);
+        }
+        const result = aesDecryptGCM(ciphertext, decKey, generateIV(counter++), hash);
+        authenticate(ciphertext);
+        return result;
+    };
+    const localHKDF = (data) => {
+        const key = hkdf(Buffer.from(data), 64, { salt, info: '' });
+        return [key.subarray(0, 32), key.subarray(32)];
+    };
+    const mixIntoKey = (data) => {
+        const [write, read] = localHKDF(data);
+        salt = write;
+        encKey = read;
+        decKey = read;
+        counter = 0;
+    };
+    const finishInit = async () => {
+        isWaitingForTransport = true;
+        const [write, read] = localHKDF(new Uint8Array(0));
+        transport = new TransportState(write, read);
+        isWaitingForTransport = false;
+        logger.trace('Noise handler transitioned to Transport state');
+        if (pendingOnFrame) {
+            logger.trace({ length: inBytes.length }, 'Flushing buffered frames after transport ready');
+            await processData(pendingOnFrame);
+            pendingOnFrame = null;
+        }
+    };
+    const processData = async (onFrame) => {
+        let size;
+        while (true) {
+            if (inBytes.length < 3)
+                return;
+            size = (inBytes[0] << 16) | (inBytes[1] << 8) | inBytes[2];
+            if (inBytes.length < size + 3)
+                return;
+            let frame = inBytes.subarray(3, size + 3);
+            inBytes = inBytes.subarray(size + 3);
+            if (transport) {
+                const result = transport.decrypt(frame);
+                frame = await decodeBinaryNode(result);
+            }
+            if (logger.level === 'trace') {
+                logger.trace({ msg: frame?.attrs?.id }, 'recv frame');
+            }
+            onFrame(frame);
+        }
+    };
+    authenticate(NOISE_HEADER);
+    authenticate(publicKey);
+    return {
+        encrypt,
+        decrypt,
+        authenticate,
+        mixIntoKey,
+        finishInit,
+        processHandshake: ({ serverHello }, noiseKey) => {
+            authenticate(serverHello.ephemeral);
+            mixIntoKey(Curve.sharedKey(privateKey, serverHello.ephemeral));
+            const decStaticContent = decrypt(serverHello.static);
+            mixIntoKey(Curve.sharedKey(privateKey, decStaticContent));
+            const certDecoded = decrypt(serverHello.payload);
+            const { intermediate: certIntermediate, leaf } = proto.CertChain.decode(certDecoded);
+            // leaf
+            if (!leaf?.details || !leaf?.signature) {
+                throw new Boom('invalid noise leaf certificate', { statusCode: 400 });
+            }
+            if (!certIntermediate?.details || !certIntermediate?.signature) {
+                throw new Boom('invalid noise intermediate certificate', { statusCode: 400 });
+            }
+            const details = proto.CertChain.NoiseCertificate.Details.decode(certIntermediate.details);
+            const { issuerSerial } = details;
+            const verify = Curve.verify(details.key, leaf.details, leaf.signature);
+            const verifyIntermediate = Curve.verify(WA_CERT_DETAILS.PUBLIC_KEY, certIntermediate.details, certIntermediate.signature);
+            if (!verify) {
+                throw new Boom('noise certificate signature invalid', { statusCode: 400 });
+            }
+            if (!verifyIntermediate) {
+                throw new Boom('noise intermediate certificate signature invalid', { statusCode: 400 });
+            }
+            if (issuerSerial !== WA_CERT_DETAILS.SERIAL) {
+                throw new Boom('certification match failed', { statusCode: 400 });
+            }
+            const keyEnc = encrypt(noiseKey.public);
+            mixIntoKey(Curve.sharedKey(noiseKey.private, serverHello.ephemeral));
+            return keyEnc;
+        },
+        encodeFrame: (data) => {
+            if (transport) {
+                data = transport.encrypt(data);
+            }
+            const dataLen = data.byteLength;
+            const introSize = sentIntro ? 0 : introHeader.length;
+            const frame = Buffer.allocUnsafe(introSize + 3 + dataLen);
+            if (!sentIntro) {
+                frame.set(introHeader);
+                sentIntro = true;
+            }
+            frame[introSize] = (dataLen >>> 16) & 0xff;
+            frame[introSize + 1] = (dataLen >>> 8) & 0xff;
+            frame[introSize + 2] = dataLen & 0xff;
+            frame.set(data, introSize + 3);
+            return frame;
+        },
+        decodeFrame: async (newData, onFrame) => {
+            if (isWaitingForTransport) {
+                inBytes = Buffer.concat([inBytes, newData]);
+                pendingOnFrame = onFrame;
+                return;
+            }
+            if (inBytes.length === 0) {
+                inBytes = Buffer.from(newData);
+            }
+            else {
+                inBytes = Buffer.concat([inBytes, newData]);
+            }
+            await processData(onFrame);
+        }
+    };
+};

package/lib/Utils/offline-node-processor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates a processor for offline stanza nodes that:
+ * - Queues nodes for sequential processing
+ * - Yields to the event loop periodically to avoid blocking
+ * - Catches handler errors to prevent the processing loop from crashing
+ */
+export function makeOfflineNodeProcessor(nodeProcessorMap: any, deps: any, batchSize?: number): {
+    enqueue: (type: any, node: any) => void;
+};

package/lib/Utils/offline-node-processor.js

@@ -0,0 +1,39 @@
+/**
+ * Creates a processor for offline stanza nodes that:
+ * - Queues nodes for sequential processing
+ * - Yields to the event loop periodically to avoid blocking
+ * - Catches handler errors to prevent the processing loop from crashing
+ */
+export function makeOfflineNodeProcessor(nodeProcessorMap, deps, batchSize = 10) {
+    const nodes = [];
+    let isProcessing = false;
+    const enqueue = (type, node) => {
+        nodes.push({ type, node });
+        if (isProcessing) {
+            return;
+        }
+        isProcessing = true;
+        const promise = async () => {
+            let processedInBatch = 0;
+            while (nodes.length && deps.isWsOpen()) {
+                const { type, node } = nodes.shift();
+                const nodeProcessor = nodeProcessorMap.get(type);
+                if (!nodeProcessor) {
+                    deps.onUnexpectedError(new Error(`unknown offline node type: ${type}`), 'processing offline node');
+                    continue;
+                }
+                await nodeProcessor(node).catch(err => deps.onUnexpectedError(err, `processing offline ${type}`));
+                processedInBatch++;
+                // Yield to event loop after processing a batch
+                // This prevents blocking the event loop for too long when there are many offline nodes
+                if (processedInBatch >= batchSize) {
+                    processedInBatch = 0;
+                    await deps.yieldToEventLoop();
+                }
+            }
+            isProcessing = false;
+        };
+        promise().catch(error => deps.onUnexpectedError(error, 'processing offline nodes'));
+    };
+    return { enqueue };
+}

package/lib/Utils/past-participants.d.ts

@@ -0,0 +1,14 @@
+import type { proto } from '../../WAProto/index.js';
+export interface ProcessedPastParticipant {
+    jid: string;
+    leaveTs?: number;
+    leaveReason?: 'left' | 'removed';
+}
+export interface ProcessedPastParticipants {
+    groupJid: string;
+    participants: ProcessedPastParticipant[];
+}
+/** Process proto.IPastParticipants[] from a history sync payload into a structured list per group. */
+export declare const processPastParticipants: (pastParticipantsList: any[]) => ProcessedPastParticipants[];
+/** Check if a history sync event contains past participants data. */
+export declare const hasPastParticipants: (event: { pastParticipants?: unknown[] }) => boolean;

package/lib/Utils/past-participants.js

@@ -0,0 +1,40 @@
+// JAP@Utils --- past-participants helpers (left/kicked member history).
+// No logic changes — @japofc/baileys's own WAProto already has the
+// `proto.PastParticipant.LeaveReason` enum and `HistorySync.pastParticipants`
+// field this depends on (confirmed present), so this ports as-is.
+//
+// This reads WhatsApp's own server-provided participant-leave history from
+// a history-sync payload (`proto.IPastParticipants[]`) — it's real protocol
+// data, not something reconstructed by listening to live events, so it
+// includes participants who left/were removed *before* this session ever
+// connected (which a live `group-participants.update` listener can never
+// see).
+import { proto } from '../../WAProto/index.js';
+
+/**
+ * Process proto.IPastParticipants[] from a history sync payload.
+ * Returns a structured list per group.
+ */
+export const processPastParticipants = (pastParticipantsList) => {
+    return pastParticipantsList.map((pp) => {
+        const groupJid = pp.groupJid ?? '';
+        const participants = (pp.pastParticipants ?? []).map((p) => ({
+            jid: p.userJid ?? '',
+            leaveTs: p.leaveTs ? Number(p.leaveTs) : undefined,
+            leaveReason: p.leaveReason === proto.PastParticipant.LeaveReason.LEFT
+                ? 'left'
+                : p.leaveReason === proto.PastParticipant.LeaveReason.REMOVED
+                    ? 'removed'
+                    : undefined
+        }));
+        return { groupJid, participants };
+    });
+};
+
+/**
+ * Check if a history sync event contains past participants data.
+ * (pastParticipants field replaces chunkOrder in this patch)
+ */
+export const hasPastParticipants = (event) => {
+    return Array.isArray(event.pastParticipants) && event.pastParticipants.length > 0;
+};