@vanzxysenpai/baileys 0.0.0-stage → 0.0.2

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/pairing-utils.d.ts

@@ -0,0 +1,5 @@
+export function normalizePairingCode(value: any): string;
+export function formatPairingCode(code: any): string;
+export function pairingErrorCode(error: any): any;
+export function isRateLimitError(error: any): boolean;
+export function isCustomPairingError(error: any): boolean;

package/lib/Utils/pairing-utils.js

@@ -0,0 +1,29 @@
+// Vanz@Port (2.0.3) --- from xbibzlibrary/whatsbibz 1.4.0 (BibzWhats/pairing.js: code + error classification) and
+// @japofc/baileys 2.4.1 (qr-render.js: formatPairingCode). Pure helpers only; the donor PairingController (timers/refresh loop) is not ported.
+/** Trim + upper-case a user-supplied custom pairing code. Returns '' unless it is exactly 8 chars of A-Z / 0-9. */
+export const normalizePairingCode = (value) => {
+    const normalized = String(value ?? '').trim().toUpperCase();
+    return /^[A-Z0-9]{8}$/.test(normalized) ? normalized : '';
+};
+/** 'ABCDEFGH' -> 'ABCD-EFGH' for display; anything that is not 8 chars is returned untouched. */
+export const formatPairingCode = (code) => {
+    const c = String(code ?? '');
+    return c.length === 8 ? `${c.slice(0, 4)}-${c.slice(4)}` : c;
+};
+/**
+ * Server error code of a failed pairing request. assertNodeErrorFree Boom errors keep the WA stanza code in `error.data`
+ * (e.g. 400 / 429) while Boom's own statusCode is a generic 500, so both are checked.
+ */
+export const pairingErrorCode = (error) => {
+    const fromData = typeof error?.data === 'number' ? error.data : undefined;
+    const status = error?.output?.statusCode ?? error?.statusCode ?? error?.status;
+    return fromData ?? (status && status !== 500 ? status : undefined);
+};
+export const isRateLimitError = (error) => {
+    const code = pairingErrorCode(error);
+    return code === 428 || code === 429 || /rate[- ]?overlimit|rate.?limit|too many/i.test(String(error?.message || error));
+};
+export const isCustomPairingError = (error) => {
+    const code = pairingErrorCode(error);
+    return code === 422 || /custom pairing code|pairing code.*(invalid|reject|unsupported)|invalid.*pairing/i.test(String(error?.message || error));
+};

package/lib/Utils/passkey.d.ts

@@ -0,0 +1,4 @@
+export function getPasskeyRequestState(node: any): {
+    type: any;
+    hasOptions: any;
+};

package/lib/Utils/passkey.js

@@ -0,0 +1,11 @@
+// Passkey companion-linking notification helper.
+// Adapted from the MIT-licensed WhiskeySockets/Baileys passkey helper (PR #2696).
+const SUPPORTED_PASSKEY_TYPES = new Set(['passkey_prologue_request', 'crsc_continuation']);
+
+export const getPasskeyRequestState = (node) => {
+    const type = node?.attrs?.type;
+    if (!SUPPORTED_PASSKEY_TYPES.has(type)) return undefined;
+    const content = Array.isArray(node?.content) ? node.content : [];
+    const hasOptions = content.some((item) => item && typeof item === 'object' && 'tag' in item);
+    return { type, hasOptions };
+};

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

@@ -0,0 +1,2 @@
+export function processPastParticipants(pastParticipantsList: any): any;
+export function hasPastParticipants(event: any): boolean;

package/lib/Utils/past-participants.js

@@ -0,0 +1,40 @@
+// Ported from @queenanya/baileys `addons/past-participants.ts`.
+// No logic changes — @vanzxysenpai/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;
+};

package/lib/Utils/payment-detection.d.ts

@@ -0,0 +1,40 @@
+/** Verifica se a webMessage contém uma mensagem de pagamento — visível ou stealth. */
+export function hasPaymentMessage(webMessage: any): boolean;
+/**
+ * Lê a marcação (quoted) de uma mensagem de pagamento — inclusive as enviadas
+ * de forma oculta para admins — e devolve o autor original e o id da
+ * mensagem citada. Ignora citações aninhadas para não atribuir o pagamento errado.
+ */
+export function getQuotedPaymentContext(webMessage: any): any;
+/**
+ * Registra o envelope de uma mensagem de grupo. `isPayment` é calculado pelo
+ * chamador (que já roda a detecção de pagamento) para evitar import cíclico.
+ */
+export function recordMessageEnvelope(webMessage: any, isPayment: any): void;
+/**
+ * Decide se uma marcação de pagamento é confiável o bastante para punir o autor.
+ *
+ * - corroborated: o bot recebeu a mensagem original, do MESMO autor, e ela era
+ *   pagamento OU foi indecifrável (consistente com o truque stealth). Pode punir.
+ * - contradicted: o bot recebeu a mensagem, mas de OUTRO autor, ou ela era
+ *   conteúdo legível que não era pagamento. É forja. Nunca punir.
+ * - nenhum dos dois: o bot não viu a mensagem original. Sem corroboração, não pune.
+ */
+export function verifyQuotedAuthor(opts1: { [key: string]: any; 
+    groupJid: any;
+    stanzaId: any;
+    participant: any;
+}): {
+    corroborated: boolean;
+    contradicted: boolean;
+};
+/** Apenas para testes: limpa o registro. */
+export function __clearEnvelopeRegistry(): void;
+/**
+ * Extrai o valor monetário de um requestPaymentMessage / sendPaymentMessage.
+ * Retorna { value, currencyCode } ou null se não encontrar.
+ */
+export function extractPaymentAmount(webMessage: any): {
+    value: number;
+    currencyCode: any;
+};

