feat(builder): reminder/location/address buttons, nativeFlow list upgrade, AIRich LaTeX, bottomSheet/limitedTimeOffer

Mined from FgsiDev/baileys-messagebuilder (same author as the AIRich gist):
- New nativeFlow buttons: reminder (cta_reminder), cancel-reminder
  (cta_cancel_reminder), location (send_location), address (address_message).
  location needs no text; others map display_text+id.
- list() upgraded from legacy listMessage to nativeFlow single_select relayed
  through the biz/interactive node, so lists now render on personal accounts.
  Round-trips row id via the existing list-select decoder.
- AIRich text now supports [expr]<imageUrl> LaTeX -> GenAILatexItem, alongside
  the existing hyperlink/citation extraction.
- buttons() gains bottomSheet + limitedTimeOffer options serialized into
  nativeFlow messageParamsJson.
Examples updated; +9 builder tests.

Author: zeative

examples/airich-bot.ts

@@ -37,6 +37,8 @@ const showcase = async (target: string): Promise<void> => {
     'Rangkuman harian dari [zaileys](https://github.com/zeative/zaileys).',
     'Sumber data dipantau otomatis. [](https://github.com/zeative/zaileys)',
     '',
+    'Rumus hari ini: [E = mc^2|160|44]<https://latex.codecogs.com/png.image?E%20%3D%20mc%5E2>',
+    '',
     'Tiga sorotan utama hari ini, plus cuplikan kode untuk bikin bot interaktif.',
   ].join('\n')
 

examples/buttons-bot.ts

@@ -93,6 +93,59 @@ client.on('connect', async ({ me }) => {
     ),
   )
 
