@kyyinfinite/lumina 1.0.0 → 1.0.2

package/src/services/message-service.js

@@ -1,102 +1,47 @@
-/**
- * @file message-service.js
- * @module lumina/services/message-service
- *
- * High-level message senders for every "basic" WhatsApp content type:
- * text, image, video, audio, document, sticker, contact, location, poll,
- * reply, react, delete, forward, copy, edit.
- *
- * Each method delegates to {@link Connection} so that the Bot wrapper stays
- * thin and the service layer never imports Baileys directly (Layer 3 must
- * not touch the adapter's internals).
- */
-
 import { coerceMediaSource } from '../utils/validator.js'
 
-/** @typedef {import('../client/connection.js').Connection} Connection */
-/** @typedef {import('./proto-service.js').ProtoService} ProtoService */
-/** @typedef {import('./media-service.js').MediaService} MediaService */
-
 export class MessageService {
-  /**
-   * @param {Connection} conn
-   * @param {ProtoService} proto
-   * @param {MediaService} media
-   */
   constructor(conn, proto, media) {
     this.conn = conn
     this.proto = proto
     this.media = media
   }
 
-  /**
-   * @param {string} jid
-   * @param {string} text
-   * @param {object} [opts]  Forwarded to generateWAMessageFromContent.
-   * @returns {Promise<object>}
-   */
-  async text(jid, text, opts) {
-    const msg = await this.conn.generateMessage(jid, { conversation: text }, opts ?? {})
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...(opts ?? {}),
-    })
+  async text(jid, text, opts = {}) {
+    const msg = await this.conn.generateMessage(jid, { conversation: text }, opts)
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /** @param {string | Buffer} source */
   async image(jid, source, caption, opts = {}) {
     return this.#sendMedia('image', jid, source, caption, opts)
   }
 
-  /** @param {string | Buffer} source */
   async video(jid, source, caption, opts = {}) {
     return this.#sendMedia('video', jid, source, caption, opts)
   }
 
-  /** @param {string | Buffer} source */
   async audio(jid, source, opts = {}) {
     return this.#sendMedia('audio', jid, source, undefined, { ...opts, ptt: opts.ptt ?? false })
   }
 
-  /** @param {string | Buffer} source */
   async document(jid, source, opts = {}) {
     return this.#sendMedia('document', jid, source, undefined, opts)
   }
 
-  /** @param {string | Buffer} source */
   async sticker(jid, source, opts = {}) {
     return this.#sendMedia('sticker', jid, source, undefined, opts)
   }
 
-  /**
-   * @param {'image'|'video'|'audio'|'document'|'sticker'} type
-   * @param {string} jid
-   * @param {string | Buffer} source
-   * @param {string} [caption]
-   * @param {object} opts
-   */
   async #sendMedia(type, jid, source, caption, opts = {}) {
     const { raw } = coerceMediaSource(source)
-    const msg = await this.conn.generateMessage(
-      jid,
-      { [type]: raw, caption, ...opts },
-      opts,
-    )
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    const content = { [type]: raw }
+    if (caption !== undefined) content.caption = caption
+    const msg = await this.conn.generateMessage(jid, content, opts)
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * Send one or more contacts.
-   *
-   * @param {string} jid
-   * @param {Array<{ name: string, number: string }>} contacts
-   * @param {object} [opts]
-   */
   async contact(jid, contacts, opts = {}) {
     const vCard = (c) =>
       `BEGIN:VCARD\nVERSION:3.0\nFN:${c.name}\nTEL;type=CELL;type=VOICE;waid=${c.number}:${c.number}\nEND:VCARD`
@@ -104,22 +49,13 @@ export class MessageService {
     if (contacts.length === 1) {
       const msg = await this.conn.generateMessage(
         jid,
-        {
-          contactMessage: {
-            displayName: contacts[0].name,
-            vcard: vCard(contacts[0]),
-          },
-        },
+        { contactMessage: { displayName: contacts[0].name, vcard: vCard(contacts[0]) } },
         opts,
       )
-      await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-        messageId: msg.key.id,
-        ...opts,
-      })
+      await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
       return msg
     }
 
-    // Multi-contact: use contactsMessage
     const multi = await this.conn.generateMessage(
       jid,
       {
@@ -130,19 +66,10 @@ export class MessageService {
       },
       opts,
     )
-    await this.conn.relayMessage(multi.key.remoteJid, multi.message, {
-      messageId: multi.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(multi.key.remoteJid, multi.message, { messageId: multi.key.id, ...opts })
     return multi
   }
 
-  /**
-   * @param {string} jid
-   * @param {number} lat
-   * @param {number} lng
-   * @param {object} [opts]  Optional name/address/urls.
-   */
   async location(jid, lat, lng, opts = {}) {
     const msg = await this.conn.generateMessage(
       jid,
@@ -157,19 +84,10 @@ export class MessageService {
       },
       opts,
     )
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * @param {string} jid
-   * @param {string} name
-   * @param {string[]} options
-   * @param {object} [opts]   { selectableCount, public, messageSecret }
-   */
   async poll(jid, name, options, opts = {}) {
     const msg = await this.conn.generatePoll(jid, {
       name,
@@ -177,21 +95,10 @@ export class MessageService {
       selectableCount: opts.selectableCount ?? 1,
       toJid: jid,
     })
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * Reply to a quoted message.
-   *
-   * @param {string} jid
-   * @param {string} text
-   * @param {object} quoted  Quoted message object (must have `.key`).
-   * @param {object} [opts]
-   */
   async reply(jid, text, quoted, opts = {}) {
     const msg = await this.conn.generateMessage(
       jid,
@@ -207,81 +114,32 @@ export class MessageService {
       },
       { quoted, ...opts },
     )
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * React to a message.
-   *
-   * @param {string} jid
-   * @param {object} key
-   * @param {string} emoji
-   * @param {object} [opts]
-   */
   async react(jid, key, emoji, opts = {}) {
     const msg = await this.conn.generateReaction(jid, { key, text: emoji })
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * Delete a message (revoke).
-   *
-   * @param {string} jid
-   * @param {object} key
-   */
   async delete(jid, key) {
     return this.conn.raw.sendMessage(jid, { delete: key })
   }
 
-  /**
-   * Forward a message.
-   *
-   * @param {string} jid
-   * @param {object} message   The message object to forward.
-   * @param {object} [opts]    { quoted, additionalNodes }
-   */
   async forward(jid, message, opts = {}) {
     return this.conn.raw.forwardMessage(jid, message, opts)
   }
 
-  /**
-   * Copy a message (re-send its content as a new message).
-   *
-   * @param {string} jid
-   * @param {object} message
-   * @param {object} [opts]
-   */
   async copy(jid, message, opts = {}) {
     const msg = await this.conn.generateMessage(jid, message, opts)
-    await this.conn.relayMessage(msg.key.remoteJid, msg.message, {
-      messageId: msg.key.id,
-      ...opts,
-    })
+    await this.conn.relayMessage(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...opts })
     return msg
   }
 
-  /**
-   * Edit a previously sent text message.
-   *
-   * @param {string} jid
-   * @param {object} key
-   * @param {string} newText
-   * @param {object} [opts]
-   */
   async edit(jid, key, newText, opts = {}) {
-    return this.conn.raw.sendMessage(jid, {
-      edit: key,
-      text: newText,
-      ...opts,
-    })
+    return this.conn.raw.sendMessage(jid, { edit: key, text: newText, ...opts })
   }
 }
 

package/src/services/proto-service.js

@@ -1,87 +1,33 @@
-/**
- * @file proto-service.js
- * @module lumina/services/proto-service
- *
- * Wraps the lower-level `proto/*` modules with a {@link Connection} so that
- * callers don't have to thread the socket through every call.
- */
-
 import { createInteractiveNodes } from '../proto/relay-nodes.js'
 
-/** @typedef {import('../client/connection.js').Connection} Connection */
-
 export class ProtoService {
-  /** @param {Connection} conn */
   constructor(conn) {
     if (!conn) throw new Error('Connection is required for ProtoService')
     this.conn = conn
   }
 
-  /**
-   * Generate a WA message object from a content descriptor.
-   *
-   * @param {string} jid
-   * @param {object} content
-   * @param {object} [opts]
-   * @returns {Promise<object>}
-   */
   async generate(jid, content, opts) {
     return this.conn.generateMessage(jid, content, opts ?? {})
   }
 
-  /**
-   * Relay a pre-built message. Returns the message ID.
-   *
-   * @param {string} jid
-   * @param {object} message
-   * @param {object} [opts]
-   * @returns {Promise<string>}
-   */
   async relay(jid, message, opts) {
     return this.conn.relayMessage(jid, message, opts ?? {})
   }
 
-  /**
-   * Relay a pre-built message WITH the biz/native_flow/mixed additional
-   * nodes. This is the variant used by every interactive builder (Button,
-   * ButtonV2, Carousel).
-   *
-   * @param {string} jid
-   * @param {object} message
-   * @param {object} [opts]
-   * @returns {Promise<string>}
-   */
   async relayInteractive(jid, message, opts = {}) {
-    const nodes = opts.additionalNodes ?? createInteractiveNodes()
     return this.conn.relayMessage(jid, message, {
       ...opts,
-      additionalNodes: nodes,
+      additionalNodes: opts.additionalNodes ?? createInteractiveNodes(),
     })
   }
 
-  /**
-   * Generate + relay in one shot. Returns the generated message object
-   * (with `.key` populated by Baileys) so callers can keep a reference.
-   *
-   * @param {string} jid
-   * @param {object} content
-   * @param {object} [opts]
-   * @param {boolean} [opts.interactive=false]   If true, attach the biz/native_flow nodes.
-   * @returns {Promise<object>}
-   */
   async generateAndRelay(jid, content, opts = {}) {
     const { interactive = false, ...rest } = opts
     const msg = await this.conn.generateMessage(jid, content, rest)
     if (interactive) {
-      await this.relayInteractive(msg.key.remoteJid, msg.message, {
-        messageId: msg.key.id,
-        ...rest,
-      })
+      await this.relayInteractive(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...rest })
     } else {
-      await this.relay(msg.key.remoteJid, msg.message, {
-        messageId: msg.key.id,
-        ...rest,
-      })
+      await this.relay(msg.key.remoteJid, msg.message, { messageId: msg.key.id, ...rest })
     }
     return msg
   }

package/src/utils/id.js

@@ -1,40 +1,15 @@
-/**
- * @file id.js
- * @module lumina/utils/id
- *
- * Stable, collision-resistant identifier generation. Replaces the obfuscated
- * `\u004E\u0049\u0058\u0045\u004C_…` prefix that was sprinkled across the
- * legacy extractIE function.
- */
-
 import crypto from 'node:crypto'
 
-/** Project-wide prefix for inline-entity keys. */
 export const ENTITY_PREFIX = 'LUMINA'
 
-/** Generate a fresh RFC-4122 v4 UUID. */
 export function uuid() {
   return crypto.randomUUID()
 }
 
-/**
- * Build a stable, scoped inline-entity key.
- *
- * @param {'HYPERLINK'|'CITATION'|'LATEX'} kind
- * @param {number} index   Zero-based counter.
- * @returns {string}       e.g. `LUMINA_HYPERLINK_0`
- */
 export function entityKey(kind, index) {
   return `${ENTITY_PREFIX}_${kind}_${index}`
 }
 
-/**
- * Hash a string with SHA-256, return hex digest (used by ProtoUpdater for
- * backup integrity verification).
- *
- * @param {string} content
- * @returns {string}
- */
 export function sha256(content) {
   return crypto.createHash('sha256').update(content).digest('hex')
 }

package/src/utils/logger.js

@@ -1,38 +1,5 @@
-/**
- * @file logger.js
- * @module lumina/utils/logger
- *
- * Minimal, zero-dependency logger with child scopes and level filtering.
- * Compatible with the pino/winston subset: { error, warn, info, debug, child }.
- *
- * Default logger is a no-op — zero overhead in production. Inject your own
- * logger via `new Bot(socket, { logger })` to enable output.
- */
+const LEVEL_ORDER = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 }
 
-/** @typedef {'silent'|'error'|'warn'|'info'|'debug'} LogLevel */
-
-const LEVEL_ORDER = /** @type {const} */ ({
-  silent: 0,
-  error: 1,
-  warn: 2,
-  info: 3,
-  debug: 4,
-})
-
-const NOOP = () => {}
-
-/**
- * Build a logger from a single options object.
- *
- * @param {object} [opts]
- * @param {LogLevel} [opts.level='warn']        Minimum level emitted.
- * @param {boolean}  [opts.silent=false]        Convenience: forces level 'silent'.
- * @param {(level: string, scope: string, args: any[]) => void} [opts.transport]
- *        Custom transport. Receives the level name, the current scope, and the
- *        raw arguments array. Default transport writes to console.
- * @param {string} [opts.scope='lumina']        Initial scope.
- * @returns {Logger}
- */
 export function createLogger(opts = {}) {
   const level = opts.silent ? 'silent' : opts.level ?? 'warn'
   const threshold = LEVEL_ORDER[level] ?? LEVEL_ORDER.warn
@@ -45,9 +12,7 @@ export function createLogger(opts = {}) {
     })
 
   const make = (scope) => {
-    const emit = (lvl, args) => {
-      if (LEVEL_ORDER[lvl] <= threshold) transport(lvl, scope, args)
-    }
+    const emit = (lvl, args) => { if (LEVEL_ORDER[lvl] <= threshold) transport(lvl, scope, args) }
     return {
       error: (...a) => emit('error', a),
       warn: (...a) => emit('warn', a),
@@ -60,6 +25,4 @@ export function createLogger(opts = {}) {
   return make(scope0)
 }
 
-/** @typedef {ReturnType<createLogger>} Logger */
-
 export default createLogger

package/src/utils/mime.js

@@ -1,99 +1,43 @@
-/**
- * @file mime.js
- * @module lumina/utils/mime
- *
- * Sniff & lookup MIME types from buffer magic bytes and file extensions.
- * Replaces the hardcoded `mime_type: 'image/png'` / `'video/mp4'` literals
- * sprinkled across the legacy AIRich builder.
- */
-
-/** @type {Record<string, string>} */
 const EXT_MAP = {
-  png: 'image/png',
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  gif: 'image/gif',
-  webp: 'image/webp',
-  bmp: 'image/bmp',
-  tiff: 'image/tiff',
-  mp4: 'video/mp4',
-  webm: 'video/webm',
-  mov: 'video/quicktime',
-  avi: 'video/x-msvideo',
-  mkv: 'video/x-matroska',
-  mp3: 'audio/mpeg',
-  ogg: 'audio/ogg',
-  wav: 'audio/wav',
-  opus: 'audio/opus',
-  m4a: 'audio/mp4',
-  pdf: 'application/pdf',
-  json: 'application/json',
-  zip: 'application/zip',
-  txt: 'text/plain',
-  html: 'text/html',
-  csv: 'text/csv',
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', bmp: 'image/bmp', tiff: 'image/tiff', mp4: 'video/mp4',
+  webm: 'video/webm', mov: 'video/quicktime', avi: 'video/x-msvideo',
+  mkv: 'video/x-matroska', mp3: 'audio/mpeg', ogg: 'audio/ogg', wav: 'audio/wav',
+  opus: 'audio/opus', m4a: 'audio/mp4', pdf: 'application/pdf',
+  json: 'application/json', zip: 'application/zip', txt: 'text/plain',
+  html: 'text/html', csv: 'text/csv',
+}
+
+function fromExtension(filename) {
+  const ext = filename.split('.').pop()?.toLowerCase() ?? ''
+  return EXT_MAP[ext] ?? 'application/octet-stream'
 }
 
-/**
- * Sniff MIME type from buffer magic bytes. Falls back to extension lookup.
- *
- * @param {Buffer} buf
- * @param {string} [filename]  Optional filename for extension fallback.
- * @returns {string}  MIME type, or 'application/octet-stream' if unknown.
- */
 export function sniffMime(buf, filename) {
   if (!Buffer.isBuffer(buf) || buf.length < 4) {
     return filename ? fromExtension(filename) : 'application/octet-stream'
   }
-  // PNG
   if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'image/png'
-  // JPEG (FFD8FF)
   if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg'
-  // GIF (GIF87a / GIF89a)
   if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) return 'image/gif'
-  // WebP — RIFF....WEBP
-  if (
-    buf.length >= 12 &&
-    buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
-    buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50
-  ) return 'image/webp'
-  // MP4 — ftyp box at offset 4
+  if (buf.length >= 12 && buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+    buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50) return 'image/webp'
   if (buf.length >= 12 && buf[4] === 0x66 && buf[5] === 0x74 && buf[6] === 0x79 && buf[7] === 0x70) {
     const brand = buf.toString('ascii', 8, 12)
     if (brand === 'qt  ') return 'video/quicktime'
     if (brand === 'M4A ') return 'audio/mp4'
     return 'video/mp4'
   }
-  // MP3 — ID3 tag or frame sync
   if (buf[0] === 0x49 && buf[1] === 0x44 && buf[2] === 0x33) return 'audio/mpeg'
   if (buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0) return 'audio/mpeg'
-  // OGG
   if (buf[0] === 0x4f && buf[1] === 0x67 && buf[2] === 0x67 && buf[3] === 0x53) return 'audio/ogg'
-  // WAV — RIFF....WAVE
-  if (
-    buf.length >= 12 &&
-    buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
-    buf[8] === 0x57 && buf[9] === 0x41 && buf[10] === 0x56 && buf[11] === 0x45
-  ) return 'audio/wav'
-  // PDF
+  if (buf.length >= 12 && buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+    buf[8] === 0x57 && buf[9] === 0x41 && buf[10] === 0x56 && buf[11] === 0x45) return 'audio/wav'
   if (buf[0] === 0x25 && buf[1] === 0x50 && buf[2] === 0x44 && buf[3] === 0x46) return 'application/pdf'
-  // ZIP
-  if (buf[0] === 0x50 && buf[1] === 0x4b && (buf[2] === 0x03 || buf[2] === 0x05 || buf[2] === 0x07)) {
-    return 'application/zip'
-  }
+  if (buf[0] === 0x50 && buf[1] === 0x4b && (buf[2] === 0x03 || buf[2] === 0x05 || buf[2] === 0x07)) return 'application/zip'
   return filename ? fromExtension(filename) : 'application/octet-stream'
 }
 
-/** @param {string} filename */
-function fromExtension(filename) {
-  const ext = filename.split('.').pop()?.toLowerCase() ?? ''
-  return EXT_MAP[ext] ?? 'application/octet-stream'
-}
-
-/**
- * @param {string} mime
- * @returns {'image'|'video'|'audio'|'document'}  WA media category.
- */
 export function mimeToCategory(mime) {
   if (mime.startsWith('image/')) return 'image'
   if (mime.startsWith('video/')) return 'video'

package/src/utils/promise.js

@@ -1,20 +1,3 @@
-/**
- * @file promise.js
- * @module lumina/utils/promise
- *
- * Promise helpers. The legacy `waitAllPromises` deep-resolver is preserved
- * here as `resolveDeep`, used only for backward-compat / lazy builder mode.
- * The default builder path uses eager await — see AIRichBuilder docs.
- */
-
-/**
- * Recursively walk an object/array tree, awaiting every Promise encountered.
- * Returns a structurally-identical tree with all Promises resolved.
- *
- * @template T
- * @param {T | Promise<T>} input
- * @returns {Promise<Awaited<T>>}
- */
 export async function resolveDeep(input) {
   const seen = await input
   if (seen && typeof seen.then === 'function') return resolveDeep(seen)
@@ -27,15 +10,6 @@ export async function resolveDeep(input) {
   return seen
 }
 
-/**
- * Run an async mapper over an array with a concurrency limit.
- *
- * @template T, R
- * @param {T[]} arr
- * @param {(item: T, i: number) => Promise<R>} mapper
- * @param {number} [concurrency=8]
- * @returns {Promise<R[]>}
- */
 export async function mapWithConcurrency(arr, mapper, concurrency = 8) {
   const results = new Array(arr.length)
   let cursor = 0