plogme 2.0.2 → 2.0.4

package/README.md

@@ -291,29 +291,68 @@ await sock.sendMessage(jid, {
 
 ### Albums
 
-Use at least two image or video items. Albums are sent as a parent message followed by separately encrypted media children.
+Albums now use an AIRich vertical unified-response layout. Provide at least two image or video items; the client receives one forwarded rich message with one large media item per row, matching WhatsApp's full-width stacked album presentation. The old `albumMessage` parent/child collection and compact thumbnail grid are no longer generated by `sendAlbumMessage()`.
 
 ```js
 await sock.sendAlbumMessage(jid, [
-  { type: 'image', data: { url: './one.jpg' } },
-  { type: 'image', data: { url: './two.jpg' } }
-], {
-  caption: 'Trip photos'
-})
+  { type: 'image', data: { url: 'https://example.com/one.jpg', width: 1200, height: 800 } },
+  {
+    image: {
+      sourceUrl: 'https://example.com/two-preview.jpg',
+      imageHighResUrl: 'https://example.com/two.jpg',
+      darkModePreviewUrl: 'https://example.com/two-dark-preview.jpg',
+      darkModeHighResUrl: 'https://example.com/two-dark.jpg',
+      width: 1200,
+      height: 800
+    }
+  },
+  {
+    type: 'video',
+    data: {
+      url: 'https://example.com/three.mp4',
+      mimeType: 'video/mp4',
+      duration: 12,
+      thumbnailUrl: 'https://example.com/three.jpg'
+    }
+  }
+])
 ```
 
-The general `sendMessage` album form is also supported:
+The general `sendMessage` album form delegates to the same full-width vertical album implementation:
 
 ```js
 await sock.sendMessage(jid, {
   album: [
-    { image: { url: './one.jpg' }, caption: 'First' },
-    { video: { url: './clip.mp4' }, caption: 'Second' }
+    { image: { url: 'https://example.com/one.jpg' } },
+    { image: { url: 'https://example.com/two.jpg' } }
   ]
 })
 ```
 
-Rich-response and bot-forwarded messages cannot be nested as album children. Send them as separate messages.
+`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.
+
+### Video grids
+
+Video grids use the supported `GenAIVideoPrimitive` inside a unified-response `GenAIGridLayoutViewModel`. They are exposed separately from `sendAlbumMessage()` because WhatsApp's protobuf does not define a `GRID_VIDEO` submessage type. Provide at least two publicly fetchable video URLs:
+
+```js
+await sock.sendVideoGridMessage(jid, [
+  {
+    url: 'https://example.com/first.mp4',
+    title: 'First clip',
+    thumbnailUrl: 'https://example.com/first.jpg',
+    progressiveUrls: ['https://cdn.example.com/first-720p.mp4']
+  },
+  {
+    url: 'https://example.com/second.mp4',
+    title: 'Second clip',
+    thumbnailUrl: 'https://example.com/second.jpg',
+    progressiveUrls: ['https://cdn.example.com/second-720p.mp4']
+  }
+])
+```
+
+The video-grid API is intentionally URL-based; it does not upload local buffers or files. `sendVideoGridMessage()` also uses the rich-message edit relay, so supported clients receive the unified response without an initial Download-only placeholder.
 
 ## Interactive messages
 
@@ -475,6 +514,116 @@ await sock.sendRichAIResponse(jid, {
 
 `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.
 
+### One unified Plogme response
+
+Use `sendPlogmeMessage` when a response may contain several optional sections. It combines every section that is present into one AIRich `unifiedResponse`; omitted sections are ignored, so callers do not need to construct a different payload for every result shape.
+
+```js
+const result = await sock.sendPlogmeMessage(jid, {
+  headerText: 'CODY AI result',
+  contentText: 'The deployment completed successfully.',
+
+  // Optional highlighted code section.
+  code: 'const status = "online"',
+  language: 'javascript',
+
+  // Optional table section. The first row is treated as the heading by default.
+  title: 'Service status',
+  table: [
+    ['Service', 'State'],
+    ['API', 'Online'],
+    ['Worker', 'Online']
+  ],
+  noHeading: false,
+
+  // Optional carousel/content items or reels.
+  items: [
+    { title: 'API documentation', url: 'https://example.com/docs' }
+  ],
+  reels: [
+    {
+      title: 'Release notes',
+      url: 'https://example.com/release.mp4',
+      thumbnail_url: 'https://example.com/release.jpg'
+    }
+  ],
+
+  // Optional inline media and LaTeX sections.
+  inlineImage: 'https://example.com/status.jpg',
+  imageText: 'Deployment status',
+  alignment: 2,
+  latex: [
+    { latexExpression: 'E = mc^2', url: 'https://example.com/equation.png' }
+  ],
+
+  // Optional citation links.
+  links: [
+    {
+      text: 'Open the deployment logs',
+      url: 'https://example.com/logs',
+      title: 'Deployment logs',
+      displayName: 'Logs'
+    }
+  ],
+
+  // Optional AIRich product card (object = Single layout; array = HScroll).
+  products: {
+    title: 'CODY AI hosting',
+    brand: 'Plogme',
+    price: '$10',
+    sale_price: '$7',
+    url: 'https://example.com/product',
+    image: 'https://example.com/product.jpg'
+  },
+
+  // Optional social-post cards (always HScroll).
+  posts: [{
+    title: 'Release announcement',
+    username: 'codyai',
+    profile: 'https://example.com/profile.jpg',
+    thumbnail: 'https://example.com/post.jpg',
+    caption: 'Deployment completed.',
+    url: 'https://example.com/post',
+    source: 'INSTAGRAM',
+    verified: true
+  }],
+
+  // Optional source cards: [favicon URL, source URL, display text].
+  sources: [[
+    'https://example.com/favicon.jpg',
+    'https://example.com/docs',
+    'Documentation'
+  ]],
+
+  // Optional playable video card. Metadata may be supplied manually.
+  inlineVideo: {
+    url: 'https://example.com/clip.mp4',
+    mimeType: 'video/mp4',
+    duration: 12,
+    fileLength: 123456
+  },
+  suggested: true,
+  footerText: 'Generated by CODY AI'
+}, undefined, {
+  // The compatibility relay is enabled by default. It sends the rich
+  // envelope normally, then uses WhatsApp's type-14 edit protocol so
+  // compatible clients render it immediately instead of showing Download.
+  renderRichResponse: true
+})
+
+console.log('Sent message:', result.key.id)
+```
+
+Every field in the example is optional. A minimal response is valid as well:
+
+```js
+await sock.sendPlogmeMessage(jid, {
+  contentText: 'Only the text section is available right now.'
+})
+```
+
+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 menus, reels, and grids
 
 ### Original Gen4 rich menu
@@ -500,6 +649,53 @@ await sock.richMenu(jid, {
 })
 ```
 
+### 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`.
+
+```js
+await sock.sendA2UICommandMenu(jid, {
+  image: 'https://example.com/cover.jpg',
+  title: 'CODY AI',
+  rows: [
+    ['.meid', 'Check ID'],
+    ['.fromid', 'Check Source'],
+    ['.ping', 'Check Speed']
+  ],
+  buttons: [
+    { text: '1st-Channel', url: 'https://example.com/first' },
+    { text: '2nd-Channel', url: 'https://example.com/second' }
+  ]
+})
+```
+
+The image URL is uploaded as the interactive header media. Rows are also available through the native-flow `single_select` menu, and button URLs are represented as A2UI `openUrl` actions.
+
+### Screenshot-style raw AIRich command card
+
+Use `sendAIRichCommandMenu` when you want the manually serialized AIRich variant: an image primitive, widget CTAs, Markdown text with optional LaTeX inline metadata, a command table, and footer URL actions. Unlike A2UI, this path is an AIRich unified response and therefore uses the normal relay plus type-14 immediate-render edit.
+
+```js
+await sock.sendAIRichCommandMenu(jid, {
+  image: 'https://example.com/cover.jpg',
+  title: 'CODY AI',
+  subtitle: 'Command List',
+  code: 'CODY AI',
+  rows: [
+    ['.meid', 'Check ID'],
+    ['.fromid', 'Check Source'],
+    ['.ping', 'Check Speed']
+  ],
+  latexImage: 'https://example.com/logo.png',
+  latexExpression: 'CODY',
+  buttons: [
+    { text: '1st-Channel', url: 'https://example.com/first' },
+    { text: '2nd-Channel', url: 'https://example.com/second' }
+  ],
+  footer: 'Developed by - CODY AI'
+})
+```
+
 Cards and carousel layout are supported:
 
 ```js