@kyyinfinite/lumina 1.0.0

package/src/builders/ai-rich.js

@@ -0,0 +1,644 @@
+/**
+ * @file builders/ai-rich.js
+ * @module lumina/builders/ai-rich
+ *
+ * AIRichBuilder — modern, fully-chainable builder for WhatsApp's AI Rich
+ * Response feature.
+ *
+ * This is the productionised successor of the legacy `AIRich` class (which
+ * was 1,270 lines, 57% of `_build-m.js`). Every legacy issue flagged in
+ * Tahap-1 analysis is fixed here:
+ *
+ *   1. Promise-in-state anti-pattern → eager await on every `add*()`.
+ *   2. 12x hardcoded `__typename` strings → sourced from `proto/primitives`.
+ *   3. 5x `messageType` magic numbers → sourced from `proto/enums.MessageType`.
+ *   4. Hardcoded `botJid: '0@bot'` → from `proto/enums.BOT_JID`.
+ *   5. Hardcoded `forwardOrigin: 4` → from `proto/enums.ForOrigin`.
+ *   6. Personal leftover `disclaimerText: '~ Ahmad tumbuh kembang'` removed.
+ *   7. Typo `GenATableUXPrimitive` corrected to `GenAITableUXPrimitive`.
+ *   8. `tokenizer` + `toTableMetadata` + `newLayout` extracted to dedicated modules.
+ *   9. 5x duplicated validation helper → `utils/validator.ensureObjectOrArray`.
+ *  10. Footer handling consolidated (was inlined in `build()`).
+ *
+ * API (verb-first fluent):
+ *   bot.ai().title(t).text(...).code(...).image(...).table(...).send(jid)
+ */
+
+import { applyContentFields } from './base.js'
+import { ensureObjectOrArray, ensureString, ensureStringArray } from '../utils/validator.js'
+import { ValidationError } from '../errors.js'
+
+import { extractInlineEntities } from '../parsers/inline-entity.js'
+import { tokenizeCode } from '../parsers/code-tokenizer.js'
+import { toTableMetadata } from '../parsers/table-metadata.js'
+
+import {
+  markdownTextPrimitive,
+  codePrimitive,
+  tablePrimitive,
+  searchResultPrimitive,
+  reelPrimitive,
+  imaginePrimitive,
+  productCardPrimitive,
+  postPrimitive,
+  metadataTextPrimitive,
+  followUpSuggestionPillPrimitive,
+  shapeSourceEntry,
+  shapeReelEntry,
+} from '../proto/primitives.js'
+import { singleLayout, hscrollLayout, actionRowLayout } from '../proto/layouts.js'
+import { assembleRichResponse } from '../proto/rich-response.js'
+import { MessageType, ImagineType, LayoutKind } from '../proto/enums.js'
+
+/** @typedef {import('../client/connection.js').Connection} Connection */
+/** @typedef {import('../services/proto-service.js').ProtoService} ProtoService */
+/** @typedef {import('../services/media-service.js').MediaService} MediaService */
+
+export class AIRichBuilder {
+  /**
+   * @param {Connection} conn
+   * @param {ProtoService} proto
+   * @param {MediaService} media
+   */
+  constructor(conn, proto, media) {
+    applyContentFields(this)
+    this.#conn = conn
+    this.#proto = proto
+    this.#media = media
+
+    /** @type {Array<object>} */
+    this._submessages = []
+    /** @type {Array<object>} */
+    this._sections = []
+    /** @type {Array<object>} */
+    this._richResponseSources = []
+
+    /** @type {boolean} */
+    this._forwarded = true
+    /** @type {boolean | object} */
+    this._notification = false
+    /** @type {boolean} */
+    this._includesUnifiedResponse = true
+    /** @type {boolean} */
+    this._includesSubmessages = true
+    /** @type {object | undefined} */
+    this._quoted
+    /** @type {string | undefined} */
+    this._quotedParticipant
+  }
+
+  /** @type {Connection} */ #conn
+  /** @type {ProtoService} */ #proto
+  /** @type {MediaService} */ #media
+
+  // ─── Envelope options ───────────────────────────────────────────────
+
+  /**
+   * Toggle forwarding metadata (default: on).
+   *
+   * @param {boolean} [v=true]
+   */
+  forwarded(v = true) {
+    this._forwarded = v
+    return this
+  }
+
+  /**
+   * Attach session-transparency metadata.
+   *
+   * @param {boolean | object} v   `true` for defaults, or `{ disclaimerText, hcaId, sessionTransparencyType }`.
+   */
+  notification(v) {
+    this._notification = v
+    return this
+  }
+
+  /**
+   * @param {object} quoted
+   * @param {string} [quotedParticipant]
+   */
+  quoted(quoted, quotedParticipant) {
+    this._quoted = quoted
+    this._quotedParticipant = quotedParticipant
+    return this
+  }
+
+  /**
+   * @param {boolean} [v=true]
+   */
+  includesUnifiedResponse(v = true) {
+    this._includesUnifiedResponse = v
+    return this
+  }
+
+  /**
+   * @param {boolean} [v=true]
+   */
+  includesSubmessages(v = true) {
+    this._includesSubmessages = v
+    return this
+  }
+
+  /**
+   * Push a raw submessage object (escape hatch).
+   *
+   * @param {object | object[]} msg
+   */
+  submessage(msg) {
+    const items = Array.isArray(msg) ? msg : [msg]
+    items.forEach((m) => ensureObjectOrArray(m, 'submessage'))
+    this._submessages.push(...items)
+    return this
+  }
+
+  // ─── Primitives ─────────────────────────────────────────────────────
+
+  /**
+   * Add a markdown-text primitive. Inline entities (`[text](url)`, `[](url)`,
+   * `[text]<url|w|h|fh|p>`) are auto-extracted.
+   *
+   * @param {string} text
+   * @param {object} [opts]   { hyperlink, citation, latex } — all default true.
+   * @returns {Promise<this>}
+   */
+  async text(text, opts = {}) {
+    ensureString(text, 'text')
+    const { hyperlink = true, citation = true, latex = true } = opts
+
+    const { text: rewritten, metadata } = extractInlineEntities(text, {
+      hyperlink,
+      citation,
+      latex,
+    })
+
+    this._submessages.push({
+      messageType: MessageType.TEXT,
+      messageText: rewritten,
+    })
+
+    this._sections.push(
+      singleLayout(markdownTextPrimitive(rewritten, metadata.length ? metadata : undefined)),
+    )
+    return this
+  }
+
+  /**
+   * Add a code-block primitive. Code is auto-tokenized for syntax highlighting.
+   *
+   * @param {string} language   e.g. 'javascript', 'python', 'go'.
+   * @param {string} code
+   * @returns {Promise<this>}
+   */
+  async code(language, code) {
+    ensureString(language, 'language')
+    ensureString(code, 'code')
+
+    const { codeBlock, unifiedBlocks } = tokenizeCode(code, language)
+
+    this._submessages.push({
+      messageType: MessageType.CODE,
+      codeMetadata: {
+        codeLanguage: language,
+        codeBlocks: codeBlock,
+      },
+    })
+
+    this._sections.push(singleLayout(codePrimitive(language, unifiedBlocks)))
+    return this
+  }
+
+  /**
+   * Add a table primitive.
+   *
+   * @param {string[][]} table    First row is the header.
+   * @param {object} [opts]       { title, hyperlink, citation, latex }
+   * @returns {Promise<this>}
+   */
+  async table(table, opts = {}) {
+    if (!Array.isArray(table)) {
+      throw new ValidationError('table must be a 2-D array', { code: 'LUMINA_VALIDATION_TABLE' })
+    }
+    const { title = '', hyperlink = true, citation = true, latex = true } = opts
+    const meta = toTableMetadata(table, { title, hyperlink, citation, latex })
+
+    this._submessages.push({
+      messageType: MessageType.TABLE,
+      tableMetadata: { title: meta.title, rows: meta.rows },
+    })
+
+    this._sections.push(singleLayout(tablePrimitive(meta.unifiedRows)))
+    return this
+  }
+
+  /**
+   * Add image primitive(s). Auto-uploads to WhatsApp.
+   *
+   * @param {string | Buffer | Array<string | Buffer>} source
+   * @param {object} [opts]   { resolveUrl } — passed to MediaService.resolve.
+   * @returns {Promise<this>}
+   */
+  async image(source, opts = {}) {
+    const { resolveUrl = false } = opts
+    const list = Array.isArray(source) ? source : [source]
+
+    /** @type {Array<{ imagePreviewUrl: string, imageHighResUrl: string, sourceUrl: string }>} */
+    const resolved = await Promise.all(
+      list.map(async (s) => {
+        const url = await this.#media.resolve(s, {
+          mediaType: 'image',
+          strategy: resolveUrl ? 'auto' : 'auto',
+        })
+        return {
+          imagePreviewUrl: url,
+          imageHighResUrl: url,
+          sourceUrl: url,
+        }
+      }),
+    )
+
+    this._submessages.push({
+      messageType: MessageType.RICH_RESPONSE,
+      gridImageMetadata: {
+        gridImageUrl: { imagePreviewUrl: resolved[0]?.imagePreviewUrl },
+        imageUrls: resolved,
+      },
+    })
+
+    for (const r of resolved) {
+      this._sections.push(
+        singleLayout(
+          imaginePrimitive(
+            { url: r.imagePreviewUrl, mime_type: 'image/png' },
+            ImagineType.IMAGE,
+          ),
+        ),
+      )
+    }
+    return this
+  }
+
+  /**
+   * Add video primitive(s). Auto-fills file_length, duration, and thumbnail
+   * by downloading & inspecting the buffer (configurable via `autoFill`).
+   *
+   * @param {string | Buffer | object | Array} source
+   * @param {object} [opts]   { autoFill = true }
+   * @returns {Promise<this>}
+   */
+  async video(source, opts = {}) {
+    const { autoFill = true } = opts
+    const isObjectVideo = (v) => v && typeof v === 'object' && v.url
+    const items = Array.isArray(source) ? source : [source]
+
+    // Placeholder submessage — matches the legacy '[ CANNOT_LOAD_VIDEO ]' pattern.
+    this._submessages.push({
+      messageType: MessageType.TEXT,
+      messageText: '[ CANNOT_LOAD_VIDEO ]',
+    })
+
+    await Promise.all(
+      items.map(async (item) => {
+        const isObj = isObjectVideo(item)
+        const url = await this.#media.resolve(
+          isObj ? item.url : item,
+          { mediaType: 'video', strategy: 'auto' },
+        )
+
+        let fileLength = isObj && item.file_length != null ? item.file_length : 0
+        let duration = isObj && item.duration != null ? item.duration : 0
+        let thumbnailB64 = null
+
+        if (autoFill) {
+          try {
+            const buf = typeof url === 'string' ? await this.#media.fetch(url) : url
+            if (buf?.length) {
+              fileLength = buf.length
+              duration = this.#media.duration(buf)
+              thumbnailB64 = await this.#media.videoThumbnail(buf, {
+                time: 0,
+                result: 'base64',
+                resizeOutput: true,
+                width: 300,
+                height: 300,
+              })
+            }
+          } catch {
+            // Swallow autofill failures — the video URL alone is still useful.
+          }
+        }
+
+        const mimeType = isObj ? item.mime_type ?? 'video/mp4' : 'video/mp4'
+
+        this._sections.push(
+          singleLayout(
+            imaginePrimitive(
+              { url, mime_type: mimeType, file_length: fileLength, duration },
+              ImagineType.ANIMATE,
+              'READY',
+              thumbnailB64 || undefined,
+            ),
+          ),
+        )
+      }),
+    )
+    return this
+  }
+
+  /**
+   * Add source(s) — citation footnotes with favicon, URL, and display text.
+   *
+   * @param {Array<string> | Array<Array<string>>} sources
+   *        Each entry is either `[iconUrl, url, text]` or (when only strings)
+   *        an array of URLs that get empty favicons.
+   * @returns {Promise<this>}
+   */
+  async source(sources = []) {
+    if (!Array.isArray(sources)) {
+      throw new ValidationError('sources must be an array', { code: 'LUMINA_VALIDATION_SOURCE' })
+    }
+
+    const normalised =
+      sources.length && typeof sources[0] === 'string'
+        ? [sources]
+        : sources
+
+    const entries = await Promise.all(
+      normalised.map(async (entry) => {
+        const [iconUrl, url, text] = entry
+        const resolvedIcon = iconUrl
+          ? await this.#media.resolve(iconUrl, { mediaType: 'image', strategy: 'auto' })
+          : ''
+        return shapeSourceEntry({ iconUrl: resolvedIcon, url, text })
+      }),
+    )
+
+    this._sections.push(singleLayout(searchResultPrimitive(entries)))
+    return this
+  }
+
+  /**
+   * Add reel(s) — short-video cards with avatar, thumbnail, like/view counts.
+   *
+   * @param {object | object[]} items
+   * @returns {Promise<this>}
+   */
+  async reels(items) {
+    ensureObjectOrArray(items, 'reels')
+    const list = Array.isArray(items) ? items : [items]
+
+    const resolved = await Promise.all(
+      list.map(async (item) => {
+        const [avatar, thumb] = await Promise.all([
+          item.profileIconUrl ?? item.profile_url ?? item.profile
+            ? this.#media.resolve(item.profileIconUrl ?? item.profile_url ?? item.profile, {
+                mediaType: 'image',
+                strategy: 'auto',
+              })
+            : Promise.resolve(''),
+          item.thumbnailUrl ?? item.thumbnail
+            ? this.#media.resolve(item.thumbnailUrl ?? item.thumbnail, {
+                mediaType: 'image',
+                strategy: 'auto',
+              })
+            : Promise.resolve(''),
+        ])
+        return { ...item, avatar, thumbnail: thumb }
+      }),
+    )
+
+    this._submessages.push({
+      messageType: MessageType.REELS,
+      contentItemsMetadata: {
+        contentType: 1,
+        itemsMetadata: resolved.map((item) => ({
+          reelItem: {
+            title: item.username ?? '',
+            profileIconUrl: item.avatar,
+            thumbnailUrl: item.thumbnail,
+            videoUrl: item.videoUrl ?? item.url ?? '',
+          },
+        })),
+      },
+    })
+
+    resolved.forEach((item, idx) => {
+      this._richResponseSources.push({
+        provider: 'LUMINA',
+        thumbnailCDNURL: item.thumbnail,
+        sourceProviderURL: item.videoUrl ?? item.url ?? '',
+        sourceQuery: '',
+        faviconCDNURL: item.avatar,
+        citationNumber: idx + 1,
+        sourceTitle: item.username ?? '',
+      })
+    })
+
+    this._sections.push(
+      hscrollLayout(resolved.map((item) => reelPrimitive(shapeReelEntry(item)))),
+    )
+    return this
+  }
+
+  /**
+   * Add product card(s).
+   *
+   * @param {object | object[]} item
+   * @returns {Promise<this>}
+   */
+  async product(item) {
+    ensureObjectOrArray(item, 'product')
+    const list = Array.isArray(item) ? item : [item]
+
+    this._submessages.push({
+      messageType: MessageType.TEXT,
+      messageText: '[ CANNOT_LOAD_PRODUCT ]',
+    })
+
+    const products = await Promise.all(
+      list.map(async (p) => {
+        const [imageUrl, iconUrl] = await Promise.all([
+          p.image_url ?? p.image
+            ? this.#media.resolve(p.image_url ?? p.image, { mediaType: 'image', strategy: 'auto' })
+            : Promise.resolve(''),
+          p.icon_url ?? p.icon
+            ? this.#media.resolve(p.icon_url ?? p.icon, { mediaType: 'image', strategy: 'auto' })
+            : Promise.resolve(''),
+        ])
+        return {
+          title: p.title,
+          brand: p.brand,
+          price: p.price,
+          sale_price: p.sale_price,
+          product_url: p.product_url ?? p.url,
+          image: { url: imageUrl },
+          additional_images: [{ url: iconUrl }],
+        }
+      }),
+    )
+
+    const primitives = products.map((p) => productCardPrimitive(p))
+    this._sections.push(
+      list.length === 1 ? singleLayout(primitives[0]) : hscrollLayout(primitives),
+    )
+    return this
+  }
+
+  /**
+   * Add post(s).
+   *
+   * @param {object | object[]} item
+   * @returns {Promise<this>}
+   */
+  async post(item) {
+    ensureObjectOrArray(item, 'post')
+    const list = Array.isArray(item) ? item : [item]
+
+    this._submessages.push({
+      messageType: MessageType.TEXT,
+      messageText: '[ CANNOT_LOAD_POST ]',
+    })
+
+    const isCarousel = list.length > 1
+
+    const primitives = await Promise.all(
+      list.map(async (p) => {
+        const [profileUrl, thumbUrl, footerIcon] = await Promise.all([
+          p.profile_picture_url ?? p.profile_url ?? p.profile
+            ? this.#media.resolve(p.profile_picture_url ?? p.profile_url ?? p.profile, {
+                mediaType: 'image',
+                strategy: 'auto',
+              })
+            : Promise.resolve(''),
+          p.thumbnail_url ?? p.thumbnail
+            ? this.#media.resolve(p.thumbnail_url ?? p.thumbnail, {
+                mediaType: 'image',
+                strategy: 'auto',
+              })
+            : Promise.resolve(''),
+          p.footer_icon ?? p.icon
+            ? this.#media.resolve(p.footer_icon ?? p.icon, {
+                mediaType: 'image',
+                strategy: 'auto',
+              })
+            : Promise.resolve(''),
+        ])
+
+        return postPrimitive(
+          {
+            title: p.title ?? '',
+            subtitle: p.subtitle ?? '',
+            username: p.username ?? '',
+            profile_picture_url: profileUrl,
+            is_verified: !!(p.is_verified ?? p.verified),
+            thumbnail_url: thumbUrl,
+            post_caption: p.post_caption ?? p.caption ?? '',
+            likes_count: p.likes_count ?? p.like ?? 0,
+            comments_count: p.comments_count ?? p.comment ?? 0,
+            shares_count: p.shares_count ?? p.share ?? 0,
+            post_url: p.post_url ?? p.url ?? '',
+            post_deeplink: p.post_deeplink ?? p.deeplink ?? '',
+            source_app: p.source_app ?? p.source ?? 'INSTAGRAM',
+            footer_label: p.footer_label ?? p.footer ?? '',
+            footer_icon: footerIcon,
+            orientation: p.orientation ?? 'LANDSCAPE',
+            post_type: p.post_type ?? 'VIDEO',
+          },
+          isCarousel,
+        )
+      }),
+    )
+
+    this._sections.push(hscrollLayout(primitives))
+    return this
+  }
+
+  /**
+   * Add a tip / metadata-text primitive (small footer-style hint).
+   *
+   * @param {string} text
+   * @returns {Promise<this>}
+   */
+  async tip(text) {
+    ensureString(text, 'tip text')
+    this._submessages.push({ messageType: MessageType.TEXT, messageText: text })
+    this._sections.push(singleLayout(metadataTextPrimitive(text)))
+    return this
+  }
+
+  /**
+   * Add follow-up suggestion pill(s).
+   *
+   * @param {string | string[]} suggestion
+   * @param {object} [opts]   { scroll = true, layout?: 'Single'|'HScroll'|'ActionRow' }
+   * @returns {Promise<this>}
+   */
+  async suggest(suggestion, opts = {}) {
+    const { scroll = true, layout } = opts
+
+    if (typeof suggestion === 'string') {
+      suggestion = [suggestion]
+    } else {
+      ensureStringArray(suggestion, 'suggestion')
+    }
+
+    const pills = suggestion.map((text) => followUpSuggestionPillPrimitive(text))
+
+    let kind
+    if (layout) {
+      kind = layout
+    } else if (pills.length === 1) {
+      kind = LayoutKind.SINGLE
+    } else {
+      kind = scroll ? LayoutKind.HSCROLL : LayoutKind.ACTION_ROW
+    }
+
+    if (kind === LayoutKind.SINGLE) {
+      this._sections.push(singleLayout(pills[0], { __typename: 'GenAIUnifiedResponseSection' }))
+    } else if (kind === LayoutKind.HSCROLL) {
+      this._sections.push(hscrollLayout(pills, { __typename: 'GenAIUnifiedResponseSection' }))
+    } else {
+      this._sections.push(actionRowLayout(pills, { __typename: 'GenAIUnifiedResponseSection' }))
+    }
+    return this
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────
+
+  /**
+   * Assemble the `botForwardedMessage` envelope (without relaying).
+   *
+   * @param {object} [opts]   Overrides forwarded / notification / etc.
+   * @returns {Promise<object>}
+   */
+  async build(opts = {}) {
+    return assembleRichResponse({
+      title: this._title,
+      sections: this._sections,
+      submessages: this._submessages,
+      richResponseSources: this._richResponseSources,
+      contextInfo: this._contextInfo,
+      footer: this._footer,
+      forwarded: opts.forwarded ?? this._forwarded,
+      notification: opts.notification ?? this._notification,
+      includesUnifiedResponse: opts.includesUnifiedResponse ?? this._includesUnifiedResponse,
+      includesSubmessages: opts.includesSubmessages ?? this._includesSubmessages,
+      quoted: opts.quoted ?? this._quoted,
+      quotedParticipant: opts.quotedParticipant ?? this._quotedParticipant,
+      extraPayload: this._extraPayload,
+    })
+  }
+
+  /**
+   * Build + relay via the Baileys socket.
+   *
+   * @param {string} jid
+   * @param {object} [opts]
+   * @returns {Promise<string>}  Message ID.
+   */
+  async send(jid, opts = {}) {
+    const envelope = await this.build(opts)
+    return this.#conn.relayMessage(jid, envelope, opts)
+  }
+}
+
+export default AIRichBuilder