@systemzero/baileys 1.0.4 → 1.0.6

package/README.md

@@ -1,1092 +1,925 @@
-# 📦 @systemzero/baileys `v1.0.4`
+<div align="center">
 
-> Biblioteca WhatsApp Web API em Node.js — fork ultra customizado com funções avançadas de envio de mensagens, grupos, mídias, IA e muito mais.
+<img src="https://files.catbox.moe/w1m2q4.jpg" width="120" style="border-radius:16px" />
 
----
+# @systemzero/baileys
+
+**v1.0.6** · Fork avançado do Baileys com suporte nativo a todos os tipos de mensagens do WhatsApp
 
-## 📋 Sumário
-
-- [Instalação](#instalação)
-- [Conexão Básica](#conexão-básica)
-- [📨 Envio de Mensagens](#-envio-de-mensagens)
-  - [Texto](#texto)
-  - [Imagem](#imagem)
-  - [Vídeo](#vídeo)
-  - [Áudio](#áudio)
-  - [Documento](#documento)
-  - [Sticker](#sticker)
-  - [Localização](#localização)
-  - [Contato](#contato)
-  - [Enquete (Poll)](#enquete-poll)
-  - [Reação](#reação)
-  - [Menção](#menção)
-  - [Link com Preview](#link-com-preview)
-  - [Resposta (Quoted)](#resposta-quoted)
-  - [Mensagem Editada](#mensagem-editada)
-  - [Mensagem Deletada](#mensagem-deletada)
-  - [Fixar Mensagem](#fixar-mensagem)
-  - [View Once](#view-once)
-  - [Modo Efêmero (Desaparecimento)](#modo-efêmero-desaparecimento)
-- [🎨 Mensagens Interativas (Botões)](#-mensagens-interativas-botões)
-  - [Botões Rápidos (Quick Reply)](#botões-rápidos-quick-reply)
-  - [Lista](#lista)
-  - [Botões Nativos (interactiveButtons)](#botões-nativos-interactivebuttons)
-  - [Pagamento Nativo](#pagamento-nativo)
-  - [Produto](#produto)
-- [🤖 Funções Rich (Meta AI Style)](#-funções-rich-meta-ai-style)
-  - [Texto Rico](#texto-rico)
-  - [Código Rico](#código-rico)
-  - [Lista Rica](#lista-rica)
-  - [Tabela Rica](#tabela-rica)
-  - [Rich Completo](#rich-completo)
-  - [Reels Ricos](#reels-ricos)
-  - [Perplexity IA](#perplexity-ia)
-- [📁 Tipos Especiais de Mensagem](#-tipos-especiais-de-mensagem)
-  - [Álbum de Fotos/Vídeos](#álbum-de-fotosvídeos)
-  - [Evento](#evento)
-  - [Resultado de Enquete](#resultado-de-enquete)
-  - [Story de Grupo](#story-de-grupo)
-  - [Pagamento (requestPayment)](#pagamento-requestpayment)
-- [👥 Funções de Grupo](#-funções-de-grupo)
-- [💬 Funções de Chat](#-funções-de-chat)
-- [🔒 Privacidade](#-privacidade)
-- [🏷️ Labels](#️-labels)
-- [📡 Presença](#-presença)
+[![NPM](https://img.shields.io/npm/v/@systemzero/baileys?color=7c3aed&style=flat-square&label=npm)](https://www.npmjs.com/package/@systemzero/baileys)
+[![License](https://img.shields.io/badge/license-MIT-6366f1?style=flat-square)](LICENSE)
+[![Author](https://img.shields.io/badge/by-Josué%20%3C%2F%3E-ec4899?style=flat-square)](https://t.me/blackhzx)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-7c3aed?style=flat-square)](https://nodejs.org)
+
+</div>
 
 ---
 
 ## Instalação
 
 ```bash
-npm install @systemzero/baileys
-# ou
-yarn add @systemzero/baileys
+npm i @systemzero/baileys
+```
+
+Dependências opcionais:
+```bash
+npm i sharp          # conversão de imagem para sticker pack
+npm i @napi-rs/image # alternativa ao sharp
 ```
 
-> **Requisito:** Node.js >= 20.0.0
+Requer `ffmpeg` instalado no sistema (com suporte a `libopus`) para conversão automática de áudio PTT e para o sistema anti-fraude de pagamento processar mídia. Confirme com `ffmpeg -encoders | grep opus`.
 
 ---
 
-## Conexão Básica
+## Índice
+
+1. [Conexão](#1-conexão)
+2. [Mensagens de mídia](#2-mensagens-de-mídia)
+3. [Mensagens especiais](#3-mensagens-especiais)
+4. [Botões e interativos](#4-botões-e-interativos)
+5. [Sticker Pack nativo](#5-sticker-pack-nativo)
+6. [Canais Newsletter](#6-canais-newsletter)
+7. [Enquetes com decrypt](#7-enquetes-com-decrypt)
+8. [AI Rich](#8-ai-rich)
+9. [LID / JID — Sistema avançado](#9-lid--jid--sistema-avançado)
+10. [Username (@usuario)](#10-username-usuario)
+11. [MessageBuilder — Button, ButtonV2, Carousel, AIRich](#11-messagebuilder--button-buttonv2-carousel-airich)
+12. [Botões estendidos (v1.0.6)](#12-botões-estendidos-v106)
+13. [Grupos](#13-grupos)
+14. [Perfil e privacidade](#14-perfil-e-privacidade)
+15. [Eventos do socket](#15-eventos-do-socket)
+16. [Utilitários](#16-utilitários)
+17. [Fixar / Desfixar mensagens](#17-fixar--desfixar-mensagens)
+18. [Resolução de nomes (getName)](#18-resolução-de-nomes-getname)
+19. [PTT real com qualquer formato de entrada](#19-ptt-real-com-qualquer-formato-de-entrada)
+20. [Guard de pagamento stealth (anti-fraude)](#20-guard-de-pagamento-stealth-anti-fraude)
+21. [Bad MAC Handler — sessões Signal](#21-bad-mac-handler--sessões-signal)
+22. [Resolução LID → telefone via grupo](#22-resolução-lid--telefone-via-grupo)
+23. [Versão do WhatsApp sempre atualizada](#23-versão-do-whatsapp-sempre-atualizada)
+24. [WhatsApp Flows — Formulários interativos](#24-whatsapp-flows--formulários-interativos)
+
+---
+
+## 1. Conexão
 
 ```js
-import makeWASocket, { useMultiFileAuthState, DisconnectReason } from '@systemzero/baileys'
+const {
+    default: makeWASocket,
+    useMultiFileAuthState,
+    DisconnectReason,
+    Browsers,
+    fetchLatestWaWebVersion
+} = require('@systemzero/baileys')
 
-const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
+const { state, saveCreds } = await useMultiFileAuthState('./session')
+const { version } = await fetchLatestWaWebVersion()
 
 const sock = makeWASocket({
-    auth: state,
-    printQRInTerminal: true
+    version,
+    auth:    state,
+    browser: Browsers.ubuntu('Chrome'),
+    printQRInTerminal: false,
+    logger:  require('pino')({ level: 'silent' }),
+    getMessage: async (key) => {
+        const msg = await store.loadMessage(key.remoteJid, key.id)
+        return msg?.message || undefined
+    }
 })
 
 sock.ev.on('creds.update', saveCreds)
 
 sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
     if (connection === 'close') {
-        const shouldReconnect = lastDisconnect?.error?.output?.statusCode !== DisconnectReason.loggedOut
-        if (shouldReconnect) conectar()
-    } else if (connection === 'open') {
-        console.log('✅ Conectado ao WhatsApp!')
+        const code = lastDisconnect?.error?.output?.statusCode
+        if (code !== DisconnectReason.loggedOut) startBot()
     }
 })
 ```
 
----
-
-## 📨 Envio de Mensagens
-
-Todas as funções de envio usam `sock.sendMessage(jid, conteúdo, opções?)`.
-
-O `jid` é o identificador do destinatário:
-- **Privado:** `'5511999999999@s.whatsapp.net'`
-- **Grupo:** `'120363xxxxxxxx@g.us'`
-- **Status:** `'status@broadcast'`
-
----
-
-### Texto
+> Veja a seção [23](#23-versão-do-whatsapp-sempre-atualizada) para um jeito mais robusto de buscar a versão, que não falha silenciosamente.
 
-Envia uma mensagem de texto simples.
+### Pairing Code
 
 ```js
-await sock.sendMessage('5511999999999@s.whatsapp.net', {
-    text: 'Olá, mundo! 👋'
-})
-```
+// Automático
+const code = await sock.requestPairingCode('5511999999999')
 
-Com formatação WhatsApp:
-```js
-await sock.sendMessage(jid, {
-    text: '*negrito* _itálico_ ~tachado~ `monoespaçado`'
-})
+// Personalizado — exatamente 8 caracteres
+const code = await sock.requestPairingCode('5511999999999', 'MYBOT001')
 ```
 
----
-
-### Imagem
-
-Envia uma imagem com legenda opcional. Aceita **Buffer**, **URL** ou **caminho local**.
+### Store em memória
 
 ```js
-// Por URL
-await sock.sendMessage(jid, {
-    image: { url: 'https://exemplo.com/foto.jpg' },
-    caption: 'Uma linda foto 🖼️'
-})
-
-// Por Buffer
-import { readFileSync } from 'fs'
-await sock.sendMessage(jid, {
-    image: readFileSync('./imagem.jpg'),
-    caption: 'Foto do arquivo'
-})
+const store = {
+    messages: {},
+    bind: (ev) => {
+        ev.on('messages.upsert', ({ messages }) => {
+            for (const msg of messages) {
+                if (!msg.key?.remoteJid) continue
+                store.messages[msg.key.remoteJid] ??= {}
+                store.messages[msg.key.remoteJid][msg.key.id] = msg
+            }
+        })
+    },
+    loadMessage: async (jid, id) => store.messages[jid]?.[id] || null
+}
+store.bind(sock.ev)
 ```
 
 ---
 
-### Vídeo
+## 2. Mensagens de mídia
 
-Envia um vídeo com legenda opcional. Aceita **Buffer**, **URL** ou **caminho local**.
+Todos os campos de mídia aceitam `Buffer`, `{ url: 'https://...' }` ou `{ stream }`.
 
 ```js
-// Por URL
-await sock.sendMessage(jid, {
-    video: { url: 'https://exemplo.com/video.mp4' },
-    caption: 'Assista esse vídeo! 🎬',
-    mimetype: 'video/mp4'
-})
+// Texto
+await sock.sendMessage(jid, { text: 'Olá!' })
 
-// Como GIF animado
+// Texto com menção
 await sock.sendMessage(jid, {
-    video: readFileSync('./animacao.mp4'),
-    gifPlayback: true,   // Reproduz como GIF
-    caption: 'Olha esse gif!'
+    text:     '@5511...!',
+    mentions: ['5511999999999@s.whatsapp.net']
 })
-```
 
----
-
-### Áudio
-
-Envia um áudio. Use `ptt: true` para enviar como mensagem de voz (PTT).
+// Imagem
+await sock.sendMessage(jid, { image: { url: 'https://...' }, caption: 'Legenda' })
 
-```js
-// Áudio normal (arquivo de música)
-await sock.sendMessage(jid, {
-    audio: { url: 'https://exemplo.com/musica.mp3' },
-    mimetype: 'audio/mp4'
-})
+// Vídeo
+await sock.sendMessage(jid, { video: buffer, caption: 'Legenda', gifPlayback: false })
 
-// Mensagem de voz (PTT)
-await sock.sendMessage(jid, {
-    audio: readFileSync('./audio.ogg'),
-    mimetype: 'audio/ogg; codecs=opus',
-    ptt: true   // Aparece como áudio de voz
-})
-```
+// Áudio normal (música)
+await sock.sendMessage(jid, { audio: buffer, mimetype: 'audio/mpeg', ptt: false })
 
----
+// Nota de voz (PTT) — ver seção 19 para conversão automática de qualquer formato
+await sock.sendMessage(jid, { audio: buffer, ptt: true })
 
-### Documento
+// Documento
+await sock.sendMessage(jid, { document: buffer, mimetype: 'application/pdf', fileName: 'doc.pdf' })
 
-Envia um arquivo/documento com nome customizado.
+// Figurinha
+await sock.sendMessage(jid, { sticker: buffer })
 
-```js
+// Album (mínimo 2 itens)
 await sock.sendMessage(jid, {
-    document: { url: 'https://exemplo.com/arquivo.pdf' },
-    mimetype: 'application/pdf',
-    fileName: 'Relatório Mensal.pdf',
-    caption: 'Segue o relatório em anexo 📄'
+    album: [{ image: buffer1 }, { image: buffer2 }, { video: bufferVideo }]
 })
 
-// Por Buffer
+// Contato
 await sock.sendMessage(jid, {
-    document: readFileSync('./contrato.docx'),
-    mimetype: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    fileName: 'Contrato.docx'
-})
-```
-
----
-
-### Sticker
-
-Envia um sticker (figurinha). Deve ser WebP ou convertido previamente.
-
-```js
-await sock.sendMessage(jid, {
-    sticker: readFileSync('./figurinha.webp')
+    contacts: {
+        displayName: 'João',
+        contacts: [{ vcard: 'BEGIN:VCARD\nVERSION:3.0\nFN:João\nTEL:+5511999999999\nEND:VCARD' }]
+    }
 })
 
-// Por URL
+// Localização
 await sock.sendMessage(jid, {
-    sticker: { url: 'https://exemplo.com/sticker.webp' }
+    location: { degreesLatitude: -23.55, degreesLongitude: -46.63, name: 'São Paulo' }
 })
 ```
 
 ---
 
-### Localização
-
-Envia uma localização no mapa.
+## 3. Mensagens especiais
 
 ```js
-await sock.sendMessage(jid, {
-    location: {
-        degreesLatitude: -23.5505,
-        degreesLongitude: -46.6333,
-        name: 'São Paulo, SP',
-        address: 'Av. Paulista, 1000'
-    }
-})
-```
+// Reação
+await sock.sendMessage(jid, { react: { text: '❤️', key: message.key } })
 
----
+// Deletar
+await sock.sendMessage(jid, { delete: message.key })
 
-### Contato
+// Editar
+await sock.sendMessage(jid, { edit: message.key, text: 'Texto editado' })
 
-Envia um contato (vCard).
+// Fixar — ver seção 17 para a versão completa
+await sock.sendMessage(jid, { pin: message.key, type: 1 })
 
-```js
-const vcard = `BEGIN:VCARD
-VERSION:3.0
-FN:João Silva
-ORG:Empresa LTDA;
-TEL;type=CELL;type=VOICE;waid=5511999999999:+55 11 99999-9999
-END:VCARD`
+// View Once
+await sock.sendMessage(jid, { image: buffer, viewOnce: true })
+await sock.sendMessage(jid, { image: buffer, viewOnceV2: true })
 
-await sock.sendMessage(jid, {
-    contacts: {
-        displayName: 'João Silva',
-        contacts: [{ vcard }]
-    }
-})
-```
+// Spoiler
+await sock.sendMessage(jid, { image: buffer, caption: '!', spoiler: true })
 
----
+// Status de grupo
+await sock.sendMessage(jid, { image: buffer, groupStatus: true })
 
-### Enquete (Poll)
+// Efêmera
+await sock.sendMessage(jid, { image: buffer, ephemeral: true })
 
-Cria uma enquete interativa no WhatsApp.
+// Lottie sticker
+await sock.sendMessage(jid, { sticker: buffer, isLottie: true })
 
-```js
-await sock.sendMessage(jid, {
-    poll: {
-        name: 'Qual sua linguagem favorita?',
-        values: ['JavaScript', 'Python', 'TypeScript', 'Go'],
-        selectableCount: 1   // Quantas opções o usuário pode escolher
-    }
-})
-```
-
----
+// Mention All
+await sock.sendMessage(jid, { text: '@all', mentionAll: true })
 
-### Reação
-
-Reage a uma mensagem com um emoji.
-
-```js
+// External Ad Reply
 await sock.sendMessage(jid, {
-    react: {
-        text: '❤️',   // Emoji da reação (string vazia para remover)
-        key: mensagem.key   // Key da mensagem que será reagida
+    text: 'Confira!',
+    externalAdReply: {
+        title: 'Título', body: 'Descrição',
+        thumbnail: bufferImg, mediaType: 1,
+        sourceUrl: 'https://systemzone.store',
+        renderLargerThumbnail: true
     }
 })
-```
 
-Para remover uma reação:
-```js
+// Enquete
 await sock.sendMessage(jid, {
-    react: { text: '', key: mensagem.key }
+    poll: { name: 'Pergunta?', values: ['A', 'B', 'C'], selectableCount: 1 }
 })
+
+// Encaminhar
+const { generateForwardMessageContent, generateWAMessageFromContent } = require('@systemzero/baileys')
+const fwd = generateForwardMessageContent(message, false)
+const msg = generateWAMessageFromContent(jid, fwd, { quoted: m })
+await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
 ```
 
----
+> ⚠️ **Removido desta versão do README:** preview de link customizado (`linkPreview` manual) e áudio embutido em rodapé de card interativo (`audioFooter`). Os dois existem no proto do WhatsApp, mas em testes reais (Android e iOS) **não renderizaram corretamente** — o `audioFooter` não mostrou o player de áudio, e o `linkPreview` manual caiu num formato de card genérico em vez do esperado. Não são recursos confiáveis hoje.
 
-### Menção
+---
 
-Menciona um ou mais usuários no texto.
+## 4. Botões e interativos
 
 ```js
-await sock.sendMessage(jid, {
-    text: 'Oi @5511999999999, tudo bem?',
-    mentions: ['5511999999999@s.whatsapp.net']
-})
-```
+const { generateWAMessageFromContent, proto } = require('@systemzero/baileys')
 
----
+const msg = generateWAMessageFromContent(jid, {
+    viewOnceMessage: {
+        message: {
+            interactiveMessage: proto.Message.InteractiveMessage.create({
+                header: { title: 'Título', hasMediaAttachment: false },
+                body:   { text: 'Texto' },
+                footer: { text: 'Rodapé' },
+                nativeFlowMessage: { buttons: [ /* tipos abaixo */ ] }
+            })
+        }
+    }
+}, { quoted: m })
 
-### Link com Preview
+await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
+```
 
-Envia uma mensagem de texto — o preview do link é gerado automaticamente se `generateHighQualityLinkPreview: true` estiver ativado na config.
+### Tipos de botão (testados e funcionais)
 
 ```js
-await sock.sendMessage(jid, {
-    text: 'Confira: https://github.com'
-})
-```
-
----
+// Resposta rápida
+{ name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: 'OK', id: 'ok' }) }
 
-### Resposta (Quoted)
+// Link
+{ name: 'cta_url', buttonParamsJson: JSON.stringify({ display_text: 'Abrir', url: 'https://systemzone.store' }) }
 
-Responde a uma mensagem específica.
+// Copiar
+{ name: 'cta_copy', buttonParamsJson: JSON.stringify({ display_text: 'Copiar', copy_code: 'CODIGO' }) }
 
-```js
-// Dentro do handler de mensagens:
-sock.ev.on('messages.upsert', async ({ messages }) => {
-    const msg = messages[0]
+// Ligar
+{ name: 'cta_call', buttonParamsJson: JSON.stringify({ display_text: 'Ligar', phone_number: '5511999999999' }) }
 
-    await sock.sendMessage(msg.key.remoteJid, {
-        text: 'Essa é minha resposta!'
-    }, {
-        quoted: msg   // Passa a mensagem original para responder
+// Lista dropdown
+{
+    name: 'single_select',
+    buttonParamsJson: JSON.stringify({
+        title: 'Escolher',
+        sections: [{ title: 'Cat', rows: [
+            { header: 'Op1', title: 'Opção 1', description: 'Desc', id: 'op1' }
+        ]}]
     })
-})
+}
 ```
 
----
-
-### Mensagem Editada
-
-Edita o conteúdo de uma mensagem já enviada.
+### Header com imagem (funciona — confirmado em teste real)
 
 ```js
+const { generateWAMessage, generateMessageIDV2 } = require('@systemzero/baileys')
+
+// Forma simplificada e já testada: usar `image` + `caption` direto no sendMessage,
+// junto com nativeFlow — a lib monta o header automaticamente.
 await sock.sendMessage(jid, {
-    text: 'Texto corrigido ✏️',
-    edit: mensagemOriginal.key   // Key da mensagem a ser editada
+    image:      { url: 'https://...' },
+    caption:    'Texto do card',
+    nativeFlow: [{ text: 'Botão', id: 'btn1' }]
 })
 ```
 
----
-
-### Mensagem Deletada
+> Use `caption`, não `text`, quando quiser header com imagem junto de `nativeFlow` — usar `text` faz a lib pular inteiro o bloco que monta o header.
 
-Deleta uma mensagem (para todos).
+### Template Buttons
 
 ```js
 await sock.sendMessage(jid, {
-    delete: mensagem.key   // Key da mensagem a deletar
+    text: 'Escolha:',
+    templateButtons: [
+        { text: 'Resposta', id: 'r1' },
+        { text: 'Site', url: 'https://systemzone.store' },
+        { text: 'Ligar', call: '5511999999999' },
+    ]
 })
 ```
 
----
-
-### Fixar Mensagem
-
-Fixa uma mensagem no chat ou grupo.
+### Sections
 
 ```js
 await sock.sendMessage(jid, {
-    pin: mensagem.key,   // Key da mensagem a fixar
-    type: 1              // 1 = fixar, 2 = desfixar
+    text: 'Selecione', buttonText: 'Ver opções',
+    sections: [{ title: 'Cat', rows: [
+        { title: 'Item 1', description: 'Desc', id: 'i1' }
+    ]}]
 })
 ```
 
 ---
 
-### View Once
-
-Envia mídia que some após ser visualizada uma vez.
+## 5. Sticker Pack nativo
 
 ```js
 await sock.sendMessage(jid, {
-    image: readFileSync('./foto_secreta.jpg'),
-    viewOnce: true,
-    caption: 'Esta foto vai sumir! 🔥'
+    cover:    bufferWebP,
+    stickers: [
+        { data: bufferWebP,  emojis: ['😂'] },
+        { data: bufferAnima, emojis: ['🔥'] },  // animada
+        { data: bufferPng,   emojis: ['✨'] },   // PNG converte auto
+    ],
+    name:        'Nome do Pack',
+    publisher:   'Autor',
+    description: 'Descrição'
 })
 ```
 
----
+> Tanto `cover` quanto cada item de `stickers[].data` esperam **Buffer**, não `{ url }`. Se você baixou as figurinhas de uma API, baixe o buffer primeiro (`axios.get(url, { responseType: 'arraybuffer' })`) antes de montar o objeto.
 
-### Modo Efêmero (Desaparecimento)
-
-Ativa ou desativa mensagens temporárias em grupos.
-
-```js
-// Ativar (86400 = 24h, 604800 = 7 dias, 7776000 = 90 dias)
-await sock.sendMessage(jid, {
-    disappearingMessagesInChat: 604800  // 7 dias em segundos
-})
-
-// Desativar
-await sock.sendMessage(jid, {
-    disappearingMessagesInChat: false
-})
-```
+Máximo 60 figurinhas, cada uma até 1MB. Requer `sharp` ou `@napi-rs/image` para PNG.
 
 ---
 
-## 🎨 Mensagens Interativas (Botões)
+## 6. Canais Newsletter
 
-### Botões Rápidos (Quick Reply)
+```js
+// Texto
+await sock.sendMessage('120363...@newsletter', { text: 'Novidade!' })
 
-Envia botões de resposta rápida usando a sintaxe simplificada.
+// Mídia — sempre via generateWAMessage + relayMessage
+const { generateWAMessage, generateMessageIDV2 } = require('@systemzero/baileys')
 
-```js
-await sock.sendMessage(jid, {
-    text: 'Escolha uma opção:',
-    footer: 'Sistema de Atendimento',
-    buttons: [
-        { buttonText: { displayText: '✅ Sim' }, buttonId: 'sim' },
-        { buttonText: { displayText: '❌ Não' }, buttonId: 'nao' },
-        { buttonText: { displayText: '❓ Talvez' }, buttonId: 'talvez' }
-    ]
+const fullMsg = await generateWAMessage(canalJid, { image: buffer, caption: 'Legenda' }, {
+    upload: sock.waUploadToServer, userJid: sock.user.id,
+    messageId: generateMessageIDV2(sock.user.id),
 })
+await sock.relayMessage(canalJid, fullMsg.message, { messageId: fullMsg.key.id })
+
+// Gerenciar
+const canal = await sock.newsletterCreate('Nome', 'Descrição')
+await sock.newsletterFollow(jid)
+await sock.newsletterUnfollow(jid)
+await sock.newsletterMute(jid)
+await sock.newsletterUnmute(jid)
+const meta = await sock.newsletterMetadata('jid', jid)
+await sock.newsletterUpdateName(jid, 'Novo Nome')
+await sock.newsletterUpdateDescription(jid, 'Nova descrição')
+await sock.newsletterUpdatePicture(jid, buffer)
+await sock.newsletterRemovePicture(jid)
+await sock.newsletterReactMessage(jid, serverId, '❤️')
+const msgs = await sock.newsletterFetchMessages(jid, 30, 0, 0)
+await sock.newsletterDelete(jid)
+const { subscribers } = await sock.newsletterSubscribers(jid)
 ```
 
 ---
 
-### Lista
-
-Envia uma lista interativa de opções (menu).
+## 7. Enquetes com decrypt
 
 ```js
+// Criar
 await sock.sendMessage(jid, {
-    listMessage: {
-        title: 'Menu Principal',
-        text: 'Selecione uma opção abaixo:',
-        footer: 'Powered by SystemZero',
-        buttonText: 'Ver Opções',
-        sections: [
-            {
-                title: 'Serviços',
-                rows: [
-                    { title: 'Suporte', description: 'Falar com atendente', rowId: 'suporte' },
-                    { title: 'Financeiro', description: 'Ver cobranças', rowId: 'financeiro' }
-                ]
-            }
-        ]
-    }
+    poll: { name: 'Pergunta?', values: ['A', 'B', 'C'], selectableCount: 1 }
 })
-```
-
----
 
-### Botões Nativos (interactiveButtons)
+// Receber votos — no connect.js após saveCreds:
+const { getAggregateVotesInPollMessage } = require('@systemzero/baileys/lib/Utils/messages.js')
 
-Botões nativos com suporte a imagem/vídeo no cabeçalho.
-
-```js
-await sock.sendMessage(jid, {
-    interactiveButtons: [
-        {
-            name: 'quick_reply',
-            buttonParamsJson: JSON.stringify({
-                display_text: '📋 Ver Cardápio',
-                id: 'cardapio'
-            })
-        },
-        {
-            name: 'cta_url',
-            buttonParamsJson: JSON.stringify({
-                display_text: '🌐 Acessar Site',
-                url: 'https://meusite.com',
-                merchant_url: 'https://meusite.com'
-            })
-        },
-        {
-            name: 'cta_call',
-            buttonParamsJson: JSON.stringify({
-                display_text: '📞 Ligar',
-                phone_number: '+5511999999999'
-            })
-        }
-    ],
-    text: 'Olá! Como posso te ajudar?',
-    footer: 'Atendimento 24h'
+sock.ev.on('messages.update', async (updates) => {
+    for (const { key, update } of updates) {
+        if (!update.pollUpdates) continue
+        const pollMsg = await store.loadMessage(key.remoteJid, key.id)
+        if (!pollMsg?.message) continue
+        const result = getAggregateVotesInPollMessage({
+            message: pollMsg.message, pollUpdates: update.pollUpdates
+        })
+        // [{ name: 'A', voters: ['5511...@s.whatsapp.net'] }]
+    }
 })
 ```
 
 ---
 
-### Pagamento Nativo
-
-Solicita um pagamento pelo WhatsApp Pay.
+## 8. AI Rich
 
 ```js
-await sock.sendMessage(jid, {
-    interactiveButtons: [
-        {
-            name: 'review_and_pay',
-            buttonParamsJson: JSON.stringify({
-                currency: 'BRL',
-                total_amount: { value: 5000, offset: 100 },  // R$ 50,00
-                reference_id: 'PEDIDO-001',
-                type: 'physical-goods',
-                order: {
-                    status: 'pending',
-                    subtotal: { value: 5000, offset: 100 },
-                    order_type: 'ORDER',
-                    items: [{
-                        name: 'Produto X',
-                        amount: { value: 5000, offset: 100 },
-                        quantity: 1,
-                        sale_amount: { value: 5000, offset: 100 }
-                    }]
-                }
-            })
-        }
-    ],
-    text: 'Seu pedido está pronto para pagamento!'
-})
-```
+// Texto com hyperlink
+await sock.sendRich(jid, [
+    sock.makeText('Acesse [nosso site](https://systemzone.store).')
+], quotedMsg)
 
----
+// Código
+await sock.sendRich(jid, [
+    sock.makeCode('bash', 'npm i @systemzero/baileys')
+], null, ['RICH_RESPONSE_CODE'])
 
-### Produto
+// Tabela
+await sock.sendRich(jid, [
+    sock.makeTable([['Nome', 'Status'], ['Botões', '✅'], ['Canais', '✅']])
+], null, ['RICH_RESPONSE_TABLE'])
 
-Exibe um produto com imagem, preço e botões de ação.
+// Lista
+await sock.sendRich(jid, [sock.makeList(['Item 1', 'Item 2'])])
 
-```js
-await sock.sendMessage(jid, {
-    productMessage: {
-        title: 'Tênis Nike Air Max',
-        description: 'Conforto e estilo para o dia a dia.',
-        thumbnail: { url: 'https://exemplo.com/tenis.jpg' },
-        productId: 'PRODUTO-001',
-        retailerId: 'LOJA-BR',
-        priceAmount1000: 39900,   // R$ 399,00
-        currencyCode: 'BRL',
-        url: 'https://minhaloja.com/produto',
-        body: 'Aproveite a oferta!',
-        footer: 'Frete grátis acima de R$ 200',
-        buttons: [
-            {
-                name: 'quick_reply',
-                buttonParamsJson: JSON.stringify({ display_text: '🛒 Comprar', id: 'comprar' })
-            }
-        ]
-    }
-})
+// Atalhos
+await sock.sendRichText(jid, 'Texto com [link](https://systemzone.store)', quotedMsg)
+await sock.sendRichCode(jid, 'Título', 'javascript', 'const x = 1', quotedMsg)
+await sock.sendRichList(jid, 'Lista', ['A', 'B'], quotedMsg)
 ```
 
 ---
 
-## 🤖 Funções Rich (Meta AI Style)
+## 9. LID / JID — Sistema avançado
 
-Estas funções enviam mensagens no estilo do Meta AI com formatação especial.
+O WhatsApp usa dois tipos de identificador:
+- **JID** (`@s.whatsapp.net`) — formato baseado em número de telefone
+- **LID** (`@lid`) — identificador opaco, não contém o número de telefone
 
-### Texto Rico
+A partir da v1.0.6, a baileys resolve automaticamente LID↔JID em mensagens recebidas e na metadata de grupo (ver seção 22), via `sharedLidPhoneCache`.
 
 ```js
-await sock.sendRichText(jid, 'Esta é uma mensagem de texto rica! ✨')
-
-// Com resposta (quoted)
-await sock.sendRichText(jid, 'Mensagem rica em resposta', mensagemOriginal)
+const {
+    lidToJid, resolveJid, resolveAll, normalizeJid, validateJid,
+    getSenderInfo, sharedLidPhoneCache, isLidUser, isPnUser,
+    getBotJid, setBotMap
+} = require('@systemzero/baileys')
 ```
 
----
-
-### Código Rico
-
-Exibe um bloco de código com syntax highlighting.
-
 ```js
-await sock.sendRichCode(
-    jid,
-    'Exemplo em JavaScript:',   // Título (opcional)
-    'javascript',               // Linguagem
-    `function soma(a, b) {
-    return a + b;
-}
-console.log(soma(2, 3));`
-)
+const jid = lidToJid('123456@lid')
+const { jid, lid } = resolveAll('5511999999999@s.whatsapp.net')
+normalizeJid('5511999999999')         // → '5511999999999@s.whatsapp.net'
+normalizeJid('123456@lid')            // → resolve via cache
+const { isValid, error } = validateJid('5511999999999@s.whatsapp.net')
+const { jid, lid, isGroup, isValid } = getSenderInfo(message)
 ```
 
----
-
-### Lista Rica
+### Cache bidirecional
 
-Exibe uma lista de itens formatada.
+O cache é populado automaticamente ao processar mensagens **e** ao buscar metadata de grupo (`groupMetadata`) — esse segundo ponto foi corrigido na v1.0.6, antes o par LID↔telefone que vem pronto na lista de participantes do grupo era descartado.
 
 ```js
-await sock.sendRichList(
-    jid,
-    '📋 Lista de Tarefas:',           // Título
-    ['Estudar Node.js', 'Fazer deploy', 'Testar bot', 'Dormir']
-)
+sharedLidPhoneCache.set('123456@lid', '5511999999999@s.whatsapp.net') // manual, raro
+const jid = sharedLidPhoneCache.getPhoneForLid('123456@lid')
+const lid = sharedLidPhoneCache.getLidForPhone('5511999999999@s.whatsapp.net')
+console.log('Entradas no cache:', sharedLidPhoneCache.size)
 ```
 
----
+> ⚠️ Atenção com sufixo de dispositivo: identidades do **próprio bot** (`sock.user.id` / `sock.user.lid`) costumam vir como `numero:N@dominio` (ex: `558892659041:10@s.whatsapp.net`). Pra comparar com a lista de `participants` (que não tem sufixo), remova só o `:N`, preservando o domínio: `jid.replace(/:\d+(?=@)/, '')` — **não use** `jid.split(':')[0]`, isso corta o domínio inteiro junto.
 
-### Tabela Rica
+---
 
-Exibe uma tabela formatada (primeira linha é o cabeçalho).
+## 10. Username (@usuario)
 
 ```js
-await sock.sendRichTable(
-    jid,
-    '📊 Relatório de Vendas',             // Título
-    [
-        ['Produto', 'Qtd', 'Valor'],       // Cabeçalho
-        ['Camiseta', '10', 'R$ 300'],
-        ['Calça', '5', 'R$ 500'],
-        ['Tênis', '3', 'R$ 900']
-    ],
-    'Total: R$ 1.700'                      // Rodapé (opcional)
-)
-```
-
----
+const { resolveUsername, isUsername } = require('@systemzero/baileys')
 
-### Rich Completo
+isUsername('@josue')    // true
+isUsername('josue')     // false
 
-Combina texto, código, lista e tabela em uma única mensagem.
-
-```js
-await sock.sendRichFull(jid, {
-    title: '🚀 Relatório Completo',
-    code: `const resultado = calcular()`,
-    language: 'javascript',
-    items: ['Item A', 'Item B', 'Item C'],
-    table: [
-        ['Campo', 'Valor'],
-        ['Status', 'Ativo'],
-        ['Versão', '1.0.3']
-    ],
-    footer: '© SystemZero Baileys'
-})
+const jid = await resolveUsername('@josue', sock.onWhatsApp.bind(sock))
+if (jid) await sock.sendMessage(jid, { text: 'Olá!' })
 ```
 
 ---
 
-### Reels Ricos
-
-Envia uma mensagem no estilo de resultado de busca com reels/vídeos.
+## 11. MessageBuilder — Button, ButtonV2, Carousel, AIRich
 
 ```js
-await sock.sendRichReels(
-    jid,
-    'Resultado da Busca',        // Título
-    'Vídeos encontrados',        // Header
-    'gatos fofinhos',            // Query de busca
-    [
-        {
-            title: 'Gato dançando',
-            url: 'https://video1.com',
-            thumbnail: 'https://thumb1.com/img.jpg'
-        }
-    ]
-)
+const { Button, ButtonV2, Carousel, AIRich } = require('@systemzero/baileys/lib/MB.cjs')
 ```
 
----
-
-### Perplexity IA
+> O socket vai sempre no construtor: `new ButtonV2(sock)`
 
-Consulta a API Perplexity e envia a resposta no chat.
+### ButtonV2 — botões clássicos
 
 ```js
-await sock.sendPerplexity(
-    jid,
-    'Qual a capital do Brasil?'
-)
-
-// Com opções (ex: responder a uma mensagem)
-await sock.sendPerplexity(
-    jid,
-    'Explique inteligência artificial',
-    { quoted: mensagemOriginal }
-)
+const msg = new ButtonV2(sock)
+msg.setTitle('Título')
+msg.setBody('Corpo')
+msg.setFooter('Rodapé')
+msg.setThumbnail('https://exemplo.com/imagem.jpg')
+msg.addButton('✅ Opção 1', 'opcao_1')
+msg.addButton('❌ Opção 2', 'opcao_2')
+await msg.send(jid, { quoted: m })
 ```
 
----
-
-## 📁 Tipos Especiais de Mensagem
-
-### Álbum de Fotos/Vídeos
+Capturar clique: `m.body` chega com o id do botão.
 
-Envia múltiplas fotos/vídeos como um álbum agrupado.
+### Button — native flow avançado
 
 ```js
-await sock.sendMessage(jid, {
-    albumMessage: [
-        { image: { url: 'https://exemplo.com/foto1.jpg' }, caption: 'Foto 1' },
-        { image: { url: 'https://exemplo.com/foto2.jpg' }, caption: 'Foto 2' },
-        { video: { url: 'https://exemplo.com/clip.mp4' }, caption: 'Vídeo do evento' }
-    ]
-})
+const msg = new Button(sock)
+msg.setTitle('Título')
+msg.setBody('Corpo')
+msg.addReply('✅ Confirmar', 'confirmar')
+msg.addUrl('🔗 Abrir site', 'https://systemzone.store')
+msg.addCopy('📋 Copiar código', 'PROMO2025')
+msg.addCall('📞 Ligar', '5511999999999')
+await msg.send(jid, { quoted: m })
 ```
 
----
-
-### Evento
-
-Cria um evento no grupo ou conversa.
+### Carousel
 
 ```js
-await sock.sendMessage(jid, {
-    eventMessage: {
-        name: '🎉 Reunião de Equipe',
-        description: 'Reunião semanal de alinhamento da equipe de desenvolvimento.',
-        location: {
-            degreesLatitude: -23.5505,
-            degreesLongitude: -46.6333,
-            name: 'Escritório Central, São Paulo'
-        },
-        joinLink: 'https://meet.google.com/abc-xyz',
-        startTime: Date.now() + 86400000,      // Amanhã
-        endTime: Date.now() + 86400000 + 3600000,  // +1 hora
-        extraGuestsAllowed: true,
-        isCanceled: false
-    }
-})
+const msg = new Carousel(sock)
+msg.setBody('Escolha um item:')
+msg.card(c => c.image('https://...').title('Card 1').text('Descrição').button('Ver', 'c1'))
+msg.card(c => c.image('https://...').title('Card 2').text('Descrição').button('Ver', 'c2'))
+await msg.send(jid, { quoted: m })
 ```
 
----
-
-### Resultado de Enquete
-
-Envia um snapshot de resultado de votação.
+### AIRich
 
 ```js
-await sock.sendMessage(jid, {
-    pollResultMessage: {
-        name: 'Qual sua linguagem favorita?',
-        pollVotes: [
-            { optionName: 'JavaScript', optionVoteCount: 42 },
-            { optionName: 'Python', optionVoteCount: 35 },
-            { optionName: 'TypeScript', optionVoteCount: 28 }
-        ]
-    }
-})
+const msg = new AIRich(sock)
+msg.addText('Acesse [System Zero](https://systemzone.store).')
+msg.addCode('javascript', `const baileys = require('@systemzero/baileys')`)
+msg.addTable([['Comando', 'Descrição'], ['!menu', 'Abre o menu']])
+await msg.send(jid, { quoted: m })
 ```
 
 ---
 
-### Story de Grupo
+## 12. Botões estendidos (v1.0.6)
 
-Envia uma mensagem como story/status de grupo.
+> ⚠️ **Não verificado nesta versão do README.** Os tipos abaixo (`catalog`, `products`, `otp`, `orderDetails`, `flow`, etc) exigem conta **WhatsApp Business API verificada** com catálogo/pagamentos configurados — nenhum deles foi testado numa conta pessoal real. Os tipos mais simples (`reminder`, `address`, `location`, `phoneNumber`, `urlBtn`, `clearChat`) têm chance maior de funcionar em qualquer conta, mas também não foram confirmados em teste real. Trate como documentação do proto, não como garantia de funcionamento. Para formulários reais e testados, veja a seção 24.
 
 ```js
-await sock.sendMessage(jid, {
-    groupStatusMessage: {
-        image: { url: 'https://exemplo.com/story.jpg' },
-        caption: 'Nosso grupo é o melhor! 🔥'
-    }
-})
-
-// Com vídeo
-await sock.sendMessage(jid, {
-    groupStatusMessage: {
-        video: { url: 'https://exemplo.com/story.mp4' },
-        caption: 'Evento da semana'
-    }
-})
+{ text: '⏰ Me lembre', reminder: 'lembrete_id' }
+{ text: '🔕 Cancelar', cancelReminder: 'lembrete_id' }
+{ text: '📍 Enviar endereço', address: true }
+{ text: '📡 Localização', location: true }
+{ text: '🛍️ Ver catálogo', catalog: '5511999999999@s.whatsapp.net' }
+{ text: '📦 Produtos', products: ['prod_id_1'], bizJid: '5511...@s.whatsapp.net' }
+{ text: 'Copiar código', otp: '123456' }
+{ text: '📞 Ligar', phoneNumber: '5511999999999' }
+{ text: '📋 Ver pedido', orderDetails: { order_id: '123', token: 'abc' } }
+{ text: '🗑️ Limpar chat', clearChat: true }
+{ text: '🔗 Abrir', urlBtn: 'https://systemzone.store' }
 ```
 
----
-
-### Pagamento (requestPayment)
-
-Solicita um pagamento com nota ou sticker.
+### isSystemNotification
 
 ```js
-await sock.sendMessage(jid, {
-    requestPaymentMessage: {
-        amount: 15000,              // R$ 150,00 (em centavos × 10)
-        currency: 'BRL',
-        from: '5511999999999@s.whatsapp.net',
-        expiry: Math.floor(Date.now() / 1000) + 86400,  // 24h
-        note: 'Pagamento do serviço de bot 🤖'
-    }
+sock.ev.on('messages.upsert', async ({ messages }) => {
+    const msg = messages[0]
+    if (msg.isSystemNotification) return // ignora notificação de sistema
 })
 ```
 
 ---
 
-## 👥 Funções de Grupo
-
-### Criar Grupo
+## 13. Grupos
 
 ```js
-const grupo = await sock.groupCreate('Nome do Grupo', [
-    '5511999999999@s.whatsapp.net',
-    '5521888888888@s.whatsapp.net'
-])
-console.log('Grupo criado:', grupo.id)
-```
+const grupo = await sock.groupCreate('Nome', ['5511...@s.whatsapp.net'])
+const meta  = await sock.groupMetadata(jid)
 
----
+await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'add')
+await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'remove')
+await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'promote')
+await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'demote')
+await sock.groupLeave(jid)
+await sock.groupUpdateSubject(jid, 'Novo Nome')
+await sock.groupUpdateDescription(jid, 'Nova descrição')
 
-### Metadados do Grupo
+const code = await sock.groupInviteCode(jid)
+await sock.groupRevokeInvite(jid)
+await sock.groupAcceptInvite('CODIGO')
+await sock.groupToggleEphemeral(jid, 86400)
 
-```js
-const info = await sock.groupMetadata('120363xxxxxxxx@g.us')
-console.log(info.subject)       // Nome do grupo
-console.log(info.participants)  // Lista de participantes
-console.log(info.desc)          // Descrição
+const grupos = await sock.groupFetchAllParticipating()
 ```
 
 ---
 
-### Adicionar / Remover / Promover / Rebaixar Participantes
+## 14. Perfil e privacidade
 
 ```js
-// Adicionar
-await sock.groupParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'add')
+const url = await sock.profilePictureUrl(jid, 'image')
+await sock.updateProfilePicture(jid, buffer)
+await sock.updateProfileStatus('🤖 Bot ativo')
 
-// Remover
-await sock.groupParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'remove')
+const [result] = await sock.onWhatsApp('5511999999999')
 
-// Tornar admin
-await sock.groupParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'promote')
+await sock.updateBlockStatus(jid, 'block')
+await sock.updateBlockStatus(jid, 'unblock')
 
-// Remover admin
-await sock.groupParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'demote')
-```
+await sock.sendPresenceUpdate('composing', jid)
+await sock.sendPresenceUpdate('available', jid)
+await sock.presenceSubscribe(jid)
 
----
+await sock.readMessages([message.key])
 
-### Atualizar Nome e Descrição
+await sock.chatModify({ archive: true }, jid)
+await sock.chatModify({ pin: true }, jid)
+await sock.chatModify({ mute: 8 * 60 * 60 * 1000 }, jid)
 
-```js
-await sock.groupUpdateSubject(jid, 'Novo Nome do Grupo ✨')
-await sock.groupUpdateDescription(jid, 'Nova descrição incrível do grupo!')
+await sock.logout()
 ```
 
 ---
 
-### Link de Convite
+## 15. Eventos do socket
 
 ```js
-// Obter link
-const code = await sock.groupInviteCode(jid)
-console.log(`https://chat.whatsapp.com/${code}`)
+sock.ev.on('messages.upsert',          ({ messages, type }) => {})
+sock.ev.on('messages.update',           (updates) => {})
+sock.ev.on('messages.delete',           (item) => {})
+sock.ev.on('messages.reaction',         (reactions) => {})
+sock.ev.on('messages.decrypt-failed',   (failInfo) => {}) // ver seção 20
+sock.ev.on('presence.update',           ({ id, presences }) => {})
+sock.ev.on('groups.update',             (updates) => {})
+sock.ev.on('group-participants.update', ({ id, participants, action }) => {})
+sock.ev.on('contacts.update',           (contacts) => {})
+sock.ev.on('connection.update',         ({ connection, lastDisconnect, qr }) => {})
+sock.ev.on('creds.update',              saveCreds)
 
-// Revogar e gerar novo link
-await sock.groupRevokeInvite(jid)
-
-// Entrar por código
-await sock.groupAcceptInvite('CodigoAqui')
-
-// Info do grupo pelo link
-const info = await sock.groupGetInviteInfo('CodigoAqui')
+sock.ev.on('call', (calls) => {
+    for (const call of calls) {
+        if (call.status === 'offer') sock.rejectCall(call.id, call.from)
+    }
+})
 ```
 
 ---
 
-### Configurações do Grupo
+## 16. Utilitários
 
 ```js
-// Apenas admins enviam mensagens
-await sock.groupSettingUpdate(jid, 'announcement')
-
-// Todos podem enviar
-await sock.groupSettingUpdate(jid, 'not_announcement')
+const { downloadMediaMessage, downloadContentFromMessage } = require('@systemzero/baileys')
+const buffer = await downloadMediaMessage(message, 'buffer', {})
 
-// Apenas admins editam info
-await sock.groupSettingUpdate(jid, 'locked')
+const { generateWAMessage, generateWAMessageFromContent, generateMessageIDV2 } = require('@systemzero/baileys')
 
-// Todos editam info
-await sock.groupSettingUpdate(jid, 'unlocked')
+const {
+    jidNormalizedUser, isJidGroup, isJidNewsletter,
+    isLidUser, isPnUser, isUsername,
+    normalizeJid, resolveAll, getSenderInfo,
+    jidEncode, jidDecode
+} = require('@systemzero/baileys')
 
-// Modo de adição de membros
-await sock.groupMemberAddMode(jid, 'all_member_add')  // Todos podem adicionar
-await sock.groupMemberAddMode(jid, 'admin_add')        // Só admins
-
-// Aprovação para entrar
-await sock.groupJoinApprovalMode(jid, 'on')   // Ativar aprovação
-await sock.groupJoinApprovalMode(jid, 'off')  // Desativar
+// Detectar dispositivo — analisa o FORMATO DO ID DA MENSAGEM, não o JID
+const { getDevice } = require('@systemzero/baileys')
+const device = getDevice(message.key.id) // 'android' | 'ios' | 'web' | 'unknown'
 ```
 
----
-
-### Sair do Grupo
-
-```js
-await sock.groupLeave(jid)
-```
+> `getDevice` só funciona em cima de um `message.key.id` real — não dá pra usar pra "descobrir o dispositivo" de alguém sem ter uma mensagem recente dela pra inspecionar.
 
 ---
 
-### Solicitações de Participação
+## 17. Fixar / Desfixar mensagens
 
 ```js
-// Listar solicitações pendentes
-const solicitacoes = await sock.groupRequestParticipantsList(jid)
+// Fixar (type: 1 = PIN_FOR_ALL)
+await sock.sendMessage(jid, { pin: quotedMsg.key, type: 1 })
 
-// Aprovar ou rejeitar
-await sock.groupRequestParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'approve')
-await sock.groupRequestParticipantsUpdate(jid, ['5511999999999@s.whatsapp.net'], 'reject')
+// Desfixar (type: 2 = UNPIN_FOR_ALL)
+await sock.sendMessage(jid, { pin: quotedMsg.key, type: 2 })
 ```
 
----
+`quotedMsg.key` precisa conter `remoteJid`, `fromMe`, `id` e (em grupos) `participant`.
 
-## 💬 Funções de Chat
+---
 
-### Modificar Chat
+## 18. Resolução de nomes (getName)
 
 ```js
-// Arquivar conversa
-await sock.chatModify({ archive: true, lastMessages: [mensagem] }, jid)
-
-// Marcar como não lida
-await sock.chatModify({ markRead: false, lastMessages: [mensagem] }, jid)
+const { getName } = require('@systemzero/baileys')
+const nome = getName(msg, contactStore) // contactStore opcional: { [jid]: { name, notify, verifiedName } }
+```
 
-// Mutar por 8 horas
-await sock.chatModify({ mute: 8 * 60 * 60 * 1000 }, jid)
+Ordem de prioridade: contato salvo localmente → `verifiedName` → `pushName`/`notify` → resolução `@lid` via cache → número formatado → `"Usuário desconhecido"`. Nunca retorna vazio.
 
-// Desmutar
-await sock.chatModify({ mute: null }, jid)
+---
 
-// Fixar conversa
-await sock.chatModify({ pin: true }, jid)
+## 19. PTT real com qualquer formato de entrada
 
-// Limpar mensagens
-await sock.chatModify({ clear: { messages: [{ id: 'ID_MSG', fromMe: true }] } }, jid)
+Antes da correção, `ptt: true` só **etiquetava** o mimetype como opus sem converter os bytes de verdade — qualquer entrada que não já fosse opus puro dava "algo errado com o arquivo de áudio" no WhatsApp. Agora a lib transcodifica de verdade via `ffmpeg` quando necessário.
 
-// Deletar conversa
-await sock.chatModify({ delete: true, lastMessages: [mensagem] }, jid)
+```js
+await sock.sendMessage(jid, {
+    audio: { url: 'https://qualquer-formato.mp3' }, // mp3, m4a, wav, o que for
+    ptt: true
+})
 ```
 
----
+A lib detecta se a fonte já é `.opus`/`.ogg` (pela extensão real, não pelo que você declarar em `mimetype`) e só converte quando necessário, pra mono/16kHz — a especificação que o player de voz do WhatsApp espera.
 
-### Marcar como Lida
-
-```js
-const key = { remoteJid: jid, id: mensagem.key.id, participant: mensagem.key.participant }
-await sock.readMessages([key])
-```
+> Requer `ffmpeg` com `libopus` no `PATH` do servidor.
 
 ---
 
-### Status e Perfil
-
-```js
-// Ver foto de perfil
-const url = await sock.profilePictureUrl('5511999999999@s.whatsapp.net', 'image')
+## 20. Guard de pagamento stealth (anti-fraude)
 
-// Atualizar foto de perfil
-await sock.updateProfilePicture(jid, readFileSync('./nova_foto.jpg'))
+A lib emite o evento `messages.decrypt-failed` sempre que uma mensagem de grupo falha na descriptografia (PreKey/CIPHERTEXT) — cobre o golpe de cobrança "invisível": mensagem normal enviada, depois **editada** pra conteúdo de pagamento.
 
-// Remover foto de perfil
-await sock.removeProfilePicture(jid)
+```js
+const { bindPaymentGuard } = require('@systemzero/baileys')
 
-// Atualizar status (bio)
-await sock.updateProfileStatus('Desenvolvendo bots 🤖')
+bindPaymentGuard(sock, {
+    isPaymentMessage: (webMessage) => { /* sua lógica de detecção */ },
+    recordEnvelope:  (webMessage, isPayment) => { /* seu registro de corroboração */ },
+    treatDecryptFailureAsSuspicious: true,
+    onDetect: (detection) => {
+        // detection.type: 'direct' | 'edited' | 'undecryptable'
+    }
+})
+```
 
-// Atualizar nome
-await sock.updateProfileName('Meu Bot')
+| Caminho | Evento | Garantia |
+|---|---|---|
+| Mensagem direta | `messages.upsert` | Roda seu detector no conteúdo normal |
+| Mensagem editada | `messages.update` | Extrai `editedMessage` e roda o mesmo detector |
+| Falha de decrypt | `messages.decrypt-failed` | Nunca ignora em silêncio, mesmo sem conteúdo |
 
-// Ver status de outro usuário
-const status = await sock.fetchStatus('5511999999999@s.whatsapp.net')
-```
+> Falha de decrypt nunca foi lida pelo bot — não existe forma de confirmar que era pagamento. O guard garante que isso nunca passe sem nenhum aviso, não que vai "adivinhar" o conteúdo.
 
 ---
 
-### Bloquear / Desbloquear
+## 21. Bad MAC Handler — sessões Signal
 
 ```js
-await sock.updateBlockStatus('5511999999999@s.whatsapp.net', 'block')
-await sock.updateBlockStatus('5511999999999@s.whatsapp.net', 'unblock')
+const { BadMacHandler, badMacHandler } = require('@systemzero/baileys')
+
+if (badMacHandler.isBadMacError(error)) {
+    badMacHandler.handleError(error, 'algum-contexto')
+}
 
-// Ver lista de bloqueados
-const bloqueados = await sock.fetchBlocklist()
+// limpa sessões Signal problemáticas, preservando creds.json
+badMacHandler.clearProblematicSessionFiles()
 ```
 
+Erros "Bad MAC" são esperados ocasionalmente em qualquer cliente Signal Protocol (sessão desincronizada do outro lado) — esse handler conta, dá reset automático após um intervalo, e remove só arquivos de sessão por par, nunca as credenciais principais.
+
 ---
 
-### Contatos
+## 22. Resolução LID → telefone via grupo
 
 ```js
-// Adicionar ou editar contato
-await sock.addOrEditContact({
-    jid: '5511999999999@s.whatsapp.net',
-    notify: 'João Silva'
-})
-
-// Remover contato
-await sock.removeContact('5511999999999@s.whatsapp.net')
+const { resolveLidPhoneFromGroup } = require('@systemzero/baileys')
+const telefone = await resolveLidPhoneFromGroup(sock, groupJid, lid)
 ```
 
+Força a resolução de um `@lid` pro telefone real buscando a metadata do grupo (que já entrega o par pronto por participante) — útil quando o cache ainda não tem aquele par.
+
 ---
 
-## 🔒 Privacidade
+## 23. Versão do WhatsApp sempre atualizada
 
 ```js
-// Último visto: 'all' | 'contacts' | 'contact_blacklist' | 'none'
-await sock.updateLastSeenPrivacy('contacts')
-
-// Online: 'all' | 'match_last_seen'
-await sock.updateOnlinePrivacy('all')
-
-// Foto de perfil: 'all' | 'contacts' | 'contact_blacklist' | 'none'
-await sock.updateProfilePicturePrivacy('contacts')
-
-// Status: 'all' | 'contacts' | 'contact_blacklist' | 'none'
-await sock.updateStatusPrivacy('contacts')
+const { getBestWaVersion } = require('@systemzero/baileys')
+const { version, isLatest, source } = await getBestWaVersion()
+```
 
-// Confirmação de leitura: 'all' | 'none'
-await sock.updateReadReceiptsPrivacy('all')
+Tenta `web.whatsapp.com`, depois GitHub, e só aceita um resultado se `isLatest === true` de verdade. Diferente de `fetchLatestWaWebVersion()`/`fetchLatestBaileysVersion()` isoladas, que sempre retornam algo (mesmo em falha, caindo num valor fixo antigo) sem deixar isso óbvio.
 
-// Adição em grupos: 'all' | 'contacts' | 'contact_blacklist' | 'none'
-await sock.updateGroupsAddPrivacy('contacts')
+---
 
-// Chamadas: 'all' | 'contacts' | 'contact_blacklist' | 'none'
-await sock.updateCallPrivacy('contacts')
+## 24. WhatsApp Flows — Formulários interativos
 
-// Preview de links: 'all' | 'none'
-await sock.updateDisableLinkPreviewsPrivacy('none')
+> ⚠️ WhatsApp Flows é um recurso de **WhatsApp Business API**, normalmente exigindo um `flow_id` aprovado pela Meta pra sua conta/app específico. O exemplo abaixo é o que está em uso real no System Zero — funciona pro `flow_id` configurado nessa conta, mas **não é garantido que o mesmo `flow_id` funcione pra qualquer outra conta**. Pra criar seu próprio Flow, você precisa cadastrar e aprovar ele no Meta Business Manager.
 
-// Modo de desaparecimento padrão
-await sock.updateDefaultDisappearingMode(604800) // 7 dias
-```
-
----
-
-## 🏷️ Labels
+### Enviando o formulário
 
 ```js
-// Criar/editar label
-await sock.addLabel({ id: '1', name: 'Cliente VIP', color: 1 })
-
-// Label em chat
-await sock.addChatLabel(jid, '1')
-await sock.removeChatLabel(jid, '1')
+const { generateWAMessageFromContent } = require('@systemzero/baileys')
 
-// Label em mensagem
-await sock.addMessageLabel(jid, msgId, '1')
-await sock.removeMessageLabel(jid, msgId, '1')
+const formMsg = generateWAMessageFromContent(jid, {
+    viewOnceMessage: {
+        message: {
+            messageContextInfo: {
+                deviceListMetadata: {},
+                deviceListMetadataVersion: 2
+            },
+            interactiveMessage: {
+                body: { text: 'Formulário de teste\n\nPreencha seus dados.' },
+                nativeFlowMessage: {
+                    buttons: [{
+                        name: 'galaxy_message',
+                        buttonParamsJson: JSON.stringify({
+                            flow_message_version: '4',
+                            flow_id: 'SEU_FLOW_ID_AQUI',
+                            flow_action_payload: {
+                                screen: 'contact_details',
+                                data: {
+                                    full_name_visible:    true,
+                                    phone_number_visible: true,
+                                    email_visible:        true,
+                                    offer_name:           'Olá, seja bem-vindo',
+                                    offer_description:    'Sistema de teste'
+                                }
+                            },
+                            well_version: 'V700',
+                            flow_cta:     '__localize:FLOWS_SIGN_UP_BUTTON_TITLE',
+                            flow_action:  'navigate',
+                            flow_token:   'T0ZGRVJfU0lHTlVQ'
+                        })
+                    }],
+                    messageParamsJson: '{}'
+                }
+            }
+        }
+    }
+}, { userJid: sock.user.id })
 
-// Favoritar mensagem
-await sock.star(jid, [{ id: msgId, fromMe: true }], true)
+await sock.relayMessage(jid, formMsg.message, { messageId: formMsg.key.id })
 ```
 
----
+### Recebendo a resposta
 
-## 📡 Presença
+A resposta do formulário chega como `interactiveResponseMessage`. O `nativeFlowResponseMessage.paramsJson` traz os dados preenchidos dentro de `wa_flow_response_params.response_message` (uma string JSON aninhada — precisa de `JSON.parse` duplo).
 
 ```js
-// Tipos: 'available' | 'unavailable' | 'composing' | 'recording' | 'paused'
-await sock.sendPresenceUpdate('composing', jid)   // "digitando..."
-await sock.sendPresenceUpdate('recording', jid)   // "gravando áudio..."
-await sock.sendPresenceUpdate('available', jid)   // Online
-await sock.sendPresenceUpdate('unavailable', jid) // Offline
-
-// Inscrever-se na presença de alguém
-await sock.presenceSubscribe(jid)
+sock.ev.on('messages.upsert', async ({ messages }) => {
+    const m = messages[0]
+    if (m.message?.interactiveResponseMessage) {
+        const nfr = m.message.interactiveResponseMessage.nativeFlowResponseMessage
+
+        if (nfr?.name === 'galaxy_message' && nfr?.paramsJson) {
+            const parsed = JSON.parse(nfr.paramsJson)
+            if (!parsed.wa_flow_response_params) return
+
+            const flowParams  = parsed.wa_flow_response_params
+            const flowId      = flowParams.flow_id || ''
+            const rawResponse = flowParams.response_message || ''
+
+            let screens = []
+            try { screens = JSON.parse(rawResponse).screens || [] } catch {}
+
+            // extrai só os campos preenchidos
+            const campos = {}
+            for (const screen of screens) {
+                for (const comp of (screen.components || [])) {
+                    if (comp.name && comp.value !== undefined && comp.value !== '') {
+                        campos[comp.name] = comp.value
+                    }
+                }
+            }
 
-// Ouvir updates de presença
-sock.ev.on('presence.update', ({ id, presences }) => {
-    console.log(presences)
+            // roteia por flow_id — adicione mais formulários aqui
+            if (flowId === 'SEU_FLOW_ID_AQUI') {
+                let resposta = 'Formulário recebido!\n\n'
+                if (campos.full_name)    resposta += `Nome: ${campos.full_name}\n`
+                if (campos.phone_number) resposta += `Telefone: +${campos.phone_number}\n`
+                if (campos.email)        resposta += `Email: ${campos.email}\n`
+                await sock.sendMessage(m.key.remoteJid, { text: resposta }, { quoted: m })
+            }
+        }
+    }
 })
 ```
 
 ---
 
-## 📌 Notas
+## Changelog
 
-- Todas as funções que enviam mensagens retornam o objeto `WAMessage` com a `key` da mensagem.
-- O campo `key.id` pode ser usado para referenciar a mensagem em edições, deleções e fixações.
-- Ao enviar mídia para grupos, certifique-se que o bot está participante do grupo.
-- Funções Rich (`sendRich*`) requerem que o WhatsApp do destinatário seja uma versão recente.
+### v1.0.6
+- **Fix PTT real** — `ptt: true` agora transcodifica via `ffmpeg` quando necessário, em vez de só etiquetar o mimetype
+- **Fix groupMetadata → sharedLidPhoneCache** — pares LID↔telefone da lista de participantes de grupo agora são registrados no cache (antes eram descartados)
+- **Fix cleanId de identidade própria** — comparação de `sock.user.id`/`sock.user.lid` com sufixo de dispositivo (`:N`) agora preserva o domínio
+- **Guard de pagamento stealth** — `bindPaymentGuard`, evento `messages.decrypt-failed`
+- **Bad MAC Handler** — `BadMacHandler`, `badMacHandler`
+- **getName** — resolução de nome em cascata, nunca vazia
+- **getBestWaVersion** — busca de versão que não falha em silêncio
+- **resolveLidPhoneFromGroup** — força resolução via metadata de grupo
+- **WhatsApp Flows** — suporte documentado a formulários interativos (`nativeFlowResponseMessage`)
+- **isSystemNotification** — flag em mensagens de notificação de sistema
+- Sistema LID/JID avançado com cache bidirecional (`sharedLidPhoneCache`)
+- `lidToJid`, `resolveJid`, `resolveAll`, `normalizeJid`, `validateJid`, `getSenderInfo`
+- Suporte a `@username` — `isUsername`, `resolveUsername`
+
+### v1.0.5
+- Sticker Pack nativo com suporte a animadas e PNG
+- Fix canal newsletter (`extraAttrs` no `plaintext`)
+- Album, Spoiler, ViewOnce V2, Ephemeral, Lottie, Evento
+- Native Flow, Carousel, Template Buttons
+- AI Rich (makeText, makeCode, makeTable, makeList, sendRich)
+- Poll decrypt com `getAggregateVotesInPollMessage`
+- MessageBuilder (`Button`, `ButtonV2`, `Carousel`, `AIRich`)
 
 ---
 
 <div align="center">
 
-**@systemzero/baileys v1.0.3** · Feito com ❤️ por [blackhzx](https://t.me/blackhzx)
+**@systemzero/baileys v1.0.6**
+
+Desenvolvido por [Josué </>](https://t.me/blackhzx) · [Canal WhatsApp](https://whatsapp.com/channel/0029VaqUb9aGk1FxqeKKOd2i) · [systemzone.store](https://systemzone.store)
 
-</div>
+</div>