@arcaelas/whatsapp 4.4.0 → 5.1.0

package/build/esm/lib/whatsapp/index.js

@@ -8,10 +8,32 @@ import { EventEmitter } from 'node:events';
 import pino from 'pino';
 import * as QRCode from 'qrcode';
 import { chat } from '../../lib/chat/index.js';
-import { contact, contact_name } from '../../lib/contact/index.js';
-import { message } from '../../lib/message/index.js';
-import Feed, { TTL_MS as FEED_TTL_MS } from '../../lib/status/index.js';
+import { contact } from '../../lib/contact/index.js';
+import { bind } from '../../lib/internal.js';
+import { Audio, Document, Event, Image, Location, message, Message, Poll, Sticker, Text, VCard, Video, } from '../../lib/message/index.js';
+import { Feed, TTL_MS as FEED_TTL_MS } from '../../lib/status/index.js';
 import { deserialize, serialize } from '../../lib/store/index.js';
+/** Estados legibles del mensaje que el receipt puede avanzar. / Readable message states a receipt can advance to. */
+const READ = 4;
+const PLAYED = 5;
+/**
+ * Deduce el MIME de un binario por su firma, acotado a lo que WhatsApp acepta en un estado.
+ * Infers a binary's MIME from its signature, limited to what WhatsApp accepts in a status.
+ *
+ * @param data - Binario a inspeccionar / Binary to inspect
+ * @returns MIME reconocido, o null / Recognized MIME, or null
+ */
+function sniff_media(data) {
+    if (data.subarray(0, 3).toString('hex') === 'ffd8ff')
+        return 'image/jpeg';
+    if (data.subarray(0, 8).toString('hex') === '89504e470d0a1a0a')
+        return 'image/png';
+    if (data.subarray(0, 4).toString() === 'RIFF' && data.subarray(8, 12).toString() === 'WEBP')
+        return 'image/webp';
+    if (data.subarray(4, 8).toString() === 'ftyp')
+        return 'video/mp4';
+    return null;
+}
 /**
  * Cliente principal de WhatsApp. No inicia la conexión al instanciar.
  * Main WhatsApp client. Does not connect on instantiation.
@@ -22,54 +44,108 @@ import { deserialize, serialize } from '../../lib/store/index.js';
  * await wa.connect((code) => console.log(code));
  */
 export class WhatsApp {
+    /** @internal Emisor de los eventos del cliente. / Client event emitter. */
+    #event = new EventEmitter();
+    /** @internal Estado compartido con las entidades (socket, resolución de JIDs). / State shared with the entities. */
+    #internals;
+    #phone;
+    #method;
+    #autoclean;
+    #reconnect;
+    #sync;
+    #intentional_close = false;
+    #silent_close = false;
+    #has_connected = false;
+    #retry_timer = null;
+    #retry_count = 0;
+    /**
+     * @internal
+     * Cadena que serializa los handlers de eventos de baileys: dos eventos sobre el mismo
+     * documento ya no se intercalan (lost updates por read-modify-write concurrente).
+     * Chain serializing baileys event handlers: two events over the same document no longer
+     * interleave (lost updates from concurrent read-modify-write).
+     */
+    #chain = Promise.resolve();
     constructor(options) {
-        /** @internal */
-        this._socket = null;
-        this._intentional_close = false;
-        this._has_connected = false;
-        this._retry_timer = null;
-        this._retry_count = 0;
         this.engine = options.engine;
-        this._phone =
-            options.phone !== undefined ? String(options.phone).replace(/\D+/g, '') : undefined;
-        this._autoclean = options.autoclean ?? true;
-        this._sync = options.sync ?? false;
-        this._reconnect = this._parse_reconnect(options.reconnect);
-        this._event = new EventEmitter();
+        this.#phone = options.phone !== undefined ? String(options.phone).replace(/\D+/g, '') : undefined;
+        this.#method = options.method;
+        this.#autoclean = options.autoclean ?? true;
+        this.#sync = options.sync ?? true;
+        this.#reconnect =
+            options.reconnect === false ? { max: 0, interval_ms: 60_000 }
+                : options.reconnect === undefined || options.reconnect === true ? { max: null, interval_ms: 60_000 }
+                    : typeof options.reconnect === 'number' ? { max: options.reconnect, interval_ms: 60_000 }
+                        : { max: options.reconnect.max ?? null, interval_ms: (options.reconnect.interval ?? 60) * 1_000 };
+        this.#internals = { socket: null, resolve_jid: (uid) => this.#resolve_jid(uid) };
+        bind(this, this.#internals);
         this.Contact = contact(this);
         this.Chat = chat(this);
-        this.Message = message(this);
+        this.Message = {
+            get: (cid, mid) => Message.get(this, cid, mid),
+            list: (cid, offset, limit) => Message.list(this, cid, offset, limit),
+            text: (cid, ...rest) => Message.text(this, cid, ...rest),
+            image: (cid, ...rest) => Message.image(this, cid, ...rest),
+            video: (cid, ...rest) => Message.video(this, cid, ...rest),
+            audio: (cid, ...rest) => Message.audio(this, cid, ...rest),
+            location: (cid, ...rest) => Message.location(this, cid, ...rest),
+            poll: (cid, ...rest) => Message.poll(this, cid, ...rest),
+            document: (cid, ...rest) => Message.document(this, cid, ...rest),
+            vcard: (cid, ...rest) => Message.vcard(this, cid, ...rest),
+            event: (cid, ...rest) => Message.event(this, cid, ...rest),
+            react: (cid, mid, emoji) => Message.react(this, cid, mid, emoji),
+            star: (cid, mid, value) => Message.star(this, cid, mid, value),
+            seen: (cid, mid) => Message.seen(this, cid, mid),
+            edit: (cid, mid, caption) => Message.edit(this, cid, mid, caption),
+            forward: (cid, mid, target) => Message.forward(this, cid, mid, target),
+            delete: (cid, mid, all) => Message.delete(this, cid, mid, all),
+            reactions: (cid, mid) => Message.reactions(this, cid, mid),
+            Text, Image, Video, Audio, Sticker, Document, Location, Poll, VCard, Event,
+        };
     }
-    /** @internal */
-    _parse_reconnect(option) {
-        if (option === false) {
-            return { max: 0, interval_ms: 60_000 };
-        }
-        if (option === undefined || option === true) {
-            return { max: null, interval_ms: 60_000 };
-        }
-        if (typeof option === 'number') {
-            return { max: option, interval_ms: 60_000 };
+    /**
+     * Contacto de la cuenta autenticada, o null mientras no hay sesión abierta.
+     * Authenticated account's contact, or null while there is no open session.
+     */
+    get contact() {
+        const user = this.#internals.socket?.user;
+        if (user) {
+            const jid = jidNormalizedUser(user.id);
+            return new this.Contact({ id: jid, phone_number: jid, lid: user.lid ?? null, name: user.name ?? null });
         }
-        return {
-            max: option.max ?? null,
-            interval_ms: (option.interval ?? 60) * 1000,
-        };
+        return null;
+    }
+    /** @internal Encola una tarea en la cadena serial de handlers. / Queues a task on the serial handler chain. */
+    #enqueue(task) {
+        this.#chain = this.#chain.then(task).catch(() => { });
+    }
+    /**
+     * Emite un evento del cliente. Lo usan las entidades de la librería para propagar los
+     * cambios que provocan; el consumidor puede emitir los suyos para pruebas.
+     * Emits a client event. Library entities use it to propagate the changes they cause;
+     * consumers may emit their own for testing.
+     *
+     * @param event - Nombre del evento / Event name
+     * @param args - Argumentos del evento / Event arguments
+     * @returns true si había listeners / true when listeners were present
+     */
+    emit(event, ...args) {
+        return this.#event.emit(event, ...args);
     }
     /**
      * Registra un listener de evento. Retorna función para desuscribirse.
      * Registers an event listener. Returns an unsubscribe function.
      */
     on(event, handler) {
-        this._event.on(event, handler);
-        return () => { this._event.off(event, handler); };
+        this.#event.on(event, handler);
+        return () => { this.#event.off(event, handler); };
     }
     /**
      * Quita un listener previamente registrado.
      * Removes a previously registered listener.
      */
     off(event, handler) {
-        this._event.off(event, handler);
+        this.#event.off(event, handler);
         return this;
     }
     /**
@@ -77,15 +153,17 @@ export class WhatsApp {
      * Registers a one-shot listener. Returns an unsubscribe function.
      */
     once(event, handler) {
-        this._event.once(event, handler);
-        return () => { this._event.off(event, handler); };
+        this.#event.once(event, handler);
+        return () => { this.#event.off(event, handler); };
     }
     /**
      * @internal
-     * Normaliza cualquier identificador (JID, LID, número, etc.) a JID canónico.
-     * Uso interno de la librería — no forma parte de la API pública.
+     * Normaliza cualquier identificador (JID, LID, número, etc.) a JID canónico. Las
+     * entidades lo alcanzan por el canal interno, no por la instancia.
+     * Normalizes any identifier (JID, LID, number…) into a canonical JID. Entities reach it
+     * through the internal channel, not through the instance.
      */
-    async _resolve_jid(uid) {
+    async #resolve_jid(uid) {
         let result = null;
         if (uid.endsWith('@g.us') || uid.endsWith('@s.whatsapp.net')) {
             result = uid;
@@ -100,6 +178,18 @@ export class WhatsApp {
                 if (reverse != null) {
                     result = `${reverse}@s.whatsapp.net`;
                 }
+                else {
+                    // El store local puede no tener el mapping (sesión sin upsert del contacto);
+                    // baileys lo conoce vía su lidMapping. Sin esto, un chat referenciado por @lid
+                    // (p.ej. el pollCreationMessageKey de un voto entrante) no resuelve al PN donde
+                    // realmente está guardado, y el mensaje/poll no se encuentra.
+                    const pn = await this.#internals.socket?.signalRepository?.lidMapping?.getPNForLID(uid).catch(() => null);
+                    if (pn) {
+                        // getPNForLID puede traer sufijo de dispositivo (`:0`); se normaliza para
+                        // que el JID coincida con el que usa el store (sin device).
+                        result = jidNormalizedUser(pn.includes('@') ? pn : `${pn}@s.whatsapp.net`);
+                    }
+                }
             }
         }
         else {
@@ -118,16 +208,20 @@ export class WhatsApp {
      * Resolves once the session is synced; retries on non-loggedOut disconnects.
      */
     async connect(callback) {
+        if (this.#internals.socket) {
+            await this.disconnect({ silent: true });
+        }
         const { version } = await fetchLatestBaileysVersion();
-        this._intentional_close = false;
-        this._has_connected = false;
+        this.#intentional_close = false;
+        this.#silent_close = false;
+        this.#has_connected = false;
         return new Promise((resolve, reject) => {
             const start = async () => {
                 // Re-lee creds en cada start() para que limpiezas del engine tomen efecto
                 // en reintentos (permite al consumer forzar nueva sesión borrando /session/creds).
                 const stored = await this.engine.get('/session/creds');
                 const creds = deserialize(stored) ?? initAuthCreds();
-                this._socket = makeWASocket({
+                this.#internals.socket = makeWASocket({
                     version,
                     auth: {
                         creds,
@@ -154,17 +248,19 @@ export class WhatsApp {
                     },
                     browser: Browsers.windows('Chrome'),
                     logger: pino({ level: 'silent' }),
-                    syncFullHistory: this._sync,
-                    // rc13 cambió el default de `shouldSyncHistoryMessage` a
-                    // `({ syncType }) => syncType !== FULL` (independiente de `syncFullHistory`).
-                    // Replicamos el comportamiento previo (rc.9), donde el sync de historial
-                    // dependía únicamente de `sync`.
-                    // rc13 changed the `shouldSyncHistoryMessage` default; we keep the rc.9
-                    // behavior where history sync depended solely on `sync`.
-                    shouldSyncHistoryMessage: () => this._sync,
+                    syncFullHistory: this.#sync,
+                    // Los syncs no-FULL cargan las LID mappings y los tctokens (trusted-contact
+                    // tokens) que rc13 exige para enviar: apagarlos todos con `() => this.#sync`
+                    // deja la sesión sin tctoken y el server rechaza los mensajes con
+                    // "error 463: account restricted or missing tctoken". Por eso se procesan
+                    // siempre los no-FULL; `sync` solo decide si además se trae el historial FULL.
+                    // Non-FULL syncs carry the LID mappings and tctokens rc13 requires to send;
+                    // disabling them all made the server reject messages with error 463. We always
+                    // process non-FULL; `sync` only gates whether FULL history is pulled too.
+                    shouldSyncHistoryMessage: ({ syncType }) => this.#sync || syncType !== proto.HistorySync.HistorySyncType.FULL,
                     markOnlineOnConnect: false,
                 });
-                const socket = this._socket;
+                const socket = this.#internals.socket;
                 socket.ev.on('creds.update', () => this.engine.set('/session/creds', serialize(creds)));
                 socket.ev.on('connection.update', async (update) => {
                     const { connection, lastDisconnect, qr } = update;
@@ -172,21 +268,25 @@ export class WhatsApp {
                         // Baileys refresca QR periódicamente (~20s). Emitimos nuevo pair
                         // code / QR en cada refresh para que el usuario pueda renovar si
                         // el anterior expiró.
-                        if (this._phone) {
-                            await callback(await socket.requestPairingCode(this._phone));
+                        // El PIN necesita número: sin `phone` la vinculación es siempre QR, y
+                        // con `phone` manda `method` (OTP por defecto).
+                        // A PIN requires a number: without `phone` linking is always QR, and with
+                        // `phone` the `method` option decides (OTP by default).
+                        if (this.#phone && (this.#method ?? 'otp') === 'otp') {
+                            await callback(await socket.requestPairingCode(this.#phone));
                         }
                         else {
                             await callback(await QRCode.toBuffer(qr, { type: 'png', margin: 2 }));
                         }
                     }
                     if (connection === 'open') {
-                        this._has_connected = true;
-                        this._retry_count = 0;
-                        this._event.emit('connected', this);
+                        this.#has_connected = true;
+                        this.#retry_count = 0;
+                        this.emit('connected', this);
                         resolve();
                     }
                     else if (connection === 'close') {
-                        this._socket = null;
+                        this.#internals.socket = null;
                         const status_code = lastDisconnect?.error?.output?.statusCode;
                         // `restartRequired` (515) es una reconexión exigida por el protocolo
                         // tras el sync inicial — no es un disconnect "real".
@@ -194,35 +294,37 @@ export class WhatsApp {
                         // Limpieza del engine ANTES de emitir `disconnected` para que los
                         // listeners vean el estado final (engine vaciado o creds borradas).
                         if (status_code === DisconnectReason.loggedOut) {
-                            if (this._autoclean) {
+                            if (this.#autoclean) {
                                 await this.engine.clear();
                             }
                             else {
                                 await this.engine.unset('/session/creds');
                             }
                         }
-                        if (this._has_connected && !is_transient) {
-                            this._event.emit('disconnected', this);
+                        // `disconnect({ silent: true })` calla el evento de este cierre concreto.
+                        // `disconnect({ silent: true })` mutes this specific close's event.
+                        if (this.#has_connected && !is_transient && !this.#silent_close) {
+                            this.emit('disconnected', this);
                         }
-                        if (!this._intentional_close) {
+                        if (!this.#intentional_close) {
                             if (status_code === DisconnectReason.loggedOut) {
                                 reject(new Error('Logged out'));
                             }
                             else {
-                                const max = this._reconnect.max;
+                                const max = this.#reconnect.max;
                                 // Transient closes (restartRequired) son parte del protocolo,
                                 // no cuentan contra el límite de reintentos por fallo.
-                                const exhausted = !is_transient && max !== null && this._retry_count >= max;
+                                const exhausted = !is_transient && max !== null && this.#retry_count >= max;
                                 if (exhausted) {
                                     reject(new Error(`Reconnect attempts exhausted (${max})`));
                                 }
                                 else {
                                     if (!is_transient) {
-                                        this._retry_count++;
+                                        this.#retry_count++;
                                     }
-                                    const delay = is_transient ? 0 : this._reconnect.interval_ms;
-                                    this._retry_timer = setTimeout(() => {
-                                        this._retry_timer = null;
+                                    const delay = is_transient ? 0 : this.#reconnect.interval_ms;
+                                    this.#retry_timer = setTimeout(() => {
+                                        this.#retry_timer = null;
                                         start().catch(reject);
                                     }, delay);
                                 }
@@ -230,24 +332,119 @@ export class WhatsApp {
                         }
                     }
                 });
-                this._attach_business_handlers(socket);
+                this.#attach_business_handlers(socket);
             };
             start().catch(reject);
         });
     }
+    /**
+     * Actualiza el perfil de la cuenta en WhatsApp: nombre público, bio y/o foto. Sólo se
+     * envía lo que llega en el parche; `photo: null` elimina la foto actual.
+     * Updates the account profile on WhatsApp: public name, bio and/or picture. Only the
+     * given fields are sent; `photo: null` removes the current picture.
+     *
+     * @param patch - Campos a actualizar / Fields to update
+     * @returns true si todo lo pedido se envió / true when everything requested was sent
+     * @throws ERR_PROFILE_PICTURE_LIB si falta `sharp` o `jimp` para procesar la foto / when `sharp` or `jimp` is missing to process the picture
+     */
+    async profile(patch) {
+        const socket = this.#internals.socket;
+        let ok = false;
+        if (socket) {
+            const self = jidNormalizedUser(socket.user?.id ?? '');
+            if (patch.name !== undefined) {
+                await socket.updateProfileName(patch.name);
+            }
+            if (patch.content !== undefined) {
+                await socket.updateProfileStatus(patch.content);
+            }
+            if (patch.photo === null) {
+                await socket.removeProfilePicture(self);
+            }
+            else if (patch.photo !== undefined) {
+                // baileys redimensiona la foto con `sharp` o `jimp`; ninguna es dependencia
+                // nuestra, así que su ausencia se traduce a un error accionable.
+                // baileys resizes the picture with `sharp` or `jimp`; neither is a dependency
+                // of ours, so their absence is translated into an actionable error.
+                await socket
+                    .updateProfilePicture(self, typeof patch.photo === 'string' ? { url: patch.photo } : patch.photo)
+                    .catch((error) => {
+                    if (/image processing library/i.test(error.message)) {
+                        throw new Error('ERR_PROFILE_PICTURE_LIB');
+                    }
+                    throw error;
+                });
+            }
+            ok = true;
+        }
+        return ok;
+    }
+    /**
+     * Publica un estado (status broadcast). Con sólo `caption` publica texto; con `content`
+     * publica imagen o video (el tipo se deduce del binario) usando `caption` como pie.
+     * `contacts` es la audiencia: WhatsApp no reparte el estado a quien no esté en la lista.
+     * Publishes a status broadcast. With only `caption` it posts text; with `content` it
+     * posts an image or video (type inferred from the binary) using `caption` as its footer.
+     * `contacts` is the audience: WhatsApp does not deliver the status to anyone outside it.
+     *
+     * @param post - Contenido, pie y audiencia / Content, caption and audience
+     * @returns Publicación creada, o null si no hay sesión / Created post, or null without a session
+     * @throws ERR_FEED_EMPTY sin `content` ni `caption` / when neither `content` nor `caption` is given
+     * @throws ERR_FEED_MEDIA si el binario no es imagen ni video / when the binary is neither image nor video
+     */
+    async feed(post) {
+        const socket = this.#internals.socket;
+        let result = null;
+        if (socket) {
+            const audience = (await Promise.all(post.contacts.map((uid) => this.#resolve_jid(String(uid))))).filter((jid) => jid !== null);
+            const mime = post.content ? sniff_media(post.content) : null;
+            if (post.content && !mime) {
+                throw new Error('ERR_FEED_MEDIA');
+            }
+            if (!post.content && !post.caption) {
+                throw new Error('ERR_FEED_EMPTY');
+            }
+            const kind = mime?.startsWith('video/') ? 'video' : mime ? 'image' : 'text';
+            const sent = await socket.sendMessage('status@broadcast', (post.content
+                ? { [kind]: post.content, caption: post.caption }
+                : { text: post.caption }), { statusJidList: audience });
+            if (sent?.key?.id) {
+                const created_at = (Number(sent.messageTimestamp) || Math.floor(Date.now() / 1_000)) * 1_000;
+                const doc = {
+                    id: sent.key.id,
+                    author_jid: jidNormalizedUser(socket.user?.id ?? ''),
+                    type: kind,
+                    caption: post.caption ?? '',
+                    mime: mime ?? 'text/plain',
+                    created_at,
+                    expires_at: created_at + FEED_TTL_MS,
+                    viewed: true,
+                    raw: sent,
+                };
+                await this.engine.set(`/status/${doc.id}`, serialize(doc), created_at);
+                if (post.content) {
+                    await this.engine.set(`/status/${doc.id}/content`, serialize({ data: post.content.toString('base64') }));
+                }
+                result = new Feed(this, doc);
+                this.emit('feed:created', result, this);
+            }
+        }
+        return result;
+    }
     /**
      * Cierra la conexión. Con `destroy: true` vacía el engine completo.
      * Closes the connection. With `destroy: true` clears the engine entirely.
      */
     async disconnect(options = {}) {
-        this._intentional_close = true;
+        this.#intentional_close = true;
+        this.#silent_close = options.silent === true;
         // Cancela cualquier retry programado por un close anterior, para no resucitar
         // el socket después de una desconexión manual.
-        if (this._retry_timer) {
-            clearTimeout(this._retry_timer);
-            this._retry_timer = null;
+        if (this.#retry_timer) {
+            clearTimeout(this.#retry_timer);
+            this.#retry_timer = null;
         }
-        if (this._socket) {
+        if (this.#internals.socket) {
             try {
                 // Pasa un error Boom-like con statusCode=connectionClosed (428) para que
                 // `lastDisconnect.error.output.statusCode` quede explícito en el close
@@ -255,17 +452,16 @@ export class WhatsApp {
                 const intentional = Object.assign(new Error('intentional close'), {
                     output: { statusCode: DisconnectReason.connectionClosed },
                 });
-                await this._socket.end(intentional);
+                await this.#internals.socket.end(intentional);
             }
             catch {
                 /* socket may already be closed */
             }
-            this._socket = null;
+            this.#internals.socket = null;
         }
         if (options.destroy) {
             await this.engine.clear();
         }
-        void options.silent;
     }
     /**
      * Conecta los handlers de eventos de baileys: contactos, chats y mensajes.
@@ -273,43 +469,45 @@ export class WhatsApp {
      *
      * @internal
      */
-    _attach_business_handlers(socket) {
-        socket.ev.on('messaging-history.set', async ({ chats, contacts, messages }) => {
-            await this._handle_contacts_upsert(contacts);
-            await this._handle_chats_upsert(chats);
-            await this._handle_messages_upsert(messages);
+    #attach_business_handlers(socket) {
+        socket.ev.on('messaging-history.set', ({ chats, contacts, messages }) => {
+            this.#enqueue(async () => {
+                await this.#handle_contacts_upsert(contacts);
+                await this.#handle_chats_upsert(chats);
+                await this.#handle_messages_upsert(messages);
+            });
         });
         socket.ev.on('contacts.upsert', (contacts) => {
-            void this._handle_contacts_upsert(contacts);
+            this.#enqueue(() => this.#handle_contacts_upsert(contacts));
         });
         socket.ev.on('contacts.update', (contacts) => {
-            void this._handle_contacts_update(contacts);
+            this.#enqueue(() => this.#handle_contacts_update(contacts));
         });
         socket.ev.on('lid-mapping.update', ({ lid, pn }) => {
-            void this._handle_lid_mapping(lid, pn);
+            this.#enqueue(() => this.#handle_lid_mapping(lid, pn));
         });
         socket.ev.on('chats.upsert', (chats) => {
-            void this._handle_chats_upsert(chats);
+            this.#enqueue(() => this.#handle_chats_upsert(chats));
         });
         socket.ev.on('chats.update', (chats) => {
-            void this._handle_chats_update(chats);
+            this.#enqueue(() => this.#handle_chats_update(chats));
         });
         socket.ev.on('chats.delete', (ids) => {
-            void this._handle_chats_delete(ids);
+            this.#enqueue(() => this.#handle_chats_delete(ids));
         });
         socket.ev.on('messages.upsert', ({ messages }) => {
-            void this._handle_messages_upsert(messages);
+            this.#enqueue(() => this.#handle_messages_upsert(messages));
         });
         socket.ev.on('messages.update', (updates) => {
-            void this._handle_messages_update(updates);
+            this.#enqueue(() => this.#handle_messages_update(updates));
         });
         socket.ev.on('message-receipt.update', (updates) => {
-            void this._handle_message_receipt(updates);
+            this.#enqueue(() => this.#handle_message_receipt(updates));
         });
         // Las reacciones llegan duplicadas por `messages.reaction` Y `messages.upsert`
         // (como `reactionMessage`). Se usa solo `messages.upsert` para evitar el doble disparo.
         // socket.ev.on('messages.reaction', (reactions) => {
-        //     void this._handle_messages_reaction(reactions);
+        //     void this.#handle_messages_reaction(reactions);
         // });
     }
     /**
@@ -319,23 +517,23 @@ export class WhatsApp {
      * @param raw - Documento del contacto a persistir / Contact document to persist
      * @internal
      */
-    async _persist_contact(raw) {
+    async #persist_contact(raw) {
         const existing = await this.engine.get(`/contact/${raw.id}`);
         await this.engine.set(`/contact/${raw.id}`, serialize(raw));
         if (raw.lid) {
             await this.engine.set(`/lid/${raw.lid}`, serialize(raw.id));
         }
         if (existing === null) {
+            const person = new this.Contact(raw);
             const cached_chat = deserialize(await this.engine.get(`/chat/${raw.id}`));
-            const chat_instance = new this.Chat(cached_chat ?? { id: raw.id, name: contact_name(raw) });
-            this._event.emit('contact:created', new this.Contact(raw, chat_instance), chat_instance, this);
+            this.emit('contact:created', person, new this.Chat(cached_chat ?? { id: raw.id, name: person.name }), this);
         }
     }
     /** @internal */
-    async _handle_contacts_upsert(contacts) {
+    async #handle_contacts_upsert(contacts) {
         for (const c of contacts) {
             if (c.id) {
-                await this._persist_contact({
+                await this.#persist_contact({
                     id: c.id,
                     lid: c.lid ?? null,
                     name: c.name ?? null,
@@ -348,7 +546,7 @@ export class WhatsApp {
         }
     }
     /** @internal */
-    async _handle_contacts_update(contacts) {
+    async #handle_contacts_update(contacts) {
         for (const c of contacts) {
             if (c.id) {
                 const current = deserialize(await this.engine.get(`/contact/${c.id}`));
@@ -366,21 +564,21 @@ export class WhatsApp {
                         if (patch.lid) {
                             await this.engine.set(`/lid/${patch.lid}`, serialize(c.id));
                         }
+                        const person = new this.Contact(merged);
                         const cached_chat = deserialize(await this.engine.get(`/chat/${c.id}`));
-                        const chat_instance = new this.Chat(cached_chat ?? { id: c.id, name: contact_name(merged) });
-                        this._event.emit('contact:updated', new this.Contact(merged, chat_instance), chat_instance, this);
+                        this.emit('contact:updated', person, new this.Chat(cached_chat ?? { id: c.id, name: person.name }), this);
                     }
                 }
             }
         }
     }
     /** @internal */
-    async _handle_lid_mapping(lid, pn) {
+    async #handle_lid_mapping(lid, pn) {
         await this.engine.set(`/lid/${lid}`, serialize(pn));
         await this.engine.set(`/lid/${pn}`, serialize(lid));
     }
     /** @internal */
-    async _handle_chats_upsert(chats) {
+    async #handle_chats_upsert(chats) {
         for (const ch of chats) {
             if (ch.id) {
                 const current = deserialize(await this.engine.get(`/chat/${ch.id}`));
@@ -390,21 +588,19 @@ export class WhatsApp {
                     archived: ch.archived ?? null,
                     pinned: ch.pinned ?? null,
                     mute_end_time: ch.muteEndTime != null ? Number(ch.muteEndTime) : null,
-                    unread_count: ch.unreadCount ?? null,
-                    read_only: ch.readOnly ?? null,
                 };
                 if (ch.name) {
                     raw.name = ch.name;
                 }
                 await this.engine.set(`/chat/${ch.id}`, serialize(raw));
                 if (current === null) {
-                    this._event.emit('chat:created', new this.Chat(raw), this);
+                    this.emit('chat:created', new this.Chat(raw), this);
                 }
             }
         }
     }
     /** @internal */
-    async _handle_chats_update(chats) {
+    async #handle_chats_update(chats) {
         for (const ch of chats) {
             if (ch.id && ch.id !== 'status@broadcast') {
                 const current = deserialize(await this.engine.get(`/chat/${ch.id}`)) ?? {
@@ -427,36 +623,33 @@ export class WhatsApp {
                 if (mute_changed) {
                     patch.mute_end_time = ch.muteEndTime != null ? Number(ch.muteEndTime) : null;
                 }
-                if (ch.unreadCount != null) {
-                    patch.unread_count = ch.unreadCount;
-                }
                 if (Object.keys(patch).length > 0) {
                     const merged = { ...current, ...patch };
                     await this.engine.set(`/chat/${ch.id}`, serialize(merged));
                     if (pinned_changed) {
-                        this._event.emit(ch.pinned != null ? 'chat:pinned' : 'chat:unpinned', new this.Chat(merged), this);
+                        this.emit(ch.pinned != null ? 'chat:pinned' : 'chat:unpinned', new this.Chat(merged), this);
                     }
                     if (archived_changed) {
-                        this._event.emit(ch.archived ? 'chat:archived' : 'chat:unarchived', new this.Chat(merged), this);
+                        this.emit(ch.archived ? 'chat:archived' : 'chat:unarchived', new this.Chat(merged), this);
                     }
                     if (mute_changed) {
                         const is_muted = patch.mute_end_time != null && patch.mute_end_time > Date.now();
-                        this._event.emit(is_muted ? 'chat:muted' : 'chat:unmuted', new this.Chat(merged), this);
+                        this.emit(is_muted ? 'chat:muted' : 'chat:unmuted', new this.Chat(merged), this);
                     }
                 }
             }
         }
     }
     /** @internal */
-    async _handle_chats_delete(ids) {
+    async #handle_chats_delete(ids) {
         for (const cid of ids) {
             const raw = deserialize(await this.engine.get(`/chat/${cid}`)) ?? { id: cid };
             await this.engine.unset(`/chat/${cid}`);
-            this._event.emit('chat:deleted', new this.Chat(raw), this);
+            this.emit('chat:deleted', new this.Chat(raw), this);
         }
     }
     /** @internal */
-    async _handle_message_receipt(updates) {
+    async #handle_message_receipt(updates) {
         for (const { key, receipt } of updates) {
             // Receipt sobre status@broadcast → marca el feed como visto y emite feed:updated.
             // Receipt on status@broadcast → marks feed viewed and emits feed:updated.
@@ -465,21 +658,27 @@ export class WhatsApp {
                 if (feed_raw && !feed_raw.viewed) {
                     feed_raw.viewed = true;
                     await this.engine.set(`/status/${key.id}`, serialize(feed_raw));
-                    this._event.emit('feed:updated', new Feed({ wa: this, doc: feed_raw }), this);
+                    this.emit('feed:updated', new Feed(this, feed_raw), this);
                 }
                 continue;
             }
             if (key.remoteJid && key.id && (receipt.readTimestamp != null || receipt.playedTimestamp != null)) {
                 const doc = deserialize(await this.engine.get(`/chat/${key.remoteJid}/message/${key.id}`));
                 if (doc) {
-                    const msg_instance = await this.Message.build_instance(doc);
-                    this._event.emit('message:seen', msg_instance, await msg_instance.chat(), this);
+                    const next = receipt.playedTimestamp != null ? PLAYED : READ;
+                    if (doc.status < next) {
+                        doc.status = next;
+                        doc.raw.status = next;
+                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                    }
+                    const msg_instance = message(this, doc);
+                    this.emit('message:seen', msg_instance, await msg_instance.chat(), this);
                 }
             }
         }
     }
     /** @internal */
-    async _handle_messages_upsert(messages) {
+    async #handle_messages_upsert(messages) {
         for (const msg of messages) {
             if (msg.key?.remoteJid && msg.key.id) {
                 const cid = msg.key.remoteJidAlt ?? msg.key.remoteJid;
@@ -490,9 +689,13 @@ export class WhatsApp {
                     // Single channel for reactions: handled here; `messages.reaction` is disabled.
                     const reaction = msg.message?.reactionMessage;
                     if (reaction?.key?.id && reaction.key.remoteJid) {
-                        const target_cid = (await this._resolve_jid(reaction.key.remoteJid)) ?? reaction.key.remoteJid;
-                        await this._handle_messages_reaction([{
-                                key: { remoteJid: target_cid, id: reaction.key.id },
+                        const target_cid = (await this.#resolve_jid(reaction.key.remoteJid)) ?? reaction.key.remoteJid;
+                        await this.#handle_messages_reaction([{
+                                key: {
+                                    remoteJid: target_cid,
+                                    id: reaction.key.id,
+                                    participant: msg.key.fromMe ? (this.#internals.socket?.user?.id ?? null) : (msg.key.participant ?? cid),
+                                },
                                 reaction: { text: reaction.text ?? '' },
                             }]);
                     }
@@ -508,7 +711,7 @@ export class WhatsApp {
                             const feed_raw = deserialize(await this.engine.get(`/status/${protocol.key.id}`));
                             if (feed_raw) {
                                 await this.engine.unset(`/status/${protocol.key.id}`);
-                                this._event.emit('feed:deleted', new Feed({ wa: this, doc: feed_raw }), this);
+                                this.emit('feed:deleted', new Feed(this, feed_raw), this);
                             }
                         }
                         continue;
@@ -556,7 +759,7 @@ export class WhatsApp {
                     if (feed_type === 'text') {
                         content_buf = Buffer.from(caption, 'utf-8');
                     }
-                    else if (this._socket) {
+                    else if (this.#internals.socket) {
                         try {
                             const buf = await downloadMediaMessage(msg, 'buffer', {});
                             if (Buffer.isBuffer(buf)) {
@@ -571,7 +774,7 @@ export class WhatsApp {
                     if (content_buf.length > 0) {
                         await this.engine.set(`/status/${mid}/content`, serialize({ data: content_buf.toString('base64') }));
                     }
-                    this._event.emit('feed:created', new Feed({ wa: this, doc: feed_raw }), this);
+                    this.emit('feed:created', new Feed(this, feed_raw), this);
                     continue;
                 }
                 if (content_type === 'pollUpdateMessage') {
@@ -581,7 +784,7 @@ export class WhatsApp {
                         creation_key.remoteJid &&
                         update?.vote?.encPayload &&
                         update.vote.encIv) {
-                        const resolved_cid = (await this._resolve_jid(creation_key.remoteJid)) ?? creation_key.remoteJid;
+                        const resolved_cid = (await this.#resolve_jid(creation_key.remoteJid)) ?? creation_key.remoteJid;
                         const target_mid = creation_key.id;
                         const poll_doc = deserialize(await this.engine.get(`/chat/${resolved_cid}/message/${target_mid}`));
                         const secret_raw = poll_doc?.raw.message?.messageContextInfo?.messageSecret;
@@ -596,23 +799,15 @@ export class WhatsApp {
                                 // Own HMAC identity depends on chat addressing (LID on @lid, PN on
                                 // @s.whatsapp.net), so fromMe positions try both candidates:
                                 // AES-GCM authenticates, a wrong key throws and the next is tried.
-                                const self_id = this._socket?.user?.id ?? '';
-                                const self_lid = this._socket?.user?.lid ?? '';
+                                const self_id = this.#internals.socket?.user?.id ?? '';
+                                const self_lid = this.#internals.socket?.user?.lid ?? '';
                                 const selves = [...new Set([self_lid, self_id].filter(Boolean))];
-                                const foreign_voter = msg.key.remoteJid?.endsWith('@lid')
-                                    ? msg.key.remoteJid
-                                    : msg.key.participant ||
-                                        msg.key.remoteJidAlt ||
-                                        msg.key.remoteJid ||
-                                        '';
-                                const foreign_creator = poll_key.remoteJid?.endsWith('@lid')
-                                    ? poll_key.remoteJid
-                                    : poll_key.participant ||
-                                        poll_key.remoteJidAlt ||
-                                        poll_key.remoteJid ||
-                                        '';
-                                const voters = msg.key.fromMe ? selves : [foreign_voter];
-                                const creators = poll_key.fromMe ? selves : [foreign_creator];
+                                // Candidatos foráneos: todas las formas de identidad del key (LID,
+                                // participant, alt, remoteJid); se prueban todas porque el addressing
+                                // del stanza varía (LID vs PN) según la migración del contacto.
+                                const foreign_of = (k) => [...new Set([k.remoteJid, k.participant, k.remoteJidAlt, k.remoteJid].filter((x) => Boolean(x)))];
+                                const voters = msg.key.fromMe ? selves : foreign_of(msg.key);
+                                const creators = poll_key.fromMe ? selves : foreign_of(poll_key);
                                 let decrypted = null;
                                 for (const voter of voters) {
                                     for (const creator of creators) {
@@ -639,9 +834,9 @@ export class WhatsApp {
                                         vote: decrypted,
                                         senderTimestampMs: Number(msg.messageTimestamp) || Date.now(),
                                     });
-                                    await this.engine.set(`/chat/${resolved_cid}/message/${target_mid}`, serialize(poll_doc));
-                                    const msg_instance = await this.Message.build_instance(poll_doc);
-                                    this._event.emit('message:updated', msg_instance, await msg_instance.chat(), this);
+                                    await this.engine.set(`/chat/${resolved_cid}/message/${target_mid}`, serialize(poll_doc), poll_doc.created_at);
+                                    const msg_instance = message(this, poll_doc);
+                                    this.emit('message:updated', msg_instance, await msg_instance.chat(), this);
                                 }
                             }
                             catch {
@@ -662,28 +857,49 @@ export class WhatsApp {
                             doc) {
                             doc.raw.message = protocol.editedMessage;
                             doc.edited = true;
-                            doc.caption = this.Message.build_message_doc(doc.raw, this._socket?.user?.id, true).caption;
-                            await this.engine.set(`/chat/${target_cid}/message/${target_mid}`, serialize(doc));
-                            const msg_instance = await this.Message.build_instance(doc);
-                            this._event.emit('message:updated', msg_instance, await msg_instance.chat(), this);
+                            doc.caption = message(this, doc.raw).caption;
+                            await this.engine.set(`/chat/${target_cid}/message/${target_mid}`, serialize(doc), doc.created_at);
+                            const msg_instance = message(this, doc);
+                            this.emit('message:updated', msg_instance, await msg_instance.chat(), this);
                         }
                         else if (protocol.type === proto.Message.ProtocolMessage.Type.REVOKE) {
                             await this.engine.unset(`/chat/${target_cid}/message/${target_mid}`);
                             if (doc) {
-                                const msg_instance = await this.Message.build_instance(doc);
-                                this._event.emit('message:deleted', msg_instance, await msg_instance.chat(), this);
+                                const msg_instance = message(this, doc);
+                                this.emit('message:deleted', msg_instance, await msg_instance.chat(), this);
                             }
                         }
                     }
                     continue;
                 }
-                const doc = this.Message.build_message_doc(msg, this._socket?.user?.id);
+                const doc = message(this, msg)._raw;
+                // Cada reconexión re-entrega el historial completo: reescribir documentos
+                // idénticos contamina la cronología, re-descarga la media y spamea eventos,
+                // así que un doc ya persistido sin cambios visibles se salta entero.
+                // Every reconnect re-delivers the full history: rewriting identical documents
+                // pollutes chronology, re-downloads media and spams events, so an already
+                // persisted doc without visible changes is skipped entirely.
+                const existing_doc = deserialize(await this.engine.get(`/chat/${cid}/message/${mid}`));
+                if (existing_doc) {
+                    if (typeof existing_doc.multiple === 'boolean') {
+                        doc.multiple = existing_doc.multiple;
+                    }
+                    if (existing_doc.reactions) {
+                        doc.reactions = existing_doc.reactions;
+                    }
+                    if (existing_doc.status >= doc.status &&
+                        existing_doc.caption === doc.caption &&
+                        existing_doc.edited === doc.edited &&
+                        existing_doc.starred === doc.starred) {
+                        continue;
+                    }
+                }
                 // Autocreación de contacto/chat desde pushName cuando baileys no emite upsert previo
-                if (!doc.me) {
+                if (!existing_doc && !doc.me) {
                     const push_name = msg.pushName ?? null;
                     const is_group = cid.endsWith('@g.us');
                     if (doc.author && !(await this.engine.get(`/contact/${doc.author}`))) {
-                        await this._persist_contact({
+                        await this.#persist_contact({
                             id: doc.author,
                             lid: msg.key.remoteJid?.endsWith('@lid') ? msg.key.remoteJid : null,
                             name: null,
@@ -699,20 +915,17 @@ export class WhatsApp {
                             name: is_group ? null : push_name,
                         };
                         await this.engine.set(`/chat/${cid}`, serialize(chat_raw));
-                        this._event.emit('chat:created', new this.Chat(chat_raw), this);
+                        this.emit('chat:created', new this.Chat(chat_raw), this);
                     }
                 }
-                // Preservar flags explícitos persistidos por el send (ej: `multiple` en polls
-                // auto-emitidos, donde el echo de WhatsApp pierde el discriminador del proto).
-                // Preserve send-time flags (e.g. `multiple` on own polls, since WhatsApp drops
-                // the proto discriminator on echo).
-                const existing_doc = deserialize(await this.engine.get(`/chat/${cid}/message/${mid}`));
-                if (existing_doc && typeof existing_doc.multiple === 'boolean') {
-                    doc.multiple = existing_doc.multiple;
-                }
-                await this.engine.set(`/chat/${cid}/message/${mid}`, serialize(doc));
+                await this.engine.set(`/chat/${cid}/message/${mid}`, serialize(doc), doc.created_at);
+                // El binario solo se materializa en la primera entrega; en re-syncs ya vive en el engine.
+                // The binary is only materialized on first delivery; on re-syncs it already lives in the engine.
                 let content_buf = Buffer.alloc(0);
-                if (doc.type === 'text') {
+                if (existing_doc) {
+                    /* ya materializado / already materialized */
+                }
+                else if (doc.type === 'text') {
                     content_buf = Buffer.from(doc.caption, 'utf-8');
                 }
                 else if (doc.type === 'location') {
@@ -735,7 +948,7 @@ export class WhatsApp {
                 else if (doc.type === 'event') {
                     content_buf = Buffer.from(JSON.stringify(msg.message?.eventMessage ?? {}), 'utf-8');
                 }
-                else if (this._socket && ['image', 'video', 'audio', 'document'].includes(doc.type)) {
+                else if (this.#internals.socket && ['image', 'video', 'audio', 'document'].includes(doc.type)) {
                     try {
                         const buffer = await downloadMediaMessage(msg, 'buffer', {});
                         if (Buffer.isBuffer(buffer)) {
@@ -749,17 +962,17 @@ export class WhatsApp {
                 if (content_buf.length > 0) {
                     await this.engine.set(`/chat/${cid}/message/${mid}/content`, serialize({ data: content_buf.toString('base64') }));
                 }
-                const instance = await this.Message.build_instance(doc);
+                const instance = message(this, doc);
                 const chat_instance = await instance.chat();
-                this._event.emit('message:created', instance, chat_instance, this);
+                this.emit('message:created', instance, chat_instance, this);
                 if (doc.forwarded) {
-                    this._event.emit('message:forwarded', instance, chat_instance, this);
+                    this.emit('message:forwarded', instance, chat_instance, this);
                 }
             }
         }
     }
     /** @internal */
-    async _handle_messages_update(updates) {
+    async #handle_messages_update(updates) {
         for (const { key, update: upd } of updates) {
             if (key.remoteJid && key.id) {
                 // Updates sobre `status@broadcast` se descartan: el feed sólo se
@@ -781,42 +994,42 @@ export class WhatsApp {
                         raw.message = edited_message;
                         doc.raw = raw;
                         doc.edited = true;
-                        doc.caption = this.Message.build_message_doc(raw, this._socket?.user?.id, true).caption;
-                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc));
-                        const msg_instance = await this.Message.build_instance(doc);
-                        this._event.emit('message:updated', msg_instance, await msg_instance.chat(), this);
+                        doc.caption = message(this, raw).caption;
+                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                        const msg_instance = message(this, doc);
+                        this.emit('message:updated', msg_instance, await msg_instance.chat(), this);
                     }
                     else if (content_update) {
                         // Actualización de contenido (ej: live location). Mergea sobre el raw existente.
                         raw.message = { ...raw.message, ...content_update };
                         doc.raw = raw;
-                        doc.caption = this.Message.build_message_doc(raw, this._socket?.user?.id, doc.edited).caption;
-                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc));
-                        const msg_instance = await this.Message.build_instance(doc);
-                        this._event.emit('message:updated', msg_instance, await msg_instance.chat(), this);
+                        doc.caption = message(this, raw).caption;
+                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                        const msg_instance = message(this, doc);
+                        this.emit('message:updated', msg_instance, await msg_instance.chat(), this);
                     }
                     else if (starred_changed) {
                         doc.starred = upd_any.starred === true;
                         raw.starred = doc.starred;
                         doc.raw = raw;
-                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc));
-                        const msg_instance = await this.Message.build_instance(doc);
-                        this._event.emit(doc.starred ? 'message:starred' : 'message:unstarred', msg_instance, await msg_instance.chat(), this);
+                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                        const msg_instance = message(this, doc);
+                        this.emit(doc.starred ? 'message:starred' : 'message:unstarred', msg_instance, await msg_instance.chat(), this);
                     }
                     else if (status !== undefined) {
                         raw.status = status;
                         doc.status = status;
                         doc.raw = raw;
-                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc));
-                        const msg_instance = await this.Message.build_instance(doc);
-                        this._event.emit('message:updated', msg_instance, await msg_instance.chat(), this);
+                        await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                        const msg_instance = message(this, doc);
+                        this.emit('message:updated', msg_instance, await msg_instance.chat(), this);
                     }
                 }
             }
         }
     }
     /** @internal */
-    async _handle_messages_reaction(reactions) {
+    async #handle_messages_reaction(reactions) {
         for (const { key, reaction } of reactions) {
             if (key.remoteJid && key.id) {
                 // Reacciones sobre status@broadcast → feed:updated (no message:reacted).
@@ -824,14 +1037,21 @@ export class WhatsApp {
                 if (key.remoteJid === 'status@broadcast') {
                     const feed_raw = deserialize(await this.engine.get(`/status/${key.id}`));
                     if (feed_raw) {
-                        this._event.emit('feed:updated', new Feed({ wa: this, doc: feed_raw }), this);
+                        this.emit('feed:updated', new Feed(this, feed_raw), this);
                     }
                     continue;
                 }
                 const doc = deserialize(await this.engine.get(`/chat/${key.remoteJid}/message/${key.id}`));
                 if (doc) {
-                    const msg_instance = await this.Message.build_instance(doc);
-                    this._event.emit('message:reacted', msg_instance, await msg_instance.chat(), reaction.text ?? '', this);
+                    const reactor = jidNormalizedUser(key.participant ?? key.remoteJid);
+                    const emoji = reaction.text ?? '';
+                    doc.reactions = [
+                        ...(doc.reactions ?? []).filter((r) => r.author !== reactor),
+                        ...(emoji ? [{ author: reactor, emoji, at: Date.now() }] : []),
+                    ];
+                    await this.engine.set(`/chat/${key.remoteJid}/message/${key.id}`, serialize(doc), doc.created_at);
+                    const msg_instance = message(this, doc);
+                    this.emit('message:reacted', msg_instance, await msg_instance.chat(), reaction.text ?? '', this);
                 }
             }
         }