@erinjs/core 1.0.0

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

@@ -0,0 +1,180 @@
+# Channels
+
+Create and manage channels, roles, and invites. Covers guild.createChannel(), channel.edit(), channel.createInvite(), guild.createRole(), and more.
+
+## Channels — Create
+
+Use guild.createChannel() to create text (0), voice (2), category (4), or link (5) channels. Requires Manage Channels permission. Pass parent_id to put a channel under a category.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (!message.guildId || message.content !== '!createchannel') return;
+  const guild = client.guilds.get(message.guildId) ?? await client.guilds.resolve(message.guildId);
+  if (!guild) return;
+
+  // Text channel (0), voice (2), category (4), link (5)
+  const textChannel = await guild.createChannel({
+    type: 0,
+    name: 'general',
+  });
+
+  // Category, then voice channel under it
+  const category = await guild.createChannel({
+    type: 4,
+    name: 'Voice Chats',
+  });
+  const voiceChannel = await guild.createChannel({
+    type: 2,
+    name: 'Lounge',
+    parent_id: category.id,
+    bitrate: 64000,
+  });
+
+  await message.reply(`Created ${textChannel.name} and ${voiceChannel.name} in ${category.name}`);
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Channels — Fetch and Edit
+
+Use guild.fetchChannels() to load all guild channels. Use channel.edit() to rename, set topic, move to a category, set slowmode, or update permission overwrites.
+
+```javascript
+const guild = client.guilds.get(guildId) ?? await client.guilds.resolve(guildId);
+if (!guild) return;
+
+const channels = await guild.fetchChannels();
+
+// Edit a text channel
+const channel = guild.channels.get(channelId);
+if (channel) {
+  await channel.edit({
+    name: 'renamed-channel',
+    topic: 'New topic here',
+    parent_id: categoryId,        // Move under category
+    rate_limit_per_user: 5,      // 5 second slowmode
+    nsfw: false,
+  });
+}
+```
+
+## Channels — Delete and Reorder
+
+Use channel.delete() to remove a channel. Use guild.setChannelPositions() to reorder channels or move them between categories.
+
+```javascript
+// Delete channel (silent: true skips system message)
+await channel.delete();
+await channel.delete({ silent: true });
+
+// Reorder channels
+await guild.setChannelPositions([
+  { id: channelId1, position: 0 },
+  { id: channelId2, position: 1, parent_id: categoryId },
+]);
+```
+
+## Channel Permission Overwrites
+
+Use channel.editPermission() to add or update overwrites (type 0=role, 1=member). Use channel.deletePermission() to remove. Use resolvePermissionsToBitfield() for allow/deny bitfields.
+
+```javascript
+import { resolvePermissionsToBitfield, PermissionFlags } from '@erinjs/core';
+
+// Deny SendMessages for a role (type 0=role, 1=member)
+await channel.editPermission(roleId, {
+  type: 0,
+  deny: resolvePermissionsToBitfield(['SendMessages']),
+});
+
+// Allow ViewChannel for a specific member
+await channel.editPermission(userId, {
+  type: 1,
+  allow: resolvePermissionsToBitfield([PermissionFlags.ViewChannel]),
+});
+
+// Remove overwrite
+await channel.deletePermission(roleId);
+```
+
+## Roles — Quick Reference
+
+Create roles with guild.createRole(), fetch with guild.fetchRoles() or guild.fetchRole(roleId). Add/remove with guild.addRoleToMember() / guild.removeRoleFromMember(). Reorder with guild.setRolePositions().
+
+::: tip
+See the Roles guide for full examples, permission bitfields, and role.edit() / role.delete().
+:::
+
+```javascript
+// See the Roles guide for full examples and permission bitfields.
+const role = await guild.createRole({ name: 'Mod', permissions: ['KickMembers', 'BanMembers'] });
+await guild.addRoleToMember(userId, role.id);
+await guild.removeRoleFromMember(userId, role.id);
+await guild.setRolePositions([{ id: role.id, position: 5 }]);
+```
+
+## Invites
+
+Use channel.createInvite() to create an invite. Use channel.fetchInvites() to list channel invites. Use invite.delete() to revoke. invite.url gives the full invite URL.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (!message.content.startsWith('!invite') || !message.guildId) return;
+  const channel = message.channel;
+  if (!channel?.createInvite) return;
+
+  if (message.content === '!invite') {
+    const invite = await channel.createInvite({
+      max_age: 86400,    // 24 hours
+      max_uses: 10,
+      temporary: false,
+    });
+    await message.reply(`Invite: ${invite.url}`);
+  }
+
+  if (message.content === '!invitelist') {
+    const invites = await channel.fetchInvites();
+    const list = invites.map((i) => `${i.code} (${i.max_uses ?? '∞'} uses)`).join('\n');
+    await message.reply(list || 'No invites.');
+  }
+
+  if (message.content.startsWith('!inviterevoke ')) {
+    const code = message.content.slice(13).trim();
+    const invites = await channel.fetchInvites();
+    const inv = invites.find((i) => i.code === code);
+    if (inv) {
+      await inv.delete();
+      await message.reply('Invite revoked.');
+    }
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Quick Reference
+
+| API | Method | Purpose |
+| --- | --- | --- |
+| `Channels` | `guild.createChannel()` | Create text, voice, category, or link channel |
+| `Channels` | `guild.fetchChannels()` | Fetch all guild channels |
+| `Channels` | `channel.edit()` | Rename, set topic, slowmode, parent, overwrites |
+| `Channels` | `channel.delete()` | Delete a channel |
+| `Channels` | `guild.setChannelPositions()` | Reorder or reparent channels |
+| `Channels` | `channel.editPermission()` | Add or update permission overwrite |
+| `Channels` | `channel.deletePermission()` | Remove permission overwrite |
+| `Roles` | `guild.createRole()` | Create a role |
+| `Roles` | `guild.addRoleToMember()` | Add role to member |
+| `Roles` | `guild.removeRoleFromMember()` | Remove role from member |
+| `Invites` | `channel.createInvite()` | Create invite with max_uses, max_age |
+| `Invites` | `channel.fetchInvites()` | List channel invites |
+| `Invites` | `invite.delete()` | Revoke invite |

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

@@ -0,0 +1,58 @@
+# Deprecated APIs
+
+APIs that are deprecated and will be removed in a future release. Migrate to the recommended alternatives.
+
+## Overview
+
+The following methods emit a one-time deprecation warning at runtime. Set ERIN_SUPPRESS_DEPRECATION=1 to silence warnings. Migrate to the recommended replacements.
+
+## Client.sendToChannel
+
+Use client.channels.send(channelId, payload) instead. Accepts the same MessageSendOptions (content, embeds, files).
+
+| Deprecated | Replacement |
+| --- | --- |
+| `client.sendToChannel(channelId, content)` | `client.channels.send(channelId, payload)` |
+
+```javascript
+// ❌ Deprecated
+await client.sendToChannel(channelId, 'Hello!');
+await client.sendToChannel(channelId, { embeds: [embed] });
+
+// ✅ Use instead
+await client.channels.send(channelId, 'Hello!');
+await client.channels.send(channelId, { embeds: [embed] });
+```
+
+## Client.fetchMessage
+
+Use channel.messages.fetch(messageId) instead. Resolve the channel first if you only have IDs.
+
+| Deprecated | Replacement |
+| --- | --- |
+| `client.fetchMessage(channelId, messageId)` | `(await client.channels.resolve(channelId))?.messages?.fetch(messageId)` |
+
+```javascript
+// ❌ Deprecated
+const message = await client.fetchMessage(channelId, messageId);
+
+// ✅ Use instead
+const channel = await client.channels.resolve(channelId);
+const message = channel?.messages ? await channel.messages.fetch(messageId) : null;
+```
+
+## ChannelManager.fetchMessage
+
+Use channel.messages.fetch(messageId) instead.
+
+| Deprecated | Replacement |
+| --- | --- |
+| `client.channels.fetchMessage(channelId, messageId)` | `channel.messages.fetch(messageId)` |
+
+## Channel.fetchMessage
+
+Use channel.messages.fetch(messageId) instead. Available on TextChannel and DMChannel.
+
+| Deprecated | Replacement |
+| --- | --- |
+| `channel.fetchMessage(messageId)` | `channel.messages.fetch(messageId)` |

package/core/apps/docs-vitepress/v/latest/guides/discord-js-compatibility.md

@@ -0,0 +1,42 @@
+# Discord.js Compatibility
+
+APIs designed to ease migration from Discord.js. Look for the green "Discord.js compatible" badge in guides.
+
+## Overview
+
+erin.js SDK provides Discord.js-style APIs where it makes sense. Sections marked with the green "Discord.js compatible" badge offer familiar patterns — click the badge to see the full API reference.
+
+## member.roles (GuildMemberRoleManager)
+
+::: info Discord.js Compatible
+See [API reference](/v/latest/api/classes/GuildMemberRoleManager) for full details.
+:::
+
+member.roles is a manager with add(), remove(), set(), and cache. Use member.roles.add(roleId), member.roles.remove(roleId), member.roles.set(roleIds), and member.roles.cache.has(roleId) instead of the old member.addRole() / member.roles.includes() pattern.
+
+```javascript
+// Discord.js style
+await member.roles.add(roleId);
+await member.roles.remove(roleId);
+await member.roles.set(['id1', 'id2']);
+if (member.roles.cache.has(roleId)) { ... }
+```
+
+## guild.members.me
+
+::: info Discord.js Compatible
+See [API reference](/v/latest/api/classes/GuildMemberManager) for full details.
+:::
+
+guild.members.me returns the bot's GuildMember in that guild. Use guild.members.fetchMe() to load it when not cached. Same as Discord.js.
+
+```javascript
+const me = guild.members.me ?? await guild.members.fetchMe();
+if (me?.permissions.has(PermissionFlags.BanMembers)) {
+  await message.reply('I can ban members here.');
+}
+```
+
+## Other parity
+
+client.channels.cache and client.guilds.cache are compatibility aliases. Collection extends Map with find(), filter(), etc. See the API reference for full details.

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

@@ -0,0 +1,65 @@
+# Editing Embeds
+
+Edit existing message embeds with message.edit().
+
+## Overview
+
+The erin.js API supports editing existing messages via PATCH. You can update the message content, embeds, or both. Only the message author (or admins with proper permissions) can edit messages.
+
+## Edit Content
+
+Update the text content of a message you sent.
+
+```javascript
+const reply = await message.reply('Initial message');
+await reply.edit({ content: 'Updated message!' });
+```
+
+## Edit Embeds
+
+Replace or update embeds on an existing message. Pass an array of EmbedBuilder instances or APIEmbed objects.
+
+```javascript
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!editembed') {
+    const embed = new EmbedBuilder()
+      .setTitle('Loading...')
+      .setColor(0x5865f2)
+      .setTimestamp();
+
+    const reply = await message.reply({ embeds: [embed] });
+
+    // Simulate loading, then update the embed
+    await new Promise((r) => setTimeout(r, 2000));
+
+    const updatedEmbed = new EmbedBuilder()
+      .setTitle('Done!')
+      .setDescription('This embed was edited after 2 seconds.')
+      .setColor(0x57f287)
+      .setTimestamp();
+
+    await reply.edit({ embeds: [updatedEmbed] });
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Edit Content and Embeds Together
+
+You can update both content and embeds in a single edit call.
+
+```javascript
+await message.edit({
+  content: 'Updated text',
+  embeds: [new EmbedBuilder().setTitle('Updated embed').setColor(0x5865f2)],
+});
+```
+
+## API Reference
+
+The edit endpoint is PATCH /channels/{channel_id}/messages/{message_id}. See openapi.json for the full request body schema. The SDK Message.edit() accepts { content?: string; embeds?: (APIEmbed | EmbedBuilder)[] }.

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

@@ -0,0 +1,87 @@
+# Embed Media
+
+Add images, thumbnails, video, and audio to embeds with EmbedBuilder and EmbedMediaOptions.
+
+## Images and Thumbnails
+
+Use setImage() and setThumbnail() with a URL string, or pass full EmbedMediaOptions for width, height, content_type, and other metadata.
+
+```javascript
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!embedimg') {
+    const embed = new EmbedBuilder()
+      .setTitle('Image Embed')
+      .setDescription('Simple image from URL.')
+      .setImage('https://placehold.co/400x200/5865f2/white?text=Image')
+      .setThumbnail('https://placehold.co/100x100/57f287/white?text=Thumb')
+      .setColor(0x5865f2);
+
+    await message.reply({ embeds: [embed] });
+  }
+});
+```
+
+## Image with Full Media Options
+
+Pass an object to setImage or setThumbnail with url, width, height, content_type, description, placeholder, duration, and flags. Use EmbedMediaFlags.IS_ANIMATED for animated GIFs.
+
+```javascript
+const embed = new EmbedBuilder()
+  .setTitle('Image with metadata')
+  .setDescription('EmbedMediaOptions: width, height')
+  .setImage({
+    url: 'https://placehold.co/400x200/5865f2/white?text=Image',
+    width: 400,
+    height: 200,
+    content_type: 'image/png',
+  })
+  .setColor(0x5865f2);
+```
+
+## GIFs in embeds
+
+Embeds require GIF format for animated images (not MP4). Add EmbedMediaFlags.IS_ANIMATED to the flags field. For Tenor URLs, use resolveTenorToImageUrl() to get the GIF URL and flag — see the GIFs (Tenor) guide.
+
+## Video in Embeds
+
+Use setVideo() to add video to a rich embed. erin.js supports the .video field. Include a title when using video. Pass a URL or EmbedMediaOptions (e.g. duration for progress bars).
+
+```javascript
+const embed = new EmbedBuilder()
+  .setTitle('Video embed')
+  .setDescription('Rich embed with video field.')
+  .setVideo('https://example.com/sample.mp4')
+  .setURL('https://example.com/sample.mp4')
+  .setColor(0x5865f2);
+
+// With full options (duration, dimensions for progress bar):
+const embedWithDuration = new EmbedBuilder()
+  .setTitle('Video with metadata')
+  .setVideo({
+    url: 'https://example.com/video.mp4',
+    duration: 120,
+    width: 1280,
+    height: 720,
+  })
+  .setColor(0x5865f2);
+```
+
+## Audio in Embeds
+
+Use setAudio() to add audio to an embed. Pass a URL or EmbedMediaOptions (e.g. duration, content_type).
+
+```javascript
+const embed = new EmbedBuilder()
+  .setTitle('Audio embed')
+  .setDescription('Rich embed with audio field.')
+  .setAudio({
+    url: 'https://example.com/sample.mp3',
+    duration: 180,
+    content_type: 'audio/mpeg',
+  })
+  .setColor(0x5865f2);
+```

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

@@ -0,0 +1,166 @@
+# Embeds
+
+Complete reference for EmbedBuilder: title, description, author, footer, fields, color, media, and more.
+
+## Overview
+
+Use EmbedBuilder to create rich embeds. EmbedBuilder instances are auto-converted—no need to call .toJSON() when passing to reply(), send(), or edit(). An embed must have at least one of: title, description, fields, or image/thumbnail. A description-only embed (no title) is valid.
+
+## Basic embed
+
+Minimal embed with title, description, color, fields, footer, and timestamp.
+
+```javascript
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!embed') {
+    const embed = new EmbedBuilder()
+      .setTitle('Hello!')
+      .setDescription('This is a erin.js embed.')
+      .setColor(0x5865f2)
+      .addFields(
+        { name: 'Field 1', value: 'Value 1', inline: true },
+        { name: 'Field 2', value: 'Value 2', inline: true }
+      )
+      .setFooter({ text: 'Powered by erin.js' })
+      .setTimestamp();
+
+    await message.reply({ embeds: [embed] });
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Title, Description, and URL
+
+setTitle() and setDescription() accept strings (max 256 and 4096 chars). setURL() makes the title a clickable link.
+
+```javascript
+const embed = new EmbedBuilder()
+  .setTitle('Clickable Title')
+  .setDescription('Main body text here.')
+  .setURL('https://example.com');
+```
+
+## Color
+
+setColor() accepts: number (0x5865f2), hex string ("#5865f2"), or [r, g, b] array.
+
+```javascript
+embed.setColor(0x5865f2);
+embed.setColor('#57f287');
+embed.setColor([88, 101, 242]);
+```
+
+## Author
+
+setAuthor() adds a header line with name. Optional: iconURL, url.
+
+```javascript
+embed.setAuthor({
+  name: 'erin.js',
+  iconURL: 'https://example.com/icon.png',
+  url: 'https://erinjs.dev',
+});
+```
+
+## Footer
+
+setFooter() adds text at the bottom. Optional: iconURL.
+
+```javascript
+embed.setFooter({
+  text: 'Powered by erin.js',
+  iconURL: 'https://example.com/footer-icon.png',
+});
+```
+
+## Timestamp
+
+setTimestamp() shows a date. Omit or pass null for current time. Pass Date or number (ms) for a specific time.
+
+```javascript
+embed.setTimestamp();                    // current time
+embed.setTimestamp(new Date('2026-01-01'));
+embed.setTimestamp(Date.now() - 3600000);  // 1 hour ago
+```
+
+## Fields
+
+addFields() adds name/value pairs. Max 25 fields. Use inline: true for side-by-side layout. spliceFields() to insert/remove.
+
+```javascript
+embed.addFields(
+  { name: 'Field 1', value: 'Value 1', inline: true },
+  { name: 'Field 2', value: 'Value 2', inline: true },
+  { name: 'Long field', value: 'Not inline, full width' }
+);
+
+// Insert/replace fields
+embed.spliceFields(1, 1, { name: 'Replaced', value: 'New value' });
+```
+
+## Image and Thumbnail
+
+setImage() adds a large image. setThumbnail() adds a small image (e.g. top-right). Pass a URL string or EmbedMediaOptions (url, width, height, content_type, etc).
+
+```javascript
+embed.setImage('https://example.com/image.png');
+embed.setThumbnail('https://example.com/thumb.png');
+
+// With metadata
+embed.setImage({
+  url: 'https://example.com/image.png',
+  width: 400,
+  height: 200,
+  content_type: 'image/png',
+});
+```
+
+## Video and Audio
+
+setVideo() and setAudio() add video/audio to embeds (erin.js supports these). Pass URL or EmbedMediaOptions. Include a title when using video. See Embed Media guide for full examples.
+
+```javascript
+embed.setVideo('https://example.com/video.mp4');
+embed.setAudio({
+  url: 'https://example.com/audio.mp3',
+  duration: 120,
+  content_type: 'audio/mpeg',
+});
+```
+
+## Multiple embeds
+
+Messages can include up to 10 embeds. Pass an array to embeds.
+
+```javascript
+await message.reply({
+  embeds: [
+    new EmbedBuilder().setTitle('First').setColor(0x5865f2),
+    new EmbedBuilder().setTitle('Second').setColor(0x57f287),
+  ],
+});
+```
+
+## Load from existing embed
+
+EmbedBuilder.from() creates a builder from an API embed (e.g. from a received message). Edit and toJSON() to send.
+
+```javascript
+const existing = message.embeds[0];
+if (existing) {
+  const edited = EmbedBuilder.from(existing)
+    .setTitle('Updated title')
+    .setColor(0x57f287);
+  await message.edit({ embeds: [edited] });
+}
+```
+
+## Limits
+
+Title ≤256, description ≤4096, field name ≤256, field value ≤1024, footer ≤2048, author name ≤256. Max 25 fields. Combined title+description+fields+footer ≤6000 chars.

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

