@erinjs/core 1.0.0

package/core/examples/reaction-bot.js

@@ -0,0 +1,70 @@
+/**
+ * Fluxer Reaction Detection Example
+ *
+ * Listens for when users react to messages. Demonstrates MESSAGE_REACTION_ADD
+ * and related gateway events. See packages/types/src/gateway/events.ts for all
+ * gateway event names (e.g. MESSAGE_REACTION_ADD, MESSAGE_REACTION_REMOVE).
+ *
+ * Usage (from repo root after npm install && npm run build):
+ *   FLUXER_BOT_TOKEN=your_token node examples/reaction-bot.js
+ */
+
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client();
+
+client.on(Events.Ready, () => {
+  console.log(`Logged in as ${client.user?.username}`);
+});
+
+// When someone adds a reaction to any message
+// MessageReactionAdd / MessageReactionRemove emit (reaction, user, messageId, channelId, emoji, userId)
+client.on(Events.MessageReactionAdd, (reaction, user, messageId, channelId, emoji, userId) => {
+  const emojiStr = emoji.id ? `<:${emoji.name}:${emoji.id}>` : emoji.name;
+  console.log(
+    `Reaction added: user ${userId} reacted with ${emojiStr} on message ${messageId} in channel ${channelId}`,
+  );
+});
+
+// Tip: filter by messageId or emoji for polls, confirmations, etc.:
+//   if (messageId !== myPollMessageId) return;
+//   if (emoji.name !== '👍') return;
+
+// Alternatively: client.events.MessageReactionAdd((reaction, user, messageId, channelId, emoji, userId) => { ... })
+
+// When someone removes their reaction
+client.on(Events.MessageReactionRemove, (reaction, user, messageId, channelId, emoji, userId) => {
+  const emojiStr = emoji.id ? `<:${emoji.name}:${emoji.id}>` : emoji.name;
+  console.log(`Reaction removed: user ${userId} removed ${emojiStr} from message ${messageId}`);
+});
+
+// When all reactions are removed from a message (moderator action)
+client.on(Events.MessageReactionRemoveAll, (data) => {
+  console.log(
+    `All reactions cleared from message ${data.message_id} in channel ${data.channel_id}`,
+  );
+});
+
+// When all reactions of a specific emoji are removed
+client.on(Events.MessageReactionRemoveEmoji, (data) => {
+  const emojiStr = data.emoji.id ? `<:${data.emoji.name}:${data.emoji.id}>` : data.emoji.name;
+  console.log(`All ${emojiStr} reactions removed from message ${data.message_id}`);
+});
+
+client.on(Events.Error, (err) => console.error('Client error:', err));
+
+const token = process.env.FLUXER_BOT_TOKEN;
+if (!token) {
+  console.error('Error: Set FLUXER_BOT_TOKEN environment variable');
+  process.exit(1);
+}
+
+client
+  .login(token)
+  .then(() => {
+    console.log('Listening for reactions...');
+  })
+  .catch((err) => {
+    console.error('Login failed:', err);
+    process.exit(1);
+  });

package/core/examples/reaction-roles-bot.js

