@kyyinfinite/lumina 1.0.0

package/src/builders/base.js

@@ -0,0 +1,109 @@
+/**
+ * @file builders/base.js
+ * @module lumina/builders/base
+ *
+ * Builder-state composer. Lumina deliberately avoids a `BaseBuilder` parent
+ * class — inheritance forces every builder to carry every state field
+ * (`_title`, `_subtitle`, etc.) whether or not they need it, and locks the
+ * framework into a single hierarchy.
+ *
+ * Instead, we expose `applyContentFields(target)` — a mixin that attaches
+ * the fluent content methods (`title`, `body`, `footer`, `contextInfo`,
+ * `payload`) to whatever builder invokes it. A builder composes only the
+ * capabilities it needs.
+ */
+
+import { ensurePlainObject } from '../utils/validator.js'
+import { ValidationError } from '../errors.js'
+
+/**
+ * Apply the shared content-mixin to a builder instance.
+ *
+ * Attaches:
+ *   - title(t)        → sets _title
+ *   - subtitle(t)     → sets _subtitle
+ *   - body(t)         → sets _body
+ *   - footer(t)       → sets _footer
+ *   - contextInfo(o)  → sets _contextInfo (validated plain object)
+ *   - payload(o)      → merges into _extraPayload (validated plain object)
+ *
+ * Each method returns `this` for chaining.
+ *
+ * @template {object} T
+ * @param {T} target   The builder instance to mixin into.
+ * @param {object} [initial]   Optional initial state.
+ * @returns {T & ContentFields}
+ */
+export function applyContentFields(target, initial = {}) {
+  target._title = initial.title ?? ''
+  target._subtitle = initial.subtitle ?? ''
+  target._body = initial.body ?? ''
+  target._footer = initial.footer ?? ''
+  target._contextInfo = initial.contextInfo ?? {}
+  target._extraPayload = initial.extraPayload ?? {}
+
+  target.title = function (t) {
+    if (typeof t !== 'string') {
+      throw new ValidationError('title must be a string', { code: 'LUMINA_VALIDATION_TITLE' })
+    }
+    target._title = t
+    return target
+  }
+
+  target.subtitle = function (t) {
+    if (typeof t !== 'string') {
+      throw new ValidationError('subtitle must be a string', { code: 'LUMINA_VALIDATION_SUBTITLE' })
+    }
+    target._subtitle = t
+    return target
+  }
+
+  target.body = function (t) {
+    if (typeof t !== 'string') {
+      throw new ValidationError('body must be a string', { code: 'LUMINA_VALIDATION_BODY' })
+    }
+    target._body = t
+    return target
+  }
+
+  target.footer = function (t) {
+    if (typeof t !== 'string') {
+      throw new ValidationError('footer must be a string', { code: 'LUMINA_VALIDATION_FOOTER' })
+    }
+    target._footer = t
+    return target
+  }
+
+  target.contextInfo = function (o) {
+    ensurePlainObject(o, 'contextInfo')
+    target._contextInfo = o
+    return target
+  }
+
+  target.payload = function (o) {
+    ensurePlainObject(o, 'payload')
+    Object.assign(target._extraPayload, o)
+    return target
+  }
+
+  return target
+}
+
+/**
+ * Helper: extract the standard content fields as an envelope fragment.
+ *
+ * @param {object} target   A builder that has had applyContentFields called on it.
+ * @returns {{ title: string, subtitle: string, body: string, footer: string, contextInfo: object, extraPayload: object }}
+ */
+export function readContentFields(target) {
+  return {
+    title: target._title,
+    subtitle: target._subtitle,
+    body: target._body,
+    footer: target._footer,
+    contextInfo: target._contextInfo,
+    extraPayload: target._extraPayload,
+  }
+}
+
+export default { applyContentFields, readContentFields }

package/src/builders/button-v2.js

