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

package/lib/MediaProcessor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MediaProcessor — convert MediaSource inputs into Baileys' WAMediaUpload.
+ *
+ * Includes sticker conversion (sharp) and audio PTT transcode (fluent-ffmpeg).
+ */
+import { type MediaSource, type OutboundContent } from '@bot-wa/core';
+import { type HostResolver } from '@bot-wa/http';
+export type WAMediaUpload = Buffer | {
+    url: string;
+} | {
+    stream: NodeJS.ReadableStream;
+};
+/** Normalize any MediaSource into a Baileys WAMediaUpload. */
+export declare function toMediaUpload(source: MediaSource): WAMediaUpload;
+/**
+ * How the provider fetches outbound `{ url }` / `https://…` media.
+ *
+ * Baileys downloads URL media with plain `fetch`, which follows redirects
+ * without checking where they land: a public URL that redirects to
+ * `http://169.254.169.254/…` would make the bot fetch (and send) internal data.
+ * By default the provider downloads remote media itself through
+ * `@bot-wa/http` (every redirect hop vetted, connection pinned to the vetted
+ * address, size and time capped) and hands Baileys a Buffer.
+ */
+export interface RemoteMediaConfig {
+    /**
+     * Accept media hosted on (or redirecting to) loopback, private or link-local
+     * addresses. `true` restores the legacy behavior: the URL is passed to
+     * Baileys untouched and streamed by it. Default `false`.
+     */
+    allowPrivateHosts?: boolean;
+    /** Accept plain `http:` URLs (each hop is still vetted). Default `true`. */
+    allowHttp?: boolean;
+    /** Largest media accepted, in bytes. Default 64 MiB. */
+    maxBytes?: number;
+    /** Time allowed for the whole download. Default 60 s. */
+    timeoutMs?: number;
+    /** Redirect hops allowed. Default 3. */
+    maxRedirects?: number;
+    /** DNS resolver used to vet hosts (tests, egress gateways). */
+    resolver?: HostResolver;
+    /** Custom fetch (tests, egress proxies). */
+    fetch?: typeof globalThis.fetch;
+}
+export declare const REMOTE_MEDIA_MAX_BYTES: number;
+/**
+ * Download `{ url }` media through `@bot-wa/http` and return a Buffer, unless
+ * {@link RemoteMediaConfig.allowPrivateHosts} opts back into the pass-through.
+ * Rejects with {@link PayloadTooLargeError} over the size cap and
+ * {@link UnsupportedContentError} for an unsafe or failing URL.
+ */
+export declare function resolveRemoteMedia(upload: WAMediaUpload, kind: OutboundContent['kind'], config?: RemoteMediaConfig): Promise<WAMediaUpload>;
+/** Read a MediaSource fully into a Buffer (used by sticker/audio transcode). */
+export declare function toBuffer(source: MediaSource): Promise<Buffer>;
+export interface StickerOptions {
+    pack?: string;
+    author?: string;
+}
+export declare function makeSticker(source: MediaSource, opts?: StickerOptions): Promise<Buffer>;
+export declare function transcodeToOpus(source: MediaSource): Promise<Buffer>;

package/lib/MediaProcessor.js