@@ -0,0 +1,140 @@
+/**
+ * Fluxer Reaction Roles Example
+ *
+ * Users react to a message to get or remove roles. Run !roles to post the message
+ * (or set REACTION_ROLES_MESSAGE_ID and REACTION_ROLES_CHANNEL_ID to use an existing message).
+ *
+ * Usage:
+ *   FLUXER_BOT_TOKEN=your_token node examples/reaction-roles-bot.js
+ *
+ * Configure ROLE_EMOJI_MAP with your guild's role IDs.
+ */
+
+import { Client, Events, EmbedBuilder } from '@erinjs/core';
+
+// Map emoji (unicode or "name:id") to role ID. Update these for your server.
+const ROLE_EMOJI_MAP = {
+  '🎮': process.env.ROLE_GAMING ?? 'ROLE_ID_FOR_GAMING',
+  '🎵': process.env.ROLE_MUSIC ?? 'ROLE_ID_FOR_MUSIC',
+  '📢': process.env.ROLE_ANNOUNCEMENTS ?? 'ROLE_ID_FOR_ANNOUNCEMENTS',
+};
+
+const PREFIX = '!';
+
+const client = new Client({ intents: 0 });
+let rolesMessageId = process.env.REACTION_ROLES_MESSAGE_ID ?? null;
+const _rolesChannelId = process.env.REACTION_ROLES_CHANNEL_ID ?? null;
+
+function getRoleIdForEmoji(reaction) {
+  const key = reaction.emoji.id
+    ? `${reaction.emoji.name}:${reaction.emoji.id}`
+    : reaction.emoji.name;
+  return ROLE_EMOJI_MAP[key] ?? ROLE_EMOJI_MAP[reaction.emoji.name];
+}
+
+async function handleReactionAdd(reaction, user) {
+  if (!reaction.guildId || reaction.messageId !== rolesMessageId) return;
+
+  const roleId = getRoleIdForEmoji(reaction);
+  if (!roleId || roleId.startsWith('ROLE_ID_')) return;
+
+  const guild = client.guilds.get(reaction.guildId);
+  if (!guild) return;
+  let member;
+  try {
+    member = guild.members.get(user.id) ?? (await guild.fetchMember(user.id));
+  } catch {
+    return;
+  }
+  if (!member) return;
+
+  if (member.roles.cache.has(roleId)) return;
+
+  try {
+    await member.addRole(roleId);
+    console.log(`[reaction-roles] Added role ${roleId} to user ${user.id}`);
+  } catch (err) {
+    console.error('[reaction-roles] Failed to add role:', err.message);
+  }
+}
+
+async function handleReactionRemove(reaction, user) {
+  if (!reaction.guildId || reaction.messageId !== rolesMessageId) return;
+
+  const roleId = getRoleIdForEmoji(reaction);
+  if (!roleId || roleId.startsWith('ROLE_ID_')) return;
+
+  const guild = client.guilds.get(reaction.guildId);
+  if (!guild) return;
+  let member;
+  try {
+    member = guild.members.get(user.id) ?? (await guild.fetchMember(user.id));
+  } catch {
+    return;
+  }
+  if (!member) return;
+
+  if (!member.roles.cache.has(roleId)) return;
+
+  try {
+    await member.removeRole(roleId);
+    console.log(`[reaction-roles] Removed role ${roleId} from user ${user.id}`);
+  } catch (err) {
+    console.error('[reaction-roles] Failed to remove role:', err.message);
+  }
+}
+
+client.on(Events.Ready, () => {
+  console.log(`Logged in as ${client.user?.username}`);
+});
+
+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 cmd = args[0]?.toLowerCase();
+
+  if (cmd === 'roles') {
+    if (!message.guildId) {
+      await message.reply('Use this in a server channel.');
+      return;
+    }
+    const emojiList = Object.entries(ROLE_EMOJI_MAP)
+      .map(
+        ([emoji, id]) =>
+          `${emoji} ${id.startsWith('ROLE_ID_') ? '(configure ROLE_EMOJI_MAP)' : ''}`,
+      )
+      .join('\n');
+    const embed = new EmbedBuilder()
+      .setTitle('Reaction Roles')
+      .setDescription(
+        'React to get a role. Remove your reaction to remove the role.\n\n' + emojiList,
+      )
+      .setColor(0x5865f2)
+      .setTimestamp();
+    const reply = await message.reply({ embeds: [embed.toJSON()] });
+    for (const emoji of Object.keys(ROLE_EMOJI_MAP)) {
+      await reply
+        .react(emoji)
+        .catch((e) => console.warn('Could not add reaction', emoji, e.message));
+    }
+    rolesMessageId = reply.id;
+    console.log(
+      `[reaction-roles] Set roles message to ${reply.id}. Set REACTION_ROLES_MESSAGE_ID=${reply.id} and REACTION_ROLES_CHANNEL_ID=${message.channelId} to reuse.`,
+    );
+  }
+});
+
+client.on(Events.MessageReactionAdd, handleReactionAdd);
+client.on(Events.MessageReactionRemove, handleReactionRemove);
+client.on(Events.Error, (err) => console.error('Client error:', err));
+
+const token = process.env.FLUXER_BOT_TOKEN;
+if (!token) {
+  console.error('Error: Set FLUXER_BOT_TOKEN');
+  process.exit(1);
+}
+
+client.login(token).catch((err) => {
+  console.error('Login failed:', err);
+  process.exit(1);
+});

