privage.js 0.22.0 → 0.26.0

package/dist/Client.d.ts

@@ -11,7 +11,7 @@ import { Role } from './structures/Role';
 import type { ClientOptions, ClientEvents, BotUser } from './types';
 /**
  * A Privage bot connection. Owns the full lifecycle — auth, ticket, socket,
- * topic joins, `session.open`/`session.resume`, heartbeat, reconnect with
+ * the bot.v1 gateway stream, heartbeat, reconnect with
  * backoff, dedupe, and transparent resume + REST catchup — and surfaces
  * friendly, camelCase events. The wire protocol never leaks into the public
  * API (see the protocol spec §12).
@@ -35,13 +35,13 @@ export declare class Client extends EventEmitter {
     readonly commands: CommandsManager;
     /**
      * Server name cache — hydrated from `GET /servers` on connect, kept fresh
-     * by `server-meta-updated`/`server-deleted` (requires `Intents.Servers`).
+     * by `server.meta_updated`/`server.deleted` (requires `Intents.Servers`).
      * Capped at {@link SERVER_CACHE_CAP}, oldest entries evict first.
      */
     readonly servers: ReadonlyMap<string, Server>;
     /**
      * Channel name cache — hydrated per-server in the background after connect,
-     * kept fresh by `channel-created`/`channel-updated`/`channel-deleted`
+     * 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.
      */
