@kyyinfinite/lumina 1.0.0

package/src/proto/updater.js

@@ -0,0 +1,318 @@
+/**
+ * @file updater.js
+ * @module lumina/proto/updater
+ *
+ * ProtoUpdater — automatic WAProto maintenance utility.
+ *
+ * WhatsApp constantly ships new protobuf definitions to its Web client, and
+ * the community `@whiskeysockets/baileys` package vendors a snapshot of those
+ * definitions as `WAProto/`. Lumina ships a small utility that:
+ *
+ *   1. Backs up the current WAProto tree before any mutation.
+ *   2. Transforms the generated CommonJS files into ESM (`require` → `import`,
+ *      `module.exports` → `export`).
+ *   3. Fixes known upstream issues (e.g. the `HistorySyncType` enum that the
+ *      `pbjs` generator sometimes emits with the wrong numeric tag).
+ *   4. Validates the result by `import()`-ing each module file.
+ *   5. Rolls back automatically on validation failure (configurable).
+ *
+ * The updater is opt-in: it never runs at import time. Users invoke it from
+ * the CLI or programmatically when they want to refresh the proto bundle.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { ProtocolError } from '../errors.js'
+import { sha256 } from '../utils/id.js'
+import { createLogger } from '../utils/logger.js'
+
+/** @typedef {import('../utils/logger.js').Logger} Logger */
+
+/**
+ * Known WAProto fixes. Each entry: { file: RegExp, apply: (content: string) => string }.
+ * Keeping these in one place makes them trivial to audit & extend.
+ */
+const KNOWN_FIXES = [
+  {
+    name: 'history-sync-type-enum',
+    file: /HistorySync\.js$/,
+    apply: (c) =>
+      // Ensure `HistorySyncType.INITIAL_BOOTSTRAP = 0` exists — some pbjs runs
+      // emit it as `= 1` which breaks downstream comparison logic.
+      c.replace(
+        /(HistorySyncType\s*=\s*\{)[\s\S]*?\}/,
+        (m) =>
+          m
+            .replace(/INITIAL_BOOTSTRAP\s*:\s*[1-9]\d*/, 'INITIAL_BOOTSTRAP: 0')
+            .replace(/INITIAL_BOOTSTRAP\s*=\s*[1-9]\d*/, 'INITIAL_BOOTSTRAP = 0'),
+      ),
+  },
+  {
+    name: 'recent-messages-enum',
+    file: /HistorySync\.js$/,
+    apply: (c) =>
+      c.replace(
+        /(RecentMessagesWeightInheritance\s*=\s*\{)[\s\S]*?\}/,
+        (m) => m.replace(/CHRONOLOGICAL\s*:\s*0/, 'CHRONOLOGICAL: 1'),
+      ),
+  },
+]
+
+/** Pattern for CommonJS `require('...')` — used by CJS→ESM transform. */
+const RE_REQUIRE = /require\(\s*(['"])([^'"]+)\1\s*\)/g
+
+/** Pattern for `module.exports = ...` / `exports.x = ...`. */
+const RE_MODULE_EXPORTS_ASSIGN = /module\.exports\s*=\s*/g
+const RE_EXPORTS_DOT = /exports\.(\w+)\s*=\s*/g
+
+/** Pattern for `const x = require('...')` — convert to `import`. */
+const RE_CONST_REQUIRE =
+  /(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*(['"])([^'"]+)\2\s*\)/g
+
+/** Pattern for destructured `const { a, b } = require('...')`. */
+const RE_DESTRUCT_REQUIRE =
+  /(?:const|let|var)\s*\{([^}]+)\}\s*=\s*require\(\s*(['"])([^'"]+)\2\s*\)/g
+
+/**
+ * Convert a CommonJS module's source to ESM.
+ *
+ * @param {string} src  Original CommonJS source.
+ * @returns {string}    ESM source.
+ */
+export function transformToESM(src) {
+  let out = src
+  // 1. const X = require('mod') → import X from 'mod'
+  out = out.replace(RE_CONST_REQUIRE, (_, name, _q, mod) => `import ${name} from '${mod}'`)
+  // 2. const { a, b } = require('mod') → import { a, b } from 'mod'
+  out = out.replace(RE_DESTRUCT_REQUIRE, (_, names, _q, mod) => {
+    const cleaned = names
+      .split(',')
+      .map((n) => n.trim())
+      .filter(Boolean)
+      .map((n) => (n.includes(':') ? n : n))
+      .join(', ')
+    return `import { ${cleaned} } from '${mod}'`
+  })
+  // 3. Bare require('mod') → import 'mod'
+  out = out.replace(RE_REQUIRE, (_, _q, mod) => `import '${mod}'`)
+  // 4. module.exports = X → export default X
+  out = out.replace(RE_MODULE_EXPORTS_ASSIGN, 'export default ')
+  // 5. exports.x = ... → export const x = ...
+  out = out.replace(RE_EXPORTS_DOT, (_, name) => `export const ${name} = `)
+  // 6. 'use strict' is implicit in ESM — drop it.
+  out = out.replace(/^['"]use strict['"];?\s*\n/m, '')
+  return out
+}
+
+/**
+ * Apply every known WAProto fix to a single file's content.
+ *
+ * @param {string} filename  Absolute path of the file being patched.
+ * @param {string} content   Current file content.
+ * @returns {{ content: string, applied: string[] }}  New content + list of fix names that fired.
+ */
+export function applyKnownFixes(filename, content) {
+  const applied = []
+  let next = content
+  for (const fix of KNOWN_FIXES) {
+    if (fix.file.test(filename)) {
+      const before = next
+      next = fix.apply(next)
+      if (next !== before) applied.push(fix.name)
+    }
+  }
+  return { content: next, applied }
+}
+
+/**
+ * ProtoUpdater — high-level orchestration.
+ */
+export class ProtoUpdater {
+  /** @param {object} [opts] */
+  constructor(opts = {}) {
+    this.protoPath = path.resolve(opts.protoPath ?? this.#defaultProtoPath())
+    this.backupDir = path.resolve(opts.backupDir ?? path.join(this.protoPath, '..', 'WAProto.backups'))
+    this.logger = (opts.logger ?? createLogger({ level: 'warn' })).child('proto-updater')
+    /** @type {Array<{ id: string, timestamp: number, path: string, hash: string }>} */
+    this.history = []
+  }
+
+  /** Resolve the default WAProto directory inside the installed Baileys package. */
+  #defaultProtoPath() {
+    try {
+      const baileysPkg = require.resolve('@whiskeysockets/baileys/package.json', {
+        paths: [process.cwd()],
+      })
+      return path.join(path.dirname(baileysPkg), 'WAProto')
+    } catch {
+      // Fallback: assume CWD/WAProto
+      return path.join(process.cwd(), 'WAProto')
+    }
+  }
+
+  /**
+   * Walk a directory recursively, returning every `.js` file path.
+   *
+   * @param {string} dir
+   * @returns {Promise<string[]>}
+   */
+  async #listJsFiles(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true })
+    const out = []
+    for (const e of entries) {
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) out.push(...(await this.#listJsFiles(full)))
+      else if (e.isFile() && e.name.endsWith('.js')) out.push(full)
+    }
+    return out
+  }
+
+  /**
+   * Create a timestamped backup of the current WAProto tree.
+   *
+   * @returns {Promise<{ id: string, timestamp: number, path: string, hash: string }>}
+   */
+  async backup() {
+    await fs.mkdir(this.backupDir, { recursive: true })
+    const timestamp = Date.now()
+    const id = `backup-${timestamp}`
+    const dest = path.join(this.backupDir, id)
+    await fs.cp(this.protoPath, dest, { recursive: true })
+
+    const hash = await this.#hashTree(dest)
+    const record = { id, timestamp, path: dest, hash }
+    this.history.push(record)
+    this.logger.info(`backup created: ${id} (sha256=${hash.slice(0, 12)}…)`)
+    return record
+  }
+
+  /**
+   * Recursively hash every `.js` file in a directory. Used to detect
+   * whether a transform actually changed anything.
+   *
+   * @param {string} dir
+   * @returns {Promise<string>}
+   */
+  async #hashTree(dir) {
+    const files = (await this.#listJsFiles(dir)).sort()
+    const hashes = await Promise.all(
+      files.map(async (f) => {
+        const c = await fs.readFile(f, 'utf8')
+        return `${path.relative(dir, f)}:${sha256(c)}`
+      }),
+    )
+    return sha256(hashes.join('\n'))
+  }
+
+  /**
+   * Restore a specific backup by id.
+   *
+   * @param {string} id
+   */
+  async restore(id) {
+    const record = this.history.find((h) => h.id === id)
+    if (!record) {
+      throw new ProtocolError(`backup not found: ${id}`, { code: 'LUMINA_PROTOCOL_BACKUP_NOT_FOUND' })
+    }
+    await fs.rm(this.protoPath, { recursive: true, force: true })
+    await fs.cp(record.path, this.protoPath, { recursive: true })
+    this.logger.warn(`restored backup: ${id}`)
+  }
+
+  /**
+   * Rollback to the most recent successful backup.
+   */
+  async rollback() {
+    if (this.history.length === 0) {
+      throw new ProtocolError('no backup available for rollback', {
+        code: 'LUMINA_PROTOCOL_NO_BACKUP',
+      })
+    }
+    const last = this.history[this.history.length - 1]
+    await this.restore(last.id)
+  }
+
+  /**
+   * Validate the current WAProto tree by importing every `.js` file.
+   *
+   * @returns {Promise<{ ok: boolean, errors: Array<{ file: string, message: string }> }>}
+   */
+  async validate() {
+    const files = await this.#listJsFiles(this.protoPath)
+    const errors = []
+    await Promise.all(
+      files.map(async (f) => {
+        try {
+          await import(pathToFileURL(f).href)
+        } catch (err) {
+          errors.push({ file: path.relative(this.protoPath, f), message: err?.message ?? String(err) })
+        }
+      }),
+    )
+    return { ok: errors.length === 0, errors }
+  }
+
+  /**
+   * Run the full update pipeline: backup → transform → fix → validate → commit/rollback.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.autoRollback=true]   Rollback automatically on validation failure.
+   * @param {boolean} [opts.dryRun=false]        Don't write to disk — return a diff summary.
+   * @returns {Promise<{ success: boolean, fromHash: string, toHash: string, backupId: string|null, appliedFixes: string[], errors: any[] }>}
+   */
+  async update(opts = {}) {
+    const autoRollback = opts.autoRollback ?? true
+    const dryRun = opts.dryRun ?? false
+
+    const fromHash = await this.#hashTree(this.protoPath)
+    const files = await this.#listJsFiles(this.protoPath)
+
+    let backupId = null
+    if (!dryRun) {
+      const backup = await this.backup()
+      backupId = backup.id
+    }
+
+    const appliedFixes = new Set()
+    const errors = []
+
+    for (const file of files) {
+      try {
+        const original = await fs.readFile(file, 'utf8')
+        const transformed = transformToESM(original)
+        const fixed = applyKnownFixes(file, transformed)
+        fixed.applied.forEach((n) => appliedFixes.add(n))
+
+        if (!dryRun && fixed.content !== original) {
+          await fs.writeFile(file, fixed.content, 'utf8')
+        }
+      } catch (err) {
+        errors.push({ file: path.relative(this.protoPath, file), message: err?.message ?? String(err) })
+      }
+    }
+
+    const toHash = dryRun ? fromHash : await this.#hashTree(this.protoPath)
+
+    if (dryRun) {
+      this.logger.info(`dry-run complete: ${appliedFixes.size} fixes would apply, ${errors.length} errors`)
+      return { success: errors.length === 0, fromHash, toHash: fromHash, backupId: null, appliedFixes: [...appliedFixes], errors }
+    }
+
+    const validation = await this.validate()
+    if (!validation.ok) {
+      errors.push(...validation.errors)
+      if (autoRollback && backupId) {
+        this.logger.warn(`validation failed (${validation.errors.length} errors) — rolling back`)
+        await this.rollback()
+        return { success: false, fromHash, toHash: fromHash, backupId, appliedFixes: [...appliedFixes], errors }
+      }
+    }
+
+    this.logger.info(`update complete: ${appliedFixes.size} fixes applied, hash ${fromHash.slice(0, 8)} → ${toHash.slice(0, 8)}`)
+    return { success: errors.length === 0, fromHash, toHash, backupId, appliedFixes: [...appliedFixes], errors }
+  }
+}
+
+export default ProtoUpdater

package/src/services/index.d.ts

@@ -0,0 +1 @@
+export * from '../index.d.ts'

package/src/services/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file services/index.js
+ * @module lumina/services
+ *
+ * Barrel re-export for the services layer.
+ */
+
+export { MediaService } from './media-service.js'
+export { ProtoService } from './proto-service.js'
+export { MessageService } from './message-service.js'

package/src/services/media-service.js

@@ -0,0 +1,184 @@
+/**
+ * @file media-service.js
+ * @module lumina/services/media-service
+ *
+ * High-level orchestrator for every media operation. Composes the lower-level
+ * `media/*` modules with a Connection instance and (optionally) a small LRU
+ * cache for repeated URL fetches.
+ */
+
+import { fetchBuffer } from '../media/fetch.js'
+import { resize, thumbnail } from '../media/image.js'
+import { getMp4Duration, extractThumbnail } from '../media/video.js'
+import { uploadToWhatsApp } from '../media/uploader.js'
+import { resolveMedia } from '../media/resolver.js'
+import { sniffMime, mimeToCategory } from '../utils/mime.js'
+
+/** @typedef {import('../client/connection.js').Connection} Connection */
+/** @typedef {import('../utils/logger.js').Logger} Logger */
+
+const LRU_MAX = 128
+
+/**
+ * @typedef {object} MediaServiceOptions
+ * @property {boolean} [cache=true]      Enable URL→buffer LRU cache.
+ * @property {number}  [cacheMax=128]    Max cache entries.
+ * @property {Logger}  [logger]
+ * @property {string}  [uploadJid]
+ */
+
+export class MediaService {
+  /**
+   * @param {Connection} conn
+   * @param {MediaServiceOptions} [opts]
+   */
+  constructor(conn, opts = {}) {
+    if (!conn) throw new Error('Connection is required for MediaService')
+    this.conn = conn
+    this.logger = opts.logger?.child('media')
+    this.uploadJid = opts.uploadJid
+    this.#cacheEnabled = opts.cache ?? true
+    this.#cacheMax = opts.cacheMax ?? LRU_MAX
+    /** @type {Map<string, { buf: Buffer, ts: number }>} */
+    this.#cache = new Map()
+  }
+
+  /** @type {boolean} */
+  #cacheEnabled
+  /** @type {number} */
+  #cacheMax
+  /** @type {Map<string, { buf: Buffer, ts: number }>} */
+  #cache
+
+  /**
+   * @param {string} url
+   * @returns {Buffer | undefined}
+   */
+  #cacheGet(url) {
+    if (!this.#cacheEnabled) return undefined
+    const entry = this.#cache.get(url)
+    if (!entry) return undefined
+    // Refresh LRU order.
+    this.#cache.delete(url)
+    this.#cache.set(url, entry)
+    return entry.buf
+  }
+
+  /**
+   * @param {string} url
+   * @param {Buffer} buf
+   */
+  #cacheSet(url, buf) {
+    if (!this.#cacheEnabled) return
+    if (this.#cache.size >= this.#cacheMax) {
+      const oldest = this.#cache.keys().next().value
+      this.#cache.delete(oldest)
+    }
+    this.#cache.set(url, { buf, ts: Date.now() })
+  }
+
+  /**
+   * Fetch a URL into a Buffer. Uses the cache when enabled.
+   *
+   * @param {string} url
+   * @param {object} [opts]   Forwarded to fetchBuffer.
+   * @returns {Promise<Buffer>}
+   */
+  async fetch(url, opts) {
+    const cached = this.#cacheGet(url)
+    if (cached) return cached
+    const buf = await fetchBuffer(url, opts)
+    if (buf.length) this.#cacheSet(url, buf)
+    return buf
+  }
+
+  /**
+   * Resize an image buffer.
+   *
+   * @param {Buffer} buf
+   * @param {object} opts
+   * @returns {Promise<Buffer>}
+   */
+  async resize(buf, opts) {
+    return resize(buf, opts)
+  }
+
+  /**
+   * Generate a square thumbnail.
+   *
+   * @param {Buffer} buf
+   * @param {number} [size=300]
+   * @param {'png'|'jpeg'|'webp'} [format]
+   * @returns {Promise<Buffer>}
+   */
+  async thumbnail(buf, size, format) {
+    return thumbnail(buf, size, format)
+  }
+
+  /**
+   * Get MP4 duration in seconds. Returns 0 on failure (silent default).
+   *
+   * @param {Buffer} buf
+   * @returns {number}
+   */
+  duration(buf) {
+    return getMp4Duration(buf)
+  }
+
+  /**
+   * Extract a thumbnail frame from a video buffer.
+   *
+   * @param {Buffer} buf
+   * @param {object} [opts]
+   * @returns {Promise<Buffer|string>}
+   */
+  async videoThumbnail(buf, opts) {
+    return extractThumbnail(buf, opts)
+  }
+
+  /**
+   * Upload a buffer to WhatsApp.
+   *
+   * @param {Buffer | { url: string }} source
+   * @param {'image'|'video'|'audio'|'document'} mediaType
+   * @param {object} [opts]
+   * @returns {Promise<string>}
+   */
+  async upload(source, mediaType, opts) {
+    return uploadToWhatsApp(this.conn, source, mediaType, { jid: this.uploadJid, ...opts })
+  }
+
+  /**
+   * Resolve a media source (URL | base64 | Buffer | array) per strategy.
+   *
+   * @param {string | Buffer | Array} source
+   * @param {object} [opts]
+   * @returns {Promise<string | Buffer | Array<string | Buffer>>}
+   */
+  async resolve(source, opts) {
+    return resolveMedia(this.conn, source, opts)
+  }
+
+  /**
+   * Convenience: sniff MIME from a buffer.
+   *
+   * @param {Buffer} buf
+   * @param {string} [filename]
+   * @returns {string}
+   */
+  sniff(buf, filename) {
+    return sniffMime(buf, filename)
+  }
+
+  /**
+   * Convenience: derive WA media category from MIME.
+   *
+   * @param {string} mime
+   * @returns {'image'|'video'|'audio'|'document'}
+   */
+  category(mime) {
+    return mimeToCategory(mime)
+  }
+}
+
+export default MediaService