@kyyinfinite/lumina 1.0.5 → 1.0.7

package/package.json

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

@@ -1,61 +1,53 @@
-
 import { applyContentFields } from './base.js'
 import { ensureObjectOrArray, ensureString, ensureStringArray } from '../utils/validator.js'
 import { ValidationError } from '../errors.js'
-
 import { extractInlineEntities } from '../parsers/inline-entity.js'
 import { tokenizeCode } from '../parsers/code-tokenizer.js'
 import { toTableMetadata } from '../parsers/table-metadata.js'
-
 import {
-  markdownTextPrimitive,
-  codePrimitive,
-  tablePrimitive,
-  searchResultPrimitive,
-  reelPrimitive,
-  imaginePrimitive,
-  productCardPrimitive,
-  postPrimitive,
-  metadataTextPrimitive,
-  followUpSuggestionPillPrimitive,
-  shapeSourceEntry,
-  shapeReelEntry,
+  markdownTextPrimitive, codePrimitive, tablePrimitive, searchResultPrimitive,
+  reelPrimitive, imaginePrimitive, productCardPrimitive, postPrimitive,
+  metadataTextPrimitive, followUpSuggestionPillPrimitive, shapeSourceEntry, shapeReelEntry,
 } from '../proto/primitives.js'
 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
     this.#media = media
-
     this._submessages = []
     this._sections = []
     this._richResponseSources = []
-
     this._forwarded = true
     this._notification = false
     this._includesUnifiedResponse = true
     this._includesSubmessages = true
-    this._quoted
-    this._quotedParticipant
+    this._quoted = undefined
+    this._quotedParticipant = undefined
   }
 
+  // ─── Flags ────────────────────────────────────────────────────────────────────
 
-
-  forwarded(v = true) {
-    this._forwarded = v
-    return this
-  }
-
-  notification(v) {
-    this._notification = v
-    return this
-  }
+  forwarded(v = true) { this._forwarded = v; return this }
+  notification(v) { this._notification = v; return this }
+  includesUnifiedResponse(v = true) { this._includesUnifiedResponse = v; return this }
+  includesSubmessages(v = true) { this._includesSubmessages = v; return this }
 
   quoted(quoted, quotedParticipant) {
     this._quoted = quoted
@@ -63,15 +55,7 @@ export class AIRichBuilder {
     return this
   }
 
-  includesUnifiedResponse(v = true) {
-    this._includesUnifiedResponse = v
-    return this
-  }
-
-  includesSubmessages(v = true) {
-    this._includesSubmessages = v
-    return this
-  }
+  // ─── Low-level section/submessage injection ───────────────────────────────────
 
   submessage(msg) {
     const items = Array.isArray(msg) ? msg : [msg]
@@ -80,42 +64,47 @@ 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
-
-    const { text: rewritten, metadata } = extractInlineEntities(text, {
-      hyperlink,
-      citation,
-      latex,
-    })
-
-    this._submessages.push({
-      messageType: MessageType.TEXT,
-      messageText: rewritten,
-    })
-
-    this._sections.push(
-      singleLayout(markdownTextPrimitive(rewritten, metadata.length ? metadata : undefined)),
-    )
+    const { text: rewritten, metadata } = extractInlineEntities(text, { hyperlink, citation, latex })
+    this._submessages.push({ messageType: MessageType.TEXT, messageText: rewritten })
+    this._sections.push(singleLayout(markdownTextPrimitive(rewritten, metadata.length ? metadata : undefined)))
     return this
   }
 
   async code(language, code) {
     ensureString(language, 'language')
     ensureString(code, 'code')
-
     const { codeBlock, unifiedBlocks } = tokenizeCode(code, language)
-
     this._submessages.push({
       messageType: MessageType.CODE,
-      codeMetadata: {
-        codeLanguage: language,
-        codeBlocks: codeBlock,
-      },
+      codeMetadata: { codeLanguage: language, codeBlocks: codeBlock },
     })
-
     this._sections.push(singleLayout(codePrimitive(language, unifiedBlocks)))
     return this
   }
@@ -126,34 +115,22 @@ export class AIRichBuilder {
     }
     const { title = '', hyperlink = true, citation = true, latex = true } = opts
     const meta = toTableMetadata(table, { title, hyperlink, citation, latex })
-
     this._submessages.push({
       messageType: MessageType.TABLE,
       tableMetadata: { title: meta.title, rows: meta.rows },
     })
-
     this._sections.push(singleLayout(tablePrimitive(meta.unifiedRows)))
     return this
   }
 
   async image(source, opts = {}) {
-    const { resolveUrl = false } = opts
     const list = Array.isArray(source) ? source : [source]
-
     const resolved = await Promise.all(
       list.map(async (s) => {
-        const url = await this.#media.resolve(s, {
-          mediaType: 'image',
-          strategy: resolveUrl ? 'auto' : 'auto',
-        })
-        return {
-          imagePreviewUrl: url,
-          imageHighResUrl: url,
-          sourceUrl: url,
-        }
+        const url = await this.#media.resolve(s, { mediaType: 'image', strategy: 'auto' })
+        return { imagePreviewUrl: url, imageHighResUrl: url, sourceUrl: url }
       }),
     )
