@bot-wa/baileys 0.0.0-stage → 0.2.0-alpha.0

package/lib/browser.js

@@ -0,0 +1,41 @@
+/**
+ * Browser identity for the Baileys handshake.
+ *
+ * The `browser` tuple (`[os, browserName, osVersion]`) feeds three parts of the
+ * WhatsApp Web handshake: the registration `DeviceProps.platformType`, the
+ * companion web-client type sent with QR/pairing codes, and the login
+ * `webInfo`. Since late July 2026 WhatsApp closes non-standard clients with
+ * 428 "Connection Terminated" before the QR is shown; Baileys 7.0.0-rc14 ships
+ * the refreshed handshake and its default identity is `Browsers.macOS('Chrome')`.
+ *
+ * The old presets used `'Desktop'` (DeviceProps DESKTOP / companion ELECTRON) and
+ * `'Bot'` (DeviceProps falls back to CHROME but the companion type becomes
+ * OTHER_WEB_CLIENT), i.e. identities that disagree with what rc14 sends by
+ * default. Every preset now resolves to Chrome on the chosen OS so all three
+ * handshake fields agree.
+ */
+import { Browsers } from '@whiskeysockets/baileys';
+/** The browser name every preset advertises; matches Baileys' own default. */
+const BROWSER_NAME = 'Chrome';
+/**
+ * Resolve the `browser` socket option.
+ *
+ * - `undefined` → `undefined`: the caller must then OMIT the `browser` key so
+ *   Baileys' default (`Browsers.macOS('Chrome')`) applies. `makeWASocket` spreads
+ *   the user config over its defaults, so even `browser: undefined` would clobber it.
+ * - a preset → `Browsers.<os>('Chrome')`.
+ * - a tuple → returned verbatim (escape hatch, e.g. `Browsers.macOS('Desktop')`
+ *   for full-history desktop emulation). WhatsApp may reject it.
+ */
+export function resolveBrowser(browser) {
+    if (browser === undefined)
+        return undefined;
+    if (Array.isArray(browser))
+        return browser;
+    switch (browser) {
+        case 'macOS': return Browsers.macOS(BROWSER_NAME);
+        case 'ubuntu': return Browsers.ubuntu(BROWSER_NAME);
+        case 'windows': return Browsers.windows(BROWSER_NAME);
+        case 'appropriate': return Browsers.appropriate(BROWSER_NAME);
+    }
+}

package/lib/identity.d.ts

@@ -0,0 +1,52 @@
+export declare class IdentityStore {
+    /** Bidirectional: lid→pn AND pn→lid (see {@link putBounded}). */
+    private map;
+    /**
+     * Record a `primary`/`alt` pair from an inbound key. `alt` is the PN twin of
+     * `primary` (or vice-versa); the pair is stored only when one side is a LID and
+     * the other a PN. Null/empty inputs are ignored.
+     */
+    observe(primary?: string | null, alt?: string | null): void;
+    /**
+     * Map a LID to its learned PN. Returns `jid` unchanged when it is not a LID, or
+     * when no PN twin has been learned yet (best-effort: it stabilises once learned).
+     */
+    canonical(jid: string): string;
+    /** True if a PN twin is already known for this LID (skips redundant async lookups). */
+    knowsPnFor(lid: string): boolean;
+    /** The learned twin of a user JID (the PN of a LID or the LID of a PN), if any. */
+    alias(jid: string): string | undefined;
+    /**
+     * Canonical id for a bare user/chat JID carried by a non-message event
+     * (presence, call, group participant). Learns `alt`, the twin the event
+     * carries alongside (`callerPn`, `authorPn`, a participant's `phoneNumber`),
+     * then applies the same rule as messages: learned LID → PN, device suffix
+     * stripped. Group/broadcast JIDs pass through normalised.
+     */
+    resolve(jid?: string | null, alt?: string | null): string;
+}
+/** The key fields canonicalisation reads; matches `WAMessageKey` and Baileys' reaction/vote keys. */
+export interface IdentityKey {
+    remoteJid?: string | null;
+    remoteJidAlt?: string | null;
+    participant?: string | null;
+    participantAlt?: string | null;
+    fromMe?: boolean | null;
+}
+/**
+ * The single LID/PN rule for a message key, shared by every emitted event
+ * (messages, reactions, poll votes) so one person never shows up as a LID on
+ * one event type and as a PN on another.
+ *
+ * Learns the LID↔PN pairs the key exposes, prefers the PN twin, maps a learned
+ * LID back to its PN and strips device suffixes. `participant` overrides
+ * `key.participant` (Baileys puts broadcast senders on `WAMessage.participant`).
+ * For a `fromMe` DM key `senderId` is the chat partner, as for messages; callers
+ * that need the author of their own action substitute the bot's id.
+ */
+export declare function canonicalKey(key: IdentityKey, identity: IdentityStore, participant?: string | null): {
+    chatId: string;
+    senderId: string;
+    isGroup: boolean;
+    rawParticipant: string | null;
+};

