privage.js 0.21.0

package/dist/structures/Interaction.d.ts

@@ -0,0 +1,149 @@
+import type { Client } from '../Client';
+import type { EmbedBuilder, Embed } from '../embeds';
+import type { ActionRow, ActionRowBuilder } from '../components';
+import { ModalBuilder, type Modal } from '../modals';
+/** Discriminates what the user did. Pre-v2 envelopes (no `kind`) read as `'button'`. */
+export type InteractionKind = 'button' | 'select' | 'command' | 'modal_submit';
+export interface InteractionUpdateData {
+    content?: string;
+    embeds?: (Embed | EmbedBuilder | Record<string, unknown>)[];
+    components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
+}
+export interface InteractionReplyData {
+    content?: string;
+    embeds?: (Embed | EmbedBuilder | Record<string, unknown>)[];
+    /**
+     * Only-you reply: never persisted, delivered as an event to the
+     * interacting user alone ("Only you can see this"). Valid for every
+     * interaction kind. Still terminal.
+     */
+    ephemeral?: boolean;
+    /** Components on the reply — ephemeral replies only (they render, but aren't clickable v1). */
+    components?: (ActionRow | ActionRowBuilder | Record<string, unknown>)[];
+}
+export type CommandOptionType = 'string' | 'integer' | 'number' | 'boolean' | 'user' | 'channel' | 'role';
+/** One resolved option of a slash-command invocation (already validated + coerced by the server). */
+export interface CommandInteractionOption {
+    name: string;
+    type: CommandOptionType;
+    /** string/user/channel/role → string (ids are snowflake strings); integer/number → number; boolean → boolean. */
+    value: string | number | boolean;
+}
+/** The invoked slash command on a `kind: 'command'` interaction. */
+export declare class InteractionCommand {
+    /** Registry id of the command. */
+    readonly id: string;
+    readonly name: string;
+    /** The raw options array, in schema order. */
+    readonly options: CommandInteractionOption[];
+    constructor(data: any);
+    /** The typed value of an option by name (`undefined` when the invoker omitted an optional one). */
+    getOption<T extends string | number | boolean = string | number | boolean>(name: string): T | undefined;
+}
+/** One submitted field of a modal (`kind: 'modal_submit'`). */
+export interface ModalSubmitField {
+    customId: string;
+    value: string;
+}
+/**
+ * A user interaction with the bot — a button click, select-menu choice,
+ * slash-command invocation, or modal submission (discriminated by `kind`).
+ * Respond within the window (5 min; 15 after `defer()`) with exactly one
+ * terminal callback — `update()` or `reply()` — optionally preceded by
+ * `defer()`, or open a modal with `showModal()` (pending interactions only).
+ * The token is single-use; after responding, further changes go through the
+ * normal `client.editMessage`/`client.send` APIs.
+ */
+export declare class Interaction {
+    private readonly client;
+    readonly id: string;
+    /** Single-use callback credential — treat like a secret; expires with the window. */
+    readonly token: string;
+    /** What the user did — `'button' | 'select' | 'command' | 'modal_submit'`. */
+    readonly kind: InteractionKind;
+    /**
+     * The component's custom_id (clicks), or the modal's custom_id
+     * (modal_submit), exactly as the sending bot chose it. `null` for
+     * slash commands.
+     */
+    readonly customId: string | null;
+    /** Selected option values — `kind: 'select'` only, `null` otherwise. */
+    readonly values: string[] | null;
+    /** The invoked slash command — `kind: 'command'` only, `null` otherwise. */
+    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. */
+    readonly messageId: string | null;
+    readonly channelId: string;
+    readonly serverId: string | null;
+    readonly user: {
+        id: string;
+        username: string | null;
+        displayName: string | null;
+    };
+    readonly createdAt: string;
+    /** The raw wire payload. */
+    readonly raw: any;
+    /** Client-side mirror of the server's state machine — guards `showModal()`. */
+    private state;
+    constructor(client: Client, data: any);
+    /** A submitted modal field's value by custom_id (`kind: 'modal_submit'`; `undefined` for omitted optional fields). */
+    getField(customId: string): string | undefined;
+    /** `kind === 'button'` (discord.js-style type guard). */
+    isButton(): boolean;
+    /** `kind === 'select'`. */
+    isSelect(): boolean;
+    /** discord.js alias for {@link isSelect}. */
+    isStringSelectMenu(): boolean;
+    /** `kind === 'command'`. */
+    isCommand(): boolean;
+    /** discord.js alias for {@link isCommand}. */
+    isChatInputCommand(): boolean;
+    /** `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).
+     */
+    update(data: InteractionUpdateData): Promise<any>;
+    /**
+     * Terminal: post a bot message replying to the original (a plain channel
+     * message for commands). Pass `{ ephemeral: true }` for an only-you reply
+     * that is never persisted.
+     */
+    reply(data: string | InteractionReplyData): Promise<any>;
+    /**
+     * discord.js alias for {@link defer} — extends the response window; follow
+     * with `editReply()`/`reply()`. (No flags/ephemeral options here: set
+     * `ephemeral` on the eventual reply instead.)
+     */
+    deferReply(): Promise<any>;
+    /**
+     * discord.js alias for {@link reply} — in this SDK the deferred response
+     * IS the reply (there is no placeholder message to edit), so editing the
+     * 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()`. */
+    defer(): Promise<any>;
+    /**
+     * Open a modal dialog for the interacting user; their submission arrives
+     * as a fresh `interaction` event with `kind: 'modal_submit'` (matched via
+     * the modal's custom_id).
+     *
+     * Only valid from a PENDING interaction, once: not after `defer()`, not
+     * after a terminal callback, and never in response to a modal submit — the
+     * server 400s all of these, and this method throws client-side first.
+     * Showing a modal does NOT extend the 5-minute window.
+     */
+    showModal(modal: Modal | ModalBuilder | Record<string, unknown>): Promise<any>;
+    /**
+     * Advance the state optimistically (so a concurrent second call sees it),
+     * but roll back when the wire call rejects — a transient failure must not
+     * strand the interaction in a state that blocks the legitimate retry.
+     */
+    private transition;
+}

package/dist/structures/Interaction.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Interaction = exports.InteractionCommand = void 0;
+const modals_1 = require("../modals");
+/** The invoked slash command on a `kind: 'command'` interaction. */
+class InteractionCommand {
+    constructor(data) {
+        this.id = String(data?.id ?? '');
+        this.name = String(data?.name ?? '');
+        this.options = Array.isArray(data?.options)
+            ? data.options.map((o) => ({
+                name: String(o?.name ?? ''),
+                type: (o?.type ?? 'string'),
+                value: o?.value,
+            }))
+            : [];
+    }
+    /** The typed value of an option by name (`undefined` when the invoker omitted an optional one). */
+    getOption(name) {
+        return this.options.find((o) => o.name === name)?.value;
+    }
+}
+exports.InteractionCommand = InteractionCommand;
+/**
+ * A user interaction with the bot — a button click, select-menu choice,
+ * slash-command invocation, or modal submission (discriminated by `kind`).
+ * Respond within the window (5 min; 15 after `defer()`) with exactly one
+ * terminal callback — `update()` or `reply()` — optionally preceded by
+ * `defer()`, or open a modal with `showModal()` (pending interactions only).
+ * The token is single-use; after responding, further changes go through the
+ * normal `client.editMessage`/`client.send` APIs.
+ */
+class Interaction {
+    constructor(client, data) {
+        this.client = client;
+        /** Client-side mirror of the server's state machine — guards `showModal()`. */
+        this.state = 'pending';
+        this.raw = data;
+        this.id = String(data.id ?? '');
+        this.token = String(data.token ?? '');
+        this.kind =
+            data.kind === 'select' || data.kind === 'command' || data.kind === 'modal_submit'
+                ? data.kind
+                : 'button'; // absent kind = pre-v2 payload = button
+        this.customId = data.custom_id != null ? String(data.custom_id) : null;
+        this.values = Array.isArray(data.values) ? data.values.map(String) : null;
+        this.command = data.command != null && typeof data.command === 'object' ? new InteractionCommand(data.command) : null;
+        this.fields = Array.isArray(data.modal?.fields)
+            ? 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.channelId = String(data.channel_id ?? '');
+        this.serverId = data.server_id != null ? String(data.server_id) : null;
+        this.user = {
+            id: String(data.user?.id ?? ''),
+            username: data.user?.username ?? null,
+            displayName: data.user?.display_name ?? null,
+        };
+        this.createdAt = String(data.created_at ?? '');
+    }
+    /** A submitted modal field's value by custom_id (`kind: 'modal_submit'`; `undefined` for omitted optional fields). */
+    getField(customId) {
+        return this.fields?.find((f) => f.customId === customId)?.value;
+    }
+    /** `kind === 'button'` (discord.js-style type guard). */
+    isButton() {
+        return this.kind === 'button';
+    }
+    /** `kind === 'select'`. */
+    isSelect() {
+        return this.kind === 'select';
+    }
+    /** discord.js alias for {@link isSelect}. */
+    isStringSelectMenu() {
+        return this.kind === 'select';
+    }
+    /** `kind === 'command'`. */
+    isCommand() {
+        return this.kind === 'command';
+    }
+    /** discord.js alias for {@link isCommand}. */
+    isChatInputCommand() {
+        return this.kind === 'command';
+    }
+    /** `kind === 'modal_submit'`. */
+    isModalSubmit() {
+        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).
+     */
+    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.');
+        }
+        return this.transition('responded', () => this.client.rest.interactionCallback(this.id, this.token, 'update', data));
+    }
+    /**
+     * Terminal: post a bot message replying to the original (a plain channel
+     * message for commands). Pass `{ ephemeral: true }` for an only-you reply
+     * that is never persisted.
+     */
+    reply(data) {
+        return this.transition('responded', () => this.client.rest.interactionCallback(this.id, this.token, 'reply', typeof data === 'string' ? { content: data } : data));
+    }
+    /**
+     * discord.js alias for {@link defer} — extends the response window; follow
+     * with `editReply()`/`reply()`. (No flags/ephemeral options here: set
+     * `ephemeral` on the eventual reply instead.)
+     */
+    deferReply() {
+        return this.defer();
+    }
+    /**
+     * discord.js alias for {@link reply} — in this SDK the deferred response
+     * IS the reply (there is no placeholder message to edit), so editing the
+     * deferred reply and replying are the same terminal callback.
+     */
+    editReply(data) {
+        return this.reply(data);
+    }
+    /** Extend the response window to 15 minutes; must still be followed by `update()` or `reply()`. */
+    defer() {
+        if (this.state !== 'pending') {
+            return this.client.rest.interactionCallback(this.id, this.token, 'defer');
+        }
+        return this.transition('deferred', () => this.client.rest.interactionCallback(this.id, this.token, 'defer'));
+    }
+    /**
+     * Open a modal dialog for the interacting user; their submission arrives
+     * as a fresh `interaction` event with `kind: 'modal_submit'` (matched via
+     * the modal's custom_id).
+     *
+     * Only valid from a PENDING interaction, once: not after `defer()`, not
+     * after a terminal callback, and never in response to a modal submit — the
+     * server 400s all of these, and this method throws client-side first.
+     * Showing a modal does NOT extend the 5-minute window.
+     */
+    showModal(modal) {
+        if (this.kind === 'modal_submit') {
+            throw new RangeError('showModal() is not valid in response to a modal submit — respond with reply() or update() instead.');
+        }
+        if (this.state !== 'pending') {
+            throw new RangeError(`showModal() is only valid once, from a pending interaction — not after defer(), a previous showModal(), or a terminal callback (state: ${this.state}).`);
+        }
+        const payload = modal instanceof modals_1.ModalBuilder ? modal.toJSON() : modal;
+        return this.transition('awaiting_modal', () => this.client.rest.interactionCallback(this.id, this.token, 'modal', payload));
+    }
+    /**
+     * Advance the state optimistically (so a concurrent second call sees it),
+     * but roll back when the wire call rejects — a transient failure must not
+     * strand the interaction in a state that blocks the legitimate retry.
+     */
+    transition(next, send) {
+        const prev = this.state;
+        this.state = next;
+        return send().catch((err) => {
+            if (this.state === next)
+                this.state = prev;
+            throw err;
+        });
+    }
+}
+exports.Interaction = Interaction;

