@erinjs/core 1.0.0

package/core/eslint.config.js

@@ -0,0 +1,80 @@
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const prettierConfig = require('eslint-config-prettier');
+const vuePlugin = require('eslint-plugin-vue');
+const vueParser = require('vue-eslint-parser');
+const globals = require('globals');
+
+module.exports = tseslint.config(
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'coverage/**',
+      '*.config.js',
+      '*.config.cjs',
+      '*.config.mjs',
+      'scripts/**',
+      '.turbo/**',
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.ts', '**/*.tsx', '**/*.js'],
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-non-null-assertion': 'off',
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+  },
+  ...(vuePlugin.configs['flat/recommended'] || []),
+  {
+    files: ['**/*.vue'],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: {
+        parser: tseslint.parser,
+        extraFileExtensions: ['.vue'],
+        sourceType: 'module',
+        ecmaVersion: 'latest',
+      },
+    },
+  },
+  {
+    files: ['apps/docs/**/*.{ts,tsx,vue}'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      'vue/multi-word-component-names': 'off',
+    },
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['examples/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': 'off',
+    },
+  },
+  prettierConfig,
+);

package/core/examples/.env.example

@@ -0,0 +1,22 @@
+# Required: Bot token from the Fluxer developer portal
+FLUXER_BOT_TOKEN=your_bot_token_here
+
+# Optional: Custom API base URL (default: https://api.fluxer.app)
+# FLUXER_API_URL=https://api.fluxer.app
+
+# Optional: Enable voice connection debug logging
+# VOICE_DEBUG=1
+
+# Optional: Use FFmpeg for video decoding (recommended on macOS)
+# FLUXER_VIDEO_FFMPEG=1
+
+# Reaction roles example: Message ID and channel ID for the roles message
+# REACTION_ROLES_MESSAGE_ID=
+# REACTION_ROLES_CHANNEL_ID=
+
+# Reaction roles: Role IDs for each emoji
+# ROLE_GAMING=
+# ROLE_MUSIC=
+# ROLE_ANNOUNCEMENTS=
+
+# Moderation example: No extra env vars needed (requires Ban Members / Kick Members)

package/core/examples/README.md

@@ -0,0 +1,68 @@
+# erin.js SDK Examples
+
+Example bots demonstrating common use cases with the erin.js SDK.
+
+## Quickest start
+
+From the repo root after `pnpm install && pnpm run build`:
+
+```bash
+FLUXER_BOT_TOKEN=your_token node examples/minimal-bot.js
+```
+
+That runs the [minimal bot](minimal-bot.js) — login + `!ping` → Pong. Guide route: `/v/latest/guides/basic-bot`.
+
+Public guide: https://erin.js.org/v/latest/guides/basic-bot
+
+To browse guides locally, run `pnpm run docs:dev` from the repo root and open `http://localhost:3333`.
+
+## Setup
+
+1. Install dependencies from the repository root:
+
+   ```bash
+   pnpm install
+   pnpm run build
+   ```
+
+2. Copy `.env.example` to `.env` and fill in your credentials:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. Run any example:
+
+   ```bash
+   FLUXER_BOT_TOKEN=your_token node examples/minimal-bot.js
+   ```
+
+## Examples
+
+| Example                                        | Description                                      | Guide                                                                                         |
+| ---------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| [minimal-bot.js](minimal-bot.js)               | Login + `!ping` → Pong                           | `/v/latest/guides/basic-bot`                                                                  |
+| [first-steps-bot.js](first-steps-bot.js)       | !ping, !hello, !avatar, !embed, !perms           | `/v/latest/guides/basic-bot`, `/v/latest/guides/profile-urls`, `/v/latest/guides/permissions` |
+| [ping-bot.js](ping-bot.js)                     | Prefix commands, embeds, DMs, voice, audio/video | `/v/latest/guides/basic-bot`, `/v/latest/guides/voice`                                        |
+| [reaction-bot.js](reaction-bot.js)             | Simple reaction handling                         | `/v/latest/guides/reactions`                                                                  |
+| [reaction-roles-bot.js](reaction-roles-bot.js) | Reaction-based role assignment                   | `/v/latest/guides/reactions`                                                                  |
+| [webhook-bot.js](webhook-bot.js)               | Webhook-based bot (no gateway)                   | `/v/latest/guides/webhooks`                                                                   |
+| [webi-bot.js](webi-bot.js)                     | Full webhook demo: embeds, files, all options    | `/v/latest/guides/webhook-attachments-embeds`                                                 |
+| [moderation-bot.js](moderation-bot.js)         | Ban, kick, unban, !perms (permissions)           | `/v/latest/guides/permissions`, `/v/latest/guides/moderation`                                 |
+
+## Environment Variables
+
+| Variable                          | Required               | Description                                  |
+| --------------------------------- | ---------------------- | -------------------------------------------- |
+| `FLUXER_BOT_TOKEN`                | Yes (for gateway bots) | Bot token from the Fluxer developer portal   |
+| `FLUXER_SUPPRESS_DEPRECATION`     | No                     | Set to `1` to silence deprecation warnings   |
+| `FLUXER_API_URL`                  | No                     | Custom API base URL                          |
+| `VOICE_DEBUG`                     | No                     | Set to `1` for voice connection logs         |
+| `FLUXER_VIDEO_FFMPEG`             | No                     | Set to `1` for FFmpeg video decoding (macOS) |
+| `REACTION_ROLES_MESSAGE_ID`       | No                     | Message ID for reaction roles                |
+| `REACTION_ROLES_CHANNEL_ID`       | No                     | Channel ID for reaction roles                |
+| `ROLE_GAMING`, `ROLE_MUSIC`, etc. | No                     | Role IDs for reaction roles emoji mapping    |
+
+## Documentation
+
+Full API reference: https://erin.js.org (or run `pnpm run docs:dev` and open `http://localhost:3333` for local docs).

