@arcaelas/whatsapp 7.4.2 → 8.2.0

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);
@@ -514,7 +578,15 @@ class WhatsApp {
                                     ];
                                     await engine.set(found.path, (0, store_1.serialize)(found.doc), found.doc.created_at);
                                     const instance = new message_1.default(init, found.doc);
-                                    this.emit('message:reacted', instance, await instance.chat(), emoji, this);
+                                    // Quién reaccionó viaja en el evento: sin él, distinguir la
+                                    // reacción del usuario del eco de una propia obligaba a cada
+                                    // consumidor a llevar su propio registro de ecos con timeouts.
+                                    // Who reacted travels in the event: without it, telling the
+                                    // user's reaction from the echo of an own one forced every
+                                    // consumer to keep its own echo ledger with timeouts.
+                                    const who = await canonical(author);
+                                    const card = (0, store_1.deserialize)(await engine.get(`/contact/${who}`));
+                                    this.emit('message:reacted', instance, await instance.chat(), emoji, new this.Contact(card ?? { id: who, lid: null, name: null, notify: null, verified_name: null, img_url: null, status: null }), this);
                                 }
                                 continue;
                             }
@@ -531,7 +603,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;
                                 }
@@ -559,6 +642,45 @@ class WhatsApp {
                                 this.emit('feed:created', new status_1.Feed(init, doc), this);
                                 continue;
                             }
