@areumtecnologia/wasockets 2.3.2 → 2.3.4

package/README.md

@@ -288,22 +288,37 @@ await ctx.unstar();
 ```
 
 #### Utilitários de Mídia (`MediaObject`):
-Se a mensagem contiver imagem, vídeo, áudio ou documento, `ctx.media` fornece métodos instantâneos:
+Se a mensagem contiver imagem, vídeo, áudio, figurinha ou documento, `ctx.media` centraliza todos os metadados e métodos de manipulação em uma única instância:
 
+##### Propriedades de `ctx.media`:
+- `ctx.media.mimetype`: Tipo MIME real (ex: `'image/jpeg'`, `'audio/ogg; codecs=opus'`).
+- `ctx.media.extension`: Extensão inferida do arquivo (ex: `'jpg'`, `'ogg'`, `'pdf'`, `'mp4'`).
+- `ctx.media.fileLength`: Tamanho do arquivo em bytes.
+- `ctx.media.fileName`: Nome original do arquivo (se enviado como documento).
+- `ctx.media.caption`: Legenda de texto anexada à mídia.
+- `ctx.media.seconds` / `duration`: Duração em segundos (para áudios e vídeos).
+- `ctx.media.isVoice` / `isPtt`: Booleano se é áudio gravado no WhatsApp (Push-To-Talk).
+- `ctx.media.isGif`: Booleano se é vídeo reproduzido como GIF animado.
+- `ctx.media.isViewOnce`: Booleano se é mídia de visualização única.
+
+##### Métodos de `ctx.media`:
 ```javascript
 if (ctx.media) {
-    // 1. Salva diretamente em disco
+    // 1. Salva diretamente em disco (cria diretórios se não existirem)
     await ctx.media.save('./pasta/comprovante.pdf');
 
-    // 2. Converte para Base64 (ideal para enviar para APIs de IA ou frontend)
-    const base64 = ctx.media.toBase64();
-    const dataUri = ctx.media.toDataUri(); // 'data:image/jpeg;base64,...'
+    // 2. Obtém como Buffer em memória (com cache automático)
+    const buffer = await ctx.media.toBuffer();
+
+    // 3. Converte para Base64 (ideal para LLMs como Gemini / OpenAI)
+    const base64 = await ctx.media.toBase64();
+    const dataUri = await ctx.media.toDataUri(); // 'data:image/jpeg;base64,...'
 
-    // 3. Obtém como Stream legível (Node Readable)
-    const stream = ctx.media.toStream();
+    // 4. Obtém como Stream legível (Node Readable)
+    const stream = await ctx.media.toStream();
 
-    // 4. Integração nativa com Sharp (se instalado) para redimensionamento/corte
-    const sharpInstance = ctx.media.toSharp();
+    // 5. Integração nativa com Sharp (se instalado) para recorte/redimensionamento
+    const sharpInstance = await ctx.media.toSharp();
 }
 ```
 

package/lib/Client/Context/CallContext.js

@@ -90,6 +90,25 @@ class CallContext {
         }
         throw new Error('No active audio stream or call is not connected yet.')
     }
+
+    toString() {
+        return `[Call ${this.id}] ${this.fromNumber} (${this.isVideo ? 'Vídeo' : 'Voz'}) - status: ${this.status}`
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            from: this.from,
+            fromNumber: this.fromNumber,
+            isVideo: this.isVideo,
+            status: this.status,
+            startTime: this.startTime
+        }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
 }
 
 exports.CallContext = CallContext

package/lib/Client/Context/MediaObject.js

@@ -155,6 +155,30 @@ class MediaObject {
         const buffer = await this.toBuffer(options)
         return sharp(buffer)
     }
+
+    toString() {
+        const sizeStr = this.fileLength ? `${this.fileLength} bytes` : 'unknown size'
+        return `[MediaObject ${this.mediaType}: ${this.mimetype} (${sizeStr})]`
+    }
+
+    toJSON() {
+        return {
+            mediaType: this.mediaType,
+            mimetype: this.mimetype,
+            extension: this.extension,
+            fileLength: this.fileLength,
+            fileName: this.fileName,
+            caption: this.caption,
+            duration: this.duration,
+            isPtt: this.isPtt,
+            isGif: this.isGif,
+            isViewOnce: this.isViewOnce
+        }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
 }
 
 exports.MediaObject = MediaObject

package/lib/Client/Context/MessageContext.js

@@ -255,6 +255,32 @@ class MessageContext {
         }
         return this.client.sock.pinInChatMessage(this.chatId, this.raw.key, 2)
     }
+
+    toString() {
+        const author = this.fromPushName || this.senderName || this.fromNumber || this.from
+        const preview = this.body ? `"${this.body}"` : `<${this.type}>`
+        return `[Message ${this.id}] ${author}: ${preview}`
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            chatId: this.chatId,
+            from: this.from,
+            to: this.to,
+            fromMe: this.fromMe,
+            fromPushName: this.fromPushName,
+            fromNumber: this.fromNumber,
+            type: this.type,
+            body: this.body,
+            isEdited: this.isEdited,
+            timestamp: this.timestamp
+        }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
 }
 
 exports.MessageContext = MessageContext

package/lib/Client/Events/ConnectionEvents.js

@@ -0,0 +1,235 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+/**
+ * Event emitted when connection status transitions between states
+ */
+class ConnectionStatusChange {
+    constructor(current, previous) {
+        this.current = current
+        this.previous = previous
+    }
+
+    toString() {
+        return JSON.stringify({ current: this.current, previous: this.previous })
+    }
+
+    toJSON() {
+        return { current: this.current, previous: this.previous }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted when a QR code is generated for authentication
+ */
+class QrCodeEvent {
+    constructor(qr) {
+        this.qr = qr || ''
+    }
+
+    toString() {
+        return this.qr
+    }
+
+    toJSON() {
+        return { qr: this.qr }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.qr
+    }
+}
+
+/**
+ * Event emitted when a 8-digit pairing code is received
+ */
+class PairingCodeEvent {
+    constructor(code) {
+        this.code = code || ''
+    }
+
+    toString() {
+        return this.code
+    }
+
+    toJSON() {
+        return { code: this.code }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.code
+    }
+}
+
+/**
+ * Event emitted when client successfully authenticates and opens connection
+ */
+class ConnectedEvent {
+    constructor(user) {
+        this.user = user || {}
+    }
+
+    get name() {
+        return this.user?.name || this.user?.notify || 'WhatsApp User'
+    }
+
+    get id() {
+        return this.user?.id || ''
+    }
+
+    toString() {
+        return `[Connected: ${this.name} (${this.id})]`
+    }
+
+    toJSON() {
+        return { user: this.user }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted when connection drops or closes
+ */
+class DisconnectedEvent {
+    constructor(options = {}) {
+        this.error = options.error || null
+        this.willReconnect = Boolean(options.willReconnect)
+        this.attempt = options.attempt || 0
+        this.delayMs = options.delayMs || 0
+        this.reason = options.reason || options.error?.message || 'Connection closed'
+    }
+
+    toString() {
+        const reconnectInfo = this.willReconnect
+            ? `Reconnecting attempt ${this.attempt} in ${this.delayMs}ms`
+            : 'No reconnect'
+        return `[Disconnected: ${this.reason} (${reconnectInfo})]`
+    }
+
+    toJSON() {
+        return {
+            error: this.error ? { message: this.error.message, stack: this.error.stack } : null,
+            willReconnect: this.willReconnect,
+            attempt: this.attempt,
+            delayMs: this.delayMs,
+            reason: this.reason
+        }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted when device session is permanently logged out
+ */
+class LoggedOutEvent {
+    constructor(error) {
+        this.error = error || null
+    }
+
+    toString() {
+        return '[LoggedOut: Session logged out on WhatsApp device]'
+    }
+
+    toJSON() {
+        return { error: this.error ? { message: this.error.message } : null }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted when one or more messages are deleted/revoked
+ */
+class MessageDeleteEvent {
+    constructor(keys) {
+        this.keys = Array.isArray(keys) ? keys : [keys].filter(Boolean)
+    }
+
+    get ids() {
+        return this.keys.map(k => k?.id || k).filter(Boolean)
+    }
+
+    toString() {
+        return `[MessageDelete: ${this.ids.join(', ')}]`
+    }
+
+    toJSON() {
+        return { keys: this.keys }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted when participants in a group are added, removed, promoted or demoted
+ */
+class GroupParticipantsUpdateEvent {
+    constructor(update = {}) {
+        this.id = update.id || ''
+        this.participants = update.participants || []
+        this.action = update.action || 'update'
+    }
+
+    toString() {
+        return `[GroupParticipantsUpdate ${this.action}: ${this.participants.join(', ')} in ${this.id}]`
+    }
+
+    toJSON() {
+        return { id: this.id, participants: this.participants, action: this.action }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+/**
+ * Event emitted on contact or group presence status updates
+ */
+class PresenceUpdateEvent {
+    constructor(presence = {}) {
+        this.id = presence.id || ''
+        this.presences = presence.presences || {}
+    }
+
+    toString() {
+        const keys = Object.keys(this.presences)
+        const summary = keys.length
+            ? keys.map(k => `${k}:${this.presences[k]?.lastKnownPresence || 'active'}`).join(', ')
+            : 'active'
+        return `[PresenceUpdate ${this.id}: ${summary}]`
+    }
+
+    toJSON() {
+        return { id: this.id, presences: this.presences }
+    }
+
+    [Symbol.toPrimitive]() {
+        return this.toString()
+    }
+}
+
+exports.ConnectionStatusChange = ConnectionStatusChange
+exports.QrCodeEvent = QrCodeEvent
+exports.PairingCodeEvent = PairingCodeEvent
+exports.ConnectedEvent = ConnectedEvent
+exports.DisconnectedEvent = DisconnectedEvent
+exports.LoggedOutEvent = LoggedOutEvent
+exports.MessageDeleteEvent = MessageDeleteEvent
+exports.GroupParticipantsUpdateEvent = GroupParticipantsUpdateEvent
+exports.PresenceUpdateEvent = PresenceUpdateEvent

package/lib/Client/Events/index.js

@@ -0,0 +1,9 @@
+"use strict"
+
+Object.defineProperty(exports, "__esModule", { value: true })
+
+const ConnectionEvents = require("./ConnectionEvents")
+
+module.exports = {
+    ...ConnectionEvents
+}

package/lib/Client/Normalizers/EventNormalizer.js

@@ -5,6 +5,11 @@ Object.defineProperty(exports, "__esModule", { value: true })
 const { Events } = require("../Constants")
 const { MessageContext } = require("../Context/MessageContext")
 const { CallContext } = require("../Context/CallContext")
+const {
+    MessageDeleteEvent,
+    GroupParticipantsUpdateEvent,
+    PresenceUpdateEvent
+} = require("../Events/ConnectionEvents")
 
 class EventNormalizer {
     /**
@@ -26,9 +31,7 @@ class EventNormalizer {
                 // Handle protocol revoke messages explicitly (delete for everyone)
                 const isRevoke = rawMsg.message?.protocolMessage?.type === 0
                 if (isRevoke) {
-                    client.emit(Events.MESSAGE_DELETE, {
-                        keys: [rawMsg.message.protocolMessage.key || rawMsg.key]
-                    })
+                    client.emit(Events.MESSAGE_DELETE, new MessageDeleteEvent([rawMsg.message.protocolMessage.key || rawMsg.key]))
                     continue // Do not emit as a new received/sent message
                 }
 
@@ -58,12 +61,12 @@ class EventNormalizer {
 
         // 3. Message deletion (revoke)
         sock.ev.on('messages.delete', (item) => {
-            client.emit(Events.MESSAGE_DELETE, item)
+            client.emit(Events.MESSAGE_DELETE, new MessageDeleteEvent(item?.keys || item))
         })
 
         // 4. Presence updates (typing, online, offline)
         sock.ev.on('presence.update', (presence) => {
-            client.emit(Events.PRESENCE_UPDATE, presence)
+            client.emit(Events.PRESENCE_UPDATE, new PresenceUpdateEvent(presence))
         })
 
         // 5. Contacts upsert
@@ -73,7 +76,7 @@ class EventNormalizer {
 
         // 6. Group participants updates (join, leave, promote, demote)
         sock.ev.on('group-participants.update', (update) => {
-            client.emit(Events.GROUP_PARTICIPANTS_UPDATE, update)
+            client.emit(Events.GROUP_PARTICIPANTS_UPDATE, new GroupParticipantsUpdateEvent(update))
         })
 
         // 7. VoIP incoming calls & status

package/lib/Client/WaClient.js

@@ -8,6 +8,14 @@ const { default: makeWASocket } = require("../Socket")
 const { useMultiFileAuthState } = require("../Utils/use-multi-file-auth-state")
 const { shouldReconnect, getReconnectDelay } = require("../Utils/reconnect")
 const { Events, ConnectionStatus } = require("./Constants")
+const {
+    ConnectionStatusChange,
+    QrCodeEvent,
+    PairingCodeEvent,
+    ConnectedEvent,
+    DisconnectedEvent,
+    LoggedOutEvent
+} = require("./Events/ConnectionEvents")
 const { JidNormalizer } = require("./Normalizers/JidNormalizer")
 const { EventNormalizer } = require("./Normalizers/EventNormalizer")
 const {
@@ -161,14 +169,14 @@ class WaClient extends EventEmitter {
             // QR Code issued
             if (qr) {
                 this._setStatus(ConnectionStatus.QR_READY)
-                this.emit(Events.QR_CODE, { qr })
+                this.emit(Events.QR_CODE, new QrCodeEvent(qr))
             }
 
             // Connection successfully established
             if (connection === 'open') {
                 this.reconnectAttempts = 0
                 this._setStatus(ConnectionStatus.CONNECTED)
-                this.emit(Events.CONNECTED, { user: this.sock.user })
+                this.emit(Events.CONNECTED, new ConnectedEvent(this.sock.user))
             }
 
             // Connection closed or dropped
@@ -178,12 +186,12 @@ class WaClient extends EventEmitter {
 
                 if (!canReconnect) {
                     this._setStatus(ConnectionStatus.LOGGED_OUT)
-                    this.emit(Events.LOGGED_OUT, { error })
+                    this.emit(Events.LOGGED_OUT, new LoggedOutEvent(error))
                 } else if (this.options.restartOnClose && !this._isDestroyed) {
                     this._scheduleReconnect(error)
                 } else {
                     this._setStatus(ConnectionStatus.DISCONNECTED)
-                    this.emit(Events.DISCONNECTED, { error, willReconnect: false })
+                    this.emit(Events.DISCONNECTED, new DisconnectedEvent({ error, willReconnect: false }))
                 }
             }
         })
@@ -203,7 +211,7 @@ class WaClient extends EventEmitter {
             try {
                 this._setStatus(ConnectionStatus.PAIRING_READY)
                 const code = await this.sock.requestPairingCode(cleanNumber)
-                this.emit(Events.PAIRING_CODE, { code })
+                this.emit(Events.PAIRING_CODE, new PairingCodeEvent(code))
             } catch (err) {
                 if (retryCount < 3 && !this._isDestroyed) {
                     setTimeout(() => attemptPairing(retryCount + 1), 3000)
@@ -224,11 +232,11 @@ class WaClient extends EventEmitter {
     _scheduleReconnect(error) {
         if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
             this._setStatus(ConnectionStatus.DISCONNECTED)
-            this.emit(Events.DISCONNECTED, {
+            this.emit(Events.DISCONNECTED, new DisconnectedEvent({
                 error,
                 willReconnect: false,
                 reason: 'Max reconnect attempts exceeded'
-            })
+            }))
             return
         }
 
@@ -238,12 +246,12 @@ class WaClient extends EventEmitter {
         })
 
         this._setStatus(ConnectionStatus.RECONNECTING)
-        this.emit(Events.DISCONNECTED, {
+        this.emit(Events.DISCONNECTED, new DisconnectedEvent({
             error,
             willReconnect: true,
             attempt: this.reconnectAttempts,
             delayMs
-        })
+        }))
 
         this._clearReconnectTimer()
         this._reconnectTimer = setTimeout(() => {
@@ -264,10 +272,7 @@ class WaClient extends EventEmitter {
         if (previousStatus === newStatus) return
 
         this.status = newStatus
-        this.emit(Events.STATUS_CHANGE, {
-            current: newStatus,
-            previous: previousStatus
-        })
+        this.emit(Events.STATUS_CHANGE, new ConnectionStatusChange(newStatus, previousStatus))
     }
 
     _clearReconnectTimer() {
@@ -435,4 +440,5 @@ class WaClient extends EventEmitter {
 }
 
 exports.WaClient = WaClient
+exports.ConnectionStatusChange = ConnectionStatusChange
 exports.default = WaClient

package/lib/Client/index.d.ts

@@ -37,6 +37,80 @@ export declare const ConnectionStatus: {
 
 export type ConnectionStatusType = typeof ConnectionStatus[keyof typeof ConnectionStatus]
 
+export declare class ConnectionStatusChange {
+    current: ConnectionStatusType
+    previous: ConnectionStatusType
+    constructor(current: ConnectionStatusType, previous: ConnectionStatusType)
+    toString(): string
+    toJSON(): { current: ConnectionStatusType; previous: ConnectionStatusType }
+}
+
+export declare class QrCodeEvent {
+    qr: string
+    constructor(qr: string)
+    toString(): string
+    toJSON(): { qr: string }
+}
+
+export declare class PairingCodeEvent {
+    code: string
+    constructor(code: string)
+    toString(): string
+    toJSON(): { code: string }
+}
+
+export declare class ConnectedEvent {
+    user: any
+    readonly name: string
+    readonly id: string
+    constructor(user: any)
+    toString(): string
+    toJSON(): { user: any }
+}
+
+export declare class DisconnectedEvent {
+    error: any | null
+    willReconnect: boolean
+    attempt: number
+    delayMs: number
+    reason: string
+    constructor(options?: any)
+    toString(): string
+    toJSON(): any
+}
+
+export declare class LoggedOutEvent {
+    error: any | null
+    constructor(error?: any)
+    toString(): string
+    toJSON(): any
+}
+
+export declare class MessageDeleteEvent {
+    keys: any[]
+    readonly ids: string[]
+    constructor(keys: any | any[])
+    toString(): string
+    toJSON(): { keys: any[] }
+}
+
+export declare class GroupParticipantsUpdateEvent {
+    id: string
+    participants: string[]
+    action: string
+    constructor(update?: any)
+    toString(): string
+    toJSON(): { id: string; participants: string[]; action: string }
+}
+
+export declare class PresenceUpdateEvent {
+    id: string
+    presences: Record<string, any>
+    constructor(presence?: any)
+    toString(): string
+    toJSON(): { id: string; presences: Record<string, any> }
+}
+
 export interface WaClientOptions {
     sessionName?: string
     dataPath?: string
@@ -530,21 +604,21 @@ export declare class WaClient extends EventEmitter {
     get isConnected(): boolean
     get rawSocket(): any
 
-    on(event: 'status.change', listener: (status: { current: ConnectionStatusType; previous: ConnectionStatusType }) => void): this
-    on(event: 'qr', listener: (data: { qr: string }) => void): this
-    on(event: 'pairing.code', listener: (data: { code: string }) => void): this
-    on(event: 'connected', listener: (data: { user: any }) => void): this
-    on(event: 'disconnected', listener: (data: { error?: any; willReconnect: boolean; attempt?: number; delayMs?: number }) => void): this
-    on(event: 'logged.out', listener: (data: { error?: any }) => void): this
+    on(event: 'status.change', listener: (status: ConnectionStatusChange) => void): this
+    on(event: 'qr', listener: (data: QrCodeEvent) => void): this
+    on(event: 'pairing.code', listener: (data: PairingCodeEvent) => void): this
+    on(event: 'connected', listener: (data: ConnectedEvent) => void): this
+    on(event: 'disconnected', listener: (data: DisconnectedEvent) => void): this
+    on(event: 'logged.out', listener: (data: LoggedOutEvent) => void): this
     on(event: 'call.incoming', listener: (call: CallContext) => void): this
     on(event: 'call.status', listener: (calls: any[]) => void): this
     on(event: 'message.received', listener: (ctx: MessageContext, raw: proto.IWebMessageInfo) => void): this
     on(event: 'message.sent', listener: (ctx: MessageContext, raw: proto.IWebMessageInfo) => void): this
     on(event: 'message.update', listener: (updates: any[]) => void): this
-    on(event: 'message.delete', listener: (item: any) => void): this
-    on(event: 'presence.update', listener: (presence: any) => void): this
+    on(event: 'message.delete', listener: (item: MessageDeleteEvent) => void): this
+    on(event: 'presence.update', listener: (presence: PresenceUpdateEvent) => void): this
     on(event: 'contacts.upsert', listener: (contacts: any[]) => void): this
-    on(event: 'group.participants.update', listener: (update: any) => void): this
+    on(event: 'group.participants.update', listener: (update: GroupParticipantsUpdateEvent) => void): this
     on(event: 'error', listener: (error: any) => void): this
     on(event: string | symbol, listener: (...args: any[]) => void): this
 }

package/lib/Client/index.js

@@ -4,6 +4,17 @@ Object.defineProperty(exports, "__esModule", { value: true })
 
 const { WaClient } = require("./WaClient")
 const { Events, ConnectionStatus } = require("./Constants")
+const {
+    ConnectionStatusChange,
+    QrCodeEvent,
+    PairingCodeEvent,
+    ConnectedEvent,
+    DisconnectedEvent,
+    LoggedOutEvent,
+    MessageDeleteEvent,
+    GroupParticipantsUpdateEvent,
+    PresenceUpdateEvent
+} = require("./Events/ConnectionEvents")
 const { MessageContext } = require("./Context/MessageContext")
 const { MediaObject } = require("./Context/MediaObject")
 const { CallContext } = require("./Context/CallContext")
@@ -40,6 +51,15 @@ const {
 exports.WaClient = WaClient
 exports.Events = Events
 exports.ConnectionStatus = ConnectionStatus
+exports.ConnectionStatusChange = ConnectionStatusChange
+exports.QrCodeEvent = QrCodeEvent
+exports.PairingCodeEvent = PairingCodeEvent
+exports.ConnectedEvent = ConnectedEvent
+exports.DisconnectedEvent = DisconnectedEvent
+exports.LoggedOutEvent = LoggedOutEvent
+exports.MessageDeleteEvent = MessageDeleteEvent
+exports.GroupParticipantsUpdateEvent = GroupParticipantsUpdateEvent
+exports.PresenceUpdateEvent = PresenceUpdateEvent
 exports.MessageContext = MessageContext
 exports.MediaObject = MediaObject
 exports.CallContext = CallContext

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areumtecnologia/wasockets",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "whatsappVersion": "2.3000.1053049953",
   "description": "Communication Library By areumtecnologia",
   "keywords": [],