@japofc/baileys

⚡ The maintained WhatsApp Web API for Node.js

Typed ESM · always-current WA Web versioning · protocol-safe tooling · 140+ production bot utilities

📦 Install · 🚀 Quick start · 🔥 Features · 💡 Examples · 📘 TypeScript · ❓ FAQ · 🇮🇩 Bahasa Indonesia

Install

npm i @japofc/baileys
Copy

Node.js 20+ is required. The package is ESM-only and has no install/postinstall scripts.

Quick start

import makeWASocket, { useMultiFileAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')
const sock = makeWASocket({ auth: state, printQRInTerminal: true })

sock.ev.on('creds.update', saveCreds)
sock.ev.on('messages.upsert', async ({ messages }) => {
  const msg = messages[0]
  if (!msg?.message || msg.key.fromMe) return
  await sock.sendMessage(msg.key.remoteJid, { text: 'pong' }, { quoted: msg })
})
Copy

Overview

@japofc/baileys is a production-oriented WhatsApp Web library for bot builders who need predictable socket behavior, complete TypeScript declarations, and maintained utilities without hidden side effects.

• Current WA Web fallback version plus makeWASocketAuto() for live version resolution.
• Full WAProto declarations and deep package exports for installed-package consumers.
• Auth backends for files, SQLite, Redis, MongoDB, MySQL, and PostgreSQL.
• Interactive messages, native flows, carousel, AIRich cards, channels/newsletters, status helpers, and bot modules.
• Hardened media/link fetching, credential redaction, session tools, reconnect helpers, and protocol-capture tooling.
• No implicit group/channel join or follow. Join/follow helpers remain available, but they only run when your code explicitly calls them.

🆚 Comparison

How @japofc/baileys stacks up against other Baileys libraries:

This table describes package-level features, not performance benchmarks. PRs to update or correct it are welcome via Contributing.

🧰 Built With

🔥 Features

✨ Exclusive J.AP Enhancements

Audio Group Status Fix

Audio status uses a more compatible implementation to avoid unsupported-version errors on older WhatsApp clients.

AIRich — the rich-response message builder

A chainable builder (AIRich, also exported as AIJap / LeafRich / JapAI / JapRich) with 40+ add*()/set*() methods covering headings, formatted text (hyperlinks/citations/LaTeX), code blocks, tables, image/video/product/post cards, task & progress cards, tip banners, and quick-reply suggestions — the kind of rich card layout you'd normally only see from an official AI/assistant-style bot. See Usage Examples below.

Native Flow Expansion

System Notification Filter

Messages include:

message.isSystemNotification
Copy

Useful for filtering:

• E2E notices
• Meta service notices
• Other system-generated messages

📦 Installation

npm install @japofc/baileys
Copy

Directly from GitHub:

npm install github:JAPofc/baileys
Copy

Requires Node.js 20+ — enforced at import time with a clear error (no install scripts: this package deliberately ships zero preinstall/postinstall hooks, so npm ci --ignore-scripts and strict supply-chain policies work out of the box).

Coming from @whiskeysockets/baileys? Migration is usually a one-line import change — see MIGRATION.md.

Optional peer dependencies

Everything below is optional — the socket works without any of them. Install only what the features you use need; missing ones fail with a clear install hint instead of a silent crash.

The version column mirrors this package's peerDependencies ranges — those are the ranges the test suite runs against. Newer majors usually work but aren't verified; npm ls <pkg> + printEnvironmentReport() (below) will tell you what you actually have.

ffmpeg: how it's found

Every feature that shells out to ffmpeg (video thumbnails, sticker conversion, voice-note conversion, VoIP audio feeding) resolves the binary through one central resolver, in this order:

1. Your override — setFfmpegPath('/path/to/ffmpeg') (exported from the package) or the FFMPEG_PATH env var
2. ffmpeg-static — if installed, its bundled binary is used automatically
3. @ffmpeg-installer/ffmpeg — same, as an alternative
4. System ffmpeg on your PATH

So on a normal server you can just npm i ffmpeg-static and never think about it. On Termux/Android (where neither npm package ships a binary) install the system one instead — it's picked up automatically:

pkg install ffmpeg
Copy

If nothing is found, the feature fails with a per-platform install hint instead of a cryptic spawn ffmpeg ENOENT.

Check your environment (doctor)

Wondering why some feature doesn't work? One call diagnoses everything — Node version, which optional deps are installed, where ffmpeg was found, the active image backend:

import { printEnvironmentReport } from '@japofc/baileys'
await printEnvironmentReport() // prints a full report + returns the snapshot
// or the raw-data version without printing:
import { checkEnvironment } from '@japofc/baileys'
const env = await checkEnvironment() // { ok, platform, node, ffmpeg, imageBackend, optionalDeps, warnings }
Copy

Or straight from the terminal, no code needed:

npx @japofc/baileys doctor    # exit code 0 = all good, 1 = warnings
npx @japofc/baileys version
npx @japofc/baileys export dump.json --format csv --out chat.csv   # WAMessage JSON → transcript
Copy

🚀 Quick Start

import { makeWASocketAuto, useMultiFileAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')

// makeWASocketAuto resolves the freshest WA Web version before connecting
// (WA sw.js -> fork -> fallback), preventing stale-version pairing 405s.
// Prefer sync? `makeWASocket({ auth: state })` still works exactly as before.
const sock = await makeWASocketAuto({
    auth: state
})

// persist credentials whenever Baileys updates them
sock.ev.on('creds.update', saveCreds)

sock.ev.on('connection.update', (update) => {
    const { connection, qr } = update

    // Easiest: pass `printQRInTerminal: true` to makeWASocket and the QR is
    // drawn automatically with the built-in zero-dependency renderer.
    // Manual/custom rendering from the event also works:
    //   import { renderQRToTerminal, qrToSVG, qrToPNG } from '@japofc/baileys'
    //   if (qr) console.log(renderQRToTerminal(qr))          // terminal (▀▄█)
    //   if (qr) fs.writeFileSync('qr.svg', qrToSVG(qr))      // for a web UI
    //   if (qr) fs.writeFileSync('qr.png', qrToPNG(qr))      // raster (send anywhere)
    if (qr) console.log('Got a pairing QR')

    if (connection === 'open') console.log('🍃 Connected!')
})

sock.ev.on('messages.upsert', ({ messages }) => {
    const msg = messages[0]
    if (!msg.message || msg.key.fromMe) return
    console.log('New message from', msg.key.remoteJid)
})
Copy

Production tip — wrap the socket in autoReconnect() and disconnect handling is done for you (exponential backoff, never reconnects on loggedOut, immediate reconnect after pairing):

import { makeWASocketAuto, autoReconnect, useMultiFileAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')
const manager = autoReconnect(() => makeWASocketAuto({ auth: state, printQRInTerminal: true }), {
    onSocket: sock => {
        sock.ev.on('creds.update', saveCreds)
        sock.ev.on('messages.upsert', handler) // re-attached on every reconnect
    },
    onLoggedOut: () => console.log('delete auth_info/ and re-pair'),
})
await manager.start()
Copy

Full runnable version: examples/auto-reconnect-bot.js.

Observability — attach createDebugMonitor() for a safe, structured snapshot (connection state, disconnect reason, uptime, message latency percentiles, send-retry counts, Signal error tallies, VoIP/WASM state, memory). It never contains QR payloads, pairing codes, auth keys, tokens, or private keys — the whole snapshot is passed through redactSecrets() before it is returned, so it's safe to log or attach to bug reports as-is:

import { createDebugMonitor } from '@japofc/baileys'

const monitor = createDebugMonitor(sock)
// later — in a health endpoint, cron log, or crash handler:
console.log(JSON.stringify(monitor.getDebugInfo(), null, 2))
// { connection: { state, uptimeMs, lastDisconnect: { code, reason } },
//   messages: { received, decryptFailed, latencyMs: { p50, p90, p99 } },
//   sendRetries, signalErrors: { noSession, badMac, ... }, voip, memory }
Copy

Experimental protocol capture — new WhatsApp features should not be faked from wishful thinking; first capture the consenting test account's BinaryNode shape, redact secrets, then add a high-level wrapper once the wire contract is known:

import { bindProtocolCapture } from '@japofc/baileys'

const capture = bindProtocolCapture(sock, { file: './wa-protocol.ndjson' })
// trigger the feature on a paired official client/test account
// each line is redacted JSON: { direction, summary, node }
await capture.close()
Copy

🔐 Authentication

Four auth-state backends ship out of the box. All return the same { state, saveCreds } shape expected by makeWASocket({ auth }), so they're drop-in interchangeable.

import { makeWASocket, useMultiFileAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')
const sock = makeWASocket({ auth: state })
sock.ev.on('creds.update', saveCreds)
Copy

Pairing code login (no QR)

import { makeWASocket, useMultiFileAuthState, formatPairingCode } from '@japofc/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')
const sock = makeWASocket({ auth: state, printQRInTerminal: false })
sock.ev.on('creds.update', saveCreds)

if (!state.creds.registered) {
    const code = await sock.requestPairingCode('628123456789') // full international number
    console.log('Pairing code:', formatPairingCode(code))      // "ABCD-EFGH"
}

// custom 8-char code (Crockford base32: 1-9, A-Z minus I/O/U)
await sock.requestPairingCode('628123456789', 'JAPJAP12')
Copy

Input is validated up front with clear errors instead of the classic silent server-side failures: formatting noise (+, spaces, dashes) is stripped, a leading 00 international call prefix is removed automatically, and the two big footguns throw immediately — local-format numbers (08123... instead of 628123..., the #1 cause of "the pairing code never arrives") and numbers over the 15-digit E.164 maximum. The same check is exported standalone as normalizePairingPhone(phone). For public-facing bots, rate-limit pairing attempts with withPairingGuard.

// SQLite variant
import { makeWASocket, useSqliteAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useSqliteAuthState({ database: './auth.db' })
const sock = makeWASocket({ auth: state })
sock.ev.on('creds.update', saveCreds)
Copy

All four database adapters accept either an existing client/collection (recommended — you control pooling and lifecycle) or a uri (the driver is lazily imported only then; none are hard dependencies):

// Redis variant — works with ioredis AND node-redis
import { makeWASocket, useRedisAuthState } from '@japofc/baileys'

const { state, saveCreds } = await useRedisAuthState({ client: myRedis, session: 'bot-1' })
const sock = makeWASocket({ auth: state })
sock.ev.on('creds.update', saveCreds)
Copy

useMultiFileAuthState also exports pruneStaleAuthFiles(folder, options) to clean up old sender-key files on a schedule — useful for long-running bots that accumulate thousands of stale key files.

🗄️ Store Backends

makeInMemoryStore() from lib/Store gives you the classic in-memory chat/contact/message cache. For anything that needs to survive a restart, makePersistentStore() (from PersistentStore.js) wraps one of five backends behind the same interface:

import { makeWASocket, makeInMemoryStore } from '@japofc/baileys'

const store = makeInMemoryStore({})
store.readFromFile('./baileys_store.json')
setInterval(() => store.writeToFile('./baileys_store.json'), 10_000)

const sock = makeWASocket({ /* ...auth etc */ })
store.bind(sock.ev)
Copy

💡 Usage Examples

Buttons & Native Flow

import { Button } from '@japofc/baileys'

await new Button(sock)
    .setTitle('Promo Spesial')
    .setBody('Diskon 20% cuma hari ini')
    .setFooter('@japofc/baileys')
    .addReply('Klaim Sekarang', 'claim_promo')
    .addUrl('Lihat Katalog', 'https://example.com/catalog')
    .addCall('Hubungi Kami', '628123456789')
    .send(jid)
Copy

Poll

import { Poll } from '@japofc/baileys'

await new Poll(sock)
    .setName('Mau makan apa hari ini?')
    .addOptions(['Fried Rice', 'Chicken Noodles', 'Meatballs'])
    .setSelectable(1)
    .send(jid)
Copy

v2.4.7 — the poll builder now validates before it sends. Duplicate options are rejected (poll results are bucketed by option text, so duplicates used to merge into one result), setEndDate() throws on an unparseable date instead of wiring endTime: NaN, and setQuiz() can no longer be combined with setAnnouncementGroup() (that path emits pollCreationMessageV2, which has no correctAnswer field, so the quiz was silently dropped). Quiz polls are also finally readable: getAggregateVotesInPollMessage() now recognises pollCreationMessageV5.

const poll = new Poll(sock)
    .setName('Quiz: ibu kota Indonesia?')
    .addOptions(['Jakarta', 'Bandung', 'Surabaya'])
    .setQuiz('Jakarta')

poll.validate()        // [] when safe to send — collects every problem at once
poll.assertValid()     // throws the first problem (build()/send() run this for you)
poll.countOptions()    // 3
poll.getOptions()      // ['Jakarta', 'Bandung', 'Surabaya'] (a copy)
poll.removeOption('Surabaya')
Poll.MAX_OPTIONS       // 12 — enforced, like MAX_NAME_LENGTH (255) / MAX_OPTION_LENGTH (100)

await poll.send(jid)
Copy

Carousel

Cards are usually built with Button(...).toCard() first. Media cards work as before, and v2.4.7 also allows valid text/button-only carousel cards (WhatsApp renders them) via addTextCard() or a Button(...).toCard() card with no media header.

import { Button, Carousel } from '@japofc/baileys'

const cardA = await new Button(sock)
    .setImage('https://example.com/a.jpg')
    .setTitle('Produk A')
    .addUrl('Lihat', 'https://example.com/a')
    .toCard()

const cardB = await new Button(sock)
    .setImage('https://example.com/b.jpg')
    .setTitle('Produk B')
    .addUrl('Lihat', 'https://example.com/b')
    .toCard()

await new Carousel(sock)
    .setBody('Pilih salah satu produk di bawah ini')
    .addCard([cardA, cardB])
    .send(jid)

// Text/button-only card, no image required:
await new Carousel(sock)
    .setBody('Quick actions')
    .addTextCard({
        title: 'Support',
        text: 'Choose an action',
        buttons: [
            { id: 'faq', text: 'FAQ' },
            { webview: 'https://example.com/help', text: 'Open Help' }
        ]
    })
    .send(jid)
Copy

AIRich — rich response cards

import { AIRich } from '@japofc/baileys'

await new AIRich(sock)
    .addHeading('Order Summary')
    .addText('Your order is being processed.')
    .addTable([
        ['Item', 'Qty'],
        ['Iced Latte', '2']
    ])
    .addTip('Orders are usually ready in 15 minutes')
    .addSuggest('Track Order')
    .send(jid)
Copy

For the common case, v2.4.7 also exports a one-liner wrapper around the same builder:

import { sendJapRich, jap } from '@japofc/baileys'

await sendJapRich(sock, jid, {
    title: 'Order Summary',
    markdown: '# Paid\nYour order is being processed.',
    actions: { text: 'Track', url: 'https://example.com/order/123' },
    suggestions: ['Track Order', 'Contact Support']
})

// Or keep chaining after the shortcut builds the card:
await jap(sock, '# Quick Report').addTip('Generated now').send(jid)
Copy

Neutral aliases (sendRich, Rich, createRich, buildRich) remain available, but the JAP-branded helpers (jap, japRich, createJapRich, buildJapRich, sendJapRich) are the preferred names for new code.

AIRich supports { id, insertAt } on every add*()/set*() call, so you can insert a block relative to one you added earlier instead of always appending to the end — handy for streaming/edit-in-place style responses combined with sendEdit(jid, id).

streamText() — the "AI typing" effect. One bubble that grows via in-place edits (exactly how Meta AI streams its answers), instead of flooding the chat:

// sends once, then patches the same bubble until the full text is out
await new AIRich(sock).streamText(jid, longAnswer, {
    chunkSize: 120,  // ~chars per reveal (split at word boundaries)
    intervalMs: 900, // pause between edits (min 300)
    cursor: ' ▍'     // shown while streaming, removed at the end ('' disables)
})
// works alongside other blocks too: addHeading()/addTable() first, then streamText()
Copy

readRichMessage() — the reader half. Parse a received rich card (from any AI/assistant-style bot) back into structured blocks instead of staring at opaque proto:

import { readRichMessage } from '@japofc/baileys'

sock.ev.on('messages.upsert', ({ messages }) => {
    const rich = readRichMessage(messages[0])
    if (!rich.found) return
    rich.blocks      // [{ type: 'heading', text }, { type: 'code', language, code },
                     //  { type: 'table', rows, headerRows }, { type: 'text', text, entities }, …]
    rich.suggestions // every suggestion-pill text
    rich.text        // flat text rendering of the whole card
})
Copy

Handles both wire forms (unified-response payload + proto submessages fallback), resolves inline link entities back to [label](url), re-joins syntax-highlighted code spans, never throws — non-rich input returns { found: false }. Round-trip tested against the AIRich builder itself.

Other builders worth knowing about: ButtonV2 (simpler quick-reply-only buttons), ButtonV3 (loadFrom(msg) to edit an existing template message in place), and Toolkit (static helpers: Toolkit.resize(), Toolkit.fetchBuffer(), Toolkit.waitAllPromises(), Toolkit.extractIE() for parsing [label](url) links/citations/LaTeX out of plain text).

📁 Builders Folder Map (lib/Builders/)

Every message builder lives in its own file under lib/Builders/, so you can trace exactly where a class comes from instead of digging through one giant MessageBuilder.js. index.js is just the barrel file that re-exports everything below (plus their aliases) for the top-level import { ... } from '@japofc/baileys' syntax.

Unified hub example — useful if you'd rather carry one object around than import each builder individually:

import { JapBaileys } from '@japofc/baileys'

const vx = new JapBaileys(sock)

await vx.button()
    .setTitle('Promo Spesial')
    .addReply('Klaim Sekarang', 'claim_promo')
    .send(jid)

await vx.poll()
    .setName('Mau makan apa hari ini?')
    .addOptions(['Fried Rice', 'Chicken Noodles'])
    .send(jid)
Copy

📌 Pin / Keep in Chat

// Pin a message for 7 days (default 24h), unpin, keep / unkeep in disappearing chats
await sock.sendPin(jid, msg.key, { durationSec: 7 * 86400 })
await sock.sendUnpin(jid, msg.key)
await sock.sendKeep(jid, msg.key)
await sock.sendUnkeep(jid, msg.key)
Copy

📅 Event

await sock.sendEvent(jid, {
    name: 'Weekly Meeting',
    description: 'Bahas progres bot',
    startDate: new Date('2026-09-15T10:00:00+07:00'),
    endDate: new Date('2026-09-15T11:00:00+07:00'),
    location: { name: 'Office', address: 'Jakarta' },
    extraGuestsAllowed: true
})
Copy

📞 Scheduled Call

Native scheduled-call message (the "Schedule call" card with a join reminder):

// 'voice' (default) or 'video'
await sock.sendScheduledCall(jid, {
    title: 'Daily standup',
    scheduledAt: new Date('2026-09-15T09:00:00+07:00'),
    callType: 'video'
})

// Cancel it later (needs the creation message's key)
await sock.cancelScheduledCall(jid, creationMsg.key)
Copy

📱 Mini App

Two modes — pass url, flow, or both (two buttons):

import { sendMiniApp } from '@japofc/baileys'

await sendMiniApp(sock, jid, {
    title: 'My Mini App',
    body: 'Tap the button to open the app 👇',
    // 1) webview mode: rich card + CTA opening your web app
    //    (in-app webview when supported, else the browser)
    url: 'https://myapp.example.com',
    params: { ref: 'wa-bot' }, // → appended as ?ref=wa-bot
    buttonText: '🚀 Open App',
    // 2) Flows mode: TRUE native in-chat mini app (forms/screens inside
    //    WhatsApp, no browser). Needs a published Flow ID from Flows Manager.
    flow: { id: '123456789', cta: '📝 Isi Form', screen: 'WELCOME' },
    thumbnail: 'https://myapp.example.com/icon.png' // url or Buffer
})
// or as a socket method: await sock.sendMiniApp(jid, { ... })
Copy

📨 Message Helpers

High-level one-liners for modern message types — validated, with friendly aliases:

await sock.sendLocation(jid, { lat: -6.2, lng: 106.8, name: 'Jakarta' });
await sock.sendContact(jid, { name: 'John', vcard: 'BEGIN:VCARD\n...' });
await sock.sendGroupInvite(jid, { code: 'AbC123', jid: groupJid, subject: 'Community' });
await sock.sendPaymentRequest(jid, { currency: 'IDR', amount: 50000, note: 'coffee ☕' });
await sock.sendInvoice(jid, { note: 'INV-001' });
await sock.sendPollOption(jid, pollKey, ['New option']);
await sock.sendEventInvite(jid, { eventTitle: 'Party', startTime: new Date(...) });
await sock.sendNewsletterInvite(jid, { newsletterJid, newsletterName: 'News' });

// Poll upgrades (already wired end-to-end):
await sock.sendPoll(jid, {
  name: 'Jam berapa?', values: ['Pagi', 'Sore'],
  endDate: new Date('2026-09-16T00:00:00Z'), // auto-close
  hideVoter: true,      // anonymous poll
  canAddOption: true,   // voters may add options
});
Copy

Music messages are experimental — the proto is correct but interop with official clients is unverified (see Honestly not implemented):

await sock.sendMusic(jid, { songUri, artworkUri, embeddedMusic: { songId, title, author } });
Copy

Escape hatch: every content key also works inline via sendMessage, and { raw: true, <AnyMessageField>: {...} } passes any proto field through untouched — full WAProto coverage with zero wrapper lag:

await sock.sendMessage(jid, { raw: true, musicMessage: { songUri } });
Copy

TypeScript consumers get a typed AnyMessageContent (import type { AnyMessageContent } from '@japofc/baileys').

🧰 Channels, History & Transcripts

Channel management (live queries):

await sock.newsletterDelete(channelJid)
await sock.newsletterAdminCount(channelJid)
await sock.newsletterJoinInvite('invite-code')
await sock.newsletterChangeOwner(channelJid, newOwnerJid) // experimental
await sock.communityGetInviteCode(communityJid)
// ...plus existing follow/unfollow/mute/react/fetch + full community CRUD
Copy

Group history sharing for new members (forwards recent messages to their DM):

import { getGroupHistoryFromStore } from '@japofc/baileys'
const messages = getGroupHistoryFromStore(store, groupJid, 10)
await sock.shareGroupHistory({ groupJid, members: newMemberJid, messages, greeting: true })
Copy

Voice-note transcription (pluggable provider — cloud Whisper or your own):

import { openAIWhisperProvider } from '@japofc/baileys'
const provider = openAIWhisperProvider({ apiKey: process.env.OPENAI_API_KEY })
const { text } = await sock.transcribeMessage(voiceNoteMsg, { provider })
Copy

Mini-app deep links (HMAC-signed params your web app can verify):

import { createMiniAppLink, parseMiniAppParams, buildFlowDataExchange } from '@japofc/baileys'
const link = createMiniAppLink('https://app.example.com/', { uid: '123' }, { secret: 's3cr3t' })
parseMiniAppParams(link, { secret: 's3cr3t' }) // → { uid: '123' } (throws if tampered)
buildFlowDataExchange('navigate', { screen: 'HOME' }) // Flows data_exchange payload
Copy

A2UI widgets now include Slider, Switch, List, ProgressBar, Avatar, Badge, Spacer, and Tabs alongside the existing Text/Image/Video/Button/Card/Modal set (all ref-validated at build()).

🔐 Security Pack

Drop-in hardening for auth state, secrets, and abuse — all in lib/Utils/auth-secure.js, covered by tests/security.test.js (incl. fuzzing).

import {
  useEncryptedFileAuthState, secureLogger, withPairingGuard,
  createQRGuard, backupAuthState, writeAuthIntegrity, repairAuthState, secureLogout
} from '@japofc/baileys'

// 1. AES-256-GCM encrypted auth state (reads legacy plaintext, migrates on save)
const { state, saveCreds } = await useEncryptedFileAuthState('./auth', { password: process.env.AUTH_PW })
const sock = makeWASocket({
  auth: state,
  logger: secureLogger(pino({ level: 'info' })), // 7. redacts qr/tokens/keys in every log line
})

// 2. pairing-code rate limit: 5/hour per number, 30s between attempts
withPairingGuard(sock, { maxPerHour: 5, minIntervalMs: 30_000 })

// 3. QR fist-guard: handle the first QR, swallow re-emits for 60s
const qrGuard = createQRGuard({ ttlMs: 60_000 })
sock.ev.on('connection.update', ({ qr }) => { qr = qrGuard.handle(qr); if (qr) show(qr) })

// 6/8. encrypted backup + integrity snapshot
await backupAuthState('./auth', './auth.jabackup', { password: process.env.BACKUP_PW })
await writeAuthIntegrity('./auth', { secret: process.env.INT_PW })

// 9. repair corrupt stores (quarantines + restores creds from backup)
await repairAuthState('./auth', { password: process.env.AUTH_PW, backupFile: './auth.jabackup', backupPassword: process.env.BACKUP_PW })

// 4. logout + overwrite/unlink every auth file + scrub in-memory creds
await secureLogout(sock, { authFolder: './auth' })
Copy

Single-file variant: useEncryptedSingleFileAuthState(file, { password }).

🆕 WA 2026 catch-up

WhatsApp 2026 features, wired into JAP-Baileys. Everything here was audited against the latest official clients — only gaps were added; what already worked is just documented.

Usernames (chat without phone numbers)

await sock.checkUsername('japstore');            // availability
await sock.setUsername('japstore');              // claim it
await sock.reserveUsername('japstore');          // reserve it (2026 reservation flow)
await sock.findUserByUsername('japstore');       // USync lookup → JID
const u = await sock.fetchContactUsernames(['62812@s.whatsapp.net']);
Copy

Editable polls (editPoll)

Polls are editable for ~15 minutes after creation (server-side rule):

const sent = await sock.sendPoll(jid, { name: 'Jam berapa?', values: ['Pagi', 'Sore'] });
await sock.editPoll(jid, sent.key, { name: 'Jam berapa?', values: ['Pagi', 'Siang', 'Sore'] });
Copy

Mass mention (sendMentionAll)

await sock.sendMentionAll(groupJid, 'Announcement: meeting at 9!');
Copy

In groups with 32+ members @all is admin-only and the rule is enforced server-side — non-admin calls are silently dropped by WhatsApp.

Status mentions (sendStatusMention)

Post a status and notify specific users or whole groups — they get the "mentioned you in their status" bubble linking to your status:

// text status, mention two users
await sock.sendStatusMention({ text: 'Big announcement! 🎉' }, [
    '62812xxx@s.whatsapp.net',
    '62813xxx@s.whatsapp.net',
])

// image status, mention an entire group (every member is notified)
await sock.sendStatusMention({ image: buffer, caption: 'New drop 🔥' }, [groupJid])
Copy

Works with any status content (text, image, video, audio). Pace the notification fan-out with { delayMs } in options (default 1500 ms per jid).

Event reminders

await sock.sendMessage(jid, {
  event: {
    title: 'Meeting', description: 'Q3', startDate: new Date('2026-09-15T09:00:00+07:00'),
    reminder: true, reminderOffsetSec: 1800, // remind 30 min before start
  }
});
Copy

Sender phone from LID events (resolveSenderPn)

Fixes LID-only payloads (e.g. call offers where caller_pn is missing):

sock.ev.on('messages.upsert', async ({ messages }) => {
  for (const m of messages) console.log(await sock.resolveSenderPn(m)); // '62812…' | null
});
Copy

View-once voice notes

sendVoiceNote() content composes with viewOnce:

await sock.sendMessage(jid, { ...(await buildVoiceNoteContent('./a.ogg')), viewOnce: true });
Copy

Member tags (groups)

Already exposed — no new code, documented here:

await sock.updateMemberLabel({ groupJid, lid, label: 'Admin' });
Copy

Honestly not implemented (and why)

• Voice message transcripts — generated on-device by official clients only; there is no transcript API on the wire.
• Group message history sharing (native) — WhatsApp began rolling out the official "Group Message History" feature (share the last 25–100 messages with a newly added member, E2EE, admin-controlled) in Feb 2026. Its wire format still hasn't been captured by any public library (re-verified 28 Sep 2026 by downloading and API-diffing upstream Baileys 7.0.0-rc14 plus the 8 largest living forks — none carry it). Until it is, this repo ships an honest workaround — shareGroupHistory() forwards recent messages into the new member's DM — which is NOT the native flow (no in-group history bubble, no "history shared" notice). If you need native behaviour, the only path today is an official client.
• Music messages (interoperability) — the MusicMessage proto struct round-trips fine and sendMusic() emits it, but real interop needs provider catalog IDs (Spotify/Apple) plus an artwork upload flow that official clients negotiate privately; no public capture exists (re-verified Sep 2026). Messages built with made-up IDs render as a plain preview or nothing at all on official clients — treat sendMusic() as experimental and test against a real device before shipping. What v2.4.1 does fix: unknown embeddedMusic fields used to be silently dropped by the proto encoder (a typo'd key just vanished from the wire) — they now throw a clear 400 listing the supported field names. For the modern music-on-status surface, see withMusicAttribution() below.
• mediaKeyDomain — now IMPLEMENTED (kept here for history). Backported from rc14 onto all 5 media types (Audio/Document/Image/Sticker/VideoMessage, enum UNSET/E2EE_CHAT/STATUS/CAPI/BOT) with a send passthrough: sendMessage(jid, { image: buf, mediaKeyDomain: 1 }). Unset by default (recommended — the server labels it). Skipped only on MMSThumbnailMetadata, where upstream's field number 8 collides with the newer messageHistoryMetadata in our proto.

🆕 Everyday Utilities

One-liners for daily bot work (also usable standalone — see examples/):

// 📊 Poll (chats/groups) + Quiz (channels only)
await sock.sendPoll(jid, { name: 'What to eat?', options: ['Rice', 'Noodles'] })
await sock.sendQuiz(channelJid, { name: 'Quiz', options: ['A', 'B'], correctAnswer: 'A' })

// 🎙️ Voice note — auto-converts mp3/wav/… to Opus PTT (needs fluent-ffmpeg)
await sock.sendVoiceNote(jid, './hello.mp3') // path | Buffer | { url }

// 📞 Tag everyone (visible @list vs hidden)
await sock.tagAll(groupJid, 'Meeting at 10!')
await sock.hideTag(groupJid, 'Announcement 📢')

// 🔍 LID → phone number (best-effort, null when unknown)
await sock.getPhoneNumber('12345@lid') // → '62812…'
await sock.getLidForPhone('62812…')    // reverse lookup

// 🧍 Humanized send — typing… + natural delay + per-chat queue
await sock.sendHumanized(jid, { text: 'Hello!' })

// 🛡️ Send Guard — global anti-ban pacing baked into sendMessage()
const sock = makeWASocket({
    sendRateLimit: {
        messagesPerMinute: 20, // global token-bucket ceiling (0 = off)
        perChatDelayMs: 1500,  // minimum gap between sends to the same chat
        jitterRatio: 0.2       // ±20% randomness so timing never looks robotic
    }
})
await sock.sendMessage(jid, { text: 'auto-paced 🛡️' })            // paced
await sock.sendMessage(jid, { text: 'now!' }, { skipRateLimit: true }) // bypass

// ✅ Delivery tracking — await the server ack of an outgoing message
const msg = await sock.sendMessage(jid, { text: 'important!' })
await sock.waitForMessageAck(msg.key.id) // resolves on ack, rejects on
                                         // server error / 60s timeout

// ✅ One-call variant — send + await the ack, race-free (waiter registered
// BEFORE the send goes out, so a fast ack can never slip through)
const { message, ack } = await sock.sendMessageAcked(jid, { text: 'critical!' }, { ackTimeoutMs: 30_000 })

// 📣 Broadcast to many jids — paced, per-jid outcomes, never dies mid-run
const report = await sock.sendBroadcast(jids, { text: 'promo!' }, { delayMs: 1500 })
// { sent: [...], failed: [{ jid, error }], total }

// 🔗 Group invite links
extractGroupInviteCode('https://chat.whatsapp.com/AbCdEf…') // 'AbCdEf…'
await sock.joinGroupViaLink('https://chat.whatsapp.com/AbCdEf…')

// 🏷️ Parse @mentions out of text → ready for sendMessage
const mentions = parseMentions(text) // ['62812…@s.whatsapp.net', …]
await sock.sendMessage(jid, { text, mentions })

// 🤖 Meta AI chat (experimental — needs Meta AI on the account/region)
const { text } = await sock.askMetaAI('Explain black holes!')
Copy

Command router for prefix bots (!menu, .sticker) with middleware + auto-help:

import { createRouter } from '@japofc/baileys'
const router = createRouter({ prefix: '!' })
router.command('ping', async (ctx) => ctx.reply('pong! 🏓'), { desc: 'Check bot' })
router.attach(sock) // → detach()
Copy

Status / channel schedulers (in-memory):

import { StatusScheduler, ChannelScheduler, StatusHelper } from '@japofc/baileys'
new StatusScheduler(sock).schedule(StatusHelper.text('Pagi! ☀️'), new Date('2026-09-11T06:00:00+07:00'))
new ChannelScheduler(sock).schedule(channelJid, { text: 'Update' }, Date.now() + 3600_000)
Copy

Music attribution on statuses (StatusAttribution.Type.MUSIC — the official Dec-2025 "add music to your status" surface, wire-verified against WAProto):

import { StatusHelper, withMusicAttribution } from '@japofc/baileys'

const status = withMusicAttribution(
  StatusHelper.text('vibes 🎵'),
  { title: 'Song Name', authorName: 'Artist', songId: '<catalog-id>' }
)
await StatusHelper.send(sock, status, jidList)
Copy

Official clients resolve the song via Meta's licensed catalog, so songId must be a real catalog id for the music chip to render there. The attribution struct itself is wire-correct either way (round-trip covered by tests).

Chat export & statistics (offline — official "Export chat" format, JSON, CSV):

import { exportChatAsText, exportChatAsCSV, chatStatistics } from '@japofc/baileys'

// messages: WAMessage[] from your store / anti-delete cache / messages.upsert
console.log(exportChatAsText(messages))
// 14/09/2026, 10.32 - J.AP: halo!
// 14/09/2026, 10.33 - Rina: <Media omitted>

fs.writeFileSync('chat.csv', exportChatAsCSV(messages))

const stats = chatStatistics(messages)
// { total, bySender, byKind, byHour[24], byWeekday[7], topWords, ... }
Copy

Also available with zero code: npx @japofc/baileys export dump.json --format text|json|csv.

Offline bot testing (createMockSocket) — test your bot logic in CI with zero WhatsApp account, zero network, zero ban risk:

import { createMockSocket, createRouter } from '@japofc/baileys'
import assert from 'assert'

const mock = createMockSocket()
myBotSetup(mock.sock)              // your real bot code, unchanged

await mock.receiveText('628xx@s.whatsapp.net', '!ping')
const reply = await mock.waitForReply()
assert.equal(reply.content.text, 'pong! 🏓')
Copy

Same ev surface and sendMessage() signature as the live socket; outgoing messages are REAL proto.WebMessageInfo objects built through the same generateWAMessage() pipeline. Supports group injection, quoted replies, connection lifecycle simulation, read-receipt/presence capture, and reset() between tests. Honest scope: it does not emulate WhatsApp servers — rate limits, sessions, and encryption are out of scope by design.

npm test runs the offline suite (tests/, 1226 tests, no network needed).

🆕 New in v2.4.5

Fresh helpers added this release. All are exported from the package root and fully typed.

🗳️ Poll manager — track who voted what (createPollManager)

getAggregateVotesInPollMessage is stateless and double-counts a voter who changes their mind (WhatsApp re-sends the voter's full selection on every change). createPollManager keeps that state — each voter counts once, latest choice wins:

import { createPollManager } from '@japofc/baileys'

const polls = createPollManager()
const sent = await sock.sendMessage(jid, { poll: { name: 'Lunch?', values: ['Pizza', 'Sushi'], selectableCount: 1 } })
polls.register(sent) // remembers options + key

// feed it decrypted votes (option names, sha256 hex, or the raw hash Buffers WA sends):
polls.applyVote(sent.key.id, voterJid, ['Pizza'])

polls.tally(sent.key.id)   // [{ name:'Pizza', count, voters:[] }, ...]
polls.winner(sent.key.id)  // { winners:['Pizza'], count } (tie-aware)
console.log(polls.render(sent.key.id)) // live bar chart
Copy

❤️‍🩹 Session-health monitor (createSessionHealthMonitor)

Detects bursts of undecryptable messages (a dead Signal session / Bad-MAC drift) per contact and alerts you — purely observational, never throws into your event loop:

import { createSessionHealthMonitor } from '@japofc/baileys'

const health = createSessionHealthMonitor({ badMacThreshold: 3, windowMs: 60_000 })
health.bind(sock)
health.onUnhealthy(({ jid, failures }) => console.warn(`${jid} session looks broken (${failures} decrypt fails)`))
health.onRecover(({ jid }) => console.log(`${jid} recovered`))
Copy

Ships with canonicalizeJid() and makeJidCanonicalizer(sock) to key a contact by one identity across the PN/LID split.

🔁 Message de-dupe / idempotency (createMessageDedupe)

Stops double-replies when WhatsApp re-delivers a message (reconnect, history sync, placeholder resend, retries):

import { createMessageDedupe } from '@japofc/baileys'

const dedupe = createMessageDedupe({ maxSize: 5000 }) // optional ttlMs
sock.ev.on('messages.upsert', ({ messages }) => {
  for (const m of messages) {
    if (dedupe.seen(m.key)) continue // already handled → skip
    // ...handle exactly once
  }
})
Copy

🔗 LID ↔ PN helpers on the socket

The mapping helpers are now first-class socket methods (no more reaching into signalRepository):

await sock.getLIDForPN('62812…@s.whatsapp.net') // → '…@lid' | null
await sock.getPNForLID('123…@lid')              // → '…@s.whatsapp.net' | null
await sock.getLIDsForPNs([...])                  // batch
await sock.getPNsForLIDs([...])                  // batch
await sock.storeLIDPNMappings([{ lid, pn }])     // seed the cache
Copy

🧩 Small toolkit helpers

Ten new pure, typed helpers exported from the root:

import { partition, zip, formatCountdown, wordCount, ellipsisMiddle,
         jidType, randomString, isNumeric, firstEmoji, maskJid } from '@japofc/baileys'

partition([1, 2, 3, 4], n => n % 2 === 0) // [[2,4],[1,3]]
zip([1, 2], ['a', 'b'])                    // [[1,'a'],[2,'b']]
formatCountdown(90_061_000)                // '1d 01:01:01'
ellipsisMiddle('abcdefgh', 5)             // 'ab…gh'
jidType('123@g.us')                        // 'group'
maskJid('628123456789@s.whatsapp.net')     // '628******89@s.whatsapp.net'
Copy

📞 Voice & Video Calls

Experimental audio-call support via a bundled WASM call stack + WebRTC relay. Requires the optional @roamhq/wrtc peer dependency.

import { VoipClient } from '@japofc/baileys'

const voip = new VoipClient({ resourcesPath: './voip-resources' })
await voip.connectWithSocket(sock)

const call = await voip.call('628123456789')

call.on('ringing', () => console.log('Ringing...'))
call.on('connected', () => console.log('Call connected'))
call.on('ended', (reason) => console.log('Call ended:', reason))
Copy

ActiveCall (returned by .call()) and CallState are also exported directly if you need finer-grained control over call state.

Answering inbound calls — offers are tracked, so the bot can pick up (1:1) or join (group):

import { attachVoip } from '@japofc/baileys'
const voip = await attachVoip(sock) // also stored as sock.voip

voip.on('incoming-call', async ({ callId, from, isGroupCall, busy }) => {
    if (busy) return
    if (isGroupCall) await voip.joinGroupCall(callId, { audioSource: './greeting.mp3' })
    else await voip.answerCall(callId, { audioSource: './greeting.mp3' })
})

// ...or fully automatic:
await attachVoip(sock, { autoAnswer: true })   // pick up 1:1 calls
await attachVoip(sock, { autoJoinGroup: true }) // join group calls
await attachVoip(sock, { autoReject: true, autoRejectText: 'Bot cannot take calls 🙏' })

// still-pending offers (answer before `offerTtlMs`, default 45s):
voip.getPendingCalls() // → [{ callId, from, isGroupCall, ... }]
Copy

Group / multi-party calls:

const gcall = await voip.startGroupCall(groupJid, ['62812…', '62813…'], { chatName: 'Meeting' })
await voip.inviteToGroupCall('62814…')
await voip.removeGroupParticipant('62813@s.whatsapp.net')
await voip.rejoinGroupCall() // recovery after a drop

voip.on('group-call-started', console.log)
voip.on('group-call-joined', console.log)
Copy

Calls also support reactions, hand-raise, recording, and call links:

const call = await voip.call('628123456789', { audioSource: './greeting.mp3' })
call.react('👍')
call.setHandRaised(true)
const stopRecording = call.recordToFile('./call.wav') // remote peer → .wav
await voip.previewCallLink('call-link-token')

// 🔀 switch what the call plays WITHOUT hanging up (IVR-style flows)
call.setAudioSource('./menu.mp3')                    // file/URL
call.setAudioSource({ data: buffer, ext: 'mp3' })    // in-memory audio
call.setAudioSource('lavfi:sine=frequency=440')      // generated tone
call.setAudioSource('silence')                       // stop playing, stay on the call
Copy

Reconnect & recovery — a watchdog monitors the relay transport during every call (watchdogIntervalMs/watchdogMaxSilent); on a dead relay it emits call-degraded and automatically re-sends the crypto rekey + offer. Manual controls:

voip.on('call-degraded', ({ callId }) => console.log('relay dead, recovering', callId))
voip.on('call-recovery', (r) => console.log('recovery result', r))
await voip.recoverCall({}) // manual: { rekey: true, offer: true }
voip.getStats()            // { busy, callId, call, relay }
sock.ev.on('call', (calls) => { /* standard offer/reject path still works */ })
Copy

Refreshing the WASM stack — if calls break after a WA Web update, re-fetch the official VoIP build directly from WhatsApp Web's bootloader endpoint:

npm run voip:fetch-wasm
Copy

No browser is needed in the default path. If WhatsApp changes the public bootloader response, the script can still fall back to a logged-in Chrome session with CALL_WASM_FETCH_MODE=browser and --remote-debugging-port=9222.

🔎 User Sync Queries

WAUSync (USyncQuery / USyncUser + protocols) lets you check things like WhatsApp registration, device lists, status, and username info for a JID before you message it — the same mechanism behind sock.onWhatsApp().

import { USyncQuery, USyncUser, USyncContactProtocol } from '@japofc/baileys'

const query = new USyncQuery()
    .withContext('interactive')
    .withMode('query')
    .withUser(new USyncUser().withPhone('628123456789'))

query.protocols.push(new USyncContactProtocol())

const result = await sock.executeUSyncQuery(query)
Copy

Available protocols: USyncContactProtocol, USyncDeviceProtocol, USyncStatusProtocol, USyncUsernameProtocol, USyncDisappearingModeProtocol, UsyncBotProfileProtocol, UsyncLIDProtocol.

👤 Username Management

High-level wrappers around WhatsApp's username feature (the @username handle you can set instead of exposing your phone number), sitting on top of USyncUsernameProtocol.

⚠️ Query-ID rotation. The GraphQL query IDs behind these calls are captured from live WA Web sessions and WhatsApp rotates them from time to time. When that happens calls fail with GraphQL server error: Bad Request (or unexpected response structure). You don't have to wait for a package update — hot-patch the rotated ID at runtime:

const sock = makeWASocket({
    usernameQueryIds: { CHECK: '<fresh-id>', SET: '<fresh-id>' } // override any of:
    // CHECK, CHECK_MULTI, SET, GET, GET_RECOMMENDATIONS, PIN_SET
})
Copy

Fresh IDs can be captured from a live WA Web session (DevTools → Network → WS frames → look for xmlns="w:mex" queries).

// Check availability + get suggestions if taken
const check = await sock.checkUsername('J.AP')
// { available: true, username: 'J.AP' }
// or: { available: false, suggestions: [...], rejectionReasons: [...] }

// Claim a username
await sock.setUsername('J.AP', { source: sock.USERNAME_SOURCE.USER_INPUT })

// Lock it behind a PIN so it can't be changed without one
await sock.setUsernamePin('123456')

// Read your own username / drop it
const mine = await sock.getMyUsername()
await sock.deleteUsername()

// Resolve a username to a JID (USync-based, like onWhatsApp() but by username)
const user = await sock.findUserByUsername('someone')
// { jid: '628...@s.whatsapp.net', contact: false }

// Batch-resolve usernames for a list of known contacts
const usernames = await sock.fetchContactUsernames(jid1, jid2, jid3)

// Get WA's own suggestions (e.g. for onboarding flows)
const recs = await sock.getUsernameRecommendations()
Copy

Requires a Community/Contact-tier account in good standing — accounts under WA's usual restrictions for new/unverified numbers may see INVALID or empty suggestions regardless of the username's actual availability.

🤖 Bot Framework

An optional, higher-level layer on top of the raw socket: middleware routing, a !command dispatcher, a message queue that survives disconnects, exponential-backoff auto-reconnect, per-JID session storage, group activity stats, and media (sticker/voice-note) conversion helpers — so a new bot project doesn't have to hand-roll session/context management every time.

Needs the better-sqlite3 peer dependency (session + stats storage) and fluent-ffmpeg (sticker/voice-note conversion, already listed above) — both fail with an install hint rather than crashing if you use a Framework feature that needs them without installing them first.

import { Bot } from '@japofc/baileys'

const bot = new Bot({
    socketConfig: { printQRInTerminal: true },
    dbPath: './bot.db',   // sessions + stats, defaults to 'baileys_store.db'
    enableStats: true     // group message/sticker leaderboards + ghost detection
})

bot.command('!ping', async (ctx) => {
    await ctx.reply({ text: 'pong' })
})

bot.command('!sticker', async (ctx) => {
    if (!ctx.quoted?.imageMessage) return ctx.reply({ text: 'Reply to an image with !sticker' })
    // ctx.replySticker() handles the WebP conversion for you
    await ctx.replySticker(imageBuffer, { packname: 'J.AP Pack', author: 'you' })
})

bot.onText(async (ctx) => {
    // ctx.session() / ctx.setSession() / ctx.updateSession() / ctx.clearSession()
    // persist small per-chat state (e.g. multi-step flows) to SQLite automatically
    const state = ctx.session()
    if (state?.awaitingReply) {
        ctx.updateSession((s) => ({ ...s, awaitingReply: false }))
    }
})

await bot.start()
Copy

Context, SessionManager, StatsManager, MediaManager, and SQLiteStore are also exported individually if you only need one piece rather than the full Bot class.

These files ship as plain .js for now — hand-written .d.ts declarations for the Framework module haven't been added yet, unlike the rest of this fork's fully-typed surface.

🧩 Utility Modules

// anti-delete + anti-edit share one MessageStore
import { MessageStore, createMessageStoreHandler, createAntiDeleteUpsertHandler, createAntiEditUpsertHandler } from '@japofc/baileys'

const store = new MessageStore()
sock.ev.on('messages.upsert', createMessageStoreHandler(store))     // register FIRST
sock.ev.on('messages.upsert', createAntiDeleteUpsertHandler(store, (info) => {
    console.log('deleted:', info.originalMessage)                   // recovered content
}))
sock.ev.on('messages.upsert', createAntiEditUpsertHandler(store, (info) => {
    console.log(`edit #${info.editCount}: "${info.beforeText}" -> "${info.afterText}"`)
    info.history // every previous revision, oldest first
}))
Copy

// event trackers — reaction / read-receipt / presence
import { createReactionTracker, createReceiptTracker, createPresenceTracker } from '@japofc/baileys'

const reactions = createReactionTracker()
reactions.bind(sock)                       // messages.reaction
reactions.getSummary(msg.key)              // { '👍': ['628…@s.whatsapp.net'], … }
reactions.onReaction(({ user, emoji, removed }) => { /* live updates */ })

const receipts = createReceiptTracker()
receipts.bind(sock)                        // message-receipt.update + messages.update
receipts.getReceipts(msg.key)              // { delivered: [...], read: [...], played: [...] }
receipts.isReadBy(msg.key, jid)            // has THIS user read it?
receipts.onRead(({ key, user }) => { /* fires once per reader */ })

const presence = createPresenceTracker()
presence.bind(sock)                        // presence.update
await sock.presenceSubscribe(jid)          // WA only streams presence for subscribed jids
presence.isOnline(jid); presence.isTyping(jid); presence.get(jid)?.lastSeen
presence.onChange(({ user, presence }) => { /* online/offline/typing transitions */ })
Copy

// bot toolkit — serializer, call guard, group events, view-once, anti-link
import {
    serializeMessage, createCallGuard, createGroupEventsTracker,
    createViewOnceCapture, createAntiLinkGuard
} from '@japofc/baileys'

sock.ev.on('messages.upsert', async ({ messages }) => {
    const m = serializeMessage(sock, messages[0])
    if (!m || m.fromMe) return
    if (m.body === 'ping') await m.reply('pong')      // quotes the original
    if (m.isMedia) { const buf = await m.download() } // media as Buffer
    if (m.quoted) console.log('replying to:', m.quoted.body)
})

const calls = createCallGuard({ autoReject: true, rejectMessage: 'Bots cannot pick up calls.' })
calls.bind(sock)                                      // 'call' event
calls.onRejected(call => console.log('rejected', call.from, call.isVideo ? '(video)' : ''))

const groups = createGroupEventsTracker()
groups.bind(sock)                                     // group-participants.update + groups.update
groups.onJoin(({ id, participants }) =>
    sock.sendMessage(id, { text: `Welcome ${participants.join(', ')}! 👋` }))
groups.onLeave(({ participants }) => console.log('left:', participants))

const vault = createViewOnceCapture()
vault.bind(sock)                                      // messages.upsert
vault.onViewOnce(({ msg, unwrapped }) =>
    console.log('view-once', unwrapped.mediaType, 'from', msg.key.remoteJid))

const antilink = createAntiLinkGuard({ autoDelete: true }) // invite links in groups
antilink.bind(sock)
antilink.onDetected(({ chat, sender }) =>
    sock.sendMessage(chat, { text: `@${sender.split('@')[0]} no group links here!`, mentions: [sender] }))
Copy

// auto-read, AFK & tag-all
import { createAutoRead, createAfkManager, sendMentionAll, sendHideTag } from '@japofc/baileys'

const reader = createAutoRead({ denylist: ['boss@s.whatsapp.net'] })
reader.bind(sock)                       // blue-ticks everything else as it arrives
reader.pause(); reader.resume()

const afk = createAfkManager()
afk.bind(sock)
afk.setAfk(sender, 'lunch break 🍜')    // e.g. from an !afk command
afk.onAfkMention(({ chat, afkUser, reason, msg }) =>
    sock.sendMessage(chat, { text: `@${afkUser.split('@')[0]} is AFK: ${reason}`, mentions: [afkUser] }, { quoted: msg }))
afk.onReturn(({ user, missed }) => console.log(user, 'is back,', missed.length, 'pings while away'))

await sendMentionAll(sock, groupJid, 'Meeting in 5 minutes!') // visible @everyone
await sendHideTag(sock, groupJid, 'Silent announcement')      // pings all, clean text

// serializeMessage upgrades: m.isViewOnce, m.viewOnce, m.expiration, m.forward(jid), m.delete()
Copy

// pairing, but comfortable — one call from socket to paired
import { pairWithCode, getPairingCodeInfo } from '@japofc/baileys'

const result = await pairWithCode(sock, '628123456789', {
    customCode: 'abcd-efgh', // optional — any format, normalized for you
    onCode: (code, formatted) => console.log('Enter on your phone:', formatted)
})
if (result.restartRequired) { /* recreate the socket — standard after pairing */ }

const info = getPairingCodeInfo(state.creds)
console.log(info.formatted, '— expires in', Math.round(info.remainingMs / 1000), 's')
// requestPairingCode itself now also accepts "abcd-efgh" / "ABCD EFGH" custom codes
Copy

// community & moderation pack
import {
    createFloodGuard, createWordFilter, createWarnManager,
    createGatekeeper, createLevelSystem
} from '@japofc/baileys'

const flood = createFloodGuard({ maxMessages: 8, windowMs: 10_000 })
flood.bind(sock)
flood.onFlood(({ chat, user }) => warns.warn(user, { chat, reason: 'flooding' }))

const filter = createWordFilter({ words: ['judol'], patterns: [/j\s*u\s*d\s*o\s*l/i], autoDelete: true })
filter.bind(sock)
filter.onMatch(({ chat, sender }) => warns.warn(sender, { chat, reason: 'banned word' }))

const warns = createWarnManager({ threshold: 3 })
warns.onThreshold(async ({ user, chat }) => {
    await sock.groupParticipantsUpdate(chat, [user], 'remove') // three strikes, out
    warns.reset(user, chat)
})

const gate = createGatekeeper()
gate.banUser('pest@s.whatsapp.net', 'spam')
sock.ev.on('messages.upsert', gate.filter(async ({ messages }) => { /* clean traffic only */ }))

const levels = createLevelSystem()
levels.bind(sock)
levels.onLevelUp(({ user, chat, level }) =>
    sock.sendMessage(chat, { text: `🎉 @${user.split('@')[0]} reached level ${level}!`, mentions: [user] }))
levels.getLeaderboard(10, chat) // top 10 in this group
Copy

// sticker branding, economy, night mode & join captcha
import {
    setStickerExif, readStickerExif, createEconomy,
    createGroupScheduler, createVerifier
} from '@japofc/baileys'

// pure JS — no node-webpmux, works on static AND animated webp
const branded = setStickerExif(webpBuffer, { packName: 'My Pack', author: 'me', emojis: ['🔥'] })
await sock.sendMessage(jid, { sticker: branded })
readStickerExif(branded) // { 'sticker-pack-name': 'My Pack', … }

const eco = createEconomy({ dailyAmount: [100, 200], streakBonus: 25, transferFee: 0.05 })
eco.claimDaily(user)          // { claimed, amount, streak } or { remainingMs }
eco.transfer(userA, userB, 100)

const nightMode = createGroupScheduler()
nightMode.add({ group, action: 'close', at: '22:00' })          // announcement-only
nightMode.add({ group, action: 'open',  at: '06:00' })          // everyone can chat
nightMode.start(sock)

const verifier = createVerifier({ timeoutMs: 120_000 })
verifier.bind(sock) // auto math-captcha for every new member
verifier.onChallenge(({ chat, user, question }) =>
    sock.sendMessage(chat, { text: `👋 @${user.split('@')[0]} verify: ${question}`, mentions: [user] }))
verifier.onFailed(({ chat, user }) => sock.groupParticipantsUpdate(chat, [user], 'remove'))

// router upgrade — guards & categorized menu:
router.command('kick', handler, { adminOnly: true, category: 'Admin' })
router.command('shutdown', handler, { ownerOnly: true })         // owners: [...] in createRouter
router.command('daily', handler, { cooldownMs: 60_000, category: 'Economy' })
Copy

// analytics, anti-tagall, shop, group backup & menfess
import {
    createCommandStats, createAntiTagAllGuard, createShop,
    backupGroup, diffGroupBackup, restoreGroupSettings, createMenfessRelay
} from '@japofc/baileys'

const stats = createCommandStats()
router.use(stats.middleware())          // counts every executed command
stats.getTopCommands(5); stats.getBusiestHours()

const antiTag = createAntiTagAllGuard({ threshold: 5, autoDelete: true })
antiTag.bind(sock)
antiTag.onDetected(({ sender, hidden }) => console.log(sender, hidden ? 'hidetag!' : 'tag-all'))

const shop = createShop(eco)            // plugs into createEconomy()
shop.addItem({ id: 'potion', name: 'Potion', price: 250, consumable: true })
shop.buy(user, 'potion', 2); shop.useItem(user, 'potion')
eco.bet(user, 100, { winChance: 0.5, multiplier: 2 }) // economy upgrade

const backup = await backupGroup(sock, groupJid)      // settings + members, JSON-safe
const diff = await diffGroupBackup(sock, backup)      // joined/left/promoted/changed
await restoreGroupSettings(sock, backup)              // subject, desc, locks

const menfess = createMenfessRelay()
menfess.bind(sock)
await menfess.start(sock, sender, targetJid, 'first anonymous message')
// both sides now chat through the bot as Anon-1 / Anon-2 until "stop"

// more upgrades: verifier { challenge: 'emoji' }, level ranks (Newbie→Legend)
Copy