package/dist/structures/Member.d.ts

@@ -0,0 +1,35 @@
+import type { Client } from '../Client';
+import type { KickBanOptions, TimeoutOptions } from '../rest';
+/** A server member, with role-management helpers. */
+export declare class Member {
+    private readonly client;
+    /** The member's user id. */
+    readonly id: string;
+    readonly username: string;
+    readonly displayName: string | null;
+    readonly avatarUrl: string | null;
+    readonly bot: boolean;
+    readonly serverId: string | null;
+    /** The raw wire payload. */
+    readonly raw: any;
+    constructor(client: Client, data: any);
+    /**
+     * Grant a role to this member. Requires the bot to have `MANAGE_ROLES`, the
+     * role to be below the bot's highest role, and its permissions to be
+     * delegatable by the bot. Rejects with `PrivagePermissionError` (403) otherwise.
+     */
+    addRole(roleId: string): Promise<any>;
+    /** Remove a role from this member. */
+    removeRole(roleId: string): Promise<any>;
+    /** Kick this member (needs KICK_MEMBERS + outrank them). */
+    kick(opts?: KickBanOptions): Promise<any>;
+    /** Ban this member (needs BAN_MEMBERS + outrank them). */
+    ban(opts?: KickBanOptions): Promise<any>;
+    /** Time out this member (needs TIMEOUT_MEMBERS). Provide `durationSeconds` or `until`. */
+    timeout(opts: TimeoutOptions): Promise<any>;
+    /** Remove this member's timeout. */
+    removeTimeout(): Promise<any>;
+    /** Set (or clear, with `null`) this member's nickname. Others need MANAGE_NICKNAMES. */
+    setNickname(nickname: string | null): Promise<any>;
+    private requireServer;
+}

