@erinjs/core 1.0.0

package/core/packages/fluxer-core/src/structures/Message.ts

@@ -0,0 +1,397 @@
+import { Client } from '../client/Client.js';
+import { Base } from './Base.js';
+import { Collection } from '@erinjs/collection';
+import {
+  APIMessage,
+  APIMessageAttachment,
+  APIMessageReaction,
+  APIMessageSticker,
+  APIMessageReference,
+  APIMessageSnapshot,
+  APIMessageCall,
+  APIEmbed,
+  APIUserPartial,
+} from '@erinjs/types';
+import { MessageType, MessageFlags, Routes } from '@erinjs/types';
+import { EmbedBuilder } from '@erinjs/builders';
+import { User } from './User.js';
+import { Channel, TextChannel, DMChannel, GuildChannel } from './Channel.js';
+import { Guild } from './Guild.js';
+
+import {
+  buildSendBody,
+  resolveMessageFiles,
+  type MessageSendOptions,
+  SendBodyResult,
+  ResolvedMessageFile,
+} from '../util/messageUtils.js';
+import { ReactionCollector } from '../util/ReactionCollector.js';
+import { ReactionCollectorOptions } from '../util/ReactionCollector.js';
+
+/** Options for editing a message (content and/or embeds). */
+export interface MessageEditOptions {
+  /** New text content */
+  content?: string;
+  /** New embeds (replaces existing) */
+  embeds?: (APIEmbed | EmbedBuilder)[];
+}
+
+export type MessagePayload = {
+  files?: ResolvedMessageFile[];
+  body: SendBodyResult & { message_reference?: APIMessageReference; flags?: number };
+};
+
+/** Options for message.reply() — ping toggle and reply-to-different-message. */
+export interface ReplyOptions {
+  /** Whether to ping the replied-to user (default true). Use false to suppress the mention notification. */
+  ping?: boolean;
+  /** Reply to a different message instead of this one. Default: this message. */
+  replyTo?: Message | { channelId: string; messageId: string };
+}
+
+/** Re-export for convenience. */
+export type { MessageSendOptions } from '../util/messageUtils.js';
+
+/** Represents a message in a channel. */
+export 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>;
+  readonly type: MessageType;
+  readonly flags: number;
+  readonly mentionEveryone: boolean;
+  readonly tts: boolean;
+  readonly embeds: APIEmbed[];
+  readonly stickers: APIMessageSticker[];
+  readonly reactions: APIMessageReaction[];
+  readonly messageReference: APIMessageReference | null;
+  readonly messageSnapshots: APIMessageSnapshot[];
+  readonly call: APIMessageCall | null;
+  readonly referencedMessage: Message | null;
+  /** Webhook ID if this message was sent via webhook. Null otherwise. */
+  readonly webhookId: string | null;
+  /** Users mentioned in this message. */
+  readonly mentions: User[];
+  /** Role IDs mentioned in this message. */
+  readonly mentionRoles: string[];
+  /** Client-side nonce for acknowledgment. Null if not provided. */
+  readonly nonce: string | null;
+
+  /**
+   * Channel where this message was sent. Resolved from cache; null if not cached.
+   * Messages can only exist in text-based channels (text, DM, announcement), so this always has send() when non-null.
+   */
+  get channel(): (TextChannel | DMChannel | GuildChannel) | null {
+    return (this.client.channels.get(this.channelId) ?? null) as
+      | (TextChannel | DMChannel | GuildChannel)
+      | null;
+  }
+
+  /** Guild where this message was sent. Resolved from cache; null for DMs or if not cached. */
+  get guild(): Guild | null {
+    return this.guildId ? (this.client.guilds.get(this.guildId) ?? null) : null;
+  }
+
+  /**
+   * Resolve the channel (from cache or API). Use when you need the channel and it may not be cached.
+   * @returns The channel
+   * @throws FluxerError with CHANNEL_NOT_FOUND if the channel does not exist
+   */
+  async resolveChannel(): Promise<Channel> {
+    return this.client.channels.resolve(this.channelId);
+  }
+
+  /**
+   * Resolve the guild (from cache or API). Returns null for DMs.
+   * @returns The guild, or null if this is a DM or guild not found
+   */
+  async resolveGuild(): Promise<Guild | null> {
+    return this.guildId ? this.client.guilds.resolve(this.guildId) : null;
+  }
+
+  /** @param data - API message from POST/PATCH /channels/{id}/messages or gateway MESSAGE_CREATE */
+  constructor(client: Client, data: APIMessage) {
+    super();
+    this.client = client;
+    this.id = data.id;
+    this.channelId = data.channel_id;
+    this.guildId = data.guild_id ?? null;
+    this.author = client.getOrCreateUser(data.author);
+    this.content = data.content;
+    this.createdAt = new Date(data.timestamp);
+    this.editedAt = data.edited_timestamp ? new Date(data.edited_timestamp) : null;
+    this.pinned = data.pinned;
+    this.attachments = new Collection();
+    for (const a of data.attachments ?? []) this.attachments.set(a.id, a);
+    this.type = (data.type ?? MessageType.Default) as MessageType;
+    this.flags = data.flags ?? 0;
+    this.mentionEveryone = data.mention_everyone ?? false;
+    this.tts = data.tts ?? false;
+    this.embeds = data.embeds ?? [];
+    this.stickers = data.stickers ?? [];
+    this.reactions = data.reactions ?? [];
+    this.messageReference = data.message_reference ?? null;
+    this.messageSnapshots = data.message_snapshots ?? [];
+    this.call = data.call ?? null;
+    this.referencedMessage = data.referenced_message
+      ? new Message(client, data.referenced_message)
+      : null;
+    this.webhookId = data.webhook_id ?? null;
+    this.mentions = (data.mentions ?? []).map((u) => client.getOrCreateUser(u));
+    this.mentionRoles = data.mention_roles ?? [];
+    this.nonce = data.nonce ?? null;
+  }
+
+  /**
+   * Send a message to this channel without replying. Use when you want a standalone message.
+   * @param options - Text content or object with content, embeds, and/or files
+   * @example
+   * await message.send('Pong!');
+   * await message.send({ embeds: [embed] }); // EmbedBuilder auto-converted
+   * await message.send({ content: 'File', files: [{ name: 'data.txt', data }] });
+   */
+  async send(options: string | MessageSendOptions): Promise<Message> {
+    const payload = await Message._createMessageBody(options);
+    return this._send(payload);
+  }
+
+  /**
+   * Send a message to a specific channel. Use for logging, forwarding, or sending to another channel in the guild.
+   * @param channelId - Snowflake of the target channel (e.g. log channel ID)
+   * @param options - Text content or object with content and/or embeds
+   * @example
+   * await message.sendTo(logChannelId, 'User ' + message.author.username + ' said: ' + message.content);
+   * await message.sendTo(announceChannelId, { embeds: [embed] });
+   */
+  async sendTo(channelId: string, options: MessageSendOptions): Promise<Message> {
+    return this.client.channels.send(channelId, options);
+  }
+
+  /**
+   * Reply to this message (shows as a reply in the client).
+   * @param options - Text content or object with content, embeds, and/or reply options (ping, replyTo)
+   * @example
+   * await message.reply('Pong!');
+   * await message.reply({ embeds: [embed] });
+   * await message.reply('No ping!', { ping: false });
+   * await message.reply({ content: 'Reply to other', replyTo: otherMessage });
+   */
+  async reply(
+    options: string | (MessageSendOptions & ReplyOptions),
+    replyOptions?: ReplyOptions,
+  ): Promise<Message> {
+    const opts = typeof options === 'string' ? { content: options } : options;
+    const mergedReply: ReplyOptions | undefined =
+      (replyOptions ?? (opts.ping !== undefined || opts.replyTo !== undefined))
+        ? { ping: opts.ping, replyTo: opts.replyTo }
+        : undefined;
+
+    const refMessage = mergedReply?.replyTo ?? this;
+    const ref =
+      refMessage instanceof Message
+        ? {
+            channel_id: refMessage.channelId,
+            message_id: refMessage.id,
+            guild_id: refMessage.guildId ?? undefined,
+          }
+        : {
+            channel_id: refMessage.channelId,
+            message_id: refMessage.messageId,
+            guild_id: undefined as string | undefined,
+          };
+
+    const payload = await Message._createMessageBody(opts, ref, mergedReply?.ping !== false);
+    return this._send(payload);
+  }
+
+  /** Exposed for testing purposes, use Message.reply() or send() for normal use */
+  static async _createMessageBody(
+    content: string | MessageSendOptions,
+    referenced_message?: { channel_id: string; message_id: string; guild_id?: string },
+    ping?: boolean,
+  ): Promise<MessagePayload> {
+    if (typeof content === 'string') {
+      if (content.length === 0) {
+        throw new RangeError('Cannot send an empty message');
+      }
+      content = { content };
+    }
+    const base = buildSendBody(content);
+    const files = content.files?.length ? await resolveMessageFiles(content.files) : undefined;
+    const body: MessagePayload['body'] = { ...base };
+    if (referenced_message) {
+      body.message_reference = referenced_message;
+      if (ping === false) {
+        body.flags = (body.flags ?? 0) | MessageFlags.SuppressNotifications;
+      }
+    }
+    return { files, body };
+  }
+
+  async _send(payload: MessagePayload): Promise<Message> {
+    const data = await this.client.rest.post<APIMessage>(
+      Routes.channelMessages(this.channelId),
+      payload,
+    );
+    this.client._addMessageToCache(this.channelId, data);
+    return new Message(this.client, data);
+  }
+
+  /**
+   * Edit this message. Only the author (or admins) can edit.
+   * @param options - New content and/or embeds
+   */
+  async edit(options: MessageEditOptions): Promise<Message> {
+    const body: { content?: string; embeds?: APIEmbed[] } = {};
+    if (options.content !== undefined) body.content = options.content;
+    if (options.embeds?.length) {
+      body.embeds = options.embeds.map((e) => (e instanceof EmbedBuilder ? e.toJSON() : e));
+    }
+    const data = await this.client.rest.patch(Routes.channelMessage(this.channelId, this.id), {
+      body,
+    });
+    return new Message(this.client, data as APIMessage);
+  }
+
+  /**
+   * Create a reaction collector for this message.
+   * Collects reactions matching the filter until time expires or max is reached.
+   * @param options - Filter, time (ms), and max count
+   * @example
+   * const collector = message.createReactionCollector({ filter: (r, u) => u.id === userId, time: 10000 });
+   * collector.on('collect', (reaction, user) => console.log(user.username, 'reacted with', reaction.emoji.name));
+   * collector.on('end', (collected, reason) => { ... });
+   */
+  createReactionCollector(options?: ReactionCollectorOptions): ReactionCollector {
+    return new ReactionCollector(this.client, this.id, this.channelId, options);
+  }
+
+  /**
+   * Re-fetch this message from the API to get the latest content, embeds, reactions, etc.
+   * Use when you have a stale Message (e.g. from an old event or cache) and need fresh data.
+   * @returns The updated message
+   * @throws FluxerError with MESSAGE_NOT_FOUND if the message was deleted or does not exist
+   * @example
+   * const updated = await message.fetch();
+   * console.log('Latest content:', updated.content);
+   */
+  async fetch(): Promise<Message> {
+    return this.client.channels.fetchMessage(this.channelId, this.id);
+  }
+
+  /** Delete this message. */
+  async delete(): Promise<void> {
+    await this.client.rest.delete(Routes.channelMessage(this.channelId, this.id));
+  }
+
+  /**
+   * Delete a specific attachment from this message.
+   * DELETE /channels/{id}/messages/{id}/attachments/{attachmentId}.
+   */
+  async deleteAttachment(attachmentId: string): Promise<void> {
+    await this.client.rest.delete(
+      Routes.channelMessageAttachment(this.channelId, this.id, attachmentId),
+      { auth: true },
+    );
+    this.attachments.delete(attachmentId);
+  }
+
+  /** Pin this message to the channel. Requires Manage Messages permission. */
+  async pin(): Promise<void> {
+    await this.client.rest.put(Routes.channelPinMessage(this.channelId, this.id));
+    this.pinned = true;
+  }
+
+  /** Unpin this message from the channel. Requires Manage Messages permission. */
+  async unpin(): Promise<void> {
+    await this.client.rest.delete(Routes.channelPinMessage(this.channelId, this.id));
+    this.pinned = false;
+  }
+
+  /**
+   * Format emoji for reaction API: unicode string or "name:id" for custom.
+   * For string resolution (e.g. :name:), use client.resolveEmoji; Message methods resolve automatically when guildId is available.
+   */
+  private static formatEmoji(emoji: string | { name: string; id: string }): string {
+    if (typeof emoji === 'string') return emoji;
+    return `${emoji.name}:${emoji.id}`;
+  }
+
+  private resolveEmojiForReaction(
+    emoji: string | { name: string; id?: string; animated?: boolean },
+  ): Promise<string> {
+    return this.client.resolveEmoji(emoji, this.guildId);
+  }
+
+  /**
+   * Add a reaction to this message (as the bot).
+   * @param emoji - Unicode emoji, custom `{ name, id }`, `:name:`, `name:id`, or `<:name:id>`
+   */
+  async react(emoji: string | { name: string; id?: string; animated?: boolean }): Promise<void> {
+    const emojiStr = await this.resolveEmojiForReaction(emoji);
+    const route = `${Routes.channelMessageReaction(this.channelId, this.id, emojiStr)}/@me`;
+    await this.client.rest.put(route);
+  }
+
+  /**
+   * Remove the bot's reaction, or a specific user's reaction if userId is provided.
+   * @param emoji - Unicode emoji, custom `{ name, id }`, `:name:`, `name:id`, or `<:name:id>`
+   * @param userId - If provided, removes that user's reaction (requires moderator permissions)
+   */
+  async removeReaction(
+    emoji: string | { name: string; id?: string; animated?: boolean },
+    userId?: string,
+  ): Promise<void> {
+    const emojiStr = await this.resolveEmojiForReaction(emoji);
+    const route = `${Routes.channelMessageReaction(this.channelId, this.id, emojiStr)}/${userId ?? '@me'}`;
+    await this.client.rest.delete(route);
+  }
+
+  /**
+   * Remove all reactions from this message.
+   * Requires moderator permissions.
+   */
+  async removeAllReactions(): Promise<void> {
+    await this.client.rest.delete(Routes.channelMessageReactions(this.channelId, this.id));
+  }
+
+  /**
+   * Remove all reactions of a specific emoji from this message.
+   * @param emoji - Unicode emoji, custom `{ name, id }`, `:name:`, `name:id`, or `<:name:id>`. Requires moderator permissions.
+   */
+  async removeReactionEmoji(
+    emoji: string | { name: string; id?: string; animated?: boolean },
+  ): Promise<void> {
+    const emojiStr = await this.resolveEmojiForReaction(emoji);
+    await this.client.rest.delete(Routes.channelMessageReaction(this.channelId, this.id, emojiStr));
+  }
+
+  /**
+   * Fetch users who reacted with the given emoji.
+   * @param emoji - Unicode emoji or custom `{ name, id }`
+   * @param options - limit (1–100), after (user ID for pagination)
+   * @returns Array of User objects
+   */
+  async fetchReactionUsers(
+    emoji: string | { name: string; id?: string; animated?: boolean },
+    options?: { limit?: number; after?: string },
+  ): Promise<User[]> {
+    const emojiStr = await this.resolveEmojiForReaction(emoji);
+    const params = new URLSearchParams();
+    if (options?.limit != null) params.set('limit', String(options.limit));
+    if (options?.after) params.set('after', options.after);
+    const qs = params.toString();
+    const route =
+      Routes.channelMessageReaction(this.channelId, this.id, emojiStr) + (qs ? `?${qs}` : '');
+    const data = await this.client.rest.get<{ users?: APIUserPartial[] } | APIUserPartial[]>(route);
+    const list = Array.isArray(data) ? data : (data?.users ?? []);
+    return list.map((u) => this.client.getOrCreateUser(u));
+  }
+}

