privage.js 0.21.0

package/dist/Client.d.ts

@@ -0,0 +1,192 @@
+import { EventEmitter } from 'events';
+import { Rest } from './rest';
+import type { KickBanOptions, TimeoutOptions, FetchMessagesOptions, FetchMembersOptions, PresenceStatus, Activity, SendMessageOptions, EditMessageOptions, CreatePollOptions, CreateWebhookOptions, EditWebhookOptions } from './rest';
+import { CommandsManager } from './commands';
+import { MessageCollector, type MessageCollectorOptions } from './collectors';
+import { Message } from './structures/Message';
+import { Member } from './structures/Member';
+import { Server } from './structures/Server';
+import { Channel } from './structures/Channel';
+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
+ * 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).
+ */
+export interface Client {
+    on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+    once<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+    off<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+    emit<K extends keyof ClientEvents>(event: K, ...args: ClientEvents[K]): boolean;
+}
+export declare class Client extends EventEmitter {
+    /** REST helper, available after `login()`. */
+    rest: Rest;
+    /** The bot's own identity, populated once connected. */
+    user: BotUser | null;
+    /**
+     * Slash-command registry — `client.commands.set([...])` bulk-overwrites,
+     * `client.commands.fetch()` lists. Use after `login()`. Invocations arrive
+     * as `interaction` events with `kind: 'command'`.
+     */
+    readonly commands: CommandsManager;
+    /**
+     * 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.
+     */
+    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`
+     * (requires `Intents.Servers`), and lazily filled on cache miss (see
+     * `ensureChannel`). Capped at {@link CHANNEL_CACHE_CAP}, oldest entries evict first.
+     */
+    readonly channels: ReadonlyMap<string, Channel>;
+    private readonly pendingChannelFetches;
+    private readonly pendingServerFetches;
+    private token;
+    private readonly api;
+    private readonly wsUrl;
+    private readonly intents;
+    private readonly debugMode;
+    private readonly streamId;
+    private socket;
+    private reconnectAttempts;
+    private reconnectPending;
+    private destroyed;
+    private connectedOnce;
+    private readyAtMs;
+    private loginResolve?;
+    private loginReject?;
+    private streamToken;
+    private resumeCursor;
+    private readonly topicCursors;
+    private readonly seen;
+    private readonly seenSet;
+    private readonly channelByMessage;
+    private readonly channelByMessageKeys;
+    constructor(options: ClientOptions);
+    /** Authenticate and connect. Resolves once the session is open (`ready`); rejects on a fatal auth error. */
+    login(token: string): Promise<void>;
+    /**
+     * True once `ready` has fired. Stays true across reconnects — it means
+     * "ready happened", not "currently connected" (discord.js semantics).
+     */
+    isReady(): boolean;
+    /** When `ready` fired, or `null` before login completes. */
+    get readyAt(): Date | null;
+    /** Epoch-ms twin of {@link readyAt}. */
+    get readyTimestamp(): number | null;
+    /** Milliseconds since `ready`, or `null` before login completes. */
+    get uptime(): number | null;
+    /** Disconnect and stop reconnecting. */
+    destroy(): void;
+    /** 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: string, userId: string, roleId: string): Promise<any>;
+    /** Remove a role from a member. */
+    removeRole(serverId: string, userId: string, roleId: string): Promise<any>;
+    /** Kick a member (needs KICK_MEMBERS). */
+    kick(serverId: string, userId: string, opts?: KickBanOptions): Promise<any>;
+    /** Ban a member (needs BAN_MEMBERS). */
+    ban(serverId: string, userId: string, opts?: KickBanOptions): Promise<any>;
+    /** Lift a ban. */
+    unban(serverId: string, userId: string): Promise<any>;
+    /** Time out a member (needs TIMEOUT_MEMBERS). */
+    timeout(serverId: string, userId: string, opts: TimeoutOptions): Promise<any>;
+    /** Remove a member's timeout. */
+    removeTimeout(serverId: string, userId: string): Promise<any>;
+    /** Delete a message (needs MANAGE_MESSAGES, or the bot's own message). */
+    deleteMessage(messageId: string): Promise<any>;
+    /** Send a message to a channel by id — no server id needed. */
+    send(channelId: string, content: string | Omit<SendMessageOptions, 'replyTo'>): Promise<any>;
+    /** React to a message. */
+    react(messageId: string, emoji: string): Promise<any>;
+    /** Remove the bot's own reaction from a message. */
+    removeReaction(messageId: string, emoji: string): Promise<any>;
+    /** Create a poll in a channel (needs send permission there). Limits: question ≤500, 2–6 unique options ≤200, deadline ≤7 days. */
+    createPoll(channelId: string, opts: CreatePollOptions): Promise<any>;
+    /** Close a poll early (creator or MANAGE_MESSAGES). A `pollClose` event follows. */
+    closePoll(pollId: string): Promise<any>;
+    /** Create a webhook on a text/announcement channel (needs MANAGE_WEBHOOKS). Response carries the webhook token. */
+    createWebhook(channelId: string, opts?: CreateWebhookOptions): Promise<any>;
+    /** List a channel's webhooks. */
+    fetchChannelWebhooks(channelId: string): Promise<any>;
+    /** List a server's webhooks. */
+    fetchServerWebhooks(serverId: string): Promise<any>;
+    /** Rename a webhook / change its avatar (`avatarUrl: null` clears). */
+    editWebhook(webhookId: string, opts: EditWebhookOptions): Promise<any>;
+    /** Delete a webhook. */
+    deleteWebhook(webhookId: string): Promise<any>;
+    /** Rotate a webhook's token — the old one stops working immediately. */
+    rotateWebhookToken(webhookId: string): Promise<any>;
+    /** Collect messages matching a filter until a count/time limit — see MessageCollector. */
+    createMessageCollector(options?: MessageCollectorOptions): MessageCollector;
+    /** Promise form of a collector: resolves with collected messages (default max 1, 60s). */
+    awaitMessages(options?: MessageCollectorOptions): Promise<Message[]>;
+    /** Set the bot's presence status ('online' | 'idle' | 'dnd' | 'offline'). */
+    setStatus(status: PresenceStatus): Promise<any>;
+    /** Set the bot's rich-presence activity (shows on the profile/member list). */
+    setActivity(activity: Activity): Promise<any>;
+    /** Clear the bot's rich-presence activity. */
+    clearActivity(): Promise<any>;
+    /** Edit a message's content. Own messages only (403 otherwise). */
+    editMessage(messageId: string, content: string | EditMessageOptions): Promise<any>;
+    /** Pin a message. */
+    pinMessage(messageId: string): Promise<any>;
+    /** Unpin a message. */
+    unpinMessage(messageId: string): Promise<any>;
+    /** Fetch a channel's message history. */
+    fetchMessages(channelId: string, opts?: FetchMessagesOptions): Promise<Message[]>;
+    /** List a server's members. */
+    fetchMembers(serverId: string, opts?: FetchMembersOptions): Promise<Member[]>;
+    /** List a server's roles. */
+    fetchRoles(serverId: string): Promise<Role[]>;
+    /** Set (or clear, with `null`) a member's nickname. Others need MANAGE_NICKNAMES. */
+    setNickname(serverId: string, userId: string, nickname: string | null): Promise<any>;
+    private debug;
+    private warn;
+    private isFatal;
+    private scheduleReconnect;
+    private connect;
+    private handshake;
+    /** `GET /servers` → populate the server cache. Best-effort — never fatal. */
+    private hydrateServers;
+    /**
+     * 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.
+     */
+    private hydrateChannels;
+    /**
+     * 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: string, serverId?: string | null): void;
+    /** Best-effort fill for a server discovered via a lazily-resolved channel. */
+    private ensureServer;
+    /** Cache-maintenance for structure events. Cache-only — never emits new SDK events. */
+    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 restCatchup;
+    private handleEvent;
+    private advanceCursors;
+    private topicOf;
+    private dispatchMessage;
+    private rememberChannel;
+    private safeEmit;
+    private remember;
+}