package/core/examples/first-steps-bot.js

@@ -0,0 +1,118 @@
+/**
+ * First Steps Bot — five starter commands to learn the SDK.
+ *
+ * Commands: !ping, !hello [name], !avatar [@user], !embed, !perms
+ *
+ * Usage (from repo root after pnpm install && pnpm run build):
+ *   FLUXER_BOT_TOKEN=your_token node examples/first-steps-bot.js
+ *
+ * Guide route (local docs): /v/latest/guides/basic-bot
+ */
+
+import {
+  Client,
+  Events,
+  EmbedBuilder,
+  parsePrefixCommand,
+  parseUserMention,
+  PermissionFlags,
+} from '@erinjs/core';
+
+const PREFIX = '!';
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => console.log('Ready!'));
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.author.bot || !message.content) return;
+
+  const parsed = parsePrefixCommand(message.content, PREFIX);
+  if (!parsed) return;
+
+  const { command, args } = parsed;
+
+  try {
+    if (command === 'ping') {
+      await message.reply('Pong!');
+      return;
+    }
+
+    if (command === 'hello') {
+      const name = args[0] ?? message.author.username;
+      await message.reply(`Hello, ${name}!`);
+      return;
+    }
+
+    if (command === 'avatar') {
+      const target = args[0];
+      const userId = target ? parseUserMention(target) : message.author.id;
+      if (!userId) {
+        await message.reply('Mention a user or leave empty for yourself: `!avatar @user`');
+        return;
+      }
+      const user =
+        userId === message.author.id
+          ? message.author
+          : await client.users.fetch(userId).catch(() => null);
+      if (!user) {
+        await message.reply('Could not find that user.');
+        return;
+      }
+      const embed = new EmbedBuilder()
+        .setTitle(`${user.username}'s avatar`)
+        .setImage(user.displayAvatarURL({ size: 256 }))
+        .setColor(user.avatarColor ?? 0x5865f2)
+        .setTimestamp();
+      await message.reply({ embeds: [embed] });
+      return;
+    }
+
+    if (command === 'embed') {
+      const embed = new EmbedBuilder()
+        .setTitle('First embed')
+        .setDescription('You just sent an embed!')
+        .setColor(0x5865f2)
+        .addFields(
+          { name: 'Field 1', value: 'Value 1', inline: true },
+          { name: 'Field 2', value: 'Value 2', inline: true },
+        )
+        .setFooter({ text: 'erin.js' })
+        .setTimestamp();
+      await message.reply({ embeds: [embed] });
+      return;
+    }
+
+    if (command === 'perms') {
+      if (!message.guildId) {
+        await message.reply('Use this command in a server.');
+        return;
+      }
+      const guild = await client.guilds.resolve(message.guildId);
+      if (!guild) {
+        await message.reply('Could not find this server.');
+        return;
+      }
+      const member = await guild.members.resolve(message.author.id);
+      const has = (flag) => member.permissions.has(flag);
+      const permNames = [];
+      if (has(PermissionFlags.BanMembers)) permNames.push('BanMembers');
+      if (has(PermissionFlags.KickMembers)) permNames.push('KickMembers');
+      if (has(PermissionFlags.Administrator)) permNames.push('Administrator');
+      if (has(PermissionFlags.ManageRoles)) permNames.push('ManageRoles');
+      const embed = new EmbedBuilder()
+        .setTitle('Your permissions')
+        .setDescription(permNames.length ? permNames.join(', ') : '*(none of the common flags)*')
+        .setColor(0x57f287)
+        .setTimestamp();
+      await message.reply({ embeds: [embed] });
+      return;
+    }
+  } catch (err) {
+    console.error('Command error:', err);
+    await message.reply('Something went wrong.').catch(() => {});
+  }
+});
+
+client.on(Events.Error, (err) => console.error('Client error:', err));
+
+await client.login(process.env.FLUXER_BOT_TOKEN);