-
     this._submessages.push({
       messageType: MessageType.RICH_RESPONSE,
       gridImageMetadata: {
@@ -161,15 +138,9 @@ export class AIRichBuilder {
         imageUrls: resolved,
       },
     })
-
     for (const r of resolved) {
       this._sections.push(
-        singleLayout(
-          imaginePrimitive(
-            { url: r.imagePreviewUrl, mime_type: 'image/png' },
-            ImagineType.IMAGE,
-          ),
-        ),
+        singleLayout(imaginePrimitive({ url: r.imagePreviewUrl, mime_type: 'image/png' }, ImagineType.IMAGE)),
       )
     }
     return this
@@ -177,22 +148,15 @@ export class AIRichBuilder {
 
   async video(source, opts = {}) {
     const { autoFill = true } = opts
-    const isObjectVideo = (v) => v && typeof v === 'object' && v.url
+    const isObjVideo = (v) => v && typeof v === 'object' && v.url
     const items = Array.isArray(source) ? source : [source]
 
-    this._submessages.push({
-      messageType: MessageType.TEXT,
-      messageText: '[ CANNOT_LOAD_VIDEO ]',
-    })
+    this._submessages.push({ messageType: MessageType.TEXT, messageText: '[ CANNOT_LOAD_VIDEO ]' })
 
     await Promise.all(
       items.map(async (item) => {
-        const isObj = isObjectVideo(item)
-        const url = await this.#media.resolve(
-          isObj ? item.url : item,
-          { mediaType: 'video', strategy: 'auto' },
-        )
-
+        const isObj = isObjVideo(item)
+        const url = await this.#media.resolve(isObj ? item.url : item, { mediaType: 'video', strategy: 'auto' })
         let fileLength = isObj && item.file_length != null ? item.file_length : 0
         let duration = isObj && item.duration != null ? item.duration : 0
         let thumbnailB64 = null
@@ -204,26 +168,18 @@ export class AIRichBuilder {
               fileLength = buf.length
               duration = this.#media.duration(buf)
               thumbnailB64 = await this.#media.videoThumbnail(buf, {
-                time: 0,
-                result: 'base64',
-                resizeOutput: true,
-                width: 300,
-                height: 300,
+                time: 0, result: 'base64', resizeOutput: true, width: 300, height: 300,
               })
             }
-          } catch {
-          }
+          } catch {}
         }
 
         const mimeType = isObj ? item.mime_type ?? 'video/mp4' : 'video/mp4'
-
         this._sections.push(
           singleLayout(
             imaginePrimitive(
               { url, mime_type: mimeType, file_length: fileLength, duration },
-              ImagineType.ANIMATE,
-              'READY',
-              thumbnailB64 || undefined,
+              ImagineType.ANIMATE, 'READY', thumbnailB64 || undefined,
             ),
           ),
         )
