@kyyinfinite/lumina 1.0.0 → 1.0.2

package/src/builders/sticker.js

@@ -0,0 +1,102 @@
+import { toSticker, addExif } from '../media/sticker.js'
+import { fetchBuffer } from '../media/fetch.js'
+import { sniffMime, mimeToCategory } from '../utils/mime.js'
+import { coerceMediaSource } from '../utils/validator.js'
+import { createInteractiveNodes } from '../proto/relay-nodes.js'
+
+export class StickerBuilder {
+  constructor(conn) {
+    this.#conn = conn
+    this._source = null
+    this._type = null
+    this._packname = 'Lumina'
+    this._author = ''
+    this._categories = ['']
+    this._extra = {}
+  }
+
+  #conn
+
+  source(input) {
+    this._source = input
+    return this
+  }
+
+  pack(packname, author = '') {
+    this._packname = packname
+    this._author = author
+    return this
+  }
+
+  author(author) {
+    this._author = author
+    return this
+  }
+
+  emoji(...emojis) {
+    this._categories = emojis.flat()
+    return this
+  }
+
+  type(type) {
+    this._type = type
+    return this
+  }
+
+  extra(obj) {
+    Object.assign(this._extra, obj)
+    return this
+  }
+
+  #metadata() {
+    return {
+      packname: this._packname,
+      author: this._author,
+      categories: this._categories,
+      extra: this._extra,
+    }
+  }
+
+  async #resolveBuffer() {
+    if (!this._source) throw new Error('sticker source is required — call .source(buffer|url)')
+
+    let buffer
+
+    if (Buffer.isBuffer(this._source)) {
+      buffer = this._source
+    } else if (typeof this._source === 'string') {
+      buffer = await fetchBuffer(this._source)
+    } else {
+      const { raw } = coerceMediaSource(this._source)
+      buffer = Buffer.isBuffer(raw) ? raw : await fetchBuffer(raw.url)
+    }
+
+    return buffer
+  }
+
+  #detectType(buffer) {
+    if (this._type) return this._type
+    const mime = sniffMime(buffer)
+    const cat = mimeToCategory(mime)
+    if (cat === 'video') return 'video'
+    return 'image'
+  }
+
+  async build() {
+    const buffer = await this.#resolveBuffer()
+    const type = this.#detectType(buffer)
+    return toSticker(buffer, type, this.#metadata())
+  }
+
+  async send(jid, opts = {}) {
+    const stickerBuffer = await this.build()
+    const msg = await this.#conn.generateMessage(jid, { sticker: stickerBuffer }, opts)
+    await this.#conn.relayMessage(msg.key.remoteJid, msg.message, {
+      messageId: msg.key.id,
+      ...opts,
+    })
+    return msg
+  }
+}
+
+export default StickerBuilder

package/src/client/bot.js

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

package/src/client/connection.js

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

package/src/errors.js

