@kyyinfinite/lumina 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyyinfinite/lumina",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Lumina — Modern WhatsApp framework built on top of Baileys. Hide the protocol complexity, expose a fluent API.",
   "type": "module",
   "main": "./src/index.js",

package/src/builders/ai-rich.js

@@ -1,28 +1,3 @@
-/**
- * @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'
@@ -50,100 +25,54 @@ import { singleLayout, hscrollLayout, actionRowLayout } from '../proto/layouts.j
 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'))
@@ -151,16 +80,7 @@ export class AIRichBuilder {
     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
@@ -182,13 +102,6 @@ export class AIRichBuilder {
     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')
@@ -207,13 +120,6 @@ export class AIRichBuilder {
     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' })
@@ -230,18 +136,10 @@ export class AIRichBuilder {
     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, {
@@ -277,20 +175,11 @@ export class AIRichBuilder {
     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 ]',
@@ -323,7 +212,6 @@ export class AIRichBuilder {
               })
             }
           } catch {
-            // Swallow autofill failures — the video URL alone is still useful.
           }
         }
 
@@ -344,14 +232,6 @@ export class AIRichBuilder {
     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' })
@@ -376,12 +256,6 @@ export class AIRichBuilder {
     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]
@@ -439,12 +313,6 @@ export class AIRichBuilder {
     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]
@@ -483,12 +351,6 @@ export class AIRichBuilder {
     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]
@@ -552,12 +414,6 @@ export class AIRichBuilder {
     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 })
@@ -565,13 +421,6 @@ export class AIRichBuilder {
     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
 
@@ -602,14 +451,7 @@ export class AIRichBuilder {
     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,
@@ -628,13 +470,6 @@ export class AIRichBuilder {
     })
   }
 
-  /**
-   * 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)

package/src/builders/base.js

@@ -1,39 +1,6 @@
-/**
- * @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 ?? ''
@@ -43,33 +10,25 @@ export function applyContentFields(target, initial = {}) {
   target._extraPayload = initial.extraPayload ?? {}
 
   target.title = function (t) {
-    if (typeof t !== 'string') {
-      throw new ValidationError('title must be a string', { code: 'LUMINA_VALIDATION_TITLE' })
-    }
+    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' })
-    }
+    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' })
-    }
+    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' })
-    }
+    if (typeof t !== 'string') throw new ValidationError('footer must be a string', { code: 'LUMINA_VALIDATION_FOOTER' })
     target._footer = t
     return target
   }
@@ -89,12 +48,6 @@ export function applyContentFields(target, initial = {}) {
   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,

package/src/builders/button-v2.js

@@ -1,100 +1,45 @@
-/**
- * @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
+  #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,
-    })
+    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) {
@@ -106,18 +51,16 @@ export class ButtonV2Builder {
       }
     }
 
-    const fallback =
-      this._data ??
-      {
-        headerType: HeaderType.LOCATION_THUMBNAIL,
-        locationMessage: {
-          degreesLatitude: 0,
-          degreesLongitude: 0,
-          name: this._title,
-          address: this._subtitle,
-          jpegThumbnail,
-        },
-      }
+    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,
@@ -136,16 +79,8 @@ export class ButtonV2Builder {
     )
   }
 
-  /**
-   * 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')
-    }
+    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,