package/lib/Utils/payment-detection.js

@@ -0,0 +1,213 @@
+// Vanz@Port --- ported from @lpzeravk/baileys 1.0.0 (payment-detection.js). Creator credits untouched. See NOTICE.md.
+/**
+ * Detecção de mensagens de pagamento — incluindo cobranças STEALTH
+ * (ocultas para admins, indecifráveis pelo bot).
+ *
+ * Integrado na @lpzeravk/baileys.
+ */
+
+const MAX_PAYMENT_SCAN_DEPTH = 8;
+
+const PAYMENT_MESSAGE_KEYS = new Set([
+    'paymentInviteMessage',
+    'requestPaymentMessage',
+    'sendPaymentMessage',
+    'cancelPaymentRequestMessage',
+    'declinePaymentRequestMessage',
+]);
+
+function canScanObject(value) {
+    return value && typeof value === 'object' && !(value instanceof ArrayBuffer) && !ArrayBuffer.isView(value);
+}
+
+function hasPaymentMessageKey(value, depth = 0, seenObjects = new WeakSet()) {
+    if (!canScanObject(value) || depth > MAX_PAYMENT_SCAN_DEPTH || seenObjects.has(value)) {
+        return false;
+    }
+
+    seenObjects.add(value);
+
+    for (const [key, childValue] of Object.entries(value)) {
+        if (key === 'quotedMessage') continue;
+
+        if (PAYMENT_MESSAGE_KEYS.has(key) && canScanObject(childValue)) {
+            return true;
+        }
+
+        if (hasPaymentMessageKey(childValue, depth + 1, seenObjects)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/** Verifica se a webMessage contém uma mensagem de pagamento — visível ou stealth. */
+export function hasPaymentMessage(webMessage) {
+    return hasPaymentMessageKey(webMessage?.message);
+}
+
+function findQuotedPaymentContext(value, depth = 0, seenObjects = new WeakSet()) {
+    if (!canScanObject(value) || depth > MAX_PAYMENT_SCAN_DEPTH || seenObjects.has(value)) {
+        return null;
+    }
+
+    seenObjects.add(value);
+
+    const contextInfo = value.contextInfo;
+
+    if (
+        canScanObject(contextInfo) &&
+        typeof contextInfo.participant === 'string' &&
+        canScanObject(contextInfo.quotedMessage) &&
+        hasPaymentMessageKey(contextInfo.quotedMessage)
+    ) {
+        return {
+            participant: contextInfo.participant,
+            stanzaId: typeof contextInfo.stanzaId === 'string' ? contextInfo.stanzaId : undefined,
+        };
+    }
+
+    for (const [key, childValue] of Object.entries(value)) {
+        if (key === 'quotedMessage') continue;
+        const found = findQuotedPaymentContext(childValue, depth + 1, seenObjects);
+        if (found) return found;
+    }
+
+    return null;
+}
+
+/**
+ * Lê a marcação (quoted) de uma mensagem de pagamento — inclusive as enviadas
+ * de forma oculta para admins — e devolve o autor original e o id da
+ * mensagem citada. Ignora citações aninhadas para não atribuir o pagamento errado.
+ */
+export function getQuotedPaymentContext(webMessage) {
+    return findQuotedPaymentContext(webMessage?.message);
+}
+
+// ─── Registro de envelopes (corroboração anti-forja) ──────────────────────
+
+const ENVELOPE_TTL_MS = 60 * 60 * 1000; // 1 hora
+const MAX_ENTRIES_PER_GROUP = 1000;
+
+// registry: Map<groupJid, Map<msgId, {participant, contentState, stealth, ts}>>
+const registry = new Map();
+
+const NON_CONTENT_KEYS = new Set(['messageContextInfo', 'senderKeyDistributionMessage']);
+
+function hasReadableContent(message) {
+    if (!message || typeof message !== 'object') return false;
+    return Object.keys(message).some((key) => !NON_CONTENT_KEYS.has(key));
+}
+
+function pruneGroup(groupMap) {
+    const now = Date.now();
+
+    for (const [id, entry] of groupMap) {
+        if (now - entry.ts > ENVELOPE_TTL_MS) {
+            groupMap.delete(id);
+        }
+    }
+
+    while (groupMap.size > MAX_ENTRIES_PER_GROUP) {
+        const oldestKey = groupMap.keys().next().value;
+        if (oldestKey === undefined) break;
+        groupMap.delete(oldestKey);
+    }
+}
+
+/**
+ * Registra o envelope de uma mensagem de grupo. `isPayment` é calculado pelo
+ * chamador (que já roda a detecção de pagamento) para evitar import cíclico.
+ */
+export function recordMessageEnvelope(webMessage, isPayment) {
+    const remoteJid = webMessage?.key?.remoteJid;
+    const id = webMessage?.key?.id;
+    const participant = webMessage?.key?.participant;
+
+    if (!remoteJid?.endsWith('@g.us') || !id || !participant) return;
+
+    let groupMap = registry.get(remoteJid);
+    if (!groupMap) {
+        groupMap = new Map();
+        registry.set(remoteJid, groupMap);
+    }
+
+    const contentState = isPayment ? 'payment' : hasReadableContent(webMessage?.message) ? 'other' : 'unreadable';
+
+    groupMap.set(id, {
+        participant,
+        contentState,
+        stealth: Boolean(webMessage?.stealthMeta),
+        ts: Date.now(),
+    });
+
+    pruneGroup(groupMap);
+}
+
+/**
+ * Decide se uma marcação de pagamento é confiável o bastante para punir o autor.
+ *
+ * - corroborated: o bot recebeu a mensagem original, do MESMO autor, e ela era
+ *   pagamento OU foi indecifrável (consistente com o truque stealth). Pode punir.
+ * - contradicted: o bot recebeu a mensagem, mas de OUTRO autor, ou ela era
+ *   conteúdo legível que não era pagamento. É forja. Nunca punir.
+ * - nenhum dos dois: o bot não viu a mensagem original. Sem corroboração, não pune.
+ */
+export function verifyQuotedAuthor({ groupJid, stanzaId, participant }) {
+    if (!stanzaId) return { corroborated: false, contradicted: false };
+
+    const entry = registry.get(groupJid)?.get(stanzaId);
+    if (!entry) return { corroborated: false, contradicted: false };
+
+    if (entry.participant !== participant) {
+        return { corroborated: false, contradicted: true };
+    }
+
+    if (entry.contentState === 'other') {
+        return { corroborated: false, contradicted: true };
+    }
+
+    return { corroborated: true, contradicted: false };
+}
+
+/** Apenas para testes: limpa o registro. */
+export function __clearEnvelopeRegistry() {
+    registry.clear();
+}
+
+// ─── Extração de valor monetário ───────────────────────────────────────────
+
+/**
+ * Extrai o valor monetário de um requestPaymentMessage / sendPaymentMessage.
+ * Retorna { value, currencyCode } ou null se não encontrar.
+ */
+export function extractPaymentAmount(webMessage) {
+    try {
+        const msg =
+            webMessage?.message?.requestPaymentMessage ||
+            webMessage?.message?.sendPaymentMessage ||
+            webMessage?.message?.paymentInviteMessage;
+
+        if (!msg) return null;
+
+        if (msg.amount && msg.amount.value !== undefined) {
+            const raw = typeof msg.amount.value === 'object' ? msg.amount.value.low ?? 0 : Number(msg.amount.value);
+            const offset = msg.amount.offset || 100;
+            return {
+                value: raw / offset,
+                currencyCode: msg.amount.currencyCode || msg.currencyCodeIso4217 || '???',
+            };
+        }
+
+        if (msg.amount1000 !== undefined) {
+            const raw = typeof msg.amount1000 === 'object' ? msg.amount1000.low ?? 0 : Number(msg.amount1000);
+            return { value: raw / 1000, currencyCode: msg.currencyCodeIso4217 || '???' };
+        }
+
+        return null;
+    } catch {
+        return null;
+    }
+}

package/lib/Utils/payment-guard.d.ts

@@ -0,0 +1,28 @@
+export function bindPaymentGuard(sock: any, hooks: PaymentGuardHooks): () => void;
+export type PaymentGuardHooks = {
+    /**
+     *   Função que decide se um webMessage (ou webMessage sintético de edição)
+     *   é uma mensagem de pagamento. Normalmente seu `hasPaymentMessage`.
+     */
+    isPaymentMessage: (webMessage: any) => boolean;
+    /**
+     * Chamado para TODA mensagem de grupo vista (payment ou não), inclusive
+     * falhas de decrypt (com `webMessage.message === null`). Normalmente seu
+     * `recordMessageEnvelope`.
+     */
+    recordEnvelope?: (webMessage: any, isPayment: boolean) => void;
+    /**
+     *   Chamado sempre que uma detecção (direta, editada ou indecifrável
+     *   suspeita) acontece.
+     */
+    onDetect: (detection: PaymentDetection) => void;
+    treatDecryptFailureAsSuspicious?: boolean;
+};
+export type PaymentDetection = {
+    type: "direct" | "edited" | "undecryptable";
+    remoteJid: string;
+    participant: string | undefined;
+    messageId: string | undefined;
+    isPreKeyError?: boolean;
+    errorMessage?: string;
+};