@@ -1,36 +1,4 @@
-/**
- * @file errors.js
- * @module lumina/errors
- *
- * Error hierarchy for Lumina. Every Lumina-thrown error subclasses
- * {@link LuminaError} and carries a stable `code`, the originating `module`,
- * and (optionally) a `cause` field that follows the ES2022 Error.cause convention.
- *
- * Hierarchy:
- *   LuminaError
- *   ├── ValidationError       (bad input — subclass of TypeError)
- *   ├── MediaError            (fetch / resize / upload / ffmpeg failure)
- *   ├── ProtoError            (assemble / generate / relay failure)
- *   ├── ConnectionError       (Baileys socket missing or incompatible)
- *   └── ProtocolError         (WAProto mismatch — emitted by ProtoUpdater)
- */
-
-/**
- * Base class for every error thrown by Lumina.
- *
- * @example
- *   if (err instanceof LuminaError) {
- *     console.error(err.code, err.module, err.message)
- *   }
- */
 export class LuminaError extends Error {
-  /**
-   * @param {string} message    Human-readable message.
-   * @param {object} [opts]
-   * @param {string} [opts.code='LUMINA_ERROR']  Stable machine code.
-   * @param {string} [opts.module='lumina']      Logical module that threw.
-   * @param {Error}  [opts.cause]                Original error (ES2022).
-   */
   constructor(message, opts = {}) {
     super(message, { cause: opts.cause })
     this.name = new.target.name
@@ -39,7 +7,6 @@ export class LuminaError extends Error {
   }
 }
 
-/** Thrown when an argument fails validation. Subclass of TypeError for compat. */
 export class ValidationError extends TypeError {
   constructor(message, opts = {}) {
     super(message, { cause: opts.cause })
@@ -49,7 +16,6 @@ export class ValidationError extends TypeError {
   }
 }
 
-/** Thrown when a media operation (fetch/resize/upload/ffmpeg) fails. */
 export class MediaError extends LuminaError {
   constructor(message, opts = {}) {
     super(message, opts)
@@ -58,7 +24,6 @@ export class MediaError extends LuminaError {
   }
 }
 
-/** Thrown when a proto assembly / message generation / relay fails. */
 export class ProtoError extends LuminaError {
   constructor(message, opts = {}) {
     super(message, opts)
@@ -67,7 +32,6 @@ export class ProtoError extends LuminaError {
   }
 }
 
-/** Thrown when the Baileys socket is missing or its API is incompatible. */
 export class ConnectionError extends LuminaError {
   constructor(message, opts = {}) {
     super(message, opts)
@@ -76,7 +40,6 @@ export class ConnectionError extends LuminaError {
   }
 }
 
-/** Thrown by {@link ProtoUpdater} when WAProto validation fails. */
 export class ProtocolError extends LuminaError {
   constructor(message, opts = {}) {
     super(message, opts)

package/src/index.d.ts

@@ -1,14 +1,4 @@
-/**
- * @file index.d.ts
- * @module @kyyinfinite/lumina
- *
- * Manual TypeScript declaration for Lumina. Every builder, service, parser,
- * and error is fully typed. Generated `.d.ts` files were rejected to keep
- * the public surface auditable and to expose rich per-method overloads
- * that auto-generation would lose.
- */
-
-// ─── External dependencies ─────────────────────────────────────────────
+
 
 declare module '@whiskeysockets/baileys' {
   export interface WASocket {
@@ -30,8 +20,6 @@ declare module '@whiskeysockets/baileys' {
   export function generateReactionMessage(jid: string, opts: any): any
 }
 
-// ─── Errors ────────────────────────────────────────────────────────────
-
 export class LuminaError extends Error {
   readonly code: string
   readonly module: string
@@ -47,8 +35,6 @@ export class ProtoError extends LuminaError {}
 export class ConnectionError extends LuminaError {}
 export class ProtocolError extends LuminaError {}
 
-// ─── Logger ────────────────────────────────────────────────────────────
-
 export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug'
 
 export interface Logger {
@@ -66,8 +52,6 @@ export function createLogger(opts?: {
   transport?: (level: string, scope: string, args: any[]) => void
 }): Logger
 
-// ─── Enums & catalog ───────────────────────────────────────────────────
-
 export const MessageType: Readonly<{
   RICH_RESPONSE: 1
   TEXT: 2
@@ -129,8 +113,6 @@ export const TYPENAME: Readonly<{
   layout(kind: string): string
 }>
 
-// ─── Parsers ───────────────────────────────────────────────────────────
-
 export interface ExtractOptions {
   extract?: boolean
   hyperlink?: boolean
@@ -165,8 +147,6 @@ export function toTableMetadata(
   opts?: { title?: string; hyperlink?: boolean; citation?: boolean; latex?: boolean },
 ): TableMetadata
 
-// ─── Connection ────────────────────────────────────────────────────────
-
 export interface ConnectionOptions {
   uploadJid?: string
   logger?: Logger
@@ -188,7 +168,6 @@ export class Connection {
   get raw(): import('@whiskeysockets/baileys').WASocket
 }
 
-// ─── Services ──────────────────────────────────────────────────────────
 
 export class MediaService {
   constructor(conn: Connection, opts?: { cache?: boolean; cacheMax?: number; logger?: Logger; uploadJid?: string })
@@ -230,8 +209,6 @@ export class MessageService {
   edit(jid: string, key: any, newText: string, opts?: any): Promise<any>
 }
 
-// ─── Builders ──────────────────────────────────────────────────────────
-
 export interface ContentFields {
   title(t: string): this
   subtitle(t: string): this
@@ -371,8 +348,6 @@ export class AIRichBuilder implements ContentFields {
   send(jid: string, opts?: object): Promise<string>
 }
 
-// ─── ProtoUpdater ──────────────────────────────────────────────────────
-
 export class ProtoUpdater {
   constructor(opts?: { protoPath?: string; backupDir?: string; logger?: Logger })
   backup(): Promise<{ id: string; timestamp: number; path: string; hash: string }>
@@ -395,7 +370,6 @@ export function assembleRichResponse(opts?: any): Promise<object>
 export function createInteractiveNodes(opts?: any): any[]
 export function createBareInteractiveNodes(opts?: any): any[]
 
-// ─── Bot ───────────────────────────────────────────────────────────────
 
 export interface BotOptions {
   uploadJid?: string
@@ -451,7 +425,6 @@ export class Bot {
   get raw(): import('@whiskeysockets/baileys').WASocket
 }
 
-// ─── Version ───────────────────────────────────────────────────────────
 
 export const VERSION: string