@@ -0,0 +1,77 @@
+# Emojis & Stickers
+
+Fetch, create, edit, and delete guild emojis and stickers. Use guild.fetchEmojis(), guild.createEmojisBulk(), and guild.createStickersBulk().
+
+## Fetch Emojis
+
+Use guild.fetchEmojis() to get all emojis in a guild. Cached in guild.emojis. Use guild.fetchEmoji(emojiId) for a single emoji. Use emoji.delete() to remove an emoji (e.g. autocreated ones).
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (!message.guildId || message.content !== '!emojis') return;
+  const guild = client.guilds.get(message.guildId) ?? await client.guilds.resolve(message.guildId);
+  if (!guild) return;
+
+  const emojis = await guild.fetchEmojis();
+  const list = emojis.map((e) => `:${e.name}: (${e.id})`).join(', ');
+  await message.reply(emojis.length ? list : 'No emojis.');
+
+  // Or get from cache after fetching: guild.emojis.get(emojiId)
+});
+
+// Fetch single emoji by ID
+const emoji = await guild.fetchEmoji(emojiId);
+await emoji.delete();
+```
+
+## Create Emojis & Stickers
+
+Use guild.createEmojisBulk() and guild.createStickersBulk() with base64 image data. Use emoji.edit() / emoji.delete() and sticker.edit() / sticker.delete() for individual updates.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+// Create emoji from URL (fetch and convert to base64)
+async function createEmojiFromUrl(guild, name, imageUrl) {
+  const res = await fetch(imageUrl);
+  const buf = await res.arrayBuffer();
+  const base64 = Buffer.from(buf).toString('base64');
+  const [emoji] = await guild.createEmojisBulk([{ name, image: base64 }]);
+  return emoji;
+}
+
+client.on(Events.MessageCreate, async (message) => {
+  if (!message.guildId || !message.content.startsWith('!addemoji ')) return;
+  const guild = client.guilds.get(message.guildId) ?? await client.guilds.resolve(message.guildId);
+  if (!guild) return;
+
+  const [_, name, url] = message.content.split(/\s+/);
+  if (!name || !url) return;
+  const emoji = await createEmojiFromUrl(guild, name, url);
+  await message.reply(`Created emoji :${emoji.name}:`);
+});
+
+// Bulk create stickers
+const stickers = await guild.createStickersBulk([
+  { name: 'cool', image: base64Image, description: 'A cool sticker' },
+]);
+
+// Edit and delete
+await emoji.edit({ name: 'newname' });
+await emoji.delete();
+```
+
+## Quick Reference
+
+| API | Method | Purpose |
+| --- | --- | --- |
+| `Emojis` | `guild.fetchEmojis()` | Fetch all guild emojis (cached in guild.emojis) |
+| `Emojis` | `guild.fetchEmoji(emojiId)` | Fetch single emoji by ID |
+| `Emojis` | `guild.createEmojisBulk()` | Bulk create emojis (base64 image) |
+| `Stickers` | `guild.createStickersBulk()` | Bulk create stickers |