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

package/lib/mediaRef.js

@@ -0,0 +1,136 @@
+/**
+ * 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 { normalizeMessageContent, proto, toNumber } from '@whiskeysockets/baileys';
+import { ProviderError } from '@bot-wa/core';
+/** Format version written by {@link serializeBaileysMediaRef}. */
+export const BAILEYS_MEDIA_REF_VERSION = 1;
+/** Upper bound of the base64 protobuf content (a media content without thumbnails is ~300 bytes). */
+const MAX_CONTENT_B64 = 16 * 1024;
+const MEDIA_FIELDS = ['imageMessage', 'videoMessage', 'audioMessage', 'documentMessage', 'stickerMessage'];
+const FIELD_OF = {
+    image: 'imageMessage',
+    video: 'videoMessage',
+    audio: 'audioMessage',
+    voice: 'audioMessage',
+    document: 'documentMessage',
+    sticker: 'stickerMessage',
+};
+/** What a download (and a re-upload) needs from one media content; nothing else is journaled. */
+const KEPT = [
+    'url', 'directPath', 'mediaKey', 'mediaKeyTimestamp', 'fileEncSha256', 'fileSha256', 'fileLength',
+    'mimetype', 'fileName', 'seconds', 'ptt', 'width', 'height', 'isAnimated',
+];
+function isViewOnce(message, content) {
+    if (content?.viewOnce)
+        return true;
+    const m = message ?? {};
+    return Boolean(m.viewOnceMessage || m.viewOnceMessageV2 || m.viewOnceMessageV2Extension
+        || m.ephemeralMessage?.message?.viewOnceMessage || m.ephemeralMessage?.message?.viewOnceMessageV2);
+}
+/**
+ * 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 function serializeBaileysMediaRef(ref, options = {}) {
+    try {
+        const message = ref.token;
+        const field = FIELD_OF[ref.kind];
+        if (!field || !message || typeof message !== 'object' || !message.key?.id || !message.key.remoteJid)
+            return undefined;
+        const inner = normalizeMessageContent(message.message);
+        const content = inner?.[field];
+        if (!content || !content.mediaKey || !(content.directPath || content.url))
+            return undefined;
+        if (isViewOnce(message.message, content) && options.viewOnce !== true)
+            return undefined;
+        const kept = {};
+        for (const name of KEPT)
+            if (content[name] !== undefined && content[name] !== null)
+                kept[name] = content[name];
+        const bytes = proto.Message.encode(proto.Message.fromObject({ [field]: kept })).finish();
+        const m = Buffer.from(bytes).toString('base64');
+        if (m.length > MAX_CONTENT_B64)
+            return undefined;
+        const k = message.key;
+        const key = {
+            remoteJid: k.remoteJid,
+            id: k.id,
+            ...(typeof k.fromMe === 'boolean' ? { fromMe: k.fromMe } : {}),
+            ...(k.participant ? { participant: k.participant } : {}),
+        };
+        const t = message.messageTimestamp === undefined || message.messageTimestamp === null ? undefined : toNumber(message.messageTimestamp);
+        const data = { key, m, ...(typeof t === 'number' && Number.isFinite(t) ? { t } : {}) };
+        return { v: BAILEYS_MEDIA_REF_VERSION, data: data };
+    }
+    catch {
+        return undefined;
+    }
+}
+const JID = /^[\w.:+-]{1,128}@[\w.-]{1,64}$/;
+const MESSAGE_ID = /^[\w.:-]{1,128}$/;
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+function invalid(why) {
+    return new ProviderError(`Invalid Baileys media reference: ${why}`);
+}
+/**
+ * Decode and validate a journaled reference into the message key and a `WAMessage` holding
+ * only the media content. @throws {ProviderError} on anything unexpected.
+ */
+export function parseBaileysMediaRef(stored, kind) {
+    if (!stored || typeof stored !== 'object')
+        throw invalid('not an object');
+    if (stored.v !== BAILEYS_MEDIA_REF_VERSION)
+        throw invalid(`unknown version ${String(stored.v)}`);
+    const data = stored.data;
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        throw invalid('no data');
+    const key = data.key;
+    if (!key || typeof key !== 'object')
+        throw invalid('no key');
+    if (typeof key.remoteJid !== 'string' || !JID.test(key.remoteJid))
+        throw invalid('bad remoteJid');
+    if (typeof key.id !== 'string' || !MESSAGE_ID.test(key.id))
+        throw invalid('bad id');
+    if (key.fromMe !== undefined && typeof key.fromMe !== 'boolean')
+        throw invalid('bad fromMe');
+    if (key.participant !== undefined && (typeof key.participant !== 'string' || !JID.test(key.participant)))
+        throw invalid('bad participant');
+    if (data.t !== undefined && (typeof data.t !== 'number' || !Number.isFinite(data.t) || data.t < 0))
+        throw invalid('bad timestamp');
+    if (typeof data.m !== 'string' || data.m.length === 0 || data.m.length > MAX_CONTENT_B64 || !BASE64.test(data.m))
+        throw invalid('bad content');
+    let decoded;
+    try {
+        decoded = proto.Message.decode(Buffer.from(data.m, 'base64'));
+    }
+    catch {
+        throw invalid('undecodable content');
+    }
+    const present = MEDIA_FIELDS.filter((f) => decoded[f] !== undefined && decoded[f] !== null);
+    const field = FIELD_OF[kind];
+    if (present.length !== 1 || present[0] !== field)
+        throw invalid('media content does not match the message kind');
+    const content = decoded[field];
+    if (!content?.mediaKey?.length)
+        throw invalid('no media key');
+    const waKey = {
+        remoteJid: key.remoteJid,
+        id: key.id,
+        ...(key.fromMe !== undefined ? { fromMe: key.fromMe } : {}),
+        ...(key.participant !== undefined ? { participant: key.participant } : {}),
+    };
+    const message = { key: waKey, message: decoded, ...(data.t !== undefined ? { messageTimestamp: data.t } : {}) };
+    return { key: waKey, message };
+}

