@arcaelas/whatsapp 4.4.0 → 5.1.0

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

@@ -1,62 +1,60 @@
 /**
  * @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 { Chat } from '../../lib/chat';
 import type { WhatsApp } from '../../lib/whatsapp';
 /**
- * Shape persistido del contacto.
- * Persisted contact shape.
- */
-export interface IContactRaw {
-    id: string;
-    lid?: string | null;
-    name?: string | null;
-    notify?: string | null;
-    verified_name?: string | null;
-    img_url?: string | null;
-    status?: string | null;
-}
-/**
- * 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 declare function contact_name(raw: IContactRaw): string;
-/**
- * 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 declare class Contact {
-    /** @internal Shape persistido. Uso interno (convención underscore). / Internal persisted shape. */
-    readonly _raw: IContactRaw;
-    /** @internal Chat 1:1 asociado ya hidratado. / Internal already-hydrated 1:1 chat. */
-    readonly _chat: Chat;
-    constructor(raw: IContactRaw, chat: Chat);
-    /** JID único. / Unique JID. */
-    get id(): string;
-    /** JID (alias). / JID (alias). */
-    get jid(): string;
-    /** LID si está disponible. / LID when available. */
-    get lid(): string | null;
-    /** Nombre: local → push → teléfono. / Name: local → push → phone. */
+    readonly _raw: {
+        id: string;
+        lid?: string | null;
+        phone_number?: string | null;
+        name?: string | null;
+        notify?: string | null;
+        verified_name?: string | null;
+        img_url?: string | null;
+        status?: string | null;
+    };
+    /**
+     * @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: {
+        id: string;
+        lid?: string | null;
+        phone_number?: string | null;
+        name?: string | null;
+        notify?: string | null;
+        verified_name?: string | null;
+        img_url?: string | null;
+        status?: string | null;
+    });
+    /** Nombre: agenda → público → verificado → teléfono. / Name: address book → public → verified → phone. */
     get name(): string;
-    /** Número sin formato. / Raw phone number. */
-    get phone(): string;
-    /** URL de foto de perfil. / Profile picture URL. */
-    get photo(): string | null;
-    /** Bio del contacto. / Contact bio. */
-    get content(): string;
     /**
-     * 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.
+     * 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.
      */
