@kyyinfinite/lumina 1.0.0

package/src/builders/card.js

@@ -0,0 +1,168 @@
+/**
+ * @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 { 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 ──────────────────────────────────────────────────────────
+
+  /**
+   * @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}`)
+    }
+    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 ────────────────────────────────────────────────────────
+
+  params(obj) {
+    ensurePlainObject(obj, 'params')
+    this._params = obj
+    return this
+  }
+
+  button(name, params, extra = {}) {
+    this._buttons.push({
+      name,
+      buttonParamsJson: typeof params === 'string' ? params : JSON.stringify(params),
+      ...extra,
+    })
+    return this
+  }
+
+  reply(displayText, id = uuid(), opts = {}) {
+    this._buttons.push({
+      name: SIMPLE_BUTTON_TYPES.reply,
+      buttonParamsJson: JSON.stringify({ display_text: displayText, id, ...opts }),
+    })
+    return this
+  }
+
+  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
+  }
+
+  copy(displayText, copyCode, opts = {}) {
+    this._buttons.push({
+      name: 'cta_copy',
+      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
+        }
+      }
+    }
+
+    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,
+      },
+    }
+  }
+}
+
+export default CardBuilder

package/src/builders/carousel.js

@@ -0,0 +1,122 @@
+/**
+ * @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
+
+  /**
+   * 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()) {
+      if (!c?.header?.hasMediaAttachment) {
+        throw new Error(`Card [${this._cards.length + i}] must include an image or video in header`)
+      }
+    }
+    this._cards.push(...cards)
+    return this
+  }
+
+  /**
+   * Variadic alias for {@link card}.
+   *
+   * @param  {...object} cards
+   */
+  cards(...cards) {
+    return this.card(cards)
+  }
+
+  /**
+   * 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,
+      {
+        ...this._extraPayload,
+        interactiveMessage: {
+          header: { hasMediaAttachment: false },
+          body: { text: this._body },
+          footer: { text: this._footer },
+          contextInfo: this._contextInfo,
+          carouselMessage: { cards: this._cards },
+        },
+      },
+      opts,
+    )
+  }
+
+  /**
+   * 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, {
+      messageId: msg.key.id,
+      additionalNodes: opts.additionalNodes ?? createInteractiveNodes(),
+      ...opts,
+    })
+    return msg
+  }
+}
+
+export default CarouselBuilder

package/src/builders/index.d.ts

@@ -0,0 +1 @@
+export * from '../index.d.ts'

package/src/builders/index.js

@@ -0,0 +1,13 @@
+/**
+ * @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'
+export { CardBuilder } from './card.js'
+export { AIRichBuilder } from './ai-rich.js'
+export { applyContentFields, readContentFields } from './base.js'

package/src/client/bot.js

@@ -0,0 +1,192 @@
+/**
+ * @file client/bot.js
+ * @module lumina/client/bot
+ *
+ * Bot — primary entry point. Wraps a Baileys socket, exposes a fluent,
+ * verb-first API, and provides factory methods for every builder.
+ *
+ *   const bot = new Bot(socket)
+ *   await bot.text(jid, 'Halo')
+ *   await bot.button().title('T').body('B').reply('OK').send(jid)
+ *   await bot.ai().text('hi').code('js', 'console.log(1)').send(jid)
+ */
+
+import { Connection } from './connection.js'
+import { MediaService } from '../services/media-service.js'
+import { ProtoService } from '../services/proto-service.js'
+import { MessageService } from '../services/message-service.js'
+
+import { ButtonBuilder } from '../builders/button.js'
+import { ButtonV2Builder } from '../builders/button-v2.js'
+import { CarouselBuilder } from '../builders/carousel.js'
+import { AIRichBuilder } from '../builders/ai-rich.js'
+
+import { extractInlineEntities, tokenizeCode, toTableMetadata } from '../parsers/index.js'
+import { createLogger } from '../utils/logger.js'
+
+/** @typedef {import('@whiskeysockets/baileys').WASocket} WASocket */
+/** @typedef {import('../utils/logger.js').Logger} Logger */
+
+/**
+ * @typedef {object} BotOptions
+ * @property {string} [uploadJid]               Pre-upload JID for media uploads.
+ * @property {Logger} [logger]                  Custom logger.
+ * @property {boolean} [mediaCache=true]        Enable MediaService URL cache.
+ * @property {string} [uploadJidDefault]        Alias for uploadJid.
+ */
+
+export class Bot {
+  /**
+   * @param {WASocket} socket
+   * @param {BotOptions} [opts]
+   */
+  constructor(socket, opts = {}) {
+    this.logger = opts.logger ?? createLogger({ level: 'warn' })
+
+    this.connection = new Connection(socket, {
+      uploadJid: opts.uploadJid ?? opts.uploadJidDefault,
+      logger: this.logger,
+    })
+
+    this.media = new MediaService(this.connection, {
+      logger: this.logger,
+      uploadJid: opts.uploadJid,
+      cache: opts.mediaCache ?? true,
+    })
+
+    this.proto = new ProtoService(this.connection)
+    this.message = new MessageService(this.connection, this.proto, this.media)
+
+    // Expose util facade as a property — bot.util.extractInlineEntities(text)
+    this.util = {
+      extractInlineEntities,
+      tokenizeCode,
+      toTableMetadata,
+    }
+  }
+
+  // ─── Basic senders ─────────────────────────────────────────────────
+
+  /** @param {string} jid @param {string} text @param {object} [opts] */
+  text(jid, text, opts) {
+    return this.message.text(jid, text, opts)
+  }
+
+  /** @param {string} jid @param {string | Buffer} source @param {string} [caption] @param {object} [opts] */
+  image(jid, source, caption, opts) {
+    return this.message.image(jid, source, caption, opts)
+  }
+
+  /** @param {string} jid @param {string | Buffer} source @param {string} [caption] @param {object} [opts] */
+  video(jid, source, caption, opts) {
+    return this.message.video(jid, source, caption, opts)
+  }
+
+  /** @param {string} jid @param {string | Buffer} source @param {object} [opts] */
+  audio(jid, source, opts) {
+    return this.message.audio(jid, source, opts)
+  }
+
+  /** @param {string} jid @param {string | Buffer} source @param {object} [opts] */
+  document(jid, source, opts) {
+    return this.message.document(jid, source, opts)
+  }
+
+  /** @param {string} jid @param {string | Buffer} source @param {object} [opts] */
+  sticker(jid, source, opts) {
+    return this.message.sticker(jid, source, opts)
+  }
+
+  /** @param {string} jid @param {Array} contacts @param {object} [opts] */
+  contact(jid, contacts, opts) {
+    return this.message.contact(jid, contacts, opts)
+  }
+
+  /** @param {string} jid @param {number} lat @param {number} lng @param {object} [opts] */
+  location(jid, lat, lng, opts) {
+    return this.message.location(jid, lat, lng, opts)
+  }
+
+  /** @param {string} jid @param {string} name @param {string[]} options @param {object} [opts] */
+  poll(jid, name, options, opts) {
+    return this.message.poll(jid, name, options, opts)
+  }
+
+  /** @param {string} jid @param {string} text @param {object} quoted @param {object} [opts] */
+  reply(jid, text, quoted, opts) {
+    return this.message.reply(jid, text, quoted, opts)
+  }
+
+  /** @param {string} jid @param {object} key @param {string} emoji @param {object} [opts] */
+  react(jid, key, emoji, opts) {
+    return this.message.react(jid, key, emoji, opts)
+  }
+
+  /** @param {string} jid @param {object} key */
+  delete(jid, key) {
+    return this.message.delete(jid, key)
+  }
+
+  /** @param {string} jid @param {object} message @param {object} [opts] */
+  forward(jid, message, opts) {
+    return this.message.forward(jid, message, opts)
+  }
+
+  /** @param {string} jid @param {object} message @param {object} [opts] */
+  copy(jid, message, opts) {
+    return this.message.copy(jid, message, opts)
+  }
+
+  /** @param {string} jid @param {object} key @param {string} newText @param {object} [opts] */
+  edit(jid, key, newText, opts) {
+    return this.message.edit(jid, key, newText, opts)
+  }
+
+  // ─── Builder factories ─────────────────────────────────────────────
+
+  /** @returns {ButtonBuilder} */
+  button() {
+    return new ButtonBuilder(this.connection, this.proto, this.media)
+  }
+
+  /** @returns {ButtonV2Builder} */
+  buttonV2() {
+    return new ButtonV2Builder(this.connection)
+  }
+
+  /** @returns {CarouselBuilder} */
+  carousel() {
+    return new CarouselBuilder(this.connection, this.proto, this.media)
+  }
+
+  /** @returns {AIRichBuilder} */
+  ai() {
+    return new AIRichBuilder(this.connection, this.proto, this.media)
+  }
+
+  // ─── Event bus ─────────────────────────────────────────────────────
+
+  /** @param {string} event @param {(...a: any[]) => void} handler @returns {() => void} */
+  on(event, handler) {
+    return this.connection.on(event, handler)
+  }
+
+  /** @param {string} event @param {(...a: any[]) => void} handler @returns {() => void} */
+  once(event, handler) {
+    return this.connection.once(event, handler)
+  }
+
+  /** @param {string} event @param {(...a: any[]) => void} handler */
+  off(event, handler) {
+    this.connection.off(event, handler)
+  }
+
+  // ─── Raw escape ────────────────────────────────────────────────────
+
+  /** @returns {WASocket} */
+  get raw() {
+    return this.connection.raw
+  }
+}
+
+export default Bot

