@areumtecnologia/wasockets 2.2.3 → 2.3.0

package/README.md

@@ -59,7 +59,8 @@ O **WaSockets** foi criado para resolver problemas crônicos de estabilidade e a
   - [O Contexto de Mensagem (MessageContext / ctx)](#o-contexto-de-mensagem-messagecontext--ctx)
   - [Builders de Botões Interativos (InteractiveMessage)](#builders-de-botões-interativos-interactivemessage)
   - [Controle de Presença Fluente (Typing / Recording)](#controle-de-presença-fluente-typing--recording)
-  - [Os 13 Submódulos Especializados](#os-13-submódulos-especializados)
+  - [Os 12 Submódulos Especializados](#os-12-submódulos-especializados)
+  - [Guia Detalhado da Abstração (docs/CLIENT_GUIDE.md)](./docs/CLIENT_GUIDE.md)
   - [Opções de Configuração (WaClientOptions)](#opções-de-configuração-waclientoptions)
 - [Instalação](#-instalação)
 - [API de Baixo Nível (makeWASocket Legado)](#-conectando-a-conta)
@@ -341,6 +342,64 @@ await client.sendInteractive('5511999999999@s.whatsapp.net', lista);
 
 ---
 
+### Enquetes (PollBuilder) e Eventos (EventBuilder)
+
+Crie enquetes interativas e convites de eventos para grupos de forma declarativa:
+
+`javascript
+const { PollBuilder, EventBuilder } = require('@areumtecnologia/wasockets/client');
+
+// 1. Enquete com contagem de votos configurável
+const enquete = new PollBuilder()
+    .setName('Qual recurso você mais utiliza no WaSockets?')
+    .addOption('VoIP e Ligações WebAssembly')
+    .addOption('Botões Interativos e PIX')
+    .addOption('Canais / Newsletters v2')
+    .setSelectableCount(1);
+
+await client.sendPoll('5511999999999', enquete);
+
+// 2. Convite de Evento com RSVP para Grupo
+const evento = new EventBuilder()
+    .setName('Reunião de Alinhamento Trimestral')
+    .setDescription('Apresentação de resultados e novos objetivos')
+    .setStartDate(new Date(2026, 11, 20, 10, 0))
+    .setEndDate(new Date(2026, 11, 20, 12, 0))
+    .setLocation('Sala Virtual / Meet', -23.55052, -46.633308)
+    .setCall('voice');
+
+await client.sendEvent('120363000000000000@g.us', evento);
+`
+
+---
+
+### Controle de Chamadas VoIP (CallContext)
+
+Gerencie chamadas ativas ou recebidas com facilidade via WebAssembly:
+
+`javascript
+const { Events } = require('@areumtecnologia/wasockets/client');
+
+// 1. Receber e atender chamada recebida
+client.on(Events.CALL_INCOMING, async (call) => {
+    console.log(Chamada recebida de:  ());
+
+    if (call.isVideo) {
+        await call.reject('Não aceitamos chamadas de vídeo');
+    } else {
+        await call.accept();
+        await call.playAudio('./audios/atendimento-ura.opus');
+    }
+});
+
+// 2. Realizar chamada ativa de voz ou vídeo
+const call = await client.voip.call('5511999999999');
+await call.playAudio('./alerta.opus');
+await call.hangup();
+`
+
+---
+
 ### Controle de Presença Fluente (Typing / Recording)
 
 Indique que o bot está digitando ou gravando áudio de forma segura, com cancelamento automático ao enviar ou via objeto retornado:
@@ -363,25 +422,24 @@ await recording.stop();
 
 ---
 
-### Os 13 Submódulos Especializados
+### Os 12 Submódulos Especializados
 
-O `WaClient` divide as operações em 13 módulos focados, acessíveis diretamente na instância:
+O WaClient divide as operações em 12 módulos focados, acessíveis diretamente na instância (consulte o [Guia Completo da Abstração](./docs/CLIENT_GUIDE.md) para a documentação detalhada de cada método):
 
 | Submódulo | Acesso | Descrição e Principais Métodos |
 | :--- | :--- | :--- |
-| **Mensagens** | `client.messages` | Envio inteligente com validação `isOnWhatsApp`, textos, mídias, álbuns (`sendAlbum`), enquetes (`sendPoll`), vCards (`sendContacts`), reações e encaminhamento. |
-| **Grupos** | `client.groups` | Criar grupos, adicionar/remover membros, promover/rebaixar admins, convites, permissões de grupo e menção em massa (`mentionAll`). |
-| **Canais / Newsletters** | `client.channels` | Criação e gestão de Newsletters v2, busca por código de convite ou JID, seguir, deixar de seguir, silenciar e buscar reações. |
-| **Privacidade** | `client.privacy` | Bloquear/desbloquear contatos, gerenciar lista de bloqueio (`getBlocklist`) e configurar privacidade de Visto por Último, Online, Foto e Recado. |
-| **Perfil** | `client.profile` | Atualizar nome de exibição (`updateName`), recado/status (`updateStatus`), foto de perfil (`updatePicture`) e obter foto em alta resolução. |
-| **Chats** | `client.chat` | Fixar conversas no topo (`pin`/`unpin`), silenciar (`mute`/`unmute`), arquivar (`archive`/`unarchive`), limpar e excluir histórico. |
-| **Presença** | `client.presence` | `startTyping()`, `startRecording()`, marcar conta como online/offline e assinar atualizações de presença de contatos específicos. |
-| **Status / Stories** | `client.stories` | Publicar Status em texto, imagem, áudio ou vídeo, com suporte a menções direcionadas (`statusJidList`) ou broadcast público. |
-| **WhatsApp Business** | `client.business` | Gestão de catálogo comercial, cadastro de produtos (`createProduct`), coleções, perfil da empresa e detalhes de pedidos (`getOrderDetails`). |
-| **Etiquetas / Labels** | `client.labels` | CRUD completo de etiquetas do WhatsApp Business, associação de etiquetas a chats e mensagens específicas. |
-| **Comunidades** | `client.communities` | Criação de comunidades, vinculação de subgrupos (`addSubgroups`), remoção e gestão do grupo de avisos gerais. |
-| **Usuários** | `client.users` | Verificação de existência no WhatsApp (`isOnWhatsApp`), metadados, busca de perfil comercial e resolução reversa de LID para PN (`getPnForLid`). |
-| **Contatos** | `client.contacts` | Cache unificado de contatos em memória com resolução profunda assíncrona de informações completas (`fetchDeep`). |
+| **Mensagens** | client.messages | Envio inteligente com validação isOnWhatsApp, textos, mídias, álbuns (sendAlbum), enquetes, vCards, localizações, reações e encaminhamento. |
+| **VoIP / Chamadas** | client.voip | Chamadas ativas de voz e vídeo (call/callVideo), controle de chamada em andamento (ctiveCall), atender e rejeitar. |
+| **Grupos** | client.groups | Criar grupos, adicionar/remover membros, promover/rebaixar admins, convites, permissões de grupo e menção em massa (mentionAll). |
+| **Canais / Newsletters** | client.channels | Criação e gestão de Newsletters v2, seguir, deixar de seguir, silenciar, listar inscritos (listSubscribed) e buscar reações. |
+| **WhatsApp Business** | client.business | Gestão de catálogo comercial, cadastro de produtos (createProduct), coleções, perfil da empresa e detalhes de pedidos (getOrderDetails). |
+| **Comunidades** | client.communities | Criação de comunidades, vinculação de subgrupos (createSubgroup/linkSubgroup), desvinculação e gestão de subgrupos. |
+| **Etiquetas / Labels** | client.labels | CRUD completo de etiquetas do WhatsApp Business, associação de etiquetas a chats e mensagens específicas. |
+| **Presença** | client.presence | startTyping(), startRecording(), marcar conta como online/offline e assinar atualizações de presença de contatos específicos. |
+| **Perfil** | client.profile | Atualizar nome de exibição (updateName), recado/status (updateAbout), foto de perfil (updatePicture com TC Token) e obter foto em alta resolução. |
+| **Privacidade** | client.privacy | Bloquear/desbloquear contatos, gerenciar lista de bloqueio (getBlocklist) e configurar privacidade de Visto por Último, Online, Foto e Recado. |
+| **Usuários** | client.users | Verificação de existência no WhatsApp (isOnWhatsApp), perfil comercial e resolução bidirecional de LID para PN (getPnForLid/getLidForPn). |
+| **Chats** | client.chat | Fixar conversas no topo (pin/unpin), silenciar (mute/unmute), arquivar (rchive/unarchive), favoritos e anotações privadas de contato. |
 
 ---
 

package/lib/Client/Builders/Buttons.js

@@ -0,0 +1,127 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+/**
+ * Quick Reply Button - user clicks and sends a predetermined text/id response
+ */
+class QuickReplyButton {
+    constructor(displayText, id) {
+        this.displayText = displayText || ''
+        this.id = id || displayText || 'quick_reply'
+    }
+
+    build() {
+        return {
+            name: 'quick_reply',
+            buttonParamsJson: JSON.stringify({
+                display_text: this.displayText,
+                id: this.id
+            })
+        }
+    }
+}
+
+/**
+ * URL Button - user clicks and opens a webpage
+ */
+class UrlButton {
+    constructor(displayText, url, merchantUrl) {
+        this.displayText = displayText || ''
+        this.url = url || ''
+        this.merchantUrl = merchantUrl || url || ''
+    }
+
+    build() {
+        return {
+            name: 'cta_url',
+            buttonParamsJson: JSON.stringify({
+                display_text: this.displayText,
+                url: this.url,
+                merchant_url: this.merchantUrl
+            })
+        }
+    }
+}
+
+/**
+ * Copy Code Button - user clicks to copy a coupon/token to clipboard
+ */
+class CopyCodeButton {
+    constructor(displayText, copyCode, id) {
+        this.displayText = displayText || ''
+        this.copyCode = copyCode || ''
+        this.id = id || 'copy_code'
+    }
+
+    build() {
+        return {
+            name: 'cta_copy',
+            buttonParamsJson: JSON.stringify({
+                display_text: this.displayText,
+                id: this.id,
+                copy_code: this.copyCode
+            })
+        }
+    }
+}
+
+/**
+ * Call Button - user clicks to initiate a standard voice call
+ */
+class CallButton {
+    constructor(displayText, phoneNumber) {
+        this.displayText = displayText || ''
+        this.phoneNumber = phoneNumber || ''
+    }
+
+    build() {
+        return {
+            name: 'cta_call',
+            buttonParamsJson: JSON.stringify({
+                display_text: this.displayText,
+                phone_number: this.phoneNumber
+            })
+        }
+    }
+}
+
+/**
+ * Native PIX Payment Button (WhatsApp Payment Info)
+ */
+class PixButton {
+    /**
+     * @param {string} displayText - Text displayed on button (e.g., 'Pagar com PIX')
+     * @param {string} pixKey - Chave PIX (CPF/CNPJ, Email, Telefone ou EVP)
+     * @param {string} [keyType='CPF'] - Tipo da chave: 'CPF', 'EMAIL', 'PHONE', 'EVP'
+     * @param {string} [merchantName='Comerciante'] - Nome do beneficiário exibido
+     */
+    constructor(displayText, pixKey, keyType = 'CPF', merchantName = 'Comerciante') {
+        this.displayText = displayText || 'Pagar via PIX'
+        this.pixKey = pixKey || ''
+        this.keyType = (keyType || 'CPF').toUpperCase()
+        this.merchantName = merchantName || 'Comerciante'
+    }
+
+    build() {
+        return {
+            name: 'payment_info',
+            buttonParamsJson: JSON.stringify({
+                payment_settings: [{
+                    type: 'pix_static_code',
+                    pix_static_code: {
+                        merchant_name: this.merchantName,
+                        key: this.pixKey,
+                        key_type: this.keyType
+                    }
+                }]
+            })
+        }
+    }
+}
+
+exports.QuickReplyButton = QuickReplyButton
+exports.UrlButton = UrlButton
+exports.CopyCodeButton = CopyCodeButton
+exports.CallButton = CallButton
+exports.PixButton = PixButton

package/lib/Client/Builders/EventBuilder.js

@@ -0,0 +1,122 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+/**
+ * Fluent builder for WhatsApp Calendar / Group Event Messages
+ */
+class EventBuilder {
+    constructor() {
+        this._name = ''
+        this._description = ''
+        this._startTime = null
+        this._endTime = null
+        this._location = null
+        this._call = null
+    }
+
+    /**
+     * Sets event title
+     * @param {string} name
+     * @returns {this}
+     */
+    setName(name) {
+        this._name = name || ''
+        return this
+    }
+
+    /**
+     * Sets event description
+     * @param {string} description
+     * @returns {this}
+     */
+    setDescription(description) {
+        this._description = description || ''
+        return this
+    }
+
+    /**
+     * Sets start time as Date, timestamp in seconds or milliseconds
+     * @param {Date|number} date
+     * @returns {this}
+     */
+    setStartDate(date) {
+        if (date instanceof Date) {
+            this._startTime = Math.floor(date.getTime() / 1000)
+        } else if (typeof date === 'number') {
+            this._startTime = date > 10000000000 ? Math.floor(date / 1000) : Math.floor(date)
+        }
+        return this
+    }
+
+    /**
+     * Sets end time as Date, timestamp in seconds or milliseconds
+     * @param {Date|number} date
+     * @returns {this}
+     */
+    setEndDate(date) {
+        if (date instanceof Date) {
+            this._endTime = Math.floor(date.getTime() / 1000)
+        } else if (typeof date === 'number') {
+            this._endTime = date > 10000000000 ? Math.floor(date / 1000) : Math.floor(date)
+        }
+        return this
+    }
+
+    /**
+     * Sets event location
+     * @param {string} name - Location name
+     * @param {number} [degreesLatitude]
+     * @param {number} [degreesLongitude]
+     * @returns {this}
+     */
+    setLocation(name, degreesLatitude, degreesLongitude) {
+        this._location = {
+            name: name || '',
+            degreesLatitude: degreesLatitude || 0,
+            degreesLongitude: degreesLongitude || 0
+        }
+        return this
+    }
+
+    /**
+     * Sets WhatsApp voice or video call for the event
+     * @param {'voice'|'video'|1|2} callType
+     * @returns {this}
+     */
+    setCall(callType = 'voice') {
+        this._call = {
+            callType: callType === 'video' || callType === 2 ? 2 : 1
+        }
+        return this
+    }
+
+    /**
+     * Compiles event into a payload ready for sendMessage()
+     * @returns {Object}
+     */
+    build() {
+        if (!this._name) {
+            throw new Error('EventBuilder requires an event title via setName().')
+        }
+
+        const nowSec = Math.floor(Date.now() / 1000)
+        const startTime = this._startTime || (nowSec + 3600) // Default 1 hour from now
+
+        const eventPayload = {
+            name: this._name,
+            description: this._description || undefined,
+            startTime,
+            endTime: this._endTime || undefined,
+            location: this._location || undefined,
+            call: this._call || undefined
+        }
+
+        return {
+            event: eventPayload
+        }
+    }
+}
+
+exports.EventBuilder = EventBuilder
+exports.default = EventBuilder

package/lib/Client/Builders/InteractiveMessage.js

@@ -0,0 +1,150 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+const { ListButton } = require("./Lists")
+
+/**
+ * Fluent builder for Interactive WhatsApp Messages (Buttons, Cards, Menus, PIX)
+ */
+class InteractiveMessage {
+    constructor() {
+        this._title = ''
+        this._subtitle = ''
+        this._text = ''
+        this._footer = ''
+        this._header = null
+        this._buttons = []
+    }
+
+    /**
+     * Sets card title
+     * @param {string} title
+     * @returns {this}
+     */
+    setTitle(title) {
+        this._title = title || ''
+        return this
+    }
+
+    /**
+     * Sets subtitle or secondary header
+     * @param {string} subtitle
+     * @returns {this}
+     */
+    setSubtitle(subtitle) {
+        this._subtitle = subtitle || ''
+        return this
+    }
+
+    /**
+     * Sets the main text body (required)
+     * @param {string} text
+     * @returns {this}
+     */
+    setText(text) {
+        this._text = text || ''
+        return this
+    }
+
+    /**
+     * Sets smaller footer text at the bottom
+     * @param {string} footer
+     * @returns {this}
+     */
+    setFooter(footer) {
+        this._footer = footer || ''
+        return this
+    }
+
+    /**
+     * Sets an image header for the interactive card
+     * @param {string|Buffer|{ url: string }} image
+     * @returns {this}
+     */
+    setHeaderImage(image) {
+        this._header = {
+            image: typeof image === 'string' ? { url: image } : image
+        }
+        return this
+    }
+
+    /**
+     * Sets a video header for the interactive card
+     * @param {string|Buffer|{ url: string }} video
+     * @returns {this}
+     */
+    setHeaderVideo(video) {
+        this._header = {
+            video: typeof video === 'string' ? { url: video } : video
+        }
+        return this
+    }
+
+    /**
+     * Adds an interactive button (QuickReply, Url, CopyCode, Call, Pix or ListButton)
+     * @param {Object} button
+     * @returns {this}
+     */
+    addButton(button) {
+        if (button) {
+            this._buttons.push(button)
+        }
+        return this
+    }
+
+    /**
+     * Adds multiple buttons at once
+     * @param {Array<Object>} buttons
+     * @returns {this}
+     */
+    addButtons(buttons) {
+        if (Array.isArray(buttons)) {
+            for (const b of buttons) {
+                this.addButton(b)
+            }
+        }
+        return this
+    }
+
+    /**
+     * Compiles the interactive message into a payload ready for sock.sendMessage()
+     * @returns {Object}
+     */
+    build() {
+        if (!this._text && !this._title) {
+            throw new Error('InteractiveMessage requires at least a text or title.')
+        }
+
+        // Check if there is a ListButton
+        const listBtn = this._buttons.find(b => b instanceof ListButton || b.sections)
+
+        if (listBtn) {
+            const builtList = typeof listBtn.build === 'function' ? listBtn.build() : listBtn
+            return {
+                text: this._text,
+                title: this._title || undefined,
+                subtitle: this._subtitle || undefined,
+                footer: this._footer || undefined,
+                buttonText: builtList.buttonText,
+                sections: builtList.sections,
+                ...(this._header || {})
+            }
+        }
+
+        // Standard interactive buttons
+        return {
+            text: this._text,
+            title: this._title || undefined,
+            subtitle: this._subtitle || undefined,
+            footer: this._footer || undefined,
+            ...(this._header || {}),
+            interactiveButtons: this._buttons.map(btn => (
+                typeof btn.build === 'function' ? btn.build() : btn
+            ))
+        }
+    }
+}
+
+exports.InteractiveMessage = InteractiveMessage
+exports.default = InteractiveMessage

package/lib/Client/Builders/Lists.js

@@ -0,0 +1,78 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+/**
+ * Individual row in an interactive list section
+ */
+class ListRow {
+    constructor(title, description = '', rowId = '') {
+        this.title = title || ''
+        this.description = description || ''
+        this.rowId = rowId || title || 'row'
+    }
+
+    build() {
+        return {
+            title: this.title,
+            description: this.description,
+            rowId: this.rowId
+        }
+    }
+}
+
+/**
+ * Categorized section containing multiple rows
+ */
+class ListSection {
+    constructor(title, rows = []) {
+        this.title = title || ''
+        this.rows = Array.isArray(rows) ? rows : []
+    }
+
+    addRow(titleOrRow, description, rowId) {
+        if (titleOrRow instanceof ListRow) {
+            this.rows.push(titleOrRow)
+        } else {
+            this.rows.push(new ListRow(titleOrRow, description, rowId))
+        }
+        return this
+    }
+
+    build() {
+        return {
+            title: this.title,
+            rows: this.rows.map(row => typeof row.build === 'function' ? row.build() : row)
+        }
+    }
+}
+
+/**
+ * List Dropdown Button configuration
+ */
+class ListButton {
+    constructor(buttonText, sections = []) {
+        this.buttonText = buttonText || 'Ver Opções'
+        this.sections = Array.isArray(sections) ? sections : []
+    }
+
+    addSection(titleOrSection, rows) {
+        if (titleOrSection instanceof ListSection) {
+            this.sections.push(titleOrSection)
+        } else {
+            this.sections.push(new ListSection(titleOrSection, rows))
+        }
+        return this
+    }
+
+    build() {
+        return {
+            buttonText: this.buttonText,
+            sections: this.sections.map(sec => typeof sec.build === 'function' ? sec.build() : sec)
+        }
+    }
+}
+
+exports.ListRow = ListRow
+exports.ListSection = ListSection
+exports.ListButton = ListButton

package/lib/Client/Builders/PollBuilder.js

@@ -0,0 +1,84 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+/**
+ * Fluent builder for WhatsApp Polls
+ */
+class PollBuilder {
+    constructor() {
+        this._name = ''
+        this._options = []
+        this._selectableCount = 1
+    }
+
+    /**
+     * Sets poll question / title
+     * @param {string} name
+     * @returns {this}
+     */
+    setName(name) {
+        this._name = name || ''
+        return this
+    }
+
+    /**
+     * Adds an option to the poll
+     * @param {string} option
+     * @returns {this}
+     */
+    addOption(option) {
+        if (option && typeof option === 'string') {
+            this._options.push(option.trim())
+        }
+        return this
+    }
+
+    /**
+     * Adds multiple options to the poll
+     * @param {Array<string>} options
+     * @returns {this}
+     */
+    addOptions(options) {
+        if (Array.isArray(options)) {
+            for (const opt of options) {
+                this.addOption(opt)
+            }
+        }
+        return this
+    }
+
+    /**
+     * Sets how many options can be selected (1 for single choice, > 1 for multiple choices)
+     * @param {number} count
+     * @returns {this}
+     */
+    setSelectableCount(count) {
+        this._selectableCount = Math.max(1, Number(count) || 1)
+        return this
+    }
+
+    /**
+     * Compiles poll into a payload for sendMessage()
+     * @returns {Object}
+     */
+    build() {
+        if (!this._name) {
+            throw new Error('PollBuilder requires a question name via setName().')
+        }
+        if (this._options.length < 2) {
+            throw new Error('PollBuilder requires at least 2 options.')
+        }
+
+        return {
+            poll: {
+                name: this._name,
+                values: this._options,
+                selectableCount: this._selectableCount
+            }
+        }
+    }
+}
+
+exports.PollBuilder = PollBuilder
+exports.default = PollBuilder