@@ -56,6 +56,7 @@ export declare class Client extends EventEmitter {
     private readonly streamId;
     private socket;
     private reconnectAttempts;
+    private lastHandshakeAt;
     private reconnectPending;
     private destroyed;
     private connectedOnce;
@@ -65,6 +66,9 @@ export declare class Client extends EventEmitter {
     private streamToken;
     private resumeCursor;
     private readonly topicCursors;
+    private readonly catchupFence;
+    private checkpointTimer;
+    private lastCheckpointedSequence;
     private readonly seen;
     private readonly seenSet;
     private readonly channelByMessage;
@@ -175,16 +179,25 @@ export declare class Client extends EventEmitter {
     private updateCaches;
     /** Insert, evicting the oldest entry (by insertion order) once at capacity. */
     private cacheSet;
-    private join;
-    private sessionOpen;
-    private sessionResume;
-    /** Send a `session.*` RPC and resolve its response `d` (rejects on `error`/timeout). */
-    private rpc;
-    /** Backfill per-topic gaps the resume buffer couldn't cover. Best-effort — never fatal. */
+    private joinGateway;
+    private handleGatewayItems;
+    /**
+     * Coalesced checkpoint push. session.checkpoint shares the per-stream
+     * command budget with every other command; one push per events batch under
+     * load can starve it (rejections arrive without receive handlers, so the
+     * SDK would never notice). Debounced, and skipped when the cursor has not
+     * advanced past the last checkpoint. Best-effort: resume correctness rides
+     * the in-memory cursor, not the server-side checkpoint.
+     */
+    private scheduleCheckpoint;
+    private clearCheckpointTimer;
+    private handleGatewayReset;
+    private pushGatewayCommand;
+    private forceGatewayReconnect;
+    /** Backfill per-topic gaps the resume buffer could not cover. */
     private restCatchup;
-    private handleEvent;
-    private advanceCursors;
-    private topicOf;
+    private handleBotCatchupEvent;
+    private handleCanonicalEvent;
     private dispatchMessage;
     private rememberChannel;
     private safeEmit;

package/dist/Client.js

@@ -19,11 +19,35 @@ const Channel_1 = require("./structures/Channel");
 const Role_1 = require("./structures/Role");
 const intents_1 = require("./intents");
 const errors_1 = require("./errors");
+const version_1 = require("./version");
 const RECONNECT_BASE_MS = 3000;
 const RECONNECT_MAX_MS = 60000;
+// A connection must survive this long after a successful handshake before a
+// later failure resets the backoff ladder. Without it, a ready-then-fail loop
+// (e.g. a recurring post-ready sequence gap) reconnects at the 3s floor
+// forever because every successful handshake zeroed the attempt counter.
+const RECONNECT_STABILITY_MS = 60000;
 const DEDUPE_CACHE = 1000;
 const RPC_TIMEOUT_MS = 10000;
+const GATEWAY_READY_TIMEOUT_MS = 30000;
+// Coalesce session.checkpoint pushes: they share the per-stream command
+// budget with everything else, and one-per-batch under load can starve it.
+const CHECKPOINT_DEBOUNCE_MS = 1000;
 const STREAM_SEQ_RE = /^\d+-\d+$/;
+// Compare two Redis stream positions ("ms-seq"). Returns <0, 0, >0.
+function compareStreamPositions(a, b) {
+    const [aMs, aSeq] = a.split('-');
+    const [bMs, bSeq] = b.split('-');
+    if (aMs.length !== bMs.length)
+        return aMs.length - bMs.length;
+    if (aMs !== bMs)
+        return aMs < bMs ? -1 : 1;
+    if (aSeq.length !== bSeq.length)
+        return aSeq.length - bSeq.length;
+    if (aSeq !== bSeq)
+        return aSeq < bSeq ? -1 : 1;
+    return 0;
+}
 // 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;
@@ -44,13 +68,13 @@ class Client extends events_1.EventEmitter {
         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`).
+         * 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`
+         * 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.
          */
@@ -60,14 +84,24 @@ class Client extends events_1.EventEmitter {
         this.token = null;
         this.socket = null;
         this.reconnectAttempts = 0;
+        // Set on successful handshake, consumed by scheduleReconnect: the backoff
+        // ladder only resets after RECONNECT_STABILITY_MS of post-handshake uptime.
+        this.lastHandshakeAt = 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)
+        this.resumeCursor = 0; // highest dense bot.v1 sequence applied on the current stream
+        this.topicCursors = new Map(); // topic -> last source position (for REST catchup)
+        // Catchup fence: after a REST catchup, heads[topic] marks how far the
+        // catchup already delivered. Live sequenced items at or below the fence are
+        // counted (sequence advances — density must hold) but not re-dispatched.
+        this.catchupFence = new Map();
+        // Coalesced checkpoint state.
+        this.checkpointTimer = null;
+        this.lastCheckpointedSequence = 0;
         // Dedupe (at-least-once delivery + resume/catchup overlap).
         this.seen = [];
         this.seenSet = new Set();
@@ -133,6 +167,7 @@ class Client extends events_1.EventEmitter {
     /** Disconnect and stop reconnecting. */
     destroy() {
         this.destroyed = true;
+        this.clearCheckpointTimer();
         if (this.socket) {
             try {
                 this.socket.disconnect();
@@ -284,6 +319,12 @@ class Client extends events_1.EventEmitter {
         if (this.destroyed || this.reconnectPending)
             return;
         this.reconnectPending = true;
+        // Reset the backoff ladder only after a run of genuine stability, so a
+        // ready-then-fail loop grows its delay instead of hammering the 3s floor.
+        if (this.lastHandshakeAt && Date.now() - this.lastHandshakeAt >= RECONNECT_STABILITY_MS) {
+            this.reconnectAttempts = 0;
+        }
+        this.lastHandshakeAt = 0;
         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`));
@@ -305,7 +346,7 @@ class Client extends events_1.EventEmitter {
         }
         try {
             await this.handshake();
-            this.reconnectAttempts = 0;
+            this.lastHandshakeAt = Date.now();
         }
         catch (err) {
             if (this.isFatal(err)) {
@@ -345,27 +386,8 @@ class Client extends events_1.EventEmitter {
             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'})`);
-        }
+        await this.joinGateway(socket);
+        this.debug(`gateway ready (profile: bot.v1, intents: ${this.intents.join(', ') || 'ALL'})`);
         if (!this.connectedOnce) {
             this.connectedOnce = true;
             this.readyAtMs = Date.now();
@@ -486,8 +508,8 @@ class Client extends events_1.EventEmitter {
     /** Cache-maintenance for structure events. Cache-only — never emits new SDK events. */
     updateCaches(type, d) {
         switch (type) {
-            case 'channel-created':
-            case 'channel-updated': {
+            case 'channel.created':
+            case 'channel.updated': {
                 if (d?.channel) {
                     const channel = new Channel_1.Channel(this, d.channel);
                     if (channel.id)
@@ -495,13 +517,13 @@ class Client extends events_1.EventEmitter {
                 }
                 break;
             }
-            case 'channel-deleted': {
+            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': {
+            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;
@@ -512,7 +534,7 @@ class Client extends events_1.EventEmitter {
                 }
                 break;
             }
-            case 'server-deleted': {
+            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);
@@ -536,78 +558,271 @@ class Client extends events_1.EventEmitter {
         }
         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,
+    async joinGateway(socket) {
+        const payload = {
+            protocol_version: 1,
+            event_profiles: ['bot.v1'],
             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;
+            transport: { encoding: 'json', compression: 'none' },
+            client: { platform: 'bot', build: `privage.js/${version_1.SDK_VERSION}` },
+            stream: {
+                id: this.streamId,
+                ...(this.streamToken
+                    ? { resume: { token: this.streamToken, last_applied_sequence: this.resumeCursor } }
+                    : {}),
+            },
+            view: { revision: 0, contexts: [], foreground: true, focused: true },
+            cached_domains: {},
+        };
+        const channel = socket.channel('gateway', payload);
+        let settled = false;
+        let readyResolve;
+        let readyReject;
+        const ready = new Promise((resolve, reject) => {
+            readyResolve = () => { settled = true; resolve(); };
+            readyReject = (error) => { settled = true; reject(error); };
+        });
+        // A join denial can happen before this promise becomes the active await.
+        // Observe rejection immediately so an early session.reconnect/timeout
+        // cannot become an unhandled rejection while the join reply is pending.
+        void ready.catch(() => undefined);
+        const readyTimer = setTimeout(() => readyReject(new errors_1.PrivageConnectionError('gateway session.ready timeout')), GATEWAY_READY_TIMEOUT_MS);
+        channel.on('events', (batch) => this.handleGatewayItems(channel, batch, true));
+        channel.on('signals', (batch) => this.handleGatewayItems(channel, batch, false));
+        channel.on('session.reset', (reset) => {
+            void this.handleGatewayReset(channel, reset).catch((error) => {
+                const failure = error instanceof Error ? error : new errors_1.PrivageConnectionError(String(error));
+                if (!settled)
+                    readyReject(failure);
+                this.forceGatewayReconnect(`reset failed (${failure.message})`);
+            });
+        });
+        channel.on('session.ready', (value) => {
+            if (typeof value?.resume_token !== 'string' || !Number.isInteger(value?.sequence_base)) {
+                if (!settled)
+                    readyReject(new errors_1.PrivageConnectionError('malformed session.ready'));
+                this.forceGatewayReconnect('malformed session.ready');
+                return;
+            }
+            this.streamToken = value.resume_token;
+            // Unconditional: sequence_base is the stream tail at attach time (resume
+            // replay is enqueued strictly before session.ready, so an applied replay
+            // never exceeds it). Math.max here would keep a stale high cursor after a
+            // server-side reset rebased the stream (e.g. to 0), making every future
+            // item look "already seen" — the bot would go permanently deaf.
+            this.resumeCursor = value.sequence_base;
+            this.lastCheckpointedSequence = value.sequence_base;
+            clearTimeout(readyTimer);
+            if (!settled)
+                readyResolve();
+        });
+        channel.on('session.reconnect', (value) => {
+            const reason = typeof value?.reason === 'string' ? value.reason : 'server requested reconnect';
+            if (!settled)
+                readyReject(new errors_1.PrivageConnectionError(reason));
+            this.forceGatewayReconnect(reason);
+        });
+        channel.on('gateway.error', (value) => {
+            this.warn(`gateway error: ${value?.code || 'unknown'}${value?.message ? ` - ${value.message}` : ''}`);
         });
+        // Disable phoenix.js's automatic channel rejoin. Its payload is frozen
+        // at construction time; this client must rebuild it from the latest
+        // resume token and dense sequence after every disconnect.
+        channel.rejoin = () => undefined;
+        try {
+            const reply = await new Promise((resolve, reject) => {
+                channel
+                    .join()
+                    .receive('ok', resolve)
+                    .receive('error', (e) => reject(new errors_1.PrivageConnectionError(`join gateway denied: ${JSON.stringify(e)}`)))
+                    .receive('timeout', () => reject(new errors_1.PrivageConnectionError('join gateway timeout')));
+            });
+            if (reply?.event_profile !== 'bot.v1' || reply?.stream_id !== this.streamId) {
+                throw new errors_1.PrivageConnectionError('gateway selected an incompatible stream/profile');
+            }
+            // session.ready may be queued before the join reply. Never overwrite its
+            // atomically-installed token with the earlier provisional join token.
+            if (!settled && typeof reply.resume_token === 'string') {
+                this.streamToken = reply.resume_token;
+            }
+            await ready;
+        }
+        finally {
+            // A denied/timed-out join never receives session.ready. Cancel its
+            // timer and close the local readiness latch as part of this attempt.
+            clearTimeout(readyTimer);
+            settled = true;
+        }
+    }
+    handleGatewayItems(channel, batch, durable) {
+        const items = Array.isArray(batch?.items) ? batch.items : null;
+        if (!items) {
+            this.forceGatewayReconnect(`malformed ${durable ? 'events' : 'signals'} batch`);
+            return;
+        }
+        const cursorBefore = this.resumeCursor;
+        for (const item of items) {
+            if (!item ||
+                typeof item !== 'object' ||
+                typeof item.name !== 'string' ||
+                !item.name ||
+                !item.payload ||
+                typeof item.payload !== 'object' ||
+                Array.isArray(item.payload)) {
+                this.forceGatewayReconnect('malformed gateway item');
+                return;
+            }
+            const source = item.source;
+            const partitionKey = typeof source?.partition_key === 'string' ? source.partition_key : null;
+            const position = typeof source?.position === 'string' && STREAM_SEQ_RE.test(source.position)
+                ? source.position
+                : null;
+            if (durable) {
+                // schema_version rides only on durable event items — the wire protocol
+                // omits it on signal items ({name, scope, payload}), so enforcing it
+                // there would tear the session down on the first typing/interaction
+                // signal delivered.
+                const sequence = item.sequence;
+                if (!Number.isInteger(sequence) || sequence < 0
+                    || typeof item.event_id !== 'string' || !item.event_id
+                    || item.schema_version !== 1) {
+                    this.forceGatewayReconnect('malformed gateway sequence');
+                    return;
+                }
+                if (sequence <= this.resumeCursor)
+                    continue;
+                if (sequence !== this.resumeCursor + 1) {
+                    this.forceGatewayReconnect(`gateway sequence gap: expected ${this.resumeCursor + 1}, got ${sequence}`);
+                    return;
+                }
+                // Catchup and live projection identities are intentionally independent,
+                // so the source-position fence pairs their copies. An item at or below the
+                // catchup head for its topic was already dispatched by restCatchup —
+                // count it (sequence density must hold) but do not re-dispatch it.
+                if (partitionKey && position) {
+                    const fence = this.catchupFence.get(partitionKey);
+                    if (fence) {
+                        if (compareStreamPositions(position, fence) <= 0) {
+                            this.resumeCursor = sequence;
+                            continue;
+                        }
+                        // First item past the fence: the catchup window for this topic is
+                        // exhausted; drop the entry so the map stays bounded.
+                        this.catchupFence.delete(partitionKey);
+                    }
+                }
+            }
+            const data = item.payload;
+            // Sequence ownership stays entirely in bot.v1. Advance before user
+            // handlers run so a throwing handler cannot create a replay gap.
+            if (durable)
+                this.resumeCursor = item.sequence;
+            this.handleCanonicalEvent({
+                name: item.name,
+                payload: data,
+                eventId: durable ? item.event_id : null,
+            });
+            if (durable && partitionKey && position) {
+                this.topicCursors.set(partitionKey, position);
+            }
+        }
+        if (durable && this.resumeCursor > cursorBefore) {
+            this.scheduleCheckpoint(channel);
+        }
     }
-    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 };
+    /**
+     * Coalesced checkpoint push. session.checkpoint shares the per-stream
+     * command budget with every other command; one push per events batch under
+     * load can starve it (rejections arrive without receive handlers, so the
+     * SDK would never notice). Debounced, and skipped when the cursor has not
+     * advanced past the last checkpoint. Best-effort: resume correctness rides
+     * the in-memory cursor, not the server-side checkpoint.
+     */
+    scheduleCheckpoint(channel) {
+        if (this.checkpointTimer)
+            return;
+        this.checkpointTimer = setTimeout(() => {
+            this.checkpointTimer = null;
+            if (this.destroyed)
+                return;
+            if (this.resumeCursor <= this.lastCheckpointedSequence)
+                return;
+            this.lastCheckpointedSequence = this.resumeCursor;
+            try {
+                channel.push('session.checkpoint', {
+                    last_applied_sequence: this.resumeCursor,
+                    view_revision: 0,
+                });
+            }
+            catch { /* channel torn down — the next session re-baselines */ }
+        }, CHECKPOINT_DEBOUNCE_MS);
+    }
+    clearCheckpointTimer() {
+        if (this.checkpointTimer) {
+            clearTimeout(this.checkpointTimer);
+            this.checkpointTimer = null;
+        }
+    }
+    async handleGatewayReset(channel, reset) {
+        if (typeof reset?.sync_id !== 'string' || !Array.isArray(reset?.required_domains)) {
+            throw new errors_1.PrivageConnectionError('malformed session.reset');
+        }
+        if (reset.required_domains.length > 0 || reset.refetch_active_conversation === true) {
+            throw new errors_1.PrivageConnectionError('bot.v1 received human recovery domains');
+        }
+        await this.restCatchup();
+        await this.pushGatewayCommand(channel, 'sync.confirm', {
+            sync_id: reset.sync_id,
+            applied_domains: {},
+            active_conversation_refetched: false,
         });
     }
-    /** Send a `session.*` RPC and resolve its response `d` (rejects on `error`/timeout). */
-    rpc(personal, type, d) {
+    pushGatewayCommand(channel, event, payload) {
         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 });
+            channel
+                .push(event, payload, RPC_TIMEOUT_MS)
+                .receive('ok', resolve)
+                .receive('error', (error) => reject(new errors_1.PrivageConnectionError(`${event} rejected: ${JSON.stringify(error)}`)))
+                .receive('timeout', () => reject(new errors_1.PrivageConnectionError(`${event} timeout`)));
         });
     }
-    /** Backfill per-topic gaps the resume buffer couldn't cover. Best-effort — never fatal. */
+    forceGatewayReconnect(reason) {
+        if (this.destroyed)
+            return;
+        this.clearCheckpointTimer();
+        const socket = this.socket;
+        this.scheduleReconnect(reason);
+        if (socket) {
+            try {
+                socket.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** Backfill per-topic gaps the resume buffer could not cover. */
     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) },
+                body: {
+                    event_profile: 'bot.v1',
+                    intents: this.intents,
+                    topics: Object.fromEntries(this.topicCursors),
+                },
             });
+            if (resp?.event_profile !== 'bot.v1') {
+                throw new errors_1.PrivageConnectionError('catchup selected an incompatible event profile');
+            }
             let replayed = 0;
             let stale = 0;
-            for (const res of Object.values(resp?.topics ?? {})) {
+            const deliveredTopics = new Set();
+            for (const [topic, res] of Object.entries(resp?.topics ?? {})) {
                 if (Array.isArray(res?.events)) {
-                    for (const e of res.events) {
-                        this.handleEvent(e);
+                    deliveredTopics.add(topic);
+                    for (const event of res.events) {
+                        this.handleBotCatchupEvent(topic, event);
                         replayed += 1;
                     }
                 }
@@ -616,8 +831,14 @@ class Client extends events_1.EventEmitter {
                 }
             }
             for (const [topic, head] of Object.entries(resp?.heads ?? {})) {
-                if (typeof head === 'string' && STREAM_SEQ_RE.test(head))
-                    this.topicCursors.set(topic, head);
+                if (typeof head !== 'string' || !STREAM_SEQ_RE.test(head))
+                    continue;
+                this.topicCursors.set(topic, head);
+                // Fence live re-delivery ONLY where catchup actually delivered the
+                // window. A resync/too_many topic's retained live events are the only
+                // copy the bot will ever see — fencing them would silently drop them.
+                if (deliveredTopics.has(topic))
+                    this.catchupFence.set(topic, head);
             }
             this.debug(`catchup replayed ${replayed} event(s)`);
             if (stale) {
@@ -625,20 +846,35 @@ class Client extends events_1.EventEmitter {
             }
         }
         catch (e) {
-            this.warn(`catchup failed: ${e?.message || e}`);
+            throw e instanceof Error ? e : new errors_1.PrivageConnectionError(String(e));
+        }
+    }
+    handleBotCatchupEvent(topic, event) {
+        const source = event?.source;
+        if (typeof event?.name !== 'string' ||
+            typeof event?.event_id !== 'string' ||
+            event?.schema_version !== 1 ||
+            !event?.payload ||
+            typeof event.payload !== 'object' ||
+            source?.partition_key !== topic ||
+            typeof source?.position !== 'string' ||
+            !STREAM_SEQ_RE.test(source.position)) {
+            throw new errors_1.PrivageConnectionError('malformed bot.v1 catchup event');
         }
+        this.handleCanonicalEvent({
+            name: event.name,
+            payload: event.payload,
+            eventId: event.event_id,
+        });
     }
     // ── 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;
+    handleCanonicalEvent(event) {
+        if (event.eventId) {
+            if (this.seenSet.has(event.eventId))
+                return;
+        }
+        const type = event.name;
+        const d = event.payload;
         // Cache maintenance must never block event dispatch — a bad payload here
         // shouldn't drop the message/reaction/member routing below.
         try {
@@ -648,38 +884,31 @@ class Client extends events_1.EventEmitter {
             this.debug(`cache update failed for ${type}: ${e?.message || e}`);
         }
         switch (type) {
-            case 'new-message':
-            case 'message-created':
-            case 'thread-message':
+            case 'message.created':
+            case 'thread.message_created':
                 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':
+            case 'message.edited':
                 this.dispatchMessage('messageUpdate', d);
                 break;
-            case 'interaction':
+            case 'interaction.created':
                 this.safeEmit('interaction', new Interaction_1.Interaction(this, d));
                 break;
-            case 'message-deleted':
+            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':
+            case 'message.bulk_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': {
+            case 'reaction.updated': {
                 const messageId = String(d.messageId ?? d.message_id ?? '');
                 const channelId = d.channel_id != null ? String(d.channel_id)
                     : d.channelId != null ? String(d.channelId)
@@ -696,27 +925,37 @@ class Client extends events_1.EventEmitter {
                 }
                 break;
             }
-            case 'member-joined':
+            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),
-                });
+            case 'member.removed':
+                if (d.reason === 'banned') {
+                    this.safeEmit('memberBan', {
+                        serverId: String(d.serverId ?? d.server_id ?? ''),
+                        userId: String(d.userId ?? d.user_id ?? ''),
+                        username: d.username ?? '',
+                        displayName: d.displayName ?? d.display_name ?? '',
+                    });
+                }
+                else {
+                    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': {
+            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);
+                this.safeEmit(type === 'member.role_added' ? 'roleAdd' : 'roleRemove', change);
                 break;
             }
-            case 'member-updated':
-            case 'nickname-updated': {
+            case 'member.updated':
+            case 'member.nickname_updated': {
                 const update = {
                     serverId: String(d.serverId ?? d.server_id ?? ''),
                     userId: String(d.userId ?? d.user_id ?? ''),
@@ -730,16 +969,15 @@ class Client extends events_1.EventEmitter {
                 this.safeEmit('memberUpdate', update);
                 break;
             }
-            case 'member-banned':
-            case 'member-unbanned':
-                this.safeEmit(type === 'member-banned' ? 'memberBan' : 'memberUnban', {
+            case 'member.unbanned':
+                this.safeEmit('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': {
+            case 'member.timed_out': {
                 const until = d.timeoutUntil ?? d.timeout_until;
                 this.safeEmit('memberTimeout', {
                     serverId: String(d.serverId ?? d.server_id ?? ''),
@@ -750,60 +988,54 @@ class Client extends events_1.EventEmitter {
                 });
                 break;
             }
-            case 'member-untimeout':
+            case 'member.timeout_cleared':
                 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', {
+            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', {
+            case 'typing.changed':
+                this.safeEmit(d.active === true ? 'typingStart' : 'typingStop', {
                     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':
+            case 'channel.created':
                 if (d?.channel)
                     this.safeEmit('channelCreate', new Channel_1.Channel(this, d.channel));
                 break;
-            case 'channel-updated':
+            case 'channel.updated':
                 if (d?.channel)
                     this.safeEmit('channelUpdate', new Channel_1.Channel(this, d.channel));
                 break;
-            case 'channel-deleted':
+            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':
+            case 'role.created':
                 if (d?.role)
                     this.safeEmit('roleCreate', new Role_1.Role(d.role));
                 break;
-            case 'role-updated':
+            case 'role.updated':
                 if (d?.role)
                     this.safeEmit('roleUpdate', new Role_1.Role(d.role));
                 break;
-            case 'role-deleted':
+            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':
+            case 'poll.voted':
                 this.safeEmit('pollVote', {
                     pollId: String(d.pollId ?? ''),
                     messageId: String(d.messageId ?? ''),
@@ -812,7 +1044,7 @@ class Client extends events_1.EventEmitter {
                     totalVotes: typeof d.totalVotes === 'number' ? d.totalVotes : Number(d.totalVotes ?? 0),
                 });
                 break;
-            case 'poll-closed':
+            case 'poll.closed':
                 this.safeEmit('pollClose', {
                     pollId: String(d.pollId ?? ''),
                     messageId: String(d.messageId ?? ''),
@@ -820,29 +1052,12 @@ class Client extends events_1.EventEmitter {
                 });
                 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;
+                this.debug(`unhandled bot.v1 event: ${type}`);
+        }
+        // Record only after internal construction/routing succeeds. If a malformed
+        // payload throws before dispatch, reset/catchup can retry the same fact.
+        if (event.eventId)
+            this.remember(event.eventId);
     }
     dispatchMessage(event, d) {
         let msg;
@@ -891,9 +1106,9 @@ class Client extends events_1.EventEmitter {
             this.warn(`failed to dispatch ${String(event)}: ${e?.message || e}`);
         }
     }
-    remember(dk) {
-        this.seenSet.add(dk);
-        this.seen.push(dk);
+    remember(eventId) {
+        this.seenSet.add(eventId);
+        this.seen.push(eventId);
         if (this.seen.length > DEDUPE_CACHE) {
             const oldest = this.seen.shift();
             if (oldest)

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Client } from './Client';
 export { Intents } from './intents';
 export type { Intent } from './intents';
 export { Message, TextChannel } from './structures/Message';
-export type { MessageThread, MessageReference, ReferencedMessage, MessageAttachment, MessageEmbed, } from './structures/Message';
+export type { MessageThread, MessageReference, ReferencedMessage, MessageAttachment, MessageEmbed, MessageInteraction, } from './structures/Message';
 export { Member } from './structures/Member';
 export { Server } from './structures/Server';
 export { Channel } from './structures/Channel';

package/dist/intents.d.ts

@@ -1,7 +1,7 @@
 /**
- * Public, curated intents. The wire gateway has 16 intents, several of which
- * are dead or no-ops in v1 (see protocol spec §6/§11); the SDK exposes only
- * the ones that actually work. Each maps to a wire intent string.
+ * Public, curated bot intents. The wire gateway accepts a broader vocabulary
+ * for shared human/legacy surfaces; this SDK exposes only categories with a
+ * bot.v1 product-event contract. Each maps to a wire intent string.
  *
  * IMPORTANT: an empty intent list means the gateway delivers ALL events
  * (firehose). The SDK always sends the explicit resolved list — declare what

package/dist/intents.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Intents = void 0;
 exports.resolveIntents = resolveIntents;
 /**
- * Public, curated intents. The wire gateway has 16 intents, several of which
- * are dead or no-ops in v1 (see protocol spec §6/§11); the SDK exposes only
- * the ones that actually work. Each maps to a wire intent string.
+ * Public, curated bot intents. The wire gateway accepts a broader vocabulary
+ * for shared human/legacy surfaces; this SDK exposes only categories with a
+ * bot.v1 product-event contract. Each maps to a wire intent string.
  *
  * IMPORTANT: an empty intent list means the gateway delivers ALL events
  * (firehose). The SDK always sends the explicit resolved list — declare what

package/dist/structures/Channel.d.ts

@@ -3,8 +3,8 @@ import type { SendMessageOptions } from '../rest';
 type Sendable = string | Omit<SendMessageOptions, 'replyTo'>;
 /**
  * A channel the bot can see. `name`/`type`/`categoryId` come from the SDK's
- * name cache — hydrated on connect, kept fresh via `channel-created`/
- * `channel-updated`/`channel-deleted` events (`Intents.Servers`), and
+ * name cache — hydrated on connect, kept fresh via `channel.created`/
+ * `channel.updated`/`channel.deleted` events (`Intents.Servers`), and
  * lazily filled on cache miss (see `Client#ensureChannel`). A channel handed
  * out before it's resolved has `name: null`; it still works for `send`.
  */

package/dist/structures/Channel.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TextChannel = exports.Channel = void 0;
 /**
  * A channel the bot can see. `name`/`type`/`categoryId` come from the SDK's
- * name cache — hydrated on connect, kept fresh via `channel-created`/
- * `channel-updated`/`channel-deleted` events (`Intents.Servers`), and
+ * name cache — hydrated on connect, kept fresh via `channel.created`/
+ * `channel.updated`/`channel.deleted` events (`Intents.Servers`), and
  * lazily filled on cache miss (see `Client#ensureChannel`). A channel handed
  * out before it's resolved has `name: null`; it still works for `send`.
  */

package/dist/structures/Interaction.d.ts

@@ -20,7 +20,12 @@ export interface InteractionReplyData {
      * persisted, so there is nowhere for the bytes to live).
      */
     ephemeral?: boolean;
-    /** Components on the reply — ephemeral replies only (they render, but aren't clickable v1). */
+    /**
+     * Components on the reply — ephemeral replies only. They are fully
+     * interactive: clicks arrive as fresh `interaction` events carrying
+     * `ephemeralMessageId`, recipient-locked to the user the ephemeral was
+     * delivered to, for 15 minutes after sending.
+     */
     components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
     /**
      * File attachments on the reply — `AttachmentBuilder`s, paths, raw bytes,
@@ -85,8 +90,18 @@ export declare class Interaction {
     readonly command: InteractionCommand | null;
     /** Submitted modal fields — `kind: 'modal_submit'` only, `null` otherwise. */
     readonly fields: ModalSubmitField[] | null;
-    /** The source message. `null` for commands (and command-born modal submits) — `update()` is invalid then. */
+    /** The source message. `null` for commands, command-born modal submits, and ephemeral-born interactions — `update()` is invalid then. */
     readonly messageId: string | null;
+    /**
+     * Set when this interaction came from a component on an **ephemeral
+     * reply** — the synthetic ephemeral message's id. Recipient-locked:
+     * only the ephemeral's recipient can click, within the panel's
+     * 15-minute window (every click also re-checks membership/timeout).
+     * Respond with `update()` to morph the panel in place (the wizard
+     * pattern — updating refreshes the window), or `reply()` to post a
+     * new message.
+     */
+    readonly ephemeralMessageId: string | null;
     readonly channelId: string;
     readonly serverId: string | null;
     readonly user: {
@@ -115,10 +130,15 @@ export declare class Interaction {
     /** `kind === 'modal_submit'`. */
     isModalSubmit(): boolean;
     /**
-     * Terminal: edit the original message (content/embeds/components).
-     * Broadcasts a normal edit. Only valid when the interaction HAS a source
-     * message — throws client-side for `kind: 'command'` and for modal submits
-     * born from a command (the server would 400).
+     * Terminal: edit the message this interaction came from
+     * (content/embeds/components). On a persisted message that's a normal
+     * edit broadcast. On an interaction born from an **ephemeral reply**
+     * (`ephemeralMessageId` set) it morphs the ephemeral panel in place —
+     * patch semantics (only the fields you send change), refreshing the
+     * panel's 15-minute window; clearing `components: []` ends the panel,
+     * and an expired panel rejects with a 404. Throws client-side for
+     * `kind: 'command'` and command-born modal submits (no source at all —
+     * the server would 400).
      */
     update(data: InteractionUpdateData): Promise<any>;
     /**
@@ -140,7 +160,12 @@ export declare class Interaction {
      * deferred reply and replying are the same terminal callback.
      */
     editReply(data: string | InteractionReplyData): Promise<any>;
-    /** Extend the response window to 15 minutes; must still be followed by `update()` or `reply()`. */
+    /**
+     * Extend the response window to 15 minutes; must still be followed by
+     * `update()` or `reply()`. The invoker's client is told the bot needs
+     * more time, so a command's "thinking" row waits patiently instead of
+     * timing out at 15 seconds.
+     */
     defer(): Promise<any>;
     /**
      * Open a modal dialog for the interacting user; their submission arrives

package/dist/structures/Interaction.js

@@ -49,6 +49,7 @@ class Interaction {
             ? data.modal.fields.map((f) => ({ customId: String(f?.custom_id ?? ''), value: String(f?.value ?? '') }))
             : null;
         this.messageId = data.message_id != null ? String(data.message_id) : null;
+        this.ephemeralMessageId = data.ephemeral_message_id != null ? String(data.ephemeral_message_id) : null;
         this.channelId = String(data.channel_id ?? '');
         this.serverId = data.server_id != null ? String(data.server_id) : null;
         this.user = {
@@ -87,17 +88,22 @@ class Interaction {
         return this.kind === 'modal_submit';
     }
     /**
-     * Terminal: edit the original message (content/embeds/components).
-     * Broadcasts a normal edit. Only valid when the interaction HAS a source
-     * message — throws client-side for `kind: 'command'` and for modal submits
-     * born from a command (the server would 400).
+     * Terminal: edit the message this interaction came from
+     * (content/embeds/components). On a persisted message that's a normal
+     * edit broadcast. On an interaction born from an **ephemeral reply**
+     * (`ephemeralMessageId` set) it morphs the ephemeral panel in place —
+     * patch semantics (only the fields you send change), refreshing the
+     * panel's 15-minute window; clearing `components: []` ends the panel,
+     * and an expired panel rejects with a 404. Throws client-side for
+     * `kind: 'command'` and command-born modal submits (no source at all —
+     * the server would 400).
      */
     update(data) {
         if (this.kind === 'command') {
             throw new RangeError('update() is not valid for command interactions — there is no source message. Use reply() instead.');
         }
-        if (this.kind === 'modal_submit' && !this.messageId) {
-            throw new RangeError('update() is not valid for this modal submit — its parent interaction had no source message. Use reply() instead.');
+        if (!this.messageId && !this.ephemeralMessageId) {
+            throw new RangeError('update() is not valid for this interaction — it has no source message. Use reply() instead.');
         }
         return this.transition('responded', () => this.client.rest.interactionCallback(this.id, this.token, 'update', data));
     }
@@ -126,7 +132,12 @@ class Interaction {
     editReply(data) {
         return this.reply(data);
     }
-    /** Extend the response window to 15 minutes; must still be followed by `update()` or `reply()`. */
+    /**
+     * Extend the response window to 15 minutes; must still be followed by
+     * `update()` or `reply()`. The invoker's client is told the bot needs
+     * more time, so a command's "thinking" row waits patiently instead of
+     * timing out at 15 seconds.
+     */
     defer() {
         if (this.state !== 'pending') {
             return this.client.rest.interactionCallback(this.id, this.token, 'defer');

package/dist/structures/Message.d.ts

@@ -76,6 +76,25 @@ export interface MessageEmbed {
     timestamp: string | null;
     createdAt: Date | null;
 }
+/**
+ * Server-verified attribution on an interaction-born bot reply — who
+ * invoked the command/component that produced this message ("X used
+ * /price"). `user` is a frozen snapshot from interaction time; later
+ * renames never rewrite it. Ordinary messages carry `interaction: null`.
+ */
+export interface MessageInteraction {
+    kind: 'command' | 'button' | 'select' | 'modal_submit';
+    /** Command name — `kind: 'command'` only, `null` otherwise. */
+    name: string | null;
+    /** Component/modal custom_id — component-born interactions only, `null` otherwise. */
+    customId: string | null;
+    /** The invoking user, snapshotted at interaction time. */
+    user: {
+        id: string;
+        username: string | null;
+        displayName: string | null;
+    };
+}
 /** A frozen or live preview of the message a reference points at. */
 export interface ReferencedMessage {
     id: string;
@@ -144,6 +163,8 @@ export declare class Message {
     readonly reference: MessageReference | null;
     /** Thread badge — `null` unless this message has (or had) a thread. */
     readonly thread: MessageThread | null;
+    /** Attribution for interaction-born bot replies, or `null` (see {@link MessageInteraction}). */
+    readonly interaction: MessageInteraction | null;
     /** The raw wire payload, for anything the typed surface doesn't expose yet. */
     readonly raw: any;
     constructor(client: Client, data: any);

package/dist/structures/Message.js

@@ -123,6 +123,22 @@ class Message {
                     deletedAt: t.deleted_at ? new Date(t.deleted_at) : null,
                 }
                 : null;
+        const ix = data.interaction;
+        this.interaction =
+            ix && typeof ix === 'object'
+                ? {
+                    kind: ix.kind === 'select' || ix.kind === 'command' || ix.kind === 'modal_submit'
+                        ? ix.kind
+                        : 'button',
+                    name: ix.name != null ? String(ix.name) : null,
+                    customId: ix.custom_id != null ? String(ix.custom_id) : null,
+                    user: {
+                        id: String(ix.user?.id ?? ''),
+                        username: ix.user?.username ?? null,
+                        displayName: ix.user?.display_name ?? null,
+                    },
+                }
+                : null;
     }
     /**
      * Compat alias (discord.js-style): the id of the message this one replies

package/dist/structures/Server.d.ts

@@ -5,7 +5,7 @@ import type { FetchMembersOptions } from '../rest';
 import { ServerChannels } from './ServerChannels';
 /**
  * A server (guild) the bot belongs to. Populated from `GET /servers` on
- * connect and kept fresh by `server-meta-updated`/`server-deleted` events
+ * connect and kept fresh by `server.meta_updated`/`server.deleted` events
  * (requires `Intents.Servers`) — see `Client`'s server/channel name cache.
  */
 export declare class Server {

package/dist/structures/Server.js

@@ -4,7 +4,7 @@ exports.Server = void 0;
 const ServerChannels_1 = require("./ServerChannels");
 /**
  * A server (guild) the bot belongs to. Populated from `GET /servers` on
- * connect and kept fresh by `server-meta-updated`/`server-deleted` events
+ * connect and kept fresh by `server.meta_updated`/`server.deleted` events
  * (requires `Intents.Servers`) — see `Client`'s server/channel name cache.
  */
 class Server {

package/dist/structures/ServerChannels.d.ts

@@ -4,7 +4,7 @@ import type { Channel } from './Channel';
  * A lightweight, read-only view over the SDK's channel name cache
  * (`Client#channels`), scoped to a single server. Backed entirely by
  * whatever's currently cached — hydrated on connect and kept fresh via
- * `channel-created`/`channel-updated`/`channel-deleted` events (see
+ * `channel.created`/`channel.updated`/`channel.deleted` events (see
  * `Client#hydrateChannels`/`ensureChannel`) — **not** an authoritative,
  * always-up-to-date fetch. A brand-new channel may be briefly absent until
  * the cache catches up.

package/dist/structures/ServerChannels.js

@@ -5,7 +5,7 @@ exports.ServerChannels = void 0;
  * A lightweight, read-only view over the SDK's channel name cache
  * (`Client#channels`), scoped to a single server. Backed entirely by
  * whatever's currently cached — hydrated on connect and kept fresh via
- * `channel-created`/`channel-updated`/`channel-deleted` events (see
+ * `channel.created`/`channel.updated`/`channel.deleted` events (see
  * `Client#hydrateChannels`/`ensureChannel`) — **not** an authoritative,
  * always-up-to-date fetch. A brand-new channel may be briefly absent until
  * the cache catches up.

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.26.0";

package/dist/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+// Single source of truth for the SDK's self-reported version.
+// A test asserts this matches package.json so a bump can't drift silently
+// (the build is plain tsc with no JSON module resolution, so we can't
+// import package.json here directly).
+exports.SDK_VERSION = '0.26.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privage.js",
-  "version": "0.22.0",
+  "version": "0.26.0",
   "description": "Official SDK for building Privage bots.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",