+  await send('reminder + cancel-reminder', () =>
+    client.send(TO).buttons(
+      [
+        { type: 'reminder', text: 'Ingatkan saya', id: 'remind_1' },
+        { type: 'cancel-reminder', text: 'Batalkan' },
+      ],
+      { title: '⏰ Reminder', text: 'Set / batalkan pengingat WhatsApp' },
+    ),
+  )
+  await send('location + address request', () =>
+    client.send(TO).buttons(
+      [
+        { type: 'location', text: 'Kirim lokasi' },
+        { type: 'address', text: 'Isi alamat', id: 'addr_1' },
+      ],
+      { title: '📍 Checkout', text: 'Bagikan lokasi atau alamat pengiriman' },
+    ),
+  )
+  await send('bottomSheet (overflow → sheet)', () =>
+    client.send(TO).buttons(
+      [
+        { id: 's1', text: 'Opsi 1' },
+        { id: 's2', text: 'Opsi 2' },
+        { id: 's3', text: 'Opsi 3' },
+        { id: 's4', text: 'Opsi 4' },
+        { id: 's5', text: 'Opsi 5' },
+      ],
+      { text: 'Banyak opsi — dikelompokkan jadi bottom sheet', bottomSheet: { listTitle: 'Semua opsi', buttonTitle: 'Lihat 5 opsi', buttonsLimit: 2 } },
+    ),
+  )
+  await send('limitedTimeOffer (countdown CTA)', () =>
+    client.send(TO).buttons(
+      [{ type: 'url', text: 'Ambil promo', url: 'https://github.com/zeative/zaileys' }, { type: 'copy', text: 'Salin kode', code: 'FLASH50' }],
+      {
+        title: '⚡ Flash Sale',
+        text: 'Diskon 50% — berakhir sebentar lagi!',
+        limitedTimeOffer: { text: 'Promo berakhir dalam', copyCode: 'FLASH50', expiresAt: Math.floor(Date.now() / 1000) + 3600 },
+      },
+    ),
+  )
+  await send('list (single_select)', () =>
+    client.send(TO).list({
+      title: '🍔 Menu',
+      description: 'Pilih pesananmu',
+      buttonText: 'Lihat menu',
+      footerText: 'zaileys',
+      sections: [
+        { title: 'Makanan', rows: [{ id: 'pizza', title: 'Pizza', description: '$6' }, { id: 'ramen', title: 'Ramen', description: '$5' }] },
+        { title: 'Minuman', rows: [{ id: 'coffee', title: 'Kopi', description: '$2' }, { id: 'tea', title: 'Teh', description: '$1' }] },
+      ],
+    }),
+  )
+
   if (headerImage) {
     await send('IMAGE header + reply buttons', () =>
       client.send(TO).buttons([{ id: 'ok', text: 'OK' }, { id: 'no', text: 'No' }], {
@@ -131,3 +184,7 @@ client.on('connect', async ({ me }) => {
 client.on('button-click', (ctx) => {
   console.log('>>> button-click FIRED | id:', ctx.buttonId, '| text:', ctx.buttonText, '| from:', ctx.sender.jid)
 })
+
+client.on('list-select', (ctx) => {
+  console.log('>>> list-select FIRED | rowId:', ctx.rowId, '| title:', ctx.title, '| from:', ctx.sender.jid)
+})

src/builder/builder.ts

@@ -9,7 +9,7 @@ import {
 } from 'baileys'
 import { sendAlbum } from './album.js'
 import { buildAudioContent } from './content/audio.js'
-import { buildButtonsContent, RELAY_CONTENT_KEY, RELAY_MEDIA_KEY, type HeaderMedia } from './content/buttons.js'
+import { buildButtonsContent, RELAY_CONTENT_KEY, RELAY_MEDIA_KEY, type ButtonsContentOptions, type HeaderMedia } from './content/buttons.js'
 import { buildCarouselContent, RELAY_CARDS_MEDIA_KEY, type CardMedia, type CarouselCard } from './content/carousel.js'
 import { buildAIRichContent, type AIRichOptions, type AIRichPart } from './content/airich.js'
 import { loadMedia } from './media-loader.js'
@@ -156,7 +156,7 @@ export class MessageBuilder<State extends BuilderState> {
   buttons(
     this: MessageBuilder<'init'>,
     buttons: Array<ButtonDef | InteractiveButton>,
-    opts?: { text?: string; footer?: string; title?: string; subtitle?: string; image?: MediaSource; video?: MediaSource },
+    opts?: ButtonsContentOptions,
   ): MessageBuilder<'content-set'> {
     this.internal.content = buildButtonsContent(buttons, opts)
     return this as unknown as MessageBuilder<'content-set'>

src/builder/content/airich.ts

@@ -87,26 +87,35 @@ const extractIE = (input: string): ExtractedIE => {
   let last = 0
   let citationIndex = 1
   let hyperlinkIndex = 0
+  let latexIndex = 0
   const stack: number[] = []
   for (let i = 0; i < input.length; i++) {
     if (input[i] === '[' && input[i - 1] !== '\\') {
       stack.push(i)
-    } else if (input[i] === ']' && input[i + 1] === '(') {
+    } else if (input[i] === ']' && (input[i + 1] === '(' || input[i + 1] === '<')) {
       const start = stack.pop()
       if (start == null) continue
+      const open = input[i + 1]
+      const close = open === '(' ? ')' : '>'
+      const isLatex = open === '<'
       let end = i + 2
       let depth = 1
       while (end < input.length && depth > 0) {
-        if (input[end] === '(' && input[end - 1] !== '\\') depth++
-        else if (input[end] === ')' && input[end - 1] !== '\\') depth--
+        if (input[end] === open && input[end - 1] !== '\\') depth++
+        else if (input[end] === close && input[end - 1] !== '\\') depth--
         end++
       }
       if (depth > 0) continue
       const raw = input.slice(start + 1, i).trim()
       const url = input.slice(i + 2, end - 1).trim()
       let key: string
       let tag: string
-      if (raw) {
+      if (isLatex) {
+        const [txt = '', width = '', height = '', fontHeight = '', padding = ''] = raw.split('|').map((s) => s.trim())
+        key = `zaileys_LATEX_${latexIndex++}`
+        tag = `{{${key}}}${txt || 'image'}{{/${key}}}`
+        ie.push({ type: 'latex', ie: { key, text: txt, url, width, height, font_height: fontHeight, padding } })
+      } else if (raw) {
         key = `zaileys_HYPERLINK_${hyperlinkIndex++}`
         tag = `{{${key}}}${url}{{/${key}}}`
         ie.push({ type: 'hyperlink', ie: { key, text: raw, url } })
@@ -132,6 +141,22 @@ const toInlineEntities = (extracted: ExtractedIE): InlineEntity[] =>
         metadata: { display_name: ie['text'], is_trusted: true, url: ie['url'], __typename: 'GenAIInlineLinkItem' },
       }
     }
+    if (type === 'latex') {
+      return {
+        key: ie['key']!,
+        metadata: {
+          latex_expression: ie['text'],
+          latex_image: {
+            url: ie['url'],
+            width: Number(ie['width']) || 100,
+            height: Number(ie['height']) || 100,
+          },
+          font_height: Number(ie['font_height']) || 83.33333333333333,
+          padding: Number(ie['padding']) || 15,
+          __typename: 'GenAILatexItem',
+        },
+      }
+    }
     return {
       key: ie['key']!,
       metadata: {
@@ -251,7 +276,8 @@ const SOURCE_URL = 'https://github.com/zeative/zaileys'
 
 /**
  * Build an EXPERIMENTAL AIRich message (Meta AI rich-response format). Composes
- * text (with `[label](url)` hyperlinks and `[](url)` citations), code blocks,
+ * text (with `[label](url)` hyperlinks, `[](url)` citations, and `[expr]<imageUrl>`
+ * LaTeX where `expr` may be `txt|width|height|fontHeight|padding`), code blocks,
  * tables, images, videos, product carousels, reels, posts, tips, and suggestion
  * pills into a `botForwardedMessage` relayed as an AI response.
  *

src/builder/content/buttons.ts

@@ -1,6 +1,6 @@
 import { proto, type AnyMessageContent } from 'baileys'
 import { ZaileysBuilderError } from '../errors.js'
-import type { ButtonDef, InteractiveButton, MediaSource } from '../types.js'
+import type { BottomSheetOptions, ButtonDef, InteractiveButton, LimitedTimeOfferOptions, MediaSource } from '../types.js'
 
 const MAX_BUTTONS = 10
 
@@ -21,26 +21,37 @@ export type HeaderMedia = { kind: 'image' | 'video'; src: MediaSource }
 /** Content shape carrying a pre-built proto message (+ optional header media) for the relay send path. */
 export type RelayContent = { [RELAY_CONTENT_KEY]: proto.IMessage; [RELAY_MEDIA_KEY]?: HeaderMedia }
 
-/** Optional decoration for {@link buildButtonsContent}: body text, footer, and a text/media header. */
+/** Optional decoration for {@link buildButtonsContent}: body text, footer, a text/media header, and nativeFlow params. */
 export type ButtonsContentOptions = {
   text?: string
   footer?: string
   title?: string
   subtitle?: string
   image?: MediaSource
   video?: MediaSource
+  bottomSheet?: BottomSheetOptions
+  limitedTimeOffer?: LimitedTimeOfferOptions
 }
 
 type NativeButton = { name: string; buttonParamsJson: string }
 
 const nonEmpty = (value: unknown): value is string => typeof value === 'string' && value.length > 0
 
-const toNativeButton = (button: ButtonDef | InteractiveButton, seen: Set<string>): NativeButton => {
+const requireText = (button: ButtonDef | InteractiveButton): string => {
   const text = (button as { text?: unknown }).text
   if (!nonEmpty(text) || text.trim().length === 0) {
     throw new ZaileysBuilderError('INVALID_OPTIONS', 'button text must be a non-empty string')
   }
+  return text
+}
+
+const toNativeButton = (button: ButtonDef | InteractiveButton, seen: Set<string>): NativeButton => {
   const type = (button as InteractiveButton).type ?? 'reply'
+  if (type === 'location') {
+    const text = (button as { text?: unknown }).text
+    return { name: 'send_location', buttonParamsJson: JSON.stringify(nonEmpty(text) ? { display_text: text } : {}) }
+  }
+  const text = requireText(button)
   if (type === 'reply') {
     const id = (button as ButtonDef).id
     if (!nonEmpty(id)) {
@@ -77,9 +88,42 @@ const toNativeButton = (button: ButtonDef | InteractiveButton, seen: Set<string>
     }
     return { name: 'cta_call', buttonParamsJson: JSON.stringify({ display_text: text, id: phone, phone_number: phone }) }
   }
+  if (type === 'reminder' || type === 'cancel-reminder') {
+    const id = (button as { id?: unknown }).id
+    const name = type === 'reminder' ? 'cta_reminder' : 'cta_cancel_reminder'
+    return { name, buttonParamsJson: JSON.stringify({ display_text: text, id: nonEmpty(id) ? id : text }) }
+  }
+  if (type === 'address') {
+    const id = (button as { id?: unknown }).id
+    return { name: 'address_message', buttonParamsJson: JSON.stringify({ display_text: text, id: nonEmpty(id) ? id : text }) }
+  }
   throw new ZaileysBuilderError('INVALID_OPTIONS', `unknown button type: ${String(type)}`)
 }
 
+/** Serialize {@link BottomSheetOptions}/{@link LimitedTimeOfferOptions} into the nativeFlow `messageParamsJson` string. */
+export const buildMessageParamsJson = (opts?: ButtonsContentOptions): string => {
+  const params: Record<string, unknown> = {}
+  if (opts?.bottomSheet) {
+    const b = opts.bottomSheet
+    params['bottom_sheet'] = {
+      ...(b.buttonsLimit !== undefined ? { in_thread_buttons_limit: b.buttonsLimit } : {}),
+      ...(b.dividers !== undefined ? { divider_indices: b.dividers } : {}),
+      ...(b.listTitle !== undefined ? { list_title: b.listTitle } : {}),
+      ...(b.buttonTitle !== undefined ? { button_title: b.buttonTitle } : {}),
+    }
+  }
+  if (opts?.limitedTimeOffer) {
+    const o = opts.limitedTimeOffer
+    params['limited_time_offer'] = {
+      ...(o.text !== undefined ? { text: o.text } : {}),
+      ...(o.url !== undefined ? { url: o.url } : {}),
+      ...(o.copyCode !== undefined ? { copy_code: o.copyCode } : {}),
+      ...(o.expiresAt !== undefined ? { expiration_time: o.expiresAt } : {}),
+    }
+  }
+  return Object.keys(params).length > 0 ? JSON.stringify(params) : ''
+}
+
 /**
  * Map declarative buttons to nativeFlow buttons, validating each. Reusable by
  * {@link buildButtonsContent} and the carousel card builder.
@@ -120,7 +164,7 @@ export const buildButtonsContent = (
 
   const interactiveMessage: proto.Message.IInteractiveMessage = {
     body: { text: opts?.text && opts.text.length > 0 ? opts.text : ' ' },
-    nativeFlowMessage: { buttons: nativeButtons, messageParamsJson: '' },
+    nativeFlowMessage: { buttons: nativeButtons, messageParamsJson: buildMessageParamsJson(opts) },
   }
   if (opts?.footer && opts.footer.length > 0) {
     interactiveMessage.footer = { text: opts.footer }

src/builder/content/list.ts

@@ -1,34 +1,28 @@
-import type { AnyMessageContent } from 'baileys'
+import { proto, type AnyMessageContent } from 'baileys'
 import { ZaileysBuilderError } from '../errors.js'
 import type { ListOptions } from '../types.js'
+import { RELAY_CONTENT_KEY, type RelayContent } from './buttons.js'
 
 const MAX_ROWS = 10
 
-/** A single list row in the emitted content; `rowId` is the round-trip field. */
-export type ListContentRow = { rowId: string; title: string; description?: string }
+/** A single nativeFlow `single_select` row; `id` is the round-trip field surfaced as `ListSelectPayload.rowId`. */
+export type ListContentRow = { header: string; title: string; description: string; id: string }
 
-/** A list section in the emitted content. */
-export type ListContentSection = { title: string; rows: ListContentRow[] }
-
-/** Interactive list-message content; carried structurally past the Baileys public `AnyMessageContent` type. */
-export type ListContent = {
-  text: string
-  footer?: string
-  title?: string
-  buttonText: string
-  sections: ListContentSection[]
-}
+/** A nativeFlow `single_select` section. */
+export type ListContentSection = { title: string; highlight_label: string; rows: ListContentRow[] }
 
 /**
- * Build list-message content from declarative {@link ListOptions}.
+ * Build a nativeFlow `single_select` list message from declarative {@link ListOptions},
+ * returned as relay-marker content.
  *
- * rc13 decision: as with buttons, the public `AnyMessageContent` union no longer
- * exposes a `listMessage` branch. The legacy list shape is still accepted by the
- * relay layer and is what `decodeListSelect` round-trips against, so it is emitted
- * here and cast at the builder boundary.
+ * rc13 decision: the legacy `listMessage` shape no longer renders on personal
+ * WhatsApp accounts. A `single_select` button inside an `interactiveMessage`
+ * renders through the same `biz > interactive (native_flow)` node the builder
+ * attaches for buttons, so lists now render everywhere buttons do.
  *
- * Each `ListSection.rows[].id` is mapped to `rowId` and returns unchanged as
- * `ListSelectPayload.rowId` when a user picks a row (Phase 4 EVT-12).
+ * Each `ListSection.rows[].id` is emitted as the row `id` and returns unchanged as
+ * `ListSelectPayload.rowId` when a user picks a row (decoded from
+ * `interactiveResponseMessage.nativeFlowResponseMessage`).
  *
  * @param opts - sections (≥1, ≤10 total rows) plus `buttonText` and optional decoration.
  * @throws ZaileysBuilderError `INVALID_OPTIONS` on blank button text, no sections,
@@ -60,23 +54,30 @@ export const buildListContent = (opts: ListOptions): AnyMessageContent => {
       }
       seen.add(row.id)
       rowCount += 1
-      const built: ListContentRow = { rowId: row.id, title: row.title }
-      if (row.description !== undefined) built.description = row.description
-      return built
+      return { header: '', title: row.title, description: row.description ?? '', id: row.id }
     })
-    return { title: section.title, rows }
+    return { title: section.title, highlight_label: '', rows }
   })
 
   if (rowCount > MAX_ROWS) {
     throw new ZaileysBuilderError('INVALID_OPTIONS', `list() accepts at most ${MAX_ROWS} rows total`)
   }
 
-  const content: ListContent = {
-    text: opts.description && opts.description.length > 0 ? opts.description : ' ',
-    buttonText: opts.buttonText,
-    sections,
+  const selectButton = {
+    name: 'single_select',
+    buttonParamsJson: JSON.stringify({ title: opts.buttonText, sections }),
+  }
+  const interactiveMessage: proto.Message.IInteractiveMessage = {
+    body: { text: opts.description && opts.description.length > 0 ? opts.description : ' ' },
+    nativeFlowMessage: { buttons: [selectButton], messageParamsJson: '' },
   }
-  if (opts.title && opts.title.length > 0) content.title = opts.title
-  if (opts.footerText && opts.footerText.length > 0) content.footer = opts.footerText
-  return content as unknown as AnyMessageContent
+  if (opts.footerText && opts.footerText.length > 0) {
+    interactiveMessage.footer = { text: opts.footerText }
+  }
+  if (opts.title && opts.title.length > 0) {
+    interactiveMessage.header = { title: opts.title, subtitle: '', hasMediaAttachment: false }
+  }
+
+  const relay: RelayContent = { [RELAY_CONTENT_KEY]: { interactiveMessage } }
+  return relay as unknown as AnyMessageContent
 }