plogme 1.0.4 → 1.0.6

package/README.md

@@ -10,7 +10,7 @@
 npm install plogme
 ```
 
-The current package version is **1.0.4**. Use Node.js 20 or newer.
+The current package version is **1.0.6**. Use Node.js 20 or newer.
 
 ## Quick start
 
@@ -474,6 +474,93 @@ sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
 })
 ```
 
+## 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.
+
+| 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. |
+
+```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'
+)
+
+// 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')
+```
+
+`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.
+
+### Group history sharing
+
+`toggleGroupHistory(jid, true)` selects `ALL_MEMBER_SHARE`; passing `false` selects `ADMIN_SHARE` through the WhatsApp MEX endpoint:
+
+```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.
+
+```js
+await sock.sendHtmlMessage(jid, {
+  html: '<h1>Simple screen</h1><p>One HTML payload.</p>',
+  trustedSources: []
+})
+
+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>' }
+  ]
+})
+```
+
+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.
+
 ## Development
 
 ```bash
@@ -490,3 +577,71 @@ Review the included license before distributing applications built with `plogme`
 ## 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.
+
+
+## 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.