package/core/packages/fluxer-core/src/structures/MessageReaction.ts

@@ -0,0 +1,72 @@
+import { APIMessage, Routes } from '@erinjs/types';
+import { FluxerAPIError, RateLimitError } from '@erinjs/rest';
+import { FluxerError } from '../errors/FluxerError.js';
+import { ErrorCodes } from '../errors/ErrorCodes.js';
+import { Client } from '../client/Client.js';
+import { Base } from './Base.js';
+import { Message } from './Message.js';
+import { Guild } from './Guild.js';
+import {
+  GatewayMessageReactionAddDispatchData,
+  GatewayMessageReactionRemoveDispatchData,
+  GatewayReactionEmoji,
+} from '@erinjs/types';
+
+/** Represents a reaction added to or removed from a message. */
+export class MessageReaction extends Base {
+  readonly client: Client;
+  readonly messageId: string;
+  readonly channelId: string;
+  readonly guildId: string | null;
+  readonly emoji: GatewayReactionEmoji;
+  /** Raw gateway payload for low-level access. */
+  readonly _data: GatewayMessageReactionAddDispatchData | GatewayMessageReactionRemoveDispatchData;
+
+  constructor(
+    client: Client,
+    data: GatewayMessageReactionAddDispatchData | GatewayMessageReactionRemoveDispatchData,
+  ) {
+    super();
+    this.client = client;
+    this._data = data;
+    this.messageId = data.message_id;
+    this.channelId = data.channel_id;
+    this.guildId = data.guild_id ?? null;
+    this.emoji = data.emoji;
+  }
+
+  /** Emoji as a string: unicode or "name:id" for custom. */
+  get emojiIdentifier(): string {
+    return this.emoji.id ? `${this.emoji.name}:${this.emoji.id}` : this.emoji.name;
+  }
+
+  /** Guild where this reaction was added. Resolved from cache; null for DMs or if not cached. */
+  get guild(): Guild | null {
+    return this.guildId ? (this.client.guilds.get(this.guildId) ?? null) : null;
+  }
+
+  /**
+   * Fetch the message this reaction belongs to.
+   * Use when you need to edit, delete, or otherwise interact with the message.
+   * @throws FluxerError with MESSAGE_NOT_FOUND if the message does not exist
+   */
+  async fetchMessage(): Promise<Message> {
+    try {
+      const data = await this.client.rest.get<APIMessage>(
+        Routes.channelMessage(this.channelId, this.messageId),
+      );
+      return new Message(this.client, data);
+    } catch (err) {
+      if (err instanceof RateLimitError) throw err;
+      if (err instanceof FluxerAPIError && err.statusCode === 404) {
+        throw new FluxerError(`Message ${this.messageId} not found in channel ${this.channelId}`, {
+          code: ErrorCodes.MessageNotFound,
+          cause: err,
+        });
+      }
+      throw err instanceof FluxerError
+        ? err
+        : new FluxerError(String(err), { cause: err as Error });
+    }
+  }
+}

