@stoatx/client 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -31,8 +31,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Attachment: () => Attachment,
+  AttachmentBuilder: () => AttachmentBuilder,
   Base: () => Base,
   BaseChannel: () => BaseChannel,
+  BitField: () => BitField,
   ChannelManager: () => ChannelManager,
   ChannelType: () => ChannelType,
   Client: () => Client,
@@ -1240,9 +1242,9 @@ var RESTManager = class {
   /**
    * Uploads a file to Stoat's CDN and returns the File ID
    */
-  async uploadFile(filename, fileBuffer) {
+  async uploadFile(tag, fileBuffer, filename) {
     if (!this.token) throw new Error("REST_NOT_READY: No token available.");
-    const url = "https://cdn.stoatusercontent.com/attachments";
+    const url = `https://cdn.stoatusercontent.com/${tag}`;
     const formData = new FormData();
     formData.append("file", new Blob([fileBuffer]), filename);
     const response = await fetch(url, {
@@ -1310,6 +1312,42 @@ var BaseManager = class {
   }
 };
 
+// src/builders/AttachmentBuilder.ts
+var AttachmentBuilder = class {
+  // Filename for CDN to use, optional but recommended
+  filename = void 0;
+  file;
+  /**
+   * 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, filename) {
+    this.filename = filename;
+    this.file = file;
+  }
+  /**
+   * Uploads this attachment to the Stoat CDN and returns the resulting file ID.
+   * @internal — use `resolveAttachment()` instead of calling this directly.
+   */
+  async upload(rest, tag) {
+    return rest.uploadFile(tag, this.file, this.filename);
+  }
+};
+
+// src/utils/resolveAttachment.ts
+async function resolveAttachment(rest, value, tag) {
+  if (value instanceof AttachmentBuilder) {
+    return value.upload(rest, tag);
+  }
+  return value;
+}
+
 // src/managers/MessageManager.ts
 var MessageManager = class extends BaseManager {
   constructor(client, channel, limit = Infinity) {
@@ -1385,6 +1423,13 @@ var MessageManager = class extends BaseManager {
         (embed) => typeof embed.toJSON === "function" ? embed.toJSON() : embed
       );
     }
+    if (payload.attachments) {
+      payload.attachments = await Promise.all(
+        payload.attachments.map(
+          (attachment) => resolveAttachment(this.client.rest, attachment, "attachments")
+        )
+      );
+    }
     const data = await this.client.rest.post(`/channels/${this.channel.id}/messages`, payload);
     return new Message(this.client, data);
   }
@@ -1993,6 +2038,233 @@ function createChannel(client, data) {
   }
 }
 
+// src/utils/BitField.ts
+var BitField = class _BitField {
+  static Flags = {};
+  static DefaultBit = 0;
+  bitfield;
+  constructor(bits) {
+    this.bitfield = this.constructor.resolve(
+      bits ?? this.constructor.DefaultBit
+    );
+  }
+  /**
+   * 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) {
+    const resolved = this.constructor.resolve(bit);
+    if (typeof this.bitfield === "bigint" && typeof resolved === "bigint") {
+      return (this.bitfield & resolved) !== BigInt(0);
+    }
+    return (Number(this.bitfield) & Number(resolved)) !== 0;
+  }
+  /**
+   * 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) {
+    return this.bitfield === this.constructor.resolve(bit);
+  }
+  /**
+   * 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, ..._hasParams) {
+    const resolvedBit = this.constructor.resolve(bit);
+    if (typeof this.bitfield === "bigint" && typeof resolvedBit === "bigint") {
+      return (this.bitfield & resolvedBit) === resolvedBit;
+    }
+    return (Number(this.bitfield) & Number(resolvedBit)) === Number(resolvedBit);
+  }
+  /**
+   * 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, ...hasParams) {
+    return new this.constructor(bits).remove(this).toArray(...hasParams);
+  }
+  /**
+   * 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() {
+    return Object.freeze(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) {
+    let total = this.constructor.DefaultBit;
+    for (const bit of bits) {
+      const resolved = this.constructor.resolve(bit);
+      if (typeof total === "bigint" && typeof resolved === "bigint") {
+        total |= resolved;
+      } else {
+        total = Number(total) | Number(resolved);
+      }
+    }
+    if (typeof this.bitfield === "bigint" && typeof total === "bigint") {
+      if (Object.isFrozen(this)) return new this.constructor(this.bitfield | total);
+      this.bitfield |= total;
+    } else {
+      if (Object.isFrozen(this))
+        return new this.constructor(Number(this.bitfield) | Number(total));
+      this.bitfield = Number(this.bitfield) | Number(total);
+    }
+    return 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) {
+    let total = this.constructor.DefaultBit;
+    for (const bit of bits) {
+      const resolved = this.constructor.resolve(bit);
+      if (typeof total === "bigint" && typeof resolved === "bigint") {
+        total |= resolved;
+      } else {
+        total = Number(total) | Number(resolved);
+      }
+    }
+    if (typeof this.bitfield === "bigint" && typeof total === "bigint") {
+      if (Object.isFrozen(this)) return new this.constructor(this.bitfield & ~total);
+      this.bitfield &= ~total;
+    } else {
+      if (Object.isFrozen(this))
+        return new this.constructor(Number(this.bitfield) & ~Number(total));
+      this.bitfield = Number(this.bitfield) & ~Number(total);
+    }
+    return 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) {
+    const serialized = {};
+    for (const [flag, bit] of Object.entries(this.constructor.Flags)) {
+      if (isNaN(Number(flag))) serialized[flag] = this.has(bit, ...hasParams);
+    }
+    return serialized;
+  }
+  /**
+   * 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) {
+    return [...this[Symbol.iterator](...hasParams)];
+  }
+  /**
+   * 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() {
+    return typeof this.bitfield === "number" ? this.bitfield : this.bitfield.toString();
+  }
+  /**
+   * Returns the underlying numeric value of this bitfield.
+   * Allows BitField instances to be used directly in arithmetic expressions.
+   */
+  valueOf() {
+    return this.bitfield;
+  }
+  /**
+   * 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) {
+    for (const bitName of Object.keys(this.constructor.Flags)) {
+      if (isNaN(Number(bitName)) && this.has(bitName, ...hasParams)) yield bitName;
+    }
+  }
+  /**
+   * 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) {
+    const { DefaultBit } = this;
+    if (bit === void 0) return DefaultBit;
+    if (typeof DefaultBit === typeof bit && bit >= DefaultBit) return bit;
+    if (bit instanceof _BitField) return bit.bitfield;
+    if (Array.isArray(bit)) {
+      return bit.map((b) => this.resolve(b)).reduce((prev, b) => {
+        if (typeof prev === "bigint" && typeof b === "bigint") return prev | b;
+        return Number(prev) | Number(b);
+      }, DefaultBit);
+    }
+    if (typeof bit === "string") {
+      if (!isNaN(Number(bit))) return typeof DefaultBit === "bigint" ? BigInt(bit) : Number(bit);
+      if (this.Flags[bit] !== void 0) return this.Flags[bit];
+    }
+    throw new RangeError(`Invalid bitfield flag or number: ${String(bit)}`);
+  }
+};
+
 // src/utils/permissions.ts
 var PermissionFlags = {
   // Server permissions
@@ -2036,26 +2308,26 @@ var PermissionFlags = {
   // Grant all
   GrantAllSafe: 0x000fffffffffffffn
 };
-var Permissions = class {
-  /**
-   * Converts a string, BigInt, or array of strings into a single BigInt
-   */
-  static resolve(permission) {
-    if (typeof permission === "bigint") return permission;
-    if (typeof permission === "string") {
-      return PermissionFlags[permission] ?? 0n;
-    }
-    if (Array.isArray(permission)) {
-      return permission.reduce((acc, p) => acc | this.resolve(p), 0n);
-    }
-    return 0n;
+var Permissions = class extends BitField {
+  static Flags = PermissionFlags;
+  static DefaultBit = 0n;
+  static resolve(bit) {
+    return super.resolve(bit);
   }
-  /**
-   * Checks if a specific permission bit exists
-   */
-  static has(totalPermissions, permissionToCheck) {
-    const resolvedCheck = this.resolve(permissionToCheck);
-    return (totalPermissions & resolvedCheck) === resolvedCheck;
+  has(bit) {
+    return super.has(bit);
+  }
+  any(bit) {
+    return super.any(bit);
+  }
+  missing(bits) {
+    return super.missing(bits);
+  }
+  add(...bits) {
+    return super.add(...bits);
+  }
+  remove(...bits) {
+    return super.remove(...bits);
   }
 };
 
@@ -2164,7 +2436,7 @@ var ChannelManager = class extends BaseManager {
     }
     if (options.icon !== void 0) {
       if (options.icon === null) remove.push("Icon");
-      else payload.icon = options.icon;
+      else payload.icon = await resolveAttachment(this.client.rest, options.icon, "icons");
     }
     if (remove.length > 0) payload.remove = remove;
     if (Object.keys(payload).length === 0) return this.fetch(channel);
@@ -2410,15 +2682,15 @@ var Member = class extends Base {
   /** Calculates the member's total permissions using BigInt */
   get permissions() {
     const server = this.server;
-    if (!server) return 0n;
+    if (!server) return new Permissions(0n);
+    if (server.ownerId === this.id) {
+      return new Permissions(PermissionFlags.GrantAllSafe);
+    }
     let totalPerms = server.defaultPermissions ?? 0n;
     for (const role of this.roles.cache.values()) {
-      totalPerms |= BigInt(role.permissions);
+      totalPerms |= BigInt(role.permissions.bitfield);
     }
-    if (server.ownerId === this.id) {
-      return PermissionFlags.GrantAllSafe;
-    }
-    return totalPerms;
+    return new Permissions(totalPerms);
   }
   /** Get avatar URL for this member, or null if they don't have one.
    * @example
@@ -2482,10 +2754,6 @@ var Member = class extends Base {
   async setNickname(nickname) {
     return this.edit({ nickname });
   }
-  /** Checks if the member has a specific permission */
-  hasPermission(permission) {
-    return Permissions.has(this.permissions, permission);
-  }
   /**
    * Edit this member.
    * @param options The options to edit the member with (nickname, roles, timeout, etc.)
@@ -2752,7 +3020,8 @@ var Role = class extends Base {
   color = null;
   hoist = false;
   rank = 0;
-  permissions = 0n;
+  icon = null;
+  _permissions = 0n;
   constructor(client, data, serverId) {
     super(client, data);
     this.serverId = serverId;
@@ -2767,16 +3036,17 @@ var Role = class extends Base {
     if (data.color !== void 0) this.color = data.color;
     if (data.hoist !== void 0) this.hoist = data.hoist;
     if (data.rank !== void 0) this.rank = data.rank;
+    if (data.icon !== void 0) this.icon = new Attachment(this.client, data.icon);
     if (data.permissions !== void 0) {
       try {
         if (typeof data.permissions === "object" && data.permissions !== null) {
           const allowPerms = data.permissions.a ?? data.permissions[0] ?? 0;
-          this.permissions = BigInt(allowPerms);
+          this._permissions = BigInt(allowPerms);
         } else {
-          this.permissions = BigInt(data.permissions);
+          this._permissions = BigInt(data.permissions);
         }
       } catch {
-        this.permissions = 0n;
+        this._permissions = 0n;
       }
     }
   }
@@ -2788,12 +3058,10 @@ var Role = class extends Base {
     return this.client.servers.cache.get(this.serverId);
   }
   /**
-   * 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) {
-    return Permissions.has(this.permissions, permission);
+  get permissions() {
+    return new Permissions(this._permissions);
   }
   /**
    * Fetches this role directly from the API to ensure data is up to date.
@@ -2821,10 +3089,10 @@ var Role = class 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 });
    */
   async edit(options) {
     let server = this.server;
@@ -2883,6 +3151,73 @@ var Role = class extends Base {
     await server.roles.setRanks(filteredRoles);
     return this;
   }
+  /**
+   * 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}`);
+   */
+  async setName(name) {
+    return await this.edit({ name });
+  }
+  /**
+   * 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}`);
+   */
+  async setColor(color) {
+    return await this.edit({ color });
+  }
+  /**
+   * 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}`);
+   */
+  async setIcon(icon) {
+    return await this.edit({ icon });
+  }
+  /**
+   * 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}`);
+   */
+  async setHoist(hoist) {
+    return await this.edit({ hoist });
+  }
   /**
    * Customizer for Node.js `console.log` and `util.inspect`.
    * Hides the cyclic client reference and raw serverId for a cleaner output.
@@ -3020,7 +3355,7 @@ var RoleManager = class extends BaseManager {
   }
   /**
    * 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.
@@ -3041,11 +3376,18 @@ var RoleManager = class extends BaseManager {
     const remove = [];
     if (options.name !== void 0) payload.name = options.name;
     if (options.hoist !== void 0) payload.hoist = options.hoist;
-    if (options.colour !== void 0) {
-      if (options.colour === null) {
+    if (options.color !== void 0) {
+      if (options.color === null) {
         remove.push("Colour");
       } else {
-        payload.colour = options.colour;
+        payload.colour = options.color;
+      }
+    }
+    if (options.icon !== void 0) {
+      if (options.icon === null) {
+        remove.push("Icon");
+      } else {
+        payload.icon = await resolveAttachment(this.client.rest, options.icon, "icons");
       }
     }
     if (remove.length > 0) {
@@ -3774,8 +4116,10 @@ var EmbedBuilder = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Attachment,
+  AttachmentBuilder,
   Base,
   BaseChannel,
+  BitField,
   ChannelManager,
   ChannelType,
   Client,