package/core/examples/webhook-bot.js

@@ -0,0 +1,239 @@
+/**
+ * Fluxer Webhook Example Bot
+ *
+ * Demonstrates the Webhook handler:
+ * - Creating webhooks via channel.createWebhook()
+ * - Fetching webhooks via channel.fetchWebhooks() / guild.fetchWebhooks()
+ * - Sending via webhook.send() and deleting via webhook.delete()
+ *
+ * Usage (from repo root after npm install && npm run build):
+ *   FLUXER_BOT_TOKEN=your_token node examples/webhook-bot.js
+ */
+
+import { Client, Events, EmbedBuilder, Webhook } from '@erinjs/core';
+
+const PREFIX = '!';
+const BRAND_COLOR = 0x4641d9;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Webhook Commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function handleWebhookCreate(message, client, args) {
+  const name = args[0] ?? 'My Webhook';
+
+  if (!message.guildId) {
+    await message.reply('Use this command in a server.');
+    return;
+  }
+
+  const channel = client.channels.get(message.channelId);
+  if (!channel?.createWebhook) {
+    await message.reply('This channel does not support webhooks.');
+    return;
+  }
+
+  try {
+    const webhook = await channel.createWebhook({ name });
+
+    const embed = new EmbedBuilder()
+      .setTitle('Webhook Created')
+      .setColor(BRAND_COLOR)
+      .addFields(
+        { name: 'Name', value: webhook.name, inline: true },
+        { name: 'ID', value: `\`${webhook.id}\``, inline: true },
+        { name: 'Channel ID', value: `\`${webhook.channelId}\``, inline: true },
+        {
+          name: 'Send',
+          value:
+            "Use `!webhook send` with the ID and token to send a message. **Store the token** – it won't be returned when listing webhooks.",
+        },
+      )
+      .setFooter({ text: 'Use !webhook send <id> <token> [message]' })
+      .setTimestamp();
+
+    await message.reply({ embeds: [embed.toJSON()] });
+  } catch (err) {
+    console.error('Webhook create error:', err);
+    await message.reply(`Failed to create webhook: ${err.message ?? err}`).catch(() => {});
+  }
+}
+
+async function handleWebhookList(message, client, args) {
+  const scope = args[0]?.toLowerCase(); // 'channel' or 'guild'
+
+  if (!message.guildId) {
+    await message.reply('Use this command in a server.');
+    return;
+  }
+
+  try {
+    const webhooks =
+      scope === 'guild'
+        ? await client.guilds.get(message.guildId)?.fetchWebhooks()
+        : await client.channels.get(message.channelId)?.fetchWebhooks();
+
+    if (!webhooks?.length) {
+      await message.reply(
+        `No webhooks in this ${scope === 'guild' ? 'guild' : 'channel'}. Use \`!webhook create\` to create one.`,
+      );
+      return;
+    }
+
+    const fields = webhooks.slice(0, 10).map((w) => ({
+      name: w.name ?? 'Unnamed',
+      value: `ID: \`${w.id}\`\nChannel: \`${w.channelId}\``,
+      inline: true,
+    }));
+
+    const embed = new EmbedBuilder()
+      .setTitle(`${scope === 'guild' ? 'Guild' : 'Channel'} Webhooks`)
+      .setColor(BRAND_COLOR)
+      .addFields(...fields)
+      .setFooter({
+        text: `Showing ${Math.min(webhooks.length, 10)} of ${webhooks.length} webhooks`,
+      })
+      .setTimestamp();
+
+    await message.reply({ embeds: [embed.toJSON()] });
+  } catch (err) {
+    console.error('Webhook list error:', err);
+    await message.reply(`Failed to fetch webhooks: ${err.message ?? err}`).catch(() => {});
+  }
+}
+
+async function handleWebhookSend(message, client, args) {
+  const webhookId = args[0];
+  const webhookToken = args[1];
+  const content = args.slice(2).join(' ');
+
+  if (!webhookId || !webhookToken) {
+    await message.reply(
+      'Usage: `!webhook send <webhook_id> <webhook_token> [message]`\nYou get the token when creating a webhook; it is not returned when listing.',
+    );
+    return;
+  }
+
+  try {
+    const webhook = Webhook.fromToken(client, webhookId, webhookToken);
+    await webhook.send(
+      content
+        ? { content }
+        : {
+            content: 'Hello from the Fluxer webhook bot!',
+            embeds: [
+              new EmbedBuilder()
+                .setTitle('Webhook Message')
+                .setDescription('This was sent via webhook.send().')
+                .setColor(BRAND_COLOR)
+                .setTimestamp()
+                .toJSON(),
+            ],
+          },
+    );
+
+    await message.reply('Message sent via webhook.');
+  } catch (err) {
+    console.error('Webhook send error:', err);
+    await message.reply(`Failed to send: ${err.message ?? err}`).catch(() => {});
+  }
+}
+
+async function handleWebhookDelete(message, client, args) {
+  const webhookId = args[0];
+
+  if (!webhookId) {
+    await message.reply('Usage: `!webhook delete <webhook_id>`');
+    return;
+  }
+
+  if (!message.guildId) {
+    await message.reply('Use this command in a server.');
+    return;
+  }
+
+  try {
+    const webhook = await Webhook.fetch(client, webhookId);
+    await webhook.delete();
+    await message.reply('Webhook deleted.');
+  } catch (err) {
+    console.error('Webhook delete error:', err);
+    await message.reply(`Failed to delete: ${err.message ?? err}`).catch(() => {});
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Client Setup
+// ─────────────────────────────────────────────────────────────────────────────
+
+const token = process.env.FLUXER_BOT_TOKEN;
+if (!token) {
+  console.error('Error: Set FLUXER_BOT_TOKEN environment variable');
+  process.exit(1);
+}
+
+const client = new Client({
+  intents: 0,
+  presence: { status: 'online', custom_status: { text: 'Managing webhooks' } },
+});
+
+client.on(Events.Ready, () => {
+  console.log(`Logged in as ${client.user?.username}`);
+  console.log('Webhook commands: !webhook create | list | send | delete');
+});
+
+client.on(Events.MessageCreate, async (message) => {
+  if (message.author.bot || !message.content) return;
+
+  const content = message.content.trim();
+  if (!content.startsWith(PREFIX)) return;
+
+  const args = content.slice(PREFIX.length).split(/\s+/);
+  const cmd = args.shift()?.toLowerCase();
+  const subcmd = args.shift()?.toLowerCase();
+
+  if (cmd !== 'webhook') return;
+
+  try {
+    switch (subcmd) {
+      case 'create':
+        await handleWebhookCreate(message, client, args);
+        break;
+      case 'list':
+        await handleWebhookList(message, client, args);
+        break;
+      case 'send':
+        await handleWebhookSend(message, client, args);
+        break;
+      case 'delete':
+        await handleWebhookDelete(message, client, args);
+        break;
+      default:
+        await message.reply(
+          '**Webhook commands:**\n' +
+            '`!webhook create [channel_id] [name]` – Create a webhook\n' +
+            '`!webhook list [channel|guild] [id]` – List webhooks\n' +
+            '`!webhook send <id> <token> [message]` – Send via webhook\n' +
+            '`!webhook delete <id>` – Delete a webhook',
+        );
+    }
+  } catch (err) {
+    console.error('Command error:', err);
+    await message.reply('An error occurred.').catch(() => {});
+  }
+});
+
+client.on(Events.Error, (err) => console.error('Client error:', err));
+
+process.on('unhandledRejection', (err) => {
+  console.error('Unhandled rejection:', err);
+  process.exit(1);
+});
+
+try {
+  await client.login(token);
+  console.log('Gateway connected');
+} catch (err) {
+  console.error('Login failed:', err);
+  process.exit(1);
+}

package/core/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "erinjs-monorepo",
+  "version": "1.2.4",
+  "private": true,
+  "license": "Apache-2.0",
+  "description": "erin.js SDK monorepo",
+  "scripts": {
+    "build": "turbo run build",
+    "test": "turbo run test",
+    "test:esm": "node scripts/test-esm-imports.mjs",
+    "test:cjs": "node scripts/test-cjs-require.mjs",
+    "test:load": "pnpm run test:esm && pnpm run test:cjs && pnpm run test:exports",
+    "test:exports": "node scripts/test-package-exports.mjs",
+    "test:smoke": "node scripts/test-smoke.mjs",
+    "test:all": "pnpm run build && pnpm exec vitest run && pnpm run test:load && pnpm run test:smoke",
+    "test:report": "pnpm run build && pnpm exec vitest run --reporter json --outputFile.json=test-results/results.json",
+    "lint": "turbo run lint --filter=!@erinjs/docs",
+    "lint:fix": "turbo run lint:fix --filter=!@erinjs/docs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test:coverage": "vitest run --coverage",
+    "clean": "turbo run clean && rm -rf node_modules",
+    "generate:types": "pnpm exec tsx scripts/generate-types.ts",
+    "generate:emoji": "pnpm exec tsx scripts/generate-emoji-shortcodes.ts",
+    "generate:docs": "pnpm exec tsx scripts/generate-docs.ts",
+    "generate:rag": "pnpm run generate:docs && pnpm exec tsx scripts/generate-ai-rag.ts",
+    "docs:generate": "pnpm run build && pnpm run generate:docs",
+    "docs:dev": "pnpm --filter @erinjs/docs dev",
+    "docs:build": "pnpm run build && pnpm run generate:docs && pnpm --filter @erinjs/docs build",
+    "docs:preview": "pnpm --filter @erinjs/docs preview",
+    "docs:deploy": "pnpm run docs:build && wrangler deploy",
+    "publish:packages": "node scripts/publish-ordered.js",
+    "publish:packages:all": "pnpm run build && pnpm -r publish --no-git-checks --filter '!./examples'"
+  },
+  "devDependencies": {
+    "@erinjs/builders": "workspace:*",
+    "@erinjs/collection": "workspace:*",
+    "@erinjs/core": "workspace:*",
+    "@erinjs/rest": "workspace:*",
+    "@erinjs/types": "workspace:*",
+    "@erinjs/util": "workspace:*",
+    "@erinjs/voice": "workspace:*",
+    "@erinjs/ws": "workspace:*",
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^10.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "dotenv": "^17.3.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.8.0",
+    "globals": "^17.3.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "tsx": "^4.19.0",
+    "turbo": "^2.3.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18",
+    "vue-eslint-parser": "^10.4.0",
+    "wrangler": "^4.0.0"
+  },
+  "packageManager": "pnpm@9.14.2",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "tar": ">=7.5.11",
+      "minimatch": ">=10.2.3",
+      "brace-expansion": ">=5.0.5",
+      "rollup": ">=4.59.0",
+      "esbuild": ">=0.25.0"
+    }
+  }
+}

