@arcaelas/whatsapp 4.5.0 → 6.0.0

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

@@ -1,65 +1,64 @@
 /**
  * @file contact/index.ts
- * @description Entidad Contact — lectura/escritura documental sobre `wa.engine`.
- * Contact entity — documental read/write over `wa.engine`.
+ * @description Entidad Contact — una ficha mínima derivada del raw del contacto.
+ * Contact entity — a minimal card derived from the raw contact document.
  */
 import { jidNormalizedUser } from 'baileys';
+import { internals } from '../../lib/internal.js';
 import { deserialize, serialize } from '../../lib/store/index.js';
 /**
- * Resuelve el nombre mostrado de un contacto con prioridad local → push → teléfono.
- * Resolves a contact's display name with priority local → push → phone number.
- *
- * @param raw - Documento persistido del contacto / Persisted contact document
- * @returns Nombre mostrado / Display name
- */
-export function contact_name(raw) {
-    return raw.name ?? raw.notify ?? raw.id.split('@')[0];
-}
-/**
- * Clase base del contacto (forma pública, solo lectura).
- * Base Contact class (public shape, read-only).
+ * Clase base del contacto: recibe el raw de baileys y deriva todo con getters.
+ * Base Contact class: receives the baileys raw and derives everything via getters.
  */
 export class Contact {
-    constructor(raw, chat) {
-        this._raw = raw;
-        this._chat = chat;
+    /**
+     * @internal Documento crudo del contacto en snake_case. `id` llega en formato LID o PN
+     * según el addressing; `phone_number` es el JID PN cuando baileys lo conoce.
+     * Raw contact document in snake_case. `id` arrives in LID or PN format depending on
+     * addressing; `phone_number` is the PN JID when baileys knows it.
+     */
+    constructor(_raw) {
+        this._raw = _raw;
     }
-    /** JID único. / Unique JID. */
-    get id() {
-        return this._raw.id;
+    /** Nombre: agenda → público → verificado → teléfono. / Name: address book → public → verified → phone. */
+    get name() {
+        const { name, notify, verified_name } = this._raw;
+        return name ?? notify ?? verified_name ?? this.phone ?? this._raw.id.split('@')[0];
     }
-    /** JID (alias). / JID (alias). */
+    /**
+     * JID legado (`@s.whatsapp.net`): el reportado por baileys o generado desde el id
+     * cuando ya viene en formato PN; null si no es determinable.
+     * Legacy JID (`@s.whatsapp.net`): the one baileys reports or generated from the id
+     * when it is already PN-formatted; null when not determinable.
+     */
     get jid() {
-        return this._raw.id;
+        if (this._raw.phone_number)
+            return jidNormalizedUser(this._raw.phone_number);
+        if (this._raw.id.endsWith('@s.whatsapp.net'))
+            return jidNormalizedUser(this._raw.id);
+        return null;
     }
-    /** LID si está disponible. / LID when available. */
+    /** LID (`@lid`) cuando es definible; null si no. / LID (`@lid`) when definable; null otherwise. */
     get lid() {
-        return this._raw.lid ?? null;
-    }
-    /** Nombre: local → push → teléfono. / Name: local → push → phone. */
-    get name() {
-        return contact_name(this._raw);
+        if (this._raw.lid)
+            return this._raw.lid;
+        if (this._raw.id.endsWith('@lid'))
+            return this._raw.id;
+        return null;
     }
-    /** Número sin formato. / Raw phone number. */
+    /**
+     * Teléfono del contacto, derivado únicamente del JID PN (nunca del LID);
+     * null cuando no hay JID determinable.
+     * Contact phone, derived from the PN JID only (never from the LID);
+     * null when no JID is determinable.
+     */
     get phone() {
-        return this._raw.id.split('@')[0];
+        return this.jid?.split('@')[0] ?? null;
     }
-    /** URL de foto de perfil. / Profile picture URL. */
+    /** URL de la foto de perfil, o null. / Profile picture URL, or null. */
     get photo() {
-        return this._raw.img_url ?? null;
-    }
-    /** Bio del contacto. / Contact bio. */
-    get content() {
-        return this._raw.status ?? '';
-    }
-    /**
-     * Chat 1:1 asociado al contacto. Async por coherencia con `Message.chat()` /
-     * `Message.author()`, aunque la instancia ya está hidratada en memoria.
-     * 1:1 chat associated with the contact. Async for consistency with
-     * `Message.chat()` / `Message.author()`, though already hydrated in memory.
-     */
-    async chat() {
-        return this._chat;
+        const url = this._raw.img_url;
+        return url?.startsWith('http') ? url : null;
     }
 }
 /**
@@ -69,174 +68,81 @@ export class Contact {
  * @param wa - Instancia principal / Main WhatsApp instance
  */
 export function contact(wa) {
-    /**
-     * Descubre el JID canónico y el LID (cuando aplica) de un número consultando al socket.
-     * Discovers the canonical JID and LID (when applicable) of a phone number via the socket.
-     */
-    async function discover_by_phone(phone) {
-        let result = null;
-        if (wa._socket && phone.length > 0) {
-            const found = (await wa._socket.onWhatsApp(phone))?.[0];
-            if (found?.exists) {
-                result = { jid: jidNormalizedUser(found.jid), lid: found.lid ?? null };
-            }
-        }
-        return result;
-    }
-    /**
-     * Obtiene foto y bio del contacto desde el socket.
-     * Fetches profile picture and bio from the socket.
-     */
-    async function fetch_profile_data(id) {
-        let img_url = null;
-        let status = null;
-        if (wa._socket) {
-            try {
-                img_url = (await wa._socket.profilePictureUrl(id, 'image')) ?? null;
-            }
-            catch {
-                /* may not exist */
-            }
-            try {
-                const result = await wa._socket.fetchStatus(id);
-                const data = result?.[0];
-                status = data?.status?.status ?? null;
-            }
-            catch {
-                /* may fail */
-            }
-        }
-        return { img_url, status };
-    }
-    /**
-     * Carga la instancia Chat 1:1 del contacto. Si no existe en engine, fabrica una mínima.
-     * Loads the 1:1 Chat instance for a contact. Falls back to a minimal instance if missing.
-     */
-    async function load_chat_for(jid, fallback_name) {
-        const cached = deserialize(await wa.engine.get(`/chat/${jid}`));
-        return new wa.Chat(cached ?? { id: jid, name: fallback_name });
-    }
     return class _Contact extends Contact {
-        constructor(raw, chat) {
-            super(raw, chat);
-        }
-        /** Chat 1:1 asociado (subclase enriquecida). / Associated 1:1 chat (enriched subclass). */
+        /**
+         * Chat 1:1 del contacto: el persistido en el engine, o una instancia mínima.
+         * The contact's 1:1 chat: the engine-persisted one, or a minimal instance.
+         *
+         * @returns Instancia de Chat / Chat instance
+         */
         async chat() {
-            return this._chat;
-        }
-        /** true si la instancia representa la cuenta autenticada. / true if this instance is the authenticated account. */
-        get me() {
-            const self_id = wa._socket?.user?.id;
-            return Boolean(self_id) && jidNormalizedUser(self_id) === this.id;
+            const cid = this.jid ?? this.lid ?? this._raw.id;
+            const cached = deserialize(await wa.engine.get(`/chat/${cid}`));
+            return new wa.Chat(cached ?? { id: cid, name: this.name });
         }
         /**
-         * Obtiene un contacto. Dispatch inteligente:
-         * - Si `uid` contiene `@` → se interpreta como JID (`@s.whatsapp.net` / `@g.us`) o LID (`@lid`) y se resuelve con el mapping.
-         * - Si no contiene `@` → se limpian los dígitos y se consulta `socket.onWhatsApp(phone)` para obtener el JID canónico.
+         * Carga un contacto por teléfono, JID o LID: primero el engine; si no está
+         * persistido lo descubre por red (`onWhatsApp` + foto + bio) y lo materializa.
+         * Loads a contact by phone, JID or LID: engine first; when not persisted it
+         * discovers it over the network (`onWhatsApp` + photo + bio) and materializes it.
          *
-         * Retrieves a contact. Smart dispatch:
-         * - If `uid` contains `@` → treated as JID or LID, resolved via mapping.
-         * - If `uid` lacks `@` → digits are extracted and `socket.onWhatsApp(phone)` resolves the canonical JID.
+         * @param uid - Teléfono, JID o LID / Phone, JID or LID
+         * @returns Contacto o null si no existe en WhatsApp / Contact or null when not on WhatsApp
          */
         static async get(uid) {
-            let result = null;
-            let jid = null;
-            let lid = null;
-            if (uid.includes('@')) {
-                jid = await wa._resolve_jid(uid);
-            }
-            else {
-                const discovered = await discover_by_phone(uid.replace(/\D+/g, ''));
-                if (discovered) {
-                    jid = discovered.jid;
-                    lid = discovered.lid;
-                }
-            }
+            const digits = String(uid).replace(/\D+/g, '');
+            const jid = String(uid).includes('@')
+                ? await internals(wa).resolve_jid(String(uid))
+                : digits
+                    ? `${digits}@s.whatsapp.net`
+                    : null;
             if (jid && !jid.endsWith('@g.us')) {
                 const cached = deserialize(await wa.engine.get(`/contact/${jid}`));
-                if (cached) {
-                    result = new _Contact(cached, await load_chat_for(jid, contact_name(cached)));
-                }
-                else if (wa._socket) {
-                    const needs_check = !lid && !uid.endsWith('@lid');
-                    const discovered = needs_check
-                        ? await discover_by_phone(jid.split('@')[0])
-                        : { jid, lid };
-                    if (discovered) {
-                        const { img_url, status } = await fetch_profile_data(discovered.jid);
+                if (cached)
+                    return new _Contact(cached);
+                const socket = internals(wa).socket;
+                if (socket) {
+                    const found = (await socket.onWhatsApp(jid.split('@')[0]))?.[0];
+                    if (found?.exists) {
+                        const id = jidNormalizedUser(found.jid);
+                        const img_url = await socket.profilePictureUrl(id, 'image').catch(() => null);
+                        const status = await socket
+                            .fetchStatus(id)
+                            .then((result) => result?.[0]?.status?.status ?? null)
+                            .catch(() => null);
                         const raw = {
-                            id: discovered.jid,
-                            lid: discovered.lid,
+                            id,
+                            lid: found.lid ?? null,
+                            phone_number: id,
                             name: null,
                             notify: null,
                             verified_name: null,
-                            img_url,
+                            img_url: img_url ?? null,
                             status,
                         };
-                        await wa.engine.set(`/contact/${discovered.jid}`, serialize(raw));
-                        if (discovered.lid) {
-                            await wa.engine.set(`/lid/${discovered.lid}`, serialize(discovered.jid));
+                        await wa.engine.set(`/contact/${id}`, serialize(raw));
+                        if (found.lid) {
+                            await wa.engine.set(`/lid/${found.lid}`, serialize(id));
                         }
-                        result = new _Contact(raw, await load_chat_for(discovered.jid, discovered.jid.split('@')[0]));
+                        return new _Contact(raw);
                     }
                 }
             }
-            return result;
+            return null;
         }
         /**
-         * Pagina los contactos persistidos por mtime DESC, pre-cargando el chat de cada uno.
-         * Paginates persisted contacts by mtime DESC, pre-loading the chat of each one.
+         * Pagina los contactos persistidos.
+         * Paginates persisted contacts.
+         *
+         * @param offset - Desplazamiento / Offset
+         * @param limit - Tamaño de página / Page size
+         * @returns Página de contactos / Contact page
          */
         static async list(offset = 0, limit = 50) {
-            const contacts = [];
-            for (const raw of await wa.engine.list('/contact', offset, limit)) {
-                const parsed = deserialize(raw);
-                if (parsed) {
-                    contacts.push(new _Contact(parsed, await load_chat_for(parsed.id, contact_name(parsed))));
-                }
-            }
-            return contacts;
-        }
-        /**
-         * Renombra localmente un contacto por id.
-         * Renames a contact locally by id.
-         */
-        static async rename(uid, name) {
-            const c = await _Contact.get(uid);
-            return c ? c.rename(name) : false;
-        }
-        /**
-         * Re-hidrata los datos del contacto por id desde el socket.
-         * Re-hydrates contact data from the socket by id.
-         */
-        static async refresh(uid) {
-            const c = await _Contact.get(uid);
-            return c ? c.refresh() : null;
-        }
-        /**
-         * Renombra el contacto localmente (solo agenda del dispositivo).
-         * Renames the contact locally (device address book only).
-         */
-        async rename(name) {
-            this._raw.name = name;
-            await wa.engine.set(`/contact/${this.id}`, serialize(this._raw));
-            return true;
-        }
-        /**
-         * Re-hidrata foto y bio desde el socket.
-         * Re-hydrates profile picture and bio from the socket.
-         */
-        async refresh() {
-            let ok = false;
-            if (wa._socket) {
-                const { img_url, status } = await fetch_profile_data(this.id);
-                this._raw.img_url = img_url;
-                this._raw.status = status;
-                await wa.engine.set(`/contact/${this.id}`, serialize(this._raw));
-                ok = true;
-            }
-            return ok ? this : null;
+            return (await wa.engine.list('/contact', offset, limit))
+                .map((raw) => deserialize(raw))
+                .filter((parsed) => parsed !== null)
+                .map((parsed) => new _Contact(parsed));
         }
     };
 }
-//# sourceMappingURL=index.js.map

package/build/esm/lib/internal.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file internal.ts
+ * @description Canal privado entre el cliente y sus entidades. Vive en un `WeakMap` fuera de
+ * la instancia, así el socket de baileys y la resolución de JIDs quedan disponibles para
+ * `Contact`, `Chat`, `Message` y `Feed` sin exponerse en la superficie pública de `WhatsApp`:
+ * el consumidor sólo ve `on`/`once`/`off`/`emit` y los métodos documentados.
+ * Private channel between the client and its entities. It lives in a `WeakMap` outside the
+ * instance, so the baileys socket and JID resolution stay available to `Contact`, `Chat`,
+ * `Message` and `Feed` without surfacing on `WhatsApp`'s public API: consumers only see
+ * `on`/`once`/`off`/`emit` and the documented methods.
+ */
+import type { WASocket } from 'baileys';
+/**
+ * Estado que el cliente comparte con sus entidades.
+ * State the client shares with its entities.
+ */
+export interface Internals {
+    /** Socket vivo de baileys, o null mientras no hay conexión. / Live baileys socket, or null while disconnected. */
+    socket: WASocket | null;
+    /** Normaliza cualquier identificador (JID, LID o teléfono) a JID canónico. / Normalizes any identifier (JID, LID or phone) into a canonical JID. */
+    resolve_jid(uid: string): Promise<string | null>;
+}
+/**
+ * Publica el estado interno de un cliente para las entidades de la librería.
+ * Publishes a client's internal state for the library entities.
+ *
+ * @param owner - Cliente dueño del estado / Client owning the state
+ * @param state - Estado compartido, mutable por el cliente / Shared state, mutated by the client
+ */
+export declare function bind(owner: object, state: Internals): void;
+/**
+ * Estado interno del cliente. Sólo lo resuelven los módulos de la librería: el objeto
+ * nunca se expone al consumidor.
+ * A client's internal state. Only library modules resolve it: the object is never exposed
+ * to the consumer.
+ *
+ * @param owner - Cliente construido por la librería / Client built by the library
+ * @returns Estado compartido / Shared state
+ */
+export declare function internals(owner: object): Internals;

package/build/esm/lib/internal.js

@@ -0,0 +1,34 @@
+/**
+ * @file internal.ts
+ * @description Canal privado entre el cliente y sus entidades. Vive en un `WeakMap` fuera de
+ * la instancia, así el socket de baileys y la resolución de JIDs quedan disponibles para
+ * `Contact`, `Chat`, `Message` y `Feed` sin exponerse en la superficie pública de `WhatsApp`:
+ * el consumidor sólo ve `on`/`once`/`off`/`emit` y los métodos documentados.
+ * Private channel between the client and its entities. It lives in a `WeakMap` outside the
+ * instance, so the baileys socket and JID resolution stay available to `Contact`, `Chat`,
+ * `Message` and `Feed` without surfacing on `WhatsApp`'s public API: consumers only see
+ * `on`/`once`/`off`/`emit` and the documented methods.
+ */
+const channel = new WeakMap();
+/**
+ * Publica el estado interno de un cliente para las entidades de la librería.
+ * Publishes a client's internal state for the library entities.
+ *
+ * @param owner - Cliente dueño del estado / Client owning the state
+ * @param state - Estado compartido, mutable por el cliente / Shared state, mutated by the client
+ */
+export function bind(owner, state) {
+    channel.set(owner, state);
+}
+/**
+ * Estado interno del cliente. Sólo lo resuelven los módulos de la librería: el objeto
+ * nunca se expone al consumidor.
+ * A client's internal state. Only library modules resolve it: the object is never exposed
+ * to the consumer.
+ *
+ * @param owner - Cliente construido por la librería / Client built by the library
+ * @returns Estado compartido / Shared state
+ */
+export function internals(owner) {
+    return channel.get(owner);
+}