package/lib/identity.js

@@ -0,0 +1,107 @@
+/**
+ * IdentityStore — stabilises Baileys 7 LID/PN identity across messages.
+ *
+ * Baileys 7 addresses a DM partner (or group participant) by their opaque LID
+ * (`…@lid`) and rides the phone-number twin (`…@s.whatsapp.net`, "PN") alongside
+ * in `remoteJidAlt`/`participantAlt`. That twin is NOT present on every message:
+ * the same partner can arrive as `LID + PN twin` on one message and as a bare
+ * `LID` on the next. Because the conversation runtime keys active flows by
+ * identity, an inconsistent identity silently splits one person across two keys —
+ * the active `ask` never receives the answer and the flow re-prompts forever
+ * (the "flujos tienen líos" bug seen live).
+ *
+ * This store LEARNS a LID↔PN pairing the first time it sees both forms together,
+ * then CANONICALISES any later bare LID back to its PN. With it, all three
+ * representations (PN-only, LID+twin, bare-LID-once-learned) collapse to a single
+ * stable PN identity, so `keyFor()` never flips mid-conversation.
+ */
+import { normalize, normalizeInboundKey, isLidUser, isPnUser } from './jid.js';
+import { putBounded } from './boundedMap.js';
+/** Cap on stored pairs — one bot rarely talks to more than a few thousand LIDs. */
+const IDENTITY_MAX = 4000;
+export class IdentityStore {
+    /** Bidirectional: lid→pn AND pn→lid (see {@link putBounded}). */
+    map = new Map();
+    /**
+     * Record a `primary`/`alt` pair from an inbound key. `alt` is the PN twin of
+     * `primary` (or vice-versa); the pair is stored only when one side is a LID and
+     * the other a PN. Null/empty inputs are ignored.
+     */
+    observe(primary, alt) {
+        if (!primary || !alt)
+            return;
+        const p = normalize(primary);
+        const a = normalize(alt);
+        if (isLidUser(p) && isPnUser(a))
+            putBounded(this.map, p, a, IDENTITY_MAX);
+        else if (isPnUser(p) && isLidUser(a))
+            putBounded(this.map, a, p, IDENTITY_MAX);
+    }
+    /**
+     * Map a LID to its learned PN. Returns `jid` unchanged when it is not a LID, or
+     * when no PN twin has been learned yet (best-effort: it stabilises once learned).
+     */
+    canonical(jid) {
+        if (!jid || !isLidUser(jid))
+            return jid;
+        const pn = this.map.get(normalize(jid));
+        return pn && isPnUser(pn) ? pn : jid;
+    }
+    /** True if a PN twin is already known for this LID (skips redundant async lookups). */
+    knowsPnFor(lid) {
+        if (!lid || !isLidUser(lid))
+            return false;
+        const pn = this.map.get(normalize(lid));
+        return !!pn && isPnUser(pn);
+    }
+    /** The learned twin of a user JID (the PN of a LID or the LID of a PN), if any. */
+    alias(jid) {
+        if (!jid)
+            return undefined;
+        return this.map.get(normalize(jid));
+    }
+    /**
+     * Canonical id for a bare user/chat JID carried by a non-message event
+     * (presence, call, group participant). Learns `alt`, the twin the event
+     * carries alongside (`callerPn`, `authorPn`, a participant's `phoneNumber`),
+     * then applies the same rule as messages: learned LID → PN, device suffix
+     * stripped. Group/broadcast JIDs pass through normalised.
+     */
+    resolve(jid, alt) {
+        const primary = jid || alt;
+        if (!primary)
+            return '';
+        this.observe(jid, alt);
+        return this.canonical(normalize(primary) || primary);
+    }
+}
+/**
+ * The single LID/PN rule for a message key, shared by every emitted event
+ * (messages, reactions, poll votes) so one person never shows up as a LID on
+ * one event type and as a PN on another.
+ *
+ * Learns the LID↔PN pairs the key exposes, prefers the PN twin, maps a learned
+ * LID back to its PN and strips device suffixes. `participant` overrides
+ * `key.participant` (Baileys puts broadcast senders on `WAMessage.participant`).
+ * For a `fromMe` DM key `senderId` is the chat partner, as for messages; callers
+ * that need the author of their own action substitute the bot's id.
+ */
+export function canonicalKey(key, identity, participant) {
+    const isGroup = (key.remoteJid ?? '').endsWith('@g.us');
+    const rawParticipant = participant ?? key.participant ?? null;
+    identity.observe(key.remoteJid, key.remoteJidAlt);
+    identity.observe(rawParticipant, key.participantAlt);
+    const { chat, sender } = normalizeInboundKey({
+        remoteJid: key.remoteJid,
+        remoteJidAlt: key.remoteJidAlt,
+        participant: rawParticipant,
+        participantAlt: key.participantAlt,
+        fromMe: key.fromMe,
+    }, isGroup);
+    return {
+        chatId: normalize(identity.canonical(chat) ?? chat),
+        senderId: normalize(identity.canonical(sender) ?? sender),
+        isGroup,
+        rawParticipant,
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @bot-wa/baileys — WhatsApp transport for @bot-wa/core (Baileys 7, IProvider v2).
+ *
+ * @example
+ * ```ts
+ * import { Bot } from '@bot-wa/core'
+ * import { BaileysProvider } from '@bot-wa/baileys'
+ *
+ * const bot = new Bot({ provider: new BaileysProvider({ session: 'demo', qr: { terminal: true } }) })
+ * await bot.start()
+ * ```
+ */
+export { BaileysProvider } from './BaileysProvider.js';
+export type { BaileysProviderConfig, QrConfig } from './BaileysProvider.js';
+export { toBaileysLogger, isBaileysLogger } from './logger.js';
+export type { BaileysLogger } from './logger.js';
+export type { BrowserConfig, BrowserPreset } from './browser.js';
+export type { PollStore, StoredPoll, PollOption } from './polls.js';
+export { IdentityStore } from './identity.js';
+export { toJid, sanitizeNumber, normalize as normalizeJid, parseJid, buildJid, shortJid, isGroup, isBroadcast, isStatus, isNewsletter, isPn, isLid, sameUser, toUserId, toChatId, isValidJid, } from './jid.js';
+export type { JID, JidInput } from './jid.js';
+export { RateLimiter, RateLimiterTimeout } from './RateLimiter.js';
+export type { RateLimitConfig, RateLimitBucketConfig, RateLimitJitterConfig } from './RateLimiter.js';
+export { toMediaUpload, toBuffer as mediaToBuffer, makeSticker, transcodeToOpus, resolveRemoteMedia, REMOTE_MEDIA_MAX_BYTES } from './MediaProcessor.js';
+export type { StickerOptions, RemoteMediaConfig, WAMediaUpload } from './MediaProcessor.js';
+export { toInbound } from './toInbound.js';
+export { toOutbound } from './toOutbound.js';
+export { classifyDisconnect, backoffDelay, MAX_RECONNECT_ATTEMPTS } from './reconnect.js';
+export type { DisconnectAction } from './reconnect.js';
+export { assertSessionDirectorySafe, removeSessionDirectory, resolveSessionDirectory, } from './sessionPath.js';

package/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * @bot-wa/baileys — WhatsApp transport for @bot-wa/core (Baileys 7, IProvider v2).
+ *
+ * @example
+ * ```ts
+ * import { Bot } from '@bot-wa/core'
+ * import { BaileysProvider } from '@bot-wa/baileys'
+ *
+ * const bot = new Bot({ provider: new BaileysProvider({ session: 'demo', qr: { terminal: true } }) })
+ * await bot.start()
+ * ```
+ */
+export { BaileysProvider } from './BaileysProvider.js';
+export { toBaileysLogger, isBaileysLogger } from './logger.js';
+// Identity + JID helpers (WhatsApp-specific; advanced users)
+export { IdentityStore } from './identity.js';
+export { toJid, sanitizeNumber, normalize as normalizeJid, parseJid, buildJid, shortJid, isGroup, isBroadcast, isStatus, isNewsletter, isPn, isLid, sameUser, toUserId, toChatId, isValidJid, } from './jid.js';
+// Anti-ban rate limiter
+export { RateLimiter, RateLimiterTimeout } from './RateLimiter.js';
+// Media processing (sticker/opus/upload)
+export { toMediaUpload, toBuffer as mediaToBuffer, makeSticker, transcodeToOpus, resolveRemoteMedia, REMOTE_MEDIA_MAX_BYTES } from './MediaProcessor.js';
+// Low-level normalizers (advanced)
+export { toInbound } from './toInbound.js';
+export { toOutbound } from './toOutbound.js';
+// reconnect classification (advanced)
+export { classifyDisconnect, backoffDelay, MAX_RECONNECT_ATTEMPTS } from './reconnect.js';
+// Session path validation (advanced/self-hosted tooling)
+export { assertSessionDirectorySafe, removeSessionDirectory, resolveSessionDirectory, } from './sessionPath.js';

package/lib/jid.d.ts

@@ -0,0 +1,70 @@
+/**
+ * JID utilities — PN/LID aware for Baileys 7.x.
+ *
+ * The user should never have to handle PN/LID duality manually; these helpers
+ * wrap Baileys' own jid functions with friendly names.
+ *
+ * @example
+ * ```ts
+ * import { toJid, isGroup, isPn } from '@bot-wa/core'
+ *
+ * const jid = toJid('573001234567')              // '573001234567@s.whatsapp.net'
+ * const isGroupChat = isGroup(jid)              // false
+ * const isPrivate = isPn(jid)                   // true
+ * ```
+ */
+import { isJidGroup, isJidBroadcast, isJidStatusBroadcast, isJidNewsletter, isPnUser as baileysIsPnUser, isLidUser as baileysIsLidUser, areJidsSameUser } from '@whiskeysockets/baileys';
+/** WhatsApp JID — `number@s.whatsapp.net`, `id@g.us`, `status@broadcast`, `…@lid`. */
+export type JID = string;
+import type { ChatId, UserId } from '@bot-wa/core';
+export type { ChatId, UserId };
+/** Anything that can be turned into a JID: full JID, plain number, or `{ groupId, userId }`. */
+export type JidInput = string | number | {
+    groupId: string;
+    userId?: string;
+};
+export { isJidGroup as isGroup, isJidBroadcast as isBroadcast, isJidStatusBroadcast as isStatus, isJidNewsletter as isNewsletter, baileysIsPnUser as isPn, baileysIsLidUser as isLid, areJidsSameUser as sameUser, };
+/** Format a raw phone number/string into a valid JID. */
+export declare function toJid(input: JidInput, kind?: 'user' | 'group' | 'broadcast'): JID;
+/** Extract just the digits (no '+', '-', spaces, '@...'). */
+export declare function sanitizeNumber(value: string | number): string;
+/** Strip device suffix & lowercase — canonical identifier. */
+export declare function normalize(jid: JID): JID;
+/** Parse a JID into components. */
+export declare function parseJid(jid: JID): {
+    user: string | null;
+    server: string | null;
+    device: number | undefined;
+    domainType: number | undefined;
+};
+/** Re-encode components as JID. Accept plain strings for simplicity. */
+export declare function buildJid(user: string, server: string): JID;
+/** Quick string form for display: hides long LIDs/jids. */
+export declare function shortJid(jid: JID): string;
+/** Coerce any input to a `UserId`. */
+export declare function toUserId(input: JidInput): UserId;
+/** Coerce any input to a `ChatId` (keeps group/broadcast if present). */
+export declare function toChatId(input: JidInput): ChatId;
+/** Validate basic JID shape (cheap, not exhaustive). */
+export declare function isValidJid(value: string): boolean;
+/** True if `jid` is a phone-number-form user JID (`…@s.whatsapp.net`). */
+export declare function isPnUser(jid: string): boolean;
+/** True if `jid` is a LID-form user JID (`…@lid`) — Baileys 7's opaque identity. */
+export declare function isLidUser(jid: string): boolean;
+/**
+ * Normalize an inbound message key to PN-preferred `chat`/`sender` identifiers.
+ *
+ * - DM: `chat` prefers `remoteJidAlt` (PN) when `remoteJid` arrived as a LID.
+ * - Group: `chat` is always the group JID (`remoteJid`, never a LID); `sender`
+ *   prefers `participantAlt` (PN) over the raw `participant` (possibly a LID).
+ */
+export declare function normalizeInboundKey(key: {
+    remoteJid?: string | null;
+    remoteJidAlt?: string | null;
+    participant?: string | null;
+    participantAlt?: string | null;
+    fromMe?: boolean | null;
+}, isGroup: boolean): {
+    chat: string;
+    sender: string;
+};

package/lib/jid.js

@@ -0,0 +1,119 @@
+/**
+ * JID utilities — PN/LID aware for Baileys 7.x.
+ *
+ * The user should never have to handle PN/LID duality manually; these helpers
+ * wrap Baileys' own jid functions with friendly names.
+ *
+ * @example
+ * ```ts
+ * import { toJid, isGroup, isPn } from '@bot-wa/core'
+ *
+ * const jid = toJid('573001234567')              // '573001234567@s.whatsapp.net'
+ * const isGroupChat = isGroup(jid)              // false
+ * const isPrivate = isPn(jid)                   // true
+ * ```
+ */
+import { jidNormalizedUser, jidDecode, jidEncode, isJidGroup, isJidBroadcast, isJidStatusBroadcast, isJidNewsletter, isPnUser as baileysIsPnUser, isLidUser as baileysIsLidUser, areJidsSameUser, } from '@whiskeysockets/baileys';
+export { isJidGroup as isGroup, isJidBroadcast as isBroadcast, isJidStatusBroadcast as isStatus, isJidNewsletter as isNewsletter, baileysIsPnUser as isPn, baileysIsLidUser as isLid, areJidsSameUser as sameUser, };
+/** Format a raw phone number/string into a valid JID. */
+export function toJid(input, kind = 'user') {
+    if (typeof input === 'object') {
+        if (kind === 'group' || input.userId) {
+            const num = sanitizeNumber(input.groupId);
+            const uid = input.userId ? sanitizeNumber(input.userId) : '';
+            return uid ? `${num}@g.us:${uid}` : `${num}@g.us`;
+        }
+    }
+    const raw = String(input);
+    if (raw.includes('@'))
+        return raw;
+    return kind === 'group'
+        ? `${sanitizeNumber(raw)}@g.us`
+        : kind === 'broadcast'
+            ? `${sanitizeNumber(raw)}@broadcast`
+            : `${sanitizeNumber(raw)}@s.whatsapp.net`;
+}
+/** Extract just the digits (no '+', '-', spaces, '@...'). */
+export function sanitizeNumber(value) {
+    return String(value).replace(/[^\d]/g, '');
+}
+/** Strip device suffix & lowercase — canonical identifier. */
+export function normalize(jid) {
+    return jidNormalizedUser(jid);
+}
+/** Parse a JID into components. */
+export function parseJid(jid) {
+    const d = (jidDecode(jid) ?? {});
+    return {
+        user: d.user ?? null,
+        server: d.server ?? null,
+        device: d.device,
+        domainType: d.domainType,
+    };
+}
+/** Re-encode components as JID. Accept plain strings for simplicity. */
+export function buildJid(user, server) {
+    return jidEncode(user, server);
+}
+/** Quick string form for display: hides long LIDs/jids. */
+export function shortJid(jid) {
+    const { user, server } = parseJid(jid);
+    if (!user || !server)
+        return jid;
+    const short = user.length > 8 ? user.slice(-8) : user;
+    return `…${short}@${server}`;
+}
+/** Coerce any input to a `UserId`. */
+export function toUserId(input) {
+    return toJid(input, 'user');
+}
+/** Coerce any input to a `ChatId` (keeps group/broadcast if present). */
+export function toChatId(input) {
+    const raw = String(input);
+    if (raw.includes('@'))
+        return raw;
+    return toJid(raw, 'user');
+}
+/** Validate basic JID shape (cheap, not exhaustive). */
+export function isValidJid(value) {
+    try {
+        return Boolean(jidDecode(value));
+    }
+    catch {
+        return false;
+    }
+}
+/* ============================================================================
+ * LID/PN IDENTITY (Baileys 7)
+ * ============================================================================
+ *
+ * Baileys 7 migrated WhatsApp's user identity to LIDs (`@lid`) — an opaque,
+ * per-account identifier that replaces the phone-number JID (`@s.whatsapp.net`,
+ * "PN") as the primary identity. Inbound events still carry the PN twin
+ * alongside the LID (`remoteJidAlt`/`participantAlt`), and the wrapper always
+ * prefers the PN form for anything user-facing (`ctx.from`, `ctx.sender`).
+ * ========================================================================== */
+/** True if `jid` is a phone-number-form user JID (`…@s.whatsapp.net`). */
+export function isPnUser(jid) {
+    return jid.endsWith('@s.whatsapp.net');
+}
+/** True if `jid` is a LID-form user JID (`…@lid`) — Baileys 7's opaque identity. */
+export function isLidUser(jid) {
+    return jid.endsWith('@lid');
+}
+/**
+ * Normalize an inbound message key to PN-preferred `chat`/`sender` identifiers.
+ *
+ * - DM: `chat` prefers `remoteJidAlt` (PN) when `remoteJid` arrived as a LID.
+ * - Group: `chat` is always the group JID (`remoteJid`, never a LID); `sender`
+ *   prefers `participantAlt` (PN) over the raw `participant` (possibly a LID).
+ */
+export function normalizeInboundKey(key, isGroup) {
+    const remote = key.remoteJid ?? '';
+    if (isGroup) {
+        const sender = (key.participantAlt && isPnUser(key.participantAlt) ? key.participantAlt : key.participant) ?? '';
+        return { chat: remote, sender };
+    }
+    const chat = key.remoteJidAlt && isPnUser(key.remoteJidAlt) && isLidUser(remote) ? key.remoteJidAlt : remote;
+    return { chat, sender: chat };
+}

package/lib/logger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Logger adapter — `BaileysProviderConfig.logger` takes any core `LoggerLike`
+ * (pino, `console`, a custom object), but Baileys' own functions (`makeWASocket`,
+ * `makeCacheableSignalKeyStore`, `downloadMediaMessage`) need its `ILogger`
+ * shape: a string `level`, `child()` and `trace()`. {@link toBaileysLogger} passes a
+ * pino-shaped logger through untouched and wraps anything else.
+ */
+import type { LoggerLike } from '@bot-wa/core';
+/**
+ * Structural copy of Baileys' `ILogger` (its main entry does not re-export it).
+ * pino's `Logger` satisfies it.
+ */
+export interface BaileysLogger {
+    level: string;
+    child(obj: Record<string, unknown>): BaileysLogger;
+    trace(obj: unknown, msg?: string): void;
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+/** Already shaped like Baileys' `ILogger` (pino and friends): a string `level`, `child()` and `trace()`. */
+export declare function isBaileysLogger(logger: LoggerLike): logger is LoggerLike & BaileysLogger;
+/**
+ * The logger handed to Baileys. A logger that already has Baileys' shape (pino) is returned
+ * as is, byte-for-byte the previous behaviour. Anything else is wrapped:
+ * - `trace` forwards to the logger's own `trace` when it has one, else it is a no-op
+ *   (Baileys' trace output is far too chatty to map onto `debug`);
+ * - `level` is the logger's string `level` when it has one, else `fallbackLevel`
+ *   (Baileys only compares it with `'trace'`);
+ * - `child(bindings)` wraps `logger.child(bindings)` when available, else the same logger
+ *   (the bindings are dropped).
+ */
+export declare function toBaileysLogger(logger: LoggerLike, fallbackLevel?: string): BaileysLogger;

package/lib/logger.js

@@ -0,0 +1,44 @@
+/**
+ * Logger adapter — `BaileysProviderConfig.logger` takes any core `LoggerLike`
+ * (pino, `console`, a custom object), but Baileys' own functions (`makeWASocket`,
+ * `makeCacheableSignalKeyStore`, `downloadMediaMessage`) need its `ILogger`
+ * shape: a string `level`, `child()` and `trace()`. {@link toBaileysLogger} passes a
+ * pino-shaped logger through untouched and wraps anything else.
+ */
+/** Already shaped like Baileys' `ILogger` (pino and friends): a string `level`, `child()` and `trace()`. */
+export function isBaileysLogger(logger) {
+    const l = logger;
+    return typeof l.level === 'string' && typeof l.child === 'function' && typeof l.trace === 'function';
+}
+/**
+ * The logger handed to Baileys. A logger that already has Baileys' shape (pino) is returned
+ * as is, byte-for-byte the previous behaviour. Anything else is wrapped:
+ * - `trace` forwards to the logger's own `trace` when it has one, else it is a no-op
+ *   (Baileys' trace output is far too chatty to map onto `debug`);
+ * - `level` is the logger's string `level` when it has one, else `fallbackLevel`
+ *   (Baileys only compares it with `'trace'`);
+ * - `child(bindings)` wraps `logger.child(bindings)` when available, else the same logger
+ *   (the bindings are dropped).
+ */
+export function toBaileysLogger(logger, fallbackLevel = 'info') {
+    if (isBaileysLogger(logger))
+        return logger;
+    const extras = logger;
+    const level = typeof extras.level === 'string' ? extras.level : fallbackLevel;
+    const trace = typeof extras.trace === 'function'
+        ? (...a) => { extras.trace.apply(logger, a); }
+        : () => { };
+    return {
+        level,
+        child(bindings) {
+            const child = typeof logger.child === 'function' ? logger.child(bindings) : logger;
+            return toBaileysLogger(child, level);
+        },
+        trace,
+        // Forward only the arguments Baileys passed (a trailing `undefined` would print on console).
+        debug: (...a) => logger.debug(...a),
+        info: (...a) => logger.info(...a),
+        warn: (...a) => logger.warn(...a),
+        error: (...a) => logger.error(...a),
+    };
+}

package/lib/mediaRef.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Durable media references for the Baileys transport (`IProvider.serializeMediaRef` /
+ * `rehydrateMediaRef`).
+ *
+ * A Baileys `MediaRef.token` is the live `WAMessage`. For the durable inbox it is reduced to
+ * what a download needs: the media content (CDN url, direct path, media key and hashes,
+ * WITHOUT thumbnails, captions or quoted context) as protobuf bytes, plus the raw message key,
+ * which only the re-upload request (`sock.updateMediaMessage`) uses when the CDN copy expired.
+ * The key is never used for identity, keying or routing (LID/PN rules are untouched).
+ *
+ * The stored value is UNTRUSTED when read back: every field is validated and a malformed,
+ * oversized, unknown-version or mismatching value is rejected with a `ProviderError`.
+ */
+import { type WAMessage, type WAMessageKey } from '@whiskeysockets/baileys';
+import { type MediaRef, type SerializedMediaRef } from '@bot-wa/core';
+/** Format version written by {@link serializeBaileysMediaRef}. */
+export declare const BAILEYS_MEDIA_REF_VERSION = 1;
+/** The journaled data of format v1. */
+export interface BaileysMediaRefV1 {
+    /** The raw WhatsApp message key (re-upload requests only). */
+    key: {
+        remoteJid: string;
+        id: string;
+        fromMe?: boolean;
+        participant?: string;
+    };
+    /** Base64 `proto.Message` holding exactly one media content. */
+    m: string;
+    /** `messageTimestamp` (seconds). */
+    t?: number;
+}
+/** Options of {@link serializeBaileysMediaRef}. */
+export interface SerializeMediaOptions {
+    /** Journal view-once media too (its key then lives at rest). Default `false`. */
+    viewOnce?: boolean;
+}
+/**
+ * The durable reference of an inbound media message, or `undefined` when it must not (or
+ * cannot) be journaled: view-once media (unless `options.viewOnce`), no media key or path,
+ * an unexpected shape. Never throws.
+ */
+export declare function serializeBaileysMediaRef(ref: MediaRef, options?: SerializeMediaOptions): SerializedMediaRef | undefined;
+/**
+ * Decode and validate a journaled reference into the message key and a `WAMessage` holding
+ * only the media content. @throws {ProviderError} on anything unexpected.
+ */
+export declare function parseBaileysMediaRef(stored: SerializedMediaRef, kind: MediaRef['kind']): {
+    key: WAMessageKey;
+    message: WAMessage;
+};