@stoatx/client 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -18,6 +18,28 @@ declare class GatewayManager {
     disconnect(): void;
 }
 
+type CDNTag = "attachments" | "avatars" | "backgrounds" | "icons" | "banners" | "emojis";
+declare class AttachmentBuilder {
+    readonly filename: string | undefined;
+    readonly file: Buffer | Blob;
+    /**
+     * Creates a new AttachmentBuilder with the given file and optional filename.
+     * @param file The file data as a Buffer or Blob.
+     * @param filename An optional filename to use for the uploaded file. If not provided, the CDN will assign a default name.
+     *                 Providing a filename can help with organization and debugging, but is not strictly required.
+     * @example
+     * // Create an attachment from a Buffer with a custom filename
+     * const buffer = Buffer.from("Hello, world!");
+     * const attachment = new AttachmentBuilder(buffer, "greeting.txt");
+     */
+    constructor(file: Buffer | Blob, filename?: string);
+    /**
+     * Uploads this attachment to the Stoat CDN and returns the resulting file ID.
+     * @internal — use `resolveAttachment()` instead of calling this directly.
+     */
+    upload(rest: RESTManager, tag: CDNTag): Promise<string>;
+}
+
 /**
  * Custom Error class for Stoat API failures
  */
@@ -46,7 +68,7 @@ declare class RESTManager {
     /**
      * Uploads a file to Stoat's CDN and returns the File ID
      */
-    uploadFile(filename: string, fileBuffer: Buffer | Blob): Promise<string>;
+    uploadFile(tag: CDNTag, fileBuffer: Buffer | Blob, filename?: string): Promise<string>;
     get(endpoint: string): Promise<any>;
     post(endpoint: string, body?: any): Promise<any>;
     patch(endpoint: string, body?: any): Promise<any>;
@@ -346,6 +368,141 @@ declare class MemberManager extends BaseManager<string, Member> {
     [util.inspect.custom](): Collection<string, Member>;
 }
 
+type BitFieldResolvable = number | string | bigint | BitField | BitFieldResolvable[];
+declare class BitField {
+    static Flags: Record<string, number | bigint>;
+    static DefaultBit: number | bigint;
+    bitfield: number | bigint;
+    constructor(bits?: BitFieldResolvable);
+    /**
+     * Checks whether this bitfield has any of the given bits set.
+     *
+     * @param bit The bit(s) to test against.
+     * @returns `true` if at least one of the provided bits is set.
+     *
+     * @example
+     * perms.any(['SendMessage', 'ManageChannel']); // true if either is set
+     */
+    any(bit: BitFieldResolvable): boolean;
+    /**
+     * Checks whether this bitfield is exactly equal to the given bit value.
+     *
+     * @param bit The bit(s) to compare against.
+     * @returns `true` if the resolved bit value is identical to this bitfield.
+     *
+     * @example
+     * new Permissions(0n).equals(0n); // true
+     */
+    equals(bit: BitFieldResolvable): boolean;
+    /**
+     * Checks whether this bitfield has *all* of the given bits set.
+     *
+     * @param bit The bit(s) to check for.
+     * @returns `true` if every provided bit is set in this bitfield.
+     *
+     * @example
+     * perms.has('SendMessage');
+     * perms.has(['SendMessage', 'ViewChannel']); // true only if both are set
+     */
+    has(bit: BitFieldResolvable, ..._hasParams: any[]): boolean;
+    /**
+     * Returns the flag names present in `bits` that are *missing* from this bitfield.
+     *
+     * @param bits The bits to check against.
+     * @returns An array of flag name strings that are in `bits` but not in this bitfield.
+     *
+     * @example
+     * // If perms only has SendMessage:
+     * perms.missing(['SendMessage', 'ManageChannel']); // ['ManageChannel']
+     */
+    missing(bits: BitFieldResolvable, ...hasParams: any[]): string[];
+    /**
+     * Freezes this BitField instance, making it immutable.
+     * Subsequent calls to `add()` or `remove()` will return a new instance instead of mutating this one.
+     *
+     * @returns This instance, frozen.
+     */
+    freeze(): Readonly<this>;
+    /**
+     * Adds one or more bits to this bitfield.
+     * If the instance is frozen, returns a new BitField with the bits added.
+     *
+     * @param bits The bit(s) to add.
+     * @returns This instance (or a new one if frozen), with the bits added.
+     *
+     * @example
+     * perms.add('SendMessage', 'ViewChannel');
+     */
+    add(...bits: BitFieldResolvable[]): this;
+    /**
+     * Removes one or more bits from this bitfield.
+     * If the instance is frozen, returns a new BitField with the bits removed.
+     *
+     * @param bits The bit(s) to remove.
+     * @returns This instance (or a new one if frozen), with the bits cleared.
+     *
+     * @example
+     * perms.remove('ManageChannel');
+     */
+    remove(...bits: BitFieldResolvable[]): this;
+    /**
+     * Serializes this bitfield to a plain object mapping each flag name to a boolean
+     * indicating whether that flag is set.
+     *
+     * @returns A record of `{ [flagName]: boolean }` for all defined flags.
+     *
+     * @example
+     * perms.serialize();
+     * // { SendMessage: true, ManageChannel: false, ... }
+     */
+    serialize(...hasParams: any[]): Record<string, boolean>;
+    /**
+     * Returns an array of flag names that are set in this bitfield.
+     *
+     * @returns An array of string flag names.
+     *
+     * @example
+     * perms.toArray(); // ['SendMessage', 'ViewChannel']
+     */
+    toArray(...hasParams: any[]): string[];
+    /**
+     * Returns the bitfield value as a JSON-safe primitive.
+     * Numbers are returned as-is; bigints are converted to their string representation
+     * to avoid JSON serialization errors.
+     */
+    toJSON(): number | string;
+    /**
+     * Returns the underlying numeric value of this bitfield.
+     * Allows BitField instances to be used directly in arithmetic expressions.
+     */
+    valueOf(): number | bigint;
+    /**
+     * Iterates over the names of all flags that are set in this bitfield.
+     *
+     * @example
+     * for (const flag of perms) {
+     *   console.log(flag); // 'SendMessage', 'ViewChannel', etc.
+     * }
+     */
+    [Symbol.iterator](...hasParams: any[]): IterableIterator<string>;
+    /**
+     * Resolves a {@link BitFieldResolvable} into a raw `number | bigint`.
+     *
+     * Resolution rules (in order):
+     * - `undefined` → `DefaultBit`
+     * - A number or bigint matching `DefaultBit`'s type and >= 0 → returned as-is
+     * - A `BitField` instance → its `.bitfield` value
+     * - An array → each element resolved and OR'd together
+     * - A numeric string → parsed as `BigInt` or `Number` depending on `DefaultBit`'s type
+     * - A named string flag → looked up in `Flags`
+     * - Anything else → throws `RangeError`
+     *
+     * @param bit The value to resolve.
+     * @throws {RangeError} If the value cannot be resolved to a valid bit.
+     */
+    static resolve(bit?: BitFieldResolvable): number | bigint;
+}
+
 declare const PermissionFlags: {
     readonly ManageChannel: bigint;
     readonly ManageServer: bigint;
@@ -383,16 +540,16 @@ declare const PermissionFlags: {
     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;
+type PermissionResolvable = PermissionString | bigint | number | Permissions | PermissionResolvable[];
+declare class Permissions extends BitField {
+    static Flags: Record<string, number | bigint>;
+    static DefaultBit: bigint;
+    static resolve(bit?: PermissionResolvable): bigint;
+    has(bit: PermissionResolvable): boolean;
+    any(bit: PermissionResolvable): boolean;
+    missing(bits: PermissionResolvable): PermissionString[];
+    add(...bits: PermissionResolvable[]): this;
+    remove(...bits: PermissionResolvable[]): this;
 }
 
 declare class DMChannel extends BaseChannel {
@@ -639,7 +796,7 @@ interface ChannelEditOptions {
     name?: string;
     description?: string | null;
     owner?: string;
-    icon?: string | null;
+    icon?: string | AttachmentBuilder | null;
     nsfw?: boolean;
     archived?: boolean;
     voice?: {
@@ -1104,7 +1261,8 @@ declare class Role extends Base {
     color: string | null;
     hoist: boolean;
     rank: number;
-    permissions: bigint;
+    icon: Attachment | null;
+    private _permissions;
     constructor(client: Client, data: any, serverId: string);
     /**
      * Updates the role instance with new data without losing the object reference.
@@ -1117,11 +1275,9 @@ declare class Role extends Base {
      */
     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.
+     * Permissions for this role
      */
-    hasPermission(permission: PermissionResolvable): boolean;
+    get permissions(): Permissions;
     /**
      * 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.
@@ -1133,7 +1289,7 @@ declare class Role extends Base {
      * await role.fetch();
      * console.log(`Role updated, current name: ${role.name}`);
      */
-    fetch(force?: boolean): Promise<this>;
+    fetch(force?: boolean): Promise<Role>;
     /**
      * 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.
@@ -1142,12 +1298,12 @@ declare class Role extends Base {
      * @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" });
+     * await role.edit({ name: "Senior Admin", color: "#FFD700" });
      *
      * // Remove the custom color from the role
-     * await role.edit({ colour: null });
+     * await role.edit({ color: null });
      */
-    edit(options: RoleEditOptions): Promise<this>;
+    edit(options: RoleEditOptions): Promise<Role>;
     /**
      * Deletes this Role from the server.
      * @throws {Error} If the role cannot be deleted (e.g., lack of permissions).
@@ -1168,7 +1324,7 @@ declare class Role extends Base {
      *   allow: ["ManageChannel", "SendMessage"]
      * });
      */
-    setPermissions(options: RolePermissionOptions): Promise<this>;
+    setPermissions(options: RolePermissionOptions): Promise<Role>;
     /**
      * Updates the hierarchical position of this role.
      * Automatically reconstructs the role array and performs a bulk update.
@@ -1180,7 +1336,66 @@ declare class Role extends Base {
      * await role.setPosition(2);
      * console.log(`Role moved to rank: ${role.rank}`);
      */
-    setPosition(newPosition: number): Promise<this>;
+    setPosition(newPosition: number): Promise<Role>;
+    /**
+     * Change the name for this role
+     * @param name The new name for the role
+     * @returns A promise that resolves to this updated Role object.
+     * @throws {Error} If API request fails.
+     * @example
+     * // Change the role's name
+     * await role.setName("New Role Name");
+     * console.log(`Role's new name: ${role.name}`);
+     */
+    setName(name: string): Promise<Role>;
+    /**
+     * Change the color for this role, it can be a HEX or CSS colours
+     * @param {[string]} color The new color for the role
+     * @returns A promise that resolves to this updated Role object.
+     * @throws {Error} If API request fails
+     * @example
+     * // Change the role's color
+     * await role.setColour("#FF0000");
+     * console.log(`Role's new color: ${role.color}`);
+     *
+     * // Use CSS color linear-graident
+     * await role.setColour("linear-gradient(90deg, #FF0000, #0000FF)");
+     * console.log(`Role's new color: ${role.color}`);
+     *
+     * // Remove the custom color from the role
+     * await role.setColour(null);
+     * console.log(`Role's color removed, current color: ${role.color}`);
+     */
+    setColor(color: string | null): Promise<Role>;
+    /**
+     * Edit the icon of this role
+     * @param icon Autumn ID for the new icon, or null to remove the custom icon
+     * @returns A promise that resolves to this updated Role object.
+     * @throws {Error} If API request fails
+     * @example
+     * // Set a new icon for the role
+     * await role.setIcon("AUTUMN_ID_FOR_ICON");
+     * console.log(`Role's new icon: ${role.icon}`);
+     *
+     * // Use AttachmentBuilder to upload a new icon file
+     * import { readFile } from "node:fs/promises";
+     * const iconFile = await readFile("./a.jpg");
+     * const attachment = new AttachmentBuilder(iconFile, "a.jpg");
+     * await role.setIcon(attachment);
+     * console.log(`Role's new icon: ${role.icon}`);
+     */
+    setIcon(icon: string | AttachmentBuilder | null): Promise<Role>;
+    /**
+     * Change the hoist status for this role
+     * @param hoist The new hoist status for the role
+     * @returns A promise that resolves to this updated Role object.
+     * @throws {Error} If API request fails
+     * @example
+     * // Enable hoisting for the role
+     * await role.setHoist(true);
+     * console.log(`Role is now hoisted: ${role.hoist}`);
+     */
+    setHoist(hoist: boolean): Promise<Role>;
     /**
      * Customizer for Node.js `console.log` and `util.inspect`.
      * Hides the cyclic client reference and raw serverId for a cleaner output.
@@ -1194,8 +1409,9 @@ interface RoleCreateOptions {
 }
 interface RoleEditOptions {
     name?: string;
-    colour?: string | null;
+    color?: string | null;
     hoist?: boolean;
+    icon?: string | AttachmentBuilder | null;
 }
 interface RolePermissionOptions {
     allow?: PermissionResolvable;
@@ -1273,7 +1489,7 @@ declare class RoleManager extends BaseManager<string, Role> {
     fetch(role: RoleResolvable, force?: boolean): Promise<Role>;
     /**
      * Edits an existing role in the server.
-     * @param role The RoleResolvable to edit.
+     * @param role The {@link 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.
@@ -1552,7 +1768,7 @@ declare class Member extends Base {
     /** Gets the Server object this member belongs to */
     get server(): Server | undefined;
     /** Calculates the member's total permissions using BigInt */
-    get permissions(): bigint;
+    get permissions(): Permissions;
     /** Get avatar URL for this member, or null if they don't have one.
      * @example
      * // Get a member's avatar URL
@@ -1599,8 +1815,6 @@ declare class Member extends Base {
      */
     send(options: string | MessageOptions): Promise<Message>;
     setNickname(nickname: string): Promise<Member>;
-    /** Checks if the member has a specific permission */
-    hasPermission(permission: PermissionResolvable): boolean;
     /**
      * Edit this member.
      * @param options The options to edit the member with (nickname, roles, timeout, etc.)
@@ -1692,7 +1906,7 @@ declare class ReactionCollector extends Collector<string, MessageReaction> {
 interface MessageOptions {
     content?: string;
     embeds?: (TextEmbedData | EmbedBuilder)[];
-    attachments?: string[];
+    attachments?: string[] | AttachmentBuilder[];
     interactions?: any[];
     flags?: number;
     masquerade?: Masquerade;
@@ -1906,4 +2120,4 @@ 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, Collector, type CollectorOptions, DMChannel, EmbedBuilder, Emoji, EmojiManager, type EmojiParent, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, MessageCollector, type MessageCollectorOptions, type MessageFetchOptions, MessageManager, type MessageOptions, MessageReaction, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, ReactionCollector, type ReactionCollectorOptions, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, StoatAPIError, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };
+export { Attachment, AttachmentBuilder, type AttachmentMetadata, Base, BaseChannel, BitField, type BitFieldResolvable, type BotInformation, type CDNTag, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, Collector, type CollectorOptions, DMChannel, EmbedBuilder, Emoji, EmojiManager, type EmojiParent, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, MessageCollector, type MessageCollectorOptions, type MessageFetchOptions, MessageManager, type MessageOptions, MessageReaction, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, ReactionCollector, type ReactionCollectorOptions, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, StoatAPIError, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };