privage.js 0.21.0

package/dist/rest.d.ts

@@ -0,0 +1,208 @@
+import type { Embed, EmbedBuilder } from './embeds';
+import type { ActionRow, ActionRowBuilder } from './components';
+import { type AttachmentBuilder, type AttachmentSource } from './attachments';
+export interface SendMessageOptions {
+    content?: string;
+    /** Bot-only. Accepts plain wire objects or `EmbedBuilder`s (max 10). */
+    embeds?: (Embed | EmbedBuilder | Record<string, unknown>)[];
+    /**
+     * File attachments — `AttachmentBuilder`s, paths, raw bytes, or Blobs
+     * (max 10, 25 MB each by default). Cannot be combined with `embeds` or
+     * `components` (v1).
+     */
+    files?: (AttachmentBuilder | AttachmentSource)[];
+    /** Bot-only. Button rows — plain wire objects or `ActionRowBuilder`s (max 5 rows). */
+    components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
+    replyTo?: string;
+    nonce?: string;
+}
+export interface EditMessageOptions {
+    content?: string;
+    /** Replace the message's button rows (bot's own messages). */
+    components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
+}
+/** Server limits: question ≤500 chars; 2–6 unique options ≤200 chars each; deadline within 7 days. */
+export interface CreatePollOptions {
+    question: string;
+    options: string[];
+    /** When voting closes — Date, epoch ms, or ISO string. Required, ≤7 days out. */
+    deadline: Date | number | string;
+    nonce?: string;
+}
+export interface CreateWebhookOptions {
+    /** Display name (defaults to 'Webhook'). */
+    name?: string;
+    avatarUrl?: string;
+}
+export interface EditWebhookOptions {
+    name?: string;
+    /** `null` clears the avatar. */
+    avatarUrl?: string | null;
+}
+export type PresenceStatus = 'online' | 'idle' | 'dnd' | 'offline';
+/** Rich-presence activity types (server-validated). */
+export declare enum ActivityType {
+    Playing = 0,
+    Listening = 2,
+    Watching = 3,
+    Custom = 4,
+    Competing = 5
+}
+export interface Activity {
+    type: ActivityType | number;
+    /** Required, ≤128 chars. */
+    name: string;
+    /** Optional, ≤128 chars. */
+    details?: string;
+    /** Optional, ≤128 chars. */
+    state?: string;
+    timestamps?: {
+        start?: number;
+        end?: number;
+    };
+}
+export interface FetchMessagesOptions {
+    /** Max messages to return (≤100, default 30). */
+    limit?: number;
+    /** ISO timestamp — messages before this point. */
+    before?: string;
+    beforeId?: string;
+    /** ISO timestamp — messages after this point. */
+    after?: string;
+    afterId?: string;
+    around?: string;
+}
+export interface FetchMembersOptions {
+    /** Max members to return (≤500, default 200). */
+    limit?: number;
+    offset?: number;
+}
+export interface KickBanOptions {
+    reason?: string;
+    /** Also delete the member's recent message history. */
+    deleteHistory?: boolean;
+}
+export interface TimeoutOptions {
+    /** How long to time out for, in seconds. */
+    durationSeconds?: number;
+    /** Or an absolute end time (mutually exclusive with `durationSeconds`). */
+    until?: Date;
+    reason?: string;
+}
+/**
+ * Thin REST client. Every call authenticates with `Authorization: Bot <token>`
+ * and maps non-2xx responses to the typed error taxonomy.
+ */
+export declare class Rest {
+    private readonly api;
+    private token;
+    constructor(opts: {
+        api: string;
+        token: string;
+    });
+    setToken(token: string): void;
+    request<T = any>(path: string, init?: {
+        method?: string;
+        body?: unknown;
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** Same as `request`, but retries a 429 (up to {@link REST_MAX_ATTEMPTS} total attempts). */
+    private requestAttempt;
+    get<T = any>(path: string): Promise<T>;
+    private buildQuery;
+    /**
+     * POST /api/messages/:channelId — `embeds` is bot-only; slowmode + rate
+     * limits apply. Response: `{ success, message }` (201) — `message` is the
+     * full message object, for both the JSON and multipart branches.
+     */
+    sendMessage(channelId: string, data: SendMessageOptions): Promise<any>;
+    /**
+     * Respond to an interaction. `type`: 'update' (terminal — edit the
+     * original message), 'reply' (terminal — post a reply; `data.ephemeral:
+     * true` for an only-you reply), 'defer' (extend the window; a terminal
+     * callback must follow), or 'modal' (open a modal — pending interactions
+     * only, once). Response: `{ success, message }` for update/reply (an
+     * ephemeral reply's `message` is a reduced, never-persisted object);
+     * defer/modal are 204s and resolve `null`.
+     */
+    interactionCallback(interactionId: string, token: string, type: 'update' | 'reply' | 'defer' | 'modal', data?: object): Promise<any>;
+    /** PUT /api/bots/commands — bulk overwrite the bot's slash commands (whole-or-400). Response: `{ success, commands }`. */
+    setCommands(commands: object[]): Promise<any>;
+    /** GET /api/bots/commands — list the bot's registered slash commands. Response: `{ success, commands }`. */
+    fetchCommands(): Promise<any>;
+    /** PUT — grant a role to a member. Needs MANAGE_ROLES + role below the bot's highest. Response: `{ success, message: string }`. */
+    addRole(serverId: string, userId: string, roleId: string): Promise<any>;
+    /** DELETE — remove a role from a member. Response: `{ success, message: string }`. */
+    removeRole(serverId: string, userId: string, roleId: string): Promise<any>;
+    /** Kick a member (needs KICK_MEMBERS + outrank the target). Response: `{ success, message: string }`. */
+    kickMember(serverId: string, userId: string, opts?: KickBanOptions): Promise<any>;
+    /** Ban a member (needs BAN_MEMBERS + outrank the target). Response: `{ success, message: string }`. */
+    banMember(serverId: string, userId: string, opts?: KickBanOptions): Promise<any>;
+    /** Lift a ban. Response: `{ success, message: string }`. */
+    unbanMember(serverId: string, userId: string): Promise<any>;
+    /** Time out (temporarily mute) a member (needs TIMEOUT_MEMBERS). Provide `durationSeconds` or `until`. Response: `{ success, timeout_until }`. */
+    timeoutMember(serverId: string, userId: string, opts: TimeoutOptions): Promise<any>;
+    /** Remove an active timeout. Response: `{ success }`. */
+    removeTimeout(serverId: string, userId: string): Promise<any>;
+    /** Delete a message (needs MANAGE_MESSAGES, or the bot's own message). Response: `{ success, message: string }`. */
+    deleteMessage(messageId: string): Promise<any>;
+    /** Add a reaction (the emoji is URL-path encoded). Response: `{ success, reactions, version }`. */
+    react(messageId: string, emoji: string): Promise<any>;
+    /** Remove the bot's own reaction. Response: `{ success, reactions, version }`. */
+    removeReaction(messageId: string, emoji: string): Promise<any>;
+    /**
+     * Create a poll in a channel (posts a poll message). Needs send
+     * permission there; poll creation is rate-limited (~10/min).
+     * Response: `{ success, message }` (201) — `message.poll` carries the
+     * poll state (question, options with counts, deadline, version).
+     */
+    createPoll(channelId: string, opts: CreatePollOptions): Promise<any>;
+    /** Close a poll early. Creator or `MANAGE_MESSAGES`. Response: `{ success, version }` — deliberately lean, no poll/message included. */
+    closePoll(pollId: string): Promise<any>;
+    /** Create a webhook on a text/announcement channel (needs MANAGE_WEBHOOKS). Response: `{ success, webhook }` (201) — `webhook.token` is returned here and on the list routes. */
+    createWebhook(channelId: string, opts?: CreateWebhookOptions): Promise<any>;
+    /** List a channel's webhooks. Response: `{ success, webhooks }`. */
+    fetchChannelWebhooks(channelId: string): Promise<any>;
+    /** List a server's webhooks. Response: `{ success, webhooks }`. */
+    fetchServerWebhooks(serverId: string): Promise<any>;
+    /** Rename a webhook / change its avatar (`avatarUrl: null` clears it). Response: `{ success, webhook }`. */
+    editWebhook(webhookId: string, opts: EditWebhookOptions): Promise<any>;
+    /** Delete a webhook. Response: 204 — resolves `null`. */
+    deleteWebhook(webhookId: string): Promise<any>;
+    /** Rotate a webhook's token (the old one stops working). Response: `{ success, token }`. */
+    rotateWebhookToken(webhookId: string): Promise<any>;
+    /** Set the bot's presence status. Response: `{ success, status }` — the effective status. */
+    setStatus(status: PresenceStatus): Promise<any>;
+    /** Set the bot's rich-presence activity. Response: `{ success, activities }`. */
+    setActivity(activity: Activity): Promise<any>;
+    /** Clear the bot's rich-presence activity. Response: `{ success, activities }` (now empty). */
+    clearActivity(): Promise<any>;
+    /** Edit a message's content and/or components. Own messages only (403 otherwise). Response: `{ success, message }`. */
+    editMessage(messageId: string, contentOrOpts: string | EditMessageOptions): Promise<any>;
+    /** Pin a message. Response: `{ success, message: string }`. */
+    pinMessage(messageId: string): Promise<any>;
+    /** Unpin a message. Response: `{ success, message: string }`. */
+    unpinMessage(messageId: string): Promise<any>;
+    /**
+     * Fetch a channel's message history. Response: `{ success, messages,
+     * hasMore }` — plus `hasMoreBefore`/`hasMoreAfter` when `around` is used.
+     */
+    fetchMessages(channelId: string, opts?: FetchMessagesOptions): Promise<{
+        messages: any[];
+        hasMore: boolean;
+        hasMoreBefore?: boolean;
+        hasMoreAfter?: boolean;
+    }>;
+    /** List a server's members. Response: `{ success, members }`. */
+    fetchMembers(serverId: string, opts?: FetchMembersOptions): Promise<{
+        members: any[];
+    }>;
+    /** List a server's roles. Response: `{ success, roles, PERMISSIONS }` — `PERMISSIONS` maps permission names to bits. */
+    fetchRoles(serverId: string): Promise<{
+        roles: any[];
+        PERMISSIONS: Record<string, number>;
+    }>;
+    /** Set (or clear, with `null`) a member's nickname. Others need MANAGE_NICKNAMES. Response: `{ success, nickname }`. */
+    setNickname(serverId: string, userId: string, nickname: string | null): Promise<any>;
+    private toError;
+}

package/dist/rest.js

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rest = exports.ActivityType = void 0;
+const crypto_1 = require("crypto");
+const errors_1 = require("./errors");
+const attachments_1 = require("./attachments");
+const REST_TIMEOUT_MS = 15000;
+// 429 auto-retry: at most 3 total attempts (1 original + 2 retries), waiting
+// the server's `retryAfter` between them (floored so a 0/near-0 value from a
+// buggy limiter still backs off a little).
+const REST_MAX_ATTEMPTS = 3;
+const REST_MIN_RETRY_MS = 250;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Rich-presence activity types (server-validated). */
+var ActivityType;
+(function (ActivityType) {
+    ActivityType[ActivityType["Playing"] = 0] = "Playing";
+    ActivityType[ActivityType["Listening"] = 2] = "Listening";
+    ActivityType[ActivityType["Watching"] = 3] = "Watching";
+    ActivityType[ActivityType["Custom"] = 4] = "Custom";
+    ActivityType[ActivityType["Competing"] = 5] = "Competing";
+})(ActivityType || (exports.ActivityType = ActivityType = {}));
+function kickBanBody(opts) {
+    if (opts.reason == null && opts.deleteHistory == null)
+        return undefined;
+    const body = {};
+    if (opts.reason != null)
+        body.reason = opts.reason;
+    if (opts.deleteHistory != null)
+        body.delete_history = opts.deleteHistory;
+    return body;
+}
+/**
+ * Thin REST client. Every call authenticates with `Authorization: Bot <token>`
+ * and maps non-2xx responses to the typed error taxonomy.
+ */
+class Rest {
+    constructor(opts) {
+        this.api = opts.api;
+        this.token = opts.token;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    request(path, init = {}) {
+        return this.requestAttempt(path, init, 1);
+    }
+    /** Same as `request`, but retries a 429 (up to {@link REST_MAX_ATTEMPTS} total attempts). */
+    async requestAttempt(path, init, attempt) {
+        // FormData bodies pass through untouched — fetch sets the multipart
+        // boundary itself, so Content-Type must NOT be set manually.
+        const isForm = typeof FormData !== 'undefined' && init.body instanceof FormData;
+        let res;
+        try {
+            res = await fetch(`${this.api}/api${path}`, {
+                method: init.method || 'GET',
+                headers: {
+                    Authorization: `Bot ${this.token}`,
+                    ...(isForm ? {} : { 'Content-Type': 'application/json' }),
+                },
+                body: isForm
+                    ? init.body
+                    : init.body != null
+                        ? JSON.stringify(init.body)
+                        : undefined,
+                // A hung request must never stall the caller (e.g. hydration blocking `ready`).
+                signal: AbortSignal.timeout(init.timeoutMs ?? REST_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            const why = e?.name === 'TimeoutError' ? `timed out after ${REST_TIMEOUT_MS}ms` : (e?.message || 'network error');
+            throw new errors_1.PrivageConnectionError(`${path} -> ${why}`);
+        }
+        const json = await res.json().catch(() => null);
+        if (!res.ok) {
+            const err = this.toError(res.status, json, path, res.headers.get('retry-after'));
+            if (err instanceof errors_1.PrivageRateLimitError && attempt < REST_MAX_ATTEMPTS) {
+                await sleep(Math.max(err.retryAfter, REST_MIN_RETRY_MS));
+                return this.requestAttempt(path, init, attempt + 1);
+            }
+            throw err;
+        }
+        return json;
+    }
+    get(path) {
+        return this.request(path);
+    }
+    buildQuery(params) {
+        const usp = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value != null)
+                usp.set(key, String(value));
+        }
+        const qs = usp.toString();
+        return qs ? `?${qs}` : '';
+    }
+    /**
+     * POST /api/messages/:channelId — `embeds` is bot-only; slowmode + rate
+     * limits apply. Response: `{ success, message }` (201) — `message` is the
+     * full message object, for both the JSON and multipart branches.
+     */
+    async sendMessage(channelId, data) {
+        const nonce = data.nonce ?? (0, crypto_1.randomUUID)();
+        if (data.files?.length) {
+            // The multipart branch server-side does not parse embeds/components —
+            // fail loud instead of silently dropping them.
+            if (data.embeds?.length || data.components?.length) {
+                throw new RangeError('Attachments cannot be combined with embeds or components in one message (v1) — send them separately.');
+            }
+            if (data.files.length > 10) {
+                throw new RangeError(`At most 10 attachments per message (got ${data.files.length}).`);
+            }
+            const form = new FormData();
+            form.append('content', data.content ?? '');
+            form.append('nonce', nonce);
+            if (data.replyTo)
+                form.append('reply_to', data.replyTo);
+            const parts = await (0, attachments_1.resolveFiles)(data.files);
+            for (const { blob, name } of parts) {
+                form.append('files', blob, name);
+            }
+            // Per-file spoiler flags ride as a JSON boolean array aligned with the
+            // multipart file order; omitted entirely when nothing is a spoiler.
+            if (parts.some((p) => p.spoiler)) {
+                form.append('attachment_spoilers', JSON.stringify(parts.map((p) => p.spoiler)));
+            }
+            // Uploads get a longer budget than ordinary REST calls.
+            return this.request(`/messages/${channelId}`, { method: 'POST', body: form, timeoutMs: 60000 });
+        }
+        const body = {
+            content: data.content ?? '',
+            nonce,
+        };
+        if (data.embeds)
+            body.embeds = data.embeds;
+        if (data.components)
+            body.components = data.components;
+        if (data.replyTo)
+            body.reply_to = data.replyTo;
+        return this.request(`/messages/${channelId}`, { method: 'POST', body });
+    }
+    /**
+     * Respond to an interaction. `type`: 'update' (terminal — edit the
+     * original message), 'reply' (terminal — post a reply; `data.ephemeral:
+     * true` for an only-you reply), 'defer' (extend the window; a terminal
+     * callback must follow), or 'modal' (open a modal — pending interactions
+     * only, once). Response: `{ success, message }` for update/reply (an
+     * ephemeral reply's `message` is a reduced, never-persisted object);
+     * defer/modal are 204s and resolve `null`.
+     */
+    interactionCallback(interactionId, token, type, data) {
+        return this.request(`/interactions/${interactionId}/${encodeURIComponent(token)}/callback`, { method: 'POST', body: data === undefined ? { type } : { type, data } });
+    }
+    /** PUT /api/bots/commands — bulk overwrite the bot's slash commands (whole-or-400). Response: `{ success, commands }`. */
+    setCommands(commands) {
+        return this.request('/bots/commands', { method: 'PUT', body: { commands } });
+    }
+    /** GET /api/bots/commands — list the bot's registered slash commands. Response: `{ success, commands }`. */
+    fetchCommands() {
+        return this.request('/bots/commands');
+    }
+    /** PUT — grant a role to a member. Needs MANAGE_ROLES + role below the bot's highest. Response: `{ success, message: string }`. */
+    addRole(serverId, userId, roleId) {
+        return this.request(`/servers/${serverId}/members/${userId}/roles/${roleId}`, { method: 'PUT' });
+    }
+    /** DELETE — remove a role from a member. Response: `{ success, message: string }`. */
+    removeRole(serverId, userId, roleId) {
+        return this.request(`/servers/${serverId}/members/${userId}/roles/${roleId}`, { method: 'DELETE' });
+    }
+    /** Kick a member (needs KICK_MEMBERS + outrank the target). Response: `{ success, message: string }`. */
+    kickMember(serverId, userId, opts = {}) {
+        return this.request(`/servers/${serverId}/members/${userId}`, { method: 'DELETE', body: kickBanBody(opts) });
+    }
+    /** Ban a member (needs BAN_MEMBERS + outrank the target). Response: `{ success, message: string }`. */
+    banMember(serverId, userId, opts = {}) {
+        return this.request(`/servers/${serverId}/bans/${userId}`, { method: 'POST', body: kickBanBody(opts) ?? {} });
+    }
+    /** Lift a ban. Response: `{ success, message: string }`. */
+    unbanMember(serverId, userId) {
+        return this.request(`/servers/${serverId}/bans/${userId}`, { method: 'DELETE' });
+    }
+    /** Time out (temporarily mute) a member (needs TIMEOUT_MEMBERS). Provide `durationSeconds` or `until`. Response: `{ success, timeout_until }`. */
+    timeoutMember(serverId, userId, opts) {
+        const body = {};
+        if (opts.durationSeconds != null)
+            body.duration_seconds = opts.durationSeconds;
+        if (opts.until != null)
+            body.timeout_until = opts.until.toISOString();
+        if (opts.reason != null)
+            body.reason = opts.reason;
+        return this.request(`/servers/${serverId}/members/${userId}/timeout`, { method: 'POST', body });
+    }
+    /** Remove an active timeout. Response: `{ success }`. */
+    removeTimeout(serverId, userId) {
+        return this.request(`/servers/${serverId}/members/${userId}/timeout`, { method: 'DELETE' });
+    }
+    /** Delete a message (needs MANAGE_MESSAGES, or the bot's own message). Response: `{ success, message: string }`. */
+    deleteMessage(messageId) {
+        return this.request(`/messages/${messageId}`, { method: 'DELETE' });
+    }
+    /** Add a reaction (the emoji is URL-path encoded). Response: `{ success, reactions, version }`. */
+    react(messageId, emoji) {
+        return this.request(`/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`, { method: 'PUT' });
+    }
+    /** Remove the bot's own reaction. Response: `{ success, reactions, version }`. */
+    removeReaction(messageId, emoji) {
+        return this.request(`/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`, { method: 'DELETE' });
+    }
+    /**
+     * Create a poll in a channel (posts a poll message). Needs send
+     * permission there; poll creation is rate-limited (~10/min).
+     * Response: `{ success, message }` (201) — `message.poll` carries the
+     * poll state (question, options with counts, deadline, version).
+     */
+    createPoll(channelId, opts) {
+        // Mirror the server's validation but fail loud and local.
+        const question = String(opts.question ?? '').trim();
+        if (!question)
+            throw new RangeError('Poll question is required.');
+        if (question.length > 500)
+            throw new RangeError(`Poll question exceeds 500 characters (got ${question.length}).`);
+        const options = (opts.options ?? []).map((o) => String(o).trim());
+        if (options.length < 2 || options.length > 6)
+            throw new RangeError(`Polls need 2–6 options (got ${options.length}).`);
+        if (options.some((o) => !o))
+            throw new RangeError('Poll options must be non-empty.');
+        if (options.some((o) => o.length > 200))
+            throw new RangeError('Poll options are limited to 200 characters each.');
+        if (new Set(options.map((o) => o.toLowerCase())).size !== options.length)
+            throw new RangeError('Poll options must be unique.');
+        const deadline = new Date(opts.deadline);
+        if (isNaN(deadline.getTime()))
+            throw new RangeError('Poll deadline is not a valid date.');
+        if (deadline.getTime() <= Date.now())
+            throw new RangeError('Poll deadline must be in the future.');
+        if (deadline.getTime() - Date.now() > 7 * 24 * 60 * 60 * 1000)
+            throw new RangeError('Poll deadline must be within 7 days.');
+        return this.request('/polls', {
+            method: 'POST',
+            body: {
+                channelId,
+                question,
+                options,
+                deadline: deadline.toISOString(),
+                nonce: opts.nonce ?? (0, crypto_1.randomUUID)(),
+            },
+        });
+    }
+    /** Close a poll early. Creator or `MANAGE_MESSAGES`. Response: `{ success, version }` — deliberately lean, no poll/message included. */
+    closePoll(pollId) {
+        return this.request(`/polls/${pollId}/close`, { method: 'POST' });
+    }
+    /** Create a webhook on a text/announcement channel (needs MANAGE_WEBHOOKS). Response: `{ success, webhook }` (201) — `webhook.token` is returned here and on the list routes. */
+    createWebhook(channelId, opts = {}) {
+        return this.request('/webhooks', {
+            method: 'POST',
+            body: { channelId, name: opts.name, avatar_url: opts.avatarUrl },
+        });
+    }
+    /** List a channel's webhooks. Response: `{ success, webhooks }`. */
+    fetchChannelWebhooks(channelId) {
+        return this.request(`/webhooks/channel/${channelId}`);
+    }
+    /** List a server's webhooks. Response: `{ success, webhooks }`. */
+    fetchServerWebhooks(serverId) {
+        return this.request(`/webhooks/server/${serverId}`);
+    }
+    /** Rename a webhook / change its avatar (`avatarUrl: null` clears it). Response: `{ success, webhook }`. */
+    editWebhook(webhookId, opts) {
+        const body = {};
+        if (opts.name !== undefined)
+            body.name = opts.name;
+        if (opts.avatarUrl !== undefined)
+            body.avatar_url = opts.avatarUrl;
+        return this.request(`/webhooks/${webhookId}`, { method: 'PATCH', body });
+    }
+    /** Delete a webhook. Response: 204 — resolves `null`. */
+    deleteWebhook(webhookId) {
+        return this.request(`/webhooks/${webhookId}`, { method: 'DELETE' });
+    }
+    /** Rotate a webhook's token (the old one stops working). Response: `{ success, token }`. */
+    rotateWebhookToken(webhookId) {
+        return this.request(`/webhooks/${webhookId}/token`, { method: 'POST' });
+    }
+    /** Set the bot's presence status. Response: `{ success, status }` — the effective status. */
+    setStatus(status) {
+        return this.request('/users/me/status', { method: 'PATCH', body: { status } });
+    }
+    /** Set the bot's rich-presence activity. Response: `{ success, activities }`. */
+    setActivity(activity) {
+        return this.request('/users/me/activities', { method: 'PUT', body: activity });
+    }
+    /** Clear the bot's rich-presence activity. Response: `{ success, activities }` (now empty). */
+    clearActivity() {
+        return this.request('/users/me/activities', { method: 'DELETE' });
+    }
+    /** Edit a message's content and/or components. Own messages only (403 otherwise). Response: `{ success, message }`. */
+    editMessage(messageId, contentOrOpts) {
+        const opts = typeof contentOrOpts === 'string' ? { content: contentOrOpts } : contentOrOpts;
+        const body = {};
+        if (opts.content !== undefined)
+            body.content = opts.content;
+        if (opts.components !== undefined)
+            body.components = opts.components;
+        return this.request(`/messages/${messageId}`, { method: 'PATCH', body });
+    }
+    /** Pin a message. Response: `{ success, message: string }`. */
+    pinMessage(messageId) {
+        return this.request(`/messages/${messageId}/pin`, { method: 'POST' });
+    }
+    /** Unpin a message. Response: `{ success, message: string }`. */
+    unpinMessage(messageId) {
+        return this.request(`/messages/${messageId}/pin`, { method: 'DELETE' });
+    }
+    /**
+     * Fetch a channel's message history. Response: `{ success, messages,
+     * hasMore }` — plus `hasMoreBefore`/`hasMoreAfter` when `around` is used.
+     */
+    fetchMessages(channelId, opts = {}) {
+        const qs = this.buildQuery({
+            limit: opts.limit,
+            before: opts.before,
+            before_id: opts.beforeId,
+            after: opts.after,
+            after_id: opts.afterId,
+            around: opts.around,
+        });
+        return this.request(`/messages/${channelId}${qs}`);
+    }
+    /** List a server's members. Response: `{ success, members }`. */
+    fetchMembers(serverId, opts = {}) {
+        const qs = this.buildQuery({ limit: opts.limit, offset: opts.offset });
+        return this.request(`/servers/${serverId}/members${qs}`);
+    }
+    /** List a server's roles. Response: `{ success, roles, PERMISSIONS }` — `PERMISSIONS` maps permission names to bits. */
+    fetchRoles(serverId) {
+        return this.request(`/servers/${serverId}/roles`);
+    }
+    /** Set (or clear, with `null`) a member's nickname. Others need MANAGE_NICKNAMES. Response: `{ success, nickname }`. */
+    setNickname(serverId, userId, nickname) {
+        return this.request(`/servers/${serverId}/nicknames/${userId}`, { method: 'PUT', body: { nickname } });
+    }
+    toError(status, body, path, retryAfter) {
+        const msg = `${path} -> ${status} ${JSON.stringify(body)}`;
+        if (status === 401)
+            return new errors_1.PrivageAuthError(msg);
+        if (status === 403)
+            return new errors_1.PrivagePermissionError(msg);
+        if (status === 429)
+            return new errors_1.PrivageRateLimitError(msg, (Number(retryAfter) || 0) * 1000);
+        return new errors_1.PrivageHTTPError(msg, status, body);
+    }
+}
+exports.Rest = Rest;

package/dist/structures/Channel.d.ts

@@ -0,0 +1,25 @@
+import type { Client } from '../Client';
+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
+ * lazily filled on cache miss (see `Client#ensureChannel`). A channel handed
+ * out before it's resolved has `name: null`; it still works for `send`.
+ */
+export declare class Channel {
+    private readonly client;
+    readonly id: string;
+    readonly name: string | null;
+    readonly type: string | null;
+    readonly serverId: string | null;
+    readonly categoryId: string | null;
+    /** The raw wire/REST payload, for anything the typed surface doesn't expose yet. */
+    readonly raw: any;
+    constructor(client: Client, data: any);
+    /** Send a message to this channel. */
+    send(content: Sendable): Promise<any>;
+}
+/** @deprecated Alias of `Channel`, kept for backwards compatibility. */
+export { Channel as TextChannel };

package/dist/structures/Channel.js

@@ -0,0 +1,34 @@
+"use strict";
+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
+ * lazily filled on cache miss (see `Client#ensureChannel`). A channel handed
+ * out before it's resolved has `name: null`; it still works for `send`.
+ */
+class Channel {
+    constructor(client, data) {
+        this.client = client;
+        this.raw = data;
+        this.id = String(data.id ?? data._id ?? '');
+        this.name = data.name ?? null;
+        this.type = data.type ?? null;
+        this.serverId =
+            data.server_id != null ? String(data.server_id) : data.serverId != null ? String(data.serverId) : null;
+        this.categoryId =
+            data.category_id != null
+                ? String(data.category_id)
+                : data.categoryId != null
+                    ? String(data.categoryId)
+                    : null;
+    }
+    /** Send a message to this channel. */
+    send(content) {
+        const data = typeof content === 'string' ? { content } : content;
+        return this.client.rest.sendMessage(this.id, data);
+    }
+}
+exports.Channel = Channel;
+exports.TextChannel = Channel;