package/core/examples/minimal-bot.js

@@ -0,0 +1,17 @@
+/**
+ * Minimal erin.js bot — login + !ping → Pong.
+ * Usage: FLUXER_BOT_TOKEN=your_token node examples/minimal-bot.js
+ *
+ * Guide route (local docs): /v/latest/guides/basic-bot
+ */
+
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => console.log('Ready!'));
+client.on(Events.MessageCreate, async (m) => {
+  if (m.content === '!ping') await m.reply('Pong');
+});
+
+await client.login(process.env.FLUXER_BOT_TOKEN);

package/core/examples/moderation-bot.js

@@ -0,0 +1,209 @@
+/**
+ * erin.js Moderation Example
+ *
+ * Prefix commands for ban, kick, and unban. Requires Ban Members / Kick Members permissions.
+ * Server owner automatically has all permissions (no role needed).
+ *
+ * Commands:
+ *   !ban @user [reason]      - Ban a user (optional: delete messages from last 24h)
+ *   !kick @user [reason]     - Kick a user
+ *   !unban @user            - Remove a ban
+ *   !perms                  - List your guild-level permissions (owner sees all)
+ *
+ * Usage:
+ *   FLUXER_BOT_TOKEN=your_token node examples/moderation-bot.js
+ *
+ * @see /v/latest/guides/permissions (local docs)
+ * @see /v/latest/guides/moderation (local docs)
+ */
+
+import {
+  Client,
+  Events,
+  EmbedBuilder,
+  FluxerError,
+  ErrorCodes,
+  PermissionFlags,
+} from '@erinjs/core';
+
+const PREFIX = '!';
+
+/** Get the member who sent the message and their guild-level permissions. */
+async function getModeratorPerms(message) {
+  let guild = message.guild;
+  if (!guild && message.guildId) {
+    guild = await message.client.guilds.fetch(message.guildId);
+  }
+  if (!guild) return null;
+  let member = guild.members.get(message.author.id);
+  if (!member) {
+    try {
+      member = await guild.fetchMember(message.author.id);
+    } catch {
+      return null;
+    }
+  }
+  return member.permissions;
+}
+
+/** Extract user ID from mention (<@123> or <@!123>) or raw snowflake. */
+function parseUserId(arg) {
+  if (!arg?.trim()) return null;
+  const mentionMatch = arg.trim().match(/^<@!?(\d{17,19})>$/);
+  if (mentionMatch) return mentionMatch[1];
+  if (/^\d{17,19}$/.test(arg.trim())) return arg.trim();
+  return null;
+}
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => {
+  console.log(
+    `Logged in as ${client.user?.username}. Moderation commands: !ban, !kick, !unban, !perms`,
+  );
+});
+
+/** Return array of permission names the user has. */
+function getPermissionNames(perms) {
+  return Object.keys(PermissionFlags).filter((name) => perms.has(PermissionFlags[name]));
+}
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.author.bot || !message.content?.startsWith(PREFIX)) return;
+
+  const args = message.content.slice(PREFIX.length).trim().split(/\s+/);
+  const command = args[0]?.toLowerCase();
+  const targetArg = args[1];
+  const reason = args.slice(2).join(' ') || null;
+
+  let guild = message.guild;
+  if (!guild && message.guildId) {
+    guild = await message.client.guilds.fetch(message.guildId);
+  }
+  if (!guild) {
+    await message.reply('Moderation commands only work in a server.');
+    return;
+  }
+
+  const userId = parseUserId(targetArg);
+  const perms = await getModeratorPerms(message);
+  if (!perms) {
+    await message.reply(
+      'Could not load your member data. The bot may need access to view server members.',
+    );
+    return;
+  }
+
+  const canBan = perms.has(PermissionFlags.BanMembers) || perms.has(PermissionFlags.Administrator);
+  const canKick =
+    perms.has(PermissionFlags.KickMembers) || perms.has(PermissionFlags.Administrator);
+
+  if (command === 'perms') {
+    const names = getPermissionNames(perms);
+    await message.reply(
+      names.length > 0
+        ? `**Your server permissions:**\n\`\`\`\n${names.join(', ')}\n\`\`\``
+        : 'You have no server permissions.',
+    );
+    return;
+  }
+
+  if (command === 'ban') {
+    if (!canBan) {
+      await message.reply('You need the Ban Members permission to use this command.');
+      return;
+    }
+    if (!userId) {
+      await message.reply('Usage: `!ban @user [reason]`');
+      return;
+    }
+    try {
+      await guild.ban(userId, {
+        reason: reason ?? undefined,
+        delete_message_days: 1,
+      });
+      const targetUser = message.mentions.find((u) => u.id === userId) ?? { username: 'Unknown' };
+      const embed = new EmbedBuilder()
+        .setTitle('User Banned')
+        .setColor(0xe74c3c)
+        .addFields(
+          { name: 'User', value: `<@${userId}> (${targetUser.username})`, inline: true },
+          { name: 'Moderator', value: `${message.author.username}`, inline: true },
+        )
+        .setTimestamp();
+      if (reason) embed.addFields({ name: 'Reason', value: reason });
+      await message.reply({ embeds: [embed.toJSON()] });
+    } catch (err) {
+      const code = err instanceof FluxerError ? err.code : null;
+      const status = err?.statusCode ?? err?.cause?.statusCode;
+      const msg =
+        code === ErrorCodes.MemberNotFound || status === 404
+          ? 'User not found or not in this server.'
+          : (err?.message ?? 'Failed to ban user.');
+      await message.reply(`Error: ${msg}`);
+    }
+    return;
+  }
+
+  if (command === 'kick') {
+    if (!canKick) {
+      await message.reply('You need the Kick Members permission to use this command.');
+      return;
+    }
+    if (!userId) {
+      await message.reply('Usage: `!kick @user [reason]`');
+      return;
+    }
+    try {
+      await guild.kick(userId);
+      const targetUser = message.mentions.find((u) => u.id === userId) ?? { username: 'Unknown' };
+      const embed = new EmbedBuilder()
+        .setTitle('User Kicked')
+        .setColor(0xf39c12)
+        .addFields(
+          { name: 'User', value: `<@${userId}> (${targetUser.username})`, inline: true },
+          { name: 'Moderator', value: `${message.author.username}`, inline: true },
+        )
+        .setTimestamp();
+      if (reason) embed.addFields({ name: 'Reason', value: reason });
+      await message.reply({ embeds: [embed.toJSON()] });
+    } catch (err) {
+      const code = err instanceof FluxerError ? err.code : null;
+      const status = err?.statusCode ?? err?.cause?.statusCode;
+      const msg =
+        code === ErrorCodes.MemberNotFound || status === 404
+          ? 'User not found or not in this server.'
+          : (err?.message ?? 'Failed to kick user.');
+      await message.reply(`Error: ${msg}`);
+    }
+    return;
+  }
+
+  if (command === 'unban') {
+    if (!canBan) {
+      await message.reply('You need the Ban Members permission to use this command.');
+      return;
+    }
+    if (!userId) {
+      await message.reply('Usage: `!unban @user`');
+      return;
+    }
+    try {
+      await guild.unban(userId);
+      await message.reply(`Unbanned <@${userId}>.`);
+    } catch (err) {
+      const status = err?.statusCode ?? err?.cause?.statusCode;
+      const msg =
+        status === 404 ? 'User is not banned.' : (err?.message ?? 'Failed to unban user.');
+      await message.reply(`Error: ${msg}`);
+    }
+    return;
+  }
+});
+
+client.on(Events.Error, (err) => console.error('[fluxer]', err));
+
+client.login(process.env.FLUXER_BOT_TOKEN).catch((err) => {
+  console.error('Login failed:', err);
+  process.exit(1);
+});

package/core/examples/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "fluxer-examples",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint": "eslint . --max-warnings 0 --config ../eslint.config.js",
+    "lint:fix": "eslint . --fix --config ../eslint.config.js"
+  },
+  "dependencies": {
+    "@erinjs/core": "workspace:*",
+    "@erinjs/voice": "workspace:*",
+    "youtube-dl-exec": "^3.1.1"
+  }
+}