plogme 1.0.3 → 1.0.5

package/README.md

@@ -1,8 +1,8 @@
 # plogme
 
-A Node.js WhatsApp Web API client for building messaging integrations with authentication, media transfer, groups, interactive messages, status updates, and rich message composition.
+`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.
 
-> **Package naming note:** npm scoped packages require a scope and package name. The valid package form is `plogme`; the bare string `@plogme` is a scope, not an installable package name by itself.
+> **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.
 
 ## Installation
 
@@ -10,15 +10,7 @@ A Node.js WhatsApp Web API client for building messaging integrations with authe
 npm install plogme
 ```
 
-For a repository checkout:
-
-```bash
-npm install github:crysnovax/baileys
-```
-
-## Requirements
-
-The package supports current Node.js LTS releases. Use Node.js 20 or newer for the latest runtime and dependency compatibility.
+The current package version is **1.0.4**. Use Node.js 20 or newer.
 
 ## Quick start
 
@@ -33,164 +25,452 @@ import pino from 'pino'
 
 async function start() {
   const { state, saveCreds } = await useMultiFileAuthState('./session')
-  const socket = makeWASocket({
+  const sock = makeWASocket({
     auth: state,
     logger: pino({ level: 'silent' })
   })
 
-  socket.ev.on('creds.update', saveCreds)
-  socket.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  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()
     }
   })
-
-  socket.ev.on('messages.upsert', async ({ messages }) => {
-    const message = messages[0]
-    if (!message?.message) return
-    await socket.sendMessage(message.key.remoteJid, { text: 'Hello from plogme' })
-  })
 }
 
 start()
 ```
 
-## Authentication
+Keep authentication files private. Never commit session credentials, private keys, or `.env` files.
 
-The recommended authentication state is multi-file authentication:
+## Authentication and pairing
 
 ```js
-import { useMultiFileAuthState } from 'plogme'
-
 const { state, saveCreds } = await useMultiFileAuthState('./session')
-```
 
-Pairing codes can be requested after the socket has initialized:
+const sock = makeWASocket({ auth: state })
+sock.ev.on('creds.update', saveCreds)
 
-```js
-const code = await socket.requestPairingCode('15551234567')
+const code = await sock.requestPairingCode('15551234567')
 console.log(code)
 ```
 
-Keep authentication files private. Do not commit session credentials, private keys, or environment files to a public repository.
+Pairing codes require the socket to be initialized and a valid phone number in international format.
 
-## Text, mentions, and reactions
+## Ordinary text, mentions, reactions, and media
 
 ```js
-await socket.sendMessage(jid, { text: 'Hello!' })
+await sock.sendMessage(jid, { text: 'Hello!' })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   text: 'Hello @15551234567',
   mentions: ['15551234567@s.whatsapp.net']
 })
 
-await socket.sendMessage(jid, {
-  react: { text: '✅', key: message.key }
+await sock.sendMessage(jid, {
+  react: { text: '👍', key: message.key }
 })
 ```
 
-## Media
+Media examples:
 
 ```js
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   image: { url: './image.jpg' },
   caption: 'Image caption'
 })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   video: { url: './video.mp4' },
   caption: 'Video caption',
   gifPlayback: false
 })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   document: { url: './report.pdf' },
   mimetype: 'application/pdf',
   fileName: 'report.pdf'
 })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   audio: { url: './audio.ogg' },
   mimetype: 'audio/ogg; codecs=opus'
 })
 ```
 
-## Interactive messages
+## Profile name and About description
+
+WhatsApp exposes the personal profile description as the **About status**. In
+`plogme`, use `updateProfileStatus`—not `updateProfileDescription`—and pass a
+plain string:
+
+```js
+await sock.updateProfileStatus('Building helpful bots')
+await sock.updateProfileName('Cody AI')
+```
+
+This updates the connected account's own profile. It does not update a contact
+or group description.
+
+## Spoiler messages
+
+For media, use `spoiler: true`. The default native mode serializes the
+supported `contextInfo.isSpoiler` flag:
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: './classified.jpg' },
+  caption: 'Open only when ready',
+  spoiler: true
+})
+```
+
+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:
+
+```js
+await sock.sendMessage(jid, {
+  video: { url: './reveal.mp4' },
+  spoiler: true,
+  mediaSpoilerMode: 'viewOnce'
+})
+```
+
+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.
+
+```js
+await sock.sendMessage(jid, {
+  text: 'The ending is revealed here',
+  spoiler: true
+})
+```
+
+## Rich text and Markdown
+
+`sendRichText` sends Markdown-capable text inside a forwarded GenAI rich-response envelope. Markdown rendering depends on the recipient's WhatsApp client.
+
+```js
+await sock.sendRichText(jid, {
+  text: `**Heading**
+
+Normal text
+
+> This is a blockquote`
+})
+```
+
+A dedicated blockquote helper is also available:
+
+```js
+await sock.sendMarkdownQuote(jid, {
+  text: `Here is the instruction:
+
+> Use this exact logo image.`
+})
+```
+
+## Copy-to-clipboard controls
+
+There are two different clipboard-related features:
+
+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.
+
+Normal text with a copy action:
+
+```js
+await sock.sendRichTextCopy(jid, {
+  text: 'npm install plogme',
+  copyText: 'npm install plogme',
+  copyLabel: 'Copy command'
+})
+```
 
