@arcaelas/whatsapp 3.1.1 → 3.3.0

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

@@ -0,0 +1,277 @@
+/**
+ * @file message/index.ts
+ * @description Entidad Message — una sola clase base que recibe `{wa, doc}` en el constructor.
+ * Subclases especializadas (Text, Image, Video, Audio, Gps, Poll) override `content()` según su tipo.
+ */
+import { type WAMessage } from 'baileys';
+import { Readable } from 'node:stream';
+import { Chat, chat } from '../../lib/chat/index.js';
+import { Contact, contact } from '../../lib/contact/index.js';
+import type { WhatsApp } from '../../lib/whatsapp/index.js';
+/** Destino aceptado por `forward`: CID (string), Chat o Contact. */
+export type ForwardTarget = string | Chat | Contact;
+type ChatInstance = InstanceType<ReturnType<typeof chat>>;
+type ContactInstance = InstanceType<ReturnType<typeof contact>>;
+/** Tipos de mensaje internos (no expuestos como getter público). */
+export type MessageType = 'text' | 'image' | 'video' | 'audio' | 'location' | 'poll';
+export declare enum MessageStatus {
+    ERROR = 0,
+    PENDING = 1,
+    SERVER_ACK = 2,
+    DELIVERED = 3,
+    READ = 4,
+    PLAYED = 5
+}
+export interface SendOptions {
+    mid?: string;
+}
+export interface SendMediaOptions extends SendOptions {
+    caption?: string;
+}
+export interface SendAudioOptions extends SendOptions {
+    ptt?: boolean;
+}
+export interface SendPollOptions extends SendOptions {
+    /** true para selección múltiple; default false (single). / true for multi-select; default false (single). */
+    multiple?: boolean;
+}
+export interface LocationOptions {
+    lat: number;
+    lng: number;
+    live?: boolean;
+}
+export interface PollOptions {
+    content: string;
+    options: Array<{
+        content: string;
+    }>;
+}
+/**
+ * Documento persistido del mensaje.
+ */
+export interface IMessage {
+    id: string;
+    cid: string;
+    mid: string | null;
+    me: boolean;
+    type: MessageType;
+    author: string;
+    status: MessageStatus;
+    starred: boolean;
+    forwarded: boolean;
+    created_at: number;
+    deleted_at: number | null;
+    mime: string;
+    caption: string;
+    edited: boolean;
+    /**
+     * Solo para polls: discriminador explícito de selección múltiple seteado al enviar.
+     * Cuando está definido, `Poll.multiple` lo prefiere sobre el conteo del proto
+     * (WhatsApp normaliza `selectableOptionsCount` en el echo de polls auto-emitidos
+     * y pierde el discriminador, por eso necesitamos persistirlo nosotros).
+     * Poll-only: explicit multi-select flag set at send time. When defined, `Poll.multiple`
+     * prefers it over the proto count (WhatsApp normalizes `selectableOptionsCount` on
+     * own-poll echo, losing the discriminator).
+     */
+    multiple?: boolean;
+    raw: WAMessage;
+}
+/**
+ * Construye el documento IMessage desde el raw de baileys.
+ */
+export declare function build_message_doc(raw: WAMessage, self_id?: string, edited?: boolean): IMessage;
+/**
+ * Clase base del mensaje. Una sola clase — toda la API de instancia vive aquí.
+ * Base message class. Single class — all instance API lives here.
+ */
+export declare class Message {
+    /** @internal */
+    protected readonly _wa: WhatsApp;
+    /** @internal */
+    protected readonly _doc: IMessage;
+    /** @internal Cache de la promesa de `author()` para evitar engine round-trips repetidos. */
+    private _author_cache;
+    /** @internal Cache de la promesa de `chat()` para evitar engine round-trips repetidos. */
+    private _chat_cache;
+    constructor(options: {
+        wa: WhatsApp;
+        doc: IMessage;
+    });
+    get id(): string;
+    get cid(): string;
+    get type(): MessageType;
+    /** JID del autor del mensaje. Para acceso síncrono sin hidratar el Contact. */
+    get from(): string;
+    /** MIME type del contenido. `text/plain` para texto, `application/json` para location/poll, mimetype real para media. */
+    get mime(): string;
+    get mid(): string | null;
+    get me(): boolean;
+    get caption(): string;
+    get starred(): boolean;
+    get forwarded(): boolean;
+    get once(): boolean;
+    get created_at(): number;
+    get deleted_at(): number | null;
+    get status(): MessageStatus;
+    get edited(): boolean;
+    /**
+     * Contacto del autor (resuelve vía `wa.Contact.get`; fallback a instancia mínima).
+     * Memoizado por instancia: la primera llamada va al engine; las siguientes
+     * reutilizan la misma promesa sin nuevos round-trips.
+     * Author contact (resolves via `wa.Contact.get`; falls back to a minimal instance).
+     * Instance-memoized: first call hits the engine; subsequent calls reuse the
+     * same promise without further round-trips.
+     */
+    author(): Promise<ContactInstance>;
+    /**
+     * Chat al que pertenece el mensaje. Memoizado por instancia: la primera llamada
+     * va al engine; las siguientes reutilizan la misma promesa.
+     * Chat the message belongs to. Instance-memoized: first call hits the engine;
+     * subsequent calls reuse the same promise.
+     */
+    chat(): Promise<ChatInstance>;
+    /** Contenido sin parsear, directo del engine. Las subclases override según su tipo. */
+    content(): Promise<Buffer>;
+    /**
+     * Devuelve un `Readable` con los bytes del mensaje. Para media (image/video/audio)
+     * lee desde el cache del engine o, si falta, descarga desde baileys. Para text/location/poll
+     * retorna el mismo binario que `content()` envuelto en un Readable.
+     * Returns a `Readable` of the message bytes. For media (image/video/audio) it reads
+     * from the engine cache or, if missing, downloads from baileys. For text/location/poll
+     * it wraps the `content()` buffer in a Readable.
+     */
+    stream(): Promise<Readable>;
+    /** Reacciona al mensaje (emoji vacío para retirar). */
+    react(emoji: string): Promise<boolean>;
+    /** Reenvía el mensaje a un destino (CID, Chat o Contact). */
+    forward(target: ForwardTarget): Promise<boolean>;
+    /** Marca el mensaje como leído. */
+    seen(): Promise<boolean>;
+    /** Destaca/retira destacado del mensaje. */
+    star(value: boolean): Promise<boolean>;
+    /** Elimina el mensaje. `all=true` (default) borra para todos; `all=false` borra sólo en mi dispositivo. */
+    delete(all?: boolean): Promise<boolean>;
+    /** Edita el texto/caption del mensaje (solo propios editables). */
+    edit(text: string): Promise<boolean>;
+    /** Observa cambios sobre este mensaje. Retorna unsubscribe. / Watches this message. Returns unsubscribe. */
+    watch(handler: (msg: Message) => void): () => void;
+    /** Responde con texto. */
+    text(caption: string, opts?: SendOptions): Promise<Message | null>;
+    /** Responde con imagen. */
+    image(buf: Buffer, opts?: SendMediaOptions): Promise<Message | null>;
+    /** Responde con video. */
+    video(buf: Buffer, opts?: SendMediaOptions): Promise<Message | null>;
+    /** Responde con audio. */
+    audio(buf: Buffer, opts?: SendAudioOptions): Promise<Message | null>;
+    /** Responde con ubicación. */
+    location(loc: LocationOptions, opts?: SendOptions): Promise<Message | null>;
+    /** Responde con encuesta. */
+    poll(poll: PollOptions, opts?: SendPollOptions): Promise<Message | null>;
+}
+/**
+ * Mensaje de texto. Override `content()` para retornar el caption como Buffer sin pasar por engine.
+ * Text message. Overrides `content()` returning caption as Buffer directly.
+ */
+export declare class Text extends Message {
+    content(): Promise<Buffer>;
+}
+/**
+ * Mensaje de imagen. Hereda `stream()` de la clase base; `content()` drena el stream.
+ * Image message. Inherits `stream()` from the base class; `content()` drains the stream.
+ */
+export declare class Image extends Message {
+    content(): Promise<Buffer>;
+}
+/**
+ * Mensaje de video. Hereda `stream()` de la clase base; `content()` drena el stream.
+ * Video message. Inherits `stream()` from the base class; `content()` drains the stream.
+ */
+export declare class Video extends Message {
+    content(): Promise<Buffer>;
+}
+/**
+ * Mensaje de audio. Hereda `stream()` de la clase base; `content()` drena el stream.
+ * `ptt` indica si es nota de voz (push-to-talk).
+ * Audio message. Inherits `stream()` from the base class; `content()` drains the stream.
+ * `ptt` flags voice notes.
+ */
+export declare class Audio extends Message {
+    /** true si es nota de voz (push-to-talk). / true if push-to-talk voice note. */
+    get ptt(): boolean;
+    content(): Promise<Buffer>;
+}
+/**
+ * Mensaje de ubicación. Agrega getters sync `lat`, `lng`, `link` derivados del raw.
+ * Location message. Adds sync getters `lat`, `lng`, `link` derived from raw.
+ */
+export declare class Gps extends Message {
+    private get _loc();
+    /** Latitud en grados. / Latitude in degrees. */
+    get lat(): number;
+    /** Longitud en grados. / Longitude in degrees. */
+    get lng(): number;
+    /** URL de Google Maps apuntando a la coordenada. / Google Maps URL for the coordinate. */
+    get link(): string;
+    /** true si es ubicación en tiempo real. / true when live location. */
+    get live(): boolean;
+}
+/**
+ * Mensaje de encuesta. `caption` es la pregunta (heredada); agrega `options[]` con conteo y `multiple`.
+ * Poll message. `caption` is the question (inherited); adds `options[]` with counts and `multiple`.
+ */
+export declare class Poll extends Message {
+    private get _poll();
+    /**
+     * true si admite múltiples respuestas. Lee primero el flag explícito persistido
+     * al enviar (caso propio, donde WhatsApp pierde el discriminador en el echo);
+     * fallback al `selectableOptionsCount` del proto (polls foráneos o de UI móvil).
+     * true if the poll accepts multiple answers. Prefers the persisted send-time
+     * flag (own polls, since WhatsApp drops the discriminator on echo); falls back
+     * to the proto `selectableOptionsCount` (foreign or mobile-UI polls).
+     */
+    get multiple(): boolean;
+    /** Opciones con conteo de votos actualizado. / Options with up-to-date vote counts. */
+    get options(): {
+        content: string;
+        count: number;
+    }[];
+    /**
+     * Vota en la encuesta. Acepta un índice o lista de índices (para `multiple`).
+     * Votes in the poll. Accepts a single index or list (for `multiple`).
+     */
+    select(index: number | number[]): Promise<boolean>;
+}
+/**
+ * Factoría que enlaza los statics a `wa` y expone las subclases.
+ * Factory binding statics to `wa` and exposing subclasses.
+ */
+export declare function message(wa: WhatsApp): {
+    Text: typeof Text;
+    Image: typeof Image;
+    Video: typeof Video;
+    Audio: typeof Audio;
+    Gps: typeof Gps;
+    Poll: typeof Poll;
+    build_message_doc: typeof build_message_doc;
+    build_instance: (doc: IMessage) => Promise<Message>;
+    /** Obtiene un mensaje por CID/MID. */
+    get(cid: string, mid: string): Promise<Message | null>;
+    /** Pagina mensajes de un chat. */
+    list(cid: string, offset?: number, limit?: number): Promise<Message[]>;
+    /** Cuenta mensajes de un chat. */
+    count(cid: string): Promise<number>;
+    text(cid: string, caption: string, opts?: SendOptions): Promise<Message | null>;
+    image(cid: string, buf: Buffer, opts?: SendMediaOptions): Promise<Message | null>;
+    video(cid: string, buf: Buffer, opts?: SendMediaOptions): Promise<Message | null>;
+    audio(cid: string, buf: Buffer, opts?: SendAudioOptions): Promise<Message | null>;
+    location(cid: string, loc: LocationOptions, opts?: SendOptions): Promise<Message | null>;
+    poll(cid: string, p: PollOptions, opts?: SendPollOptions): Promise<Message | null>;
+    edit(cid: string, mid: string, text: string): Promise<boolean>;
+    delete(cid: string, mid: string, all?: boolean): Promise<boolean>;
+    react(cid: string, mid: string, emoji: string): Promise<boolean>;
+    forward(cid: string, mid: string, target: ForwardTarget): Promise<boolean>;
+    seen(cid: string, mid: string): Promise<boolean>;
+    star(cid: string, mid: string, value: boolean): Promise<boolean>;
+    watch(cid: string, mid: string, handler: (msg: Message) => void): () => void;
+};
+export {};