@kyyinfinite/lumina 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyyinfinite/lumina",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "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

@@ -12,13 +12,21 @@ import {
 import { singleLayout, hscrollLayout, actionRowLayout } from '../proto/layouts.js'
 import { assembleRichResponse } from '../proto/rich-response.js'
 import { MessageType, ImagineType, LayoutKind } from '../proto/enums.js'
+import { isRawSocket, socketToServices } from '../utils/socket-to-conn.js'
 
 export class AIRichBuilder {
   #conn
   #proto
   #media
 
+  /**
+   * @param {object} conn  Connection instance OR raw Baileys socket (legacy: new AIRich(socket))
+   */
   constructor(conn, proto, media) {
+    // ── Auto-detect raw socket (backward compat: new AIRich(socket)) ──────────
+    const services = isRawSocket(conn) ? socketToServices(conn) : null
+    if (services) { conn = services.conn; proto = services.proto; media = services.media }
+
     applyContentFields(this)
     this.#conn = conn
     this.#proto = proto
@@ -34,6 +42,8 @@ export class AIRichBuilder {
     this._quotedParticipant = undefined
   }
 
+  // ─── Flags ────────────────────────────────────────────────────────────────────
+
   forwarded(v = true) { this._forwarded = v; return this }
   notification(v) { this._notification = v; return this }
   includesUnifiedResponse(v = true) { this._includesUnifiedResponse = v; return this }
@@ -45,6 +55,8 @@ export class AIRichBuilder {
     return this
   }
 
+  // ─── Low-level section/submessage injection ───────────────────────────────────
+
   submessage(msg) {
     const items = Array.isArray(msg) ? msg : [msg]
     items.forEach((m) => ensureObjectOrArray(m, 'submessage'))
@@ -52,6 +64,30 @@ export class AIRichBuilder {
     return this
   }
 
+  /**
+   * Directly push a raw section object (or array of objects) into the sections list.
+   * Useful when you've built a section manually via proto helpers.
+   */
+  section(s) {
+    const items = Array.isArray(s) ? s : [s]
+    for (const item of items) {
+      if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+        throw new ValidationError('Section must be a plain object or array of plain objects', {
+          code: 'LUMINA_VALIDATION_SECTION',
+        })
+      }
+      this._sections.push(item)
+    }
+    return this
+  }
+
+  /** @deprecated use `.submessage()` */
+  addSubmessage(msg) { return this.submessage(msg) }
+  /** @deprecated use `.section()` */
+  addSection(s) { return this.section(s) }
+
+  // ─── Content builders ─────────────────────────────────────────────────────────
+
   async text(text, opts = {}) {
     ensureString(text, 'text')
     const { hyperlink = true, citation = true, latex = true } = opts
@@ -176,10 +212,10 @@ export class AIRichBuilder {
     const resolved = await Promise.all(
       list.map(async (item) => {
         const avatarSrc = item.profileIconUrl ?? item.profile_url ?? item.profile
-        const thumbSrc = item.thumbnailUrl ?? item.thumbnail
+        const thumbSrc  = item.thumbnailUrl ?? item.thumbnail
         const [avatar, thumbnail] = await Promise.all([
           avatarSrc ? this.#media.resolve(avatarSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
-          thumbSrc ? this.#media.resolve(thumbSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
+          thumbSrc  ? this.#media.resolve(thumbSrc,  { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
         ])
         return { ...item, avatar, thumbnail }
       }),
@@ -219,10 +255,10 @@ export class AIRichBuilder {
     this._submessages.push({ messageType: MessageType.TEXT, messageText: '[ CANNOT_LOAD_PRODUCT ]' })
     const products = await Promise.all(
       list.map(async (p) => {
-        const imgSrc = p.image_url ?? p.image
+        const imgSrc  = p.image_url ?? p.image
         const iconSrc = p.icon_url ?? p.icon
         const [imageUrl, iconUrl] = await Promise.all([
-          imgSrc ? this.#media.resolve(imgSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
+          imgSrc  ? this.#media.resolve(imgSrc,  { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
           iconSrc ? this.#media.resolve(iconSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
         ])
         return {
@@ -246,12 +282,12 @@ export class AIRichBuilder {
     const primitives = await Promise.all(
       list.map(async (p) => {
         const profileSrc = p.profile_picture_url ?? p.profile_url ?? p.profile
-        const thumbSrc = p.thumbnail_url ?? p.thumbnail
-        const footerSrc = p.footer_icon ?? p.icon
+        const thumbSrc   = p.thumbnail_url ?? p.thumbnail
+        const footerSrc  = p.footer_icon ?? p.icon
         const [profileUrl, thumbUrl, footerIcon] = await Promise.all([
           profileSrc ? this.#media.resolve(profileSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
-          thumbSrc ? this.#media.resolve(thumbSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
-          footerSrc ? this.#media.resolve(footerSrc, { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
+          thumbSrc   ? this.#media.resolve(thumbSrc,   { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
+          footerSrc  ? this.#media.resolve(footerSrc,  { mediaType: 'image', strategy: 'auto' }) : Promise.resolve(''),
         ])
         return postPrimitive({
           title: p.title ?? '', subtitle: p.subtitle ?? '', username: p.username ?? '',
@@ -285,13 +321,10 @@ export class AIRichBuilder {
     }
     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 (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) {
@@ -302,6 +335,32 @@ export class AIRichBuilder {
     return this
   }
 
+  // ─── Legacy add* aliases (paste / AIRich API) ─────────────────────────────────
+  /** @deprecated use `.text()` */
+  async addText(text, opts)               { return this.text(text, opts) }
+  /** @deprecated use `.code()` */
+  async addCode(language, code)           { return this.code(language, code) }
+  /** @deprecated use `.table()` */
+  async addTable(table, opts)             { return this.table(table, opts) }
+  /** @deprecated use `.image()` */
+  async addImage(source, opts)            { return this.image(source, opts) }
+  /** @deprecated use `.video()` */
+  async addVideo(source, opts)            { return this.video(source, opts) }
+  /** @deprecated use `.source()` */
+  async addSource(sources)               { return this.source(sources) }
+  /** @deprecated use `.reels()` */
+  async addReels(items)                  { return this.reels(items) }
+  /** @deprecated use `.product()` */
+  async addProduct(item)                 { return this.product(item) }
+  /** @deprecated use `.post()` */
+  async addPost(item)                    { return this.post(item) }
+  /** @deprecated use `.tip()` */
+  async addTip(text)                     { return this.tip(text) }
+  /** @deprecated use `.suggest()` */
+  async addSuggest(suggestion, opts)     { return this.suggest(suggestion, opts) }
+
+  // ─── Build & send ─────────────────────────────────────────────────────────────
+
   async build(opts = {}) {
     return assembleRichResponse({
       title: this._title,

package/src/builders/base.js

@@ -45,15 +45,24 @@ export function applyContentFields(target, initial = {}) {
     return target
   }
 
+  // ─── Legacy aliases (paste / BaseBuilder API) ───────────────────────────────
+  target.setTitle     = target.title
+  target.setSubtitle  = target.subtitle
+  target.setBody      = target.body
+  target.setFooter    = target.footer
+  target.setContextInfo = target.contextInfo
+  /** @deprecated use `.payload()` */
+  target.addPayload   = target.payload
+
   return target
 }
 
 export function readContentFields(target) {
   return {
-    title: target._title,
-    subtitle: target._subtitle,
-    body: target._body,
-    footer: target._footer,
+    title:       target._title,
+    subtitle:    target._subtitle,
+    body:        target._body,
+    footer:      target._footer,
     contextInfo: target._contextInfo,
     extraPayload: target._extraPayload,
   }

package/src/builders/button-v2.js

@@ -1,13 +1,23 @@
 import { applyContentFields } from './base.js'
-import { coerceMediaSource, ensurePlainObject } from '../utils/validator.js'
+import { 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'
+import { isRawSocket, socketToServices } from '../utils/socket-to-conn.js'
 
 export class ButtonV2Builder {
+  #conn
+
+  /**
+   * @param {object} conn  Connection instance OR raw Baileys socket (legacy)
+   */
   constructor(conn) {
+    // ── Auto-detect raw socket (backward compat: new ButtonV2(socket)) ─────────
+    const services = isRawSocket(conn) ? socketToServices(conn) : null
+    if (services) conn = services.conn
+
     applyContentFields(this)
     this.#conn = conn
     this._buttons = []
@@ -15,8 +25,6 @@ export class ButtonV2Builder {
     this._data = null
   }
 
-  #conn
-
   button(displayText, id = uuid()) {
     this._buttons.push({ buttonId: id, buttonText: { displayText }, type: 1 })
     return this
@@ -40,6 +48,16 @@ export class ButtonV2Builder {
     return this
   }
 
+  // ─── Legacy aliases (paste / ButtonV2 API) ───────────────────────────────────
+  /** @deprecated use `.button()` */
+  addButton(displayText, id = uuid()) { return this.button(displayText, id) }
+  /** @deprecated use `.rawButton()` */
+  addRawButton(obj)                   { return this.rawButton(obj) }
+  /** @deprecated use `.thumbnail()` */
+  setThumbnail(source)                { return this.thumbnail(source) }
+  /** @deprecated use `.media()` */
+  setMedia(obj)                       { return this.media(obj) }
+
   async build(jid, opts = {}) {
     let jpegThumbnail = null
     if (this._thumbnailSource) {

package/src/builders/button.js

@@ -2,6 +2,7 @@ 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'
+import { isRawSocket, socketToServices } from '../utils/socket-to-conn.js'
 
 class SelectionBuilder {
   constructor() {
@@ -9,10 +10,7 @@ class SelectionBuilder {
     this._sections = []
   }
 
-  title(t) {
-    this._title = t
-    return this
-  }
+  title(t) { this._title = t; return this }
 
   section(title, builder) {
     const section = { title, highlight_label: '', rows: [] }
@@ -27,10 +25,7 @@ class SelectionBuilder {
 }
 
 class SectionBuilder {
-  constructor(rowsRef) {
-    this._rows = rowsRef
-  }
-
+  constructor(rowsRef) { this._rows = rowsRef }
   row(header, title, description, id) {
     this._rows.push({ header, title, description, id })
     return this
@@ -38,7 +33,18 @@ class SectionBuilder {
 }
 
 export class ButtonBuilder {
+  #conn
+  #proto
+  #media
+
+  /**
+   * @param {object} conn  Connection instance OR raw Baileys socket (legacy)
+   */
   constructor(conn, proto, media) {
+    // ── Auto-detect raw socket (backward compat: new Button(socket)) ──────────
+    const services = isRawSocket(conn) ? socketToServices(conn) : null
+    if (services) { conn = services.conn; proto = services.proto; media = services.media }
+
     applyContentFields(this)
     this.#conn = conn
     this.#proto = proto
@@ -46,11 +52,12 @@ export class ButtonBuilder {
     this._buttons = []
     this._data = null
     this._params = {}
+    // For legacy makeRow / makeSection support
+    this._currentSelectionIndex = -1
+    this._currentSectionIndex = -1
   }
 
-  #conn
-  #proto
-  #media
+  // ─── Media setters ───────────────────────────────────────────────────────────
 
   media(type, source, opts = {}) {
     if (!['image', 'video', 'document'].includes(type)) {
@@ -61,10 +68,44 @@ export class ButtonBuilder {
     return this
   }
 
-  image(source, opts) { return this.media('image', source, opts) }
-  video(source, opts) { return this.media('video', 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) }
 
+  /** @deprecated use `.media(obj)` – raw object form */
+  setMedia(obj) {
+    ensurePlainObject(obj, 'media')
+    this._data = obj
+    return this
+  }
+
+  // ── Legacy set* shims (image / video / document with url-or-buffer) ──────────
+  setImage(path, opts = {}) {
+    if (!path) throw new Error('Url or buffer needed')
+    this._data = Buffer.isBuffer(path) ? { image: path, ...opts } : { image: { url: path }, ...opts }
+    return this
+  }
+
+  setVideo(path, opts = {}) {
+    if (!path) throw new Error('Url or buffer needed')
+    this._data = Buffer.isBuffer(path) ? { video: path, ...opts } : { video: { url: path }, ...opts }
+    return this
+  }
+
+  setDocument(path, opts = {}) {
+    if (!path) throw new Error('Url or buffer needed')
+    this._data = Buffer.isBuffer(path) ? { document: path, ...opts } : { document: { url: path }, ...opts }
+    return this
+  }
+
+  // ─── Params / params ─────────────────────────────────────────────────────────
+
+  params(obj) { ensurePlainObject(obj, 'params'); this._params = obj; return this }
+  /** @deprecated use `.params()` */
+  setParams(obj) { return this.params(obj) }
+
+  // ─── Raw button ──────────────────────────────────────────────────────────────
+
   button(name, params, extra = {}) {
     this._buttons.push({
       name,
@@ -74,27 +115,34 @@ export class ButtonBuilder {
     return this
   }
 
-  params(obj) {
-    ensurePlainObject(obj, 'params')
-    this._params = obj
-    return this
-  }
+  /** @deprecated use `.button()` */
+  addButton(name, params) { return this.button(name, params) }
+
+  // ─── Simple buttons ──────────────────────────────────────────────────────────
 
   simpleButton(kind, displayText, id, opts = {}) {
     const name = SimpleButtonType[kind]
     if (!name) throw new TypeError(`unknown simple button kind: ${kind}`)
-    this._buttons.push({
-      name,
-      buttonParamsJson: JSON.stringify({ display_text: displayText, id, ...opts }),
-    })
+    this._buttons.push({ name, buttonParamsJson: JSON.stringify({ display_text: displayText, id, ...opts }) })
     return this
   }
 
-  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) }
+  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) }
+
+  /** @deprecated use `.reply()` */
+  addReply(displayText, id, opts)          { return this.reply(displayText, id, opts) }
+  /** @deprecated use `.call()` */
+  addCall(displayText, id, opts)           { return this.call(displayText, id, opts) }
+  /** @deprecated use `.reminder()` */
+  addReminder(displayText, id, opts)       { return this.reminder(displayText, id, opts) }
+  /** @deprecated use `.cancelReminder()` */
+  addCancelReminder(displayText, id, opts) { return this.cancelReminder(displayText, id, opts) }
+  /** @deprecated use `.address()` */
+  addAddress(displayText, id, opts)        { return this.address(displayText, id, opts) }
 
   url(displayText, url, opts = {}) {
     this._buttons.push({
@@ -122,6 +170,19 @@ export class ButtonBuilder {
     return this
   }
 
+  /** @deprecated use `.url()` */
+  addUrl(displayText, url, webview_interaction = false, opts = {}) {
+    return this.url(displayText, url, { webview_interaction, ...opts })
+  }
+
+  /** @deprecated use `.copy()` */
+  addCopy(displayText, copyCode, opts = {}) { return this.copy(displayText, copyCode, opts) }
+
+  /** @deprecated use `.location()` */
+  addLocation(opts = {}) { return this.location(opts) }
+
+  // ─── Selection (new fluent builder API) ──────────────────────────────────────
+
   selection(title, builder, extra = {}) {
     const sel = new SelectionBuilder()
     sel.title(title)
@@ -130,11 +191,57 @@ export class ButtonBuilder {
     return this
   }
 
-  clear() {
-    this._buttons = []
+  // ─── Legacy selection API (paste compatible) ──────────────────────────────────
+  // addSelection() / makeSection() / makeRow() use mutable cursor state
+
+  /**
+   * @deprecated Prefer `.selection(title, cb)` builder style.
+   * Adds a single_select button and sets cursor for makeSection/makeRow.
+   */
+  addSelection(title, options = {}) {
+    this._buttons.push({
+      ...options,
+      name: 'single_select',
+      buttonParamsJson: JSON.stringify({ title, sections: [] }),
+    })
+    this._currentSelectionIndex = this._buttons.length - 1
+    this._currentSectionIndex = -1
     return this
   }
 
+  /**
+   * @deprecated Append a section to the current selection (cursor must be set by addSelection).
+   */
+  makeSection(title = '', highlight_label = '') {
+    if (this._currentSelectionIndex === -1) throw new Error('You need to create a selection first')
+    const params = JSON.parse(this._buttons[this._currentSelectionIndex].buttonParamsJson)
+    params.sections.push({ title, highlight_label, rows: [] })
+    this._currentSectionIndex = params.sections.length - 1
+    this._buttons[this._currentSelectionIndex].buttonParamsJson = JSON.stringify(params)
+    return this
+  }
+
+  /**
+   * @deprecated Append a row to the current section.
+   */
+  makeRow(header = '', title = '', description = '', id = '') {
+    if (this._currentSelectionIndex === -1 || this._currentSectionIndex === -1) {
+      throw new Error('You need to create a selection and a section first')
+    }
+    const params = JSON.parse(this._buttons[this._currentSelectionIndex].buttonParamsJson)
+    params.sections[this._currentSectionIndex].rows.push({ header, title, description, id })
+    this._buttons[this._currentSelectionIndex].buttonParamsJson = JSON.stringify(params)
+    return this
+  }
+
+  // ─── Utility ─────────────────────────────────────────────────────────────────
+
+  clear() { this._buttons = []; return this }
+  /** @deprecated use `.clear()` */
+  clearButtons() { return this.clear() }
+
+  // ─── Build & send ─────────────────────────────────────────────────────────────
+
   async toCard() {
     let mediaPayload = {}
     if (this._data) {

package/src/builders/carousel.js

@@ -1,9 +1,21 @@
 import { applyContentFields } from './base.js'
 import { createInteractiveNodes } from '../proto/relay-nodes.js'
 import { CardBuilder } from './card.js'
+import { isRawSocket, socketToServices } from '../utils/socket-to-conn.js'
 
 export class CarouselBuilder {
+  #conn
+  #proto
+  #media
+
+  /**
+   * @param {object} conn  Connection instance OR raw Baileys socket (legacy)
+   */
   constructor(conn, proto, media) {
+    // ── Auto-detect raw socket (backward compat: new Carousel(socket)) ─────────
+    const services = isRawSocket(conn) ? socketToServices(conn) : null
+    if (services) { conn = services.conn; proto = services.proto; media = services.media }
+
     applyContentFields(this, { body: '', footer: '' })
     this.#conn = conn
     this.#proto = proto
@@ -11,10 +23,6 @@ export class CarouselBuilder {
     this._cards = []
   }
 
-  #conn
-  #proto
-  #media
-
   newCard() {
     return new CardBuilder(this.#conn)
   }
@@ -30,9 +38,10 @@ export class CarouselBuilder {
     return this
   }
 
-  cards(...cards) {
-    return this.card(cards.flat())
-  }
+  cards(...cards) { return this.card(cards.flat()) }
+
+  /** @deprecated use `.card()` */
+  addCard(card) { return this.card(card) }
 
   async build(jid, opts = {}) {
     return this.#conn.generateMessage(

package/src/builders/index.js

@@ -5,3 +5,9 @@ export { CardBuilder } from './card.js'
 export { AIRichBuilder } from './ai-rich.js'
 export { StickerBuilder } from './sticker.js'
 export { applyContentFields, readContentFields } from './base.js'
+
+// Legacy aliases
+export { ButtonBuilder as Button }    from './button.js'
+export { ButtonV2Builder as ButtonV2 } from './button-v2.js'
+export { CarouselBuilder as Carousel } from './carousel.js'
+export { AIRichBuilder as AIRich }    from './ai-rich.js'

package/src/compat/toolkit.js

@@ -0,0 +1,145 @@
+/**
+ * Toolkit — backward-compatibility shim matching the original monolithic library's
+ * static helper class. All methods delegate to the modular Lumina internals.
+ *
+ * Usage (legacy):
+ *   import { Toolkit } from '@kyyinfinite/lumina'
+ *   const url = await Toolkit.toUrl(sock, buffer, 'image')
+ */
+import { extractInlineEntities } from '../parsers/inline-entity.js'
+import { resize as _resize } from '../media/image.js'
+import { resolveDeep } from '../utils/promise.js'
+import { fetchBuffer as _fetchBuffer } from '../media/fetch.js'
+import { getMp4Duration as _getMp4Duration, extractThumbnail as _extractThumbnail } from '../media/video.js'
+import { isRawSocket, socketToServices } from '../utils/socket-to-conn.js'
+import { resolveMedia as _resolveMedia } from '../media/resolver.js'
+import { uploadToWhatsApp } from '../media/uploader.js'
+
+function getConn(client) {
+  if (isRawSocket(client)) return socketToServices(client).conn
+  return client // already a Connection
+}
+
+export class Toolkit {
+  // ─── Inline entity extraction ──────────────────────────────────────────────
+  /**
+   * Extract hyperlinks / citations / latex from markdown-like text.
+   * Returns the same shape as the original: { text, ie, inline_entities }
+   */
+  static extractIE(text, opts = {}) {
+    const { text: rewritten, entities, metadata } = extractInlineEntities(text, opts)
+    return { text: rewritten, ie: entities, inline_entities: metadata }
+  }
+
+  // ─── Image ────────────────────────────────────────────────────────────────
+  /**
+   * Resize a buffer to (x, y) using sharp.
+   * @param {Buffer} buffer
+   * @param {number} x  width
+   * @param {number} y  height
+   * @param {string} [fit='cover']
+   */
+  static async resize(buffer, x, y, fit = 'cover') {
+    return _resize(buffer, { width: x, height: y, fit, format: 'png' })
+  }
+
+  // ─── Promise utility ──────────────────────────────────────────────────────
+  /**
+   * Recursively resolve all Promises inside a nested object / array.
+   */
+  static async waitAllPromises(input) {
+    return resolveDeep(input)
+  }
+
+  // ─── Fetch ────────────────────────────────────────────────────────────────
+  /**
+   * Download a URL and return a Buffer. Returns Buffer.alloc(0) on error when silent=true.
+   * @param {string} url
+   * @param {object} [options]  fetch options
+   * @param {object} [meta]
+   * @param {boolean} [meta.silent=true]
+   */
+  static async fetchBuffer(url, options = {}, { silent = true } = {}) {
+    return _fetchBuffer(url, { ...options, silent })
+  }
+
+  // ─── Media upload ─────────────────────────────────────────────────────────
+  /**
+   * Upload a buffer / URL to WhatsApp servers and return the CDN URL.
+   * @param {object} _client  Raw Baileys socket or Connection
+   * @param {Buffer|string} path  Buffer or local/remote URL
+   * @param {string} [mediaType='document']
+   */
+  static async toUrl(_client, path, mediaType = 'document') {
+    if (!path) throw new Error('Url or buffer needed')
+    const conn = getConn(_client)
+    const source = Buffer.isBuffer(path) ? path : { url: path }
+    return uploadToWhatsApp(conn, source, mediaType)
+  }
+
+  // ─── Media resolver ───────────────────────────────────────────────────────
+  /**
+   * Resolve media to a URL, Buffer, or base64 string.
+   * @param {object} _client   Raw Baileys socket or Connection
+   * @param {Buffer|string|Array} media
+   * @param {string} [mediaType='image']
+   * @param {object} [opts]
+   * @param {boolean} [opts.resolveUrl=false]
+   * @param {boolean} [opts.resolveWAUrl=false]
+   * @param {'url'|'buffer'|'base64'} [opts.result='url']
+   * @param {boolean} [opts.resize=false]
+   * @param {number} [opts.width=300]
+   * @param {number} [opts.height=300]
+   */
+  static async resolveMedia(_client, media, mediaType = 'image', opts = {}) {
+    const { result = 'url', resize: doResize = false, width = 300, height = 300 } = opts
+    const conn = getConn(_client)
+
+    let strategy
+    if (result === 'buffer')  strategy = 'buffer'
+    else if (result === 'base64') strategy = 'base64'
+    else strategy = 'auto'
+
+    const resizeOpts = doResize ? { width, height, fit: 'cover' } : undefined
+
+    if (Array.isArray(media)) {
+      return Promise.all(
+        media.map((m) => _resolveMedia(conn, m, { mediaType, strategy, resize: resizeOpts }))
+      )
+    }
+
+    return _resolveMedia(conn, media, { mediaType, strategy, resize: resizeOpts })
+  }
+
+  // ─── Video ────────────────────────────────────────────────────────────────
+  /**
+   * Parse MP4 duration from a buffer (in seconds). Returns 0 on error when silent=true.
+   */
+  static getMp4Duration(buffer, { silent = true } = {}) {
+    return _getMp4Duration(buffer, { silent })
+  }
+
+  /**
+   * Extract a frame from an MP4 buffer as PNG.
+   * @param {Buffer} videoBuffer
+   * @param {object} [opts]
+   * @param {number} [opts.time]           Timestamp in seconds (default: 20% of duration)
+   * @param {'buffer'|'base64'} [opts.result='buffer']
+   * @param {boolean} [opts.resize=true]
+   * @param {number} [opts.width=300]
+   * @param {number} [opts.height=300]
+   * @param {boolean} [opts.silent=true]
+   */
+  static async getMp4Preview(videoBuffer, opts = {}) {
+    const {
+      time, result = 'buffer', resize: doResize = true,
+      width = 300, height = 300, silent = true,
+    } = opts
+    return _extractThumbnail(videoBuffer, {
+      time, result,
+      resizeOutput: doResize, width, height, silent,
+    })
+  }
+}
+
+export default Toolkit

package/src/index.js

@@ -29,9 +29,12 @@ import {
 import { singleLayout, hscrollLayout, actionRowLayout, layoutFor } from './proto/layouts.js'
 import { LuminaError, ValidationError, MediaError, ProtoError, ConnectionError, ProtocolError } from './errors.js'
 import { createLogger } from './utils/logger.js'
+import { Toolkit } from './compat/toolkit.js'
 
 export const VERSION = '1.0.0'
 
+// ─── Primary exports ──────────────────────────────────────────────────────────
+
 export {
   Bot, Connection,
   ButtonBuilder, ButtonV2Builder, CarouselBuilder, CardBuilder, AIRichBuilder, StickerBuilder,
@@ -49,6 +52,21 @@ export {
   singleLayout, hscrollLayout, actionRowLayout, layoutFor,
   LuminaError, ValidationError, MediaError, ProtoError, ConnectionError, ProtocolError,
   createLogger,
+  Toolkit,
 }
 
+// ─── Legacy class-name aliases (paste / monolithic library API) ───────────────
+// Allows code written for the original format to work without changes:
+//   import { AIRich, Button, ButtonV2, Carousel } from '@kyyinfinite/lumina'
+//   new AIRich(sock), new Button(sock), etc.
+
+/** @deprecated Use AIRichBuilder */
+export const AIRich   = AIRichBuilder
+/** @deprecated Use ButtonBuilder */
+export const Button   = ButtonBuilder
+/** @deprecated Use ButtonV2Builder */
+export const ButtonV2 = ButtonV2Builder
+/** @deprecated Use CarouselBuilder */
+export const Carousel = CarouselBuilder
+
 export default Bot

package/src/utils/socket-to-conn.js

@@ -0,0 +1,41 @@
+import { Connection } from '../client/connection.js'
+import { MediaService } from '../services/media-service.js'
+import { ProtoService } from '../services/proto-service.js'
+
+/**
+ * JID used by the original monolithic library for media uploads.
+ * Kept as default so legacy code (new AIRich(socket)) works without extra config.
+ */
+const DEFAULT_UPLOAD_JID = '@newsletter'
+
+/**
+ * Check whether `v` looks like a raw Baileys socket (has relayMessage + ev).
+ */
+export function isRawSocket(v) {
+  return (
+    v != null &&
+    typeof v === 'object' &&
+    typeof v.relayMessage === 'function' &&
+    v.ev != null
+  )
+}
+
+/**
+ * Wrap a raw Baileys socket into the three service objects that Lumina builders expect.
+ * Returns null if `socketOrConn` is already a Connection (not a raw socket).
+ *
+ * @param {object} socketOrConn  Raw Baileys socket or existing Connection
+ * @param {object} [opts]
+ * @param {string} [opts.uploadJid]  JID used for media upload (defaults to @newsletter)
+ * @returns {{ conn: Connection, media: MediaService, proto: ProtoService } | null}
+ */
+export function socketToServices(socketOrConn, opts = {}) {
+  if (!isRawSocket(socketOrConn)) return null
+  const uploadJid = opts.uploadJid ?? DEFAULT_UPLOAD_JID
+  const conn = new Connection(socketOrConn, { uploadJid })
+  const media = new MediaService(conn, { uploadJid })
+  const proto = new ProtoService(conn)
+  return { conn, media, proto }
+}
+
+export default { isRawSocket, socketToServices }