@erinjs/core 1.0.0 → 1.2.4

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

@@ -1,130 +0,0 @@
-# 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

@@ -1,172 +0,0 @@
-# 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

@@ -1,109 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,73 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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();
-```