+                            if (kind === 'encEventResponseMessage') {
+                                const enc = msg.message?.encEventResponseMessage;
+                                const key = enc?.eventCreationMessageKey;
+                                const found = key?.id && key.remoteJid ? await locate(key.remoteJid, key.id) : null;
+                                const raw_secret = found?.doc.raw.message?.messageContextInfo?.messageSecret;
+                                const secret = typeof raw_secret === 'string' ? Buffer.from(raw_secret, 'base64') : raw_secret;
+                                if (found && secret && enc?.encPayload && enc.encIv) {
+                                    const mine = [socket.user?.lid, socket.user?.id];
+                                    const theirs = (from) => [from.remoteJid, from.participant, from.remoteJidAlt];
+                                    const responders = (msg.key.fromMe ? mine : theirs(msg.key)).filter((id) => Boolean(id));
+                                    const creators = (found.doc.raw.key?.fromMe ? mine : theirs(found.doc.raw.key ?? {})).filter((id) => Boolean(id));
+                                    for (const pair of responders.flatMap((who) => creators.map((creator) => [who, creator]))) {
+                                        try {
+                                            const parsed = (0, baileys_1.decryptEventResponse)({ encPayload: enc.encPayload, encIv: enc.encIv }, {
+                                                eventCreatorJid: (0, baileys_1.jidNormalizedUser)(pair[1]),
+                                                eventMsgId: found.doc.id,
+                                                eventEncKey: secret,
+                                                responderJid: (0, baileys_1.jidNormalizedUser)(pair[0]),
+                                            });
+                                            const response = { 1: 'going', 2: 'not_going', 3: 'maybe' }[parsed.response];
+                                            if (response) {
+                                                const author = await canonical((0, baileys_1.jidNormalizedUser)((msg.key.fromMe ? socket.user?.id : msg.key.participant ?? cid) ?? cid));
+                                                found.doc.responses = [
+                                                    ...(found.doc.responses ?? []).filter((entry) => entry.author !== author),
+                                                    { author, response, guests: Number(parsed.extraGuestCount ?? 0), at: (Number(msg.messageTimestamp) || Math.floor(Date.now() / 1_000)) * 1_000 },
+                                                ];
+                                                await engine.set(found.path, (0, store_1.serialize)(found.doc), found.doc.created_at);
+                                                const instance = new message_1.default(init, found.doc);
+                                                this.emit('message:updated', instance, await instance.chat(), this);
+                                            }
+                                            break;
+                                        }
+                                        catch {
+                                            /* identidad equivocada / wrong identity */
+                                        }
+                                    }
+                                }
+                                continue;
+                            }
                             if (kind === 'pollUpdateMessage') {
                                 const key = msg.message?.pollUpdateMessage?.pollCreationMessageKey;
                                 const vote = msg.message?.pollUpdateMessage?.vote;

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

@@ -4,10 +4,10 @@
  * Chat entity — individual and group conversations.
  */
 import type { WASocket } from 'baileys';
-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.
@@ -86,7 +86,7 @@ export declare function chat(init: {
          * @param limit - Tamaño de página / Page size
          * @returns Página de contactos / Contact page
          */
-        members(offset?: number, limit?: number): Promise<Contact[]>;
+        members(offset?: number, limit?: number): Promise<InstanceType<typeof init.wa.Contact>[]>;
         /**
          * Descripción: el asunto del grupo o, en un 1:1, la bio del contacto. Es asíncrono
          * porque ninguna de las dos vive en el documento del chat.
@@ -147,6 +147,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.
@@ -203,7 +220,7 @@ export declare function chat(init: {
          * @param limit - Tamaño de página / Page size
          * @returns Página de contactos / Contact page
          */
-        members(offset?: number, limit?: number): Promise<Contact[]>;
+        members(offset?: number, limit?: number): Promise<InstanceType<typeof init.wa.Contact>[]>;
         /**
          * Descripción: el asunto del grupo o, en un 1:1, la bio del contacto. Es asíncrono
          * porque ninguna de las dos vive en el documento del chat.
@@ -264,6 +281,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.
@@ -319,7 +353,7 @@ export declare function chat(init: {
          * @param limit - Tamaño de página / Page size
          * @returns Página de contactos / Contact page
          */
-        members(offset?: number, limit?: number): Promise<Contact[]>;
+        members(offset?: number, limit?: number): Promise<InstanceType<typeof init.wa.Contact>[]>;
         /**
          * Descripción: el asunto del grupo o, en un 1:1, la bio del contacto. Es asíncrono
          * porque ninguna de las dos vive en el documento del chat.
@@ -380,6 +414,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;
@@ -75,6 +76,13 @@ export declare function contact(init: Init): {
         img_url?: string | null;
         status?: string | null;
     }): {
+        /**
+         * true cuando este contacto es la propia cuenta. La comparación cubre JID y LID porque
+         * la cuenta se anuncia por cualquiera de los dos según el chat.
+         * true when this contact is the account itself. The comparison covers JID and LID
+         * because the account announces itself through either depending on the chat.
+         */
+        get me(): boolean;
         /**
          * Chat 1:1 del contacto: el persistido, o una instancia mínima.
          * The contact's 1:1 chat: the persisted one, or a minimal instance.
@@ -82,6 +90,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;
@@ -113,6 +139,13 @@ export declare function contact(init: Init): {
      * @returns Contacto, o null si no existe en WhatsApp / Contact, or null when not on WhatsApp
      */
     get(uid: string | number): Promise<{
+        /**
+         * true cuando este contacto es la propia cuenta. La comparación cubre JID y LID porque
+         * la cuenta se anuncia por cualquiera de los dos según el chat.
+         * true when this contact is the account itself. The comparison covers JID and LID
+         * because the account announces itself through either depending on the chat.
+         */
+        get me(): boolean;
         /**
          * Chat 1:1 del contacto: el persistido, o una instancia mínima.
          * The contact's 1:1 chat: the persisted one, or a minimal instance.
@@ -120,6 +153,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;
@@ -150,6 +201,13 @@ export declare function contact(init: Init): {
      * @returns Página de contactos / Contact page
      */
     list(offset?: number, limit?: number): Promise<{
+        /**
+         * true cuando este contacto es la propia cuenta. La comparación cubre JID y LID porque
+         * la cuenta se anuncia por cualquiera de los dos según el chat.
+         * true when this contact is the account itself. The comparison covers JID and LID
+         * because the account announces itself through either depending on the chat.
+         */
+        get me(): boolean;
         /**
          * Chat 1:1 del contacto: el persistido, o una instancia mínima.
          * The contact's 1:1 chat: the persisted one, or a minimal instance.
@@ -157,6 +215,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

@@ -53,6 +53,17 @@ export default class Contact {
  */
 export function contact(init) {
     class _Contact extends Contact {
+        /**
+         * true cuando este contacto es la propia cuenta. La comparación cubre JID y LID porque
+         * la cuenta se anuncia por cualquiera de los dos según el chat.
+         * true when this contact is the account itself. The comparison covers JID and LID
+         * because the account announces itself through either depending on the chat.
+         */
+        get me() {
+            const user = init.socket.user;
+            const mine = [user?.id, user?.lid].filter((id) => Boolean(id)).map((id) => (id.split(':')[0] ?? '').split('@')[0]);
+            return [this.jid, this.lid, this._raw.id].some((id) => id && mine.includes((id.split('@')[0] ?? '')));
+        }
         /**
          * Chat 1:1 del contacto: el persistido, o una instancia mínima.
          * The contact's 1:1 chat: the persisted one, or a minimal instance.
@@ -63,6 +74,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. */
@@ -62,6 +63,12 @@ export default class Message {
             emoji: string;
             at: number;
         }[];
+        responses?: {
+            author: string;
+            response: 'going' | 'not_going' | 'maybe';
+            guests: number;
+            at: number;
+        }[];
         viewed?: boolean | null;
         raw: WAMessage;
     };
@@ -154,6 +161,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 +317,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 {
@@ -370,6 +408,20 @@ export declare class VCard extends Message {
 export declare class Event extends Message {
     /** @internal Bloque del evento en el raw. / Raw event block. */
     get _event(): proto.Message.IEventMessage | null | undefined;
+    /** Asistentes confirmados, acompañantes incluidos. / Confirmed attendees, companions included. */
+    get going(): number;
+    /**
+     * Respuestas de asistencia al evento, con el nombre resuelto de cada contacto y en orden
+     * de llegada — la última es la más reciente.
+     * Attendance responses, with each contact's resolved name, in arrival order — the last one
+     * is the most recent.
+     */
+    attendees(): Promise<{
+        name: string;
+        contact: string;
+        response: 'going' | 'not_going' | 'maybe';
+        guests: number;
+    }[]>;
     /** Nombre del evento. / Event name. */
     get name(): string;
     /** Inicio en ISO UTC. / Start as ISO UTC. */
@@ -428,6 +480,12 @@ export declare function message(init: Init): {
                 emoji: string;
                 at: number;
             }[];
+            responses?: {
+                author: string;
+                response: "going" | "not_going" | "maybe";
+                guests: number;
+                at: number;
+            }[];
             viewed?: boolean | null;
             raw: WAMessage;
         };
@@ -511,6 +569,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>;
         /**