@kyyinfinite/lumina 1.0.0 → 1.0.1

package/src/builders/button.js

@@ -1,95 +1,36 @@
-/**
- * @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'
+import { SimpleButtonType } 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 */
-
-/**
- * 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)
+    builder(new SectionBuilder(section.rows))
     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
@@ -97,40 +38,20 @@ class SectionBuilder {
 }
 
 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 ──────────────────────────────────────────────────────────
+  #conn
+  #proto
+  #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}`)
@@ -140,31 +61,10 @@ export class ButtonBuilder {
     return this
   }
 
-  /** @param {string | Buffer} source */
-  image(source, opts) {
-    return this.media('image', source, opts)
-  }
+  image(source, opts) { return this.media('image', source, opts) }
+  video(source, opts) { return this.media('video', source, opts) }
+  document(source, opts) { return this.media('document', 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,
@@ -174,29 +74,14 @@ export class ButtonBuilder {
     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]
+    const name = SimpleButtonType[kind]
     if (!name) throw new TypeError(`unknown simple button kind: ${kind}`)
     this._buttons.push({
       name,
@@ -205,36 +90,12 @@ export class ButtonBuilder {
     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)
-  }
+  reply(displayText, id, opts) { return this.simpleButton('reply', displayText, id, opts) }
+  call(displayText, id, opts) { return this.simpleButton('call', displayText, id, opts) }
+  reminder(displayText, id, opts) { return this.simpleButton('reminder', displayText, id, opts) }
+  cancelReminder(displayText, id, opts) { return this.simpleButton('cancelReminder', displayText, id, 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',
@@ -248,97 +109,42 @@ export class ButtonBuilder {
     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,
-      }),
+      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),
-    })
+    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),
-    })
+    this._buttons.push({ ...extra, name: 'single_select', buttonParamsJson: JSON.stringify(sel.build()) })
     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
-        }
+        if (err?.message?.includes('Invalid media type')) mediaPayload = this._data
+        else throw err
       }
     }
-
     return {
       body: { text: this._body },
       footer: { text: this._footer },
@@ -355,35 +161,15 @@ export class ButtonBuilder {
     }
   }
 
-  /**
-   * 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,
-        },
-      },
+      { ...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, {

package/src/builders/card.js

@@ -1,57 +1,19 @@
-/**
- * @file builders/card.js
- * @module lumina/builders/card
- *
- * CardBuilder — composes a single carousel card. The legacy `Carousel` class
- * required the user to construct card objects manually (including calling
- * `prepareWAMessageMedia` themselves), which leaked the proto layer.
- *
- * CardBuilder is structurally identical to {@link ButtonBuilder} minus the
- * `send()` method — cards are not standalone messages, they're embedded
- * inside a carousel.
- */
-
 import { applyContentFields } from './base.js'
 import { coerceMediaSource, ensurePlainObject } from '../utils/validator.js'
+import { SimpleButtonType } from '../proto/enums.js'
 import { uuid } from '../utils/id.js'
 
