@arcaelas/whatsapp 4.5.0 → 5.1.0

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

@@ -3,12 +3,10 @@
  * @description Orquestador principal del cliente WhatsApp v3.
  * Main orchestrator of the WhatsApp v3 client.
  */
-import { type WASocket } from 'baileys';
-import { EventEmitter } from 'node:events';
-import { chat } from '../../lib/chat/index.js';
-import { contact } from '../../lib/contact/index.js';
-import { message, Message } from '../../lib/message/index.js';
-import Feed from '../../lib/status/index.js';
+import { chat, Chat } from '../../lib/chat/index.js';
+import { contact, Contact } from '../../lib/contact/index.js';
+import { Audio, Document, Event, Image, Location, Message, Poll, Sticker, Text, VCard, Video } from '../../lib/message/index.js';
+import { Feed } from '../../lib/status/index.js';
 import { type Engine } from '../../lib/store/index.js';
 /**
  * Opciones del cliente WhatsApp.
@@ -30,14 +28,17 @@ export type ReconnectOption = boolean | number | {
 export interface IWhatsApp {
     /** Motor de almacenamiento. / Storage engine. */
     engine: Engine;
-    /** Teléfono para emparejamiento por PIN (OTP). / Phone for PIN pairing (OTP). */
+    /**
+     * Teléfono de la cuenta. Su presencia habilita el emparejamiento por PIN; sin él la
+     * vinculación es siempre por QR.
+     * Account phone. Its presence enables PIN pairing; without it linking is always by QR.
+     */
     phone?: number | string;
     /**
-     * Fuerza el método de vinculación. Tiene precedencia sobre la heurística por `phone`:
-     * `auth = method ?? (phone ? 'otp' : 'qr')`. `otp` requiere `phone`.
-     *
-     * Forces the linking method, taking precedence over the phone heuristic:
-     * `auth = method ?? (phone ? 'otp' : 'qr')`. `otp` requires `phone`.
+     * Elige el canal de vinculación **cuando hay `phone`**: `otp` (default) o `qr`. Sin
+     * `phone` la opción se ignora, porque el PIN no puede pedirse sin número.
+     * Picks the linking channel **when `phone` is set**: `otp` (default) or `qr`. Without
+     * `phone` it is ignored, since a PIN cannot be requested without a number.
      */
     method?: 'qr' | 'otp';
     /**
@@ -64,11 +65,13 @@ export interface IWhatsApp {
  * Disconnect options.
  */
 export interface DisconnectOptions {
-    /** No emitir evento de cierre. / Suppress close emission. */
+    /** No emitir el evento `disconnected` de este cierre. / Suppress this close's `disconnected` event. */
     silent?: boolean;
     /** Vaciar el engine tras cerrar. / Clear the engine after closing. */
     destroy?: boolean;
 }
+/** Argumentos de un estático de envío sin el cliente ni el cid. / Send-static arguments without client and cid. */
+type Tail<P extends unknown[]> = P extends [unknown, unknown, ...infer R] ? R : never;
 type MessageInstance = Message;
 type ChatInstance = InstanceType<ReturnType<typeof chat>>;
 type ContactInstance = InstanceType<ReturnType<typeof contact>>;