@@ -0,0 +1,159 @@
+/**
+ * @file builders/button-v2.js
+ * @module lumina/builders/button-v2
+ *
+ * ButtonV2Builder — legacy `buttonsMessage` format. Preserved for users who
+ * target WhatsApp clients that do not yet support native flow.
+ *
+ * Refactored to use the same mixin-based content fields, registry-based
+ * button factory, and centralised interactive relay nodes as ButtonBuilder.
+ * The hardcoded `headerType: 6` (LOCATION_THUMBNAIL) magic number is now
+ * sourced from `proto/enums.HeaderType`.
+ */
+
+import { applyContentFields } from './base.js'
+import { coerceMediaSource, ensurePlainObject } from '../utils/validator.js'
+import { createInteractiveNodes } from '../proto/relay-nodes.js'
+import { HeaderType } from '../proto/enums.js'
+import { uuid } from '../utils/id.js'
+
+import { fetchBuffer } from '../media/fetch.js'
+import { resize } from '../media/image.js'
+
+/** @typedef {import('../client/connection.js').Connection} Connection */
+
+export class ButtonV2Builder {
+  /** @param {Connection} conn */
+  constructor(conn) {
+    applyContentFields(this)
+    this.#conn = conn
+
+    /** @type {Array<object>} */
+    this._buttons = []
+    /** @type {string | Buffer | null} */
+    this._thumbnailSource = null
+    /** @type {object | null} */
+    this._data = null
+  }
+
+  /** @type {Connection} */ #conn
+
+  /**
+   * Add a legacy button with a display text and (optional) explicit ID.
+   * Auto-generates a UUID when `id` is omitted.
+   *
+   * @param {string} displayText
+   * @param {string} [id]
+   */
+  button(displayText, id = uuid()) {
+    this._buttons.push({
+      buttonId: id,
+      buttonText: { displayText },
+      type: 1,
+    })
+    return this
+  }
+
+  /**
+   * Push a raw, already-shaped button object.
+   *
+   * @param {object} obj
+   */
+  rawButton(obj) {
+    ensurePlainObject(obj, 'button')
+    this._buttons.push(obj)
+    return this
+  }
+
+  /**
+   * Set the JPEG thumbnail (used by the location-fallback path).
+   *
+   * @param {string | Buffer} source
+   */
+  thumbnail(source) {
+    if (!source) throw new TypeError('thumbnail source is required')
+    this._thumbnailSource = source
+    return this
+  }
+
+  /**
+   * Provide a fully-shaped media descriptor that overrides the
+   * location-thumbnail fallback entirely.
+   *
+   * @param {object} obj
+   */
+  media(obj) {
+    ensurePlainObject(obj, 'media')
+    this._data = obj
+    return this
+  }
+
+  /**
+   * Build the proto message object (without relaying).
+   *
+   * @param {string} jid
+   * @param {object} [opts]
+   * @returns {Promise<object>}
+   */
+  async build(jid, opts = {}) {
+    let jpegThumbnail = null
+    if (this._thumbnailSource) {
+      const buf = Buffer.isBuffer(this._thumbnailSource)
+        ? this._thumbnailSource
+        : await fetchBuffer(this._thumbnailSource, { silent: true })
+      if (buf.length) {
+        jpegThumbnail = await resize(buf, { width: 300, height: 300, fit: 'cover', format: 'png' })
+      }
+    }
+
+    const fallback =
+      this._data ??
+      {
+        headerType: HeaderType.LOCATION_THUMBNAIL,
+        locationMessage: {
+          degreesLatitude: 0,
+          degreesLongitude: 0,
+          name: this._title,
+          address: this._subtitle,
+          jpegThumbnail,
+        },
+      }
+
+    return this.#conn.generateMessage(
+      jid,
+      {
+        ...this._extraPayload,
+        buttonsMessage: {
+          contentText: this._body,
+          footerText: this._footer,
+          ...fallback,
+          viewOnce: true,
+          contextInfo: this._contextInfo,
+          buttons: [...this._buttons],
+        },
+      },
+      opts,
+    )
+  }
+
+  /**
+   * Build + relay.
+   *
+   * @param {string} jid
+   * @param {object} [opts]
+   */
+  async send(jid, opts = {}) {
+    if (this._buttons.length === 0) {
+      throw new Error('ButtonV2 requires at least one button')
+    }
+    const msg = await this.build(jid, opts)
+    await this.#conn.relayMessage(msg.key.remoteJid, msg.message, {
+      messageId: msg.key.id,
+      additionalNodes: opts.additionalNodes ?? createInteractiveNodes(),
+      ...opts,
+    })
+    return msg
+  }
+}
+
+export default ButtonV2Builder