package/core/packages/builders/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@erinjs/builders",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.4",
+  "description": "Builders for Fluxer messages and embeds",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blstmo-abandoned-us-for-the-milk/core.git",
+    "directory": "packages/builders"
+  },
+  "bugs": "https://github.com/blstmo-abandoned-us-for-the-milk/core/issues",
+  "homepage": "https://github.com/blstmo-abandoned-us-for-the-milk/core#readme",
+  "keywords": [
+    "fluxer",
+    "embed",
+    "builder",
+    "sdk"
+  ],
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --max-warnings 0 --config ../../eslint.config.js",
+    "lint:fix": "eslint src --fix --config ../../eslint.config.js",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  },
+  "dependencies": {
+    "@erinjs/types": "workspace:*",
+    "@erinjs/util": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}

package/core/packages/builders/src/index.ts

@@ -0,0 +1,13 @@
+export {
+  EmbedBuilder,
+  type EmbedAuthorOptions,
+  type EmbedFooterOptions,
+  type EmbedFieldData,
+  type EmbedMediaOptions,
+} from './messages/EmbedBuilder.js';
+export {
+  AttachmentBuilder,
+  type AttachmentPayloadOptions,
+  type APIAttachmentPayload,
+} from './messages/AttachmentBuilder.js';
+export { MessagePayload, type MessagePayloadData } from './messages/MessagePayload.js';