-The client supports button, list, template, carousel, and native-flow message structures exposed by the installed library version. A basic button example is:
+The same behavior can be requested through `sendRichText` by supplying `copyText`:
 
 ```js
-await socket.sendMessage(jid, {
+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'
+})
+```
+
+Quote plus copy action:
+
+```js
+await sock.sendQuoteCopy(jid, {
+  text: `Ready-to-paste instruction:
+
+> Use this exact logo image...`,
+  copyText: 'Use this exact logo image...',
+  copyLabel: 'Copy me'
+})
+```
+
+`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
+
+```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>'
+})
+```
+
+`sendHtmlMessage` uses an experimental HTML primitive. Do not pass untrusted user input into HTML without sanitizing it.
+
+The experimental rich menu helper accepts a header, body buttons, cards, and footer:
+
+```js
+await sock.richMenu(jid, {
+  header: { title: 'Deploy Suite' },
+  body: {
+    title: 'Choose an action',
+    buttons: [
+      { id: 'deploy', text: 'Deploy' },
+      { id: 'logs', text: 'View logs' }
+    ]
+  },
+  footer: { text: 'Example menu' }
+})
+```
+
+Always validate button IDs on the server. Never treat a user-controlled button ID as an authorization grant.
+
+## Carousels and rich button grids
+
+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`.
+
+```js
+await sock.sendRichButtonGrid(jid, {
   text: 'Choose an option',
-  footer: 'Menu',
-  buttons: [
-    { buttonId: 'confirm', buttonText: { displayText: 'Confirm' }, type: 1 },
-    { buttonId: 'cancel', buttonText: { displayText: 'Cancel' }, type: 1 }
-  ],
-  headerType: 1
+  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' }
+      ]
+    }
+  ]
 })
 ```
 
-Always validate button input on the server. A button identifier is user-controlled input and must not be treated as an authorization grant.
+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.
 
-## Groups
+For a single native-flow message:
 
 ```js
-const metadata = await socket.groupMetadata(groupJid)
-await socket.groupParticipantsUpdate(groupJid, [userJid], 'add')
-await socket.groupParticipantsUpdate(groupJid, [userJid], 'remove')
-await socket.groupSettingUpdate(groupJid, 'announcement')
+await sock.sendMessage(jid, {
+  text: 'Open the site',
+  nativeFlow: [
+    { url: 'https://example.com', text: 'Open' }
+  ]
+})
 ```
 