@@ -0,0 +1,137 @@
+/**
+ * MediaProcessor — convert MediaSource inputs into Baileys' WAMediaUpload.
+ *
+ * Includes sticker conversion (sharp) and audio PTT transcode (fluent-ffmpeg).
+ */
+import { readFileSync, existsSync } from 'fs';
+import sharp from 'sharp';
+import ffmpeg from 'fluent-ffmpeg';
+import ffmpegInstaller from '@ffmpeg-installer/ffmpeg';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { readFile } from 'fs/promises';
+ffmpeg.setFfmpegPath(ffmpegInstaller.path);
+import { PayloadTooLargeError, UnsupportedContentError } from '@bot-wa/core';
+import { fetchBuffer, SecureHttpError } from '@bot-wa/http';
+/** Normalize any MediaSource into a Baileys WAMediaUpload. */
+export function toMediaUpload(source) {
+    if (typeof source === 'string') {
+        // URL → leave as URL (Baileys streams)
+        if (/^https?:\/\//i.test(source) || !existsSync(source)) {
+            return { url: source };
+        }
+        // Local path → Buffer (could also be { url: 'file://...' })
+        return readFileSync(source);
+    }
+    if (Buffer.isBuffer(source))
+        return source;
+    if (source.url)
+        return { url: source.url };
+    if (source.buffer)
+        return source.buffer;
+    if (source.path)
+        return readFileSync(source.path);
+    if (source.stream)
+        return { stream: source.stream };
+    throw new Error(`Invalid MediaSource: ${typeof source}`);
+}
+export const REMOTE_MEDIA_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Download `{ url }` media through `@bot-wa/http` and return a Buffer, unless
+ * {@link RemoteMediaConfig.allowPrivateHosts} opts back into the pass-through.
+ * Rejects with {@link PayloadTooLargeError} over the size cap and
+ * {@link UnsupportedContentError} for an unsafe or failing URL.
+ */
+export async function resolveRemoteMedia(upload, kind, config = {}) {
+    if (Buffer.isBuffer(upload) || !('url' in upload) || !/^https?:\/\//i.test(upload.url))
+        return upload;
+    if (config.allowPrivateHosts === true)
+        return upload;
+    try {
+        return await fetchBuffer(upload.url, {
+            allowHttp: config.allowHttp !== false,
+            maxBytes: config.maxBytes ?? REMOTE_MEDIA_MAX_BYTES,
+            timeoutMs: config.timeoutMs ?? 60_000,
+            ...(config.maxRedirects !== undefined ? { maxRedirects: config.maxRedirects } : {}),
+            ...(config.resolver ? { resolver: config.resolver } : {}),
+            ...(config.fetch ? { fetch: config.fetch } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof SecureHttpError && error.code === 'RESPONSE_TOO_LARGE') {
+            throw new PayloadTooLargeError(`${kind} media exceeds ${config.maxBytes ?? REMOTE_MEDIA_MAX_BYTES} bytes`);
+        }
+        const reason = error instanceof SecureHttpError ? error.message : 'download failed';
+        const wrapped = new UnsupportedContentError(kind, `${kind} media URL rejected: ${reason}`);
+        wrapped.cause = error;
+        throw wrapped;
+    }
+}
+/** Read a MediaSource fully into a Buffer (used by sticker/audio transcode). */
+export async function toBuffer(source) {
+    if (typeof source === 'string') {
+        if (/^https?:\/\//i.test(source)) {
+            throw new Error('Remote URL not supported here — download it first');
+        }
+        return readFile(source);
+    }
+    if (Buffer.isBuffer(source))
+        return source;
+    if (source.buffer)
+        return source.buffer;
+    if (source.path)
+        return readFile(source.path);
+    throw new Error('Cannot convert this MediaSource to buffer');
+}
+export async function makeSticker(source, opts = {}) {
+    const buffer = await toBuffer(source);
+    // PNG/WebP 512×512 transparent padding ( whatsapp sticker spec )
+    const padded = await sharp(buffer, { failOn: 'none' })
+        .resize(512, 512, {
+        fit: 'contain',
+        background: { r: 0, g: 0, b: 0, alpha: 0 },
+    })
+        .extend({
+        top: 0, bottom: 0, left: 0, right: 0,
+        background: { r: 0, g: 0, b: 0, alpha: 0 },
+    })
+        .webp()
+        .toBuffer();
+    if (!opts.pack && !opts.author)
+        return padded;
+    // EXIF packing with author/pack metadata omitted for now; returns plain WebP
+    return padded;
+}
+/* =============================================================================
+ * AUDIO (PTT transcode)
+ * ========================================================================== */
+import { writeFile, unlink } from 'fs/promises';
+import { randomUUID } from 'crypto';
+export async function transcodeToOpus(source) {
+    const input = await toBuffer(source);
+    const inPath = join(tmpdir(), `baileys-in-${randomUUID()}.bin`);
+    const outPath = join(tmpdir(), `baileys-out-${randomUUID()}.ogg`);
+    await writeFile(inPath, input);
+    try {
+        await new Promise((resolve, reject) => {
+            ffmpeg(inPath)
+                .outputOptions([
+                '-c:a libopus',
+                '-ac 1',
+                '-avoid_negative_ts make_zero',
+                '-ar 48000',
+            ])
+                .output(outPath)
+                .on('end', () => resolve())
+                .on('error', (err) => reject(err))
+                .run();
+        });
+        return await readFile(outPath);
+    }
+    finally {
+        // Always clean up both temp files — even when ffmpeg rejects — so a stream
+        // of failed transcodes can't leak the OS temp dir.
+        await unlink(inPath).catch(() => { });
+        await unlink(outPath).catch(() => { });
+    }
+}

package/lib/RateLimiter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * RateLimiter — Token bucket rate limiter for outbound messages.
+ *
+ * WhatsApp bans accounts that send too many messages in a short period. This
+ * rate limiter sits in the `before('send')` hook pipeline and enforces:
+ *   - Per-chat limits (e.g. max 5 messages per 10 seconds to the same chat)
+ *   - Global limits (e.g. max 50 messages per 60 seconds across all chats)
+ *   - Optional human-like jitter between sends
+ *
+ * When a limit is exceeded, the send is queued (not dropped) and released
+ * once the bucket refills. A blocked chat never stalls other chats: the queue
+ * is scanned for the first send whose buckets currently allow it. Sends that
+ * wait longer than `maxWait` are rejected so a caller can never hang forever.
+ *
+ * @example
+ * ```ts
+ * const bot = new Bot({
+ *   session: 'my-bot',
+ *   rateLimit: {
+ *     perChat: { max: 5, window: '10s' },
+ *     global: { max: 50, window: '60s' },
+ *     jitter: { min: 500, max: 1500 },
+ *   },
+ * })
+ * ```
+ */
+import { RateLimitedError } from '@bot-wa/core';
+export interface RateLimitBucketConfig {
+    /** Maximum tokens (messages) allowed in the window. */
+    max: number;
+    /** Time window for the bucket (e.g. '10s', '1m'). */
+    window: string | number;
+}
+export interface RateLimitJitterConfig {
+    /** Minimum delay in ms between sends. */
+    min: number;
+    /** Maximum delay in ms between sends. */
+    max: number;
+}
+export interface RateLimitConfig {
+    /** Per-chat rate limit. Default: { max: 5, window: '10s' } */
+    perChat?: RateLimitBucketConfig;
+    /** Global rate limit across all chats. Default: { max: 50, window: '60s' } */
+    global?: RateLimitBucketConfig;
+    /** Human-like jitter between sends. Default: disabled. */
+    jitter?: RateLimitJitterConfig;
+    /** Set to false to disable rate limiting entirely. Default: true. */
+    enabled?: boolean;
+    /**
+     * Max time a send may wait in the queue before it is rejected with
+     * {@link RateLimiterTimeout}. Prevents a mis-configured limit from hanging a
+     * caller forever. Default: '30s'. Set to `0` to wait indefinitely.
+     */
+    maxWait?: string | number;
+    /**
+     * Max distinct per-chat buckets kept in memory. Idle (fully-refilled) buckets
+     * are evicted first, so eviction never lifts an active limit. Default: 5000.
+     */
+    maxChats?: number;
+}
+/**
+ * Thrown when a queued send waits longer than the configured `maxWait`.
+ *
+ * A {@link RateLimitedError} (so a {@link ProviderError}), as the IProvider send
+ * contract requires: callers can `catch (e instanceof RateLimitedError)` the same
+ * way for this local limiter and for a server-side 429. `retryAfterMs` is the
+ * time until the blocking bucket refills one token.
+ */
+export declare class RateLimiterTimeout extends RateLimitedError {
+    readonly chatId: string;
+    readonly waitedMs: number;
+    constructor(chatId: string, waitedMs: number, retryAfterMs?: number);
+}
+export declare class RateLimiter {
+    private perChatBuckets;
+    private globalBucket;
+    private queue;
+    private processing;
+    private lastSendAt;
+    /** Bumped by reset() so an in-flight drain from a previous cycle bails out. */
+    private generation;
+    private readonly perChatMax;
+    private readonly perChatWindowMs;
+    private readonly maxChats;
+    private readonly maxWaitMs;
+    private readonly jitterMin;
+    private readonly jitterMax;
+    private readonly enabled;
+    constructor(config?: RateLimitConfig);
+    /**
+     * Acquire permission to send a message to `chatId`. Resolves when the send is
+     * allowed (may wait if rate-limited). Rejects with {@link RateLimiterTimeout}
+     * if it waits past `maxWait`, or a `ProviderError('RateLimiter reset')` if the
+     * limiter is reset (e.g. the provider stops) while the send is queued.
+     */
+    acquire(chatId: string): Promise<void>;
+    /** Number of messages currently waiting in the queue. */
+    get pending(): number;
+    /** Number of per-chat buckets currently tracked (bounded by `maxChats`). */
+    get trackedChats(): number;
+    private processQueue;
+    private drain;
+    private tryConsume;
+    private refillBucket;
+    /** Time (ms) until both buckets gating `chatId` hold a token again (>= 1). */
+    private retryAfterFor;
+    /** Time (ms) until the soonest queued send could proceed — used instead of busy-polling. */
+    private nextRefillDelay;
+    /** Evict idle (fully-refilled) buckets when over `maxChats`; never drops an active limit. */
+    private pruneBuckets;
+    private computeJitter;
+    private sleep;
+    /** Clear all buckets and the queue (e.g. on bot stop). */
+    reset(): void;
+}

package/lib/RateLimiter.js

@@ -0,0 +1,286 @@
+/**
+ * RateLimiter — Token bucket rate limiter for outbound messages.
+ *
+ * WhatsApp bans accounts that send too many messages in a short period. This
+ * rate limiter sits in the `before('send')` hook pipeline and enforces:
+ *   - Per-chat limits (e.g. max 5 messages per 10 seconds to the same chat)
+ *   - Global limits (e.g. max 50 messages per 60 seconds across all chats)
+ *   - Optional human-like jitter between sends
+ *
+ * When a limit is exceeded, the send is queued (not dropped) and released
+ * once the bucket refills. A blocked chat never stalls other chats: the queue
+ * is scanned for the first send whose buckets currently allow it. Sends that
+ * wait longer than `maxWait` are rejected so a caller can never hang forever.
+ *
+ * @example
+ * ```ts
+ * const bot = new Bot({
+ *   session: 'my-bot',
+ *   rateLimit: {
+ *     perChat: { max: 5, window: '10s' },
+ *     global: { max: 50, window: '60s' },
+ *     jitter: { min: 500, max: 1500 },
+ *   },
+ * })
+ * ```
+ */
+import { parseDuration, ProviderError, RateLimitedError } from '@bot-wa/core';
+const DEFAULT_PER_CHAT = { max: 5, window: '10s' };
+const DEFAULT_GLOBAL = { max: 50, window: '60s' };
+const DEFAULT_MAX_WAIT = '30s';
+const DEFAULT_MAX_CHATS = 5000;
+/** Retry hint used when the caller builds a timeout without a bucket to measure. */
+const DEFAULT_RETRY_AFTER_MS = 1000;
+/**
+ * Thrown when a queued send waits longer than the configured `maxWait`.
+ *
+ * A {@link RateLimitedError} (so a {@link ProviderError}), as the IProvider send
+ * contract requires: callers can `catch (e instanceof RateLimitedError)` the same
+ * way for this local limiter and for a server-side 429. `retryAfterMs` is the
+ * time until the blocking bucket refills one token.
+ */
+export class RateLimiterTimeout extends RateLimitedError {
+    chatId;
+    waitedMs;
+    constructor(chatId, waitedMs, retryAfterMs = DEFAULT_RETRY_AFTER_MS) {
+        super(retryAfterMs, `RateLimiter: send to ${chatId} exceeded maxWait after ${waitedMs}ms`);
+        this.chatId = chatId;
+        this.waitedMs = waitedMs;
+        this.name = 'RateLimiterTimeout';
+    }
+}
+export class RateLimiter {
+    perChatBuckets = new Map();
+    globalBucket;
+    queue = [];
+    processing = false;
+    lastSendAt = 0;
+    /** Bumped by reset() so an in-flight drain from a previous cycle bails out. */
+    generation = 0;
+    perChatMax;
+    perChatWindowMs;
+    maxChats;
+    maxWaitMs;
+    jitterMin;
+    jitterMax;
+    enabled;
+    constructor(config = {}) {
+        this.enabled = config.enabled !== false;
+        const perChat = config.perChat ?? DEFAULT_PER_CHAT;
+        assertPositive('perChat.max', perChat.max);
+        this.perChatMax = perChat.max;
+        this.perChatWindowMs = parseDuration(perChat.window);
+        assertPositive('perChat.window', this.perChatWindowMs);
+        const global = config.global ?? DEFAULT_GLOBAL;
+        assertPositive('global.max', global.max);
+        const globalWindowMs = parseDuration(global.window);
+        assertPositive('global.window', globalWindowMs);
+        this.globalBucket = {
+            tokens: global.max,
+            lastRefill: Date.now(),
+            max: global.max,
+            windowMs: globalWindowMs,
+        };
+        this.jitterMin = config.jitter?.min ?? 0;
+        this.jitterMax = config.jitter?.max ?? 0;
+        this.maxWaitMs = config.maxWait !== undefined ? parseDuration(config.maxWait) : parseDuration(DEFAULT_MAX_WAIT);
+        this.maxChats = config.maxChats ?? DEFAULT_MAX_CHATS;
+        assertNonNegative('jitter.min', this.jitterMin);
+        assertNonNegative('jitter.max', this.jitterMax);
+        if (this.jitterMax < this.jitterMin) {
+            throw new RangeError('RateLimiter jitter.max must be greater than or equal to jitter.min');
+        }
+        assertNonNegative('maxWait', this.maxWaitMs);
+        assertPositiveInteger('maxChats', this.maxChats);
+    }
+    /**
+     * Acquire permission to send a message to `chatId`. Resolves when the send is
+     * allowed (may wait if rate-limited). Rejects with {@link RateLimiterTimeout}
+     * if it waits past `maxWait`, or a `ProviderError('RateLimiter reset')` if the
+     * limiter is reset (e.g. the provider stops) while the send is queued.
+     */
+    async acquire(chatId) {
+        if (!this.enabled)
+            return;
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject, chatId, enqueuedAt: Date.now() });
+            this.processQueue();
+        });
+    }
+    /** Number of messages currently waiting in the queue. */
+    get pending() {
+        return this.queue.length;
+    }
+    /** Number of per-chat buckets currently tracked (bounded by `maxChats`). */
+    get trackedChats() {
+        return this.perChatBuckets.size;
+    }
+    processQueue() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        const gen = this.generation;
+        void this.drain(gen);
+    }
+    async drain(gen) {
+        while (this.queue.length > 0) {
+            if (this.generation !== gen)
+                return; // reset() happened — abandon this drain
+            const now = Date.now();
+            // Reject sends that have waited too long (walk backwards: splicing is safe).
+            if (this.maxWaitMs > 0) {
+                for (let i = this.queue.length - 1; i >= 0; i--) {
+                    const it = this.queue[i];
+                    const waited = now - it.enqueuedAt;
+                    if (waited >= this.maxWaitMs) {
+                        this.queue.splice(i, 1);
+                        it.reject(new RateLimiterTimeout(it.chatId, waited, this.retryAfterFor(it.chatId, now)));
+                    }
+                }
+                if (this.queue.length === 0)
+                    break;
+            }
+            // Send the FIRST queued item whose buckets allow it now — scanning past a
+            // blocked head keeps one rate-limited chat from stalling every other chat.
+            // FIFO within a chat is preserved: an older blocked item shares its bucket
+            // with newer items of the same chat, so they stay blocked together.
+            let sent = false;
+            for (let i = 0; i < this.queue.length; i++) {
+                if (this.tryConsume(this.queue[i].chatId, now)) {
+                    const item = this.queue.splice(i, 1)[0];
+                    const jitter = this.computeJitter();
+                    if (jitter > 0)
+                        await this.sleep(jitter);
+                    this.lastSendAt = Date.now();
+                    item.resolve();
+                    sent = true;
+                    break;
+                }
+            }
+            if (!sent)
+                await this.sleep(this.nextRefillDelay(now));
+        }
+        if (this.generation === gen)
+            this.processing = false;
+    }
+    tryConsume(chatId, now = Date.now()) {
+        // Refill global bucket
+        this.refillBucket(this.globalBucket, now);
+        if (this.globalBucket.tokens < 1)
+            return false;
+        // Refill (creating if needed) per-chat bucket
+        let chatBucket = this.perChatBuckets.get(chatId);
+        if (!chatBucket) {
+            chatBucket = {
+                tokens: this.perChatMax,
+                lastRefill: now,
+                max: this.perChatMax,
+                windowMs: this.perChatWindowMs,
+            };
+            this.perChatBuckets.set(chatId, chatBucket);
+            this.pruneBuckets(now);
+        }
+        this.refillBucket(chatBucket, now);
+        if (chatBucket.tokens < 1)
+            return false;
+        // Consume from both
+        this.globalBucket.tokens -= 1;
+        chatBucket.tokens -= 1;
+        return true;
+    }
+    refillBucket(bucket, now) {
+        const elapsed = now - bucket.lastRefill;
+        if (elapsed <= 0)
+            return;
+        const refillRate = bucket.max / bucket.windowMs;
+        const tokensToAdd = elapsed * refillRate;
+        bucket.tokens = Math.min(bucket.max, bucket.tokens + tokensToAdd);
+        bucket.lastRefill = now;
+    }
+    /** Time (ms) until both buckets gating `chatId` hold a token again (>= 1). */
+    retryAfterFor(chatId, now) {
+        this.refillBucket(this.globalBucket, now);
+        const chatBucket = this.perChatBuckets.get(chatId);
+        if (chatBucket)
+            this.refillBucket(chatBucket, now);
+        const wait = Math.max(timeToOneToken(this.globalBucket), chatBucket ? timeToOneToken(chatBucket) : 0);
+        return Math.max(1, Math.ceil(wait));
+    }
+    /** Time (ms) until the soonest queued send could proceed — used instead of busy-polling. */
+    nextRefillDelay(now) {
+        let wait = Infinity;
+        // If the global bucket is the blocker, that gates everything.
+        wait = Math.min(wait, timeToOneToken(this.globalBucket));
+        for (const it of this.queue) {
+            const b = this.perChatBuckets.get(it.chatId);
+            // No bucket yet ⇒ a fresh full bucket ⇒ sendable immediately.
+            wait = b ? Math.min(wait, timeToOneToken(b)) : 0;
+            if (wait === 0)
+                break;
+        }
+        if (!Number.isFinite(wait))
+            wait = 100;
+        // Clamp: never spin faster than 10ms, never sleep past 1s (re-checks bound staleness).
+        return Math.max(10, Math.min(Math.ceil(wait), 1000));
+    }
+    /** Evict idle (fully-refilled) buckets when over `maxChats`; never drops an active limit. */
+    pruneBuckets(now) {
+        if (this.perChatBuckets.size <= this.maxChats)
+            return;
+        for (const [id, b] of this.perChatBuckets) {
+            if (this.perChatBuckets.size <= this.maxChats)
+                break;
+            this.refillBucket(b, now);
+            if (b.tokens >= b.max)
+                this.perChatBuckets.delete(id); // idle → recreating it is a no-op
+        }
+        // All remaining are active; fall back to oldest-first (global bucket still caps totals).
+        while (this.perChatBuckets.size > this.maxChats) {
+            const oldest = this.perChatBuckets.keys().next();
+            if (oldest.done)
+                break;
+            this.perChatBuckets.delete(oldest.value);
+        }
+    }
+    computeJitter() {
+        if (this.jitterMin <= 0 && this.jitterMax <= 0)
+            return 0;
+        const min = Math.max(this.jitterMin, 0);
+        const max = Math.max(this.jitterMax, min);
+        return min + Math.random() * (max - min);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /** Clear all buckets and the queue (e.g. on bot stop). */
+    reset() {
+        this.generation++;
+        this.perChatBuckets.clear();
+        this.globalBucket.tokens = this.globalBucket.max;
+        this.globalBucket.lastRefill = Date.now();
+        // Reject all queued sends (typed: send() must only reject with ProviderError).
+        for (const item of this.queue) {
+            item.reject(new ProviderError('RateLimiter reset'));
+        }
+        this.queue = [];
+        this.processing = false;
+    }
+}
+function timeToOneToken(b) {
+    return b.tokens >= 1 ? 0 : (1 - b.tokens) * (b.windowMs / b.max);
+}
+function assertPositive(field, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`RateLimiter ${field} must be a finite number greater than 0`);
+    }
+}
+function assertNonNegative(field, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`RateLimiter ${field} must be a finite number greater than or equal to 0`);
+    }
+}
+function assertPositiveInteger(field, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new RangeError(`RateLimiter ${field} must be a positive integer`);
+    }
+}

