@kyyinfinite/lumina 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KyyInfinite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,629 @@
+# @kyyinfinite/lumina
+
+> Modern WhatsApp framework built on top of [Baileys](https://github.com/WhiskeySockets/Baileys).
+> Hide the protocol complexity, expose a fluent API.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node: >=20](https://img.shields.io/badge/Node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+[![Module: ESM](https://img.shields.io/badge/Module-ESM-blue.svg)](https://nodejs.org/api/esm.html)
+[![TypeScript](https://img.shields.io/badge/TypeScript-typed-blue.svg)](#typescript)
+
+Lumina is **not** a helper. Lumina is **not** a thin wrapper.
+
+Lumina is an abstraction layer that absorbs **all** the complexity of WhatsApp
+Web's binary protocol — `WAProto`, `generateWAMessageFromContent`,
+`relayMessage`, `prepareWAMessageMedia`, Native Flow, Interactive Message,
+Rich Response, ContextInfo, media upload, and proto generation — so that
+developers can focus on building bots.
+
+```js
+import { Bot } from '@kyyinfinite/lumina'
+
+const bot = new Bot(socket)
+
+await bot.text(jid, 'Halo')
+
+await bot.button()
+  .title('Lumina')
+  .body('Pilih menu')
+  .reply('Menu', 'menu_cmd')
+  .url('Website', 'https://github.com/kyyinfinite/lumina')
+  .send(jid)
+
+await bot.ai()
+  .text('Cek [dokumentasi](https://github.com/kyyinfinite/lumina)')
+  .code('javascript', 'console.log("hi")')
+  .image('https://picsum.photos/600/300')
+  .table([['Name', 'Score'], ['A', '90'], ['B', '85']])
+  .suggest(['Lanjut', 'Ulang'])
+  .send(jid)
+```
+
+---
+
+## Table of Contents
+
+- [Install](#install)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Basic Usage](#basic-usage)
+- [Builder Usage](#builder-usage)
+  - [Button](#button)
+  - [Carousel](#carousel)
+  - [AI Rich](#ai-rich)
+- [Media](#media)
+- [Proto Update](#proto-update)
+- [TypeScript](#typescript)
+- [API Reference](#api-reference)
+- [Migration](#migration)
+- [Best Practice](#best-practice)
+- [FAQ](#faq)
+
+---
+
+## Install
+
+```bash
+# npm
+npm install @kyyinfinite/lumina @whiskeysockets/baileys
+
+# pnpm
+pnpm add @kyyinfinite/lumina @whiskeysockets/baileys
+
+# yarn
+yarn add @kyyinfinite/lumina @whiskeysockets/baileys
+```
+
+Optional peer dependencies (lazy-loaded only when needed):
+
+```bash
+# For image resizing (PNG/JPEG/WebP):
+npm install sharp
+
+# For video thumbnail extraction:
+npm install fluent-ffmpeg
+# Plus the ffmpeg binary itself: https://ffmpeg.org/download.html
+```
+
+Requirements:
+- Node.js ≥ 20
+- WhatsApp Web socket via `@whiskeysockets/baileys` ≥ 6.7
+
+---
+
+## Features
+
+- **Fluent, verb-first API** — `bot.text()`, `button.title().body().reply().send()`.
+- **5 interactive builders** — Button (native flow), ButtonV2 (legacy), Carousel, Card, AI Rich.
+- **AI Rich Response** with 11 primitives: text, code, table, image, video, source, reels, product, post, tip, suggest.
+- **Media toolkit** — fetch, resize, thumbnail, MP4 duration, ffmpeg frame extractor, WA upload, base64/URL/Buffer strategies.
+- **Inline entity parser** — auto-extract `[text](url)`, `[](url)`, `[text]<url|w|h|fh|p>` to interactive citations/hyperlinks/latex.
+- **Code tokenizer** — syntax highlighting for 13 languages (JS/TS/Python/Java/Go/C/C++/PHP/Rust/HTML/CSS/Bash/Markdown).
+- **ProtoUpdater** — automatic WAProto maintenance (CJS→ESM transform, HistorySyncType fix, backup/restore/rollback).
+- **Catalog-driven** — every magic number, `__typename`, and version string lives in one file (`proto/enums.js`).
+- **TypeScript-first** — manual `.d.ts` with full typing for every public surface.
+- **Tree-shakable** — subpath exports for `parsers`, `media`, `proto`, `services`, `builders`.
+- **Error hierarchy** — `LuminaError` → `ValidationError | MediaError | ProtoError | ConnectionError | ProtocolError`.
+- **Optional logger** — inject pino/winston subset, or use the built-in no-op default.
+- **Eager async** — every `add*()` is awaited immediately; no race conditions on stored Promises.
+- **Zero personal leftovers** — every hardcoded value is parameterised or removed.
+
+---
+
+## Quick Start
+
+```js
+import makeWASocket from '@whiskeysockets/baileys'
+import { useMultiFileAuthState } from '@whiskeysockets/baileys'
+import { Bot } from '@kyyinfinite/lumina'
+
+const { state, saveCreds } = await useMultiFileAuthState('./.auth')
+const socket = makeWASocket.default({ auth: state, printQRInTerminal: true })
+
+const bot = new Bot(socket, {
+  uploadJid: '62831@s.whatsapp.net', // optional, defaults to a permissive bot JID
+})
+
+socket.ev.on('creds.update', saveCreds)
+
+bot.on('messages.upsert', async ({ messages }) => {
+  const m = messages[0]
+  if (!m?.message || m.key.fromMe) return
+
+  const text = m.message.conversation ?? m.message.extendedTextMessage?.text ?? ''
+  if (text.toLowerCase() === 'ping') {
+    await bot.text(m.key.remoteJid, 'pong 🏓')
+  }
+})
+```
+
+---
+
+## Basic Usage
+
+```js
+const jid = '62812xxxxxxx@s.whatsapp.net'
+
+await bot.text(jid, 'Halo!')
+await bot.image(jid, 'image.jpg', 'Caption opsional')
+await bot.video(jid, 'video.mp4', 'Video caption')
+await bot.audio(jid, 'audio.mp3')
+await bot.document(jid, 'file.pdf')
+await bot.sticker(jid, 'sticker.webp')
+
+await bot.contact(jid, [{ name: 'Andi', number: '62812xxxxxxx' }])
+await bot.location(jid, -6.2, 106.8, { name: 'Jakarta', address: 'Indonesia' })
+await bot.poll(jid, 'Pilih menu', ['A', 'B', 'C'], { selectableCount: 1 })
+
+await bot.reply(jid, 'Reply text', quotedMessage)
+await bot.react(jid, msgKey, '👍')
+await bot.delete(jid, msgKey)
+await bot.forward(jid, originalMessage)
+await bot.copy(jid, originalMessage)
+await bot.edit(jid, msgKey, 'edited text')
+```
+
+---
+
+## Builder Usage
+
+### Button
+
+Native-flow interactive message with chainable API.
+
+```js
+await bot.button()
+  .title('Lumina')
+  .subtitle('Demo')
+  .body('Pilih menu di bawah')
+  .footer('Powered by Lumina')
+  .image('https://picsum.photos/600/300')
+  .reply('Menu Utama', 'cmd_menu')
+  .reply('Owner', 'cmd_owner')
+  .url('Website', 'https://github.com/kyyinfinite/lumina')
+  .copy('Salin Token', 'LUMINA-TOKEN')
+  .call('Hubungi CS', '62812xxxxxxx')
+  .send(jid)
+```
+
+Selection with sections & rows (callback-based, no mutable state):
+
+```js
+await bot.button()
+  .body('Pilih kategori:')
+  .selection('Kategori', (sel) => sel
+    .section('Makanan', (s) => s
+      .row('Nasi Goreng', 'Nasi Goreng Special', 'Rp 25.000', 'food_nasgor')
+      .row('Mie Ayam', 'Mie Ayam Bakso', 'Rp 20.000', 'food_mieayam'))
+    .section('Minuman', (s) => s
+      .row('Es Teh', 'Es Teh Manis', 'Rp 5.000', 'drink_esteh')))
+  .send(jid)
+```
+
+### Carousel
+
+Multi-card carousel with per-card buttons.
+
+```js
+const carousel = bot.carousel().body('Pilih produk:')
+
+for (const p of products) {
+  const card = await carousel
+    .newCard()
+    .title(p.name)
+    .body(p.price)
+    .image(p.image)
+    .reply('Beli', p.cmd)
+    .build()
+  carousel.card(card)
+}
+
+await carousel.send(jid)
+```
+
+### AI Rich
+
+AI Rich Response — the most powerful builder. 11 primitives, fully chainable.
+
+```js
+await bot.ai()
+  .title('AI Assistant')
+  .footer('Generated by Lumina')
+  .text('Halo! Cek [dokumentasi](https://github.com/kyyinfinite/lumina).')
+  .code('javascript', 'console.log("hi")')
+  .image('https://picsum.photos/600/300')
+  .table([
+    ['Fitur', 'Status'],
+    ['Text', '✓'],
+    ['Image', '✓'],
+  ])
+  .tip('Tip: pakai fluent API untuk chaining yang bersih.')
+  .suggest(['Lanjut', 'Ulang'])
+  .source([
+    ['https://favicon.io/favicon.png', 'https://github.com', 'GitHub'],
+  ])
+  .product({
+    title: 'Sepatu Lumina',
+    brand: 'Lumina',
+    price: 'Rp 250.000',
+    url: 'https://example.com/1',
+    image_url: 'https://picsum.photos/400/400',
+  })
+  .send(jid)
+```
+
+---
+
+## Media
+
+The `MediaService` (`bot.media`) handles every media operation:
+
+```js
+// Fetch a URL into a Buffer (with built-in LRU cache).
+const buf = await bot.media.fetch('https://example.com/image.png')
+
+// Resize an image.
+const thumb = await bot.media.resize(buf, { width: 200, height: 200, format: 'jpeg' })
+
+// Square thumbnail helper.
+const sq = await bot.media.thumbnail(buf, 300, 'png')
+
+// MP4 duration (no native deps — pure ISO-BMFF box parser).
+const seconds = bot.media.duration(videoBuf)
+
+// Extract a video frame via ffmpeg.
+const frameB64 = await bot.media.videoThumbnail(videoBuf, { time: 0, result: 'base64' })
+
+// Upload to WhatsApp CDN.
+const cdnUrl = await bot.media.upload(buf, 'image')
+
+// Resolve any source (URL | base64 | Buffer | array) per strategy.
+const resolved = await bot.media.resolve(source, {
+  mediaType: 'image',         // 'image' | 'video' | 'audio' | 'document'
+  strategy: 'auto',           // 'auto' | 'url-only' | 'buffer' | 'base64' | 'upload'
+  resize: { width: 300, height: 300, fit: 'cover' },
+})
+
+// Sniff MIME from buffer magic bytes.
+const mime = bot.media.sniff(buf, 'photo.jpg')
+const category = bot.media.category(mime) // 'image' | 'video' | 'audio' | 'document'
+```
+
+---
+
+## Proto Update
+
+Lumina ships `ProtoUpdater` for refreshing `@whiskeysockets/baileys/WAProto`
+with safety net:
+
+```js
+import { ProtoUpdater } from '@kyyinfinite/lumina'
+
+const updater = new ProtoUpdater({
+  protoPath: './node_modules/@whiskeysockets/baileys/WAProto',
+  backupDir: './.wa-proto-backups',
+})
+
+// Dry-run: see what would change without writing.
+const dryRun = await updater.update({ dryRun: true })
+console.log(dryRun.appliedFixes)
+
+// Real update with auto-rollback on validation failure.
+const result = await updater.update({ autoRollback: true })
+if (!result.success) {
+  console.error('update failed, rolled back:', result.errors)
+}
+```
+
+What it does:
+
+1. **Backup** the current WAProto tree (timestamped, SHA-256-hashed).
+2. **Transform** every `.js` file from CommonJS to ESM:
+   - `require('x')` → `import ... from 'x'`
+   - `module.exports = x` → `export default x`
+   - `exports.x = ...` → `export const x = ...`
+3. **Apply known fixes**:
+   - `HistorySyncType.INITIAL_BOOTSTRAP = 0` (some `pbjs` runs emit `= 1`)
+   - `RecentMessagesWeightInheritance.CHRONOLOGICAL = 1`
+4. **Validate** by `import()`-ing every transformed file.
+5. **Rollback** automatically if validation fails (unless `autoRollback: false`).
+
+---
+
+## TypeScript
+
+Lumina ships a **manually-authored** `.d.ts` (no auto-generated noise) with
+full typing for every public surface:
+
+```ts
+import { Bot, AIRichBuilder, ButtonBuilder, LuminaError } from '@kyyinfinite/lumina'
+
+const bot: Bot = new Bot(socket)
+
+const builder: AIRichBuilder = bot.ai()
+await builder.text('hi').code('javascript', 'console.log(1)').send(jid)
+
+try {
+  await bot.text(jid, 'hello')
+} catch (err) {
+  if (err instanceof LuminaError) {
+    console.error(err.code, err.module, err.message)
+  }
+}
+```
+
+Type-checked features:
+
+- Every builder method returns `this` (chainable)
+- `AIRichBuilder.add*()` methods return `Promise<this>` (eager async)
+- Error classes carry `code: string` and `module: string`
+- Enum-like catalogs (`MessageType`, `HeaderType`, `LayoutKind`, ...) are `Readonly`
+- `Bot.raw` escape hatch typed as `WASocket`
+
+---
+
+## API Reference
+
+### `Bot`
+
+| Method | Returns | Description |
+|---|---|---|
+| `text(jid, text, opts?)` | `Promise<WAMessage>` | Send a plain text message. |
+| `image(jid, source, caption?, opts?)` | `Promise<WAMessage>` | Send an image. |
+| `video(jid, source, caption?, opts?)` | `Promise<WAMessage>` | Send a video. |
+| `audio(jid, source, opts?)` | `Promise<WAMessage>` | Send an audio file. |
+| `document(jid, source, opts?)` | `Promise<WAMessage>` | Send a document. |
+| `sticker(jid, source, opts?)` | `Promise<WAMessage>` | Send a sticker. |
+| `contact(jid, contacts, opts?)` | `Promise<WAMessage>` | Send one or more contacts. |
+| `location(jid, lat, lng, opts?)` | `Promise<WAMessage>` | Send a location pin. |
+| `poll(jid, name, options, opts?)` | `Promise<WAMessage>` | Send a poll. |
+| `reply(jid, text, quoted, opts?)` | `Promise<WAMessage>` | Reply to a quoted message. |
+| `react(jid, key, emoji, opts?)` | `Promise<WAMessage>` | React with an emoji. |
+| `delete(jid, key)` | `Promise<void>` | Delete (revoke) a message. |
+| `forward(jid, message, opts?)` | `Promise<WAMessage>` | Forward a message. |
+| `copy(jid, message, opts?)` | `Promise<WAMessage>` | Copy a message's content. |
+| `edit(jid, key, newText, opts?)` | `Promise<WAMessage>` | Edit a previously sent message. |
+| `button()` | `ButtonBuilder` | Create a native-flow button builder. |
+| `buttonV2()` | `ButtonV2Builder` | Create a legacy buttonsMessage builder. |
+| `carousel()` | `CarouselBuilder` | Create a carousel builder. |
+| `ai()` | `AIRichBuilder` | Create an AI Rich Response builder. |
+| `on(event, handler)` | `() => void` | Subscribe to a Baileys event. Returns unsubscriber. |
+| `once(event, handler)` | `() => void` | Subscribe once. |
+| `off(event, handler)` | `void` | Unsubscribe. |
+| `raw` | `WASocket` | Escape hatch to the underlying Baileys socket. |
+
+### `ButtonBuilder`
+
+Content methods: `title`, `subtitle`, `body`, `footer`, `contextInfo`, `payload`.
+
+Media: `media(type, source, opts?)`, `image(src, opts?)`, `video(src, opts?)`, `document(src, opts?)`.
+
+Buttons: `reply`, `call`, `reminder`, `cancelReminder`, `address`, `url`, `copy`, `location`, `selection`, `button` (generic), `params`, `clear`.
+
+Lifecycle: `toCard()`, `build(jid, opts?)`, `send(jid, opts?)`.
+
+### `CarouselBuilder`
+
+Content: `body`, `footer`, `contextInfo`, `payload`.
+
+Cards: `newCard()` → `CardBuilder`, `card(card | card[])`, `cards(...cards)`.
+
+Lifecycle: `build(jid, opts?)`, `send(jid, opts?)`.
+
+### `AIRichBuilder`
+
+Envelope: `title`, `footer`, `contextInfo`, `payload`, `forwarded(v?)`, `notification(v)`, `quoted(q, participant?)`, `includesUnifiedResponse(v?)`, `includesSubmessages(v?)`, `submessage(msg)`.
+
+Primitives (all `Promise<this>`): `text`, `code`, `table`, `image`, `video`, `source`, `reels`, `product`, `post`, `tip`, `suggest`.
+
+Lifecycle: `build(opts?)` → `Promise<object>`, `send(jid, opts?)` → `Promise<string>`.
+
+### `MediaService`
+
+`fetch`, `resize`, `thumbnail`, `duration`, `videoThumbnail`, `upload`, `resolve`, `sniff`, `category`.
+
+### `ProtoUpdater`
+
+`backup()`, `restore(id)`, `rollback()`, `validate()`, `update(opts?)`.
+
+### Errors
+
+`LuminaError` (base), `ValidationError`, `MediaError`, `ProtoError`, `ConnectionError`, `ProtocolError`.
+
+Each carries `code: string`, `module: string`, and the ES2022 `cause` field.
+
+---
+
+## Migration
+
+Migrating from the legacy `_build-m.js`?
+
+| Legacy | Lumina |
+|---|---|
+| `new Button(socket)` | `bot.button()` |
+| `setTitle(x)` / `setBody(x)` | `.title(x)` / `.body(x)` |
+| `setVideo(path)` / `setImage(path)` / `setDocument(path)` | `.video(src)` / `.image(src)` / `.document(src)` (or unified `.media(type, src)`) |
+| `addReply(text, id)` | `.reply(text, id)` |
+| `addUrl(text, url, webview)` | `.url(text, url, { webview_interaction })` |
+| `addSelection(title)` + `makeSection()` + `makeRow()` | `.selection(title, sel => sel.section('...', s => s.row(...)))` |
+| `new Carousel(socket).addCard(card)` | `bot.carousel().card(await carousel.newCard()....build())` |
+| `new AIRich(socket).addText(...)` | `bot.ai().text(...)` (await) |
+| `Toolkit.resize(buf, w, h)` | `bot.media.resize(buf, { width: w, height: h })` |
+| `Toolkit.fetchBuffer(url, {}, { silent: true })` | `bot.media.fetch(url, { silent: true })` |
+| `Toolkit.resolveMedia(client, src, 'image')` | `bot.media.resolve(src, { mediaType: 'image' })` |
+| `Toolkit.getMp4Duration(buf)` | `bot.media.duration(buf)` |
+| `Toolkit.getMp4Preview(buf, { time: 0 })` | `bot.media.videoThumbnail(buf, { time: 0 })` |
+| `Toolkit.toUrl(client, path, 'image')` | `bot.media.upload(path, 'image')` |
+| `Toolkit.extractIE(text, opts)` | `bot.util.extractInlineEntities(text, opts)` (or `extractInlineEntities` from `@kyyinfinite/lumina/parsers`) |
+| `AIRich.tokenizer(code, lang)` | `bot.util.tokenizeCode(code, lang)` |
+| `AIRich.toTableMetadata(arr)` | `bot.util.toTableMetadata(arr)` |
+| `AIRich.newLayout('Single', data)` | `singleLayout(data)` from `@kyyinfinite/lumina/proto` |
+
+### Behavioral changes
+
+- **Eager async**: every `add*()` / `text()` / `image()` on `AIRichBuilder` is `async` and resolves media immediately. You must `await` each call. The legacy "store Promise, resolve at build()" pattern is gone.
+- **No `NIXEL_` prefix**: inline entity keys are now `LUMINA_HYPERLINK_0`, `LUMINA_CITATION_1`, `LUMINA_LATEX_0`. Override via `extractInlineEntities(text, { prefix: 'CUSTOM' })`.
+- **No `disclaimerText: '~ Ahmad tumbuh kembang'`**: that personal leftover is gone. Set your own via `ai.notification({ disclaimerText: 'Your disclaimer' })`.
+- **`GenATableUXPrimitive` typo corrected** → `GenAITableUXPrimitive` (verified against current WhatsApp Web wire format).
+- **`Carousel.send()`** now properly awaits `build()` (was missing in legacy).
+- **`@newsletter` jid** for media upload is no longer hardcoded. Configure via `new Bot(socket, { uploadJid })` or per-call `bot.media.upload(src, type, { jid })`.
+- **`Button.paramsList` dead code** removed.
+
+---
+
+## Best Practice
+
+### Do
+
+- **Await every `add*()` on AIRichBuilder.** They're async by design — chaining without `await` will silently drop primitives.
+  ```js
+  // Correct
+  await bot.ai().text('a').text('b').send(jid)
+
+  // Wrong — text() returns a Promise, .text('b') is undefined
+  bot.ai().text('a').text('b').send(jid)
+  ```
+
+- **Reuse `bot` across handlers.** Constructing a `Bot` per message wastes the LRU cache and re-runs the Baileys API surface check.
+
+- **Inject a logger in development.**
+  ```js
+  const bot = new Bot(socket, {
+    logger: createLogger({ level: 'debug' }),
+  })
+  ```
+
+- **Use subpath imports for utilities** to keep your bundle small:
+  ```js
+  import { extractInlineEntities } from '@kyyinfinite/lumina/parsers'
+  ```
+
+- **Catch `LuminaError`** for graceful fallback:
+  ```js
+  try {
+    await bot.image(jid, 'https://broken-url.example/x.png')
+  } catch (err) {
+    if (err instanceof MediaError) {
+      await bot.text(jid, 'Image unavailable.')
+    }
+  }
+  ```
+
+### Don't
+
+- **Don't touch `bot.raw`** unless absolutely necessary. It bypasses every Lumina abstraction and will break on Baileys upgrades.
+
+- **Don't call `bot.button()`/`bot.ai()`/... inside a hot loop without `await`** — each call returns a fresh builder; not awaiting it will orphan primitives.
+
+- **Don't pass non-WA URLs to `strategy: 'url-only'`** — that strategy only accepts `*.whatsapp.net` URLs. Use `'auto'` (default) for everything else.
+
+- **Don't rely on `GenATableUXPrimitive`** (the typo). Use the catalog: `import { TYPENAME } from '@kyyinfinite/lumina/proto'`.
+
+---
+
+## FAQ
+
+### Is Lumina compatible with CJS (`require`)?
+
+No. Lumina is **ESM-only**. Node 20+ supports ESM natively. If you're stuck on CJS, use dynamic `import()`:
+
+```js
+async function main() {
+  const { Bot } = await import('@kyyinfinite/lumina')
+  // ...
+}
+```
+
+### Do I need `sharp` and `ffmpeg`?
+
+Only if you use the features that depend on them:
+
+- `sharp` — required for `bot.media.resize()`, `bot.media.thumbnail()`, and any AI Rich primitive that resizes images. Lazy-loaded.
+- `fluent-ffmpeg` + ffmpeg binary — required for `bot.media.videoThumbnail()`. Lazy-loaded.
+
+If you never call those methods, neither dependency needs to be installed.
+
+### Why is `AIRichBuilder.text()` async?
+
+Because it parses inline entities synchronously (cheap) **and** the parent
+class supports primitives that resolve media asynchronously (`image`,
+`video`, `product`, `post`, `reels`). Forcing every primitive through an
+async signature keeps the API uniform and prevents the legacy anti-pattern
+of storing Promise objects inside the builder's state.
+
+### How do I customise the `botJid` for forwarded AI messages?
+
+You can't — WhatsApp requires `0@bot` for the AI bot metadata to render
+correctly. If WhatsApp ever changes this, update `proto/enums.BOT_JID` and
+the whole framework follows.
+
+### How do I add a new language to the code tokenizer?
+
+Append a `Set` of keywords to `src/parsers/code-tokenizer-keywords.js`:
+
+```js
+export const KEYWORDS = {
+  // ...
+  kotlin: new Set(['fun', 'val', 'var', 'class', 'object', 'when', /* ... */]),
+}
+```
+
+`tokenizeCode('kotlin', code)` will pick it up automatically.
+
+### How do I add a new native-flow button type?
+
+For "simple" types (params = `{ display_text, id, ...opts }`):
+
+```js
+// In src/builders/button.js
+const SIMPLE_BUTTON_TYPES = {
+  // ...
+  myCustomButton: 'cta_my_custom',
+}
+ButtonBuilder.prototype.myCustomButton = function (displayText, id, opts) {
+  return this.simpleButton('myCustomButton', displayText, id, opts)
+}
+```
+
+For complex types (custom params), use the generic `button(name, params)`.
+
+### How do I update WAProto after a Baileys upgrade?
+
+```js
+import { ProtoUpdater } from '@kyyinfinite/lumina'
+
+const updater = new ProtoUpdater()
+const result = await updater.update({ autoRollback: true })
+if (result.success) {
+  console.log('updated:', result.appliedFixes)
+} else {
+  console.error('rolled back:', result.errors)
+}
+```
+
+### Does Lumina work with multi-device accounts?
+
+Yes — Lumina is purely a builder/relay layer; it works with any Baileys
+socket that supports `relayMessage`, `prepareWAMessageMedia`, and the
+`ev` event bus.
+
+### Can I use Lumina without sending — just to build message objects?
+
+Yes. Every builder has a `build()` method that returns the proto-ready
+object without relaying:
+
+```js
+const msg = await bot.button().title('T').body('B').reply('OK').build(jid)
+// msg.message is the proto object — inspect, log, or relay manually.
+```
+
+---
+
+## License
+
+MIT © [KyyInfinite](https://github.com/kyyinfinite)
+
+## Repository
+
+- Source: <https://github.com/kyyinfinite/lumina>
+- Issues: <https://github.com/kyyinfinite/lumina/issues>