@@ -236,12 +192,7 @@ export class AIRichBuilder {
     if (!Array.isArray(sources)) {
       throw new ValidationError('sources must be an array', { code: 'LUMINA_VALIDATION_SOURCE' })
     }
-
-    const normalised =
-      sources.length && typeof sources[0] === 'string'
-        ? [sources]
-        : sources
-
+    const normalised = sources.length && typeof sources[0] === 'string' ? [sources] : sources
     const entries = await Promise.all(
       normalised.map(async (entry) => {
         const [iconUrl, url, text] = entry
@@ -251,7 +202,6 @@ export class AIRichBuilder {
         return shapeSourceEntry({ iconUrl: resolvedIcon, url, text })
       }),
     )
-
     this._sections.push(singleLayout(searchResultPrimitive(entries)))
     return this
   }
@@ -259,27 +209,17 @@ export class AIRichBuilder {
   async reels(items) {
     ensureObjectOrArray(items, 'reels')
     const list = Array.isArray(items) ? items : [items]
-
     const resolved = await Promise.all(
       list.map(async (item) => {
-        const [avatar, thumb] = await Promise.all([
-          item.profileIconUrl ?? item.profile_url ?? item.profile
-            ? this.#media.resolve(item.profileIconUrl ?? item.profile_url ?? item.profile, {
-                mediaType: 'image',
-                strategy: 'auto',
-              })
-            : Promise.resolve(''),
-          item.thumbnailUrl ?? item.thumbnail
-            ? this.#media.resolve(item.thumbnailUrl ?? item.thumbnail, {
-                mediaType: 'image',
-                strategy: 'auto',
-              })
-            : Promise.resolve(''),
+        const avatarSrc = item.profileIconUrl ?? item.profile_url ?? item.profile
+        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(''),
         ])
-        return { ...item, avatar, thumbnail: thumb }
+        return { ...item, avatar, thumbnail }
       }),
     )
-
     this._submessages.push({
       messageType: MessageType.REELS,
       contentItemsMetadata: {
@@ -294,7 +234,6 @@ export class AIRichBuilder {
         })),
       },
     })
-
     resolved.forEach((item, idx) => {
       this._richResponseSources.push({
         provider: 'LUMINA',
@@ -306,110 +245,62 @@ export class AIRichBuilder {
         sourceTitle: item.username ?? '',
       })
     })
-
-    this._sections.push(
-      hscrollLayout(resolved.map((item) => reelPrimitive(shapeReelEntry(item)))),
-    )
+    this._sections.push(hscrollLayout(resolved.map((item) => reelPrimitive(shapeReelEntry(item)))))
     return this
   }
 
   async product(item) {
     ensureObjectOrArray(item, 'product')
     const list = Array.isArray(item) ? item : [item]
-
-    this._submessages.push({
-      messageType: MessageType.TEXT,
-      messageText: '[ CANNOT_LOAD_PRODUCT ]',
-    })
-
+    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 iconSrc = p.icon_url ?? p.icon
         const [imageUrl, iconUrl] = await Promise.all([
-          p.image_url ?? p.image
-            ? this.#media.resolve(p.image_url ?? p.image, { mediaType: 'image', strategy: 'auto' })
-            : Promise.resolve(''),
-          p.icon_url ?? p.icon
-            ? this.#media.resolve(p.icon_url ?? p.icon, { 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 {
-          title: p.title,
-          brand: p.brand,
-          price: p.price,
-          sale_price: p.sale_price,
+          title: p.title, brand: p.brand, price: p.price, sale_price: p.sale_price,
           product_url: p.product_url ?? p.url,
           image: { url: imageUrl },
           additional_images: [{ url: iconUrl }],
         }
       }),
     )
-
     const primitives = products.map((p) => productCardPrimitive(p))
