@arcaelas/whatsapp 7.4.2 → 8.0.0

package/build/cjs/index.d.ts

@@ -7,7 +7,7 @@ import WhatsApp from './lib/whatsapp';
 export { WhatsApp };
 export default WhatsApp;
 export type IWhatsApp = ConstructorParameters<typeof WhatsApp>[0];
-export type { Farewell } from './lib/whatsapp';
+export type { ChatWatch, ContactWatch, Farewell, MessageWatch, Presence, WatchEvent } from './lib/whatsapp';
 export type DisconnectOptions = NonNullable<Parameters<WhatsApp['disconnect']>[0]>;
 export type ReconnectOption = NonNullable<IWhatsApp['reconnect']>;
 export { FileSystemEngine, RedisEngine, S3Engine, SQLiteEngine, serialize, deserialize } from './lib/store';

package/build/cjs/lib/chat/index.d.ts

@@ -8,6 +8,7 @@ import type Contact from '../../lib/contact';
 import type Message from '../../lib/message';
 import { type Engine } from '../../lib/store';
 import type WhatsApp from '../../lib/whatsapp';
+import type { ChatWatch, WatchEvent } from '../../lib/whatsapp';
 /**
  * Chat: recibe el raw y deriva todo con getters.
  * Chat: receives the raw and derives everything via getters.
@@ -147,6 +148,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.
@@ -264,6 +282,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.
@@ -380,6 +415,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.

package/build/cjs/lib/chat/index.js

@@ -213,6 +213,37 @@ function chat(init) {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        async watch(handler) {
+            const off_message = init.wa.on('message:created', (msg) => {
+                if (msg.cid === this._raw.id)
+                    handler({ name: 'message', payload: msg });
+            });
+            if (this.type === 'group') {
+                return off_message;
+            }
+            const who = await init.wa.Contact.get(this._raw.id);
+            const off_presence = (await who?.watch((event) => handler(event))) ?? (() => { });
+            return () => {
+                off_message();
+                off_presence();
+            };
+        }
         async seen() {
             const last = await tail(this._raw.id);
             // Marcar leído se acusa con recibos, no con una mutación del estado de la app.

package/build/cjs/lib/contact/index.d.ts

@@ -7,6 +7,7 @@ import { type WASocket } from 'baileys';
 import { Feed } from '../../lib/status';
 import { type Engine } from '../../lib/store';
 import type WhatsApp from '../../lib/whatsapp';
+import type { ContactWatch, WatchEvent } from '../../lib/whatsapp';
 /** Sesión activa que liga la entidad. / Active session binding the entity. */
 type Init = {
     wa: WhatsApp;
@@ -82,6 +83,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;
@@ -120,6 +139,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;
@@ -157,6 +194,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;

package/build/cjs/lib/contact/index.js

@@ -68,6 +68,37 @@ function contact(init) {
             const cid = this.jid ?? this.lid ?? this._raw.id;
             return new init.wa.Chat((0, store_1.deserialize)(await init.engine.get(`/chat/${cid}`)) ?? { id: cid, name: this.name });
         }
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        async watch(handler) {
+            const jid = this.jid ?? this.lid ?? this._raw.id;
+            const mine = (jid.split('@')[0] ?? '').split(':')[0];
+            await init.socket.presenceSubscribe(jid);
+            return init.wa.on('contact:presence', (who, name) => {
+                // El mismo contacto llega unas veces por teléfono y otras por LID: comparar la
+                // parte identificadora es lo único que los reconoce como la misma persona.
+                // The same contact arrives sometimes by phone and sometimes by LID: comparing the
+                // identifying part is the only thing recognising them as the same person.
+                if ([who.jid, who.lid, who._raw.id].some((id) => (id ?? '').startsWith(mine))) {
+                    handler({ name, payload: who });
+                }
+            });
+        }
         /**
          * Contacto por teléfono, JID o LID: primero el engine y, si no está persistido, se
          * descubre por red con su foto y su bio, y se materializa.

package/build/cjs/lib/message/index.d.ts

@@ -11,6 +11,7 @@ import Chat from '../../lib/chat';
 import type Contact from '../../lib/contact';
 import { type Engine } from '../../lib/store';
 import type WhatsApp from '../../lib/whatsapp';
+import type { MessageWatch, WatchEvent } from '../../lib/whatsapp';
 /** Estados legibles indexados por el status numérico de baileys. / Readable states indexed by the baileys numeric status. */
 declare const STATUS: readonly ["error", "pending", "sent", "delivered", "read", "played"];
 /** Sesión activa que liga la entidad. / Active session binding the entity. */
@@ -154,6 +155,24 @@ export default class Message {
      * @param value - true destaca / true stars
      */
     star(value: boolean): Promise<boolean>;
+    /**
+     * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+     * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+     *
+     * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+     * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+     * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+     * Watches what happens to this message: that it gets read, that its audio gets played, or
+     * that it is retired. It lives on the base class, so every message type inherits it.
+     *
+     * Under the hood it listens to the message's updates and translates them: `message:updated`
+     * does not tell read from played —both are a status change— and whoever watches a message
+     * wants to know which of the two happened, not that «something changed».
+     *
+     * @param handler - Recibe cada cambio / Receives every change
+     * @returns Función para dejar de supervisar / Function to stop watching
+     */
+    watch(handler: (event: WatchEvent<MessageWatch, Message>) => void): () => void;
     /** Marca el mensaje como leído. / Marks the message as read. */
     seen(): Promise<boolean>;
     /**
@@ -292,6 +311,19 @@ export declare class Audio extends Media {
     get duration(): number;
     /** Forma de onda 0-100 lista para pintar. / Paint-ready 0-100 waveform. */
     get waveform(): number[];
+    /** true si ya fue reproducido: el micrófono azul que ve quien lo mandó. / true when already played: the blue mic its sender sees. */
+    get played(): boolean;
+    /**
+     * Acusa el audio como reproducido. Es un aviso aparte del de leído —abrir el chat no
+     * reproduce nada—, y por eso viaja como recibo propio: quien lo mandó ve el micrófono
+     * azul sólo después de esto.
+     * Acknowledges the audio as played. It is separate from the read receipt —opening the chat
+     * plays nothing— and so travels as its own receipt: whoever sent it sees the blue mic only
+     * after this.
+     *
+     * @returns true cuando el acuse salió / true once the receipt left
+     */
+    play(): Promise<boolean>;
 }
 /** Mensaje de sticker. / Sticker message. */
 export declare class Sticker extends Media {
@@ -511,6 +543,24 @@ export declare function message(init: Init): {
          * @param value - true destaca / true stars
          */
         star(value: boolean): Promise<boolean>;
+        /**
+         * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+         * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+         *
+         * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+         * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+         * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+         * Watches what happens to this message: that it gets read, that its audio gets played, or
+         * that it is retired. It lives on the base class, so every message type inherits it.
+         *
+         * Under the hood it listens to the message's updates and translates them: `message:updated`
+         * does not tell read from played —both are a status change— and whoever watches a message
+         * wants to know which of the two happened, not that «something changed».
+         *
+         * @param handler - Recibe cada cambio / Receives every change
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<MessageWatch, Message>) => void): () => void;
         /** Marca el mensaje como leído. / Marks the message as read. */
         seen(): Promise<boolean>;
         /**

package/build/cjs/lib/message/index.js

@@ -295,6 +295,51 @@ class Message {
         await this._init.engine.set(`/chat/${doc.cid}/message/${doc.id}`, (0, store_1.serialize)(doc), doc.created_at);
         return true;
     }
+    /**
+     * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+     * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+     *
+     * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+     * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+     * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+     * Watches what happens to this message: that it gets read, that its audio gets played, or
+     * that it is retired. It lives on the base class, so every message type inherits it.
+     *
+     * Under the hood it listens to the message's updates and translates them: `message:updated`
+     * does not tell read from played —both are a status change— and whoever watches a message
+     * wants to know which of the two happened, not that «something changed».
+     *
+     * @param handler - Recibe cada cambio / Receives every change
+     * @returns Función para dejar de supervisar / Function to stop watching
+     */
+    watch(handler) {
+        const { wa } = this._init;
+        let seen = this._raw.status;
+        const off_updated = wa.on('message:updated', (msg) => {
+            if (msg.id === this._raw.id) {
+                const status = msg._raw.status;
+                // Sólo los avances cuentan: un mismo estado repetido no es una noticia, y sin
+                // este corte cada acuse reenviado por WhatsApp se contaría como una lectura más.
+                // Only advances count: a repeated status is not news, and without this cut every
+                // acknowledgement WhatsApp resends would count as another read.
+                if (status > seen) {
+                    seen = status;
+                    if (status >= baileys_1.proto.WebMessageInfo.Status.PLAYED)
+                        handler({ name: 'played', payload: msg });
+                    else if (status >= baileys_1.proto.WebMessageInfo.Status.READ)
+                        handler({ name: 'read', payload: msg });
+                }
+            }
+        });
+        const off_deleted = wa.on('message:deleted', (msg) => {
+            if (msg.id === this._raw.id)
+                handler({ name: 'deleted', payload: msg });
+        });
+        return () => {
+            off_updated();
+            off_deleted();
+        };
+    }
     /** Marca el mensaje como leído. / Marks the message as read. */
     async seen() {
         const { cid, id, author } = this._raw;
@@ -478,6 +523,23 @@ class Audio extends Media {
     get duration() { return this._media?.seconds ?? 0; }
     /** Forma de onda 0-100 lista para pintar. / Paint-ready 0-100 waveform. */
     get waveform() { return Array.from(to_buffer(this._media?.waveform) ?? []); }
+    /** true si ya fue reproducido: el micrófono azul que ve quien lo mandó. / true when already played: the blue mic its sender sees. */
+    get played() { return this._raw.status >= baileys_1.proto.WebMessageInfo.Status.PLAYED; }
+    /**
+     * Acusa el audio como reproducido. Es un aviso aparte del de leído —abrir el chat no
+     * reproduce nada—, y por eso viaja como recibo propio: quien lo mandó ve el micrófono
+     * azul sólo después de esto.
+     * Acknowledges the audio as played. It is separate from the read receipt —opening the chat
+     * plays nothing— and so travels as its own receipt: whoever sent it sees the blue mic only
+     * after this.
+     *
+     * @returns true cuando el acuse salió / true once the receipt left
+     */
+    async play() {
+        const { cid, id, author } = this._raw;
+        await this._init.socket.sendReceipt(cid, cid.endsWith('@g.us') ? author : undefined, [id], 'played');
+        return true;
+    }
 }
 exports.Audio = Audio;
 /** Mensaje de sticker. / Sticker message. */

package/build/cjs/lib/whatsapp/index.d.ts

@@ -3,6 +3,33 @@ import { Account, contact } from '../../lib/contact';
 import Message, { message } from '../../lib/message';
 import { Feed } from '../../lib/status';
 import { type Engine } from '../../lib/store';
+/**
+ * Lo que hace alguien al otro lado, en los términos en los que se mira: WhatsApp distingue
+ * «disponible» de «escribiendo» y de «grabando», y esa distinción es justo la que interesa
+ * vigilar. `paused` no se propaga: es dejar de escribir, no un estado en sí.
+ * What someone is doing on the other end, in the terms one watches it: WhatsApp tells «available»
+ * from «typing» and from «recording», and that distinction is exactly what is worth watching.
+ * `paused` is not propagated: it is stopping typing, not a state of its own.
+ */
+export type Presence = 'online' | 'offline' | 'typing' | 'recording';
+/**
+ * Lo que se supervisa con `watch()`, en un solo sobre: `name` dice qué pasó y `payload` trae la
+ * instancia a la que le pasó, ya resuelta. Quien escucha no tiene que volver a buscar de quién
+ * se trata ni filtrar lo que no le toca.
+ * What `watch()` supervises, in a single envelope: `name` says what happened and `payload` brings
+ * the already-resolved instance it happened to. Whoever listens does not have to look up who it
+ * was nor filter out what does not concern them.
+ */
+export interface WatchEvent<N extends string, P> {
+    name: N;
+    payload: P;
+}
+/** Cada acción de alguien al otro lado, incluido dejar de escribir o de grabar. / Every action from the other end, including stopping typing or recording. */
+export type ContactWatch = 'online' | 'offline' | 'typing' | 'recording' | 'stopped-typing' | 'stopped-recording';
+/** Lo que le puede pasar a un mensaje ya enviado. / What can happen to an already-sent message. */
+export type MessageWatch = 'read' | 'played' | 'deleted';
+/** Un chat mezcla lo que hace la persona con lo que llega a la conversación. / A chat mixes what the person does with what arrives in the conversation. */
+export type ChatWatch = ContactWatch | 'message';
 type ChatInstance = InstanceType<ReturnType<typeof chat>>;
 type ContactInstance = InstanceType<ReturnType<typeof contact>>;
 interface Options {
@@ -63,8 +90,14 @@ export interface Farewell {
 interface EventMap {
     connected: [WhatsApp];
     disconnected: [WhatsApp, Farewell];
+    /** Fallo que no tumba la conexión pero que quien la abrió necesita saber. / A failure that does not drop the connection but whoever opened it needs to know. */
+    error: [Error & {
+        code?: string;
+    }, WhatsApp];
     'contact:created': [ContactInstance, ChatInstance, WhatsApp];
     'contact:updated': [ContactInstance, ChatInstance, WhatsApp];
+    /** Alguien entró, salió, escribe o graba. Sólo llega de quien se esté vigilando con `Contact.watch()`. / Someone came in, left, is typing or recording. Only arrives for whoever is being watched with `Contact.watch()`. */
+    'contact:presence': [ContactInstance, ContactWatch, WhatsApp];
     'chat:created': [ChatInstance, WhatsApp];
     'chat:deleted': [ChatInstance, WhatsApp];
     'chat:pinned': [ChatInstance, WhatsApp];

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

@@ -72,7 +72,18 @@ const queued = (locks, path, work) => {
     locks.set(path, next.catch(() => { }));
     return next;
 };
+/** Traduce el vocabulario de baileys al que se vigila; lo que no está aquí no se propaga. / Translates baileys' vocabulary into the watched one; whatever is missing is not propagated. */
+const PRESENCE = { available: 'online', unavailable: 'offline', composing: 'typing', recording: 'recording', paused: 'paused' };
 const readable = (value) => (value && !/^\+?[\d\s·•∙⋅]+$/.test(value) ? value : null);
+/**
+ * Refrescos de QR que dura un PIN antes de darlo por caducado. WhatsApp no avisa de la
+ * expiración, así que se mide por los ciclos de refresco (~20 s cada uno): tres son el margen
+ * observado en el que un código sigue siendo aceptado.
+ * QR refreshes a PIN lasts before it is considered expired. WhatsApp gives no expiry notice, so
+ * it is measured in refresh cycles (~20s each): three is the observed window in which a code is
+ * still accepted.
+ */
+const OTP_CYCLES = 3;
 class WhatsApp {
     #event = new node_events_1.EventEmitter();
     #options;
@@ -115,9 +126,13 @@ class WhatsApp {
         let retries = 0;
         let intentional = false;
         let silent = false;
+        let paired = false;
+        let cycles = 0;
         let alive = null;
         let timer = null;
         let chain = Promise.resolve();
+        /** Qué estaba haciendo cada quien, para poder leer su `paused`. / What each one was doing, so their `paused` can be read. */
+        const doing = new Map();
         const locks = new Map();
         return new Promise((resolve, reject) => {
             const start = async () => {
@@ -296,9 +311,33 @@ class WhatsApp {
                 socket.ev.on('creds.update', () => queued(locks, '/session/creds', () => engine.set('/session/creds', (0, store_1.serialize)(creds))));
                 socket.ev.on('connection.update', async ({ connection, lastDisconnect, qr }) => {
                     if (qr && !creds.registered) {
-                        await callback(digits && (method ?? 'otp') === 'otp'
-                            ? await socket.requestPairingCode(digits)
-                            : await QRCode.toBuffer(qr, { type: 'png', margin: 2 }));
+                        if (digits && (method ?? 'otp') === 'otp') {
+                            // El QR se refresca cada ~20 s, pero el PIN vive más: pedir uno en
+                            // cada refresco invalida el anterior y el que la persona está
+                            // tecleando deja de servir a media escritura —el síntoma es un PIN
+                            // correcto que «no lo toma»—. Por eso se cuenta el ciclo y sólo se
+                            // renueva al caducar de verdad, gastando un reintento del presupuesto.
+                            // The QR refreshes every ~20s, but the PIN lives longer: asking for
+                            // one on each refresh invalidates the previous, and the one being
+                            // typed stops working mid-typing —the symptom is a correct PIN that
+                            // «is not accepted»—. So the cycle is counted and it is only renewed
+                            // once it truly expires, spending one retry from the budget.
+                            cycles = paired ? cycles + 1 : 0;
+                            if (!paired || cycles >= OTP_CYCLES) {
+                                if (paired && budget !== null && retries >= budget) {
+                                    this.emit('error', Object.assign(new Error('El código de vinculación expiró'), { code: 'ERR_OTP_EXPIRED' }), this);
+                                }
+                                else {
+                                    retries += paired ? 1 : 0;
+                                    cycles = 0;
+                                    paired = true;
+                                    await callback(await socket.requestPairingCode(digits));
+                                }
+                            }
+                        }
+                        else {
+                            await callback(await QRCode.toBuffer(qr, { type: 'png', margin: 2 }));
+                        }
                     }
                     if (connection === 'open') {
                         connected = true;
@@ -409,6 +448,31 @@ class WhatsApp {
                         }
                     }).catch(() => { });
                 });
+                socket.ev.on('presence.update', ({ id, presences }) => {
+                    chain = chain.then(async () => {
+                        const cid = await canonical(id);
+                        for (const [participant, data] of Object.entries(presences)) {
+                            const state = PRESENCE[data.lastKnownPresence];
+                            if (state) {
+                                const who = await canonical(participant || cid);
+                                // `paused` es «dejó de hacer lo que hacía», y sólo el estado
+                                // anterior dice qué era: sin recordarlo no se puede distinguir
+                                // dejar de escribir de dejar de grabar.
+                                // `paused` means «stopped doing what they were doing», and only
+                                // the previous state says which: without remembering it there is
+                                // no telling stopped-typing from stopped-recording.
+                                const last = doing.get(who);
+                                const name = state === 'paused' ? (last === 'recording' ? 'stopped-recording' : 'stopped-typing') : state;
+                                if (state === 'typing' || state === 'recording')
+                                    doing.set(who, state);
+                                else
+                                    doing.delete(who);
+                                const card = (0, store_1.deserialize)(await engine.get(`/contact/${who}`));
+                                this.emit('contact:presence', new this.Contact(card ?? { id: who, lid: null, name: null, notify: null, verified_name: null, img_url: null, status: null }), name, this);
+                            }
+                        }
+                    }).catch(() => { });
+                });
                 socket.ev.on('lid-mapping.update', ({ lid, pn }) => {
                     chain = chain.then(async () => {
                         await remember(lid, pn);
@@ -531,7 +595,18 @@ class WhatsApp {
                                     continue;
                                 }
                                 const type = { conversation: 'text', extendedTextMessage: 'text', imageMessage: 'image', videoMessage: 'video', audioMessage: 'audio' }[kind ?? ''];
-                                const author = msg.key.participant ?? '';
+                                // El autor de un estado puede llegar por `participant` o por su
+                                // alterno según venga identificado por teléfono o por LID, y se
+                                // guarda canónico como todo lo demás: con el LID crudo el estado
+                                // queda a nombre de un número larguísimo que no case con ningún
+                                // contacto, y para quien mira es un estado que no llegó.
+                                // A status author can arrive via `participant` or its alternate
+                                // depending on whether it is identified by phone or by LID, and
+                                // is stored canonically like everything else: with the raw LID
+                                // the status ends up under a long meaningless number matching no
+                                // contact, and to whoever looks it is a status that never came.
+                                const claimed = msg.key.participant ?? msg.key.participantAlt ?? '';
+                                const author = claimed ? await canonical(claimed) : '';
                                 if (!type || !author) {
                                     continue;
                                 }

package/build/esm/index.d.ts

@@ -7,7 +7,7 @@ import WhatsApp from './lib/whatsapp/index.js';
 export { WhatsApp };
 export default WhatsApp;
 export type IWhatsApp = ConstructorParameters<typeof WhatsApp>[0];
-export type { Farewell } from './lib/whatsapp/index.js';
+export type { ChatWatch, ContactWatch, Farewell, MessageWatch, Presence, WatchEvent } from './lib/whatsapp/index.js';
 export type DisconnectOptions = NonNullable<Parameters<WhatsApp['disconnect']>[0]>;
 export type ReconnectOption = NonNullable<IWhatsApp['reconnect']>;
 export { FileSystemEngine, RedisEngine, S3Engine, SQLiteEngine, serialize, deserialize } from './lib/store/index.js';

package/build/esm/lib/chat/index.d.ts

@@ -8,6 +8,7 @@ import type Contact from '../../lib/contact/index.js';
 import type Message from '../../lib/message/index.js';
 import { type Engine } from '../../lib/store/index.js';
 import type WhatsApp from '../../lib/whatsapp/index.js';
+import type { ChatWatch, WatchEvent } from '../../lib/whatsapp/index.js';
 /**
  * Chat: recibe el raw y deriva todo con getters.
  * Chat: receives the raw and derives everything via getters.
@@ -147,6 +148,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.
@@ -264,6 +282,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.
@@ -380,6 +415,23 @@ export declare function chat(init: {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ChatWatch, InstanceType<typeof init.wa.Contact> | Message>) => void): Promise<() => void>;
         seen(): Promise<boolean>;
         /**
          * Vacía los mensajes del chat en la cuenta y en el engine, conservando el chat.

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

@@ -209,6 +209,37 @@ export function chat(init) {
          * Marca el chat completo como leído en la cuenta.
          * Marks the whole chat as read on the account.
          */
+        /**
+         * Supervisa la conversación entera: lo que hace la persona al otro lado —entra, sale,
+         * escribe, graba, deja de escribir, deja de grabar— y los mensajes que van llegando.
+         *
+         * No reimplementa nada: monta el `watch` del contacto dueño del chat y le suma los
+         * mensajes nuevos. En un grupo no hay una sola persona a la que seguir, así que sólo
+         * quedan los mensajes.
+         * Watches the whole conversation: what the person on the other end does —comes in, leaves,
+         * types, records, stops typing, stops recording— and the messages arriving.
+         *
+         * It reimplements nothing: it sets up the watch of the chat's owning contact and adds new
+         * messages to it. In a group there is no single person to follow, so only messages remain.
+         *
+         * @param handler - Recibe cada acción y cada mensaje / Receives every action and every message
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        async watch(handler) {
+            const off_message = init.wa.on('message:created', (msg) => {
+                if (msg.cid === this._raw.id)
+                    handler({ name: 'message', payload: msg });
+            });
+            if (this.type === 'group') {
+                return off_message;
+            }
+            const who = await init.wa.Contact.get(this._raw.id);
+            const off_presence = (await who?.watch((event) => handler(event))) ?? (() => { });
+            return () => {
+                off_message();
+                off_presence();
+            };
+        }
         async seen() {
             const last = await tail(this._raw.id);
             // Marcar leído se acusa con recibos, no con una mutación del estado de la app.

package/build/esm/lib/contact/index.d.ts

@@ -7,6 +7,7 @@ import { type WASocket } from 'baileys';
 import { Feed } from '../../lib/status/index.js';
 import { type Engine } from '../../lib/store/index.js';
 import type WhatsApp from '../../lib/whatsapp/index.js';
+import type { ContactWatch, WatchEvent } from '../../lib/whatsapp/index.js';
 /** Sesión activa que liga la entidad. / Active session binding the entity. */
 type Init = {
     wa: WhatsApp;
@@ -82,6 +83,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;
@@ -120,6 +139,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;
@@ -157,6 +194,24 @@ export declare function contact(init: Init): {
          * @returns Instancia de Chat / Chat instance
          */
         chat(): Promise<InstanceType<typeof init.wa.Chat>>;
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<ContactWatch, /*elided*/ any>) => void): Promise<() => void>;
         readonly _raw: {
             id: string;
             lid?: string | null;

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

@@ -63,6 +63,37 @@ export function contact(init) {
             const cid = this.jid ?? this.lid ?? this._raw.id;
             return new init.wa.Chat(deserialize(await init.engine.get(`/chat/${cid}`)) ?? { id: cid, name: this.name });
         }
+        /**
+         * Supervisa lo que hace el contacto: entra, sale, escribe, graba, deja de escribir o deja
+         * de grabar. Un aviso por acción, ya filtrado a esta persona.
+         *
+         * WhatsApp no difunde presencia por su cuenta —hay que pedirla contacto por contacto— y
+         * deja de mandarla al reconectar, así que la supervisión se vuelve a montar en cada
+         * sesión nueva.
+         * Watches what the contact does: comes in, leaves, types, records, stops typing or stops
+         * recording. One notice per action, already filtered down to this person.
+         *
+         * WhatsApp does not broadcast presence on its own —it must be asked for contact by
+         * contact— and stops sending it on reconnect, so the watch is set up again on every new
+         * session.
+         *
+         * @param handler - Recibe cada acción / Receives every action
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        async watch(handler) {
+            const jid = this.jid ?? this.lid ?? this._raw.id;
+            const mine = (jid.split('@')[0] ?? '').split(':')[0];
+            await init.socket.presenceSubscribe(jid);
+            return init.wa.on('contact:presence', (who, name) => {
+                // El mismo contacto llega unas veces por teléfono y otras por LID: comparar la
+                // parte identificadora es lo único que los reconoce como la misma persona.
+                // The same contact arrives sometimes by phone and sometimes by LID: comparing the
+                // identifying part is the only thing recognising them as the same person.
+                if ([who.jid, who.lid, who._raw.id].some((id) => (id ?? '').startsWith(mine))) {
+                    handler({ name, payload: who });
+                }
+            });
+        }
         /**
          * Contacto por teléfono, JID o LID: primero el engine y, si no está persistido, se
          * descubre por red con su foto y su bio, y se materializa.

package/build/esm/lib/message/index.d.ts

@@ -11,6 +11,7 @@ import Chat from '../../lib/chat/index.js';
 import type Contact from '../../lib/contact/index.js';
 import { type Engine } from '../../lib/store/index.js';
 import type WhatsApp from '../../lib/whatsapp/index.js';
+import type { MessageWatch, WatchEvent } from '../../lib/whatsapp/index.js';
 /** Estados legibles indexados por el status numérico de baileys. / Readable states indexed by the baileys numeric status. */
 declare const STATUS: readonly ["error", "pending", "sent", "delivered", "read", "played"];
 /** Sesión activa que liga la entidad. / Active session binding the entity. */
@@ -154,6 +155,24 @@ export default class Message {
      * @param value - true destaca / true stars
      */
     star(value: boolean): Promise<boolean>;
+    /**
+     * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+     * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+     *
+     * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+     * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+     * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+     * Watches what happens to this message: that it gets read, that its audio gets played, or
+     * that it is retired. It lives on the base class, so every message type inherits it.
+     *
+     * Under the hood it listens to the message's updates and translates them: `message:updated`
+     * does not tell read from played —both are a status change— and whoever watches a message
+     * wants to know which of the two happened, not that «something changed».
+     *
+     * @param handler - Recibe cada cambio / Receives every change
+     * @returns Función para dejar de supervisar / Function to stop watching
+     */
+    watch(handler: (event: WatchEvent<MessageWatch, Message>) => void): () => void;
     /** Marca el mensaje como leído. / Marks the message as read. */
     seen(): Promise<boolean>;
     /**
@@ -292,6 +311,19 @@ export declare class Audio extends Media {
     get duration(): number;
     /** Forma de onda 0-100 lista para pintar. / Paint-ready 0-100 waveform. */
     get waveform(): number[];
+    /** true si ya fue reproducido: el micrófono azul que ve quien lo mandó. / true when already played: the blue mic its sender sees. */
+    get played(): boolean;
+    /**
+     * Acusa el audio como reproducido. Es un aviso aparte del de leído —abrir el chat no
+     * reproduce nada—, y por eso viaja como recibo propio: quien lo mandó ve el micrófono
+     * azul sólo después de esto.
+     * Acknowledges the audio as played. It is separate from the read receipt —opening the chat
+     * plays nothing— and so travels as its own receipt: whoever sent it sees the blue mic only
+     * after this.
+     *
+     * @returns true cuando el acuse salió / true once the receipt left
+     */
+    play(): Promise<boolean>;
 }
 /** Mensaje de sticker. / Sticker message. */
 export declare class Sticker extends Media {
@@ -511,6 +543,24 @@ export declare function message(init: Init): {
          * @param value - true destaca / true stars
          */
         star(value: boolean): Promise<boolean>;
+        /**
+         * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+         * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+         *
+         * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+         * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+         * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+         * Watches what happens to this message: that it gets read, that its audio gets played, or
+         * that it is retired. It lives on the base class, so every message type inherits it.
+         *
+         * Under the hood it listens to the message's updates and translates them: `message:updated`
+         * does not tell read from played —both are a status change— and whoever watches a message
+         * wants to know which of the two happened, not that «something changed».
+         *
+         * @param handler - Recibe cada cambio / Receives every change
+         * @returns Función para dejar de supervisar / Function to stop watching
+         */
+        watch(handler: (event: WatchEvent<MessageWatch, Message>) => void): () => void;
         /** Marca el mensaje como leído. / Marks the message as read. */
         seen(): Promise<boolean>;
         /**

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

@@ -288,6 +288,51 @@ export default class Message {
         await this._init.engine.set(`/chat/${doc.cid}/message/${doc.id}`, serialize(doc), doc.created_at);
         return true;
     }
+    /**
+     * Supervisa qué le pasa a este mensaje: que lo lean, que reproduzcan su audio o que lo
+     * retiren. Vive en la clase base, así que todo tipo de mensaje lo hereda.
+     *
+     * Por dentro escucha las actualizaciones del mensaje y las traduce: `message:updated` no
+     * distingue leído de reproducido —los dos son un cambio de estado— y quien supervisa un
+     * mensaje quiere saber cuál de los dos ocurrió, no que «algo cambió».
+     * Watches what happens to this message: that it gets read, that its audio gets played, or
+     * that it is retired. It lives on the base class, so every message type inherits it.
+     *
+     * Under the hood it listens to the message's updates and translates them: `message:updated`
+     * does not tell read from played —both are a status change— and whoever watches a message
+     * wants to know which of the two happened, not that «something changed».
+     *
+     * @param handler - Recibe cada cambio / Receives every change
+     * @returns Función para dejar de supervisar / Function to stop watching
+     */
+    watch(handler) {
+        const { wa } = this._init;
+        let seen = this._raw.status;
+        const off_updated = wa.on('message:updated', (msg) => {
+            if (msg.id === this._raw.id) {
+                const status = msg._raw.status;
+                // Sólo los avances cuentan: un mismo estado repetido no es una noticia, y sin
+                // este corte cada acuse reenviado por WhatsApp se contaría como una lectura más.
+                // Only advances count: a repeated status is not news, and without this cut every
+                // acknowledgement WhatsApp resends would count as another read.
+                if (status > seen) {
+                    seen = status;
+                    if (status >= proto.WebMessageInfo.Status.PLAYED)
+                        handler({ name: 'played', payload: msg });
+                    else if (status >= proto.WebMessageInfo.Status.READ)
+                        handler({ name: 'read', payload: msg });
+                }
+            }
+        });
+        const off_deleted = wa.on('message:deleted', (msg) => {
+            if (msg.id === this._raw.id)
+                handler({ name: 'deleted', payload: msg });
+        });
+        return () => {
+            off_updated();
+            off_deleted();
+        };
+    }
     /** Marca el mensaje como leído. / Marks the message as read. */
     async seen() {
         const { cid, id, author } = this._raw;
@@ -467,6 +512,23 @@ export class Audio extends Media {
     get duration() { return this._media?.seconds ?? 0; }
     /** Forma de onda 0-100 lista para pintar. / Paint-ready 0-100 waveform. */
     get waveform() { return Array.from(to_buffer(this._media?.waveform) ?? []); }
+    /** true si ya fue reproducido: el micrófono azul que ve quien lo mandó. / true when already played: the blue mic its sender sees. */
+    get played() { return this._raw.status >= proto.WebMessageInfo.Status.PLAYED; }
+    /**
+     * Acusa el audio como reproducido. Es un aviso aparte del de leído —abrir el chat no
+     * reproduce nada—, y por eso viaja como recibo propio: quien lo mandó ve el micrófono
+     * azul sólo después de esto.
+     * Acknowledges the audio as played. It is separate from the read receipt —opening the chat
+     * plays nothing— and so travels as its own receipt: whoever sent it sees the blue mic only
+     * after this.
+     *
+     * @returns true cuando el acuse salió / true once the receipt left
+     */
+    async play() {
+        const { cid, id, author } = this._raw;
+        await this._init.socket.sendReceipt(cid, cid.endsWith('@g.us') ? author : undefined, [id], 'played');
+        return true;
+    }
 }
 /** Mensaje de sticker. / Sticker message. */
 export class Sticker extends Media {

package/build/esm/lib/whatsapp/index.d.ts

@@ -3,6 +3,33 @@ import { Account, contact } from '../../lib/contact/index.js';
 import Message, { message } from '../../lib/message/index.js';
 import { Feed } from '../../lib/status/index.js';
 import { type Engine } from '../../lib/store/index.js';
+/**
+ * Lo que hace alguien al otro lado, en los términos en los que se mira: WhatsApp distingue
+ * «disponible» de «escribiendo» y de «grabando», y esa distinción es justo la que interesa
+ * vigilar. `paused` no se propaga: es dejar de escribir, no un estado en sí.
+ * What someone is doing on the other end, in the terms one watches it: WhatsApp tells «available»
+ * from «typing» and from «recording», and that distinction is exactly what is worth watching.
+ * `paused` is not propagated: it is stopping typing, not a state of its own.
+ */
+export type Presence = 'online' | 'offline' | 'typing' | 'recording';
+/**
+ * Lo que se supervisa con `watch()`, en un solo sobre: `name` dice qué pasó y `payload` trae la
+ * instancia a la que le pasó, ya resuelta. Quien escucha no tiene que volver a buscar de quién
+ * se trata ni filtrar lo que no le toca.
+ * What `watch()` supervises, in a single envelope: `name` says what happened and `payload` brings
+ * the already-resolved instance it happened to. Whoever listens does not have to look up who it
+ * was nor filter out what does not concern them.
+ */
+export interface WatchEvent<N extends string, P> {
+    name: N;
+    payload: P;
+}
+/** Cada acción de alguien al otro lado, incluido dejar de escribir o de grabar. / Every action from the other end, including stopping typing or recording. */
+export type ContactWatch = 'online' | 'offline' | 'typing' | 'recording' | 'stopped-typing' | 'stopped-recording';
+/** Lo que le puede pasar a un mensaje ya enviado. / What can happen to an already-sent message. */
+export type MessageWatch = 'read' | 'played' | 'deleted';
+/** Un chat mezcla lo que hace la persona con lo que llega a la conversación. / A chat mixes what the person does with what arrives in the conversation. */
+export type ChatWatch = ContactWatch | 'message';
 type ChatInstance = InstanceType<ReturnType<typeof chat>>;
 type ContactInstance = InstanceType<ReturnType<typeof contact>>;
 interface Options {
@@ -63,8 +90,14 @@ export interface Farewell {
 interface EventMap {
     connected: [WhatsApp];
     disconnected: [WhatsApp, Farewell];
+    /** Fallo que no tumba la conexión pero que quien la abrió necesita saber. / A failure that does not drop the connection but whoever opened it needs to know. */
+    error: [Error & {
+        code?: string;
+    }, WhatsApp];
     'contact:created': [ContactInstance, ChatInstance, WhatsApp];
     'contact:updated': [ContactInstance, ChatInstance, WhatsApp];
+    /** Alguien entró, salió, escribe o graba. Sólo llega de quien se esté vigilando con `Contact.watch()`. / Someone came in, left, is typing or recording. Only arrives for whoever is being watched with `Contact.watch()`. */
+    'contact:presence': [ContactInstance, ContactWatch, WhatsApp];
     'chat:created': [ChatInstance, WhatsApp];
     'chat:deleted': [ChatInstance, WhatsApp];
     'chat:pinned': [ChatInstance, WhatsApp];

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

@@ -34,7 +34,18 @@ const queued = (locks, path, work) => {
     locks.set(path, next.catch(() => { }));
     return next;
 };
+/** Traduce el vocabulario de baileys al que se vigila; lo que no está aquí no se propaga. / Translates baileys' vocabulary into the watched one; whatever is missing is not propagated. */
+const PRESENCE = { available: 'online', unavailable: 'offline', composing: 'typing', recording: 'recording', paused: 'paused' };
 const readable = (value) => (value && !/^\+?[\d\s·•∙⋅]+$/.test(value) ? value : null);
+/**
+ * Refrescos de QR que dura un PIN antes de darlo por caducado. WhatsApp no avisa de la
+ * expiración, así que se mide por los ciclos de refresco (~20 s cada uno): tres son el margen
+ * observado en el que un código sigue siendo aceptado.
+ * QR refreshes a PIN lasts before it is considered expired. WhatsApp gives no expiry notice, so
+ * it is measured in refresh cycles (~20s each): three is the observed window in which a code is
+ * still accepted.
+ */
+const OTP_CYCLES = 3;
 export default class WhatsApp {
     #event = new EventEmitter();
     #options;
@@ -77,9 +88,13 @@ export default class WhatsApp {
         let retries = 0;
         let intentional = false;
         let silent = false;
+        let paired = false;
+        let cycles = 0;
         let alive = null;
         let timer = null;
         let chain = Promise.resolve();
+        /** Qué estaba haciendo cada quien, para poder leer su `paused`. / What each one was doing, so their `paused` can be read. */
+        const doing = new Map();
         const locks = new Map();
         return new Promise((resolve, reject) => {
             const start = async () => {
@@ -258,9 +273,33 @@ export default class WhatsApp {
                 socket.ev.on('creds.update', () => queued(locks, '/session/creds', () => engine.set('/session/creds', serialize(creds))));
                 socket.ev.on('connection.update', async ({ connection, lastDisconnect, qr }) => {
                     if (qr && !creds.registered) {
-                        await callback(digits && (method ?? 'otp') === 'otp'
-                            ? await socket.requestPairingCode(digits)
-                            : await QRCode.toBuffer(qr, { type: 'png', margin: 2 }));
+                        if (digits && (method ?? 'otp') === 'otp') {
+                            // El QR se refresca cada ~20 s, pero el PIN vive más: pedir uno en
+                            // cada refresco invalida el anterior y el que la persona está
+                            // tecleando deja de servir a media escritura —el síntoma es un PIN
+                            // correcto que «no lo toma»—. Por eso se cuenta el ciclo y sólo se
+                            // renueva al caducar de verdad, gastando un reintento del presupuesto.
+                            // The QR refreshes every ~20s, but the PIN lives longer: asking for
+                            // one on each refresh invalidates the previous, and the one being
+                            // typed stops working mid-typing —the symptom is a correct PIN that
+                            // «is not accepted»—. So the cycle is counted and it is only renewed
+                            // once it truly expires, spending one retry from the budget.
+                            cycles = paired ? cycles + 1 : 0;
+                            if (!paired || cycles >= OTP_CYCLES) {
+                                if (paired && budget !== null && retries >= budget) {
+                                    this.emit('error', Object.assign(new Error('El código de vinculación expiró'), { code: 'ERR_OTP_EXPIRED' }), this);
+                                }
+                                else {
+                                    retries += paired ? 1 : 0;
+                                    cycles = 0;
+                                    paired = true;
+                                    await callback(await socket.requestPairingCode(digits));
+                                }
+                            }
+                        }
+                        else {
+                            await callback(await QRCode.toBuffer(qr, { type: 'png', margin: 2 }));
+                        }
                     }
                     if (connection === 'open') {
                         connected = true;
@@ -371,6 +410,31 @@ export default class WhatsApp {
                         }
                     }).catch(() => { });
                 });
+                socket.ev.on('presence.update', ({ id, presences }) => {
+                    chain = chain.then(async () => {
+                        const cid = await canonical(id);
+                        for (const [participant, data] of Object.entries(presences)) {
+                            const state = PRESENCE[data.lastKnownPresence];
+                            if (state) {
+                                const who = await canonical(participant || cid);
+                                // `paused` es «dejó de hacer lo que hacía», y sólo el estado
+                                // anterior dice qué era: sin recordarlo no se puede distinguir
+                                // dejar de escribir de dejar de grabar.
+                                // `paused` means «stopped doing what they were doing», and only
+                                // the previous state says which: without remembering it there is
+                                // no telling stopped-typing from stopped-recording.
+                                const last = doing.get(who);
+                                const name = state === 'paused' ? (last === 'recording' ? 'stopped-recording' : 'stopped-typing') : state;
+                                if (state === 'typing' || state === 'recording')
+                                    doing.set(who, state);
+                                else
+                                    doing.delete(who);
+                                const card = deserialize(await engine.get(`/contact/${who}`));
+                                this.emit('contact:presence', new this.Contact(card ?? { id: who, lid: null, name: null, notify: null, verified_name: null, img_url: null, status: null }), name, this);
+                            }
+                        }
+                    }).catch(() => { });
+                });
                 socket.ev.on('lid-mapping.update', ({ lid, pn }) => {
                     chain = chain.then(async () => {
                         await remember(lid, pn);
@@ -493,7 +557,18 @@ export default class WhatsApp {
                                     continue;
                                 }
                                 const type = { conversation: 'text', extendedTextMessage: 'text', imageMessage: 'image', videoMessage: 'video', audioMessage: 'audio' }[kind ?? ''];
-                                const author = msg.key.participant ?? '';
+                                // El autor de un estado puede llegar por `participant` o por su
+                                // alterno según venga identificado por teléfono o por LID, y se
+                                // guarda canónico como todo lo demás: con el LID crudo el estado
+                                // queda a nombre de un número larguísimo que no case con ningún
+                                // contacto, y para quien mira es un estado que no llegó.
+                                // A status author can arrive via `participant` or its alternate
+                                // depending on whether it is identified by phone or by LID, and
+                                // is stored canonically like everything else: with the raw LID
+                                // the status ends up under a long meaningless number matching no
+                                // contact, and to whoever looks it is a status that never came.
+                                const claimed = msg.key.participant ?? msg.key.participantAlt ?? '';
+                                const author = claimed ? await canonical(claimed) : '';
                                 if (!type || !author) {
                                     continue;
                                 }

package/package.json

@@ -72,7 +72,7 @@
     "release": "npm publish --access public"
   },
   "types": "./build/esm/index.d.ts",
-  "version": "7.4.2",
+  "version": "8.0.0",
   "engines": {
     "node": ">=20"
   },