@@ -113,26 +116,69 @@ interface WhatsAppEventMap {
  * await wa.connect((code) => console.log(code));
  */
 export declare class WhatsApp {
-    private readonly _phone?;
-    private readonly _method?;
-    /** @internal */
-    readonly _event: EventEmitter<WhatsAppEventMap>;
-    private readonly _autoclean;
-    private readonly _reconnect;
-    private readonly _sync;
-    /** @internal */
-    _socket: WASocket | null;
-    private _intentional_close;
-    private _has_connected;
-    private _retry_timer;
-    private _retry_count;
+    #private;
+    /** Motor de almacenamiento de la sesión. / Session storage engine. */
     readonly engine: Engine;
+    /** Entidad `Contact` ligada a este cliente. / `Contact` entity bound to this client. */
     readonly Contact: ReturnType<typeof contact>;
+    /** Entidad `Chat` ligada a este cliente. / `Chat` entity bound to this client. */
     readonly Chat: ReturnType<typeof chat>;
-    readonly Message: ReturnType<typeof message>;
+    /**
+     * Entidad `Message` ligada a este cliente: los mismos estáticos de `Message` sin repetir
+     * la instancia, más las subclases para `instanceof`.
+     * `Message` entity bound to this client: the same `Message` statics without repeating the
+     * instance, plus the subclasses for `instanceof`.
+     */
+    readonly Message: {
+        get: (cid: string, mid: string) => ReturnType<typeof Message.get>;
+        list: (cid: string, offset?: number, limit?: number) => ReturnType<typeof Message.list>;
+        text: (cid: string, ...rest: Tail<Parameters<typeof Message.text>>) => ReturnType<typeof Message.text>;
+        image: (cid: string, ...rest: Tail<Parameters<typeof Message.image>>) => ReturnType<typeof Message.image>;
+        video: (cid: string, ...rest: Tail<Parameters<typeof Message.video>>) => ReturnType<typeof Message.video>;
+        audio: (cid: string, ...rest: Tail<Parameters<typeof Message.audio>>) => ReturnType<typeof Message.audio>;
+        location: (cid: string, ...rest: Tail<Parameters<typeof Message.location>>) => ReturnType<typeof Message.location>;
+        poll: (cid: string, ...rest: Tail<Parameters<typeof Message.poll>>) => ReturnType<typeof Message.poll>;
+        document: (cid: string, ...rest: Tail<Parameters<typeof Message.document>>) => ReturnType<typeof Message.document>;
+        vcard: (cid: string, ...rest: Tail<Parameters<typeof Message.vcard>>) => ReturnType<typeof Message.vcard>;
+        event: (cid: string, ...rest: Tail<Parameters<typeof Message.event>>) => ReturnType<typeof Message.event>;
+        react: (cid: string, mid: string, emoji: string) => Promise<boolean>;
+        star: (cid: string, mid: string, value: boolean) => Promise<boolean>;
+        seen: (cid: string, mid: string) => Promise<boolean>;
+        edit: (cid: string, mid: string, caption: string) => Promise<boolean>;
+        forward: (cid: string, mid: string, target: string | Chat | Contact) => Promise<boolean>;
+        delete: (cid: string, mid: string, all?: boolean) => Promise<boolean>;
+        reactions: (cid: string, mid: string) => Promise<{
+            emoji: string;
+            count: number;
+        }[]>;
+        Text: typeof Text;
+        Image: typeof Image;
+        Video: typeof Video;
+        Audio: typeof Audio;
+        Sticker: typeof Sticker;
+        Document: typeof Document;
+        Location: typeof Location;
+        Poll: typeof Poll;
+        VCard: typeof VCard;
+        Event: typeof Event;
+    };
     constructor(options: IWhatsApp);
-    /** @internal */
-    private _parse_reconnect;
+    /**
+     * Contacto de la cuenta autenticada, o null mientras no hay sesión abierta.
+     * Authenticated account's contact, or null while there is no open session.
+     */
+    get contact(): InstanceType<ReturnType<typeof contact>> | null;
+    /**
+     * Emite un evento del cliente. Lo usan las entidades de la librería para propagar los
+     * cambios que provocan; el consumidor puede emitir los suyos para pruebas.
+     * Emits a client event. Library entities use it to propagate the changes they cause;
+     * consumers may emit their own for testing.
+     *
+     * @param event - Nombre del evento / Event name
+     * @param args - Argumentos del evento / Event arguments
+     * @returns true si había listeners / true when listeners were present
+     */
+    emit<E extends keyof WhatsAppEventMap>(event: E, ...args: WhatsAppEventMap[E]): boolean;
     /**
      * Registra un listener de evento. Retorna función para desuscribirse.
      * Registers an event listener. Returns an unsubscribe function.
@@ -148,12 +194,6 @@ export declare class WhatsApp {
      * Registers a one-shot listener. Returns an unsubscribe function.
      */
     once<E extends keyof WhatsAppEventMap>(event: E, handler: (...args: WhatsAppEventMap[E]) => void): () => void;
-    /**
-     * @internal
-     * Normaliza cualquier identificador (JID, LID, número, etc.) a JID canónico.
-     * Uso interno de la librería — no forma parte de la API pública.
-     */
-    _resolve_jid(uid: string): Promise<string | null>;
     /**
      * Inicia la conexión. El callback recibe el PIN (string) si se configuró `phone`, o el QR (Buffer PNG) si no.
      * Resuelve cuando la sesión sincroniza; reintenta automáticamente en cierres no-loggedOut.
@@ -163,44 +203,42 @@ export declare class WhatsApp {
      */
     connect(callback: (auth: string | Buffer) => void | Promise<void>): Promise<void>;
     /**
-     * Cierra la conexión. Con `destroy: true` vacía el engine completo.
-     * Closes the connection. With `destroy: true` clears the engine entirely.
+     * Actualiza el perfil de la cuenta en WhatsApp: nombre público, bio y/o foto. Sólo se
+     * envía lo que llega en el parche; `photo: null` elimina la foto actual.
+     * Updates the account profile on WhatsApp: public name, bio and/or picture. Only the
+     * given fields are sent; `photo: null` removes the current picture.
+     *
+     * @param patch - Campos a actualizar / Fields to update
+     * @returns true si todo lo pedido se envió / true when everything requested was sent
+     * @throws ERR_PROFILE_PICTURE_LIB si falta `sharp` o `jimp` para procesar la foto / when `sharp` or `jimp` is missing to process the picture
      */
-    disconnect(options?: DisconnectOptions): Promise<void>;
+    profile(patch: {
+        name?: string;
+        content?: string;
+        photo?: string | Buffer | null;
+    }): Promise<boolean>;
     /**
-     * Conecta los handlers de eventos de baileys: contactos, chats y mensajes.
-     * Wires baileys event handlers: contacts, chats and messages.
+     * Publica un estado (status broadcast). Con sólo `caption` publica texto; con `content`
+     * publica imagen o video (el tipo se deduce del binario) usando `caption` como pie.
+     * `contacts` es la audiencia: WhatsApp no reparte el estado a quien no esté en la lista.
+     * Publishes a status broadcast. With only `caption` it posts text; with `content` it
+     * posts an image or video (type inferred from the binary) using `caption` as its footer.
+     * `contacts` is the audience: WhatsApp does not deliver the status to anyone outside it.
      *
-     * @internal
+     * @param post - Contenido, pie y audiencia / Content, caption and audience
+     * @returns Publicación creada, o null si no hay sesión / Created post, or null without a session
+     * @throws ERR_FEED_EMPTY sin `content` ni `caption` / when neither `content` nor `caption` is given
+     * @throws ERR_FEED_MEDIA si el binario no es imagen ni video / when the binary is neither image nor video
      */
-    private _attach_business_handlers;
+    feed(post: {
+        content?: Buffer;
+        caption?: string;
+        contacts: (string | number)[];
+    }): Promise<Feed | null>;
     /**
-     * Persiste un contacto y su índice LID; emite `contact:created` solo si es nuevo.
-     * Persists a contact and its LID index; emits `contact:created` only when new.
-     *
-     * @param raw - Documento del contacto a persistir / Contact document to persist
-     * @internal
+     * Cierra la conexión. Con `destroy: true` vacía el engine completo.
+     * Closes the connection. With `destroy: true` clears the engine entirely.
      */
-    private _persist_contact;
-    /** @internal */
-    private _handle_contacts_upsert;
-    /** @internal */
-    private _handle_contacts_update;
-    /** @internal */
-    private _handle_lid_mapping;
-    /** @internal */
-    private _handle_chats_upsert;
-    /** @internal */
-    private _handle_chats_update;
-    /** @internal */
-    private _handle_chats_delete;
-    /** @internal */
-    private _handle_message_receipt;
-    /** @internal */
-    private _handle_messages_upsert;
-    /** @internal */
-    private _handle_messages_update;
-    /** @internal */
-    private _handle_messages_reaction;
+    disconnect(options?: DisconnectOptions): Promise<void>;
 }
 export default WhatsApp;