-Group administration calls require the connected account to have the corresponding privileges. Applications should handle permission failures and disconnected sessions gracefully.
+## Media albums
+
+Albums are sent as a parent album message followed by associated image or video child messages. Provide at least two media items:
+
+```js
+await sock.sendMessage(jid, {
+  album: [
+    {
+      image: { url: './image-1.jpg' },
+      caption: 'First image'
+    },
+    {
+      image: { url: './image-2.jpg' },
+      caption: 'Second image'
+    }
+  ]
+})
+```
+
+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.
+
+## 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
+
+```js
+await sock.sendBotDiagnostics(jid, {
+  text: 'Diagnostics test',
+  botBackend: 1, // 0 = AAPI, 1 = CLIPPY
+  toolsUsed: ['web_search', 'image_search'],
+  isThinking: true
+})
+```
+
+### Command metadata
+
+```js
+await sock.sendBotCommand(jid, {
+  text: 'Command metadata test',
+  commandName: 'summarize',
+  commandDescription: 'Summarize the current conversation',
+  commandPrompt: 'Summarize the current conversation in five bullets'
+})
+```
+
+### Resolved tool-call metadata
+
+```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:
+
+```js
+await sock.sendBotToolResult(jid, {
+  text: 'Serialized result',
+  toolCallId: 'tool-123',
+  resolutionDataSerialized: JSON.stringify({
+    status: 'success',
+    value: 'Completed'
+  })
+})
+```
+
+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.
 
 ## Status updates
 
-Status messages can be sent with text, images, videos, captions, and mentions according to the message content supported by the current protocol version:
+Use `backgroundColor` rather than `backgroundArgb` in the high-level API:
 
 ```js
-await socket.sendMessage('status@broadcast', {
+await sock.sendStatus({
   text: 'Service status: online',
-  backgroundArgb: 0xff102a43,
+  backgroundColor: 0xff102a43,
   font: 2
+}, {
+  statusJidList: ['15551234567@s.whatsapp.net']
 })
 ```
 
+Alternatively, send directly to `status@broadcast` when using the raw status protocol supported by the installed version.
+
+## Groups
+
+```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.
+
+### 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:
+
+```js
+await sock.updateMemberLabel(groupJid, 'Developer')
+```
+
+To remove the label, pass an empty string:
+
+```js
+await sock.updateMemberLabel(groupJid, '')
+```
+
+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.
+
+## WhatsApp Flows and web views
+
+```js
+await sock.sendWhatsAppFlow(jid, {
+  flowId: '1234567890',
+  flowToken: 'example-token',
+  cta: 'Open flow',
+  text: 'Complete this form'
+})
+
+await sock.sendRichWebview(jid, {
+  url: 'https://example.com/app',
+  text: 'Open the app',
+  buttonText: 'Open'
+})
+```
+
+The flow ID, token, and hosted URL must be valid for the target business configuration.
+
 ## Message options
 
 ```js
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   text: 'Disappearing message',
   ephemeralExpiration: 86400
 })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   text: 'Updated text',
   edit: message.key
 })
 
-await socket.sendMessage(jid, {
+await sock.sendMessage(jid, {
   delete: message.key
 })
 ```
 
-Use raw protocol options only when the target client and installed library version support them. Unsupported message fields can be rejected by WhatsApp or ignored by the recipient.
+Raw protocol fields are version-dependent. Unsupported fields may be ignored or rejected by WhatsApp.
 
 ## Error handling and reconnection
 
-Connections can close because of logout, network interruption, protocol updates, or server-side session invalidation. Applications should distinguish logout from recoverable failures and should avoid starting multiple concurrent connection loops.
+Connections may close because of logout, network interruption, protocol updates, or server-side session invalidation. Avoid starting multiple concurrent connection loops.
 
 ```js
-socket.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+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('Session logged out; remove the old session and pair again.')
+    console.error('Logged out; remove the old session and pair again.')
     return
   }
-  console.log('Connection interrupted; reconnect using a backoff strategy.')
+
+  console.log('Connection interrupted; reconnect with backoff.')
 })
 ```
 
@@ -201,12 +481,80 @@ npm install
 npm test
 ```
 
-Before opening a pull request, run the test suite, check the generated package contents, and confirm that no credentials or session files are included.
+Before publishing, verify generated protobuf files, package contents, version metadata, and that no authentication state or environment files are included.
 
 ## License
 
-Review the repository license before distributing applications built with this package. Keep required notices with redistributed source and binaries.
+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, package version, operating system, relevant error text, and a minimal reproducible example. Never include authentication state or private account data in an issue.
+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.
+
+
+## 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
+
+```js
+await sock.sendMessage(jid, {
+  sticker: { url: './sticker.webp' },
+  stickerAudio: { url: './sound.ogg' }
+})
+```
+
+### Newsletter follower invites
+
+```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' })
+```
+
+Rich HTML and bot-forwarded messages cannot be album children; send those separately. Album grouping is still dependent on WhatsApp server/client behavior.