package/lib/polls.d.ts

@@ -0,0 +1,147 @@
+import { type proto, type WAMessage } from '@whiskeysockets/baileys';
+/** Default number of polls remembered; the oldest idle poll is evicted first. */
+export declare const POLL_CACHE_MAX = 500;
+/** Default number of counted vote message ids remembered to drop redeliveries. */
+export declare const VOTE_IDS_MAX = 5000;
+export interface PollOption {
+    name: string;
+    /** Hex SHA-256 of the option name: what a decrypted vote selects. */
+    hash: string;
+}
+/**
+ * The JSON-safe record a {@link PollStore} keeps for one poll: what a later
+ * process needs to decrypt, bind and tally its votes. No message bodies beyond
+ * the poll question and option names.
+ */
+export interface StoredPoll {
+    /** The poll message id (the store key). */
+    id: string;
+    /** The poll message key: its chat and creator, as Baileys delivered it. */
+    key: {
+        remoteJid: string;
+        remoteJidAlt?: string;
+        participant?: string;
+        participantAlt?: string;
+        fromMe: boolean;
+    };
+    /** The poll question. */
+    name: string;
+    /** Base64 of the poll's 32-byte messageSecret (the vote decryption key material). */
+    secret: string;
+    /** Option names with their hex SHA-256, in the poll's order. */
+    options: PollOption[];
+    /** Latest selection per canonical voter id (empty `hashes` = retracted). */
+    votes: Array<{
+        voter: string;
+        hashes: string[];
+        at: number;
+    }>;
+    /** Poll creation time, unix seconds, when known. */
+    timestamp?: number;
+}
+/**
+ * Pluggable persistence for polls, so votes cast after a restart can still be
+ * decrypted and tallied. Keyed by poll message id. The provider calls `set`
+ * when it first sees a poll and after every counted vote, `get` when a vote
+ * names a poll missing from its in-memory cache (or a new poll reuses an id),
+ * and `delete` when a stored entry is malformed. Retention (TTL, cleanup) is up
+ * to the host. A rejecting call is logged and never breaks sends or ingress.
+ * The entry holds the poll's secret: keep the store as private as the session.
+ */
+export interface PollStore {
+    get(pollId: string): Promise<StoredPoll | null | undefined>;
+    set(pollId: string, poll: StoredPoll): Promise<void>;
+    delete(pollId: string): Promise<void>;
+}
+export interface TrackedPoll {
+    id: string;
+    /** The poll creation message (the `native` of a poll-vote `ref`). */
+    message: WAMessage;
+    secret: Uint8Array;
+    options: PollOption[];
+    /** Latest selection per canonical voter id. An empty list is a retracted vote. */
+    votes: Map<string, {
+        hashes: string[];
+        at: number;
+    }>;
+}
+/** The poll creation inside a message (any version, unwrapped), or `undefined`. */
+export declare function pollCreationOf(message: WAMessage): {
+    name: string;
+    options: string[];
+    secret?: Uint8Array;
+} | undefined;
+/** The encrypted vote inside a message (unwrapped), or `undefined`. */
+export declare function pollUpdateOf(message: WAMessage): proto.Message.IPollUpdateMessage | undefined;
+/** Bounded, insertion-ordered cache of the polls whose votes can be decrypted. */
+export declare class PollTracker {
+    private readonly max;
+    private readonly maxVoteIds;
+    private readonly polls;
+    /** `<pollId> <voteMessageId>` of the votes already counted, oldest first. */
+    private readonly votesSeen;
+    constructor(max?: number, maxVoteIds?: number);
+    get size(): number;
+    /**
+     * Remember `message` if it is a poll creation carrying its messageSecret.
+     * Returns whether it is tracked. Seeing the same poll again (the `send()`
+     * result, then Baileys' `append` echo) keeps the tallies collected so far. A
+     * different poll reusing a tracked id (ids are chosen by the sending client)
+     * never replaces it; its votes fail the caller's creator check.
+     */
+    remember(message: WAMessage): boolean;
+    /**
+     * Like {@link remember}, returning the tracked poll and whether this call
+     * added it (`isNew`), so a caller can persist new polls only.
+     */
+    track(message: WAMessage): {
+        poll: TrackedPoll;
+        isNew: boolean;
+    } | undefined;
+    /** Insert an already-built poll (e.g. loaded from a {@link PollStore}), evicting the oldest. */
+    adopt(poll: TrackedPoll): void;
+    get(id: string): TrackedPoll | undefined;
+    /** Mark a poll as recently used so active polls outlive idle ones. */
+    touch(poll: TrackedPoll): void;
+    /**
+     * Whether the vote message `voteId` was already counted for `poll`. Baileys
+     * re-emits offline deliveries as `append` upserts, so the same vote message
+     * can arrive twice.
+     */
+    hasVote(poll: TrackedPoll, voteId: string): boolean;
+    /** Record that `voteId` was counted for `poll`; the oldest ids are forgotten first. */
+    markVote(poll: TrackedPoll, voteId: string): void;
+}
+/**
+ * Decrypt an encrypted vote, trying every creator × voter JID candidate (both
+ * normalised, device-free). Returns the selected option hashes (hex), or
+ * `undefined` when no pair authenticates: wrong secret, or a JID form we do not
+ * know.
+ */
+export declare function decryptVote(vote: proto.Message.IPollEncValue | null | undefined, poll: TrackedPoll, creators: string[], voters: string[]): {
+    hashes: string[];
+} | undefined;
+/**
+ * Store `voterId`'s latest selection. Earlier entries whose voter has since been
+ * canonicalised to another id (a bare LID whose PN was learned) are merged first,
+ * so one person is counted once. Returns `false`, changing nothing, for a vote
+ * older than the one already stored. A vote with the same timestamp replaces it:
+ * it is another vote message sent in the same millisecond, because redeliveries
+ * of an already counted message are dropped earlier ({@link PollTracker.hasVote}).
+ */
+export declare function recordVote(poll: TrackedPoll, voterId: string, hashes: string[], at: number, canonical: (id: string) => string): boolean;
+/** Per-option tallies in the poll's option order, with canonical voter ids. */
+export declare function tally(poll: TrackedPoll): Array<{
+    name: string;
+    votes: number;
+    voters: string[];
+}>;
+/** The JSON-safe {@link StoredPoll} for a tracked poll. */
+export declare function toStoredPoll(poll: TrackedPoll): StoredPoll;
+/**
+ * Rebuild a tracked poll from a stored record, or `undefined` when the record
+ * is malformed (wrong id, missing chat, secret not 32 bytes, bad options or
+ * votes). `message` is a minimal poll creation message carrying the stored key,
+ * usable as the `native` of a poll-vote ref (e.g. to quote the poll).
+ */
+export declare function fromStoredPoll(id: string, stored: unknown): TrackedPoll | undefined;