package/core/packages/builders/src/messages/AttachmentBuilder.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import { AttachmentBuilder } from './AttachmentBuilder.js';
+
+describe('AttachmentBuilder', () => {
+  it('creates with required id and filename', () => {
+    const att = new AttachmentBuilder(0, 'image.png');
+    expect(att.id).toBe(0);
+    expect(att.filename).toBe('image.png');
+    expect(att.spoiler).toBe(false);
+    expect(att.description).toBeUndefined();
+  });
+
+  it('creates with description and spoiler options', () => {
+    const att = new AttachmentBuilder(1, 'photo.jpg', {
+      description: 'A nice photo',
+      spoiler: true,
+    });
+    expect(att.id).toBe(1);
+    expect(att.filename).toBe('SPOILER_photo.jpg');
+    expect(att.description).toBe('A nice photo');
+    expect(att.spoiler).toBe(true);
+  });
+
+  it('throws for empty filename', () => {
+    expect(() => new AttachmentBuilder(0, '')).toThrow('Filename is required');
+    expect(() => new AttachmentBuilder(0, '   ')).toThrow('Filename is required');
+  });
+
+  it('setName updates filename', () => {
+    const att = new AttachmentBuilder(0, 'file.png');
+    att.setName('renamed.png');
+    expect(att.filename).toBe('renamed.png');
+  });
+
+  it('setName adds SPOILER_ prefix when spoiler is true', () => {
+    const att = new AttachmentBuilder(0, 'file.png', { spoiler: true });
+    att.setName('other.png');
+    expect(att.filename).toBe('SPOILER_other.png');
+  });
+
+  it('setName throws for empty', () => {
+    const att = new AttachmentBuilder(0, 'file.png');
+    expect(() => att.setName('')).toThrow('Filename is required');
+  });
+
+  it('setDescription updates description', () => {
+    const att = new AttachmentBuilder(0, 'file.png');
+    att.setDescription('Alt text');
+    expect(att.description).toBe('Alt text');
+    att.setDescription(null);
+    expect(att.description).toBeUndefined();
+  });
+
+  it('setSpoiler adds SPOILER_ prefix', () => {
+    const att = new AttachmentBuilder(0, 'file.png');
+    att.setSpoiler(true);
+    expect(att.spoiler).toBe(true);
+    expect(att.filename).toBe('SPOILER_file.png');
+  });
+
+  it('setSpoiler removes prefix when false', () => {
+    const att = new AttachmentBuilder(0, 'file.png', { spoiler: true });
+    att.setSpoiler(false);
+    expect(att.spoiler).toBe(false);
+    expect(att.filename).toBe('file.png');
+  });
+
+  it('toJSON returns API format', () => {
+    const att = new AttachmentBuilder(2, 'doc.pdf', { description: 'PDF document' });
+    const json = att.toJSON();
+    expect(json).toEqual({ id: 2, filename: 'doc.pdf', description: 'PDF document' });
+  });
+
+  it('toJSON omits description when undefined', () => {
+    const att = new AttachmentBuilder(0, 'image.png');
+    const json = att.toJSON();
+    expect(json).toEqual({ id: 0, filename: 'image.png', description: undefined });
+  });
+});