package/dist/structures/Member.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Member = void 0;
+const errors_1 = require("../errors");
+/** A server member, with role-management helpers. */
+class Member {
+    constructor(client, data) {
+        this.client = client;
+        this.raw = data;
+        this.id = String(data.user_id ?? data.id ?? '');
+        this.username = data.username ?? 'unknown';
+        this.displayName = data.display_name ?? null;
+        this.avatarUrl = data.avatar_url ?? null;
+        this.bot = !!data.is_bot;
+        this.serverId = data.serverId != null ? String(data.serverId) : (data.server_id != null ? String(data.server_id) : null);
+    }
+    /**
+     * Grant a role to this member. Requires the bot to have `MANAGE_ROLES`, the
+     * role to be below the bot's highest role, and its permissions to be
+     * delegatable by the bot. Rejects with `PrivagePermissionError` (403) otherwise.
+     */
+    addRole(roleId) {
+        return this.client.addRole(this.requireServer(), this.id, roleId);
+    }
+    /** Remove a role from this member. */
+    removeRole(roleId) {
+        return this.client.removeRole(this.requireServer(), this.id, roleId);
+    }
+    /** Kick this member (needs KICK_MEMBERS + outrank them). */
+    kick(opts) {
+        return this.client.kick(this.requireServer(), this.id, opts);
+    }
+    /** Ban this member (needs BAN_MEMBERS + outrank them). */
+    ban(opts) {
+        return this.client.ban(this.requireServer(), this.id, opts);
+    }
+    /** Time out this member (needs TIMEOUT_MEMBERS). Provide `durationSeconds` or `until`. */
+    timeout(opts) {
+        return this.client.timeout(this.requireServer(), this.id, opts);
+    }
+    /** Remove this member's timeout. */
+    removeTimeout() {
+        return this.client.removeTimeout(this.requireServer(), this.id);
+    }
+    /** Set (or clear, with `null`) this member's nickname. Others need MANAGE_NICKNAMES. */
+    setNickname(nickname) {
+        return this.client.setNickname(this.requireServer(), this.id, nickname);
+    }
+    requireServer() {
+        if (!this.serverId)
+            throw new errors_1.PrivagePermissionError('Roles can only be managed on server members, not in DMs.');
+        return this.serverId;
+    }
+}
+exports.Member = Member;