package/lib/polls.js

@@ -0,0 +1,243 @@
+/**
+ * Poll tracking and vote decryption for Baileys 7.
+ *
+ * WhatsApp encrypts every poll vote end to end with a key derived from the
+ * poll's 32-byte `messageContextInfo.messageSecret`, the poll id, the poll
+ * creator's JID and the voter's JID. Baileys 7 ships its own decryption
+ * commented out (Utils/process-message.js), so `messages.update` never carries
+ * `pollUpdates`: a vote only arrives as an encrypted `pollUpdateMessage` upsert.
+ *
+ * {@link PollTracker} remembers the polls this process sees (with their secret
+ * and option hashes) and the vote messages already counted, {@link decryptVote}
+ * tries the creator/voter JID forms a client may have used (LID and PN differ
+ * per addressing mode; AES-GCM rejects a wrong pair, so trying them is safe), and
+ * {@link recordVote}/{@link tally} keep the latest selection per voter and
+ * aggregate it into per-option counts.
+ *
+ * The key derivation does not cover the chat, and every member of a chat knows
+ * its polls' ids and secrets, so a decryptable vote is not proof that it belongs
+ * to the poll it names: the caller must also bind the vote to the poll's chat and
+ * creator (see BaileysProvider.onPollVote).
+ */
+import { createHash } from 'node:crypto';
+import { decryptPollVote, normalizeMessageContent } from '@whiskeysockets/baileys';
+/** Default number of polls remembered; the oldest idle poll is evicted first. */
+export const POLL_CACHE_MAX = 500;
+/** Default number of counted vote message ids remembered to drop redeliveries. */
+export const VOTE_IDS_MAX = 5000;
+/** The poll creation inside a message (any version, unwrapped), or `undefined`. */
+export function pollCreationOf(message) {
+    const content = normalizeMessageContent(message.message);
+    const creation = content?.pollCreationMessage ?? content?.pollCreationMessageV2 ?? content?.pollCreationMessageV3;
+    if (!creation)
+        return undefined;
+    const secret = content?.messageContextInfo?.messageSecret ?? message.message?.messageContextInfo?.messageSecret;
+    return {
+        name: creation.name ?? '',
+        options: (creation.options ?? []).map((o) => o.optionName ?? ''),
+        secret: secret ?? undefined,
+    };
+}
+/** The encrypted vote inside a message (unwrapped), or `undefined`. */
+export function pollUpdateOf(message) {
+    return normalizeMessageContent(message.message)?.pollUpdateMessage ?? undefined;
+}
+const optionHash = (name) => createHash('sha256').update(Buffer.from(name)).digest('hex');
+/** Bounded, insertion-ordered cache of the polls whose votes can be decrypted. */
+export class PollTracker {
+    max;
+    maxVoteIds;
+    polls = new Map();
+    /** `<pollId> <voteMessageId>` of the votes already counted, oldest first. */
+    votesSeen = new Set();
+    constructor(max = POLL_CACHE_MAX, maxVoteIds = VOTE_IDS_MAX) {
+        this.max = max;
+        this.maxVoteIds = maxVoteIds;
+    }
+    get size() { return this.polls.size; }
+    /**
+     * Remember `message` if it is a poll creation carrying its messageSecret.
+     * Returns whether it is tracked. Seeing the same poll again (the `send()`
+     * result, then Baileys' `append` echo) keeps the tallies collected so far. A
+     * different poll reusing a tracked id (ids are chosen by the sending client)
+     * never replaces it; its votes fail the caller's creator check.
+     */
+    remember(message) {
+        return !!this.track(message);
+    }
+    /**
+     * Like {@link remember}, returning the tracked poll and whether this call
+     * added it (`isNew`), so a caller can persist new polls only.
+     */
+    track(message) {
+        const id = message.key?.id;
+        if (!id)
+            return undefined;
+        const existing = this.polls.get(id);
+        if (existing)
+            return { poll: existing, isNew: false };
+        const creation = pollCreationOf(message);
+        if (!creation?.secret?.length)
+            return undefined;
+        const poll = {
+            id,
+            message,
+            secret: creation.secret,
+            options: creation.options.map((name) => ({ name, hash: optionHash(name) })),
+            votes: new Map(),
+        };
+        this.adopt(poll);
+        return { poll, isNew: true };
+    }
+    /** Insert an already-built poll (e.g. loaded from a {@link PollStore}), evicting the oldest. */
+    adopt(poll) {
+        this.polls.delete(poll.id);
+        this.polls.set(poll.id, poll);
+        while (this.polls.size > this.max) {
+            const oldest = this.polls.keys().next();
+            if (oldest.done)
+                break;
+            this.polls.delete(oldest.value);
+        }
+    }
+    get(id) { return this.polls.get(id); }
+    /** Mark a poll as recently used so active polls outlive idle ones. */
+    touch(poll) {
+        if (this.polls.delete(poll.id))
+            this.polls.set(poll.id, poll);
+    }
+    /**
+     * Whether the vote message `voteId` was already counted for `poll`. Baileys
+     * re-emits offline deliveries as `append` upserts, so the same vote message
+     * can arrive twice.
+     */
+    hasVote(poll, voteId) {
+        return this.votesSeen.has(`${poll.id} ${voteId}`);
+    }
+    /** Record that `voteId` was counted for `poll`; the oldest ids are forgotten first. */
+    markVote(poll, voteId) {
+        this.votesSeen.add(`${poll.id} ${voteId}`);
+        while (this.votesSeen.size > this.maxVoteIds) {
+            const oldest = this.votesSeen.values().next();
+            if (oldest.done)
+                break;
+            this.votesSeen.delete(oldest.value);
+        }
+    }
+}
+/**
+ * Decrypt an encrypted vote, trying every creator × voter JID candidate (both
+ * normalised, device-free). Returns the selected option hashes (hex), or
+ * `undefined` when no pair authenticates: wrong secret, or a JID form we do not
+ * know.
+ */
+export function decryptVote(vote, poll, creators, voters) {
+    if (!vote?.encPayload?.length || !vote.encIv?.length)
+        return undefined;
+    for (const pollCreatorJid of creators) {
+        for (const voterJid of voters) {
+            try {
+                const decoded = decryptPollVote(vote, { pollCreatorJid, pollMsgId: poll.id, pollEncKey: poll.secret, voterJid });
+                return { hashes: (decoded.selectedOptions ?? []).map((h) => Buffer.from(h).toString('hex')) };
+            }
+            catch {
+                // Wrong JID pair: GCM authentication fails. Try the next candidate.
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Store `voterId`'s latest selection. Earlier entries whose voter has since been
+ * canonicalised to another id (a bare LID whose PN was learned) are merged first,
+ * so one person is counted once. Returns `false`, changing nothing, for a vote
+ * older than the one already stored. A vote with the same timestamp replaces it:
+ * it is another vote message sent in the same millisecond, because redeliveries
+ * of an already counted message are dropped earlier ({@link PollTracker.hasVote}).
+ */
+export function recordVote(poll, voterId, hashes, at, canonical) {
+    for (const [id, entry] of [...poll.votes]) {
+        const target = canonical(id);
+        if (!target || target === id)
+            continue;
+        poll.votes.delete(id);
+        const existing = poll.votes.get(target);
+        if (!existing || existing.at <= entry.at)
+            poll.votes.set(target, entry);
+    }
+    const previous = poll.votes.get(voterId);
+    if (previous && at < previous.at)
+        return false;
+    poll.votes.set(voterId, { hashes, at });
+    return true;
+}
+/** Per-option tallies in the poll's option order, with canonical voter ids. */
+export function tally(poll) {
+    return poll.options.map((option) => {
+        const voters = [...poll.votes].filter(([, v]) => v.hashes.includes(option.hash)).map(([id]) => id);
+        return { name: option.name, votes: voters.length, voters };
+    });
+}
+/** Optional key fields kept beside `remoteJid`/`fromMe`: the twins and the group creator. */
+const KEY_FIELDS = ['remoteJidAlt', 'participant', 'participantAlt'];
+/** The JSON-safe {@link StoredPoll} for a tracked poll. */
+export function toStoredPoll(poll) {
+    const raw = poll.message.key ?? {};
+    const key = { remoteJid: raw.remoteJid ?? '', fromMe: !!raw.fromMe };
+    for (const field of KEY_FIELDS) {
+        const value = raw[field];
+        if (typeof value === 'string' && value)
+            key[field] = value;
+    }
+    const timestamp = Number(poll.message.messageTimestamp ?? 0);
+    return {
+        id: poll.id,
+        key,
+        name: pollCreationOf(poll.message)?.name ?? '',
+        secret: Buffer.from(poll.secret).toString('base64'),
+        options: poll.options.map((o) => ({ name: o.name, hash: o.hash })),
+        votes: [...poll.votes].map(([voter, v]) => ({ voter, hashes: [...v.hashes], at: v.at })),
+        ...(Number.isFinite(timestamp) && timestamp > 0 ? { timestamp } : {}),
+    };
+}
+const isString = (v) => typeof v === 'string';
+const HEX_HASH = /^[0-9a-f]{64}$/;
+/**
+ * Rebuild a tracked poll from a stored record, or `undefined` when the record
+ * is malformed (wrong id, missing chat, secret not 32 bytes, bad options or
+ * votes). `message` is a minimal poll creation message carrying the stored key,
+ * usable as the `native` of a poll-vote ref (e.g. to quote the poll).
+ */
+export function fromStoredPoll(id, stored) {
+    if (!stored || typeof stored !== 'object')
+        return undefined;
+    const s = stored;
+    if (s.id !== id || !s.key || typeof s.key !== 'object' || !isString(s.key.remoteJid) || !s.key.remoteJid)
+        return undefined;
+    if (!isString(s.secret))
+        return undefined;
+    const secret = new Uint8Array(Buffer.from(s.secret, 'base64'));
+    if (secret.length !== 32)
+        return undefined;
+    if (!Array.isArray(s.options) || !s.options.every((o) => o && isString(o.name) && isString(o.hash) && HEX_HASH.test(o.hash)))
+        return undefined;
+    const votes = new Map();
+    for (const v of Array.isArray(s.votes) ? s.votes : []) {
+        if (!v || !isString(v.voter) || !Array.isArray(v.hashes) || !v.hashes.every(isString) || typeof v.at !== 'number')
+            return undefined;
+        votes.set(v.voter, { hashes: [...v.hashes], at: v.at });
+    }
+    const key = { remoteJid: s.key.remoteJid, fromMe: !!s.key.fromMe, id };
+    for (const field of KEY_FIELDS)
+        if (isString(s.key[field]) && s.key[field])
+            key[field] = s.key[field];
+    const message = {
+        key,
+        message: {
+            pollCreationMessage: { name: isString(s.name) ? s.name : '', options: s.options.map((o) => ({ optionName: o.name })) },
+            messageContextInfo: { messageSecret: secret },
+        },
+        ...(typeof s.timestamp === 'number' ? { messageTimestamp: s.timestamp } : {}),
+    };
+    return { id, message, secret, options: s.options.map((o) => ({ name: o.name, hash: o.hash })), votes };
+}

package/lib/reconnect.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reconnect policy — pure decision logic for connection-close handling.
+ *
+ * Extracted from BaileysProvider so it can be unit-tested without a socket.
+ * Maps a Baileys {@link DisconnectReason} status code to the action the
+ * provider should take, and computes the backoff delay between attempts.
+ */
+export type DisconnectAction = 
+/** Session is invalid — wipe auth state and start fresh. */
+'wipe'
+/** Do NOT reconnect — another client owns the session, or we're forbidden. */
+ | 'stop'
+/** Reconnect immediately (normal post-pairing restart). */
+ | 'reconnect-now'
+/** Reconnect after an exponential backoff delay. */
+ | 'reconnect-backoff';
+/**
+ * Decide what to do when the socket closes, from the disconnect status code.
+ *
+ * - `loggedOut` / `badSession` / `multideviceMismatch` → `wipe`
+ * - `connectionReplaced` (440, "conflict": another device/instance took the
+ *   session) / `forbidden` (403) → `stop` — reconnecting just fights the other
+ *   client forever and risks a ban
+ * - `restartRequired` (515) → `reconnect-now` (expected during pairing)
+ * - everything else (timeouts, transient closes, service unavailable) →
+ *   `reconnect-backoff`
+ */
+export declare function classifyDisconnect(statusCode: number | undefined): DisconnectAction;
+/**
+ * Exponential backoff with a cap. `attempt` is 0-based (first retry = 0).
+ *
+ * @example
+ * ```ts
+ * backoffDelay(0) // 1000
+ * backoffDelay(1) // 2000
+ * backoffDelay(5) // 30000 (capped)
+ * ```
+ */
+export declare function backoffDelay(attempt: number, base?: number, cap?: number): number;
+/** Max consecutive backoff reconnect attempts before giving up. */
+export declare const MAX_RECONNECT_ATTEMPTS = 10;

package/lib/reconnect.js

@@ -0,0 +1,51 @@
+/**
+ * Reconnect policy — pure decision logic for connection-close handling.
+ *
+ * Extracted from BaileysProvider so it can be unit-tested without a socket.
+ * Maps a Baileys {@link DisconnectReason} status code to the action the
+ * provider should take, and computes the backoff delay between attempts.
+ */
+import { DisconnectReason } from '@whiskeysockets/baileys';
+/**
+ * Decide what to do when the socket closes, from the disconnect status code.
+ *
+ * - `loggedOut` / `badSession` / `multideviceMismatch` → `wipe`
+ * - `connectionReplaced` (440, "conflict": another device/instance took the
+ *   session) / `forbidden` (403) → `stop` — reconnecting just fights the other
+ *   client forever and risks a ban
+ * - `restartRequired` (515) → `reconnect-now` (expected during pairing)
+ * - everything else (timeouts, transient closes, service unavailable) →
+ *   `reconnect-backoff`
+ */
+export function classifyDisconnect(statusCode) {
+    switch (statusCode) {
+        case DisconnectReason.loggedOut:
+        case DisconnectReason.badSession:
+        case DisconnectReason.multideviceMismatch:
+            return 'wipe';
+        case DisconnectReason.connectionReplaced:
+        case DisconnectReason.forbidden:
+            return 'stop';
+        case DisconnectReason.restartRequired:
+            return 'reconnect-now';
+        default:
+            return 'reconnect-backoff';
+    }
+}
+/**
+ * Exponential backoff with a cap. `attempt` is 0-based (first retry = 0).
+ *
+ * @example
+ * ```ts
+ * backoffDelay(0) // 1000
+ * backoffDelay(1) // 2000
+ * backoffDelay(5) // 30000 (capped)
+ * ```
+ */
+export function backoffDelay(attempt, base = 1000, cap = 30_000) {
+    if (attempt < 0)
+        attempt = 0;
+    return Math.min(base * 2 ** attempt, cap);
+}
+/** Max consecutive backoff reconnect attempts before giving up. */
+export const MAX_RECONNECT_ATTEMPTS = 10;

package/lib/sessionPath.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve a session directory without allowing an identifier to escape its
+ * configured root. Session identifiers are deliberately opaque: callers that
+ * need hierarchy should configure a different `sessionsDir`, not put path
+ * separators in `session`.
+ */
+export declare function resolveSessionDirectory(sessionsDir?: string, session?: string): string;
+/**
+ * Reject an existing session symlink and verify real-path containment. This
+ * prevents auth reads/writes from being redirected outside `sessionsDir`.
+ */
+export declare function assertSessionDirectorySafe(sessionsDir?: string, session?: string): string;
+/** Remove exactly one validated session directory. */
+export declare function removeSessionDirectory(sessionsDir?: string, session?: string): void;