-    chat(): Promise<Chat>;
+    get jid(): string | null;
+    /** LID (`@lid`) cuando es definible; null si no. / LID (`@lid`) when definable; null otherwise. */
+    get lid(): string | null;
+    /**
+     * 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(): string | null;
+    /** URL de la foto de perfil, o null. / Profile picture URL, or null. */
+    get photo(): string | null;
 }
 /**
  * Factoría de Contact ligada al contexto WhatsApp.
@@ -65,162 +63,147 @@ export declare class Contact {
  * @param wa - Instancia principal / Main WhatsApp instance
  */
 export declare function contact(wa: WhatsApp): {
-    new (raw: IContactRaw, chat: InstanceType<typeof wa.Chat>): {
-        /** @internal Chat 1:1 hidratado como subclase enriquecida. / Internal hydrated 1:1 chat as enriched subclass. */
-        readonly _chat: InstanceType<typeof wa.Chat>;
-        /** Chat 1:1 asociado (subclase enriquecida). / Associated 1:1 chat (enriched subclass). */
-        chat(): Promise<InstanceType<typeof wa.Chat>>;
-        /** true si la instancia representa la cuenta autenticada. / true if this instance is the authenticated account. */
-        get me(): boolean;
+    new (_raw: {
+        id: string;
+        lid?: string | null;
+        phone_number?: string | null;
+        name?: string | null;
+        notify?: string | null;
+        verified_name?: string | null;
+        img_url?: string | null;
+        status?: string | null;
+    }): {
         /**
-         * Renombra el contacto localmente (solo agenda del dispositivo).
-         * Renames the contact locally (device address book only).
+         * 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
          */
-        rename(name: string): Promise<boolean>;
+        chat(): Promise<InstanceType<typeof wa.Chat>>;
+        readonly _raw: {
+            id: string;
+            lid?: string | null;
+            phone_number?: string | null;
+            name?: string | null;
+            notify?: string | null;
+            verified_name?: string | null;
+            img_url?: string | null;
+            status?: string | null;
+        };
+        /** Nombre: agenda → público → verificado → teléfono. / Name: address book → public → verified → phone. */
+        get name(): string;
         /**
-         * Re-hidrata foto y bio desde el socket.
-         * Re-hydrates profile picture and bio from the socket.
+         * 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.
          */
-        refresh(): Promise</*elided*/ any | null>;
-        /** @internal Shape persistido. Uso interno (convención underscore). / Internal persisted shape. */
-        readonly _raw: IContactRaw;
-        /** JID único. / Unique JID. */
-        get id(): string;
-        /** JID (alias). / JID (alias). */
-        get jid(): string;
-        /** LID si está disponible. / LID when available. */
+        get jid(): string | null;
+        /** LID (`@lid`) cuando es definible; null si no. / LID (`@lid`) when definable; null otherwise. */
         get lid(): string | null;
-        /** Nombre: local → push → teléfono. / Name: local → push → phone. */
-        get name(): string;
-        /** Número sin formato. / Raw phone number. */
-        get phone(): string;
-        /** URL de foto de perfil. / Profile picture URL. */
+        /**
+         * 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(): string | null;
+        /** URL de la foto de perfil, o null. / Profile picture URL, or null. */
         get photo(): string | null;
-        /** Bio del contacto. / Contact bio. */
-        get content(): string;
     };
     /**
-     * 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
      */
-    get(uid: string): Promise<{
-        /** @internal Chat 1:1 hidratado como subclase enriquecida. / Internal hydrated 1:1 chat as enriched subclass. */
-        readonly _chat: InstanceType<typeof wa.Chat>;
-        /** Chat 1:1 asociado (subclase enriquecida). / Associated 1:1 chat (enriched subclass). */
-        chat(): Promise<InstanceType<typeof wa.Chat>>;
-        /** true si la instancia representa la cuenta autenticada. / true if this instance is the authenticated account. */
-        get me(): boolean;
+    get(uid: string | number): Promise<{
         /**
-         * Renombra el contacto localmente (solo agenda del dispositivo).
-         * Renames the contact locally (device address book only).
+         * 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
          */
-        rename(name: string): Promise<boolean>;
+        chat(): Promise<InstanceType<typeof wa.Chat>>;
+        readonly _raw: {
+            id: string;
+            lid?: string | null;
+            phone_number?: string | null;
+            name?: string | null;
+            notify?: string | null;
+            verified_name?: string | null;
+            img_url?: string | null;
+            status?: string | null;
+        };
+        /** Nombre: agenda → público → verificado → teléfono. / Name: address book → public → verified → phone. */
+        get name(): string;
         /**
-         * Re-hidrata foto y bio desde el socket.
-         * Re-hydrates profile picture and bio from the socket.
+         * 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.
          */
-        refresh(): Promise</*elided*/ any | null>;
-        /** @internal Shape persistido. Uso interno (convención underscore). / Internal persisted shape. */
-        readonly _raw: IContactRaw;
-        /** JID único. / Unique JID. */
-        get id(): string;
-        /** JID (alias). / JID (alias). */
-        get jid(): string;
-        /** LID si está disponible. / LID when available. */
+        get jid(): string | null;
+        /** LID (`@lid`) cuando es definible; null si no. / LID (`@lid`) when definable; null otherwise. */
         get lid(): string | null;
-        /** Nombre: local → push → teléfono. / Name: local → push → phone. */
-        get name(): string;
-        /** Número sin formato. / Raw phone number. */
-        get phone(): string;
-        /** URL de foto de perfil. / Profile picture URL. */
+        /**
+         * 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(): string | null;
+        /** URL de la foto de perfil, o null. / Profile picture URL, or null. */
         get photo(): string | null;
-        /** Bio del contacto. / Contact bio. */
-        get content(): string;
     } | 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
      */
     list(offset?: number, limit?: number): Promise<{
-        /** @internal Chat 1:1 hidratado como subclase enriquecida. / Internal hydrated 1:1 chat as enriched subclass. */
-        readonly _chat: InstanceType<typeof wa.Chat>;
-        /** Chat 1:1 asociado (subclase enriquecida). / Associated 1:1 chat (enriched subclass). */
-        chat(): Promise<InstanceType<typeof wa.Chat>>;
-        /** true si la instancia representa la cuenta autenticada. / true if this instance is the authenticated account. */
-        get me(): boolean;
         /**
-         * Renombra el contacto localmente (solo agenda del dispositivo).
-         * Renames the contact locally (device address book only).
+         * 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
          */
-        rename(name: string): Promise<boolean>;
-        /**
-         * Re-hidrata foto y bio desde el socket.
-         * Re-hydrates profile picture and bio from the socket.
-         */
-        refresh(): Promise</*elided*/ any | null>;
-        /** @internal Shape persistido. Uso interno (convención underscore). / Internal persisted shape. */
-        readonly _raw: IContactRaw;
-        /** JID único. / Unique JID. */
-        get id(): string;
-        /** JID (alias). / JID (alias). */
-        get jid(): string;
-        /** LID si está disponible. / LID when available. */
-        get lid(): string | null;
-        /** Nombre: local → push → teléfono. / Name: local → push → phone. */
-        get name(): string;
-        /** Número sin formato. / Raw phone number. */
-        get phone(): string;
-        /** URL de foto de perfil. / Profile picture URL. */
-        get photo(): string | null;
-        /** Bio del contacto. / Contact bio. */
-        get content(): string;
-    }[]>;
-    /**
-     * Renombra localmente un contacto por id.
-     * Renames a contact locally by id.
-     */
-    rename(uid: string, name: string): Promise<boolean>;
-    /**
-     * Re-hidrata los datos del contacto por id desde el socket.
-     * Re-hydrates contact data from the socket by id.
-     */
-    refresh(uid: string): Promise<{
-        /** @internal Chat 1:1 hidratado como subclase enriquecida. / Internal hydrated 1:1 chat as enriched subclass. */
-        readonly _chat: InstanceType<typeof wa.Chat>;
-        /** Chat 1:1 asociado (subclase enriquecida). / Associated 1:1 chat (enriched subclass). */
         chat(): Promise<InstanceType<typeof wa.Chat>>;
-        /** true si la instancia representa la cuenta autenticada. / true if this instance is the authenticated account. */
-        get me(): boolean;
+        readonly _raw: {
+            id: string;
+            lid?: string | null;
+            phone_number?: string | null;
+            name?: string | null;
+            notify?: string | null;
+            verified_name?: string | null;
+            img_url?: string | null;
+            status?: string | null;
+        };
+        /** Nombre: agenda → público → verificado → teléfono. / Name: address book → public → verified → phone. */
+        get name(): string;
         /**
-         * Renombra el contacto localmente (solo agenda del dispositivo).
-         * Renames the contact locally (device address book only).
+         * 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.
          */
-        rename(name: string): Promise<boolean>;
+        get jid(): string | null;
+        /** LID (`@lid`) cuando es definible; null si no. / LID (`@lid`) when definable; null otherwise. */
+        get lid(): string | null;
         /**
-         * Re-hidrata foto y bio desde el socket.
-         * Re-hydrates profile picture and bio from the socket.
+         * 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.
          */
-        refresh(): Promise</*elided*/ any | null>;
-        /** @internal Shape persistido. Uso interno (convención underscore). / Internal persisted shape. */
-        readonly _raw: IContactRaw;
-        /** JID único. / Unique JID. */
-        get id(): string;
-        /** JID (alias). / JID (alias). */
-        get jid(): string;
-        /** LID si está disponible. / LID when available. */
-        get lid(): string | null;
-        /** Nombre: local → push → teléfono. / Name: local → push → phone. */
-        get name(): string;
-        /** Número sin formato. / Raw phone number. */
-        get phone(): string;
-        /** URL de foto de perfil. / Profile picture URL. */
+        get phone(): string | null;
+        /** URL de la foto de perfil, o null. / Profile picture URL, or null. */
         get photo(): string | null;
-        /** Bio del contacto. / Contact bio. */
-        get content(): string;
-    } | null>;
+    }[]>;
 };