@fluxerjs/core 1.0.5 → 1.0.7

package/dist/index.d.mts

@@ -1,63 +1,28 @@
+import { Collection } from '@fluxerjs/collection';
 import * as _fluxerjs_types from '@fluxerjs/types';
-import { APIUserPartial, APIMessageAttachment, APIMessage, APIEmbed, APIWebhook, ChannelType, APIChannelPartial, APIChannel, APIGuild, APIGuildMember, GatewayPresenceUpdateData, GatewaySendPayload, Routes, GatewayMessageReactionAddDispatchData, GatewayMessageReactionRemoveDispatchData, GatewayMessageReactionRemoveAllDispatchData, GatewayMessageReactionRemoveEmojiDispatchData, GatewayVoiceStateUpdateDispatchData, GatewayVoiceServerUpdateDispatchData } from '@fluxerjs/types';
+import { APIWebhook, APIChannelPartial, ChannelType, APIChannel, APIMessageAttachment, APIMessage, APIEmbed, APIUserPartial, APIGuild, APIGuildMember, GatewayPresenceUpdateData, GatewaySendPayload, Routes, GatewayMessageReactionAddDispatchData, GatewayMessageReactionRemoveDispatchData, GatewayMessageReactionRemoveAllDispatchData, GatewayMessageReactionRemoveEmojiDispatchData, GatewayVoiceStateUpdateDispatchData, GatewayVoiceServerUpdateDispatchData } from '@fluxerjs/types';
 export { GatewayOpcodes, Routes } from '@fluxerjs/types';
-import { Collection } from '@fluxerjs/collection';
+import { EmbedBuilder } from '@fluxerjs/builders';
+export { AttachmentBuilder, EmbedBuilder, MessagePayload } from '@fluxerjs/builders';
 import { EventEmitter } from 'events';
 import { REST } from '@fluxerjs/rest';
 import { WebSocketManager } from '@fluxerjs/ws';
-export { AttachmentBuilder, EmbedBuilder, MessagePayload } from '@fluxerjs/builders';
 
 declare abstract class Base {
     abstract readonly client: Client;
 }
 
-declare class User extends Base {
-    readonly client: Client;
-    readonly id: string;
-    username: string;
-    discriminator: string;
-    globalName: string | null;
-    avatar: string | null;
-    readonly bot: boolean;
-    constructor(client: Client, data: APIUserPartial);
-    avatarURL(options?: {
-        size?: number;
-        extension?: string;
-    }): string | null;
-    displayAvatarURL(options?: {
-        size?: number;
-    }): string;
-    toString(): string;
-}
-
-declare class Message extends Base {
-    readonly client: Client;
-    readonly id: string;
-    readonly channelId: string;
-    readonly guildId: string | null;
-    readonly author: User;
-    content: string;
-    readonly createdAt: Date;
-    readonly editedAt: Date | null;
-    pinned: boolean;
-    readonly attachments: Collection<string, APIMessageAttachment>;
-    channel?: Channel;
-    constructor(client: Client, data: APIMessage);
-    reply(options: string | {
-        content?: string;
-        embeds?: APIEmbed[];
-    }): Promise<Message>;
-    edit(options: {
-        content?: string;
-    }): Promise<Message>;
-    delete(): Promise<void>;
-}
-
+/** Options for sending a message via webhook. */
 interface WebhookSendOptions {
+    /** Message text content */
     content?: string;
+    /** Embed objects (use EmbedBuilder.toJSON()) */
     embeds?: Array<Record<string, unknown>>;
+    /** Override the webhook's default username */
     username?: string;
+    /** Override the webhook's default avatar URL */
     avatar_url?: string;
+    /** Text-to-speech */
     tts?: boolean;
 }
 /**
@@ -73,6 +38,7 @@ declare class Webhook extends Base {
     avatar: string | null;
     /** Present only when webhook was created via createWebhook(); not returned when fetching. */
     readonly token: string | null;
+    /** @param data - API webhook from POST /channels/{id}/webhooks (has token) or GET /webhooks/{id} (no token) */
     constructor(client: Client, data: APIWebhook & {
         token?: string | null;
     });