-/** @typedef {import('../client/connection.js').Connection} Connection */
-
-/**
- * Registry of simple button types (same as ButtonBuilder, kept local so the
- * card module stays self-contained for tree-shaking).
- * @type {Record<string, string>}
- */
-const SIMPLE_BUTTON_TYPES = {
-  reply: 'quick_reply',
-  call: 'cta_call',
-  reminder: 'cta_reminder',
-  cancelReminder: 'cta_cancel_reminder',
-  address: 'address_message',
-}
-
 export class CardBuilder {
-  /** @param {Connection} conn */
   constructor(conn) {
     applyContentFields(this)
     this.#conn = conn
-    /** @type {Array<{ name: string, buttonParamsJson: string }>} */
     this._buttons = []
-    /** @type {object | null} */
     this._data = null
-    /** @type {object} */
     this._params = {}
   }
 
-  /** @type {Connection} */ #conn
-
-  // ─── Media ──────────────────────────────────────────────────────────
+  #conn
 
-  /**
-   * @param {'image'|'video'|'document'} type
-   * @param {string | Buffer | object} source
-   * @param {object} [opts]
-   */
   media(type, source, opts = {}) {
     if (!['image', 'video', 'document'].includes(type)) {
       throw new TypeError(`media type must be image | video | document, got: ${type}`)
@@ -61,22 +23,9 @@ export class CardBuilder {
     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 ────────────────────────────────────────────────────────
+  image(source, opts) { return this.media('image', source, opts) }
+  video(source, opts) { return this.media('video', source, opts) }
+  document(source, opts) { return this.media('document', source, opts) }
 
   params(obj) {
     ensurePlainObject(obj, 'params')
@@ -95,7 +44,7 @@ export class CardBuilder {
 
   reply(displayText, id = uuid(), opts = {}) {
     this._buttons.push({
-      name: SIMPLE_BUTTON_TYPES.reply,
+      name: SimpleButtonType.reply,
       buttonParamsJson: JSON.stringify({ display_text: displayText, id, ...opts }),
     })
     return this
@@ -117,37 +66,21 @@ export class CardBuilder {
   copy(displayText, copyCode, opts = {}) {
     this._buttons.push({
       name: 'cta_copy',
-      buttonParamsJson: JSON.stringify({
-        display_text: displayText,
-        copy_code: copyCode,
-        ...opts,
-      }),
+      buttonParamsJson: JSON.stringify({ display_text: displayText, copy_code: copyCode, ...opts }),
     })
     return this
   }
 
-  // ─── Lifecycle ──────────────────────────────────────────────────────
-
-  /**
-   * Build the proto-ready card object.
-   *
-   * @returns {Promise<object>}
-   */
   async build() {
     let mediaPayload = {}
     if (this._data) {
       try {
-        // Layer 4 must not touch Baileys directly — go through Connection.
         mediaPayload = await this.#conn.uploadMedia(this._data)
       } catch (err) {
-        if (err?.message?.includes('Invalid media type')) {
-          mediaPayload = this._data
-        } else {
-          throw err
-        }
+        if (err?.message?.includes('Invalid media type')) mediaPayload = this._data
+        else throw err
       }
     }
-
     return {
       body: { text: this._body },
       footer: { text: this._footer },

package/src/builders/carousel.js

@@ -1,62 +1,24 @@
-/**
- * @file builders/carousel.js
- * @module lumina/builders/carousel
- *
- * CarouselBuilder — composes a `carouselMessage` containing one or more
- * cards produced by {@link CardBuilder}.
- *
- * Bug fix vs legacy: the original `Carousel.send()` forgot to `await`
- * `build()`. Lumina's version is consistently async and awaits throughout.
- */
-
 import { applyContentFields } from './base.js'
 import { createInteractiveNodes } from '../proto/relay-nodes.js'
 import { CardBuilder } from './card.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 CarouselBuilder {
-  /**
-   * @param {Connection} conn
-   * @param {ProtoService} proto
-   * @param {MediaService} media
-   */
   constructor(conn, proto, media) {
     applyContentFields(this, { body: '', footer: '' })
     this.#conn = conn
     this.#proto = proto
     this.#media = media
-    /** @type {Array<object>} raw, already-built card objects */
     this._cards = []
   }
 
-  /** @type {Connection} */ #conn
-  /** @type {ProtoService} */ #proto
-  /** @type {MediaService} */ #media
+  #conn
+  #proto
+  #media
 
-  /**
-   * Create a fresh {@link CardBuilder} bound to this carousel's connection.
-   * User builds it inline, calls `.build()` on it, and passes the result
-   * back to {@link card}.
-   *
-   * @example
-   *   const card = await carousel.newCard()
-   *     .title('A').image('a.jpg').reply('Buy', 'buy_a').build()
-   *   carousel.card(card)
-   *
-   * @returns {CardBuilder}
-   */
   newCard() {
     return new CardBuilder(this.#conn)
   }
 
-  /**
-   * Append one or more pre-built cards.
-   *
-   * @param {object | object[]} card
-   */
   card(card) {
     const cards = Array.isArray(card) ? card : [card]
     for (const [i, c] of cards.entries()) {
@@ -68,22 +30,10 @@ export class CarouselBuilder {
     return this
   }
 
-  /**
-   * Variadic alias for {@link card}.
-   *
-   * @param  {...object} cards
-   */
   cards(...cards) {
-    return this.card(cards)
+    return this.card(cards.flat())
   }
 
-  /**
-   * Build the proto message object (without relaying).
-   *
-   * @param {string} jid
-   * @param {object} [opts]
-   * @returns {Promise<object>}
-   */
   async build(jid, opts = {}) {
     return this.#conn.generateMessage(
       jid,
@@ -101,13 +51,6 @@ export class CarouselBuilder {
     )
   }
 
-  /**
-   * Build + relay.
-   *
-   * @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, {

package/src/builders/index.js

@@ -1,10 +1,3 @@
-/**
- * @file builders/index.js
- * @module lumina/builders
- *
- * Barrel re-export for the builders layer.
- */
-
 export { ButtonBuilder } from './button.js'
 export { ButtonV2Builder } from './button-v2.js'
 export { CarouselBuilder } from './carousel.js'