package/lib/boundedMap.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bounded-size `Map` helpers.
+ *
+ * Some caches (e.g. BaileysProvider's LID<->PN identity cache) grow by one pair per resolved
+ * identity, forever, with no natural eviction point. `putBounded` caps that growth with a
+ * simple insertion-order eviction: `Map` preserves insertion order, so once the map exceeds
+ * `max` entries we just drop the oldest ones — no timestamps or access-tracking required.
+ */
+/**
+ * Sets `a -> b` and `b -> a` on `map`, then evicts the oldest entries (in insertion order)
+ * until `map.size <= max`. A no-op eviction pass when the map is already within `max`.
+ */
+export declare function putBounded(map: Map<string, string>, a: string, b: string, max: number): void;

package/lib/boundedMap.js

@@ -0,0 +1,22 @@
+/**
+ * Bounded-size `Map` helpers.
+ *
+ * Some caches (e.g. BaileysProvider's LID<->PN identity cache) grow by one pair per resolved
+ * identity, forever, with no natural eviction point. `putBounded` caps that growth with a
+ * simple insertion-order eviction: `Map` preserves insertion order, so once the map exceeds
+ * `max` entries we just drop the oldest ones — no timestamps or access-tracking required.
+ */
+/**
+ * Sets `a -> b` and `b -> a` on `map`, then evicts the oldest entries (in insertion order)
+ * until `map.size <= max`. A no-op eviction pass when the map is already within `max`.
+ */
+export function putBounded(map, a, b, max) {
+    map.set(a, b);
+    map.set(b, a);
+    while (map.size > max) {
+        const oldest = map.keys().next();
+        if (oldest.done)
+            break;
+        map.delete(oldest.value);
+    }
+}

package/lib/browser.d.ts

@@ -0,0 +1,15 @@
+/** OS presets; each one advertises Chrome on that OS. */
+export type BrowserPreset = 'macOS' | 'ubuntu' | 'windows' | 'appropriate';
+/** A preset, or an explicit `[os, browserName, osVersion]` tuple (caller-owned risk). */
+export type BrowserConfig = BrowserPreset | [string, string, string];
+/**
+ * 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 declare function resolveBrowser(browser?: BrowserConfig): [string, string, string] | undefined;