@@ -84,12 +50,18 @@ declare class Webhook extends Base {
      */
     send(options: string | WebhookSendOptions): Promise<void>;
     /**
-     * Fetch a webhook by ID using bot auth. The returned webhook will not have a token (cannot send).
+     * Fetch a webhook by ID using bot auth.
+     * @param client - The client instance
+     * @param webhookId - The webhook ID
+     * @returns Webhook without token (cannot send)
      */
     static fetch(client: Client, webhookId: string): Promise<Webhook>;
     /**
      * Create a Webhook instance from an ID and token (e.g. from a stored webhook URL).
-     * Useful when you have the token from a previous createWebhook() call.
+     * @param client - The client instance
+     * @param webhookId - The webhook ID
+     * @param token - The webhook token (from createWebhook or stored)
+     * @param options - Optional channelId, guildId, name for display
      */
     static fromToken(client: Client, webhookId: string, token: string, options?: {
         channelId?: string;
@@ -98,11 +70,20 @@ declare class Webhook extends Base {
     }): Webhook;
 }
 
+/** Base class for all channel types. */
 declare abstract class Channel extends Base {
+    /** Create a DM channel from API data (type DM or GroupDM). */
+    static createDM(client: Client, data: APIChannelPartial): DMChannel;
     readonly client: Client;
     readonly id: string;
     type: ChannelType;
+    /** @param data - API channel from GET /channels/{id} or GET /guilds/{id}/channels */
     constructor(client: Client, data: APIChannelPartial);
+    /**
+     * Create the appropriate channel subclass from API data.
+     * @param client - The client instance
+     * @param data - Channel data from the API
+     */
     static from(client: Client, data: APIChannel | APIChannelPartial): GuildChannel | TextChannel | null;
 }
 declare class GuildChannel extends Channel {
@@ -111,12 +92,19 @@ declare class GuildChannel extends Channel {
     position?: number;
     parentId: string | null;
     constructor(client: Client, data: APIChannel);
-    /** Create a webhook in this channel. Returns the webhook with token (required for send()). */
+    /**
+     * Create a webhook in this channel.
+     * @param options - Webhook name and optional avatar URL
+     * @returns The webhook with token (required for send()). Requires Manage Webhooks permission.
+     */
     createWebhook(options: {
         name: string;
         avatar?: string | null;
     }): Promise<Webhook>;
-    /** Fetch all webhooks in this channel. Returned webhooks do not include the token (cannot send). */
+    /**
+     * Fetch all webhooks in this channel.
+     * @returns Webhooks (includes token when listing from channel; can send via send())
+     */
     fetchWebhooks(): Promise<Webhook[]>;
 }
 declare class TextChannel extends GuildChannel {
@@ -125,6 +113,10 @@ declare class TextChannel extends GuildChannel {
     rateLimitPerUser?: number;
     lastMessageId?: string | null;
     constructor(client: Client, data: APIChannel);
+    /**
+     * Send a message to this channel.
+     * @param options - Text content or object with `content` and/or `embeds`
+     */
     send(options: string | {
         content?: string;
         embeds?: unknown[];
@@ -142,7 +134,135 @@ declare class LinkChannel extends GuildChannel {
     url?: string | null;
     constructor(client: Client, data: APIChannel);
 }
+/** DM channel (direct message between bot and a user). */
+declare class DMChannel extends Channel {
+    lastMessageId?: string | null;
+    constructor(client: Client, data: APIChannelPartial);
+    /**
+     * Send a message to this DM channel.
+     * @param options - Text content or object with `content` and/or `embeds`
+     */
+    send(options: string | {
+        content?: string;
+        embeds?: unknown[];
+    }): Promise<Message>;
+}
 
+/** Options for editing a message (content and/or embeds). */
+interface MessageEditOptions {
+    /** New text content */
+    content?: string;
+    /** New embeds (replaces existing) */
+    embeds?: (APIEmbed | EmbedBuilder)[];
+}
+/** Represents a message in a channel. */
+declare class Message extends Base {
+    readonly client: Client;
+    readonly id: string;
+    readonly channelId: string;
+    readonly guildId: string | null;
+    readonly author: User;
+    content: string;
+    readonly createdAt: Date;
+    readonly editedAt: Date | null;
+    pinned: boolean;
+    readonly attachments: Collection<string, APIMessageAttachment>;
+    channel?: Channel;
+    /** @param data - API message from POST/PATCH /channels/{id}/messages or gateway MESSAGE_CREATE */
+    constructor(client: Client, data: APIMessage);
+    /**
+     * Reply to this message.
+     * @param options - Text content or object with content and/or embeds
+     */
+    reply(options: string | {
+        content?: string;
+        embeds?: APIEmbed[];
+    }): Promise<Message>;
+    /**
+     * Edit this message. Only the author (or admins) can edit.
+     * @param options - New content and/or embeds
+     */
+    edit(options: MessageEditOptions): Promise<Message>;
+    /** Delete this message. */
+    delete(): Promise<void>;
+    /**
+     * Format emoji for reaction API: unicode string or "name:id" for custom.
+     * @param emoji - Unicode emoji (e.g. "👍") or custom { name, id } or "name:id" string
+     */
+    private static formatEmoji;
+    /**
+     * Add a reaction to this message (as the bot).
+     * @param emoji - Unicode emoji (e.g. `👍`) or custom emoji `{ name, id }`
+     */
+    react(emoji: string | {
+        name: string;
+        id: string;
+    }): Promise<void>;
+    /**
+     * Remove the bot's reaction, or a specific user's reaction if userId is provided.
+     * @param emoji - Unicode emoji or custom `{ name, id }`
+     * @param userId - If provided, removes that user's reaction (requires moderator permissions)
+     */
+    removeReaction(emoji: string | {
+        name: string;
+        id: string;
+    }, userId?: string): Promise<void>;
+    /**
+     * Remove all reactions from this message.
+     * Requires moderator permissions.
+     */
+    removeAllReactions(): Promise<void>;
+    /**
+     * Remove all reactions of a specific emoji from this message.
+     * @param emoji - Unicode emoji or custom `{ name, id }`. Requires moderator permissions.
+     */
+    removeReactionEmoji(emoji: string | {
+        name: string;
+        id: string;
+    }): Promise<void>;
+}
+
+/** Represents a user (or bot) on Fluxer. */
+declare class User extends Base {
+    readonly client: Client;
+    readonly id: string;
+    username: string;
+    discriminator: string;
+    globalName: string | null;
+    avatar: string | null;
+    readonly bot: boolean;
+    /** @param data - API user from message author, GET /users/{id}, or GET /users/@me */
+    constructor(client: Client, data: APIUserPartial);
+    /**
+     * Get the URL for this user's avatar.
+     * @param options - Optional `size` and `extension` (default: `png`)
+     */
+    avatarURL(options?: {
+        size?: number;
+        extension?: string;
+    }): string | null;
+    /** Get the avatar URL, or the default avatar if none set. */
+    displayAvatarURL(options?: {
+        size?: number;
+    }): string;
+    /** Returns a mention string (e.g. `<@123456>`). */
+    toString(): string;
+    /**
+     * Create or get a DM channel with this user.
+     * Returns the DM channel; use {@link DMChannel.send} to send messages.
+     */
+    createDM(): Promise<DMChannel>;
+    /**
+     * Send a DM to this user.
+     * Convenience method that creates the DM channel and sends the message.
+     */
+    send(options: string | {
+        content?: string;
+        embeds?: unknown[];
+    }): Promise<Message>;
+}
+
+/** Represents a Fluxer guild (server). */
 declare class Guild extends Base {
     readonly client: Client;
     readonly id: string;
@@ -152,17 +272,27 @@ declare class Guild extends Base {
     readonly ownerId: string;
     members: Collection<string, GuildMember>;
     channels: Collection<string, GuildChannel>;
+    /** @param data - API guild from GET /guilds/{id} or gateway GUILD_CREATE */
     constructor(client: Client, data: APIGuild);
+    /** Get the guild icon URL, or null if no icon. */
     iconURL(options?: {
         size?: number;
     }): string | null;
+    /** Get the guild banner URL, or null if no banner. */
     bannerURL(options?: {
         size?: number;
     }): string | null;
+    /**
+     * Fetch a guild member by user ID.
+     * @param userId - The user ID of the member to fetch
+     * @returns The guild member, or null if not found
+     */
+    fetchMember(userId: string): Promise<GuildMember | null>;
     /** Fetch all webhooks in this guild. Returned webhooks do not include the token (cannot send). */
     fetchWebhooks(): Promise<Webhook[]>;
 }
 
+/** Represents a member of a guild. */
 declare class GuildMember extends Base {
     readonly client: Client;
     readonly id: string;
@@ -172,10 +302,24 @@ declare class GuildMember extends Base {
     readonly roles: string[];
     readonly joinedAt: Date;
     communicationDisabledUntil: Date | null;
+    /** @param data - API guild member from GET /guilds/{id}/members or GET /guilds/{id}/members/{user_id} */
     constructor(client: Client, data: APIGuildMember & {
         guild_id?: string;
     }, guild: Guild);
+    /** Nickname, or global name, or username. */
     get displayName(): string;
+    /**
+     * Add a role to this member.
+     * @param roleId - The role ID to add
+     * Requires Manage Roles permission.
+     */
+    addRole(roleId: string): Promise<void>;
+    /**
+     * Remove a role from this member.
+     * @param roleId - The role ID to remove
+     * Requires Manage Roles permission.
+     */
+    removeRole(roleId: string): Promise<void>;
 }
 
 interface ClientOptions {
@@ -258,6 +402,7 @@ interface ClientEvents {
     [Events.Error]: [error: Error];
     [Events.Debug]: [message: string];
 }
+/** Main Fluxer bot client. Connects to the gateway, emits events, and provides REST access. */
 declare class Client extends EventEmitter {
     readonly options: ClientOptions;
     readonly rest: REST;
@@ -267,13 +412,25 @@ declare class Client extends EventEmitter {
     user: ClientUser | null;
     readyAt: Date | null;
     private _ws;
+    /** @param options - Token, REST config, WebSocket, presence, etc. */
     constructor(options?: ClientOptions);
+    /** WebSocket manager. Throws if not logged in. */
     get ws(): WebSocketManager;
-    /** Send a payload to the gateway (e.g. Voice State Update). Uses shard 0 when single-shard. */
+    /**
+     * Send a payload to the gateway (e.g. Voice State Update).
+     * @param shardId - Shard ID (use 0 for single-shard)
+     * @param payload - Gateway payload to send
+     */
     sendToGateway(shardId: number, payload: GatewaySendPayload): void;
     private handleDispatch;
+    /**
+     * Connect to the Fluxer gateway and authenticate.
+     * @param token - Bot token (e.g. from FLUXER_BOT_TOKEN)
+     */
     login(token: string): Promise<string>;
+    /** Disconnect from the gateway and clear cached data. */
     destroy(): Promise<void>;
+    /** Returns true if the client has received Ready and `user` is set. */
     isReady(): this is Client & {
         user: NonNullable<Client['user']>;
     };
@@ -289,4 +446,4 @@ declare const ErrorCodes: {
     readonly InvalidToken: "INVALID_TOKEN";
 };
 
-export { Base, CategoryChannel, Channel, Client, type ClientEvents, ClientUser, ErrorCodes, Events, FluxerError, Guild, GuildChannel, GuildMember, LinkChannel, Message, TextChannel, User, VoiceChannel, Webhook, type WebhookSendOptions };
+export { Base, CategoryChannel, Channel, Client, type ClientEvents, ClientUser, DMChannel, ErrorCodes, Events, FluxerError, Guild, GuildChannel, GuildMember, LinkChannel, Message, type MessageEditOptions, TextChannel, User, VoiceChannel, Webhook, type WebhookSendOptions };