@erinjs/core 1.0.0

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

@@ -0,0 +1,130 @@
+# Roles
+
+Create, fetch, edit, and delete guild roles. Use PermissionFlags and resolvePermissionsToBitfield for permission bitfields.
+
+## Overview
+
+Guild roles can be created, fetched, edited, and deleted. Use guild.createRole(), guild.fetchRoles(), guild.fetchRole(roleId), role.edit(), and role.delete(). Requires Manage Roles permission. For permission bitfields, use resolvePermissionsToBitfield() or role.has() to check a role's permissions.
+
+## Create a role
+
+Use guild.createRole() to create a new role. Pass name, permissions, color, hoist, mentionable, unicode_emoji, position, or hoist_position. Permissions accept PermissionResolvable (string, number, array) for convenience.
+
+```javascript
+import { Client, Events, PermissionFlags, resolvePermissionsToBitfield } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!createrole' && message.guildId) {
+    const guild = client.guilds.get(message.guildId) ?? await client.guilds.resolve(message.guildId);
+    if (!guild) return;
+
+    const role = await guild.createRole({
+      name: 'Moderator',
+      permissions: ['BanMembers', 'KickMembers', 'ManageMessages'],
+      color: 0x5865f2,
+      hoist: true,
+      mentionable: false,
+    });
+    await message.reply(`Created role ${role.name} (${role.id})`);
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Fetch roles
+
+Use guild.fetchRoles() to fetch all roles from the API and cache them. Use guild.fetchRole(roleId) to fetch a single role by ID. Throws ErinError with ROLE_NOT_FOUND on 404.
+
+```javascript
+// Fetch all roles (updates guild.roles cache)
+const roles = await guild.fetchRoles();
+
+// Fetch a single role by ID
+const role = await guild.fetchRole(roleId);
+console.log(role.name, role.color);
+```
+
+## Edit a role
+
+Use role.edit() to update a role. Pass any of name, permissions, color, hoist, mentionable, unicode_emoji, position, hoist_position. Permissions accept PermissionResolvable.
+
+```javascript
+const role = guild.roles.get(roleId) ?? await guild.fetchRole(roleId);
+await role.edit({
+  name: 'Senior Mod',
+  permissions: ['BanMembers', 'KickMembers', 'ManageMessages', 'ManageRoles'],
+  color: 0x57f287,
+});
+```
+
+## Delete a role
+
+Use role.delete() to remove a role. The role is removed from guild.roles cache.
+
+```javascript
+const role = guild.roles.get(roleId) ?? await guild.fetchRole(roleId);
+await role.delete();
+await message.reply('Role deleted.');
+```
+
+## Check role permissions
+
+Use role.has(permission) to check if a role has a specific permission. Administrator implies all permissions.
+
+```javascript
+import { PermissionFlags } from '@erinjs/core';
+
+if (role.has(PermissionFlags.BanMembers)) {
+  await message.reply('This role can ban members.');
+}
+if (role.has('ManageChannels')) {
+  await message.reply('This role can manage channels.');
+}
+```
+
+## Add/remove roles from members (member.roles)
+
+::: info Discord.js Compatible
+See [API reference](/v/latest/api/classes/GuildMemberRoleManager) for full details.
+:::
+
+Use member.roles.add(), member.roles.remove(), and member.roles.set() for Discord.js-style role management. member.roles.cache is a Collection of Role objects. Also available: guild.addRoleToMember() and guild.removeRoleFromMember() when you only have user ID.
+
+```javascript
+// Discord.js parity: member.roles.add(), remove(), set()
+const member = await guild.fetchMember(userId);
+
+await member.roles.add(roleId);        // Add a role
+await member.roles.remove(roleId);     // Remove a role
+await member.roles.set(['id1', 'id2']); // Replace all roles
+
+// Check if member has a role
+if (member.roles.cache.has(roleId)) {
+  await message.reply('Member already has this role.');
+}
+
+// Guild-level: when you only have user ID (no member fetch needed)
+await guild.addRoleToMember(userId, roleId);
+await guild.removeRoleFromMember(userId, roleId);
+```
+
+## Permission bitfields for create/edit
+
+When creating or editing roles, pass permissions as a string (API format), number, PermissionString, or array. Use resolvePermissionsToBitfield() to combine multiple permissions. Handles high bits (PinMessages, ModerateMembers, etc.) correctly with BigInt.
+
+```javascript
+import { resolvePermissionsToBitfield, PermissionFlags } from '@erinjs/core';
+
+// Single permission by name
+resolvePermissionsToBitfield('SendMessages');  // "2048"
+
+// Array of permissions (OR'd together)
+resolvePermissionsToBitfield(['SendMessages', 'ViewChannel', 'ReadMessageHistory']);
+// Returns combined bitfield as string
+
+// From PermissionFlags enum
+resolvePermissionsToBitfield(PermissionFlags.BanMembers);  // "4"
+```

package/core/apps/docs-vitepress/v/latest/guides/sending-without-reply.md

@@ -0,0 +1,172 @@
+# Sending Without Reply
+
+Send messages to the same channel or to specific channels. Covers message.send(), message.sendTo(), client.channels.send(), and client.channels.resolve().
+
+## message.send() vs message.reply()
+
+message.reply() sends a message that references another message (shows as a "reply" in Discord). message.send() sends to the same channel with no reference—a regular standalone message.
+
+## Sending to the same channel
+
+Use message.send() when you want to post in the channel without replying. Same signature as reply(): pass a string or object with content and/or embeds.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!hello') {
+    await message.send('Hello! This is a regular message, not a reply.');
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Sending to a specific channel (e.g. logging)
+
+Use message.sendTo(channelId, payload) to send to another channel—handy for logging, announcements, or forwarding. You only need the target channel ID.
+
+```javascript
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+const LOG_CHANNEL_ID = process.env.LOG_CHANNEL_ID; // Your log channel's snowflake
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.content === '!report' && message.guildId && LOG_CHANNEL_ID) {
+    const embed = new EmbedBuilder()
+      .setTitle('User report')
+      .setDescription(message.content)
+      .addFields(
+        { name: 'Author', value: message.author.username, inline: true },
+        { name: 'Channel', value: `<#${message.channelId}>`, inline: true }
+      )
+      .setTimestamp();
+
+    await message.sendTo(LOG_CHANNEL_ID, { embeds: [embed] });
+    await message.send('Report logged.');
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## client.channels.send() — send by channel ID
+
+Use client.channels.send(channelId, payload) when you have a channel ID. Works even if the channel is not cached. No need to fetch first when you only need to send.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+const ANNOUNCE_CHANNEL_ID = process.env.ANNOUNCE_CHANNEL_ID;
+
+client.on(Events.Ready, async () => {
+  if (ANNOUNCE_CHANNEL_ID) {
+    await client.channels.send(ANNOUNCE_CHANNEL_ID, 'Bot is online!');
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## client.channels.resolve() — get channel by ID
+
+Resolve a channel by ID from cache or API. Use channel.canSendMessage() or channel.isTextBased() before sending. For sending when you only have an ID, prefer client.channels.send() which skips the fetch.
+
+```javascript
+import { Client } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+await client.login(process.env.ERIN_BOT_TOKEN);
+
+// Fetch channel (from API if not cached)
+const channel = await client.channels.resolve(channelId);
+if (channel?.canSendMessage()) {
+  await channel.send('Hello!');
+}
+// Or for webhooks: if (channel?.createWebhook) { ... }
+```
+
+## fetch message by id
+
+Use channel.messages.fetch(messageId) when you have the channel. For IDs-only, fetch the channel first.
+
+```javascript
+// When you have the channel
+const message = await channel.messages.fetch(messageId);
+if (message) {
+  await message.edit({ content: 'Updated!' });
+  await message.react('👍');
+}
+
+// When you only have IDs (e.g. from sqlite)
+const ch = await client.channels.resolve(channelId);
+const msg = await ch?.messages?.fetch(messageId);
+if (msg) await msg.delete();
+
+// When channel is cached
+const m = client.channels.get(channelId);
+if (m?.canSendMessage()) {
+  const mes = await m.messages.fetch(messageId);
+  if (mes) await mes.edit({ content: 'Edited!' });
+}
+
+// Refresh a stale message instance
+const updated = await message.fetch();
+if (updated) console.log(updated.content);
+```
+
+## message.channel and message.channel.send()
+
+message.channel returns the channel (from cache); null if not cached. Messages only exist in text-based channels, so when non-null it always has send(). Use message.channel.send() for the same as message.send() but via the channel object.
+
+```javascript
+client.on(Events.MessageCreate, async (message) => {
+  const channel = message.channel;   // TextChannel | DMChannel | GuildChannel | null
+  const guild = message.guild;       // Guild | null (null for DMs)
+  if (channel) {
+    await channel.send('Same channel, different API');  // or message.send()
+  }
+});
+```
+
+## channel.canSendMessage() — permission check
+
+Before sending, use canSendMessage() to check if the bot has ViewChannel and SendMessages. For DMs always true; for guild channels uses guild.members.me permissions.
+
+```javascript
+const channel = await client.channels.resolve(channelId);
+if (channel?.canSendMessage()) {
+  await channel.send('Hello!');
+}
+```
+
+## Typing indicator
+
+Use channel.sendTyping() before a slow operation so users see "Bot is typing...". Lasts ~10 seconds.
+
+```javascript
+const channel = message.channel ?? (await message.resolveChannel());
+if (channel?.canSendMessage?.()) {
+  await channel.sendTyping();
+  await slowOperation(); // e.g. fetch external API
+  await message.reply('Done!');
+}
+```
+
+## Quick reference
+
+```javascript
+// Same channel, no reply
+await message.send('Pong!');
+
+// Reply to the message
+await message.reply('Pong!');
+
+// Send to a specific channel
+await message.sendTo(logChannelId, 'User joined!');
+await client.channels.send(channelId, 'New update available!');
+```

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

@@ -0,0 +1,109 @@
+# Voice
+
+Join voice channels and play audio with @erinjs/voice. Supports WebM/Opus streams—no FFmpeg required.
+
+## Installation
+
+Add the voice package alongside the core library.
+
+```bash
+pnpm add @erinjs/voice @erinjs/core
+```
+
+## Setup
+
+Create a VoiceManager before login so it receives VoiceStatesSync from READY/GUILD_CREATE. This lets the manager see users already in voice when the bot starts.
+
+```javascript
+import { Client, Events, VoiceChannel } from '@erinjs/core';
+import { getVoiceManager } from '@erinjs/voice';
+
+const client = new Client({ intents: 0 });
+getVoiceManager(client); // Must be before login
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## Join a Voice Channel
+
+Get the user's voice channel with getVoiceChannelId, then join. The connection resolves when ready.
+
+```javascript
+const voiceManager = getVoiceManager(client);
+const voiceChannelId = voiceManager.getVoiceChannelId(guildId, userId);
+if (!voiceChannelId) return; // User not in voice
+
+const channel = client.channels.get(voiceChannelId);
+if (!(channel instanceof VoiceChannel)) return;
+
+const connection = await voiceManager.join(channel);
+```
+
+## Play Audio
+
+Play a WebM/Opus URL or stream. The voice package does not use FFmpeg—input must be WebM with Opus. Use yt-dlp or similar to get direct stream URLs from YouTube.
+
+```javascript
+// URL (fetched and demuxed automatically)
+await connection.play('https://example.com/audio.webm');
+
+// Or a Node.js ReadableStream of Opus
+await connection.play(opusStream);
+```
+
+## Getting Stream URLs from YouTube
+
+Use youtube-dl-exec or yt-dlp to extract a WebM/Opus URL.
+
+```javascript
+import youtubedl from 'youtube-dl-exec';
+
+const result = await youtubedl(videoUrl, {
+  getUrl: true,
+  f: 'bestaudio[ext=webm][acodec=opus]/bestaudio[ext=webm]/bestaudio',
+}, { timeout: 15000 });
+
+const streamUrl = String(result ?? '').trim();
+await connection.play(streamUrl);
+```
+
+## Volume Control
+
+LiveKitRtcConnection supports setVolume(0-200) and getVolume(). 100 = normal, 50 = half, 200 = double. Affects current and future playback.
+
+```javascript
+import { LiveKitRtcConnection } from '@erinjs/voice';
+
+if (connection instanceof LiveKitRtcConnection) {
+  connection.setVolume(80); // 80% volume
+  console.log('Current volume:', connection.getVolume());
+}
+```
+
+## Stop and Leave
+
+Stop playback and disconnect. getConnection accepts channel ID or guild ID. leave(guildId) leaves all channels; leaveChannel(channelId) leaves a specific channel.
+
+```javascript
+// By channel ID (primary) or guild ID
+const connection = voiceManager.getConnection(channelId) ?? voiceManager.getConnection(guildId);
+connection?.stop();
+if (connection) voiceManager.leaveChannel(connection.channel.id);
+// Or leave all channels in the guild:
+voiceManager.leave(guildId);
+```
+
+## LiveKit and serverLeave
+
+If using LiveKit, the server may emit serverLeave. Listen and reconnect if needed.
+
+```javascript
+connection.on?.('serverLeave', async () => {
+  try {
+    const conn = await voiceManager.join(channel);
+    await conn.play(streamUrl);
+  } catch (e) {
+    console.error('Auto-reconnect failed:', e);
+  }
+});
+```

package/core/apps/docs-vitepress/v/latest/guides/wait-for-guilds.md

@@ -0,0 +1,37 @@
+# Wait for All Guilds
+
+Delay the Ready event until all guilds have been received. Use when your bot needs the full guild cache before handling Ready.
+
+## Overview
+
+By default, Ready fires as soon as the gateway sends the READY payload. Some guilds may be sent as unavailable stubs and arrive later via GUILD_CREATE. Enable waitForGuilds if your Ready handler needs every guild to be in client.guilds before proceeding.
+
+## Usage
+
+Pass waitForGuilds: true in ClientOptions. Ready will emit only after all guilds from READY (including those marked unavailable) have been received via GUILD_CREATE.
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({
+  waitForGuilds: true,
+});
+
+client.on(Events.Ready, () => {
+  // client.guilds now contains every guild — no stubs, all fully loaded
+  console.log(`Bot is in ${client.guilds.size} guilds`);
+  for (const [id, guild] of client.guilds) {
+    console.log(`- ${guild.name} (${guild.channels.size} channels)`);
+  }
+});
+
+await client.login(process.env.ERIN_BOT_TOKEN);
+```
+
+## When to use it
+
+Use waitForGuilds when your bot iterates over all guilds in Ready (e.g. syncing state, broadcasting announcements, or building in-memory caches). Without it, client.guilds may be incomplete at Ready time.
+
+::: tip
+If you only need a few guilds by ID, prefer client.guilds.resolve(guildId) instead — no need to wait for all guilds.
+:::

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

@@ -0,0 +1,73 @@
+# Webhook Attachments & Embeds
+
+Send embeds with or without a title, and attach files to webhook messages—same API as channel messages.
+
+## Overview
+
+Webhooks support rich embeds and file attachments. Embeds can have just a description (no title required), and you can attach files the same way as with channel.send or message.reply.
+
+## Embeds Without a Title
+
+You do not need a title for embeds to work. At least one of title, description, fields, or image/thumbnail is required. A description-only embed is valid.
+
+```javascript
+import { Client, Webhook, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+
+// Description only—no title
+await webhook.send({
+  embeds: [
+    new EmbedBuilder()
+      .setDescription('This embed has no title. Description-only works fine.')
+      .setColor(0x5865f2)
+      .setTimestamp(),
+  ],
+});
+```
+
+## Direct Attachments
+
+Attach files to webhook messages using the files array. Each file needs name and data (Blob, ArrayBuffer, or Uint8Array). Optional filename overrides the display name.
+
+```javascript
+import { Client, Webhook } from '@erinjs/core';
+import { readFileSync } from 'fs';
+
+const client = new Client({ intents: 0 });
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+
+const buffer = readFileSync('report.pdf');
+await webhook.send({
+  content: 'Report attached',
+  files: [
+    { name: 'report.pdf', data: buffer },
+    { name: 'log.txt', data: new TextEncoder().encode('Log content'), filename: 'log-2025.txt' },
+  ],
+});
+```
+
+## Full Example: Embed + Files
+
+Combine content, description-only embed, and file attachments in a single webhook send.
+
+```javascript
+import { Client, Webhook, EmbedBuilder } from '@erinjs/core';
+import { readFileSync } from 'fs';
+
+const client = new Client({ intents: 0 });
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+
+await webhook.send({
+  content: 'Build completed',
+  embeds: [
+    new EmbedBuilder()
+      .setDescription('Deploy succeeded. See attachment for logs.')
+      .setColor(0x57f287)
+      .setTimestamp(),
+  ],
+  files: [{ name: 'deploy.log', data: readFileSync('deploy.log') }],
+  username: 'CI Bot',
+});
+```

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

@@ -0,0 +1,131 @@
+# Webhooks
+
+A complete guide to Discord webhooks—sending messages without a gateway, creating, editing, and managing webhooks.
+
+## What are Webhooks?
+
+Webhooks let you send messages to a channel using a URL (ID + token). You can use them in scripts, CI pipelines, or anywhere you need to post without a full bot connection. No gateway, no events—just REST.
+
+## Webhooks Without a Bot
+
+A Client with intents: 0 is enough. No need to connect to the gateway or handle events. Ideal for scripts or one-off sends.
+
+```javascript
+import { Client, Webhook } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+await webhook.send('Message from a script!');
+```
+
+## Creating a Webhook
+
+Create a webhook on a text channel. Requires Manage Webhooks permission. The token is returned only when creating—store it securely. It will never be returned when listing or fetching.
+
+```javascript
+import { Client } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+await client.login(process.env.ERIN_BOT_TOKEN);
+
+const channel = client.channels.get(channelId);
+if (!channel?.createWebhook) throw new Error('Channel does not support webhooks');
+
+const webhook = await channel.createWebhook({ name: 'My Webhook' });
+console.log(webhook.id, webhook.token); // Store token—it won't be returned when listing
+```
+
+## Sending Messages
+
+Send text, embeds, or both. You can override the username and avatar for each message.
+
+```javascript
+import { Client, Webhook, EmbedBuilder } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+
+await webhook.send({
+  content: 'Hello from webhook!',
+  embeds: [
+    new EmbedBuilder()
+      .setTitle('Webhook Message')
+      .setColor(0x5865f2)
+      .setTimestamp(),
+  ],
+  username: 'Custom Name',
+  avatar_url: 'https://example.com/avatar.png',
+});
+```
+
+## Simple text only
+
+```javascript
+await webhook.send('Plain text message');
+```
+
+## Embeds without a title
+
+Embeds can use only a description—no title required. At least one of title, description, fields, or image is needed.
+
+```javascript
+await webhook.send({
+  embeds: [
+    new EmbedBuilder()
+      .setDescription('Description-only embed works.')
+      .setColor(0x5865f2),
+  ],
+});
+```
+
+## Fetching & Listing Webhooks
+
+Fetch by ID or list channel/guild webhooks. Requires a logged-in bot. Fetched webhooks have no token and cannot send—but you can edit or delete them with bot auth.
+
+```javascript
+import { Client, Webhook } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+await client.login(process.env.ERIN_BOT_TOKEN);
+
+// Fetch single webhook (no token)
+const webhook = await Webhook.fetch(client, webhookId);
+
+// List channel webhooks
+const channel = client.channels.get(channelId);
+const channelWebhooks = await channel?.fetchWebhooks() ?? [];
+
+// List guild webhooks
+const guild = client.guilds.get(guildId);
+const guildWebhooks = await guild?.fetchWebhooks() ?? [];
+```
+
+## Editing a Webhook
+
+Use webhook.edit() to change name, avatar, or (with bot auth) channel. With a token (e.g. from createWebhook or fromToken), you can update name and avatar. Without a token (fetched webhook), bot auth lets you also change the target channel.
+
+```javascript
+import { Client, Webhook } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+await client.login(process.env.ERIN_BOT_TOKEN);
+
+// With token (name and avatar only)
+const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+await webhook.edit({ name: 'New Name', avatar: null });
+// avatar: null clears the webhook avatar
+
+// With bot auth (fetched webhook — can also move to another channel)
+const fetched = await Webhook.fetch(client, webhookId);
+await fetched.edit({
+  name: 'Updated Name',
+  channel_id: newChannelId,  // move webhook to different channel
+});
+```
+
+## Deleting a Webhook
+
+```javascript
+const webhook = await Webhook.fetch(client, webhookId);
+await webhook.delete();
+```