package/core/packages/fluxer-core/src/structures/PartialMessage.ts

@@ -0,0 +1,12 @@
+import { Channel } from './Channel.js';
+
+/** Minimal message data for MessageDelete when the full message is not available. */
+export interface PartialMessage {
+  id: string;
+  channelId: string;
+  channel?: Channel | null;
+  /** Message content, when provided by the gateway (e.g. Fluxer). */
+  content?: string | null;
+  /** Author user ID, when provided by the gateway (e.g. Fluxer). */
+  authorId?: string | null;
+}

package/core/packages/fluxer-core/src/structures/Role.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { Client, Role } from '../';
+import { PermissionFlags } from '@erinjs/util';
+
+function createMockClient() {
+  return {} as Client;
+}
+
+function createRole(
+  permissions: string | bigint,
+  overrides: Partial<{ id: string; name: string }> = {},
+) {
+  return new Role(
+    createMockClient(),
+    {
+      permissions: permissions.toString(),
+      id: overrides.id ?? '1',
+      name: overrides.name ?? 'Role',
+      color: 0,
+      position: 0,
+      hoist: false,
+      mentionable: false,
+    },
+    'guild1',
+  );
+}
+
+describe('Role.permissions', () => {
+  describe('has()', () => {
+    it('returns true when role has Administrator (grants all permissions)', () => {
+      const role = createRole(PermissionFlags.Administrator); // 1 << 3 = Administrator
+      expect(role.permissions.has(PermissionFlags.Administrator)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.SendMessages)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.BanMembers)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.ManageChannels)).toBe(true);
+    });
+
+    it('returns true when role has specific permission', () => {
+      const role = createRole('2048'); // SendMessages
+      expect(role.permissions.has(PermissionFlags.SendMessages)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.BanMembers)).toBe(false);
+      expect(role.permissions.has(PermissionFlags.ViewChannel)).toBe(false);
+    });
+
+    it('returns true for string permission name', () => {
+      const role = createRole(PermissionFlags.SendMessages);
+      expect(role.permissions.has('SendMessages')).toBe(true);
+      expect(role.permissions.has('BanMembers')).toBe(false);
+    });
+
+    it('returns false when role has no permissions', () => {
+      const role = createRole('0');
+      expect(role.permissions.has(PermissionFlags.SendMessages)).toBe(false);
+      expect(role.permissions.has(PermissionFlags.Administrator)).toBe(false);
+    });
+
+    it('throws an error for invalid permission name', () => {
+      const role = createRole(PermissionFlags.Administrator);
+      expect(() => role.permissions.has('NonExistent' as never)).toThrow(RangeError);
+    });
+
+    it('handles combined permission bitfield', () => {
+      // SendMessages (2048) | ViewChannel (1024) = 3072
+      const role = createRole(String(PermissionFlags.SendMessages | PermissionFlags.ViewChannel));
+      expect(role.permissions.has(PermissionFlags.SendMessages)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.ViewChannel)).toBe(true);
+      expect(role.permissions.has(PermissionFlags.BanMembers)).toBe(false);
+    });
+  });
+
+  describe('toString()', () => {
+    it('returns role mention format', () => {
+      const role = createRole('0', { id: '123456789' });
+      expect(role.toString()).toBe('<@&123456789>');
+    });
+  });
+});

