privage.js 0.21.0

package/dist/Client.js

@@ -0,0 +1,904 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+const events_1 = require("events");
+const crypto_1 = require("crypto");
+const phoenix_1 = require("phoenix");
+const ws_1 = __importDefault(require("ws"));
+const rest_1 = require("./rest");
+const Interaction_1 = require("./structures/Interaction");
+const commands_1 = require("./commands");
+const collectors_1 = require("./collectors");
+const Message_1 = require("./structures/Message");
+const Member_1 = require("./structures/Member");
+const Server_1 = require("./structures/Server");
+const Channel_1 = require("./structures/Channel");
+const Role_1 = require("./structures/Role");
+const intents_1 = require("./intents");
+const errors_1 = require("./errors");
+const RECONNECT_BASE_MS = 3000;
+const RECONNECT_MAX_MS = 60000;
+const DEDUPE_CACHE = 1000;
+const RPC_TIMEOUT_MS = 10000;
+const STREAM_SEQ_RE = /^\d+-\d+$/;
+// Bound the server/channel name caches so a bot in a huge number of servers
+// can't grow them without limit — oldest entries evict first (insertion order).
+const SERVER_CACHE_CAP = 10000;
+const CHANNEL_CACHE_CAP = 10000;
+// Channel-list hydration fans out one REST call per server; cap concurrency
+// so a bot in hundreds of servers doesn't burst the API on connect.
+const CHANNEL_HYDRATE_CONCURRENCY = 5;
+class Client extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        /** The bot's own identity, populated once connected. */
+        this.user = null;
+        /**
+         * Slash-command registry — `client.commands.set([...])` bulk-overwrites,
+         * `client.commands.fetch()` lists. Use after `login()`. Invocations arrive
+         * as `interaction` events with `kind: 'command'`.
+         */
+        this.commands = new commands_1.CommandsManager(this);
+        /**
+         * Server name cache — hydrated from `GET /servers` on connect, kept fresh
+         * by `server-meta-updated`/`server-deleted` (requires `Intents.Servers`).
+         * Capped at {@link SERVER_CACHE_CAP}, oldest entries evict first.
+         */
+        this.servers = new Map();
+        /**
+         * Channel name cache — hydrated per-server in the background after connect,
+         * kept fresh by `channel-created`/`channel-updated`/`channel-deleted`
+         * (requires `Intents.Servers`), and lazily filled on cache miss (see
+         * `ensureChannel`). Capped at {@link CHANNEL_CACHE_CAP}, oldest entries evict first.
+         */
+        this.channels = new Map();
+        this.pendingChannelFetches = new Set();
+        this.pendingServerFetches = new Set();
+        this.token = null;
+        this.socket = null;
+        this.reconnectAttempts = 0;
+        this.reconnectPending = false;
+        this.destroyed = false;
+        this.connectedOnce = false;
+        this.readyAtMs = null;
+        // Resume state (survives reconnects).
+        this.streamToken = null;
+        this.resumeCursor = 0; // highest `ss` seen on the current stream
+        this.topicCursors = new Map(); // topic -> last `s` (for REST catchup)
+        // Dedupe (at-least-once delivery + resume/catchup overlap).
+        this.seen = [];
+        this.seenSet = new Set();
+        // Message -> channel cache: reaction-update payloads omit the channel id
+        // (it only lives in the wire topic), so we resolve it from recently-seen
+        // messages. Cache miss (e.g. a reaction on a pre-connect message) -> null.
+        this.channelByMessage = new Map();
+        this.channelByMessageKeys = [];
+        // Defaults target production so a fresh install Just Works. A custom api
+        // (option or $PRIVAGE_API) keeps the derive-ws-from-api behavior for
+        // self-hosted/local setups; production's ws lives on its own host, so it
+        // can't be derived.
+        const customApi = options.api || process.env.PRIVAGE_API;
+        this.api = (customApi || 'https://api.privage.xyz').replace(/\/$/, '');
+        this.wsUrl =
+            options.ws ||
+                process.env.PRIVAGE_WS ||
+                (customApi
+                    ? this.api.replace(/^http/, 'ws').replace(/:\d+$/, ':4000') + '/socket'
+                    : 'wss://ws.privage.xyz/socket');
+        this.intents = (0, intents_1.resolveIntents)(options.intents || []);
+        this.debugMode = !!options.debug;
+        this.streamId = `privage-bot-${(0, crypto_1.randomUUID)()}`;
+    }
+    /** Authenticate and connect. Resolves once the session is open (`ready`); rejects on a fatal auth error. */
+    login(token) {
+        // Fail loud and local: without this guard a missing token ships
+        // `Authorization: Bot undefined` and surfaces as a cryptic 401 from the
+        // server. (Common trip: passing the token to the constructor,
+        // discord.js-style — the constructor takes options, login takes the token.)
+        if (typeof token !== 'string' || !token.trim()) {
+            return Promise.reject(new errors_1.PrivageAuthError('No token provided — pass your bot token to login(token).'));
+        }
+        this.token = token;
+        if (this.intents.length === 0) {
+            this.warn('No intents declared — the gateway will deliver ALL events. Declare intents to scope your bot.');
+        }
+        return new Promise((resolve, reject) => {
+            this.loginResolve = resolve;
+            this.loginReject = reject;
+            void this.connect();
+        });
+    }
+    /**
+     * True once `ready` has fired. Stays true across reconnects — it means
+     * "ready happened", not "currently connected" (discord.js semantics).
+     */
+    isReady() {
+        return this.connectedOnce;
+    }
+    /** When `ready` fired, or `null` before login completes. */
+    get readyAt() {
+        return this.readyAtMs !== null ? new Date(this.readyAtMs) : null;
+    }
+    /** Epoch-ms twin of {@link readyAt}. */
+    get readyTimestamp() {
+        return this.readyAtMs;
+    }
+    /** Milliseconds since `ready`, or `null` before login completes. */
+    get uptime() {
+        return this.readyAtMs !== null ? Date.now() - this.readyAtMs : null;
+    }
+    /** Disconnect and stop reconnecting. */
+    destroy() {
+        this.destroyed = true;
+        if (this.socket) {
+            try {
+                this.socket.disconnect();
+            }
+            catch { /* ignore */ }
+            this.socket = null;
+        }
+    }
+    /** Grant a role to a member. Requires the bot to have MANAGE_ROLES and the role to sit below the bot's highest. */
+    addRole(serverId, userId, roleId) {
+        return this.rest.addRole(serverId, userId, roleId);
+    }
+    /** Remove a role from a member. */
+    removeRole(serverId, userId, roleId) {
+        return this.rest.removeRole(serverId, userId, roleId);
+    }
+    /** Kick a member (needs KICK_MEMBERS). */
+    kick(serverId, userId, opts) {
+        return this.rest.kickMember(serverId, userId, opts);
+    }
+    /** Ban a member (needs BAN_MEMBERS). */
+    ban(serverId, userId, opts) {
+        return this.rest.banMember(serverId, userId, opts);
+    }
+    /** Lift a ban. */
+    unban(serverId, userId) {
+        return this.rest.unbanMember(serverId, userId);
+    }
+    /** Time out a member (needs TIMEOUT_MEMBERS). */
+    timeout(serverId, userId, opts) {
+        return this.rest.timeoutMember(serverId, userId, opts);
+    }
+    /** Remove a member's timeout. */
+    removeTimeout(serverId, userId) {
+        return this.rest.removeTimeout(serverId, userId);
+    }
+    /** Delete a message (needs MANAGE_MESSAGES, or the bot's own message). */
+    deleteMessage(messageId) {
+        return this.rest.deleteMessage(messageId);
+    }
+    /** Send a message to a channel by id — no server id needed. */
+    send(channelId, content) {
+        const data = typeof content === 'string' ? { content } : content;
+        return this.rest.sendMessage(channelId, data);
+    }
+    /** React to a message. */
+    react(messageId, emoji) {
+        return this.rest.react(messageId, emoji);
+    }
+    /** Remove the bot's own reaction from a message. */
+    removeReaction(messageId, emoji) {
+        return this.rest.removeReaction(messageId, emoji);
+    }
+    /** Create a poll in a channel (needs send permission there). Limits: question ≤500, 2–6 unique options ≤200, deadline ≤7 days. */
+    createPoll(channelId, opts) {
+        return this.rest.createPoll(channelId, opts);
+    }
+    /** Close a poll early (creator or MANAGE_MESSAGES). A `pollClose` event follows. */
+    closePoll(pollId) {
+        return this.rest.closePoll(pollId);
+    }
+    /** Create a webhook on a text/announcement channel (needs MANAGE_WEBHOOKS). Response carries the webhook token. */
+    createWebhook(channelId, opts) {
+        return this.rest.createWebhook(channelId, opts);
+    }
+    /** List a channel's webhooks. */
+    fetchChannelWebhooks(channelId) {
+        return this.rest.fetchChannelWebhooks(channelId);
+    }
+    /** List a server's webhooks. */
+    fetchServerWebhooks(serverId) {
+        return this.rest.fetchServerWebhooks(serverId);
+    }
+    /** Rename a webhook / change its avatar (`avatarUrl: null` clears). */
+    editWebhook(webhookId, opts) {
+        return this.rest.editWebhook(webhookId, opts);
+    }
+    /** Delete a webhook. */
+    deleteWebhook(webhookId) {
+        return this.rest.deleteWebhook(webhookId);
+    }
+    /** Rotate a webhook's token — the old one stops working immediately. */
+    rotateWebhookToken(webhookId) {
+        return this.rest.rotateWebhookToken(webhookId);
+    }
+    /** Collect messages matching a filter until a count/time limit — see MessageCollector. */
+    createMessageCollector(options) {
+        return new collectors_1.MessageCollector(this, options);
+    }
+    /** Promise form of a collector: resolves with collected messages (default max 1, 60s). */
+    awaitMessages(options) {
+        return (0, collectors_1.awaitMessages)(this, options);
+    }
+    /** Set the bot's presence status ('online' | 'idle' | 'dnd' | 'offline'). */
+    setStatus(status) {
+        return this.rest.setStatus(status);
+    }
+    /** Set the bot's rich-presence activity (shows on the profile/member list). */
+    setActivity(activity) {
+        return this.rest.setActivity(activity);
+    }
+    /** Clear the bot's rich-presence activity. */
+    clearActivity() {
+        return this.rest.clearActivity();
+    }
+    /** Edit a message's content. Own messages only (403 otherwise). */
+    editMessage(messageId, content) {
+        return this.rest.editMessage(messageId, content);
+    }
+    /** Pin a message. */
+    pinMessage(messageId) {
+        return this.rest.pinMessage(messageId);
+    }
+    /** Unpin a message. */
+    unpinMessage(messageId) {
+        return this.rest.unpinMessage(messageId);
+    }
+    /** Fetch a channel's message history. */
+    async fetchMessages(channelId, opts) {
+        const res = await this.rest.fetchMessages(channelId, opts);
+        return (res?.messages ?? []).map((m) => new Message_1.Message(this, m));
+    }
+    /** List a server's members. */
+    async fetchMembers(serverId, opts) {
+        const res = await this.rest.fetchMembers(serverId, opts);
+        return (res?.members ?? []).map((m) => new Member_1.Member(this, { ...m, server_id: serverId }));
+    }
+    /** List a server's roles. */
+    async fetchRoles(serverId) {
+        const res = await this.rest.fetchRoles(serverId);
+        return (res?.roles ?? []).map((r) => new Role_1.Role(r));
+    }
+    /** Set (or clear, with `null`) a member's nickname. Others need MANAGE_NICKNAMES. */
+    setNickname(serverId, userId, nickname) {
+        return this.rest.setNickname(serverId, userId, nickname);
+    }
+    // ── connection lifecycle ──────────────────────────────────────────────
+    debug(msg) {
+        if (this.debugMode)
+            this.emit('debug', msg);
+    }
+    warn(msg) {
+        this.emit('warn', msg);
+    }
+    isFatal(err) {
+        return err instanceof errors_1.PrivageAuthError || err instanceof errors_1.PrivagePermissionError;
+    }
+    scheduleReconnect(reason) {
+        if (this.destroyed || this.reconnectPending)
+            return;
+        this.reconnectPending = true;
+        const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempts, RECONNECT_MAX_MS);
+        this.reconnectAttempts += 1;
+        this.emit('connectionError', new errors_1.PrivageConnectionError(`${reason} — reconnecting in ${Math.round(delay / 1000)}s`));
+        setTimeout(() => {
+            this.reconnectPending = false;
+            void this.connect();
+        }, delay);
+    }
+    async connect() {
+        if (this.destroyed)
+            return;
+        const previous = this.socket;
+        this.socket = null;
+        if (previous) {
+            try {
+                previous.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            await this.handshake();
+            this.reconnectAttempts = 0;
+        }
+        catch (err) {
+            if (this.isFatal(err)) {
+                const fatal = new errors_1.PrivageAuthError(err.message || String(err));
+                if (this.loginReject) {
+                    this.loginReject(fatal);
+                    this.loginReject = undefined;
+                    this.loginResolve = undefined;
+                }
+                return;
+            }
+            this.scheduleReconnect(`Connect failed (${err?.message || err})`);
+        }
+    }
+    async handshake() {
+        this.rest = new rest_1.Rest({ api: this.api, token: this.token });
+        const me = await this.rest.get('/auth/me');
+        const botId = String(me.user?.id ?? me.user?._id ?? '');
+        this.user = { id: botId, username: me.user?.username ?? botId };
+        this.debug(`authenticated as ${this.user.username} (${botId})`);
+        const { token: ticket } = await this.rest.get('/gateway/ticket');
+        const socket = new phoenix_1.Socket(this.wsUrl, {
+            transport: ws_1.default,
+            params: { token: ticket, stream_id: this.streamId },
+            reconnectAfterMs: () => 3600000, // we own reconnection
+            heartbeatIntervalMs: 30000,
+        });
+        this.socket = socket;
+        socket.onClose(() => {
+            if (socket !== this.socket)
+                return;
+            this.scheduleReconnect('Socket closed');
+        });
+        await new Promise((resolve, reject) => {
+            socket.onOpen(resolve);
+            socket.onError((e) => reject(new errors_1.PrivageConnectionError(`socket error: ${e?.message || e}`)));
+            socket.connect();
+        });
+        this.debug('socket connected');
+        const personal = await this.join(socket, `user:${botId}`);
+        await this.join(socket, `bot:${botId}`, (envelope) => this.handleEvent(envelope));
+        if (this.streamToken) {
+            // Reconnect: try to resume the delivery stream; on any gap, fill via REST.
+            const resumed = await this.sessionResume(personal).catch(() => null);
+            if (resumed && resumed.resumed) {
+                if (resumed.catchupRequired)
+                    await this.restCatchup();
+                this.debug('session resumed');
+            }
+            else {
+                // Stream expired/rejected — fresh session, then backfill everything missed.
+                await this.sessionOpen(personal);
+                await this.restCatchup();
+                this.debug('session re-opened (resume unavailable)');
+            }
+        }
+        else {
+            await this.sessionOpen(personal);
+            this.debug(`session open (intents: ${this.intents.join(', ') || 'ALL'})`);
+        }
+        if (!this.connectedOnce) {
+            this.connectedOnce = true;
+            this.readyAtMs = Date.now();
+            // Servers first, blocking `ready` — cheap (one call) and most bots key
+            // off server identity immediately. Channels are hydrated in the
+            // background below: a bot in many servers shouldn't have a slow `ready`.
+            await this.hydrateServers();
+            if (this.loginResolve) {
+                this.loginResolve();
+                this.loginResolve = undefined;
+                this.loginReject = undefined;
+            }
+            this.emit('ready', { user: this.user });
+            void this.hydrateChannels();
+        }
+    }
+    // ── server/channel name cache ─────────────────────────────────────────
+    /** `GET /servers` → populate the server cache. Best-effort — never fatal. */
+    async hydrateServers() {
+        try {
+            const resp = await this.rest.get('/servers');
+            for (const row of resp?.servers ?? []) {
+                const server = new Server_1.Server(this, row);
+                if (server.id)
+                    this.cacheSet(this.servers, server.id, server, SERVER_CACHE_CAP);
+            }
+            this.debug(`hydrated ${this.servers.size} server(s)`);
+        }
+        catch (e) {
+            this.warn(`server hydration failed: ${e?.message || e}`);
+        }
+    }
+    /**
+     * Per-server channel list, concurrency-limited and run in the background
+     * (never awaited by `handshake`). Best-effort — a slow or failing server's
+     * channel list never breaks the connection or delays other servers.
+     */
+    async hydrateChannels() {
+        try {
+            const serverIds = Array.from(this.servers.keys());
+            let cursor = 0;
+            let count = 0;
+            const worker = async () => {
+                for (;;) {
+                    const i = cursor++;
+                    if (i >= serverIds.length)
+                        return;
+                    const serverId = serverIds[i];
+                    try {
+                        const resp = await this.rest.get(`/channels/server/${serverId}`);
+                        for (const row of resp?.channels ?? []) {
+                            const channel = new Channel_1.Channel(this, row);
+                            if (channel.id) {
+                                this.cacheSet(this.channels, channel.id, channel, CHANNEL_CACHE_CAP);
+                                count += 1;
+                            }
+                        }
+                    }
+                    catch (e) {
+                        this.warn(`channel hydration failed for server ${serverId}: ${e?.message || e}`);
+                    }
+                }
+            };
+            const workers = Array.from({ length: Math.min(CHANNEL_HYDRATE_CONCURRENCY, serverIds.length) }, () => worker());
+            await Promise.all(workers);
+            this.debug(`hydrated ${count} channel(s) across ${serverIds.length} server(s)`);
+        }
+        catch (e) {
+            this.warn(`channel hydration failed: ${e?.message || e}`);
+        }
+    }
+    /**
+     * Lazily resolve an uncached channel over REST (deduped per id, fire-and-forget).
+     * Called automatically on a cache-miss message so the *next* message in that
+     * channel resolves — useful for brand-new channels or bots that didn't
+     * declare `Intents.Servers`. Safe to call redundantly; a no-op if already
+     * cached or already in flight.
+     */
+    ensureChannel(channelId, serverId) {
+        if (!channelId || this.channels.has(channelId) || this.pendingChannelFetches.has(channelId))
+            return;
+        this.pendingChannelFetches.add(channelId);
+        this.rest
+            .get(`/channels/${channelId}`)
+            .then((resp) => {
+            const row = resp?.channel;
+            if (!row)
+                return;
+            const channel = new Channel_1.Channel(this, row);
+            if (!channel.id)
+                return;
+            this.cacheSet(this.channels, channel.id, channel, CHANNEL_CACHE_CAP);
+            const sid = channel.serverId || serverId || null;
+            if (sid)
+                this.ensureServer(sid);
+        })
+            .catch((e) => this.debug(`ensureChannel(${channelId}) failed: ${e?.message || e}`))
+            .finally(() => this.pendingChannelFetches.delete(channelId));
+    }
+    /** Best-effort fill for a server discovered via a lazily-resolved channel. */
+    ensureServer(serverId) {
+        if (!serverId || this.servers.has(serverId) || this.pendingServerFetches.has(serverId))
+            return;
+        this.pendingServerFetches.add(serverId);
+        this.rest
+            .get(`/servers/${serverId}`)
+            .then((resp) => {
+            const row = resp?.server;
+            if (!row)
+                return;
+            const server = new Server_1.Server(this, row);
+            if (server.id)
+                this.cacheSet(this.servers, server.id, server, SERVER_CACHE_CAP);
+        })
+            .catch((e) => this.debug(`ensureServer(${serverId}) failed: ${e?.message || e}`))
+            .finally(() => this.pendingServerFetches.delete(serverId));
+    }
+    /** Cache-maintenance for structure events. Cache-only — never emits new SDK events. */
+    updateCaches(type, d) {
+        switch (type) {
+            case 'channel-created':
+            case 'channel-updated': {
+                if (d?.channel) {
+                    const channel = new Channel_1.Channel(this, d.channel);
+                    if (channel.id)
+                        this.cacheSet(this.channels, channel.id, channel, CHANNEL_CACHE_CAP);
+                }
+                break;
+            }
+            case 'channel-deleted': {
+                const channelId = d?.channelId != null ? String(d.channelId) : d?.channel_id != null ? String(d.channel_id) : null;
+                if (channelId)
+                    this.channels.delete(channelId);
+                break;
+            }
+            case 'server-meta-updated': {
+                // Sparse patch — icon/banner-only updates omit `name` etc. Merge over
+                // the cached raw row so untouched fields survive.
+                const serverId = d?.serverId != null ? String(d.serverId) : d?.server_id != null ? String(d.server_id) : null;
+                if (serverId) {
+                    const existing = this.servers.get(serverId);
+                    const merged = { ...(existing?.raw ?? { id: serverId }), ...d };
+                    this.cacheSet(this.servers, serverId, new Server_1.Server(this, merged), SERVER_CACHE_CAP);
+                }
+                break;
+            }
+            case 'server-deleted': {
+                const serverId = d?.serverId != null ? String(d.serverId) : d?.server_id != null ? String(d.server_id) : null;
+                if (serverId) {
+                    this.servers.delete(serverId);
+                    for (const [channelId, channel] of this.channels) {
+                        if (channel.serverId === serverId)
+                            this.channels.delete(channelId);
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    /** Insert, evicting the oldest entry (by insertion order) once at capacity. */
+    cacheSet(map, key, value, cap) {
+        if (!map.has(key) && map.size >= cap) {
+            const oldest = map.keys().next().value;
+            if (oldest !== undefined)
+                map.delete(oldest);
+        }
+        map.set(key, value);
+    }
+    join(socket, topic, onBroadcast) {
+        return new Promise((resolve, reject) => {
+            const channel = socket.channel(topic, {});
+            if (onBroadcast)
+                channel.on('broadcast', onBroadcast);
+            channel
+                .join()
+                .receive('ok', () => resolve(channel))
+                .receive('error', (e) => reject(new errors_1.PrivageConnectionError(`join ${topic} denied: ${JSON.stringify(e)}`)))
+                .receive('timeout', () => reject(new errors_1.PrivageConnectionError(`join ${topic} timeout`)));
+        });
+    }
+    sessionOpen(personal) {
+        return this.rpc(personal, 'session.open', {
+            schema_version: 1,
+            gateway_protocol: { min: 2, max: 2 },
+            stream_id: this.streamId,
+            intents: this.intents,
+            client: { platform: 'bot', build: null },
+            device: { foreground: true, focused: true },
+        }).then((d) => {
+            // A fresh stream — reset the resume cursor to its baseline.
+            this.streamToken = d?.stream_token ?? this.streamToken;
+            this.resumeCursor = typeof d?.latest_ss === 'number' ? d.latest_ss : 0;
+        });
+    }
+    sessionResume(personal) {
+        return this.rpc(personal, 'session.resume', {
+            stream_id: this.streamId,
+            stream_token: this.streamToken,
+            resume_seq: this.resumeCursor,
+        }).then((d) => {
+            this.streamToken = d?.stream_token ?? this.streamToken;
+            // Replay buffered events through the normal path (dedupe + cursor advance + emit).
+            for (const e of d?.events ?? [])
+                this.handleEvent(e);
+            return { resumed: !!d?.resumed, catchupRequired: !!d?.catchup_required };
+        });
+    }
+    /** Send a `session.*` RPC and resolve its response `d` (rejects on `error`/timeout). */
+    rpc(personal, type, d) {
+        return new Promise((resolve, reject) => {
+            const rid = (0, crypto_1.randomUUID)();
+            const timer = setTimeout(() => reject(new errors_1.PrivageConnectionError(`${type} timeout`)), RPC_TIMEOUT_MS);
+            const onReply = (env) => {
+                if (env?.rid !== rid || env?.t !== type)
+                    return;
+                clearTimeout(timer);
+                if (env.k === 'error')
+                    reject(new errors_1.PrivageConnectionError(`${type} rejected: ${JSON.stringify(env.d)}`));
+                else
+                    resolve(env.d ?? {});
+            };
+            personal.on('broadcast', onReply);
+            personal.push(type, { k: 'request', t: type, v: 2, rid, d });
+        });
+    }
+    /** Backfill per-topic gaps the resume buffer couldn't cover. Best-effort — never fatal. */
+    async restCatchup() {
+        if (this.topicCursors.size === 0)
+            return;
+        try {
+            const resp = await this.rest.request('/gateway/catchup', {
+                method: 'POST',
+                body: { topics: Object.fromEntries(this.topicCursors) },
+            });
+            let replayed = 0;
+            let stale = 0;
+            for (const res of Object.values(resp?.topics ?? {})) {
+                if (Array.isArray(res?.events)) {
+                    for (const e of res.events) {
+                        this.handleEvent(e);
+                        replayed += 1;
+                    }
+                }
+                else if (res?.resync || res?.too_many) {
+                    stale += 1;
+                }
+            }
+            for (const [topic, head] of Object.entries(resp?.heads ?? {})) {
+                if (typeof head === 'string' && STREAM_SEQ_RE.test(head))
+                    this.topicCursors.set(topic, head);
+            }
+            this.debug(`catchup replayed ${replayed} event(s)`);
+            if (stale) {
+                this.warn(`catchup: ${stale} topic(s) had too large a gap to backfill — some state may be stale; re-fetch over REST if it matters`);
+            }
+        }
+        catch (e) {
+            this.warn(`catchup failed: ${e?.message || e}`);
+        }
+    }
+    // ── event routing ─────────────────────────────────────────────────────
+    handleEvent(envelope) {
+        this.advanceCursors(envelope);
+        const dk = envelope?.dk;
+        if (dk) {
+            if (this.seenSet.has(dk))
+                return; // at-least-once delivery — dedupe by dk
+            this.remember(dk);
+        }
+        const type = envelope?.t || envelope?.d?.type || 'unknown';
+        const d = envelope?.d && typeof envelope.d === 'object' ? envelope.d : envelope;
+        // Cache maintenance must never block event dispatch — a bad payload here
+        // shouldn't drop the message/reaction/member routing below.
+        try {
+            this.updateCaches(type, d);
+        }
+        catch (e) {
+            this.debug(`cache update failed for ${type}: ${e?.message || e}`);
+        }
+        switch (type) {
+            case 'new-message':
+            case 'message-created':
+            case 'thread-message':
+                this.dispatchMessage('messageCreate', d);
+                break;
+            case 'new-message-batch':
+                for (const m of d.messages || []) {
+                    if (m)
+                        this.dispatchMessage('messageCreate', { ...m, channel_id: m.channel_id || d.channel_id });
+                }
+                break;
+            case 'message-edited':
+                this.dispatchMessage('messageUpdate', d);
+                break;
+            case 'interaction':
+                this.safeEmit('interaction', new Interaction_1.Interaction(this, d));
+                break;
+            case 'message-deleted':
+                this.safeEmit('messageDelete', {
+                    id: String(d.id ?? d.message_id ?? ''),
+                    channelId: String(d.channel_id ?? ''),
+                    serverId: d.server_id != null ? String(d.server_id) : null,
+                });
+                break;
+            case 'bulk-messages-deleted':
+                this.safeEmit('messageDeleteBulk', {
+                    ids: (d.ids || d.message_ids || d.messageIds || []).map(String),
+                    channelId: String(d.channel_id ?? ''),
+                    serverId: d.server_id != null ? String(d.server_id) : null,
+                });
+                break;
+            case 'reaction-update': {
+                const messageId = String(d.messageId ?? d.message_id ?? '');
+                const channelId = d.channel_id != null ? String(d.channel_id)
+                    : d.channelId != null ? String(d.channelId)
+                        : this.channelByMessage.get(messageId) ?? null;
+                this.safeEmit('reactionUpdate', {
+                    messageId,
+                    channelId,
+                    reactions: Array.isArray(d.reactions) ? d.reactions : [],
+                });
+                // Granular add/remove — present on single-user toggles (not bulk clears).
+                if (d.actor_id != null && d.emoji != null) {
+                    const action = { messageId, channelId, emoji: String(d.emoji), userId: String(d.actor_id) };
+                    this.safeEmit(d.added ? 'reactionAdd' : 'reactionRemove', action);
+                }
+                break;
+            }
+            case 'member-joined':
+                this.safeEmit('memberJoin', new Member_1.Member(this, d));
+                break;
+            case 'member-left':
+                this.safeEmit('memberLeave', {
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                    serverId: d.serverId != null ? String(d.serverId) : (d.server_id != null ? String(d.server_id) : null),
+                });
+                break;
+            case 'member-role-added':
+            case 'member-role-removed': {
+                const change = {
+                    serverId: String(d.serverId ?? d.server_id ?? ''),
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                    roleId: String(d.roleId ?? d.role_id ?? ''),
+                };
+                this.safeEmit(type === 'member-role-added' ? 'roleAdd' : 'roleRemove', change);
+                break;
+            }
+            case 'member-updated':
+            case 'nickname-updated': {
+                const update = {
+                    serverId: String(d.serverId ?? d.server_id ?? ''),
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                };
+                if (d.display_name != null)
+                    update.displayName = d.display_name;
+                if (d.avatar_url != null)
+                    update.avatarUrl = d.avatar_url;
+                if (d.nickname != null)
+                    update.nickname = d.nickname;
+                this.safeEmit('memberUpdate', update);
+                break;
+            }
+            case 'member-banned':
+            case 'member-unbanned':
+                this.safeEmit(type === 'member-banned' ? 'memberBan' : 'memberUnban', {
+                    serverId: String(d.serverId ?? d.server_id ?? ''),
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                    username: d.username ?? '',
+                    displayName: d.displayName ?? d.display_name ?? '',
+                });
+                break;
+            case 'member-timeout': {
+                const until = d.timeoutUntil ?? d.timeout_until;
+                this.safeEmit('memberTimeout', {
+                    serverId: String(d.serverId ?? d.server_id ?? ''),
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                    until: until ? new Date(until) : null,
+                    moderatorId: d.moderatorId != null ? String(d.moderatorId) : (d.moderator_id != null ? String(d.moderator_id) : null),
+                    reason: d.reason ?? null,
+                });
+                break;
+            }
+            case 'member-untimeout':
+                this.safeEmit('memberUntimeout', {
+                    serverId: String(d.serverId ?? d.server_id ?? ''),
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                });
+                break;
+            case 'message-pinned':
+            case 'message-unpinned':
+                this.safeEmit(type === 'message-pinned' ? 'messagePin' : 'messageUnpin', {
+                    messageId: String(d.messageId ?? d.message_id ?? ''),
+                    channelId: String(d.channelId ?? d.channel_id ?? ''),
+                });
+                break;
+            case 'typing-start':
+                this.safeEmit('typingStart', {
+                    userId: String(d.user?.id ?? d.user?.user_id ?? d.userId ?? d.user_id ?? ''),
+                    channelId: String(d.channelId ?? d.channel_id ?? ''),
+                });
+                break;
+            case 'typing-stop':
+                this.safeEmit('typingStop', {
+                    userId: String(d.userId ?? d.user_id ?? ''),
+                    channelId: String(d.channelId ?? d.channel_id ?? ''),
+                });
+                break;
+            case 'channel-created':
+                if (d?.channel)
+                    this.safeEmit('channelCreate', new Channel_1.Channel(this, d.channel));
+                break;
+            case 'channel-updated':
+                if (d?.channel)
+                    this.safeEmit('channelUpdate', new Channel_1.Channel(this, d.channel));
+                break;
+            case 'channel-deleted':
+                this.safeEmit('channelDelete', {
+                    channelId: String(d.channelId ?? d.channel_id ?? ''),
+                    serverId: d.serverId != null ? String(d.serverId) : (d.server_id != null ? String(d.server_id) : null),
+                });
+                break;
+            case 'role-created':
+                if (d?.role)
+                    this.safeEmit('roleCreate', new Role_1.Role(d.role));
+                break;
+            case 'role-updated':
+                if (d?.role)
+                    this.safeEmit('roleUpdate', new Role_1.Role(d.role));
+                break;
+            case 'role-deleted':
+                this.safeEmit('roleDelete', {
+                    roleId: String(d.roleId ?? d.role_id ?? ''),
+                    serverId: d.serverId != null ? String(d.serverId) : (d.server_id != null ? String(d.server_id) : null),
+                });
+                break;
+            case 'poll-voted':
+                this.safeEmit('pollVote', {
+                    pollId: String(d.pollId ?? ''),
+                    messageId: String(d.messageId ?? ''),
+                    voterId: String(d.voterId ?? ''),
+                    optionIdx: typeof d.optionIdx === 'number' ? d.optionIdx : Number(d.optionIdx ?? 0),
+                    totalVotes: typeof d.totalVotes === 'number' ? d.totalVotes : Number(d.totalVotes ?? 0),
+                });
+                break;
+            case 'poll-closed':
+                this.safeEmit('pollClose', {
+                    pollId: String(d.pollId ?? ''),
+                    messageId: String(d.messageId ?? ''),
+                    totalVotes: typeof d.totalVotes === 'number' ? d.totalVotes : Number(d.totalVotes ?? 0),
+                });
+                break;
+            default:
+                this.debug(`unhandled event: ${type}`);
+        }
+    }
+    advanceCursors(envelope) {
+        const ss = typeof envelope?.ss === 'number' ? envelope.ss : null;
+        if (ss != null && ss > this.resumeCursor)
+            this.resumeCursor = ss;
+        const s = envelope?.s;
+        if (typeof s === 'string' && STREAM_SEQ_RE.test(s)) {
+            const d = envelope?.d && typeof envelope.d === 'object' ? envelope.d : envelope;
+            const topic = this.topicOf(d);
+            if (topic)
+                this.topicCursors.set(topic, s);
+        }
+    }
+    topicOf(d) {
+        const ch = d?.channel_id ?? d?.channelId;
+        if (ch != null)
+            return `channel:${ch}`;
+        const sv = d?.server_id ?? d?.serverId;
+        if (sv != null)
+            return `server:${sv}`;
+        return null;
+    }
+    dispatchMessage(event, d) {
+        let msg;
+        try {
+            msg = new Message_1.Message(this, d);
+        }
+        catch (e) {
+            this.warn(`failed to build ${event}: ${e?.message || e}`);
+            return;
+        }
+        if (msg.id && msg.channelId)
+            this.rememberChannel(msg.id, msg.channelId);
+        // Emit first — delivery is the priority and must never be blocked by the
+        // secondary name-cache fill below.
+        try {
+            this.emit(event, msg);
+        }
+        catch (e) {
+            this.warn(`${event} handler error: ${e?.message || e}`);
+        }
+        if (msg.channelId && !this.channels.has(msg.channelId)) {
+            try {
+                this.ensureChannel(msg.channelId, msg.serverId ?? undefined);
+            }
+            catch (e) {
+                this.debug(`ensureChannel failed: ${e?.message || e}`);
+            }
+        }
+    }
+    rememberChannel(messageId, channelId) {
+        if (this.channelByMessage.has(messageId))
+            return;
+        this.channelByMessage.set(messageId, channelId);
+        this.channelByMessageKeys.push(messageId);
+        if (this.channelByMessageKeys.length > DEDUPE_CACHE) {
+            const oldest = this.channelByMessageKeys.shift();
+            if (oldest)
+                this.channelByMessage.delete(oldest);
+        }
+    }
+    safeEmit(event, ...args) {
+        try {
+            this.emit(event, ...args);
+        }
+        catch (e) {
+            this.warn(`failed to dispatch ${String(event)}: ${e?.message || e}`);
+        }
+    }
+    remember(dk) {
+        this.seenSet.add(dk);
+        this.seen.push(dk);
+        if (this.seen.length > DEDUPE_CACHE) {
+            const oldest = this.seen.shift();
+            if (oldest)
+                this.seenSet.delete(oldest);
+        }
+    }
+}
+exports.Client = Client;