package/dist/structures/Message.d.ts

@@ -0,0 +1,181 @@
+import type { Client } from '../Client';
+import type { Author } from '../types';
+import type { SendMessageOptions } from '../rest';
+import { Member } from './Member';
+import { Channel, TextChannel } from './Channel';
+import type { Server } from './Server';
+export { TextChannel };
+type Sendable = string | Omit<SendMessageOptions, 'replyTo'>;
+/**
+ * A message's thread badge — present only when a thread exists (or existed:
+ * a tombstoned thread keeps `deletedAt` set with `id: null` semantics
+ * preserved from the wire, so "deleted" is distinguishable from "never had
+ * one"). Non-thread messages carry `thread: null`.
+ */
+export interface MessageThread {
+    /** The thread channel's id (`null` on a tombstoned thread). */
+    id: string | null;
+    replyCount: number;
+    lastActivityAt: Date | null;
+    /** Set when the thread was deleted. */
+    deletedAt: Date | null;
+}
+/** A file attached to a received message (normalized from the wire row). */
+export interface MessageAttachment {
+    id: string;
+    /** Filename shown in the client. */
+    filename: string;
+    /** Download URL. */
+    url: string;
+    mimeType: string;
+    /** Size in bytes. */
+    size: number;
+    /** Image/video dimensions, when known. */
+    width: number | null;
+    height: number | null;
+    /** Renders blurred in the client until the viewer reveals it. */
+    spoiler: boolean;
+    createdAt: Date | null;
+}
+/**
+ * An embed as received on a message — the flattened STORED shape, not the
+ * nested shape you send. On persist the server flattens the nested input:
+ * `author.*` becomes `authorName`/`authorUrl`/`icon`, `image`/`thumbnail`
+ * collapse into the single `thumbnail` slot, and numeric colors are stored
+ * as hex strings. `type` is `'rich'` for bot-built embeds, `'link'` for
+ * URL unfurls.
+ */
+export interface MessageEmbed {
+    id: string;
+    type: string;
+    url: string | null;
+    title: string | null;
+    description: string | null;
+    /** Hex color string (`'#2ea043'`) — numeric colors are stored as hex. */
+    color: string | null;
+    /** The single image slot (send-side `image`/`thumbnail` collapse here). */
+    thumbnail: string | null;
+    authorName: string | null;
+    authorUrl: string | null;
+    icon: string | null;
+    siteName: string | null;
+    provider: string | null;
+    videoUrl: string | null;
+    /** Preview image/video dimensions, when known. */
+    width: number | null;
+    height: number | null;
+    fields: {
+        name: string;
+        value: string;
+        inline: boolean;
+    }[];
+    footer: {
+        text: string;
+    } | null;
+    /** The embed's own display timestamp (ISO string), if one was set. */
+    timestamp: string | null;
+    createdAt: Date | null;
+}
+/** A frozen or live preview of the message a reference points at. */
+export interface ReferencedMessage {
+    id: string;
+    content: string;
+    author: Author | null;
+    createdAt: Date | null;
+    attachments: MessageAttachment[];
+    embeds: MessageEmbed[];
+}
+/**
+ * A self-contained pointer at another message.
+ *
+ * - `reply` — resolves live (edits to the target reflect; deleted target → `message: null`).
+ * - `forward` — an anti-tamper snapshot: content/embeds/attachments are frozen
+ *   at forward time; the author stays live while the original exists.
+ * - `pin` — "X pinned a message" system rows.
+ *
+ * `message` is `undefined` when the referent wasn't resolved (e.g. edit
+ * broadcasts), `null` when it was deleted, and a preview otherwise.
+ * `channelId`/`serverId` are set only when the referent lives in another
+ * channel/server (forwards).
+ */
+export interface MessageReference {
+    type: 'reply' | 'forward' | 'pin';
+    messageId: string;
+    channelId: string | null;
+    serverId: string | null;
+    message?: ReferencedMessage | null;
+}
+/** A received message. */
+export declare class Message {
+    private readonly client;
+    readonly id: string;
+    readonly channelId: string;
+    readonly serverId: string | null;
+    readonly content: string;
+    readonly author: Author;
+    readonly createdAt: Date | null;
+    /**
+     * When the CONTENT was last edited, or `null` if never edited (the wire
+     * omits the key; the SDK normalizes to an explicit null, discord.js
+     * editedTimestamp-style). Component-only updates never set this.
+     */
+    readonly editedAt: Date | null;
+    /** Users mentioned in this message (from `mentions`). */
+    readonly mentions: {
+        id: string;
+        username: string | null;
+    }[];
+    /** Role ids mentioned in this message (from `mention_role_ids`). */
+    readonly mentionRoleIds: string[];
+    /** `true` if this message mentions `@everyone`/`@here`. */
+    readonly mentionEveryone: boolean;
+    /** Files attached to this message. */
+    readonly attachments: MessageAttachment[];
+    /** Embeds on this message — the flattened received shape (see {@link MessageEmbed}). */
+    readonly embeds: MessageEmbed[];
+    /**
+     * `true` if the message was pinned when this payload was produced.
+     * Fetched history (`fetchMessages`) carries pin state; a live
+     * `messageCreate` is always `false` (a new message can't be pinned
+     * yet). Track later changes via `messagePin` / `messageUnpin`.
+     */
+    readonly pinned: boolean;
+    /** Pointer at another message (reply/forward/pin), or `null`. */
+    readonly reference: MessageReference | null;
+    /** Thread badge — `null` unless this message has (or had) a thread. */
+    readonly thread: MessageThread | null;
+    /** The raw wire payload, for anything the typed surface doesn't expose yet. */
+    readonly raw: any;
+    constructor(client: Client, data: any);
+    /**
+     * Compat alias (discord.js-style): the id of the message this one replies
+     * to, or `null`. Derived from {@link reference} — prefer that for new code;
+     * forwards and pins are not surfaced here.
+     */
+    get replyToId(): string | null;
+    /**
+     * The channel this message was sent in. Resolved from the SDK's name
+     * cache when available (`.name` populated); falls back to a minimal
+     * handle (`.name === null`) that still supports `.send()` while the
+     * cache lazily fills in the background.
+     */
+    get channel(): Channel;
+    /** The server this message was sent in, or `null` in a DM. Resolved from the SDK's cache. */
+    get server(): Server | null;
+    /** Reply to this message (threads it via `reply_to`). */
+    reply(content: Sendable): Promise<any>;
+    /** Delete this message (needs MANAGE_MESSAGES, or it's the bot's own). */
+    delete(): Promise<any>;
+    /** React to this message. */
+    react(emoji: string): Promise<any>;
+    /** Remove the bot's own reaction from this message. */
+    removeReaction(emoji: string): Promise<any>;
+    /** Edit this message's content. Own messages only (403 otherwise). */
+    edit(content: string): Promise<any>;
+    /** Pin this message. */
+    pin(): Promise<any>;
+    /** Unpin this message. */
+    unpin(): Promise<any>;
+    /** The author as a server member (with `addRole`/`removeRole`), or null in DMs. */
+    get member(): Member | null;
+}