-    this._sections.push(
-      list.length === 1 ? singleLayout(primitives[0]) : hscrollLayout(primitives),
-    )
+    this._sections.push(list.length === 1 ? singleLayout(primitives[0]) : hscrollLayout(primitives))
     return this
   }
 
   async post(item) {
     ensureObjectOrArray(item, 'post')
     const list = Array.isArray(item) ? item : [item]
-
-    this._submessages.push({
-      messageType: MessageType.TEXT,
-      messageText: '[ CANNOT_LOAD_POST ]',
-    })
-
+    this._submessages.push({ messageType: MessageType.TEXT, messageText: '[ CANNOT_LOAD_POST ]' })
     const isCarousel = list.length > 1
-
     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 [profileUrl, thumbUrl, footerIcon] = await Promise.all([
-          p.profile_picture_url ?? p.profile_url ?? p.profile
-            ? this.#media.resolve(p.profile_picture_url ?? p.profile_url ?? p.profile, {
-                mediaType: 'image',
-                strategy: 'auto',
-              })
-            : Promise.resolve(''),
-          p.thumbnail_url ?? p.thumbnail
-            ? this.#media.resolve(p.thumbnail_url ?? p.thumbnail, {
-                mediaType: 'image',
-                strategy: 'auto',
-              })
-            : Promise.resolve(''),
-          p.footer_icon ?? p.icon
-            ? this.#media.resolve(p.footer_icon ?? p.icon, {
-                mediaType: 'image',
-                strategy: 'auto',
-              })
-            : Promise.resolve(''),
+          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(''),
         ])
-
-        return postPrimitive(
-          {
-            title: p.title ?? '',
-            subtitle: p.subtitle ?? '',
-            username: p.username ?? '',
-            profile_picture_url: profileUrl,
-            is_verified: !!(p.is_verified ?? p.verified),
-            thumbnail_url: thumbUrl,
-            post_caption: p.post_caption ?? p.caption ?? '',
-            likes_count: p.likes_count ?? p.like ?? 0,
-            comments_count: p.comments_count ?? p.comment ?? 0,
-            shares_count: p.shares_count ?? p.share ?? 0,
-            post_url: p.post_url ?? p.url ?? '',
-            post_deeplink: p.post_deeplink ?? p.deeplink ?? '',
-            source_app: p.source_app ?? p.source ?? 'INSTAGRAM',
-            footer_label: p.footer_label ?? p.footer ?? '',
-            footer_icon: footerIcon,
-            orientation: p.orientation ?? 'LANDSCAPE',
-            post_type: p.post_type ?? 'VIDEO',
-          },
-          isCarousel,
-        )
+        return postPrimitive({
+          title: p.title ?? '', subtitle: p.subtitle ?? '', username: p.username ?? '',
+          profile_picture_url: profileUrl, is_verified: !!(p.is_verified ?? p.verified),
+          thumbnail_url: thumbUrl, post_caption: p.post_caption ?? p.caption ?? '',
+          likes_count: p.likes_count ?? p.like ?? 0, comments_count: p.comments_count ?? p.comment ?? 0,
+          shares_count: p.shares_count ?? p.share ?? 0, post_url: p.post_url ?? p.url ?? '',
+          post_deeplink: p.post_deeplink ?? p.deeplink ?? '', source_app: p.source_app ?? p.source ?? 'INSTAGRAM',
+          footer_label: p.footer_label ?? p.footer ?? '', footer_icon: footerIcon,
+          orientation: p.orientation ?? 'LANDSCAPE', post_type: p.post_type ?? 'VIDEO',
+        }, isCarousel)
       }),
     )
-
     this._sections.push(hscrollLayout(primitives))
     return this
   }
@@ -423,23 +314,16 @@ export class AIRichBuilder {
 
   async suggest(suggestion, opts = {}) {
     const { scroll = true, layout } = opts
-
     if (typeof suggestion === 'string') {
       suggestion = [suggestion]
     } else {
       ensureStringArray(suggestion, 'suggestion')
     }
-
     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' }))
@@ -451,6 +335,31 @@ 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({

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 }