package/src/client/connection.js

@@ -0,0 +1,180 @@
+/**
+ * @file connection.js
+ * @module lumina/client/connection
+ *
+ * Connection — Baileys socket adapter. This is the ONLY module in the whole
+ * framework that knows about Baileys' raw API surface. Every other module
+ * talks to Baileys through one of the four ports Connection exposes:
+ *
+ *   - MediaPort     → uploadMedia
+ *   - GeneratePort  → generateMessage
+ *   - RelayPort     → relayMessage
+ *   - EventBus      → on / once / off
+ *
+ * If Baileys renames `relayMessage` to `sendRaw`, this is the only file
+ * that needs updating.
+ */
+
+import { ConnectionError } from '../errors.js'
+
+/** @typedef {import('@whiskeysockets/baileys').WASocket} WASocket */
+
+/**
+ * @typedef {object} ConnectionOptions
+ * @property {string} [uploadJid]   Default JID used for pre-uploading media.
+ * @property {import('../utils/logger.js').Logger} [logger]
+ */
+
+export class Connection {
+  /** @param {WASocket} socket */
+  /** @param {ConnectionOptions} [opts] */
+  constructor(socket, opts = {}) {
+    if (!socket) {
+      throw new ConnectionError('socket is required', { code: 'LUMINA_CONNECTION_NO_SOCKET' })
+    }
+    this.#socket = socket
+    this.uploadJid = opts.uploadJid
+    this.logger = opts.logger
+
+    // Verify the bare-minimum API surface we depend on.
+    const required = ['relayMessage', 'ev']
+    for (const m of required) {
+      if (typeof socket[m] === 'undefined') {
+        throw new ConnectionError(`socket is missing required field: ${m}`, {
+          code: 'LUMINA_CONNECTION_INCOMPATIBLE',
+        })
+      }
+    }
+  }
+
+  /** @type {WASocket | null} */
+  #socket = null
+
+  /**
+   * Upload media via Baileys' `prepareWAMessageMedia`. We lazy-import it so
+   * that the framework loads even if the user's Baileys version is older
+   * than the one we tested against.
+   *
+   * @param {object} media   `{ image: Buffer | { url } }` etc.
+   * @param {object} [opts]  `{ jid, ... }` forwarded to prepareWAMessageMedia.
+   * @returns {Promise<object>}
+   */
+  async uploadMedia(media, opts = {}) {
+    const { prepareWAMessageMedia } = await import('@whiskeysockets/baileys')
+    const jid = opts.jid ?? this.uploadJid
+    if (!jid) {
+      throw new ConnectionError('uploadJid must be set (via constructor or per-call)', {
+        code: 'LUMINA_CONNECTION_NO_UPLOAD_JID',
+      })
+    }
+    return prepareWAMessageMedia(media, {
+      upload: this.#socket.waUploadToServer,
+      jid,
+      ...opts,
+    })
+  }
+
+  /**
+   * Generate a WA message object from a content descriptor.
+   *
+   * @param {string} jid
+   * @param {object} content
+   * @param {object} [opts]
+   * @returns {Promise<object>}
+   */
+  async generateMessage(jid, content, opts = {}) {
+    const { generateWAMessageFromContent } = await import('@whiskeysockets/baileys')
+    return generateWAMessageFromContent(jid, content, opts)
+  }
+
+  /**
+   * Generate a poll message.
+   *
+   * @param {string} jid
+   * @param {object} opts  { name, values, selectableCount, toJid, messageSecret }
+   * @returns {Promise<object>}
+   */
+  async generatePoll(jid, opts) {
+    const { generatePollMessage } = await import('@whiskeysockets/baileys')
+    return generatePollMessage(jid, opts)
+  }
+
+  /**
+   * Generate a reaction message.
+   *
+   * @param {string} jid
+   * @param {object} opts  { key, text }
+   * @returns {Promise<object>}
+   */
+  async generateReaction(jid, opts) {
+    const { generateReactionMessage } = await import('@whiskeysockets/baileys')
+    return generateReactionMessage(jid, opts)
+  }
+
+  /**
+   * Relay a pre-built message via `relayMessage`. Returns the message ID.
+   *
+   * @param {string} jid
+   * @param {object} message
+   * @param {object} [opts]
+   * @returns {Promise<string>}
+   */
+  async relayMessage(jid, message, opts = {}) {
+    const messageId = opts.messageId ?? this.#socket.generateMessageTag()
+    await this.#socket.relayMessage(jid, message, {
+      messageId,
+      ...opts,
+    })
+    return messageId
+  }
+
+  /**
+   * Subscribe to a Baileys event. Returns an unsubscriber.
+   *
+   * @param {string} event
+   * @param {(...args: any[]) => void} handler
+   * @returns {() => void}
+   */
+  on(event, handler) {
+    this.#socket.ev.on(event, handler)
+    return () => this.#socket.ev.off(event, handler)
+  }
+
+  /**
+   * Subscribe once.
+   *
+   * @param {string} event
+   * @param {(...args: any[]) => void} handler
+   * @returns {() => void}
+   */
+  once(event, handler) {
+    const off = this.on(event, (...args) => {
+      off()
+      handler(...args)
+    })
+    return off
+  }
+
+  /**
+   * Unsubscribe.
+   *
+   * @param {string} event
+   * @param {(...args: any[]) => void} handler
+   */
+  off(event, handler) {
+    this.#socket.ev.off(event, handler)
+  }
+
+  /**
+   * Raw Baileys socket — escape hatch for advanced users. Use sparingly;
+   * any code that touches `raw` bypasses Lumina's contract and may break
+   * on Baileys upgrades.
+   *
+   * @returns {WASocket}
+   */
+  get raw() {
+    return this.#socket
+  }
+}
+
+export default Connection