package/src/builders/button.js

@@ -0,0 +1,398 @@
+/**
+ * @file builders/button.js
+ * @module lumina/builders/button
+ *
+ * ButtonBuilder — modern, chainable builder for native-flow interactive
+ * messages.
+ *
+ * Key improvements over the legacy `Button` class:
+ *
+ *   1. Verb-first fluent API (`title()`, `body()`, `reply()`, `url()`, …)
+ *      instead of Java-style `setTitle()` / `addReply()`.
+ *   2. Single unified `media(type, source)` method replaces the 3x
+ *      duplicated `setVideo/setImage/setDocument` of the legacy code.
+ *   3. Registry-based button factory: the 5 identical `addReply/addCall/
+ *      addReminder/addCancelReminder/addAddress` methods collapse to one
+ *      `BUTTON_TYPES` table + one factory.
+ *   4. Callback-based selection API (no more mutable `_currentSelectionIndex`
+ *      / `_currentSectionIndex` state juggling).
+ *   5. Interactive relay nodes sourced from `proto/relay-nodes.js` (was
+ *      duplicated 3x in the legacy code).
+ *   6. Dead `paramsList` static field removed entirely.
+ */
+
+import { applyContentFields } from './base.js'
+import { coerceMediaSource, ensurePlainObject } from '../utils/validator.js'
+import { createInteractiveNodes } from '../proto/relay-nodes.js'
+
+/** @typedef {import('../client/connection.js').Connection} Connection */
+/** @typedef {import('../services/proto-service.js').ProtoService} ProtoService */
+/** @typedef {import('../services/media-service.js').MediaService} MediaService */
+
+/**
+ * Registry of "simple" button types — those whose `buttonParamsJson` is just
+ * `{ display_text, id, ...opts }`. Adding a new simple type is a one-line change.
+ *
+ * @type {Record<string, string>}
+ */
+const SIMPLE_BUTTON_TYPES = {
+  reply: 'quick_reply',
+  call: 'cta_call',
+  reminder: 'cta_reminder',
+  cancelReminder: 'cta_cancel_reminder',
+  address: 'address_message',
+}
+
+/**
+ * Selection builder — passed to the `selection()` callback so users can
+ * compose sections & rows safely without mutating outer state.
+ */
+class SelectionBuilder {
+  constructor() {
+    this._title = ''
+    this._sections = []
+    this._currentSection = null
+  }
+
+  /** @param {string} t */
+  title(t) {
+    this._title = t
+    return this
+  }
+
+  /**
+   * @param {string} title
+   * @param {(s: SectionBuilder) => void} builder
+   */
+  section(title, builder) {
+    const section = { title, highlight_label: '', rows: [] }
+    const sb = new SectionBuilder(section.rows)
+    builder(sb)
+    this._sections.push(section)
+    return this
+  }
+
+  /** @returns {object} proto-ready selection params */
+  build() {
+    return { title: this._title, sections: this._sections }
+  }
+}
+
+class SectionBuilder {
+  /** @param {Array} rowsRef */
+  constructor(rowsRef) {
+    this._rows = rowsRef
+  }
+
+  /**
+   * @param {string} header
+   * @param {string} title
+   * @param {string} description
+   * @param {string} id
+   */
+  row(header, title, description, id) {
+    this._rows.push({ header, title, description, id })
+    return this
+  }
+}
+
+export class ButtonBuilder {
+  /**
+   * @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<{ name: string, buttonParamsJson: string }>} */
+    this._buttons = []
+    /** @type {object | null} */
+    this._data = null
+    /** @type {object} */
+    this._params = {}
+  }
+
+  /** @type {Connection} */ #conn
+  /** @type {ProtoService} */ #proto
+  /** @type {MediaService} */ #media
+
+  // ─── Media ──────────────────────────────────────────────────────────
+
+  /**
+   * Unified media setter. Replaces the legacy `setVideo/setImage/setDocument`
+   * triplicate.
+   *
+   * @param {'image'|'video'|'document'} type
+   * @param {string | Buffer | object} source
+   * @param {object} [opts]   Additional fields merged into the media descriptor.
+   */
+  media(type, source, opts = {}) {
+    if (!['image', 'video', 'document'].includes(type)) {
+      throw new TypeError(`media type must be image | video | document, got: ${type}`)
+    }
+    if (!source) throw new TypeError('media source is required')
+    this._data = { [type]: coerceMediaSource(source).raw, ...opts }
+    return this
+  }
+
+  /** @param {string | Buffer} source */
+  image(source, opts) {
+    return this.media('image', source, opts)
+  }
+
+  /** @param {string | Buffer} source */
+  video(source, opts) {
+    return this.media('video', source, opts)
+  }
+
+  /** @param {string | Buffer} source */
+  document(source, opts) {
+    return this.media('document', source, opts)
+  }
+
+  // ─── Buttons ────────────────────────────────────────────────────────
+
+  /**
+   * Generic raw-button pusher. Use this to attach button types Lumina does
+   * not have a shortcut for.
+   *
+   * @param {string} name     Button name as expected by WAProto.
+   * @param {object | string} params   Object (will be JSON.stringify-ed) or pre-stringified JSON.
+   * @param {object} [extra]   Extra top-level fields merged onto the button entry.
+   */
+  button(name, params, extra = {}) {
+    this._buttons.push({
+      name,
+      buttonParamsJson: typeof params === 'string' ? params : JSON.stringify(params),
+      ...extra,
+    })
+    return this
+  }
+
+  /**
+   * Configure `messageParamsJson` (top-level interactive message params).
+   *
+   * @param {object} obj
+   */
+  params(obj) {
+    ensurePlainObject(obj, 'params')
+    this._params = obj
+    return this
+  }
+
+  /**
+   * Build a "simple" button (reply / call / reminder / cancelReminder /
+   * address) via the SIMPLE_BUTTON_TYPES registry. Each shortcut below
+   * delegates here.
+   *
+   * @param {keyof typeof SIMPLE_BUTTON_TYPES} kind
+   * @param {string} displayText
+   * @param {string} [id]      Auto-generated UUID when omitted.
+   * @param {object} [opts]    Extra params merged into buttonParamsJson.
+   */
+  simpleButton(kind, displayText, id, opts = {}) {
+    const name = SIMPLE_BUTTON_TYPES[kind]
+    if (!name) throw new TypeError(`unknown simple button kind: ${kind}`)
+    this._buttons.push({
+      name,
+      buttonParamsJson: JSON.stringify({ display_text: displayText, id, ...opts }),
+    })
+    return this
+  }
+
+  /** @param {string} displayText @param {string} [id] @param {object} [opts] */
+  reply(displayText, id, opts) {
+    return this.simpleButton('reply', displayText, id, opts)
+  }
+
+  /** @param {string} displayText @param {string} [id] @param {object} [opts] */
+  call(displayText, id, opts) {
+    return this.simpleButton('call', displayText, id, opts)
+  }
+
+  /** @param {string} displayText @param {string} [id] @param {object} [opts] */
+  reminder(displayText, id, opts) {
+    return this.simpleButton('reminder', displayText, id, opts)
+  }
+
+  /** @param {string} displayText @param {string} [id] @param {object} [opts] */
+  cancelReminder(displayText, id, opts) {
+    return this.simpleButton('cancelReminder', displayText, id, opts)
+  }
+
+  /** @param {string} displayText @param {string} [id] @param {object} [opts] */
+  address(displayText, id, opts) {
+    return this.simpleButton('address', displayText, id, opts)
+  }
+
+  /**
+   * @param {string} displayText
+   * @param {string} url
+   * @param {object} [opts]   { webview_interaction, ... }
+   */
+  url(displayText, url, opts = {}) {
+    this._buttons.push({
+      name: 'cta_url',
+      buttonParamsJson: JSON.stringify({
+        display_text: displayText,
+        url,
+        webview_interaction: opts.webview_interaction ?? false,
+        ...opts,
+      }),
+    })
+    return this
+  }
+
+  /**
+   * @param {string} displayText
+   * @param {string} copyCode
+   * @param {object} [opts]
+   */
+  copy(displayText, copyCode, opts = {}) {
+    this._buttons.push({
+      name: 'cta_copy',
+      buttonParamsJson: JSON.stringify({
+        display_text: displayText,
+        copy_code: copyCode,
+        ...opts,
+      }),
+    })
+    return this
+  }
+
+  /**
+   * Send-location button. No display text — the params object is opaque.
+   *
+   * @param {object} [opts]
+   */
+  location(opts = {}) {
+    this._buttons.push({
+      name: 'send_location',
+      buttonParamsJson: JSON.stringify(opts),
+    })
+    return this
+  }
+
+  /**
+   * Add a single-select button via a callback. The callback receives a
+   * {@link SelectionBuilder} so sections & rows can be composed without
+   * touching outer state.
+   *
+   * @example
+   *   button.selection('Menu', sel => sel
+   *     .section('Main', s => s.row('A', 'Sub A', 'desc', 'a_id').row('B', 'Sub B', 'desc', 'b_id'))
+   *     .section('Extras', s => s.row('C', 'Sub C', 'desc', 'c_id'))
+   *   )
+   *
+   * @param {string} title
+   * @param {(sel: SelectionBuilder) => void} builder
+   * @param {object} [extra]
+   */
+  selection(title, builder, extra = {}) {
+    const sel = new SelectionBuilder()
+    sel.title(title)
+    builder(sel)
+    const params = sel.build()
+    this._buttons.push({
+      ...extra,
+      name: 'single_select',
+      buttonParamsJson: JSON.stringify(params),
+    })
+    return this
+  }
+
+  /** Remove all configured buttons. */
+  clear() {
+    this._buttons = []
+    return this
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────
+
+  /**
+   * Build a proto-ready "card" object — useful when this button is being
+   * embedded inside a carousel card rather than sent standalone.
+   *
+   * @returns {Promise<object>}
+   */
+  async toCard() {
+    let mediaPayload = {}
+    if (this._data) {
+      try {
+        // Use Connection.uploadMedia — Layer 4 must not touch Baileys directly.
+        mediaPayload = await this.#conn.uploadMedia(this._data)
+      } catch (err) {
+        // Legacy code string-matched 'Invalid media type' — too brittle.
+        // We surface the original error but keep the raw `_data` as a
+        // fallback so a builder with a non-uploadable source still produces
+        // something usable.
+        if (err?.message?.includes('Invalid media type')) {
+          mediaPayload = this._data
+        } else {
+          throw err
+        }
+      }
+    }
+
+    return {
+      body: { text: this._body },
+      footer: { text: this._footer },
+      header: {
+        title: this._title,
+        subtitle: this._subtitle,
+        hasMediaAttachment: !!this._data,
+        ...(this._data ? mediaPayload : {}),
+      },
+      nativeFlowMessage: {
+        messageParamsJson: JSON.stringify(this._params),
+        buttons: this._buttons,
+      },
+    }
+  }
+
+  /**
+   * Build the full proto message object (without relaying).
+   *
+   * @param {string} jid
+   * @param {object} [opts]
+   * @returns {Promise<object>}
+   */
+  async build(jid, opts = {}) {
+    const card = await this.toCard()
+    return this.#conn.generateMessage(
+      jid,
+      {
+        ...this._extraPayload,
+        interactiveMessage: {
+          ...card,
+          contextInfo: this._contextInfo,
+        },
+      },
+      opts,
+    )
+  }
+
+  /**
+   * Build + relay via the interactive channel (with biz/native_flow nodes).
+   *
+   * @param {string} jid
+   * @param {object} [opts]
+   * @returns {Promise<object>}
+   */
+  async send(jid, opts = {}) {
+    const msg = await this.build(jid, opts)
+    await this.#conn.relayMessage(msg.key.remoteJid, msg.message, {
+      messageId: msg.key.id,
+      additionalNodes: opts.additionalNodes ?? createInteractiveNodes(),
+      ...opts,
+    })
+    return msg
+  }
+}
+
+export default ButtonBuilder