package/core/packages/fluxer-core/src/structures/Role.ts

@@ -0,0 +1,112 @@
+import { Client } from '../client/Client.js';
+import { Base } from './Base.js';
+import { APIRole, RESTUpdateRoleBody } from '@erinjs/types';
+import { Routes } from '@erinjs/types';
+import {
+  PermissionFlags,
+  resolvePermissionsToBitfield,
+  type PermissionResolvable,
+  ALL_PERMISSIONS_BIGINT,
+  PermissionsBitField,
+} from '@erinjs/util';
+
+/** Represents a role in a guild. */
+export class Role extends Base {
+  readonly client: Client;
+  readonly id: string;
+  readonly guildId: string;
+  name: string;
+  color: number;
+  position: number;
+  _permissions: string;
+  hoist: boolean;
+  mentionable: boolean;
+  unicodeEmoji: string | null;
+  /** Separately sorted position for hoisted roles. Null if not set. */
+  hoistPosition: number | null;
+
+  /** @param client - The client instance */
+  /** @param data - API role from GET /guilds/{id}/roles or gateway role events */
+  /** @param guildId - The guild this role belongs to */
+  constructor(client: Client, data: APIRole, guildId: string) {
+    super();
+    this.client = client;
+    this.id = data.id;
+    this.guildId = guildId;
+    this.name = data.name;
+    this.color = data.color;
+    this.position = data.position;
+    this._permissions = data.permissions;
+    this.hoist = !!data.hoist;
+    this.mentionable = !!data.mentionable;
+    this.unicodeEmoji = data.unicode_emoji ?? null;
+    this.hoistPosition = data.hoist_position ?? null;
+  }
+
+  get permissions(): PermissionsBitField {
+    const bits = BigInt(this._permissions);
+    return new PermissionsBitField(
+      (bits & PermissionFlags.Administrator) !== 0n ? ALL_PERMISSIONS_BIGINT : bits,
+    );
+  }
+
+  /** Update mutable fields from fresh API data. Used by edit and gateway events. */
+  _patch(data: Partial<APIRole>): void {
+    if (data.name !== undefined) this.name = data.name;
+    if (data.color !== undefined) this.color = data.color;
+    if (data.position !== undefined) this.position = data.position;
+    if (data.permissions !== undefined) this._permissions = data.permissions;
+    if (data.hoist !== undefined) this.hoist = !!data.hoist;
+    if (data.mentionable !== undefined) this.mentionable = !!data.mentionable;
+    if (data.unicode_emoji !== undefined) this.unicodeEmoji = data.unicode_emoji ?? null;
+    if (data.hoist_position !== undefined) this.hoistPosition = data.hoist_position ?? null;
+  }
+
+  /** Returns a mention string (e.g. `<@&123456>`). */
+  toString(): string {
+    return `<@&${this.id}>`;
+  }
+
+  /**
+   * Edit this role.
+   * Requires Manage Roles permission.
+   * @param options - Role updates (permissions accepts PermissionResolvable for convenience)
+   * @returns This role (updated in place)
+   * @example
+   * await role.edit({ name: 'Moderator', permissions: ['BanMembers', 'KickMembers'] });
+   */
+  async edit(
+    options: RESTUpdateRoleBody & { permissions?: string | PermissionResolvable },
+  ): Promise<Role> {
+    const body: Record<string, unknown> = {};
+    if (options.name !== undefined) body.name = options.name;
+    if (options.permissions !== undefined) {
+      body.permissions =
+        typeof options.permissions === 'string'
+          ? options.permissions
+          : resolvePermissionsToBitfield(options.permissions);
+    }
+    if (options.color !== undefined) body.color = options.color;
+    if (options.hoist !== undefined) body.hoist = options.hoist;
+    if (options.mentionable !== undefined) body.mentionable = options.mentionable;
+    if (options.unicode_emoji !== undefined) body.unicode_emoji = options.unicode_emoji;
+    if (options.position !== undefined) body.position = options.position;
+    if (options.hoist_position !== undefined) body.hoist_position = options.hoist_position;
+    const data = await this.client.rest.patch<APIRole>(Routes.guildRole(this.guildId, this.id), {
+      body: Object.keys(body).length ? body : undefined,
+      auth: true,
+    });
+    this._patch(data);
+    return this;
+  }
+
+  /**
+   * Delete this role.
+   * Requires Manage Roles permission.
+   */
+  async delete(): Promise<void> {
+    await this.client.rest.delete(Routes.guildRole(this.guildId, this.id), { auth: true });
+    const guild = this.client.guilds.get(this.guildId);
+    if (guild) guild.roles.delete(this.id);
+  }
+}