plogme 2.0.4 → 2.0.5

package/README.md

@@ -1,4 +1,4 @@
-# Plogme
+# 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.
 
@@ -234,6 +234,44 @@ await sock.updateProfileName('Cody AI')
 await sock.updateProfileStatus('Building helpful WhatsApp tools')
 ```
 
+### Events and polls
+
+```js
+await sock.sendMessage(jid, {
+  event: {
+    name: 'Meet and Mingle',
+    description: 'A scheduled community event.',
+    call: 'audio',
+    startDate: new Date(Date.now() + 3600000),
+    endDate: new Date(Date.now() + 28800000),
+    isCancelled: false,
+    isScheduleCall: false,
+    extraGuestsAllowed: false,
+    location: { name: 'Lagos', degreesLatitude: 6.5244, degreesLongitude: 3.3792 }
+  }
+})
+
+await sock.sendMessage(jid, {
+  poll: {
+    name: 'Release preference',
+    values: ['Stable', 'Beta'],
+    selectableCount: 1,
+    endDate: new Date(Date.now() + 28800000),
+    hideVoter: false,
+    canAddOption: false
+  }
+})
+```
+
+### Forward and edit
+
+```js
+await sock.sendMessage(jid, { forward: message, force: true })
+await sock.sendMessage(jid, { delete: message.key })
+await sock.sendMessage(jid, { text: 'Updated text', edit: message.key })
+await sock.sendMessage(jid, { caption: 'Updated caption', edit: message.key })
+```
+
 ## Media and albums
 
 ### Images, video, audio, documents, and stickers
@@ -329,7 +367,7 @@ await sock.sendMessage(jid, {
 })
 ```
 
-`sendAlbumMessage()` accepts fetchable image and video URLs. Local `Buffer`/file inputs are not uploaded by this rich album API. The lower-level `prepareGridImageMessage()` helper remains available when a compact `GRID_IMAGE` layout is specifically required; `sendAlbumMessage()` itself uses the larger `GenAIVStackLayoutViewModel` presentation.
+`sendAlbumMessage()` accepts fetchable image and video URLs. Local `Buffer`/file inputs are not uploaded by this rich album API. The lower-level `prepareGridImageMessage()` helper remains available when a compact `GRID_IMAGE` layout is specifically required; `sendAlbumMessage()` itself uses a full-width `GenAIVStackLayoutViewModel` presentation for both images and videos. Image primitives explicitly request full-width presentation and carry preview/full URL fallbacks.
 
 ### Video grids
 
@@ -384,6 +422,29 @@ await sock.sendMessage(jid, {
 })
 ```
 
+Buttons can also carry media and a native-flow selector:
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: 'https://example.com/image.jpg' },
+  caption: 'Interactive buttons',
+  footer: 'CODY AI',
+  buttons: [
+    { text: 'Rating', id: '#Rating' },
+    {
+      text: 'Select',
+      sections: [{
+        title: 'Available options',
+        rows: [
+          { header: '', title: 'Secret Ingredient', description: '', id: '#SecretIngredient' },
+          { header: '', title: 'Coupon', description: '', id: '#CouponCode' }
+        ]
+      }]
+    }
+  ]
+})
+```
+
 ### Native flow
 
 ```js
@@ -406,6 +467,89 @@ await sock.sendRichWebview(jid, {
 })
 ```
 
+The lower-level `sendMessage` form also supports native-flow options, offer metadata, calls, copy actions, and webviews:
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: 'https://example.com/image.jpg' },
+  caption: 'Interactive options',
+  footer: 'CODY AI',
+  optionText: 'Select options',
+  optionTitle: 'Select options',
+  offerText: 'New coupon',
+  offerCode: 'SAVE20',
+  offerUrl: 'https://example.com/coupon',
+  offerExpiration: Date.now() + 3600000,
+  nativeFlow: [
+    { text: 'Greeting', id: '#Greeting', icon: 'review' },
+    { text: 'Call', call: '2348000000000' },
+    { text: 'Copy', copy: 'CODY AI' },
+    { text: 'Source', url: 'https://example.com', useWebview: true },
+    {
+      text: 'Select',
+      icon: 'default',
+      sections: [{
+        title: 'Available options',
+        rows: [{ header: '', title: 'Coupon', description: '', id: '#CouponCode' }]
+      }]
+    }
+  ],
+  interactiveAsTemplate: false
+})
+```
+
+Carousel cards and an audio footer are supported by the same `sendMessage` shape:
+
+```js
+await sock.sendMessage(jid, {
+  text: 'Choose a service',
+  footer: 'CODY AI',
+  cards: [
+    {
+      image: { url: 'https://example.com/service-a.jpg' },
+      caption: 'Service A',
+      footer: 'CODY AI',
+      nativeFlow: [{ text: 'Open source', url: 'https://example.com/a', useWebview: true }]
+    },
+    {
+      image: { url: 'https://example.com/service-b.jpg' },
+      caption: 'Service B',
+      footer: 'CODY AI',
+      offerText: 'New coupon',
+      offerCode: 'SAVE20',
+      offerUrl: 'https://example.com/coupon',
+      offerExpiration: Date.now() + 3600000,
+      nativeFlow: [{ text: 'Open source', url: 'https://example.com/b' }]
+    }
+  ]
+})
+
+await sock.sendMessage(jid, {
+  text: 'Music in footer',
+  audioFooter: { url: 'https://example.com/footer.mp3' },
+  nativeFlow: [
+    { text: 'Next', id: '#Next', icon: 'review' },
+    { text: 'Skip', id: '#Skip', icon: 'default' }
+  ]
+})
+```
+
+### Hydrated templates
+
+```js
+await sock.sendMessage(jid, {
+  title: 'CODY AI',
+  image: { url: 'https://example.com/image.jpg' },
+  caption: 'Choose an action',
+  footer: 'Plogme',
+  templateButtons: [
+    { text: 'Open menu', id: '#Menu' },
+    { text: 'Open source', url: 'https://example.com' },
+    { text: 'Call support', call: '2348000000000' }
+  ]
+})
+```
+
 ### Interactive table
 
 ```js
