@kyyinfinite/lumina 1.0.0

package/src/services/message-service.js

@@ -0,0 +1,288 @@
+/**
+ * @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 ?? {}),
+    })
+    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,
+    })
+    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`
+
+    if (contacts.length === 1) {
+      const msg = await this.conn.generateMessage(
+        jid,
+        {
+          contactMessage: {
+            displayName: contacts[0].name,
+            vcard: vCard(contacts[0]),
+          },
+        },
+        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,
+      {
+        contactsMessage: {
+          displayName: contacts.map((c) => c.name).join(', '),
+          contacts: contacts.map((c) => ({ vcard: vCard(c) })),
+        },
+      },
+      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,
+      {
+        locationMessage: {
+          degreesLatitude: lat,
+          degreesLongitude: lng,
+          name: opts.name,
+          address: opts.address,
+          url: opts.url,
+        },
+      },
+      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,
+      values: options,
+      selectableCount: opts.selectableCount ?? 1,
+      toJid: jid,
+    })
+    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,
+      {
+        extendedTextMessage: {
+          text,
+          contextInfo: {
+            stanzaId: quoted.key.id,
+            participant: quoted.key.participant ?? quoted.key.remoteJid,
+            quotedMessage: quoted.message ?? { conversation: '' },
+          },
+        },
+      },
+      { quoted, ...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,
+    })
+    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,
+    })
+    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,
+    })
+  }
+}
+
+export default MessageService

package/src/services/proto-service.js

@@ -0,0 +1,90 @@
+/**
+ * @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,
+    })
+  }
+
+  /**
+   * 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,
+      })
+    } else {
+      await this.relay(msg.key.remoteJid, msg.message, {
+        messageId: msg.key.id,
+        ...rest,
+      })
+    }
+    return msg
+  }
+}
+
+export default ProtoService

package/src/utils/id.js

@@ -0,0 +1,42 @@
+/**
+ * @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')
+}
+
+export default { uuid, entityKey, sha256, ENTITY_PREFIX }

package/src/utils/logger.js

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ */
+
+/** @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
+  const scope0 = opts.scope ?? 'lumina'
+  const transport =
+    opts.transport ??
+    ((lvl, scope, args) => {
+      const fn = lvl === 'error' ? console.error : lvl === 'warn' ? console.warn : console.log
+      fn(`[${lvl}] ${scope}:`, ...args)
+    })
+
+  const make = (scope) => {
+    const emit = (lvl, args) => {
+      if (LEVEL_ORDER[lvl] <= threshold) transport(lvl, scope, args)
+    }
+    return {
+      error: (...a) => emit('error', a),
+      warn: (...a) => emit('warn', a),
+      info: (...a) => emit('info', a),
+      debug: (...a) => emit('debug', a),
+      child: (sub) => make(sub ? `${scope}:${sub}` : scope),
+    }
+  }
+
+  return make(scope0)
+}
+
+/** @typedef {ReturnType<createLogger>} Logger */
+
+export default createLogger

package/src/utils/mime.js

@@ -0,0 +1,104 @@
+/**
+ * @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',
+}
+
+/**
+ * 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[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[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'
+  }
+  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'
+  if (mime.startsWith('audio/')) return 'audio'
+  return 'document'
+}
+
+export default { sniffMime, mimeToCategory, EXT_MAP }

package/src/utils/promise.js

@@ -0,0 +1,52 @@
+/**
+ * @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)
+  if (Array.isArray(seen)) return Promise.all(seen.map(resolveDeep))
+  if (seen && typeof seen === 'object') {
+    const entries = Object.entries(seen)
+    const resolved = await Promise.all(entries.map(async ([k, v]) => [k, await resolveDeep(v)]))
+    return Object.fromEntries(resolved)
+  }
+  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
+  const workers = new Array(Math.min(concurrency, arr.length)).fill(0).map(async () => {
+    while (cursor < arr.length) {
+      const i = cursor++
+      results[i] = await mapper(arr[i], i)
+    }
+  })
+  await Promise.all(workers)
+  return results
+}
+
+export default { resolveDeep, mapWithConcurrency }