plogme 2.0.0 → 2.0.2

package/README.md

@@ -1,8 +1,35 @@
-# plogme
-
-`plogme` is a Node.js WhatsApp Web client based on the Baileys protocol implementation. It supports authentication, media, groups, interactive messages, status updates, albums, native flows, rich responses, and experimental Meta AI-style message envelopes.
-
-> **Experimental feature notice:** Rich responses, Meta AI-style metadata, HTML primitives, clipboard addon sections, carousels, and albums use WhatsApp Web protocol structures that may change without notice. Unsupported fields can be ignored, rejected, or rendered differently across WhatsApp versions.
+# Plogme
+
+**Plogme** is a Node.js WhatsApp Web client built on the Baileys protocol implementation. It provides authentication, messaging, media uploads, groups, status updates, interactive messages, albums, rich responses, Meta AI-style envelopes, HTML screens, and selected WhatsApp Web protocol features.
+
+> [!IMPORTANT]
+> Plogme is a protocol library. WhatsApp server behavior and client rendering can change without notice. Rich responses, HTML primitives, native flows, reels, carousels, and experimental protocol fields may render differently across WhatsApp versions.
+
+[![npm version](https://img.shields.io/npm/v/plogme?style=flat-square)](https://www.npmjs.com/package/plogme)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-10b981?style=flat-square&logo=node.js)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/tests-30%20passing-10b981?style=flat-square)](https://github.com/crysnovax/baileys)
+
+## Contents
+
+1. [Installation](#installation)
+2. [Quick start](#quick-start)
+3. [Authentication and pairing](#authentication-and-pairing)
+4. [Sending messages](#sending-messages)
+5. [Media and albums](#media-and-albums)
+6. [Interactive messages](#interactive-messages)
+7. [Rich messages](#rich-messages)
+8. [Rich menus, reels, and grids](#rich-menus-reels-and-grids)
+9. [HTML screens and built-in apps](#html-screens-and-built-in-apps)
+10. [Status updates](#status-updates)
+11. [Groups and group history](#groups-and-group-history)
+12. [Reports and moderation](#reports-and-moderation)
+13. [Experimental bot metadata](#experimental-bot-metadata)
+14. [WhatsApp flows and web views](#whatsapp-flows-and-web-views)
+15. [View-once utilities](#view-once-utilities)
+16. [Connection handling](#connection-handling)
+17. [Security and removed automatic behavior](#security-and-removed-automatic-behavior)
+18. [Development](#development)
+19. [License and support](#license-and-support)
 
 ## Installation
 
@@ -10,29 +37,32 @@
 npm install plogme
 ```
 
-The current package version is **2.0.0**. Use Node.js 20 or newer.
+The package currently requires **Node.js 20 or newer**.
 
-## Important: Join Update Channels Manually
+To install the development branch directly from GitHub:
 
-**Plogme does not automatically follow or subscribe to any WhatsApp channel.** If you want to receive code examples, tutorials, updates, and usage guidance, please join the relevant official channel manually:
+```bash
+npm install github:crysnovax/baileys
+```
 
-- **CODY AI:** [Join the CODY AI WhatsApp channel](https://whatsapp.com/channel/0029Vb8296789inZCpWLuS3T)
-- **CRYSNOVA AI:** [Join the CRYSNOVA AI WhatsApp channel](https://whatsapp.com/channel/0029Vb6pe77K0IBn48HLKb38)
+Plogme is an ES module package. Use `import` syntax in Node.js projects configured with `"type": "module"`.
 
-Joining either channel is optional and is never performed automatically by the package.
+> [!WARNING]
+> Never commit authentication state, private keys, `.env` files, or downloaded session data. Add your session directory to `.gitignore`.
 
 ## Quick start
 
+This is the smallest complete connection example. It saves credentials, reconnects after temporary disconnects, and stops reconnecting after logout.
+
 ```js
-import {
-  makeWASocket,
+import makeWASocket, {
   DisconnectReason,
   useMultiFileAuthState
 } from 'plogme'
 import { Boom } from '@hapi/boom'
 import pino from 'pino'
 
-async function start() {
+async function connect() {
   const { state, saveCreds } = await useMultiFileAuthState('./session')
   const sock = makeWASocket({
     auth: state,
@@ -40,38 +70,60 @@ async function start() {
   })
 
   sock.ev.on('creds.update', saveCreds)
+
   sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
-    if (connection === 'open') console.log('Connected')
-    if (connection === 'close') {
-      const status = new Boom(lastDisconnect?.error)?.output?.statusCode
-      if (status !== DisconnectReason.loggedOut) start()
+    if (connection === 'open') {
+      console.log('Connected to WhatsApp')
+      return
     }
+
+    if (connection !== 'close') return
+
+    const statusCode = new Boom(lastDisconnect?.error)?.output?.statusCode
+    if (statusCode === DisconnectReason.loggedOut) {
+      console.error('Logged out. Remove the old session and pair again.')
+      return
+    }
+
+    console.log('Connection closed; reconnecting')
+    connect().catch(console.error)
   })
+
+  return sock
 }
 
-start()
+await connect()
 ```
 
-Keep authentication files private. Never commit session credentials, private keys, or `.env` files.
-
 ## Authentication and pairing
 
+### Multi-file authentication
+
+`useMultiFileAuthState` is the recommended development setup because credentials and keys are stored as separate files.
+
 ```js
 const { state, saveCreds } = await useMultiFileAuthState('./session')
-
 const sock = makeWASocket({ auth: state })
 sock.ev.on('creds.update', saveCreds)
+```
+
+### Pairing code
 
+Request a pairing code after creating the socket. Supply a phone number in international format without `+`, spaces, or punctuation.
+
+```js
 const code = await sock.requestPairingCode('15551234567')
-console.log(code)
+console.log('Pairing code:', code)
 ```
 
-Pairing codes require the socket to be initialized and a valid phone number in international format.
+Keep the pairing code private and use it only with the WhatsApp account you control.
+
+## Sending messages
 
-## Ordinary text, mentions, reactions, and media
+### Text, mentions, and reactions
 
 ```js
-await sock.sendMessage(jid, { text: 'Hello!' })
+await sock.sendMessage(jid, { text: 'Hello from Plogme' })
 
 await sock.sendMessage(jid, {
   text: 'Hello @15551234567',
@@ -79,11 +131,112 @@ await sock.sendMessage(jid, {
 })
 
 await sock.sendMessage(jid, {
-  react: { text: '👍', key: message.key }
+  react: {
+    text: '👍',
+    key: message.key
+  }
 })
 ```
 
-Media examples:
+### WhatsApp Channels
+
+Resolve a Channel invite code or a full WhatsApp Channel invite URL without
+automatically following the Channel:
+
+```js
+const channel = await sock.newsletterGetInviteInfo(
+  'https://whatsapp.com/channel/0029Vb6pe77K0IBn48HLKb38'
+)
+
+console.log(channel?.id, channel?.name, channel?.description)
+```
+
+React to a Channel post with its Channel JID and `serverId`. Pass `null`,
+`undefined`, or an empty string to remove the reaction:
+
+```js
+await sock.newsletterReactMessage(
+  '120363000000000000@newsletter',
+  '12345',
+  '👍'
+)
+
+await sock.newsletterReactMessage(
+  '120363000000000000@newsletter',
+  '12345',
+  null
+)
+```
+
+### Chat themes and animated wallpapers
+
+Send a chat-theme protocol message with a color scheme and an animated
+wallpaper. `chatThemeId` is normalized to the WhatsApp color-scheme form by
+adding `@Tonal`; use `colorSchemeId` when you already have the complete value.
+`dimLevel` is a normalized value from `0` to `1`.
+
+```js
+await sock.sendMessage(jid, {
+  chatTheme: {
+    chatThemeId: 'Royal-Blue',
+    animatedWallpaper: {
+      id: 'wallpaper-1',
+      dimLevel: 0.25
+    }
+  }
+})
+
+// Equivalent explicit color-scheme form:
+await sock.sendMessage(jid, {
+  chatTheme: {
+    colorSchemeId: 'Royal-Blue@Tonal',
+    animatedWallpaper: {
+      animatedWallpaperId: 'wallpaper-1',
+      opacity: 25
+    }
+  }
+})
+```
+
+### Editing and deleting
+
+```js
+await sock.sendMessage(jid, {
+  text: 'Updated text',
+  edit: message.key
+})
+
+await sock.sendMessage(jid, {
+  caption: 'Updated media caption',
+  edit: message.key
+})
+
+await sock.sendMessage(jid, {
+  delete: message.key
+})
+```
+
+### Forwarding
+
+```js
+await sock.sendMessage(jid, {
+  forward: message,
+  force: true
+})
+```
+
+### Profile name and About status
+
+These methods update the connected account's own profile.
+
+```js
+await sock.updateProfileName('Cody AI')
+await sock.updateProfileStatus('Building helpful WhatsApp tools')
+```
+
+## Media and albums
+
+### Images, video, audio, documents, and stickers
 
 ```js
 await sock.sendMessage(jid, {
@@ -94,161 +247,245 @@ await sock.sendMessage(jid, {
 await sock.sendMessage(jid, {
   video: { url: './video.mp4' },
   caption: 'Video caption',
-  gifPlayback: false
+  gifPlayback: false,
+  ptv: false
+})
+
+await sock.sendMessage(jid, {
+  audio: { url: './voice.ogg' },
+  mimetype: 'audio/ogg; codecs=opus',
+  ptt: true
 })
 
 await sock.sendMessage(jid, {
   document: { url: './report.pdf' },
   mimetype: 'application/pdf',
-  fileName: 'report.pdf'
+  fileName: 'report.pdf',
+  caption: 'Monthly report'
 })
 
 await sock.sendMessage(jid, {
-  audio: { url: './audio.ogg' },
-  mimetype: 'audio/ogg; codecs=opus'
+  sticker: { url: './sticker.webp' }
 })
 ```
 
-## Profile name and About description
+Remote URLs, local file paths, and buffers are supported where the selected media helper accepts them.
+
+> [!WARNING]
+> A URL must point to a real, playable media file. A URL returning an HTML error page, an empty file, or an invalid video container can produce a WhatsApp media verification or download warning even when the library code is correct.
 
-WhatsApp exposes the personal profile description as the **About status**. In
-`plogme`, use `updateProfileStatus`—not `updateProfileDescription`—and pass a
-plain string:
+### GIF playback and video notes
 
 ```js
-await sock.updateProfileStatus('Building helpful bots')
-await sock.updateProfileName('Cody AI')
-```
+await sock.sendMessage(jid, {
+  video: { url: './animation.mp4' },
+  gifPlayback: true,
+  caption: 'Animated clip'
+})
 
-This updates the connected account's own profile. It does not update a contact
-or group description.
+await sock.sendMessage(jid, {
+  video: { url: './video-note.mp4' },
+  ptv: true
+})
+```
 
-## Spoiler messages
+### Albums
 
-For media, use `spoiler: true`. The default native mode serializes the
-supported `contextInfo.isSpoiler` flag:
+Use at least two image or video items. Albums are sent as a parent message followed by separately encrypted media children.
 
 ```js
-await sock.sendMessage(jid, {
-  image: { url: './classified.jpg' },
-  caption: 'Open only when ready',
-  spoiler: true
+await sock.sendAlbumMessage(jid, [
+  { type: 'image', data: { url: './one.jpg' } },
+  { type: 'image', data: { url: './two.jpg' } }
+], {
+  caption: 'Trip photos'
 })
 ```
 
-For clients that do not support native media spoilers, explicitly use the
-compatibility fallback. This sends a view-once envelope; it is **not** the
-same as a native spoiler:
+The general `sendMessage` album form is also supported:
 
 ```js
 await sock.sendMessage(jid, {
-  video: { url: './reveal.mp4' },
-  spoiler: true,
-  mediaSpoilerMode: 'viewOnce'
+  album: [
+    { image: { url: './one.jpg' }, caption: 'First' },
+    { video: { url: './clip.mp4' }, caption: 'Second' }
+  ]
 })
 ```
 
-For text, the default fallback uses WhatsApp's rolling-out `||...||` spoiler
-formatting. Native text metadata can be requested with
-`spoilerMode: 'native'`. Rendering remains client-version dependent.
+Rich-response and bot-forwarded messages cannot be nested as album children. Send them as separate messages.
+
+## Interactive messages
+
+### Buttons and lists
 
 ```js
 await sock.sendMessage(jid, {
-  text: 'The ending is revealed here',
-  spoiler: true
+  text: 'Choose an option',
+  footer: 'Plogme',
+  buttons: [
+    { text: 'Confirm', id: 'confirm' },
+    { text: 'Cancel', id: 'cancel' }
+  ]
 })
-```
 
-## Rich text and Markdown
+await sock.sendMessage(jid, {
+  text: 'Choose a category',
+  title: 'Categories',
+  buttonText: 'Open list',
+  sections: [
+    {
+      title: 'Available categories',
+      rows: [
+        { title: 'Support', description: 'Get help', rowId: 'support' },
+        { title: 'News', description: 'Read updates', rowId: 'news' }
+      ]
+    }
+  ]
+})
+```
 
-`sendRichText` sends Markdown-capable text inside a forwarded GenAI rich-response envelope. Markdown rendering depends on the recipient's WhatsApp client.
+### Native flow
 
 ```js
-await sock.sendRichText(jid, {
-  text: `**Heading**
+await sock.sendWhatsAppFlow(jid, {
+  flowId: 'your-flow-id',
+  flowToken: 'your-flow-token',
+  cta: 'Open form',
+  text: 'Complete this form'
+})
+```
 
-Normal text
+For a rich URL call-to-action:
 
-> This is a blockquote`
+```js
+await sock.sendRichWebview(jid, {
+  url: 'https://example.com/app',
+  text: 'Open the app',
+  buttonText: 'Open',
+  useWebview: true
 })
 ```
 
-A dedicated blockquote helper is also available:
+### Interactive table
 
 ```js
-await sock.sendMarkdownQuote(jid, {
-  text: `Here is the instruction:
-
-> Use this exact logo image.`
+await sock.sendInteractiveTable(jid, {
+  title: 'Deployment status',
+  headers: ['Service', 'State'],
+  rows: [
+    ['API', 'Online'],
+    ['Worker', 'Online']
+  ],
+  buttons: [],
+  footer: 'Updated now'
 })
 ```
 
-## Copy-to-clipboard controls
+## Rich messages
 
-There are two different clipboard-related features:
+Rich messages are forwarded GenAI-style envelopes. The sender now routes rich payloads through normal WhatsApp message generation before relay so clients receive the expected message metadata.
 
-1. `sendCopyButton` creates the inline GenAI `COPY_TO_CLIPBOARD` addon section.
-2. `sendRichTextCopy` and `sendQuoteCopy` place ordinary Markdown content and a clipboard addon section in the same rich response. The text does **not** need to contain a quote.
+> [!NOTE]
+> Rich rendering is client-dependent. A rich message can be structurally valid while a particular WhatsApp build chooses a fallback rendering.
 
-Normal text with a copy action:
+### Rich text and quotes
 
 ```js
-await sock.sendRichTextCopy(jid, {
-  text: 'npm install plogme',
-  copyText: 'npm install plogme',
-  copyLabel: 'Copy command'
+await sock.sendRichText(jid, {
+  text: '**Deployment complete**\n\nThe service is online.'
+})
+
+await sock.sendMarkdownQuote(jid, {
+  text: '> Use the production URL for verification.'
 })
 ```
 
-The same behavior can be requested through `sendRichText` by supplying `copyText`:
+### Copy-to-clipboard actions
 
 ```js
-await sock.sendRichText(jid, {
-  text: 'This is ordinary text with a copy action.',
-  copyText: 'This is ordinary text with a copy action.',
-  copyLabel: 'Copy me'
+await sock.sendCopyButton(jid, {
+  text: 'npm install plogme',
+  label: 'Copy command'
 })
-```
 
-Quote plus copy action:
+await sock.sendRichTextCopy(jid, {
+  text: 'Install the package first.',
+  copyText: 'npm install plogme',
+  copyLabel: 'Copy command'
+})
 
-```js
 await sock.sendQuoteCopy(jid, {
-  text: `Ready-to-paste instruction:
-
-> Use this exact logo image...`,
-  copyText: 'Use this exact logo image...',
-  copyLabel: 'Copy me'
+  text: '> Run the tests before publishing.',
+  copyText: 'npm test',
+  copyLabel: 'Copy test command'
 })
 ```
 
-`COPY_TO_CLIPBOARD` is an in-message rich-response action. It is different from the separate copy/forward/like/dislike toolbar that WhatsApp may render below first-party Meta AI messages. That toolbar is client-generated and is not authoritatively controllable through this API.
-
-## Rich links, images, HTML, and menus
+### Rich image and inline links
 
 ```js
-await sock.sendRichLink(jid, {
-  text: 'Open the deployment site',
-  url: 'https://example.com'
-})
-
 await sock.sendRichImage(jid, {
   url: 'https://example.com/image.jpg',
   mimeType: 'image/jpeg'
 })
 
-await sock.sendHtmlMessage(jid, {
-  html: '<h1>Hello</h1><p>Rendered HTML content</p>'
+await sock.sendRichLink(jid, {
+  text: 'Open the documentation',
+  links: [
+    {
+      text: 'Documentation',
+      url: 'https://example.com/docs',
+      isTrusted: true
+    }
+  ]
 })
 ```
 
-`sendHtmlMessage` uses an experimental HTML primitive. Do not pass untrusted user input into HTML without sanitizing it.
+### Rich tables, lists, code, and LaTeX
 
-The experimental rich menu helper accepts a header, body buttons, cards, and footer:
+```js
+await sock.sendTable(
+  jid,
+  'Build status',
+  ['Service', 'State'],
+  [
+    { items: ['API', 'Online'] },
+    { items: ['Worker', 'Online'] }
+  ]
+)
+
+await sock.sendList(jid, 'Next steps', [
+  { title: 'Test', description: 'Run the test suite' },
+  { title: 'Deploy', description: 'Publish the verified build' }
+])
+
+await sock.sendCodeBlock(jid, 'console.log("hello")', undefined, {
+  language: 'javascript'
+})
+
+await sock.sendRichAIResponse(jid, {
+  table: {
+    title: 'Status',
+    headers: ['Name', 'Value'],
+    rows: [['version', '2.0.1']]
+  }
+})
+```
+
+`sendRichAIResponse` also accepts `list`, `codeBlock`, and `latex` content objects. For a pre-existing Meta AI response, `captureAndResendUnifiedResponse(jid, message, quoted)` captures and resends its unified response.
+
+## Rich menus, reels, and grids
+
+### Original Gen4 rich menu
+
+Use `sock.richMenu` for the original Gen4-style menu. This is the primary rich-menu API.
 
 ```js
 await sock.richMenu(jid, {
-  header: { title: 'Deploy Suite' },
+  header: {
+    title: 'Deployment tools'
+  },
   body: {
     title: 'Choose an action',
     buttons: [
@@ -256,136 +493,150 @@ await sock.richMenu(jid, {
       { id: 'logs', text: 'View logs' }
     ]
   },
-  footer: { text: 'Example menu' }
+  footer: {
+    text: 'Open documentation',
+    url: 'https://example.com/docs'
+  }
 })
 ```
 
-Always validate button IDs on the server. Never treat a user-controlled button ID as an authorization grant.
+Cards and carousel layout are supported:
 
-## Carousels and rich button grids
+```js
+await sock.richMenu(jid, {
+  body: {
+    carousel: true,
+    cards: [
+      {
+        title: 'Production',
+        toast: 'Production selected',
+        buttons: [{ id: 'production', text: 'Open' }]
+      },
+      {
+        title: 'Staging',
+        toast: 'Staging selected',
+        buttons: [{ id: 'staging', text: 'Open' }]
+      }
+    ]
+  }
+})
+```
 
-Use `sendRichButtonGrid` for media cards with native-flow buttons. A carousel needs at least one valid image, video, or product header per card. The helper accepts either `buttons` or `nativeFlow`.
+Validate button IDs on the server. A button ID is an event value, not an authorization grant.
+
+### Reels and rich media
+
+`sendReels` accepts an array of reel records. The main rich-media path is used for reels, sources, links, tables, and future rich payloads.
 
 ```js
-await sock.sendRichButtonGrid(jid, {
-  text: 'Choose an option',
-  footer: 'Select one',
-  cards: [
-    {
-      image: { url: './first.jpg' },
-      title: 'First card',
-      caption: 'First card description',
-      buttons: [
-        { id: 'first', text: 'Select first' }
-      ]
-    },
-    {
-      image: { url: './second.jpg' },
-      title: 'Second card',
-      caption: 'Second card description',
-      buttons: [
-        { id: 'second', text: 'Select second' }
-      ]
-    }
-  ]
+await sock.sendReels(jid, [
+  {
+    title: 'Example reel',
+    creator: 'Example creator',
+    videoUrl: 'https://cdn.example.com/reel.mp4',
+    thumbnailUrl: 'https://cdn.example.com/reel.jpg',
+    profileIconUrl: 'https://cdn.example.com/avatar.jpg',
+    likesCount: 120,
+    sharesCount: 8,
+    viewCount: 2400,
+    reelSource: 'IG',
+    isVerified: true
+  }
+], undefined, {
+  text: 'Featured reels'
 })
 ```
 
-Supported button properties include `id`, `text`, `url`, `call`, and `copy`. Carousel cards must have valid media headers. A card containing only text is not a valid carousel card.
+Use a valid MP4 or another supported playable video. Test the URL with a media probe before sending it.
 
-For a single native-flow message:
+For a general rich response:
 
 ```js
-await sock.sendMessage(jid, {
-  text: 'Open the site',
-  nativeFlow: [
-    { url: 'https://example.com', text: 'Open' }
+await sock.sendRichMedia(jid, {
+  contentText: 'A rich response',
+  reels: [
+    {
+      title: 'Short clip',
+      url: 'https://cdn.example.com/clip.mp4'
+    }
   ]
 })
 ```
 
-## Media albums
+### Rich button grid
 
-Albums are sent as a parent album message followed by associated image or video child messages. Provide at least two media items:
+`sendRichButtonGrid` sends ordinary message cards with native-flow buttons. It is distinct from the original Gen4 `richMenu` envelope.
 
 ```js
-await sock.sendMessage(jid, {
-  album: [
+await sock.sendRichButtonGrid(jid, {
+  text: 'Choose a service',
+  footer: 'Select one',
+  cards: [
     {
-      image: { url: './image-1.jpg' },
-      caption: 'First image'
+      title: 'Status',
+      image: { url: './status.jpg' },
+      buttons: [{ text: 'View status', id: 'status' }]
     },
     {
-      image: { url: './image-2.jpg' },
-      caption: 'Second image'
+      title: 'Logs',
+      image: { url: './logs.jpg' },
+      buttons: [{ text: 'View logs', id: 'logs' }]
     }
   ]
 })
 ```
 
-Album children are required to be actual `imageMessage` or `videoMessage` payloads. A `botForwardedMessage` or `richResponseMessage` cannot be nested as an album child. If rich text or a rich-response envelope is needed, send it as a separate message before or after the album.
+## HTML screens and built-in apps
 
-## Experimental bot metadata
-
-The following methods attach newer `WAProto` bot metadata fields through `messageContextInfo.botMetadata`. They are experimental and may have no visible effect unless the receiving client and server support the corresponding first-party feature.
-
-### Diagnostics metadata
+### Ordinary HTML message
 
 ```js
-await sock.sendBotDiagnostics(jid, {
-  text: 'Diagnostics test',
-  botBackend: 1, // 0 = AAPI, 1 = CLIPPY
-  toolsUsed: ['web_search', 'image_search'],
-  isThinking: true
+await sock.sendHtmlMessage(jid, {
+  html: '<h1>Hello</h1><p>Rendered HTML content.</p>',
+  trustedSources: []
 })
 ```
 
-### Command metadata
+### Tabbed rich HTML screen
 
 ```js
-await sock.sendBotCommand(jid, {
-  text: 'Command metadata test',
-  commandName: 'summarize',
-  commandDescription: 'Summarize the current conversation',
-  commandPrompt: 'Summarize the current conversation in five bullets'
+await sock.sendRichHtmlMessage(jid, {
+  title: 'Example app',
+  url: 'https://your-domain.example',
+  trustedSources: ['your-domain.example'],
+  tabs: [
+    {
+      tab_header: 'Home',
+      html: '<h1>Home</h1><p>Welcome.</p>'
+    },
+    {
+      tab_header: 'Help',
+      html: '<h2>Help</h2><p>Tap the buttons to continue.</p>'
+    }
+  ]
 })
 ```
 
-### Resolved tool-call metadata
+`trustedSources` and `url` are application-specific. Sanitize user-controlled HTML before sending it.
 
-```js
-await sock.sendBotToolResult(jid, {
-  text: 'Tool result test',
-  toolCallId: `tool-${Date.now()}`,
-  resolutionData: {
-    status: 'success',
-    result: { value: 'Completed' }
-  }
-})
-```
-
-You may provide a pre-serialized result instead:
+### Built-in screens
 
 ```js
-await sock.sendBotToolResult(jid, {
-  text: 'Serialized result',
-  toolCallId: 'tool-123',
-  resolutionDataSerialized: JSON.stringify({
-    status: 'success',
-    value: 'Completed'
-  })
-})
+await sock.sendSlotMachine(jid)
+await sock.sendMiniApp(jid, { title: 'Pairing mini-app' })
+await sock.sendWebsitePreview(jid, 'https://example.com')
+await sock.sendLinkPreview(jid, 'https://example.com')
 ```
 
-These methods do not fabricate Meta's verification certificates or signatures. They should not be treated as a way to impersonate a first-party Meta AI response.
+The built-in mini-app uses its configured first-party source. Generic rich HTML remains configurable.
 
 ## Status updates
 
-Use `backgroundColor` rather than `backgroundArgb` in the high-level API:
+`sendStatus` sends a status update and resolves recipients from `statusJidList`.
 
 ```js
 await sock.sendStatus({
-  text: 'Service status: online',
+  text: 'Service online',
   backgroundColor: 0xff102a43,
   font: 2
 }, {
@@ -393,198 +644,156 @@ await sock.sendStatus({
 })
 ```
 
-Alternatively, send directly to `status@broadcast` when using the raw status protocol supported by the installed version.
+For status mentions:
+
+```js
+await sock.sendStatusMention(
+  { text: 'Welcome to the team' },
+  ['15551234567@s.whatsapp.net']
+)
+```
 
-## Groups
+## Groups and group history
 
 ```js
 const metadata = await sock.groupMetadata(groupJid)
+
 await sock.groupParticipantsUpdate(groupJid, [userJid], 'add')
 await sock.groupParticipantsUpdate(groupJid, [userJid], 'remove')
 await sock.groupSettingUpdate(groupJid, 'announcement')
 ```
 
-Group administration requires the corresponding privileges. Handle permission failures and disconnected sessions.
+### Member labels
 
-### Group member labels
-
-`updateMemberLabel` sets the connected account's own custom member label in a
-group. The first argument must be the **group JID** (`123456789-123456@g.us`),
-not the member's individual JID:
+`updateMemberLabel` sets the connected account's own label in a group.
 
 ```js
 await sock.updateMemberLabel(groupJid, 'Developer')
+await sock.updateMemberLabel(groupJid, '') // remove the label
 ```
 
-To remove the label, pass an empty string:
+### Group history sharing
 
 ```js
-await sock.updateMemberLabel(groupJid, '')
+await sock.toggleGroupHistory(groupJid, true)  // all members
+await sock.toggleGroupHistory(groupJid, false) // admins only
 ```
 
-Labels are limited to 30 characters by the protocol. This is not an admin
-operation for assigning labels to arbitrary participants; WhatsApp associates
-the label with the account that sends the protocol message.
+## Reports and moderation
 
-## WhatsApp Flows and web views
+The reporting APIs have different wire operations. Use the method that matches the action you intend to perform.
 
 ```js
-await sock.sendWhatsAppFlow(jid, {
-  flowId: '1234567890',
-  flowToken: 'example-token',
-  cta: 'Open flow',
-  text: 'Complete this form'
-})
+await sock.reportSpam(
+  groupJid,
+  [{ id: messageId, from: userJid, t: Math.floor(Date.now() / 1000) }],
+  'group_info_report',
+  'Example group'
+)
 
-await sock.sendRichWebview(jid, {
-  url: 'https://example.com/app',
-  text: 'Open the app',
-  buttonText: 'Open'
-})
+const userAccepted = await sock.reportUser(userJid, 'spam')
+const messageAccepted = await sock.reportMessage(
+  userJid,
+  messageId,
+  'harassment',
+  participantJid
+)
+await sock.reportAndBlockUser(userJid, 'scam')
 ```
 
-The flow ID, token, and hosted URL must be valid for the target business configuration.
+`reportUser` and `reportMessage` return whether WhatsApp acknowledged the request. An acknowledgement is not a guarantee of a particular moderation outcome.
 
-## Message options
+## Experimental bot metadata
+
+These methods attach experimental fields under `messageContextInfo.botMetadata`.
 
 ```js
-await sock.sendMessage(jid, {
-  text: 'Disappearing message',
-  ephemeralExpiration: 86400
+await sock.sendBotDiagnostics(jid, {
+  text: 'Diagnostics test',
+  botBackend: 1,
+  toolsUsed: ['web_search'],
+  isThinking: false
 })
 
-await sock.sendMessage(jid, {
-  text: 'Updated text',
-  edit: message.key
+await sock.sendBotCommand(jid, {
+  text: 'Command test',
+  commandName: 'summarize',
+  commandDescription: 'Summarize the conversation',
+  commandPrompt: 'Summarize the conversation in five bullets'
 })
 
-await sock.sendMessage(jid, {
-  delete: message.key
+await sock.sendBotToolResult(jid, {
+  text: 'Tool completed',
+  toolCallId: 'tool-123',
+  resolutionData: { status: 'success', value: 42 }
 })
 ```
 
-Raw protocol fields are version-dependent. Unsupported fields may be ignored or rejected by WhatsApp.
-
-## Error handling and reconnection
+These methods do not provide Meta's private verification credentials and must not be used to impersonate a first-party Meta AI message.
 
-Connections may close because of logout, network interruption, protocol updates, or server-side session invalidation. Avoid starting multiple concurrent connection loops.
+## WhatsApp flows and web views
 
 ```js
-sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
-  if (connection !== 'close') return
-
-  const status = new Boom(lastDisconnect?.error)?.output?.statusCode
-  if (status === DisconnectReason.loggedOut) {
-    console.error('Logged out; remove the old session and pair again.')
-    return
-  }
+await sock.sendWhatsAppFlow(jid, {
+  flowId: 'your-flow-id',
+  flowToken: 'your-flow-token',
+  cta: 'Open form',
+  text: 'Complete this form'
+})
 
-  console.log('Connection interrupted; reconnect with backoff.')
+await sock.sendRichWebview(jid, {
+  url: 'https://example.com/app',
+  text: 'Open the app',
+  buttonText: 'Open'
 })
 ```
 
-## Reporting, group history, rich HTML, and source grep
-
-Version 1.0.6 adds the realvare-style `w:report` methods without replacing plogme's existing evidence-based `reportSpam` method. The methods use different WhatsApp IQ namespaces and should be selected according to the operation you intend to perform.
+Flow identifiers and tokens must belong to a valid business configuration.
 
-| API | Wire operation | Use |
-| --- | --- | --- |
-| `reportSpam(jid, messages, spamFlow, subject)` | `xmlns="spam"` → `spam_list` | Report a chat or group with message evidence. |
-| `reportUser(jid, reason, waitForAckMs)` | `xmlns="w:report"` → `user` | Report one user. |
-| `reportMessage(jid, messageId, reason, participantJid, waitForAckMs)` | `xmlns="w:report"` → `message` | Report one message. |
-| `reportAndBlockUser(jid, reason, waitForAckMs)` | `w:report` followed by block | Report a user and then block them. |
+## View-once utilities
 
 ```js
-// Existing plogme spam-list report with evidence.
-await sock.reportSpam(
-  '1203630@g.us',
-  [{ id: 'ABCD1234', from: '15550001111@s.whatsapp.net', t: 1710000000 }],
-  'group_info_report',
-  'Example group'
-)
+const info = sock.getViewOnceInfo(message)
+console.log(info)
 
-// New direct report methods.
-const acknowledged = await sock.reportUser('15550001111@s.whatsapp.net', 'spam')
-const messageAcknowledged = await sock.reportMessage(
-  '15550001111@s.whatsapp.net', 'ABCD1234', 'harassment',
-  '15550001111@s.whatsapp.net'
-)
-await sock.reportAndBlockUser('15550001111@s.whatsapp.net', 'scam')
+if (sock.isViewOnce(message)) {
+  await sock.autoVV(message)
+}
 ```
 
-`reportUser` and `reportMessage` return `true` when WhatsApp acknowledges the IQ request and `false` when it times out. A timeout does not prove delivery failed; the request may already have reached the server.
+`autoVV` and `antiVV` are utilities for view-once handling. Their behavior depends on the message shape and client version; use them only for messages you are authorized to process.
 
-### Group history sharing
+## Connection handling
 
-`toggleGroupHistory(jid, true)` selects `ALL_MEMBER_SHARE`; passing `false` selects `ADMIN_SHARE` through the WhatsApp MEX endpoint:
+A connection can close because of logout, network interruption, protocol changes, or session invalidation. Avoid starting multiple reconnect loops for the same socket.
 
 ```js
-await sock.toggleGroupHistory('1203630@g.us', true)
-await sock.toggleGroupHistory('1203630@g.us', false)
-```
-
-### Two HTML transports
-
-`sendHtmlMessage` sends the ordinary single-screen `FOAHtmlPrimitiveDemoDONOTUSE` envelope. `sendRichHtmlMessage` is the reusable transport for interactive GenAI HTML screens like tabbed games; it uses `GenAIaeacdsnwHtmlPrimitive` inside `FOAIDNixelButtonSheets` and supports multiple tabs.
+sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection !== 'close') return
 
-```js
-await sock.sendHtmlMessage(jid, {
-  html: '<h1>Simple screen</h1><p>One HTML payload.</p>',
-  trustedSources: []
-})
+  const statusCode = new Boom(lastDisconnect?.error)?.output?.statusCode
+  if (statusCode === DisconnectReason.loggedOut) {
+    console.error('Logged out; pair again with a new session')
+    return
+  }
 
-await sock.sendRichHtmlMessage(jid, {
-  title: 'Games',
-  url: 'https://your-domain.example',
-  trustedSources: ['your-domain.example'],
-  tabs: [
-    { tab_header: 'mini-app', html: '<canvas id="game"></canvas><script>/* game */</script>' },
-    { tab_header: 'Instructions', html: '<h2>How to play</h2><p>Tap to jump.</p>' }
-  ]
+  setTimeout(() => {
+    connect().catch(console.error)
+  }, 3000)
 })
 ```
 
-The rich transport is deliberately separate because clients that render the normal HTML primitive do not necessarily open the embedded-screen/tabbed envelope the same way.
-
-The built-in `sendSlotMachine` keeps its existing ordinary HTML transport. The attached interactive mini-app is available as `sendMiniApp`; because it uses the embedded-screen envelope, plogme configures that built-in game with the owned `pair.crysnova.link` source:
-
-```js
-await sock.sendMiniApp(jid)
-await sock.sendMiniApp(jid, { title: 'My mini-app' })
-```
-
-The `sendRichHtmlMessage` function itself remains neutral: user-supplied screens do not inherit `pair.crysnova.link` and should provide their own `url` and `trustedSources` when those fields are needed.
-
-### Reusable source grep
-
-`grepSource` is exported from `lib/Utils/index.js`, and `sock.grepCode` is available after socket creation. It returns exact relative file paths, one-based line numbers, columns, and matching source lines without invoking a shell.
-
-```js
-const matches = sock.grepCode('sendRichHtmlMessage', { maxResults: 20 })
-console.log(matches)
-// [{ file: 'lib/Socket/messages-send.js', line: 2705, column: 12, text: '...' }]
-
-const reportMatches = sock.grepCode('reportMessage', { caseSensitive: false })
-const regexMatches = sock.grepCode('report(User|Message)', { regex: true, flags: 'i' })
-```
-
-By default the search covers `lib` and `WAProto`; `includeReadme: true` also searches the README.
-
-## Changes to Automatic Behaviors
-
-Previous versions of Plogme included several related behaviors that have been removed from the npm release:
+## Security and removed automatic behavior
 
-- Automatic following of the project's official WhatsApp channel.
-- Anti-rebranding/anti-brand enforcement.
-- Device fingerprinting and remote attestation, which collected machine characteristics such as the hostname, operating system, CPU model, architecture, and Node.js version before sending a fingerprint to an external verification service.
+Plogme does not automatically follow WhatsApp channels, fingerprint the host machine, contact a remote attestation service, or enforce rebranding through runtime code.
 
-These behaviors were not introduced with malicious intent. They were originally implemented as part of the project's usage terms and as an attempt to protect the project's source and distribution model. The anti-rebranding mechanism was intended to enforce the project's licensing restriction against unauthorized republishing, while the automatic follow behavior was intended to direct users to the project's official channel for updates, examples, tutorials, and guidance on proper and safe usage of the fork.
+> [!NOTE]
+> Official update channels are optional. Users who want updates must join them manually:
+>
+> - [CODY AI WhatsApp channel](https://whatsapp.com/channel/0029Vb8296789inZCpWLuS3T)
+> - [CRYSNOVA AI WhatsApp channel](https://whatsapp.com/channel/0029Vb6pe77K0IBn48HLKb38)
 
-Users were previously informed about these behaviors and advised not to use the package if they did not agree with them.
-
-However, these mechanisms went beyond what should be expected from a library and could result in behavior that users did not explicitly initiate. For transparency, predictability, and a better npm package experience, these mechanisms have now been completely removed.
-
-Current Plogme releases do not automatically follow external accounts or channels, do not enforce branding or rebranding restrictions through runtime behavior, and do not fingerprint the host machine or contact a remote attestation service for that purpose. The project's licensing terms still apply; removing runtime enforcement does not grant permission to violate the applicable license.
+The project license still applies. Removing runtime enforcement does not change the license terms.
 
 ## Development
 
@@ -593,80 +802,18 @@ npm install
 npm test
 ```
 
-Before publishing, verify generated protobuf files, package contents, version metadata, and that no authentication state or environment files are included.
-
-## License
-
-Review the included license before distributing applications built with `plogme`. Keep required notices with redistributed source and binaries.
-
-## Support
-
-For implementation questions, include the Node.js version, `plogme` version, operating system, relevant error text, and a minimal reproducible example. Never include authentication state or private account data in an issue.
+Before publishing, verify the package contents and ensure no session data, private keys, or environment files are included.
 
+The repository includes generated WhatsApp protocol files under `WAProto/`. Changes to generated protocol definitions should be made deliberately and tested against the installed WhatsApp client versions you support.
 
-## Ported WhatsApp Web protocol features
-
-The bundled WAProto schema is updated to WhatsApp Web version `2.3000.1047412487`, with the generated runtime, TypeScript declarations, and connection version updated together. Selected support includes newsletter follower-invite base/V2 fields, ACP2 receive-state extraction, animated wallpaper encoding, and nested audio in sticker messages. These remain experimental and client-dependent.
-
-### Animated wallpaper
-
-```js
-await sock.sendMessage(jid, {
-  chatTheme: {
-    animatedWallpaper: { id: 'wallpaper-id', dimLevel: 0.25 }
-  }
-})
-```
-
-### Sticker with audio
+## License and support
 
-```js
-await sock.sendMessage(jid, {
-  sticker: { url: './sticker.webp' },
-  stickerAudio: { url: './sound.ogg' }
-})
-```
+Review [`LICENSE`](LICENSE) before redistributing applications or modified source.
 
-### Newsletter follower invites
+For implementation questions, include the Node.js version, Plogme version, operating system, relevant error text, and a minimal reproduction. Do not include authentication state or private account data.
 
-```js
-await sock.sendMessage(jid, {
-  newsletterFollowerInvite: {
-    newsletterJid: '123456789@newsletter',
-    newsletterName: 'My newsletter',
-    caption: 'Follow this channel'
-  }
-})
-
-await sock.sendMessage(jid, {
-  newsletterFollowerInviteMessageV2: {
-    newsletterJid: '123456789@newsletter',
-    newsletterName: 'My newsletter',
-    caption: 'Follow this channel'
-  }
-})
-```
-
-### Device-scoped relay options
-
-`relayMessage` supports `isSecret`, `protected`, and `me` for supported private-chat device fan-out paths. These select recipients and may add `device_fanout`; they are not encryption, access-control, or delivery guarantees and may not behave identically for groups, statuses, retries, or future clients. They are unrelated to the protobuf field `messageContextInfo.messageSecret`.
-
-```js
-await sock.relayMessage(jid, message, {
-  messageId: messageId,
-  isSecret: true
-})
-```
-
-### Explicit album wrapper
-
-Albums remain parent/child wire messages: one album header is relayed first, followed by separately encrypted image/video children associated with the parent key. The receiver must group them visually. The explicit wrapper accepts typed media objects and applies a caption to the first child:
-
-```js
-await sock.sendAlbumMessage(jid, [
-  { type: 'image', data: { url: './one.jpg' } },
-  { type: 'image', data: { url: './two.jpg' } }
-], { caption: 'Album caption' })
-```
+## References
 
-Rich HTML and bot-forwarded messages cannot be album children; send those separately. Album grouping is still dependent on WhatsApp server/client behavior.
+[1]: https://github.com/crysnovax/baileys "Plogme source repository"
+[2]: https://www.npmjs.com/package/plogme "Plogme on npm"
+[3]: https://github.com/WhiskeySockets/Baileys "Baileys protocol implementation"