@@ -624,6 +768,63 @@ await sock.sendPlogmeMessage(jid, {
 
 The compatibility edit can be disabled for a specific send with `{ renderRichResponse: false }`. This sends the generated rich envelope once without the follow-up edit.
 
+### Rich response arrays
+
+For mixed rich content, `richResponse` accepts text, code, and table items in one generated response:
+
+```js
+await sock.sendMessage(jid, {
+  disclaimerText: 'CODY AI result',
+  richResponse: [
+    { text: 'Build result' },
+    { language: 'javascript', code: [{ highlightType: 0, codeContent: 'console.log("online")' }] },
+    { text: 'Runtime comparison:' },
+    {
+      title: 'Runtime',
+      table: [
+        { isHeading: true, items: ['', 'Node.js', 'Bun'] },
+        { isHeading: false, items: ['State', 'Online', 'Online'] }
+      ]
+    }
+  ]
+})
+```
+
+### Rich URL previews and verified media
+
+```js
+await sock.sendMessage(jid, {
+  text: 'https://example.com/docs',
+  richPreview: true
+})
+
+await sock.sendMessage(jid, {
+  text: 'https://example.com/docs',
+  richPreview: true,
+  previewTitle: 'CODY AI documentation',
+  previewDescription: 'Open the verified documentation'
+})
+
+await sock.sendMessage(jid, {
+  image: { url: 'https://example.com/verified-image.jpg' },
+  caption: 'Verified image',
+  verifiedMe: true
+})
+```
+
+`verifiedMe` applies to image and video messages. Rich previews require a `text` field containing the URL; preview rendering remains client-dependent.
+
+### Secured Meta service label
+
+To request the supported secured Meta service label on an outgoing message:
+
+```js
+await sock.sendMessage(jid, {
+  text: 'CODY AI secured response',
+  secureMetaServiceLabel: true
+})
+```
+
 ## Rich menus, reels, and grids
 
 ### Original Gen4 rich menu
@@ -633,13 +834,19 @@ Use `sock.richMenu` for the original Gen4-style menu. This is the primary rich-m
 ```js
 await sock.richMenu(jid, {
   header: {
-    title: 'Deployment tools'
+    title: 'Deployment tools',
+    image: {
+      url: 'https://example.com/cover.jpg',
+      mimeType: 'image/jpeg',
+      width: 1200,
+      height: 800
+    }
   },
   body: {
     title: 'Choose an action',
     buttons: [
-      { id: 'deploy', text: 'Deploy' },
-      { id: 'logs', text: 'View logs' }
+      { id: 'deploy', text: 'Deploy', toast: 'Deploy selected' },
+      { id: 'logs', text: 'View logs', toast: 'Logs selected' }
     ]
   },
   footer: {
@@ -649,6 +856,33 @@ await sock.richMenu(jid, {
 })
 ```
 
+### Universal A2UI message
+
+`sendA2UIMessage` is the generic sender. It accepts arbitrary A2UI components, Bloks widget data, native-flow buttons, and optional media; it is not restricted to the command-table template. It also uses the immediate relay/edit compatibility path.
+
+```js
+await sock.sendA2UIMessage(jid, {
+  bloksWidget: {
+    type: 'im_a2ui',
+    data: {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'custom-card',
+        catalogId: 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json',
+        components: [
+          { id: 'root', component: 'Column', children: ['title'] },
+          { id: 'title', component: 'Text', text: 'My custom A2UI card', variant: 'h2' }
+        ]
+      }
+    },
+    fallback: 'My custom A2UI card'
+  },
+  nativeFlowMessage: {
+    buttons: [{ name: 'quick_reply', buttonParamsJson: JSON.stringify({ id: 'open', display_text: 'Open' }) }]
+  }
+})
+```
+
 ### Large A2UI command card
 
 Use `sendA2UICommandMenu` for the full-size card layout with an uploaded image header, a command/function table, URL buttons, and a native-flow command selector. This is an `interactiveMessage`/A2UI payload, not an AIRich `unifiedResponse`, so it is intentionally separate from `sendPlogmeMessage` and `richMenu`.
@@ -720,6 +954,41 @@ await sock.richMenu(jid, {
 
 Validate button IDs on the server. A button ID is an event value, not an authorization grant.
 
+### Universal social/entity cards
+
+The leaked profile-result format is exposed through a provider-neutral API. It supports Instagram and other providers without hard-coding the Instagram wire format. Every send uses the same immediate AIRich relay/edit path as the other rich messages.
+
+```js
+await sock.sendSocialEntity(jid, {
+  platform: 'YOUTUBE',
+  username: 'crysnovax',
+  title: 'CODY AI',
+  imageUrl: 'https://example.com/avatar.png',
+  entityUrl: 'https://www.youtube.com/@crysnovax',
+  fullName: 'CRYSNOVAX',
+  isVerified: true,
+  resultText: 'See results'
+})
+```
+
+### Instagram profile card
+
+Instagram is the primary dedicated convenience API. It emits the `IG_PROFILE` social entity metadata while sharing the universal implementation.
+
+```js
+await sock.sendInstagramProfile(jid, {
+  username: 'crysnovax',
+  title: 'CODY AI',
+  subtitle: '⚉',
+  imageUrl: 'https://example.com/avatar.png',
+  entityId: '123456',
+  entityUrl: 'https://www.instagram.com/crysnovax',
+  fullName: 'CRYSNOVAX',
+  isVerified: true,
+  resultText: 'See results'
+})
+```
+
 ### 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.
@@ -948,6 +1217,25 @@ Flow identifiers and tokens must belong to a valid business configuration.
 
 ## View-once utilities
 
+Text view-once messages use the client-compatible inner `ExtendedTextMessage.viewOnce` flag:
+
+```js
+await sock.sendMessage(jid, {
+  text: 'viewOnceMessage',
+  viewOnce: true
+})
+```
+
+Media view-once messages continue to use WhatsApp's standard outer `viewOnceMessage` envelope:
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: 'https://example.com/secret.jpg' },
+  caption: 'Open once',
+  viewOnce: true
+})
+```
+
 ```js
 const info = sock.getViewOnceInfo(message)
 console.log(info)
@@ -1013,3 +1301,1121 @@ For implementation questions, include the Node.js version, Plogme version, opera
 [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"
+
+---
+
+# Additional APIs from the Bailey2 compatibility surface
+
+The following reference sections document supported APIs that are not repeated in the core CODY/Plogme guide above. They are retained from the `crysnovax/baileys2` compatibility documentation and exclude package-specific ban-checker functionality.
+
+## Welcome Flow
+
+Auto-greet new contacts with an interactive FAQ menu. Fires once per contact, never repeats.
+
+### Basic Setup
+
+```javascript
+import { createWelcomeFlow } from '@crysnovax/baileys'
+
+const welcome = createWelcomeFlow(sock, {
+  greeting: 'Welcome! How can I help you today?',
+  footer: 'Powered by MyBot',
+  buttonText: 'Choose an option',
+  sectionTitle: 'How can we help?',
+  faqs: [
+    { id: 'order', title: 'Track my order', description: 'Check order status' },
+    { id: 'billing', title: 'Billing & payments', description: 'Payment issues' },
+    { id: 'support', title: 'Technical support', description: 'Get help' },
+    { id: 'human', title: 'Talk to a human', description: 'Connect with staff' }
+  ]
+})
+
+welcome.listen() // start
+```
+
+### With Callbacks
+
+```javascript
+const welcome = createWelcomeFlow(sock, {
+  greeting: 'Hi there! What brings you here today?',
+  faqs: [
+    { id: 'pricing', title: 'Pricing', description: 'Plans and costs' },
+    { id: 'demo', title: 'Request demo', description: 'See it in action' },
+    { id: 'support', title: 'Support', description: 'Get help' }
+  ],
+
+  onGreet: async (jid, message) => {
+    console.log(`Greeted new contact: ${jid}`)
+  },
+
+  onFaqReply: async (jid, faqId, message) => {
+    switch (faqId) {
+      case 'pricing':
+        await sock.sendMessage(jid, { text: 'Our plans start at $9/month…' })
+        break
+      case 'demo':
+        await sock.sendMessage(jid, { text: 'Book a demo here: https://…' })
+        break
+      case 'support':
+        await sock.sendMessage(jid, { text: 'Describe your issue and we will help!' })
+        break
+    }
+  }
+})
+
+welcome.listen()
+```
+
+### Persist Across Restarts
+
+```javascript
+const welcome = createWelcomeFlow(sock, {
+  greeting: 'Welcome!',
+  faqs: [...],
+  persistPath: './data/greeted-contacts.json'
+})
+```
+
+### Control Methods
+
+```javascript
+welcome.listen()         // start listening
+welcome.stop()           // stop listening
+welcome.reset(jid)       // force re-greet one contact
+welcome.resetAll()       // clear all seen contacts
+welcome.hasGreeted(jid)  // check if greeted → boolean
+```
+
+### Config Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| greeting | string | 'Welcome!…' | Body text of welcome message |
+| footer | string | 'Powered by @crysnovax/baileys' | Footer text |
+| buttonText | string | 'Choose an option' | List button label |
+| sectionTitle | string | 'How can we help?' | Section header |
+| faqs | Array | 4 defaults | { id, title, description } |
+| typingDelayMs | number | 1200 | Typing indicator duration |
+| persistPath | string\|null | null | JSON file to persist JIDs |
+| ignoreGroups | boolean | true | Skip group chats |
+| ignoreNewsletter | boolean | true | Skip newsletters |
+| ignoreBroadcast | boolean | true | Skip broadcasts |
+| onGreet | async fn | null | Called after greeting sent |
+| onFaqReply | async fn | null | Called on FAQ selection |
+
+---
+
+## Payment Messages
+
+```javascript
+// Payment invite
+sock.sendMessage(jid, {
+  paymentInviteServiceType: 3 // 1, 2, or 3
+})
+
+// Invoice (not supported yet)
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  invoiceNote: 'Invoice'
+})
+
+// Order
+sock.sendMessage(jid, {
+  orderText: 'Order',
+  thumbnail: fs.readFileSync('./image.jpg')
+})
+
+// Request payment
+sock.sendMessage(jid, {
+  text: 'Request Payment',
+  requestPaymentFrom: '0@s.whatsapp.net'
+})
+```
+
+---
+
+## Message Options
+
+```javascript
+// AI icon (private chat only)
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'With AI icon!',
+  ai: true
+})
+
+// Ephemeral
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'Ephemeral',
+  ephemeral: true
+})
+
+// External ad reply
+sock.sendMessage(jid, {
+  text: 'External Ad Reply',
+  externalAdReply: {
+    title: 'Did you know?',
+    body: 'I dont know',
+    thumbnail: fs.readFileSync('./image.jpg'),
+    largeThumbnail: false,
+    url: 'https://example.com'
+  }
+})
+
+// Group status (a valid group JID is required)
+const groupStatus = await sock.sendMessage(groupJid, {
+  image: { url: './image.jpg' },
+  caption: 'Group Status!',
+  groupStatus: true
+})
+
+// Text, video, audio, stickers, mentions, and rich previews use the same flag.
+await sock.sendMessage(groupJid, {
+  text: 'Group update',
+  mentions: ['628123456789@s.whatsapp.net'],
+  groupStatus: true
+})
+
+// Delete using the key returned by the original group-status send.
+// The group JID must match key.remoteJid when that field is present.
+await sock.deleteGroupStatus(groupJid, groupStatus.key)
+
+// Report APIs submit the report first, then apply the requested safety action.
+// Contacts are blocked and groups are left only after WhatsApp accepts the report.
+await sock.reportContact('628123456789@s.whatsapp.net', [message.key])
+await sock.reportGroup(groupJid, [message.key])
+
+// Lottie sticker
+sock.sendMessage(jid, {
+  sticker: { url: './sticker.webp' },
+  isLottie: true
+})
+
+// likeThis — relay message exactly as-is, zero processing
+// Bypasses generateWAMessage entirely — no re-encoding, no normalization.
+// Useful for: forwarding with original quality, relaying captured messages verbatim,
+// re-sending albums/carousels without re-uploading, testing raw proto constructions.
+sock.sendMessage(jid, {
+  likeThis: true,
+  ...capturedMessage.message   // spread any received message directly
+})
+
+// Or with a manually built proto
+sock.sendMessage(jid, {
+  likeThis: true,
+  imageMessage: { ...rawProtoFields }
+})
+
+// Or forwarding with original quality intact
+sock.sendMessage(jid, {
+  likeThis: true,
+  extendedTextMessage: {
+    text: 'Built manually',
+    contextInfo: {
+      externalAdReply: {
+        title: '@crysnovax/baileys',
+        thumbnail: fs.readFileSync('./image.jpg'),
+        sourceApp: 'whatsapp',
+        showAdAttribution: true,
+        mediaType: 1
+      }
+    }
+  }
+})
+
+// Secure Meta service label: adds actual_actors, host_storage, and
+// privacy_mode_ts to the outbound business node. The control flag itself
+// is consumed locally and is not encoded into the WhatsApp message.
+sock.sendMessage(jid, {
+  text: 'Just a label!',
+  secureMetaServiceLabel: true
+})
+
+// Spoiler (compatible context flag; no unsupported future-proof wrapper)
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'Spoiler',
+  spoiler: true
+})
+
+// View once
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'View Once',
+  viewOnce: true
+})
+
+// View once v2
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'View Once V2',
+  viewOnceV2: true
+})
+
+// View once v2 extension
+sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'View Once V2 Extension',
+  viewOnceV2Extension: true
+})
+```
+
+---
+
+## Status & Stories
+
+Statuses are sent to `status@broadcast` and require at least one viewer JID. Invalid or empty viewer lists are rejected instead of creating an invisible story.
+
+```javascript
+const viewers = [
+  '628123456789@s.whatsapp.net',
+  '628987654321@s.whatsapp.net'
+]
+
+// Standard API: styled text status. Fonts 0-9 are supported.
+await sock.sendMessage('status@broadcast', {
+  text: 'Hello world!',
+  backgroundColor: '#FF1FA15A',
+  font: 0
+}, { statusJidList: viewers })
+
+// Convenience API (equivalent to the standard form)
+await sock.sendMessage('status@broadcast', {
+  status: true,
+  text: 'Exclusive status!',
+  statusJidList: viewers,
+  backgroundColor: 'teal',
+  font: 2
+})
+
+// Image and video statuses support captions
+await sock.sendMessage('status@broadcast', {
+  status: true,
+  image: { url: './image.jpg' },
+  caption: 'My status!',
+  statusJidList: viewers
+})
+await sock.sendMessage('status@broadcast', {
+  status: true,
+  video: { url: './video.mp4' },
+  caption: 'Watch this!',
+  statusJidList: viewers
+})
+
+// Audio or voice-note status, including waveform/background metadata
+await sock.sendMessage('status@broadcast', {
+  status: true,
+  audio: { url: './audio.ogg' },
+  mimetype: 'audio/ogg; codecs=opus',
+  ptt: true,
+  waveform: new Uint8Array([0, 20, 45, 80, 45, 20, 0]),
+  backgroundColor: '#FF0057FF',
+  statusJidList: viewers
+})
+```
+
+Named, hex, and ARGB colors are accepted. Viewer JIDs are normalized and deduplicated.
+
+### Status Mentions
+
+Passing an array as the destination posts a status and sends mention notifications to those contacts or groups. This is intentionally separate from `statusJidList`, which controls viewers without mentioning them.
+
+```javascript
+await sock.sendMessage([jidA, groupJid], { text: 'Hey, check my status!' })
+```
+
+---
+
+## Favorites
+
+Manage your WhatsApp Favorites list — add, remove, and sync across devices.
+
+### Add to Favorites
+
+```javascript
+// Add a single JID
+await sock.addToFavorites(['628123456789@s.whatsapp.net'])
+
+// Add multiple JIDs (replaces entire list — merge handled by caller)
+await sock.addToFavorites([
+  '628123456789@s.whatsapp.net',
+  '628987654321@s.whatsapp.net',
+  '1234@g.us'
+])
+```
+
+### Remove from Favorites
+
+```javascript
+// Remove specific JIDs (pass remaining list after filter)
+await sock.removeFromFavorites([
+  '628123456789@s.whatsapp.net'  // only this one remains
+])
+```
+
+### Full Example with Local Persistence
+
+```javascript
+import fs from 'fs'
+import path from 'path'
+
+const FAV_FILE = path.join(process.cwd(), 'database', 'favorites.json')
+
+const loadFavs = () => {
+  try { return JSON.parse(fs.readFileSync(FAV_FILE, 'utf8')) }
+  catch { return [] }
+}
+
+const saveFavs = (favs) => {
+  fs.mkdirSync(path.dirname(FAV_FILE), { recursive: true })
+  fs.writeFileSync(FAV_FILE, JSON.stringify(favs, null, 2))
+}
+
+// Add
+const existing = loadFavs()
+const target = '628123456789@s.whatsapp.net'
+if (!existing.includes(target)) {
+  const merged = [...existing, target]
+  await sock.addToFavorites(merged)
+  saveFavs(merged)
+}
+
+// Remove
+const toRemove = '628123456789@s.whatsapp.net'
+const remaining = existing.filter(jid => jid !== toRemove)
+await sock.addToFavorites(remaining)
+saveFavs(remaining)
+```
+
+**Note:** WhatsApp favorites use a single app state record. Each SET replaces the entire list. Always pass the complete desired array.
+
+---
+
+## Newsletter Management
+
+```javascript
+// Create
+sock.newsletterCreate('@crysnovax/baileys', 'Fresh updates weekly')
+
+// Metadata
+const metadata = await sock.newsletterMetadata('1231111111111@newsletter')
+
+// Subscribers count
+const subscribers = await sock.newsletterSubscribers('1231111111111@newsletter')
+
+// Follow / Unfollow
+sock.newsletterFollow('1231111111111@newsletter')
+sock.newsletterUnfollow('1231111111111@newsletter')
+
+// Mute / Unmute
+sock.newsletterMute('1231111111111@newsletter')
+sock.newsletterUnmute('1231111111111@newsletter')
+
+// Admin management
+sock.newsletterDemote('1231111111111@newsletter', '6281111111111@s.whatsapp.net')
+sock.newsletterChangeOwner('1231111111111@newsletter', '6281111111111@s.whatsapp.net')
+
+// Update
+sock.newsletterUpdate('1231111111111@newsletter', { name: '@crysnovax/baileys' })
+sock.newsletterUpdateName('1231111111111@newsletter', '@crysnovax/baileys')
+sock.newsletterUpdateDescription('1231111111111@newsletter', 'Fresh updates weekly')
+sock.newsletterUpdatePicture('1231111111111@newsletter', { url: 'path/to/image.jpg' })
+sock.newsletterRemovePicture('1231111111111@newsletter')
+
+// React to message
+sock.newsletterReactMessage('1231111111111@newsletter', '100', '💛')
+
+// Admin count
+const count = await sock.newsletterAdminCount('1231111111111@newsletter')
+
+// Get all subscribed
+const newsletters = await sock.newsletterSubscribed()
+
+// Fetch messages
+const messages = sock.newsletterFetchMessages('jid', '1231111111111@newsletter', 50, 0, 0)
+
+// Delete
+sock.newsletterDelete('1231111111111@newsletter')
+```
+
+---
+
+## Group Management
+
+```javascript
+// Create
+const group = await sock.groupCreate('@crysnovax/baileys', ['628123456789@s.whatsapp.net'])
+
+// Metadata
+const metadata = await sock.groupMetadata(jid)
+
+// Invite
+const inviteCode = await sock.groupInviteCode(jid)
+sock.groupRevokeInvite(jid)
+sock.groupAcceptInvite(inviteCode)
+
+// Leave
+sock.groupLeave(jid)
+
+// Participants
+sock.groupParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'add')
+sock.groupParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'remove')
+sock.groupParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'promote')
+sock.groupParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'demote')
+
+// Join requests
+sock.groupRequestParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'approve')
+
+// Info updates
+sock.groupUpdateSubject(jid, '@crysnovax/baileys')
+sock.groupUpdateDescription(jid, 'Updated description')
+sock.updateProfilePicture(jid, { url: 'path/to/image.jpg' })
+sock.removeProfilePicture(jid)
+
+// Settings
+sock.groupSettingUpdate(jid, 'announcement')      // admin only chat
+sock.groupSettingUpdate(jid, 'not_announcement')  // open chat
+sock.groupSettingUpdate(jid, 'locked')              // admin only edit info
+sock.groupSettingUpdate(jid, 'unlocked')            // all edit info
+
+// Add mode
+sock.groupMemberAddMode(jid, 'admin_add')
+sock.groupMemberAddMode(jid, 'all_member_add')
+
+// Ephemeral
+sock.groupToggleEphemeral(jid, 86400)  // enable
+sock.groupToggleEphemeral(jid, 0)        // disable
+
+// Approval mode
+sock.groupJoinApprovalMode(jid, 'on')
+sock.groupJoinApprovalMode(jid, 'off')
+
+// Fetch all
+const groups = await sock.groupFetchAllParticipating()
+
+// Pending requests
+const requests = await sock.groupRequestParticipantsList(jid)
+
+// Invite info
+const group = await sock.groupGetInviteInfo('ABC123456789')
+
+// Member label
+sock.updateMemberLabel(jid, '@crysnovax/baileys')
+```
+
+---
+
+## Community Management
+
+```javascript
+// Create
+const community = await sock.communityCreate('@crysnovax/baileys', 'Fresh updates weekly')
+
+// Create subgroup
+const group = await sock.communityCreateGroup(
+  'Announcements',
+  ['628123456789@s.whatsapp.net'],
+  communityJid
+)
+
+// Link / Unlink
+sock.communityLinkGroup(groupJid, communityJid)
+sock.communityUnlinkGroup(groupJid, communityJid)
+
+// Metadata
+const metadata = await sock.communityMetadata(jid)
+
+// Invite
+const inviteCode = await sock.communityInviteCode(jid)
+sock.communityRevokeInvite(jid)
+sock.communityAcceptInvite(inviteCode)
+
+// Leave
+sock.communityLeave(jid)
+
+// Join requests
+sock.communityRequestParticipantsUpdate(jid, ['628123456789@s.whatsapp.net'], 'approve')
+
+// Updates
+sock.communityUpdateSubject(jid, '@crysnovax/baileys')
+sock.communityUpdateDescription(jid, 'Updated description')
+
+// Settings
+sock.communitySettingUpdate(jid, 'announcement')
+sock.communitySettingUpdate(jid, 'not_announcement')
+sock.communitySettingUpdate(jid, 'locked')
+sock.communitySettingUpdate(jid, 'unlocked')
+
+// Add mode
+sock.communityMemberAddMode(jid, 'admin_add')
+sock.communityMemberAddMode(jid, 'all_member_add')
+
+// Ephemeral
+sock.communityToggleEphemeral(jid, 86400)
+sock.communityToggleEphemeral(jid, 0)
+
+// Approval mode
+sock.communityJoinApprovalMode(jid, 'on')
+sock.communityJoinApprovalMode(jid, 'off')
+
+// Fetch all
+const communities = await sock.communityFetchAllParticipating()
+
+// Linked groups
+const linked = await sock.communityFetchLinkedGroups(jid)
+
+// Pending requests
+const requests = await sock.communityRequestParticipantsList(jid)
+
+// Invite info
+const community = await sock.communityGetInviteInfo('ABC123456789')
+```
+
+---
+
+## Profile & Business
+
+```javascript
+// Profile picture
+const url = await sock.profilePictureUrl(jid, 'image')
+
+// Standard — auto crop + resize to 720×720
+sock.updateProfilePicture(jid, buffer)
+sock.updateProfilePicture(jid, { url })
+
+// Standard with custom dimensions
+sock.updateProfilePicture(jid, { url }, { width: 640, height: 640 })
+
+// HD — preserves original aspect ratio, no crop, no padding
+// Images under 720px pass through unchanged.
+// Larger images are scaled down proportionally to fit within 720px.
+sock.updateProfilePicture(jid, buffer, { hd: true })
+sock.updateProfilePicture(jid, { url }, { hd: true })
+
+sock.removeProfilePicture(jid)
+
+// Profile info (name and personal About/bio)
+await sock.updateProfileName('My Name')
+await sock.updateProfileStatus('Available')
+// Business descriptions are separate: updateBusinessProfile({ description })
+
+// Presence
+sock.sendPresenceUpdate('available', jid)
+sock.presenceSubscribe(jid)
+
+// Read receipts
+sock.readMessages([message.key])
+sock.sendReceipt(jid, participant, [messageId], 'read')
+
+// Block / Unblock
+sock.updateBlockStatus(jid, 'block')
+sock.updateBlockStatus(jid, 'unblock')
+
+// Blocklist
+const blocked = await sock.fetchBlocklist()
+
+// Chat modify
+sock.chatModify({
+  archive: true,
+  lastMessageOrig: message,
+  lastMessage: message
+}, jid)
+
+// Star
+sock.star(jid, [{ id: messageId, fromMe: true }], true)
+
+// Contact
+sock.addOrEditContact(jid, { displayName: 'Name' })
+sock.removeContact(jid)
+
+// Labels
+sock.addChatLabel(jid, labelId)
+sock.removeChatLabel(jid, labelId)
+sock.addMessageLabel(jid, messageId, labelId)
+
+// App state sync
+sock.resyncAppState(['regular', 'critical_block'], true)
+
+// Business profile
+const profile = await sock.getBusinessProfile(jid)
+
+// Product create
+const product = await sock.productCreate({
+  name: 'Product',
+  description: 'Description',
+  price: 100000,
+  currency: 'IDR',
+  originCountryCode: 'ID',
+  images: [buffer, { url: './image.jpg' }]
+})
+
+// Product update
+await sock.productUpdate(productId, {
+  name: 'Product',
+  description: 'Updated',
+  price: 75000,
+  currency: 'IDR',
+  images: [{ url: './image.jpg' }]
+})
+
+// Product delete
+sock.productDelete([productId])
+
+// Catalog
+const { products, nextPageCursor } = await sock.getCatalog({
+  jid: '628123456789@s.whatsapp.net',
+  limit: 10
+})
+
+// Collections
+const collections = await sock.getCollections('628123456789@s.whatsapp.net', 10)
+
+// Order details
+const order = await sock.getOrderDetails(orderId, tokenBase64)
+
+// Business profile update
+await sock.updateBusinessProfile({
+  address: 'Jakarta, Indonesia',
+  description: 'Official Store',
+  websites: ['https://example.com'],
+  email: 'email@example.com',
+  hours: {
+    timezone: 'Asia/Jakarta',
+    days: [{ day: 'mon', mode: 'open_24h' }]
+  }
+})
+
+// Use empty strings or an empty websites array to clear profile fields.
+await sock.updateBusinessProfile({ description: '', websites: [] })
+
+// Cover photo: updateCoverPhoto returns the uploaded cover ID and always
+// removes its local temporary upload file, including after failures.
+const coverId = await sock.updateCoverPhoto({ url: './image.jpg' })
+await sock.removeCoverPhoto(coverId)
+
+// Quick replies
+sock.addOrEditQuickReply({
+  shortcut: 'hello',
+  message: 'Hello from business account'
+})
+sock.removeQuickReply(timestamp)
+```
+
+---
+
+## Privacy & Security
+
+```javascript
+// Last seen
+sock.updateLastSeenPrivacy('all')
+sock.updateLastSeenPrivacy('contacts')
+sock.updateLastSeenPrivacy('contact_blacklist')
+sock.updateLastSeenPrivacy('nobody')
+
+// Online
+sock.updateOnlinePrivacy('all')
+sock.updateOnlinePrivacy('match_last_seen')
+
+// Profile picture
+sock.updateProfilePicturePrivacy('contacts')
+
+// Status
+sock.updateStatusPrivacy('contacts')
+
+// Read receipts
+sock.updateReadReceiptsPrivacy('all')
+sock.updateReadReceiptsPrivacy('none')
+
+// Groups add
+sock.updateGroupsAddPrivacy('all')
+sock.updateGroupsAddPrivacy('contacts')
+
+// Messages
+sock.updateMessagesPrivacy('all')
+sock.updateMessagesPrivacy('contacts')
+sock.updateMessagesPrivacy('nobody')
+
+// Call
+sock.updateCallPrivacy('everyone')
+
+// Default disappearing mode
+sock.updateDefaultDisappearingMode(86400)
+
+// Link previews
+sock.updateDisableLinkPreviewsPrivacy(true)
+```
+
+---
+
+## Utility Methods
+
+### LID / Phone Number Resolution
+
+```javascript
+// Resolve LID ↔ PN cross-mappings
+const userId = await sock.findUserId('628123456789@s.whatsapp.net')
+console.log(userId)
+// { lid: '1234567890@lid', phoneNumber: '628123456789@s.whatsapp.net' }
+
+const userId2 = await sock.findUserId('1234567890@lid')
+console.log(userId2)
+// { lid: '1234567890@lid', phoneNumber: '628123456789@s.whatsapp.net' }
+```
+
+LID-to-phone resolution uses mappings learned from trusted WhatsApp envelopes, history, or PN-to-LID USync. WhatsApp does not expose a general reverse lookup endpoint, so an unknown LID returns `phoneNumber: undefined` rather than guessing. Primary devices resolve to canonical `number@s.whatsapp.net` JIDs; linked-device suffixes and hosted domains are preserved.
+
+### Fetch User Status
+
+```javascript
+// Fetch status metadata for one or more users
+const statusList = await sock.fetchStatus('628123456789@s.whatsapp.net', '628987654321@s.whatsapp.net')
+```
+
+### Fetch Disappearing Duration
+
+```javascript
+// Get disappearing message duration for contacts
+const durations = await sock.fetchDisappearingDuration('628123456789@s.whatsapp.net')
+```
+
+### Bot List
+
+```javascript
+// Fetch official bot list (v2)
+const bots = await sock.getBotListV2()
+// [{ jid: '...', personaId: '...' }]
+```
+
+### Call Links
+
+```javascript
+// Create voice/video call link
+const token = await sock.createCallLink('audio')        // voice call
+const token2 = await sock.createCallLink('video')        // video call
+const token3 = await sock.createCallLink('video', {       // with scheduled event
+  startTime: Date.now() + 3600000
+})
+```
+
+### Server Properties
+
+```javascript
+// Access server-assigned AB props
+console.log(sock.serverProps)
+// {
+//   privacyTokenOn1to1: true,      // tctoken on 1:1 messages
+//   profilePicPrivacyToken: true,  // tctoken on profile pic IQs
+//   lidTrustedTokenIssueToLid: false  // issue tctokens to LID
+// }
+```
+
+### App State Sync
+
+```javascript
+// Force resync specific collections
+await sock.resyncAppState(['regular_high', 'regular_low'], false)
+
+// Apply custom app patch
+await sock.appPatch({
+  syncAction: { ... },
+  index: ['...'],
+  type: 'regular_low',
+  apiVersion: 5,
+  operation: proto.SyncdMutation.SyncdOperation.SET
+})
+```
+
+### Clean Dirty Bits
+
+```javascript
+// Clear dirty bits for specific sync types
+await sock.cleanDirtyBits('account_sync', timestamp)
+```
+
+---
+
+## Meta AI Features
+
+Meta AI-style thinking indicators and live reasoning feeds. Works on all WhatsApp clients — no "Update WhatsApp" messages.
+
+**Note:** These use plain text placeholders with typing indicators by default, avoiding unsupported-message bubbles. Final code blocks, tables, links, and rich responses are unchanged. Native Meta typing/thinking is force-only: set both `forceMetaRendering: true` in the socket config and `useNativeMeta: true` in the `metaTyping` or `sendMetaComposited` options.
+
+### Meta Typing Indicator
+
+Show a live thinking indicator that you control. Delete it manually when ready — no "edited" badge ever appears.
+
+```javascript
+import { metaTyping, buildSteps } from '@crysnovax/baileys'
+
+const placeholder = await metaTyping(sock, jid, {
+  description: 'Thinking…',
+  steps: buildSteps(['Reading your message…', 'Writing response…'])
+})
+
+// Do your work here…
+
+// Delete the indicator cleanly
+await sock.sendMessage(jid, { delete: placeholder.key })
+
+// Send the real message
+await sock.sendMessage(jid, { text: 'Here is your answer!' })
+```
+
+What users see:
+
+```
+[typing… indicator]
+
+_Thinking…_
+○ Reading your message…
+○ Writing response…
+
+[auto-deletes]
+
+Here is your answer!
+```
+
+### Meta Compositing
+
+Full flow: indicator shows → auto-deletes → clean final message lands. Works with every rich content type.
+
+```javascript
+import { sendMetaComposited, PlanningStepStatus } from '@crysnovax/baileys'
+
+// With code block
+await sendMetaComposited(
+  sock, jid,
+  { code: 'const x = 1 + 1', language: 'javascript' },
+  {
+    thinkingMs: 3000,
+    description: 'Analyzing…',
+    steps: [
+      { title: 'Reading context…', status: PlanningStepStatus.DONE },
+      { title: 'Writing code…', status: PlanningStepStatus.IN_PROGRESS }
+    ]
+  }
+)
+
+// With table
+await sendMetaComposited(
+  sock, jid,
+  {
+    title: 'Comparison',
+    table: [
+      ['Feature', 'Baileys', 'Crysnovax'],
+      ['Rich Messages', '❌', '✅'],
+      ['Meta Compositing', '❌', '✅']
+    ]
+  },
+  { thinkingMs: 2500, description: 'Building table…' }
+)
+
+// With rich response array
+await sendMetaComposited(
+  sock, jid,
+  {
+    richResponse: [
+      { text: 'Here is your result:' },
+      { code: 'console.log("hello")', language: 'javascript' },
+      { text: 'Run it with `node index.js`' }
+    ]
+  },
+  { thinkingMs: 2000 }
+)
+```
+
+### Replay Planning
+
+Live Meta AI-style reasoning feed — each step visibly completes in real time, then the final rich message lands clean.
+
+```javascript
+import { replayPlanning, mixedSteps } from '@crysnovax/baileys'
+
+await replayPlanning(
+  sock, jid,
+
+  // Steps — status managed automatically
+  mixedSteps([
+    { title: 'Understanding your question…', type: 'reasoning' },
+    { title: 'Searching for data…', type: 'search' },
+    { title: 'Writing the answer…' }
+  ]),
+
+  // Final rich message
+  { code: 'const answer = 42', language: 'javascript' },
+
+  // Options
+  {
+    description: 'Thinking…',
+    stepDelayMs: 900,
+    finalPauseMs: 600
+  }
+)
+```
+
+What users see:
+
+```
+_Thinking…_
+○ Understanding your question…
+○ Searching for data…
+○ Writing the answer…
+
+[step 1 completes]
+_Thinking…_
+✓ Understanding your question…
+○ Searching for data…
+○ Writing the answer…
+
+[step 2 completes]
+_Thinking…_
+✓ Understanding your question…
+✓ Searching for data…
+○ Writing the answer…
+
+[all done, deletes, then:]
+
+const answer = 42
+```
+
+Step type helpers:
+
+```javascript
+import {
+  buildReasoningSteps,  // isReasoning: true
+  buildSearchSteps,     // isEnhancedSearch: true
+  mixedSteps,           // mix any combination
+  buildSteps            // plain steps
+} from '@crysnovax/baileys'
+
+// All reasoning
+buildReasoningSteps(['Analyzing the problem…', 'Checking edge cases…'])
+
+// All search
+buildSearchSteps(['Searching the web…', 'Reading top results…'])
+
+// Mixed — most realistic Meta AI look
+mixedSteps([
+  { title: 'Reading your message…', type: 'reasoning' },
+  { title: 'Searching sources…', type: 'search' },
+  { title: 'Composing response…' }
+])
+```
+
+Replay planning only (no final message):
+
+```javascript
+import { replayPlanningOnly, buildSearchSteps } from '@crysnovax/baileys'
+
+await replayPlanningOnly(
+  sock, jid,
+  buildSearchSteps(['Looking up prices…', 'Comparing results…']),
+  { stepDelayMs: 1200 }
+)
+
+// Send whatever you want after — no badge, no trace
+await sock.sendMessage(jid, { text: 'Here are the results!' })
+```
+
+Options reference:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| description | string | 'Thinking…' | Top label on the indicator bubble |
+| placeholderText | string | '' | Body text while steps run |
+| stepDelayMs | number | 900 | Ms between each step completing |
+| finalPauseMs | number | 600 | Ms to hold after all steps done |
+| abortOnDisconnect | boolean | true | Stops cleanly if socket closes |
+| sendOptions | object | {} | Extra options for final sendMessage |
+
+---
+
+## Events Reference
+
+```javascript
+sock.ev.on('connection.update', (update) => {})
+sock.ev.on('creds.update', (update) => {})
+sock.ev.on('messaging-history.set', (update) => {})
+sock.ev.on('messaging-history.status', (update) => {})
+sock.ev.on('chats.upsert', (update) => {})
+sock.ev.on('chats.update', (update) => {})
+sock.ev.on('chats.delete', (update) => {})
+sock.ev.on('chats.lock', (update) => {})
+sock.ev.on('lid-mapping.update', (update) => {})
+sock.ev.on('presence.update', (update) => {})
+sock.ev.on('contacts.upsert', (update) => {})
+sock.ev.on('contacts.update', (update) => {})
+sock.ev.on('messages.delete', (update) => {})
+sock.ev.on('messages.update', (update) => {})
+sock.ev.on('messages.media-update', (update) => {})
+sock.ev.on('messages.upsert', (update) => {})
+sock.ev.on('messages.reaction', (update) => {})
+sock.ev.on('message-receipt.update', (update) => {})
+sock.ev.on('groups.upsert', (update) => {})
+sock.ev.on('groups.update', (update) => {})
+sock.ev.on('group-participants.update', (update) => {})
+sock.ev.on('group.join-request', (update) => {})
+sock.ev.on('group.member-tag.update', (update) => {})
+sock.ev.on('blocklist.set', (update) => {})
+sock.ev.on('blocklist.update', (update) => {})
+sock.ev.on('call', (update) => {})
+sock.ev.on('labels.edit', (update) => {})
+sock.ev.on('labels.association', (update) => {})
+sock.ev.on('newsletter.reaction', (update) => {})
+sock.ev.on('newsletter.view', (update) => {})
+sock.ev.on('newsletter-participants.update', (update) => {})
+sock.ev.on('newsletter-settings.update', (update) => {})
+sock.ev.on('settings.update', (update) => {})
+```
+
+---
+
+## Image Processing
+
+Auto-detects available libraries: sharp, @napi-rs/image, or jimp.
+
+```javascript
+import { getImageProcessingLibrary } from '@crysnovax/baileys'
+import { readFile } from 'fs/promises'
+
+const lib = await getImageProcessingLibrary()
+const bufferOrFilePath = './image.jpg'
+const width = 512
+let output
+
+// Sharp
+if (lib.sharp?.default) {
+  const img = lib.sharp.default(bufferOrFilePath)
+  output = await img.resize(width).jpeg({ quality: 80 }).toBuffer()
+}
+
+// NAPI-RS Image
+else if (lib.image?.Transformer) {
+  const inputBuffer = Buffer.isBuffer(bufferOrFilePath)
+    ? bufferOrFilePath
+    : await readFile(bufferOrFilePath)
+  const img = new lib.image.Transformer(inputBuffer)
+  output = await img.resize(width, undefined, 0).jpeg(50)
+}
+
+// Jimp
+else if (lib.jimp?.Jimp) {
+  const img = await lib.jimp.Jimp.read(bufferOrFilePath)
+  output = await img
+    .resize({ w: width, mode: lib.jimp.ResizeStrategy.BILINEAR })
+    .getBuffer('image/jpeg', { quality: 50 })
+}
+
+else {
+  throw new Error('No image processing library available')
+}
+```
+
+---
+
+## Credits and attribution
+
+Plogme/CODY is a downstream fork and enhancement of the Baileys protocol implementation by [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys). The underlying WhatsApp Web protocol work, structure, and many foundational APIs come from WhiskeySockets. Additional changes in this fork include CODY/Plogme rich-message composition, immediate AIRich rendering relay, A2UI and Gen4 menu helpers, albums, video grids, and related documentation.
+
+This README also incorporates compatible API examples from [crysnovax/baileys2](https://github.com/crysnovax/baileys2). Custom package-specific ban-checker APIs are intentionally not documented here.