@erinjs/core 1.0.0

package/core/apps/docs-vitepress/v/latest/guides/events.md

@@ -0,0 +1,202 @@
+# Events
+
+Listen to gateway events with client.on. Handle messages, guild updates, voice state changes, and more.
+
+## Basic Usage
+
+Use client.on(Events.X, handler) to subscribe to events. Handlers receive event-specific payloads.
+
+::: tip
+client.events.X(handler) offers the same API with chaining and better autocomplete.
+:::
+
+::: code-group
+```javascript [Default]
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => {
+  console.log('Bot is ready!');
+});
+
+client.on(Events.MessageCreate, async (message) => {
+  console.log(message.content);
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+```javascript [client.events]
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client
+  .events.Ready(() => console.log('Bot is ready!'))
+  .events.MessageCreate(async (message) => console.log(message.content));
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+:::
+
+## Common Events
+
+Essential events for most bots.
+
+```javascript
+// Bot finished loading
+client.on(Events.Ready, () => {});
+
+// New message (DM or guild)
+client.on(Events.MessageCreate, async (message) => {});
+
+// Reaction events
+client.on(Events.MessageReactionAdd, (reaction, user, messageId, channelId, emoji, userId) => {});
+client.on(Events.MessageReactionRemove, (reaction, user, messageId, channelId, emoji, userId) => {});
+
+// Guild joined/left/updated
+client.on(Events.GuildCreate, (guild) => {});
+client.on(Events.GuildDelete, (guild) => {});
+
+// Channel created/updated/deleted
+client.on(Events.ChannelCreate, (channel) => {});
+client.on(Events.ChannelDelete, (channel) => {});
+
+// Member joined/left/updated
+client.on(Events.GuildMemberAdd, (member) => {});
+client.on(Events.GuildMemberRemove, (member) => {});
+
+// Voice state changed (for @erinjs/voice)
+client.on(Events.VoiceStateUpdate, (data) => {});
+client.on(Events.VoiceServerUpdate, (data) => {});
+```
+
+## Reaction Events
+
+Listen for when users add or remove reactions. Handlers receive (reaction, user, messageId, channelId, emoji, userId). Use MessageReactionRemoveAll and MessageReactionRemoveEmoji for moderator actions.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageReactionAdd, (reaction, user, messageId, channelId, emoji, userId) => {
+  const emojiStr = emoji.id ? `<:${emoji.name}:${emoji.id}>` : emoji.name;
+  console.log(`User ${userId} reacted with ${emojiStr} on message ${messageId}`);
+
+  // Filter for specific message (e.g. poll) or emoji
+  if (emoji.name === '👍') {
+    console.log('Someone voted yes!');
+  }
+});
+
+client.on(Events.MessageReactionRemove, (reaction, user, messageId, channelId, emoji, userId) => {
+  console.log(`User ${userId} removed ${emoji.name} from message ${messageId}`);
+});
+
+client.on(Events.MessageReactionRemoveAll, (data) => {
+  console.log(`All reactions cleared from message ${data.message_id}`);
+});
+
+client.on(Events.MessageReactionRemoveEmoji, (data) => {
+  console.log(`All ${data.emoji.name} reactions removed from message ${data.message_id}`);
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Error Handling
+
+```javascript
+client.on(Events.Error, (err) => {
+  console.error('Client error:', err);
+});
+```
+
+## Gateway Dispatch Events Reference
+
+All events the erin.js gateway can send. Use GatewayDispatchEvents from @erinjs/types for type-safe checks.
+
+| Category | Events |
+| --- | --- |
+| Connection & Session | `Ready, Resumed, SessionsReplace` |
+| User | `UserUpdate, UserSettingsUpdate, UserGuildSettingsUpdate, UserPinnedDmsUpdate, UserNoteUpdate, RecentMentionDelete` |
+| Saved Messages & Auth | `SavedMessageCreate, SavedMessageDelete, AuthSessionChange` |
+| Presence | `PresenceUpdate` |
+| Guild | `GuildCreate, GuildUpdate, GuildDelete, GuildMemberAdd, GuildMemberUpdate, GuildMemberRemove, GuildMembersChunk, GuildMemberListUpdate, GuildSync` |
+| Roles | `GuildRoleCreate, GuildRoleUpdate, GuildRoleUpdateBulk, GuildRoleDelete` |
+| Guild Assets | `GuildEmojisUpdate, GuildStickersUpdate` |
+| Moderation | `GuildBanAdd, GuildBanRemove` |
+| Channels | `ChannelCreate, ChannelUpdate, ChannelUpdateBulk, ChannelDelete, ChannelRecipientAdd, ChannelRecipientRemove, ChannelPinsUpdate, ChannelPinsAck` |
+| Passive | `PassiveUpdates` |
+| Invites | `InviteCreate, InviteDelete` |
+| Messages | `MessageCreate, MessageUpdate, MessageDelete, MessageDeleteBulk, MessageReactionAdd, MessageReactionRemove, MessageReactionRemoveAll, MessageReactionRemoveEmoji, MessageAck` |
+| Typing | `TypingStart` |
+| Webhooks | `WebhooksUpdate` |
+| Relationships | `RelationshipAdd, RelationshipUpdate, RelationshipRemove` |
+| Voice | `VoiceStateUpdate, VoiceServerUpdate` |
+| Calls | `CallCreate, CallUpdate, CallDelete` |
+| Favorites | `FavoriteMemeCreate, FavoriteMemeUpdate, FavoriteMemeDelete` |
+| SDK / Compatibility | `InteractionCreate, GuildIntegrationsUpdate, GuildScheduledEventCreate, GuildScheduledEventUpdate, GuildScheduledEventDelete` |
+
+## Event Payload Reference
+
+Payload structure for each event. Handler receives (data) or (message), (reaction, user, ...) etc. Types: Gateway*DispatchData from @erinjs/types.
+
+| Event | Payload |
+| --- | --- |
+| `READY` | `{ v, user, guilds, session_id, shard?, application: { id, flags } }` |
+| `RESUMED` | `(no payload)` |
+| `SESSIONS_REPLACE` | `Array of session objects` |
+| `USER_UPDATE` | `APIUser — id, username, discriminator, global_name, avatar, etc.` |
+| `GUILD_CREATE` | `APIGuild — id, name, icon, owner_id, channels[], members[], roles[], ...` |
+| `GUILD_UPDATE` | `APIGuild — full guild object` |
+| `GUILD_DELETE` | `{ id, unavailable? }` |
+| `GUILD_MEMBER_ADD` | `APIGuildMember & { guild_id } — user, roles, nick, joined_at, ...` |
+| `GUILD_MEMBER_UPDATE` | `{ guild_id, roles, user, nick?, avatar?, joined_at?, ... }` |
+| `GUILD_MEMBER_REMOVE` | `{ guild_id, user }` |
+| `GUILD_MEMBERS_CHUNK` | `{ guild_id, members[], chunk_index, chunk_count, presences?, nonce? }` |
+| `GUILD_MEMBER_LIST_UPDATE` | `{ guild_id, id, member_count, online_count, groups[], ops[] }` |
+| `GUILD_ROLE_CREATE` | `{ guild_id, role: APIRole }` |
+| `GUILD_ROLE_UPDATE` | `{ guild_id, role: APIRole }` |
+| `GUILD_ROLE_UPDATE_BULK` | `{ guild_id, roles: APIRole[] }` |
+| `GUILD_ROLE_DELETE` | `{ guild_id, role_id }` |
+| `GUILD_EMOJIS_UPDATE` | `{ guild_id, emojis: APIEmoji[] }` |
+| `GUILD_STICKERS_UPDATE` | `{ guild_id, stickers: APISticker[] }` |
+| `GUILD_BAN_ADD` | `{ guild_id, user, reason? }` |
+| `GUILD_BAN_REMOVE` | `{ guild_id, user }` |
+| `CHANNEL_CREATE` | `APIChannel — id, name, type, guild_id?, parent_id, ...` |
+| `CHANNEL_UPDATE` | `APIChannel` |
+| `CHANNEL_UPDATE_BULK` | `{ channels: APIChannel[] }` |
+| `CHANNEL_DELETE` | `APIChannel` |
+| `CHANNEL_RECIPIENT_ADD` | `{ channel_id, user }` |
+| `CHANNEL_RECIPIENT_REMOVE` | `{ channel_id, user }` |
+| `CHANNEL_PINS_UPDATE` | `{ channel_id, guild_id?, last_pin_timestamp? }` |
+| `CHANNEL_PINS_ACK` | `{ channel_id, last_pin_timestamp? }` |
+| `INVITE_CREATE` | `APIInvite — code, guild, channel, inviter?, expires_at?, ...` |
+| `INVITE_DELETE` | `{ code, channel_id, guild_id? }` |
+| `MESSAGE_CREATE` | `APIMessage — id, channel_id, author, content, embeds, attachments, member?, ...` |
+| `MESSAGE_UPDATE` | `APIMessage — partial (edited fields)` |
+| `MESSAGE_DELETE` | `{ id, channel_id, guild_id?, content?, author_id? }` |
+| `MESSAGE_DELETE_BULK` | `{ ids[], channel_id, guild_id? }` |
+| `MESSAGE_REACTION_ADD` | `{ message_id, channel_id, user_id, guild_id?, emoji: { id, name, animated? } }` |
+| `MESSAGE_REACTION_REMOVE` | `{ message_id, channel_id, user_id, guild_id?, emoji }` |
+| `MESSAGE_REACTION_REMOVE_ALL` | `{ message_id, channel_id, guild_id? }` |
+| `MESSAGE_REACTION_REMOVE_EMOJI` | `{ message_id, channel_id, guild_id?, emoji }` |
+| `MESSAGE_ACK` | `{ message_id, channel_id } — read receipt` |
+| `TYPING_START` | `{ channel_id, user_id, timestamp, guild_id?, member? }` |
+| `VOICE_STATE_UPDATE` | `{ guild_id?, channel_id, user_id, member?, session_id, deaf?, mute?, ... }` |
+| `VOICE_SERVER_UPDATE` | `{ token, guild_id, endpoint, connection_id? }` |
+| `WEBHOOKS_UPDATE` | `{ guild_id, channel_id }` |
+| `PRESENCE_UPDATE` | `{ user: { id }, guild_id?, status?, activities?, custom_status? }` |
+| `GUILD_INTEGRATIONS_UPDATE` | `{ guild_id }` |
+| `GUILD_SCHEDULED_EVENT_CREATE` | `{ guild_id, id }` |
+| `GUILD_SCHEDULED_EVENT_UPDATE` | `{ guild_id, id }` |
+| `GUILD_SCHEDULED_EVENT_DELETE` | `{ guild_id, id }` |
+| `USER_NOTE_UPDATE` | `{ id, note? }` |
+| `SAVED_MESSAGE_CREATE` | `APIMessage` |
+| `SAVED_MESSAGE_DELETE` | `{ id }` |
+| `RELATIONSHIP_ADD / UPDATE` | `{ id, type }` |
+| `RELATIONSHIP_REMOVE` | `{ id }` |
+| `CALL_CREATE / UPDATE / DELETE` | `{ id, channel_id, ... }` |
+| `INTERACTION_CREATE` | `APIApplicationCommandInteraction` |

package/core/apps/docs-vitepress/v/latest/guides/gifs.md

@@ -0,0 +1,47 @@
+# GIFs (Tenor)
+
+Send Tenor GIFs as content (gifv) or in embeds using resolveTenorToImageUrl() for GIF URLs.
+
+## How Tenor GIFs Work
+
+Tenor embeds are created by the erin.js unfurler when you send a Tenor URL as message content. Do not use custom embeds for Tenor GIFs—the API turns the URL into a type: "gifv" embed.
+
+## Send a Tenor GIF
+
+Send the Tenor URL as content. No embeds needed. The unfurler detects the URL and creates the gifv embed.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!gif') {
+    const tenorUrl = 'https://tenor.com/view/stressed-gif-7048057395502071840';
+    await message.reply({ content: tenorUrl });
+  }
+});
+```
+
+## Tenor URL in an embed
+
+Tenor page URLs do not work as setImage() URLs. Use resolveTenorToImageUrl() to fetch the Tenor page or oEmbed, derive the GIF URL (embeds require GIF, not MP4), and return { url, flags: IS_ANIMATED }. For full gifv embeds, send the Tenor URL as content.
+
+```javascript
+import { EmbedBuilder, resolveTenorToImageUrl } from '@erinjs/core';
+
+const tenorUrl = 'https://tenor.com/view/stressed-gif-7048057395502071840';
+const media = await resolveTenorToImageUrl(tenorUrl);
+if (media) {
+  const embed = new EmbedBuilder()
+    .setTitle('Tenor in embed')
+    .setDescription('GIF URL + IS_ANIMATED flag')
+    .setImage(media)
+    .setColor(0x5865f2);
+  await message.reply({ embeds: [embed] });
+}
+```
+
+## Important
+
+Custom embeds cannot create gifv embeds. For full animated gifv, send the Tenor URL as content. resolveTenorToImageUrl() returns GIF URL + IS_ANIMATED (derived from media.tenor.com path).

package/core/apps/docs-vitepress/v/latest/guides/installation.md

@@ -0,0 +1,10 @@
+# Installation
+
+Install the package and configure your bot token.
+
+```bash
+npm install @erinjs/core
+
+# Run your bot (Node 18+)
+ERIN_BOT_TOKEN=your_token node your-bot.js
+```

package/core/apps/docs-vitepress/v/latest/guides/moderation.md

@@ -0,0 +1,89 @@
+# Moderation
+
+Implement ban, kick, and unban commands. Check permissions first (see Permissions guide).
+
+## Overview
+
+Use guild.ban(), guild.kick(), and guild.unban() for moderation. Always check member permissions before allowing moderation commands—see the Permissions guide.
+
+## Ban a member
+
+guild.ban(userId, options) bans a user. Pass reason for the audit log. Requires BanMembers permission.
+
+```javascript
+const userId = parseUserMention(target);
+if (userId) {
+  await guild.ban(userId, { reason: rest.join(' ') || undefined });
+  await message.reply(`Banned <@${userId}>.`);
+}
+```
+
+## Kick a member
+
+guild.kick(userId, options) kicks a user from the guild. Pass reason for the audit log. Requires KickMembers permission.
+
+```javascript
+const userId = parseUserMention(target);
+if (userId) {
+  await guild.kick(userId, { reason: rest.join(' ') || undefined });
+  await message.reply(`Kicked <@${userId}>.`);
+}
+```
+
+## Unban a user
+
+guild.unban(userId, reason?) removes a ban. Requires BanMembers permission.
+
+```javascript
+const userId = parseUserMention(target);
+if (userId) {
+  await guild.unban(userId, rest.join(' ') || undefined);
+  await message.reply(`Unbanned <@${userId}>.`);
+}
+```
+
+## Full moderation example
+
+See examples/moderation-bot.js for a complete bot with !ban, !kick, !unban, and !perms commands.
+
+```javascript
+import { Client, Events, PermissionFlags, parseUserMention } from '@erinjs/core';
+
+const PREFIX = '!';
+const client = new Client({ intents: 0 });
+
+async function getModeratorPerms(message) {
+  const guild = message.guild ?? await message.client.guilds.resolve(message.guildId);
+  if (!guild) return null;
+  const member = guild.members.get(message.author.id);
+  const resolved = member ?? await guild.fetchMember(message.author.id);
+  return resolved?.permissions ?? null;
+}
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.author.bot || !message.content?.startsWith(PREFIX)) return;
+  const [cmd, target, ...rest] = message.content.slice(PREFIX.length).trim().split(/\s+/);
+  const perms = await getModeratorPerms(message);
+  if (!perms) return;
+
+  const guild = message.guild ?? await message.client.guilds.resolve(message.guildId);
+  if (!guild) return;
+
+  if (cmd === 'ban' && (perms.has(PermissionFlags.BanMembers) || perms.has(PermissionFlags.Administrator))) {
+    const userId = parseUserMention(target);
+    if (userId) {
+      await guild.ban(userId, { reason: rest.join(' ') || undefined });
+      await message.reply(`Banned <@${userId}>.`);
+    }
+  }
+  if (cmd === 'kick' && (perms.has(PermissionFlags.KickMembers) || perms.has(PermissionFlags.Administrator))) {
+    const userId = parseUserMention(target);
+    if (userId) {
+      await guild.kick(userId, { reason: rest.join(' ') || undefined });
+      await message.reply(`Kicked <@${userId}>.`);
+    }
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```

package/core/apps/docs-vitepress/v/latest/guides/permissions.md

@@ -0,0 +1,130 @@
+# Permissions
+
+Check member permissions (guild-level and channel-specific), bot permissions via guild.members.me, owner override, and PermissionFlags.
+
+## Overview
+
+Use member.permissions for guild-level checks (roles only) and member.permissionsIn(channel) for channel-specific permissions (includes overwrites). The server owner always has all permissions.
+
+## Guild-level permissions
+
+member.permissions returns an object with has(permission). Use it for server-wide actions like ban, kick, manage roles.
+
+```javascript
+import { Client, Events, PermissionFlags } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+async function getMemberPerms(message) {
+  const guild = message.guild ?? await message.client.guilds.resolve(message.guildId);
+  if (!guild) return null;
+  const member = guild.members.get(message.author.id) ?? await guild.fetchMember(message.author.id);
+  return member?.permissions ?? null;
+}
+
+client.on(Events.MessageCreate, async (message) => {
+  const perms = await getMemberPerms(message);
+  if (!perms) return;
+
+  if (perms.has(PermissionFlags.BanMembers)) {
+    await message.reply('You can ban members.');
+  }
+  if (perms.has(PermissionFlags.Administrator)) {
+    await message.reply('You have Administrator.');
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Bot's own permissions (guild.members.me)
+
+::: info Discord.js Compatible
+See [API reference](/v/latest/api/classes/GuildMemberManager) for full details.
+:::
+
+Use guild.members.me to get the bot's GuildMember. Returns null if not cached. Use guild.members.fetchMe() to load it. Discord.js parity.
+
+```javascript
+// Check if the bot can ban members in this guild
+const guild = message.guild ?? await message.client.guilds.resolve(message.guildId);
+const me = guild?.members.me ?? (guild ? await guild.members.fetchMe() : null);
+if (me?.permissions.has(PermissionFlags.BanMembers)) {
+  await message.reply('I have Ban Members permission.');
+}
+```
+
+## Editing the bot's guild profile (nickname)
+
+Use guild.members.me.edit({ nick }) to change the bot's nickname in that guild. Pass nick: null to clear and show the username. Requires Change Nickname permission (or bot has Manage Nicknames). See examples/ping-bot.js for a !setnick command.
+
+```javascript
+const guild = message.guild ?? await client.guilds.resolve(message.guildId);
+const me = guild?.members.me ?? (guild ? await guild.members.fetchMe() : null);
+if (me) {
+  await me.edit({ nick: 'My Custom Nick' });
+  await message.reply('Nickname updated!');
+}
+// Clear nickname (show username)
+await me.edit({ nick: null });
+```
+
+## Owner override
+
+The guild owner automatically receives all permissions regardless of roles. No need to give the owner a role with Administrator.
+
+```javascript
+// When the message author is the server owner:
+const perms = member.permissions;
+perms.has(PermissionFlags.BanMembers);  // true
+perms.has(PermissionFlags.ManageRoles); // true
+perms.has(PermissionFlags.Administrator); // true
+// ... all permission flags return true for the owner
+```
+
+## Channel-specific permissions
+
+member.permissionsIn(channel) applies channel overwrites. Use it when checking if a user can send messages, read history, or connect to voice in a specific channel.
+
+```javascript
+const channel = message.channel;
+if (channel?.canSendMessage?.()) {
+  const perms = member.permissionsIn(channel);
+  if (perms.has(PermissionFlags.SendMessages)) {
+    await channel.send('You can send here!');
+  }
+}
+```
+
+## Managing roles
+
+Create, fetch, edit, and delete roles with guild.createRole(), guild.fetchRoles(), guild.fetchRole(roleId), role.edit(), and role.delete(). Use resolvePermissionsToBitfield() for permission bitfields. See the Roles guide for full examples.
+
+```javascript
+// Create a role with specific permissions
+const role = await guild.createRole({
+  name: 'Mod',
+  permissions: ['KickMembers', 'BanMembers', 'ManageMessages'],
+});
+
+// Add/remove roles from members
+await guild.addRoleToMember(userId, roleId);
+await guild.removeRoleFromMember(userId, roleId);
+```
+
+## PermissionFlags reference
+
+Common flags: BanMembers, KickMembers, Administrator, ManageRoles, ManageChannels, ManageGuild, ViewAuditLog, ManageMessages, SendMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone, Connect, Speak, MuteMembers, ModerateMembers, CreateExpressions, PinMessages, BypassSlowmode.
+
+```javascript
+import { PermissionFlags } from '@erinjs/core';
+
+// Check multiple
+const canModerate = perms.has(PermissionFlags.BanMembers) || perms.has(PermissionFlags.Administrator);
+
+// List all permissions the user has
+const names = Object.keys(PermissionFlags).filter((name) =>
+  perms.has(PermissionFlags[name])
+);
+await message.reply(`Your permissions: ${names.join(', ')}`);
+```

package/core/apps/docs-vitepress/v/latest/guides/prefix-commands.md

@@ -0,0 +1,41 @@
+# Prefix Commands
+
+Handle !commands by listening to MessageCreate and parsing the content.
+
+## Basic Structure
+
+Check for a prefix, split args, and dispatch to command handlers.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const PREFIX = '!';
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.author.bot || !message.content) return;
+  if (!message.content.startsWith(PREFIX)) return;
+
+  const args = message.content.slice(PREFIX.length).trim().split(/\s+/);
+  const command = args.shift()?.toLowerCase();
+
+  if (command === 'ping') {
+    await message.reply('Pong!');
+  }
+  if (command === 'hello') {
+    const name = args[0] ?? 'there';
+    await message.reply(`Hello, ${name}!`);
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Guild-Only Commands
+
+```javascript
+if (!message.guildId) {
+  await message.reply('This command only works in a server.');
+  return;
+}
+```

package/core/apps/docs-vitepress/v/latest/guides/profile-urls.md

@@ -0,0 +1,58 @@
+# Profile URLs
+
+Get avatar, banner, and other CDN URLs easily with User/Webhook/GuildMember methods or standalone CDN helpers for raw API data.
+
+## User avatar and banner
+
+When you have a User object (e.g. message.author), use avatarURL(), displayAvatarURL(), and bannerURL(). These handle animated avatars (a_ prefix) and default fallbacks.
+
+```javascript
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!avatar') {
+    const user = message.author;
+    // avatarURL() returns null if no custom avatar; displayAvatarURL() uses default
+    const avatarUrl = user.displayAvatarURL({ size: 256 });
+    const bannerUrl = user.bannerURL({ size: 512 });
+
+    const embed = new EmbedBuilder()
+      .setTitle(`${user.username}'s profile`)
+      .setThumbnail(avatarUrl)
+      .setColor(user.avatarColor ?? 0x5865f2);
+    if (bannerUrl) embed.setImage(bannerUrl);
+    await message.reply({ embeds: [embed] });
+  }
+});
+```
+
+## Raw API data: CDN helpers
+
+When you have raw API data (e.g. from client.rest.get(Routes.user(id))), use the standalone CDN helpers. They work with id + hash and support size and extension options.
+
+```javascript
+import { cdnAvatarURL, cdnBannerURL } from '@erinjs/core';
+
+// From REST response
+const userData = await client.rest.get(Routes.user(userId));
+const avatarUrl = cdnAvatarURL(userData.id, userData.avatar, { size: 256 });
+const bannerUrl = cdnBannerURL(userData.id, profile?.banner ?? null, { size: 512 });
+
+// Or use User: client.getOrCreateUser(userData) then user.displayAvatarURL()
+const user = client.getOrCreateUser(userData);
+const avatarUrl2 = user.displayAvatarURL({ size: 256 });
+```
+
+## Guild member and webhook avatars
+
+GuildMember has displayAvatarURL() (guild avatar or fallback to user) and bannerURL(). Webhook has avatarURL().
+
+```javascript
+// Member avatar (guild-specific or user fallback)
+const memberAvatar = member.displayAvatarURL({ size: 128 });
+
+// Webhook avatar
+const webhookAvatar = webhook.avatarURL({ size: 64 });
+```

package/core/apps/docs-vitepress/v/latest/guides/reactions.md

@@ -0,0 +1,69 @@
+# Reactions
+
+Add, remove, and listen for message reactions with Message.react(), removeReaction(), and reaction events.
+
+## Add a Reaction
+
+Use message.react() to add an emoji reaction as the bot. Pass a unicode emoji string or custom emoji { name, id }.
+
+```javascript
+const reply = await message.reply('React to this!');
+await reply.react('👍');
+await reply.react({ name: 'customemoji', id: '123456789012345678' });
+```
+
+## Remove Reactions
+
+Remove the bot's reaction with removeReaction(emoji). Remove a specific user's reaction with removeReaction(emoji, userId). Clear all reactions with removeAllReactions() or removeReactionEmoji(emoji).
+
+```javascript
+// Remove the bot's reaction
+await message.removeReaction('👍');
+
+// Remove a specific user's reaction (requires moderator permissions)
+await message.removeReaction('👍', userId);
+
+// Remove all reactions of one emoji from the message
+await message.removeReactionEmoji('👍');
+
+// Remove all reactions from the message
+await message.removeAllReactions();
+```
+
+## Listen for Reactions
+
+MessageReactionAdd and MessageReactionRemove emit (reaction, user, messageId, channelId, emoji, userId). Use client.on(Events.X, handler) or client.events.MessageReactionAdd(handler).
+
+```javascript
+client.on(Events.MessageReactionAdd, async (reaction, user, messageId, channelId, emoji, userId) => {
+  if (emoji.name === '👍') {
+    console.log(`User ${userId} voted yes on message ${messageId}`);
+    const message = await reaction.fetchMessage();
+    if (message) await message.react('✅');
+  }
+});
+
+client.on(Events.MessageReactionRemove, (reaction, user, messageId, channelId, emoji, userId) => {
+  console.log(`User ${userId} removed ${emoji.name} from message ${messageId}`);
+});
+```
+
+## Reaction Roles Example
+
+::: info Discord.js Compatible
+See [API reference](/v/latest/api/classes/GuildMemberRoleManager) for full details.
+:::
+
+See examples/reaction-roles-bot.js for a full bot that assigns roles when users react to a message. Uses (reaction, user), Guild.fetchMember(), member.roles.add() (Discord.js parity), and guild.createRole() if you need to create roles programmatically. See the Roles guide for role CRUD.
+
+```javascript
+// Simplified reaction-roles logic
+client.on(Events.MessageReactionAdd, async (reaction, user) => {
+  if (!reaction.guildId || reaction.messageId !== rolesMessageId) return;
+  const roleId = ROLE_EMOJI_MAP[reaction.emoji.name];
+  if (!roleId) return;
+  const guild = client.guilds.get(reaction.guildId);
+  const member = await guild?.fetchMember(user.id);
+  if (member && !member.roles.cache.has(roleId)) await member.roles.add(roleId);
+});
+```