@stoatx/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1338 @@
+import { EventEmitter } from 'events';
+import * as util from 'node:util';
+
+declare class GatewayManager {
+    private client;
+    private ws;
+    private pingInterval;
+    private token;
+    private reconnectAttempts;
+    private readonly maxReconnectWait;
+    private isIntentionalClose;
+    constructor(client: Client);
+    connect(token: string): Promise<void>;
+    private handleMessage;
+    private startPingLoop;
+    private send;
+    private reconnect;
+    disconnect(): void;
+}
+
+declare class RESTManager {
+    private client;
+    private baseURL;
+    private token;
+    private buckets;
+    constructor(client: Client);
+    setToken(token: string): void;
+    /**
+     * Generates a local identifier for the bucket based on method and path.
+     */
+    private getRouteKey;
+    makeRequest(method: string, endpoint: string, body?: any): Promise<any>;
+    private execute;
+    /**
+     * Uploads a file to Stoat's CDN and returns the File ID
+     */
+    uploadFile(filename: string, fileBuffer: Buffer | Blob): Promise<string>;
+    get(endpoint: string): Promise<any>;
+    post(endpoint: string, body: any): Promise<any>;
+    patch(endpoint: string, body: any): Promise<any>;
+    delete(endpoint: string): Promise<any>;
+    put(endpoint: string, body: any): Promise<any>;
+}
+
+/**
+ * The base class for all structures.
+ */
+declare abstract class Base {
+    readonly id: string;
+    cachedAt: number;
+    protected readonly client: Client;
+    constructor(client: Client, data: {
+        _id: string;
+    });
+    /**
+     * Compares this object with another to see if they represent the same entity.
+     */
+    equals(other: Base | string): boolean;
+    /**
+     * Returns the UUID string when the object is cast to a string.
+     */
+    toString(): string;
+    /**
+     * Helper to quickly clone a structure
+     */
+    _clone(): this;
+}
+
+type AttachmentMetadata = {
+    type: "File";
+} | {
+    type: "Text";
+} | {
+    type: "Audio";
+} | {
+    type: "Image";
+    width: number;
+    height: number;
+    thumbhash?: number[];
+    animated?: boolean;
+} | {
+    type: "Video";
+    width: number;
+    height: number;
+};
+declare class Attachment extends Base {
+    id: string;
+    tag: string;
+    filename: string;
+    metadata: AttachmentMetadata;
+    contentType: string;
+    size: number;
+    deleted?: boolean;
+    reported?: boolean;
+    messageId?: string;
+    userId?: string;
+    serverId?: string;
+    objectId?: string;
+    constructor(client: Client, data: any);
+    /**
+     * Automatically constructs the direct CDN URL for this file
+     */
+    get url(): string;
+    /**
+     * Helper boolean to quickly check if it's an image
+     */
+    get isImage(): boolean;
+}
+
+declare enum UserRelationship {
+    None = "None",
+    User = "User",
+    Friend = "Friend",
+    Outgoing = "Outgoing",
+    Incoming = "Incoming",
+    Blocked = "Blocked",
+    BlockedOther = "BlockedOther"
+}
+declare enum UserPresence {
+    Online = "Online",
+    Idle = "Idle",
+    Focus = "Focus",
+    Busy = "Busy",
+    Invisible = "Invisible"
+}
+interface BotInformation {
+    owner: string;
+}
+interface UserStatus {
+    presence: UserPresence;
+    text?: string | null;
+}
+interface UserProfile {
+    background?: string | null;
+    content?: string | null;
+}
+declare class User extends Base {
+    discriminator: string;
+    online: boolean;
+    relationship: UserRelationship;
+    username: string;
+    avatar?: Attachment | null;
+    badges?: number;
+    bot: false | BotInformation;
+    displayName?: string | null;
+    flags?: number;
+    privileged?: boolean;
+    status?: UserStatus | null;
+    constructor(client: Client, data: any);
+    _patch(data: any, clear?: string[]): void;
+    /**
+     * Convenience getter to return the user's tag (username#discriminator)
+     */
+    get tag(): string;
+    /**
+     * Fetch a User to update their information
+     * @param force Skip the cache check and force an API request
+     * @returns The fetched User object
+     * @throws Error if the user cannot be found or fetched
+     * @example
+     * // Fetch a user
+     * await user.fetch();
+     */
+    fetch(force?: boolean): Promise<this>;
+}
+
+/**
+ * A utility class that extends the native JavaScript Map with Array-like methods.
+ */
+declare class Collection<K, V> extends Map<K, V> {
+    limit: number;
+    constructor(limit?: number);
+    /**
+     * Overrides the default set method to enforce the maximum cache size.
+     */
+    set(key: K, value: V): this;
+    /**
+     * Finds the first item where the given function returns true.
+     */
+    find(fn: (value: V, key: K, collection: this) => boolean): V | undefined;
+    /**
+     * Returns a new Collection containing only the items where the function returns true.
+     */
+    filter(fn: (value: V, key: K, collection: this) => boolean): Collection<K, V>;
+    /**
+     * Maps each item to a new array of values.
+     */
+    map<T>(fn: (value: V, key: K, collection: this) => T): T[];
+    /**
+     * Gets the very first value in the Collection (based on insertion order).
+     */
+    first(): V | undefined;
+    /**
+     * Gets the very last value in the Collection.
+     */
+    last(): V | undefined;
+    /**
+     * Checks if at least one item matches the condition.
+     */
+    some(fn: (value: V, key: K, collection: this) => boolean): boolean;
+}
+
+/**
+ * @template K The type of the cache keys (usually string)
+ * @template Holds The type of the Structure this manager holds
+ */
+declare abstract class BaseManager<K, Holds> {
+    client: Client;
+    cache: Collection<K, Holds>;
+    constructor(client: Client, limit?: number);
+    /**
+     * Defines how to extract the unique ID from a raw API payload.
+     * @internal
+     */
+    protected abstract extractId(data: any): K;
+    /**
+     * Defines how to construct a new instance of the Structure.
+     * @internal
+     */
+    protected abstract construct(data: any): Holds;
+    /**
+     * Transforms raw data into a Structure, patches if existing, and saves to cache.
+     * @internal
+     */
+    _add(data: any): Holds;
+}
+
+type MemberResolvable = Member | User | string;
+interface MemberEditOptions {
+    nickname?: string | null;
+    avatar?: string | null;
+    roles?: string[];
+    timeout?: string | null;
+}
+interface MemberBanOptions {
+    reason?: string | null;
+    deleteMessageSeconds?: number;
+}
+interface FetchMembersOptions {
+    exclude_offline?: boolean;
+}
+declare class MemberManager extends BaseManager<string, Member> {
+    server: Server;
+    constructor(client: Client, server: Server, limit?: number);
+    /**
+     * Tell BaseManager how to handle Revolt's Member IDs
+     * @internal
+     */
+    protected extractId(data: any): string;
+    /**
+     * Tell BaseManager how to build a Member
+     * @internal
+     */
+    protected construct(data: any): Member;
+    resolve(member: MemberResolvable): Member | undefined;
+    resolveId(member: MemberResolvable): string;
+    fetch(member: MemberResolvable, force?: boolean): Promise<Member>;
+    /**
+     * Fetches multiple members from the server.
+     * @param options Filter options for the fetch request.
+     * @returns A promise that resolves to a Collection of fetched Members.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Fetch all members in the server
+     * const allMembers = await server.members.fetchMany();
+     *
+     * // Fetch only online members to save bandwidth
+     * const onlineMembers = await server.members.fetchMany({ exclude_offline: true });
+     */
+    fetchMany(options?: FetchMembersOptions): Promise<Collection<string, Member>>;
+    /**
+     * Edits a member in the server.
+     * @param member The MemberResolvable to edit.
+     * @param options The fields to update (nickname, roles, timeout, etc.).
+     */
+    edit(member: MemberResolvable, options: MemberEditOptions): Promise<Member>;
+    /**
+     * Kicks a member from the server.
+     * @param member The MemberResolvable to kick.
+     */
+    kick(member: MemberResolvable): Promise<void>;
+    /**
+     * Bans a member from the server.
+     * @param member The MemberResolvable to ban.
+     * @param options The ban options
+     */
+    ban(member: MemberResolvable, options?: MemberBanOptions): Promise<void>;
+    /**
+     * Unbans a user from the server
+     * @param member The MemberResolvable to unban
+     */
+    unban(member: MemberResolvable): Promise<void>;
+    [util.inspect.custom](): Collection<string, Member>;
+}
+
+declare const PermissionFlags: {
+    readonly ManageChannel: bigint;
+    readonly ManageServer: bigint;
+    readonly ManagePermissions: bigint;
+    readonly ManageRole: bigint;
+    readonly ManageCustomisation: bigint;
+    readonly KickMembers: bigint;
+    readonly BanMembers: bigint;
+    readonly TimeoutMembers: bigint;
+    readonly AssignRoles: bigint;
+    readonly ChangeNickname: bigint;
+    readonly ManageNicknames: bigint;
+    readonly ChangeAvatar: bigint;
+    readonly RemoveAvatars: bigint;
+    readonly ViewChannel: bigint;
+    readonly ReadMessageHistory: bigint;
+    readonly SendMessage: bigint;
+    readonly ManageMessages: bigint;
+    readonly ManageWebhooks: bigint;
+    readonly InviteOthers: bigint;
+    readonly SendEmbeds: bigint;
+    readonly UploadFiles: bigint;
+    readonly Masquerade: bigint;
+    readonly React: bigint;
+    readonly BypassSlowmode: bigint;
+    readonly Connect: bigint;
+    readonly Speak: bigint;
+    readonly Video: bigint;
+    readonly MuteMembers: bigint;
+    readonly DeafenMembers: bigint;
+    readonly MoveMembers: bigint;
+    readonly Listen: bigint;
+    readonly MentionEveryone: bigint;
+    readonly MentionRoles: bigint;
+    readonly GrantAllSafe: 4503599627370495n;
+};
+type PermissionString = keyof typeof PermissionFlags;
+type PermissionResolvable = bigint | PermissionString | PermissionResolvable[];
+declare class Permissions {
+    /**
+     * Converts a string, BigInt, or array of strings into a single BigInt
+     */
+    static resolve(permission: PermissionResolvable): bigint;
+    /**
+     * Checks if a specific permission bit exists
+     */
+    static has(totalPermissions: bigint, permissionToCheck: PermissionResolvable): boolean;
+}
+
+declare class DMChannel extends BaseChannel {
+    active: boolean;
+    recipients: DMChannel[];
+    lastMessageId: string | null;
+    constructor(client: any, data: any);
+    _patch(data: any): void;
+}
+
+declare class GroupChannel extends BaseChannel {
+    name: string;
+    ownerId: string;
+    recipients: string[];
+    description?: string | null;
+    icon: Attachment | null;
+    lastMessageId?: string | null;
+    nsfw: boolean;
+    constructor(client: Client, data: any);
+    _patch(data: any, clear?: string[]): void;
+    /** Gets the User object of the person who owns this group */
+    get owner(): User | undefined;
+    /** Resolves the recipient IDs into an array of cached User objects */
+    get recipientUsers(): User[];
+    /**
+     * Updates the default (everyone) permissions for this channel.
+     * @param permissions The default permissions to grant globally in this channel.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If invalid permissions are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Set the default permission to allow everyone to view the channel
+     * await channel.setDefaultPermissions(["ViewChannel", "ReadMessageHistory"]);
+     */
+    setDefaultPermissions(permissions: PermissionResolvable): Promise<this>;
+    [util.inspect.custom](_depth: number, options: util.InspectOptions, inspect: typeof util.inspect): string;
+}
+
+type ChannelResolvable = BaseChannel | string;
+interface ChannelEditOptions {
+    name?: string;
+    description?: string | null;
+    owner?: string;
+    icon?: string | null;
+    nsfw?: boolean;
+    archived?: boolean;
+    voice?: {
+        max_users: number;
+    };
+    slowmode?: number;
+}
+interface ChannelRolePermissionOptions {
+    allow?: PermissionResolvable;
+    deny?: PermissionResolvable;
+}
+declare class ChannelManager extends BaseManager<string, BaseChannel> {
+    client: Client;
+    /**
+     * Manages API methods and caching for all channels globally.
+     * @param client The active Client instance.
+     * @param limit The maximum number of channels to hold in the cache.
+     */
+    constructor(client: Client, limit?: number);
+    protected extractId(data: any): string;
+    protected construct(data: any): BaseChannel;
+    /**
+     * Resolves a ChannelResolvable to a cached BaseChannel object.
+     * @param channel The ChannelResolvable to resolve.
+     * @returns The resolved BaseChannel, or undefined if not cached.
+     */
+    resolve(channel: ChannelResolvable): BaseChannel | undefined;
+    resolveText(channel: ChannelResolvable): TextChannel | undefined;
+    resolveDM(channel: ChannelResolvable): DMChannel | undefined;
+    resolveGroup(channel: ChannelResolvable): GroupChannel | undefined;
+    /**
+     * Extracts ID from a ChannelResolvable.
+     * @param channel The ChannelResolvable to extract the ID from.
+     * @returns The extracted channel ID.
+     * @throws {TypeError} If an invalid type is provided.
+     */
+    resolveId(channel: ChannelResolvable): string;
+    /**
+     * Fetches a Channel from the API or resolves it from the local cache.
+     * @param channel The ID, mention, or Channel object to fetch.
+     * @param force Whether to skip the cache check and force a direct API request. Defaults to true.
+     * @returns A promise that resolves to the fetched BaseChannel object.
+     * @throws {TypeError} If an invalid ChannelResolvable is provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Fetch a channel, bypassing cache
+     * const channel = await client.channels.fetch("01H...");
+     */
+    fetch(channel: ChannelResolvable, force?: boolean): Promise<BaseChannel>;
+    /**
+     * Edits a channel in the server.
+     * @param channel The ChannelResolvable to edit.
+     * @param options The fields to update.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If invalid options or ChannelResolvable are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Update channel name and remove its description
+     * await client.channels.edit("01H...", { name: "general", description: null });
+     */
+    edit(channel: ChannelResolvable, options: ChannelEditOptions): Promise<BaseChannel>;
+    /**
+     * Updates the permission overrides for a specific role in a channel.
+     * @param channel The ChannelResolvable to update permissions for.
+     * @param roleId The raw string ID of the role to update.
+     * @param options The allow and deny permissions to set.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If the channel is not a Server Channel, or options are invalid.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Deny a role the ability to send messages in this channel
+     * await client.channels.setRolePermissions(channel, "ROLE_ID", { deny: ["SendMessage"] });
+     */
+    setRolePermissions(channel: ChannelResolvable, roleId: string, options: ChannelRolePermissionOptions): Promise<BaseChannel>;
+    /**
+     * Updates the default (everyone) permissions for a channel.
+     * @param channel The ChannelResolvable to update permissions for.
+     * @param permissions The default permissions to grant globally in this channel.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If invalid permissions are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Set the default permission to allow everyone to view the channel
+     * await client.channels.setDefaultPermissions(channel, ["ViewChannel", "ReadMessageHistory"]);
+     */
+    setDefaultPermissions(channel: ChannelResolvable, permissions: PermissionResolvable): Promise<BaseChannel>;
+    /**
+     * Deletes a server channel, leaves a group, or closes a DM.
+     * @param channel The channel object, raw ID, or mention string to delete.
+     * @returns A promise that resolves when the action is successful.
+     * @throws {Error} If the API request fails.
+     * @example
+     * await client.channels.delete("01H...");
+     */
+    delete(channel: ChannelResolvable): Promise<void>;
+}
+
+declare class TextChannel extends BaseChannel {
+    name: string;
+    serverId: string;
+    defaultPermissions?: {
+        a: number;
+        d: number;
+    };
+    description?: string | null;
+    icon?: Attachment | null;
+    lastMessageId?: string | null;
+    nsfw?: boolean;
+    slowmode?: number;
+    voice?: any;
+    constructor(client: Client, data: any);
+    _patch(data: any, clear?: string[]): void;
+    /**
+     * Updates the permission overrides for the channel.
+     * @param roleId The raw string ID of the role to update.
+     * @param options The allow and deny permissions to set.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If the channel is not a Server Channel, or options are invalid.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Deny a role the ability to send messages in this channel
+     * await channel.setRolePermissions("ROLE_ID", { deny: ["SendMessage"] });
+     */
+    setRolePermissions(roleId: string, options: ChannelRolePermissionOptions): Promise<this>;
+    /**
+     * Updates the default (everyone) permissions for this channel.
+     * @param permissions The default permissions to grant globally in this channel.
+     * @returns A promise that resolves to the updated BaseChannel.
+     * @throws {TypeError} If invalid permissions are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Set the default permission to allow everyone to view the channel
+     * await channel.setDefaultPermissions(["ViewChannel", "ReadMessageHistory"]);
+     */
+    setDefaultPermissions(permissions: PermissionResolvable): Promise<this>;
+}
+
+type MessageResolvable = Message | string;
+interface MessageFetchOptions {
+    limit?: number;
+    before?: string;
+    after?: string;
+    sort?: "Relevance" | "Latest" | "Oldest";
+    nearby?: string;
+    includeUsers?: boolean;
+}
+declare class MessageManager extends BaseManager<string, Message> {
+    private channel;
+    constructor(client: Client, channel: BaseChannel, limit?: number);
+    /**
+     * Tell BaseManager how to find the ID for Messages
+     */
+    protected extractId(data: any): string;
+    /**
+     * Tell BaseManager how to build a Message
+     */
+    protected construct(data: any): Message;
+    fetch(id: string): Promise<Message>;
+    /**
+     * Fetches multiple messages from the channel using specific filter parameters.
+     * @param options The query parameters to filter the fetched messages.
+     * @returns A promise that resolves to a Collection of fetched Messages.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Fetch the last 50 messages in the channel
+     * const messages = await channel.messages.fetchMany({ limit: 50, sort: "Latest" });
+     *
+     * // Fetch 20 messages before a specific message ID
+     * const history = await channel.messages.fetchMany({ limit: 20, before: "01H..." });
+     */
+    fetchMany(options?: MessageFetchOptions): Promise<Collection<string, Message>>;
+    resolveId(message: MessageResolvable): string;
+    /**
+     * Sends a new message to this channel.
+     * @param contentOrOptions The string content or message options payload.
+     * @returns A promise that resolves to the sent Message.
+     */
+    send(contentOrOptions: MessageOptions | string): Promise<Message>;
+    /**
+     * Edits an existing message.
+     * @param message The MessageResolvable (object or ID) to edit.
+     * @param contentOrOptions The new content or options.
+     * @returns A promise that resolves to the updated Message.
+     */
+    edit(message: MessageResolvable, contentOrOptions: string | MessageOptions): Promise<Message>;
+    /**
+     * Deletes a message from the channel.
+     * @param message The MessageResolvable to delete.
+     */
+    delete(message: MessageResolvable): Promise<void>;
+    /**
+     * Pins a message in the channel.
+     * @param message The MessageResolvable to pin.
+     */
+    pin(message: MessageResolvable): Promise<void>;
+    /**
+     * Unpins a message in the channel.
+     * @param message The MessageResolvable to unpin.
+     */
+    unpin(message: MessageResolvable): Promise<void>;
+    [util.inspect.custom](): Collection<string, Message>;
+}
+
+declare enum ChannelType {
+    TEXT = "TextChannel",
+    DM = "DirectMessage",
+    GROUP = "Group"
+}
+interface ChannelCreateOptions {
+    name: string;
+    type: "Text" | "Voice";
+    description?: string;
+    nsfw?: boolean;
+    voice?: {
+        max_users?: number;
+    };
+}
+declare abstract class BaseChannel extends Base {
+    type: ChannelType;
+    messages: MessageManager;
+    protected constructor(client: Client, data: any);
+    /**
+     * Sends a message to this channel.
+     * @param contentOrOptions The string content or message options payload.
+     * @returns A promise that resolves to the sent Message.
+     * @example
+     * await channel.send("Hello world!");
+     * await channel.send({ content: "Here is an embed", embeds: [myEmbed] });
+     */
+    send(contentOrOptions: string | MessageOptions): Promise<Message>;
+    fetch(force?: boolean): Promise<this>;
+    /**
+     * Fetches multiple messages from this channel.
+     * @param options The query parameters to filter the messages.
+     */
+    fetchMessages(options?: MessageFetchOptions): Promise<Collection<string, Message>>;
+    /**
+     * Edits this channel.
+     * @param options The fields to update
+     */
+    edit(options: ChannelEditOptions): Promise<this>;
+    /**
+     * Deletes this channel.
+     */
+    delete(): Promise<void>;
+    isText(): this is TextChannel;
+    isDM(): this is DMChannel;
+    isGroup(): this is GroupChannel;
+}
+
+declare class ServerChannelManager {
+    private client;
+    private server;
+    constructor(client: Client, server: Server);
+    get cache(): Collection<string, BaseChannel>;
+    /**
+     * Creates a new channel within this server.
+     * @param options The configuration for the new channel.
+     * @returns The newly created Channel object.
+     */
+    create(options: ChannelCreateOptions): Promise<BaseChannel>;
+    [util.inspect.custom](): Collection<string, BaseChannel>;
+}
+
+declare class Role extends Base {
+    serverId: string;
+    name: string;
+    color: string | null;
+    hoist: boolean;
+    rank: number;
+    permissions: bigint;
+    constructor(client: Client, data: any, serverId: string);
+    /**
+     * Updates the role instance with new data without losing the object reference.
+     * @internal
+     */
+    _patch(data: any): void;
+    /**
+     * The server this role belongs to.
+     * Pulls dynamically from the cache to prevent massive memory duplication.
+     */
+    get server(): Server | undefined;
+    /**
+     * Checks whether this role has a specific permission.
+     * @param permission The permission to check for.
+     * @returns True if the role has the permission.
+     */
+    hasPermission(permission: PermissionResolvable): boolean;
+    /**
+     * Fetches this role directly from the API to ensure data is up to date.
+     * @param force Whether to skip the cache check and force a direct API request. Defaults to false.
+     * @returns A promise that resolves to the fetched Role object.
+     * @throws {TypeError} If an invalid RoleResolvable is provided.
+     * @throws {Error} If the API request fails (e.g., the role does not exist).
+     * @example
+     * // Refresh the role's data from the API
+     * await role.fetch();
+     * console.log(`Role updated, current name: ${role.name}`);
+     */
+    fetch(force?: boolean): Promise<this>;
+    /**
+     * Edits the role with the given options. Only the fields provided in the options will be updated; all other fields will remain unchanged.
+     * @param options The fields to update.
+     * @returns A promise that resolves to the updated Role.
+     * @throws {TypeError} If invalid options or RoleResolvable are provided.
+     * @throws {Error} If the API request fails (e.g., lack of permissions).
+     * @example
+     * // Change the role's name and color
+     * await role.edit({ name: "Senior Admin", colour: "#FFD700" });
+     *
+     * // Remove the custom color from the role
+     * await role.edit({ colour: null });
+     */
+    edit(options: RoleEditOptions): Promise<this>;
+    /**
+     * Deletes this Role from the server.
+     * @throws {Error} If the role cannot be deleted (e.g., lack of permissions).
+     * @example
+     * // Delete a role by its ID
+     * await role.delete();
+     */
+    delete(): Promise<void>;
+    /**
+     * Updates the permissions for this role.
+     * @param options The allow and deny permissions to set.
+     * @returns A promise that resolves to the updated Role object.
+     * @throws {TypeError} If invalid options are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Grant the role permission to manage channels and send messages
+     * await role.setPermissions({
+     *   allow: ["ManageChannel", "SendMessage"]
+     * });
+     */
+    setPermissions(options: RolePermissionOptions): Promise<this>;
+    /**
+     * Updates the hierarchical position of this role.
+     * Automatically reconstructs the role array and performs a bulk update.
+     * @param newPosition The new rank/position for this role (0-indexed).
+     * @returns A promise that resolves to this updated Role object.
+     * @throws {Error} If API request fails.
+     * @example
+     * // Move this role to position 2 in the hierarchy
+     * await role.setPosition(2);
+     * console.log(`Role moved to rank: ${role.rank}`);
+     */
+    setPosition(newPosition: number): Promise<this>;
+    /**
+     * Customizer for Node.js `console.log` and `util.inspect`.
+     * Hides the cyclic client reference and raw serverId for a cleaner output.
+     * @internal
+     */
+    [util.inspect.custom](): string;
+}
+
+interface RoleCreateOptions {
+    name: string;
+}
+interface RoleEditOptions {
+    name?: string;
+    colour?: string | null;
+    hoist?: boolean;
+}
+interface RolePermissionOptions {
+    allow?: PermissionResolvable;
+    deny?: PermissionResolvable;
+}
+type RoleResolvable = Role | string;
+declare class RoleManager extends BaseManager<string, Role> {
+    private server;
+    /**
+     * Manages API methods and caching for server roles.
+     */
+    constructor(client: Client, server: Server, limit?: number);
+    /**
+     * Tell BaseManager how to find the ID for Roles
+     */
+    protected extractId(data: any): string;
+    /**
+     * Tell BaseManager how to build a Role
+     */
+    protected construct(data: any): Role;
+    /**
+     * Adds or updates a role in the local cache.
+     * @internal
+     * @param data The raw role data from the API.
+     * @param idParam An optional ID parameter if the payload wraps the role object.
+     * @returns The newly created or updated Role object.
+     */
+    _add(data: any, idParam?: string): Role;
+    [util.inspect.custom](): Collection<string, Role>;
+    /**
+     * Resolves a RoleResolvable to a Role object from the cache.
+     * @param role The RoleResolvable to resolve.
+     * @returns The resolved Role object, or undefined if not found.
+     */
+    resolve(role: RoleResolvable): Role | undefined;
+    /**
+     * Extracts ID from a RoleResolvable.
+     * @param role The RoleResolvable to extract the ID from.
+     * @returns The extracted role ID.
+     * @throws TypeError if an invalid type is provided.
+     */
+    resolveId(role: RoleResolvable): string;
+    /**
+     * Creates a new role in this server.
+     * @param options The name and optional rank of the new role
+     * @returns Role The role that was created
+     * @throws {Error} If the role cannot be created (e.g., lack of permissions, invalid options).
+     * @throws {TypeError} If invalid options are provided.
+     * @example
+     * // Create a new role named "Moderator" with rank 1
+     * const moderatorRole = await server.roles.create({ name: "Moderator", rank: 1 });
+     * console.log(`Created role: ${moderatorRole.name} with ID: ${moderatorRole.id}`);
+     */
+    create(options: RoleCreateOptions): Promise<Role>;
+    /**
+     * Fetches a Role from the API or resolves it from the local cache.
+     * @param role The ID, mention, or Role object to fetch.
+     * @param force Whether to skip the cache check and force a direct API request. Defaults to false.
+     * @returns A promise that resolves to the fetched Role object.
+     * @throws {TypeError} If an invalid RoleResolvable is provided.
+     * @throws {Error} If the API request fails (e.g., the role does not exist).
+     * @example
+     * // Fetch a role from the API
+     * const role = await server.roles.fetch("01JE2MM759J5D7CHJF084R7MJ2");
+     * console.log(`Fetched role: ${role.name} with ID: ${role.id}`);
+     *
+     * // Fetch a role by mention
+     * const role = await.server.roles.fetch("<%01JE2MM759J5D7CHJF084R7MJ2>");
+     * console.log(`Fetched role: ${role.name} with ID: ${role.id}`);
+     *
+     * // Force fetch a role, bypassing the cache
+     * const role = await server.roles.fetch("01JE2MM759J5D7CHJF084R7MJ2", true);
+     * console.log(`Fetched role: ${role.name} with ID: ${role.id}`);
+     */
+    fetch(role: RoleResolvable, force?: boolean): Promise<Role>;
+    /**
+     * Edits an existing role in the server.
+     * @param role The RoleResolvable to edit.
+     * @param options The fields to update.
+     * @returns A promise that resolves to the updated Role.
+     * @throws {TypeError} If invalid options or RoleResolvable are provided.
+     * @throws {Error} If the API request fails (e.g., lack of permissions).
+     * @example
+     * // Rename a role and give it a red color
+     * await server.roles.edit("01H...", { name: "Super Admin", colour: "#FF0000" });
+     *
+     * // Remove the custom color from a role
+     * await server.roles.edit(role, { colour: null });
+     */
+    edit(role: RoleResolvable, options: RoleEditOptions): Promise<Role>;
+    /**
+     * Deletes a Role from the server.
+     * @param role The RoleResolvable to delete
+     * @returns A promise that resolves when the role is successfully deleted.
+     * @throws {TypeError} If an invalid RoleResolvable is provided.
+     * @throws {Error} If the role cannot be deleted (e.g., lack of permissions).
+     * @example
+     * // Delete a role by its ID
+     * await server.roles.delete("01JE2MM759J5D7CHJF084R7MJ2");
+     * console.log("Role deleted successfully.");
+     *
+     * // Delete a role using a Role object
+     * const role = await server.roles.fetch("01JE2MM759J5D7CHJF084R7MJ2");
+     * await server.roles.delete(role);
+     * console.log("Role deleted successfully.");
+     *
+     * // Delete a role by mention
+     * await server.roles.delete("<%01JE2MM759J5D7CHJF084R7MJ2>");
+     * console.log("Role deleted successfully.");
+     */
+    delete(role: RoleResolvable): Promise<void>;
+    /**
+     * Updates the permissions for a role in the server.
+     * @param role The RoleResolvable to update permissions for.
+     * @param options The allow and deny permissions to set.
+     * @returns A promise that resolves to the updated Role.
+     * @throws {TypeError} If an invalid RoleResolvable or options are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Set permissions using an array of strings.
+     * await server.roles.setPermissions(role, {
+     *   allow: ["ManageChannel", "ViewChannel", "SendMessage"]
+     * });
+     */
+    setPermissions(role: RoleResolvable, options: RolePermissionOptions): Promise<Role>;
+    /**
+     * Updates the hierarchical positions of roles in the server.
+     * @param ranks An array of RoleResolvables representing the new order of roles.
+     * @returns A promise that resolves when the ranks are successfully updated.
+     * @throws {TypeError} If the ranks parameter is not an array or contains invalid resolvables.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Reorder roles by passing an array of Role objects or IDs
+     * await server.roles.setRanks(["RoleID_1", adminRoleObject, "RoleID_3"]);
+     */
+    setRanks(ranks: RoleResolvable[]): Promise<Server>;
+}
+
+declare class ServerInvite {
+    code: string;
+    creatorId: string;
+    channelId: string;
+    constructor(data: any);
+    _patch(data: any): void;
+}
+
+declare class ServerInviteManager extends BaseManager<string, ServerInvite> {
+    server: Server;
+    constructor(client: Client, server: Server, limit?: number);
+    protected extractId(data: any): string;
+    protected construct(data: any): ServerInvite;
+    /**
+     * Fetches all active invites for this server.
+     */
+    fetch(): Promise<Collection<string, ServerInvite>>;
+}
+
+declare class ServerBan {
+    userId: string;
+    reason: string | null;
+    constructor(data: any);
+    _patch(data: any): void;
+}
+
+declare class ServerBanManager extends BaseManager<string, ServerBan> {
+    server: Server;
+    constructor(client: Client, server: Server, limit?: number);
+    protected extractId(data: any): string;
+    protected construct(data: any): ServerBan;
+    /**
+     * Fetches all bans in this server.
+     * Automatically caches the associated User objects globally!
+     * @returns A promise that resolves to a Collection of Bans.
+     */
+    fetch(): Promise<Collection<string, ServerBan>>;
+    /**
+     * Unbans a user from the server.
+     * @param userId The ID of the user to unban.
+     */
+    remove(userId: string): Promise<void>;
+}
+
+interface ServerEditOptions {
+    name?: string;
+    description?: string | null;
+    icon?: string | null;
+    banner?: string | null;
+    categories?: {
+        id: string;
+        title: string;
+        channels: string[];
+    }[];
+    systemMessages?: {
+        userJoined?: string | null;
+        userLeft?: string | null;
+        userKicked?: string | null;
+        userBanned?: string | null;
+    };
+    analytics?: boolean;
+    owner?: string;
+}
+declare class ServerManager extends BaseManager<string, Server> {
+    constructor(client: Client, limit?: number);
+    /**
+     * Tell BaseManager how to find the ID for Servers
+     */
+    protected extractId(data: any): string;
+    /**
+     * Tell BaseManager how to build a Server
+     */
+    protected construct(data: any): Server;
+    /**
+     * Fetches a server from the API.
+     * @param id The server ID.
+     * @param force Whether to skip the cache and fetch from the API.
+     */
+    fetch(id: string, force?: boolean): Promise<Server>;
+    edit(serverId: string, options: ServerEditOptions): Promise<Server>;
+    [util.inspect.custom](): Collection<string, Server>;
+}
+
+interface Categories {
+    channels: string[];
+    id: string;
+    title: string;
+}
+declare class Server extends Base {
+    channelIds: string[];
+    defaultPermissions: bigint;
+    name: string;
+    ownerId: string;
+    analytics: boolean;
+    banner: Attachment | null;
+    categories: Categories[];
+    description: string | null;
+    discoverable: boolean;
+    flags: number;
+    icon: Attachment | null;
+    nsfw: boolean;
+    members: MemberManager;
+    channels: ServerChannelManager;
+    roles: RoleManager;
+    bans: ServerBanManager;
+    invites: ServerInviteManager;
+    constructor(client: Client, data: any);
+    /**
+     * Updates the server instance with new data without losing the object reference.
+     */
+    _patch(data: any, clear?: string[]): void;
+    /**
+     * Edits this server.
+     * @param options The fields to update.
+     */
+    edit(options: ServerEditOptions): Promise<this>;
+    /**
+     * Leaves the server
+     */
+    leave(): Promise<any>;
+    /**
+     * Fetches multiple members from this server.
+     * @param options Filter options for the fetch request.
+     * @returns A Collection of the fetched members.
+     */
+    fetchMembers(options?: FetchMembersOptions): Promise<Collection<string, Member>>;
+}
+
+declare class MemberRoleManager {
+    private member;
+    constructor(member: Member);
+    /**
+     * Gets a Collection of the actual Role objects this member has.
+     * This dynamically pulls from the Server's role cache so references are always up to date
+     */
+    get cache(): Collection<string, Role>;
+    /**
+     * Checks if the member has a specific role.
+     * @param role The RoleResolvable to check for.
+     */
+    has(role: RoleResolvable): boolean;
+    /**
+     * Adds a role to the member.
+     * @param role The RoleResolvable to add.
+     * @returns A promise that resolves to the updated Member.
+     */
+    add(role: RoleResolvable): Promise<Member>;
+    /**
+     * Removes a role from the member.
+     * @param role The RoleResolvable to remove.
+     * @returns A promise that resolves to the updated Member.
+     */
+    remove(role: RoleResolvable): Promise<Member>;
+    /**
+     * Overwrites all roles on the member with a completely new array.
+     * @param roles An array of RoleResolvables.
+     * @returns A promise that resolves to the updated Member.
+     */
+    set(roles: RoleResolvable[]): Promise<Member>;
+}
+
+declare class Member extends Base {
+    serverId: string;
+    nickname: string | null;
+    avatar: string | null;
+    roleIds: string[];
+    joinedAt: Date;
+    timeout: Date | null;
+    canPublish: boolean;
+    canRecieve: boolean;
+    roles: MemberRoleManager;
+    constructor(client: Client, data: any);
+    _patch(data: any): void;
+    /** Gets the global User object for this member */
+    get user(): User | undefined;
+    /** Gets the Server object this member belongs to */
+    get server(): Server | undefined;
+    /** Resolves the array of role strings into actual Role objects */
+    get roleObjects(): Role[];
+    /** Calculates the member's total permissions using BigInt */
+    get permissions(): bigint;
+    /** Checks if the member has a specific permission */
+    hasPermission(permission: PermissionResolvable): boolean;
+    /**
+     * Edits this member's nickname, avatar, roles, or timeout.
+     */
+    edit(options: MemberEditOptions): Promise<this>;
+    /**
+     * Kicks this member from the server.
+     */
+    kick(): Promise<void>;
+    /**
+     * Bans this member from the server.
+     * @param options The options for this ban
+     */
+    ban(options?: MemberBanOptions): Promise<void>;
+    unban(): Promise<void>;
+    [util.inspect.custom](depth: number, options: util.InspectOptions, inspect: typeof util.inspect): string;
+}
+
+interface TextEmbedData {
+    type: "Text";
+    title?: string;
+    description?: string;
+    url?: string;
+    icon_url?: string;
+    colour?: string;
+    media?: string;
+}
+declare class EmbedBuilder {
+    private data;
+    constructor(data?: Partial<TextEmbedData>);
+    setTitle(title: string): this;
+    setDescription(description: string): this;
+    setUrl(url: string): this;
+    setIconUrl(iconUrl: string): this;
+    setColor(color: string): this;
+    setMedia(fileId: string): this;
+    /**
+     * Serializes the builder into the raw JSON required by the API
+     */
+    toJSON(): TextEmbedData;
+}
+
+interface MessageOptions {
+    content?: string;
+    embeds?: (TextEmbedData | EmbedBuilder)[];
+    attachments?: string[];
+    interactions?: any[];
+    flags?: number;
+    masquerade?: Masquerade;
+    replies?: ReplyIntent[];
+}
+interface Masquerade {
+    avatar?: string;
+    name?: string;
+    colour?: string;
+}
+interface ReplyIntent {
+    id: string;
+    mention: boolean;
+    fail_if_not_exists?: boolean;
+}
+interface Interaction {
+    reactions: string[];
+    restrictReactions: boolean;
+}
+declare class Message extends Base {
+    content: string | null;
+    authorId: string;
+    channelId: string;
+    embeds: any[];
+    attachments: Attachment[];
+    editedAt: Date | null;
+    createdAt: Date | null;
+    flags: number;
+    interactions: Interaction | null;
+    masquerade: Masquerade | null;
+    mentions: string[];
+    pinned: boolean;
+    reactions: any[];
+    replies: string[];
+    role_mentions: string[];
+    constructor(client: Client, data: any);
+    reply(contentOrOptions: string | MessageOptions): Promise<Message>;
+    /**
+     * Edits this message.
+     * @param contentOrOptions The new content or options for the message.
+     */
+    edit(contentOrOptions: string | MessageOptions): Promise<this>;
+    /**
+     * Deletes this message.
+     */
+    delete(): Promise<void>;
+    /**
+     * Pins this message.
+     */
+    pin(): Promise<void>;
+    /**
+     * Unpins this message.
+     */
+    unpin(): Promise<void>;
+    /** Gets the Channel object from cache */
+    get channel(): BaseChannel | undefined;
+    /** Gets the Global User object from cache */
+    get author(): User | undefined;
+    /** Gets the Server Member object (if sent in a server) */
+    get member(): Member | undefined;
+    /** Gets the Server ID if this message was sent in a server channel */
+    get serverId(): string | undefined;
+    /** Gets the Server object from cache */
+    get server(): Server | undefined;
+    _patch(data: any): void;
+    [util.inspect.custom](depth: number, options: util.InspectOptions, inspect: typeof util.inspect): string;
+}
+
+type UserResolvable = User | string;
+interface UserEditOptions {
+    avatar?: string | null;
+    displayName?: string | null;
+    profile?: UserProfile;
+    status?: UserStatus;
+}
+declare class UserManager extends BaseManager<string, User> {
+    constructor(client: Client, limit?: number);
+    /**
+     * Tell BaseManager how to find the ID for Users
+     */
+    protected extractId(data: any): string;
+    /**
+     * Tell BaseManager how to build a User
+     */
+    protected construct(data: any): User;
+    /**
+     * Resolves a UserResolvable to a User object from the cache.
+     */
+    resolve(user: UserResolvable): User | undefined;
+    /**
+     * Extracts ID from a UserResolvable.
+     * @param user The UserResolvable to extract the ID from.
+     * @returns The extracted user ID.
+     * @throws TypeError if an invalid type is provided.
+     */
+    resolveId(user: UserResolvable): string;
+    /**
+     * Fetches a User.
+     * @param user The ID or mention to fetch
+     * @param force Skip the cache check and force an API request
+     * @returns The fetched User object
+     * @throws Error if the user cannot be found or fetched
+     * @throws TypeError if invalid UserResolvable is provided
+     * @example
+     * // Fetch a user by ID
+     * const user = await client.users.fetch("01JE2MM759J5D7CHJF084R7MJ2");
+     * console.log(user.username);
+     *
+     * // Fetch a user by mention
+     * const user = await client.users.fetch("<@01JE2MM759J5D7CHJF084R7MJ2>");
+     * console.log(user.username);
+     *
+     * // Force fetch a user, bypassing the cache
+     * const user = await client.users.fetch("01JE2MM759J5D7CHJF084R7MJ2", true);
+     * console.log(user.username);
+     */
+    fetch(user: UserResolvable, force?: boolean): Promise<User>;
+    /**
+     * Fetch the current user (the bot itself).
+     * @returns The fetched User object representing the current user.
+     * @throws Error if the user cannot be fetched.
+     * @example
+     * // Fetch the current user (the bot itself)
+     * const me = await client.users.fetchMe();
+     * console.log(`Logged in as ${me.tag}`);
+     */
+    fetchMe(): Promise<User>;
+    /**
+     * Edits the currently authenticated user (the bot itself).
+     * @param options The fields to update (avatar, status, profile, etc.).
+     * @returns A promise that resolves to the updated User object.
+     * @throws {TypeError} If invalid options are provided.
+     * @throws {Error} If the API request fails.
+     * @example
+     * // Update the bot's status and presence
+     * await client.users.editMe({
+     *   status: { text: "Watching the server", presence: "Online" }
+     * });
+     *
+     * // Clear the bot's avatar and display name
+     * await client.users.editMe({ avatar: null, displayName: null });
+     */
+    editMe(options: UserEditOptions): Promise<User>;
+}
+
+/**
+ * Represents the authenticated bot's user object.
+ */
+declare class ClientUser extends User {
+    constructor(client: Client, data: any);
+}
+
+interface SweeperOptions {
+    messages?: {
+        lifetime: number;
+        interval: number;
+    };
+}
+declare class SweeperManager {
+    private client;
+    private options;
+    private messageInterval;
+    constructor(client: Client, options: SweeperOptions);
+    start(): void;
+    private sweepMessages;
+    stop(): void;
+}
+
+interface ClientEvents {
+    ready: [data: any];
+    messageCreate: [message: Message];
+    messageUpdate: [oldMessage: null | Message, newMessage: Message];
+    messageDelete: [message: Message | {
+        id: string;
+        channelId: string;
+    }];
+    error: [error: Error];
+    debug: [message: string];
+    raw: [data: any];
+    channelCreate: [channel: BaseChannel];
+    channelUpdate: [oldChannel: BaseChannel | null, newChannel: BaseChannel];
+    channelDelete: [channel: BaseChannel | string];
+    serverCreate: [server: Server];
+    serverUpdate: [oldServer: Server | null, newServer: Server];
+    serverDelete: [server: Server | string];
+    userUpdate: [oldUser: User, newUser: User];
+    serverMemberJoin: [member: Member];
+    serverMemberLeave: [member: Member];
+}
+interface ClientOptions {
+    sweepers?: SweeperOptions;
+    cacheLimits?: {
+        users?: number;
+        servers?: number;
+        channels?: number;
+    };
+}
+declare class Client extends EventEmitter {
+    options: ClientOptions;
+    rest: RESTManager;
+    gateway: GatewayManager;
+    channels: ChannelManager;
+    servers: ServerManager;
+    users: UserManager;
+    sweepers: SweeperManager;
+    user: ClientUser | null;
+    constructor(options?: ClientOptions);
+    /**
+     * Connects the bot to the Stoat Gateway
+     */
+    login(token: string): Promise<any>;
+    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;
+    emit<K extends keyof ClientEvents>(event: K, ...args: ClientEvents[K]): boolean;
+}
+
+/**
+ * A fallback class for channel types that are not yet officially supported by the library.
+ */
+declare class UnknownChannel extends BaseChannel {
+    constructor(client: Client, data: any);
+}
+
+export { Attachment, type AttachmentMetadata, Base, BaseChannel, type BotInformation, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, DMChannel, EmbedBuilder, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, type MessageFetchOptions, MessageManager, type MessageOptions, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };