@erinjs/core 1.0.0

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

@@ -0,0 +1,69 @@
+/**
+ * Builder for message attachment metadata (filename, description, spoiler).
+ * Actual file data is passed separately when sending (e.g. FormData).
+ */
+export interface AttachmentPayloadOptions {
+  name: string;
+  description?: string;
+  spoiler?: boolean;
+}
+
+/** API format for an attachment in a message payload. */
+export interface APIAttachmentPayload {
+  id: number;
+  filename: string;
+  description?: string | null;
+}
+
+/** Builder for attachment metadata (filename, description, spoiler). Actual file data is passed separately when sending. */
+export class AttachmentBuilder {
+  public readonly id: number;
+  public filename: string;
+  public description?: string | null;
+  public spoiler: boolean;
+
+  /** @param id - Index of the attachment (0-based). Must match the FormData part order. */
+  constructor(id: number, filename: string, options?: Partial<AttachmentPayloadOptions>) {
+    if (!filename?.trim()) {
+      throw new Error('Filename is required');
+    }
+    this.id = id;
+    this.filename = options?.spoiler ? `SPOILER_${filename}` : filename;
+    this.description = options?.description ?? undefined;
+    this.spoiler = options?.spoiler ?? false;
+  }
+
+  /** Set the displayed filename. */
+  setName(name: string): this {
+    if (!name?.trim()) {
+      throw new Error('Filename is required');
+    }
+    this.filename = this.spoiler ? `SPOILER_${name}` : name;
+    return this;
+  }
+
+  /** Set the attachment description (alt text). */
+  setDescription(description: string | null): this {
+    this.description = description ?? undefined;
+    return this;
+  }
+
+  /** Mark the attachment as a spoiler (blurred until clicked). */
+  setSpoiler(spoiler = true): this {
+    this.spoiler = spoiler;
+    if (spoiler && !this.filename.startsWith('SPOILER_'))
+      this.filename = `SPOILER_${this.filename}`;
+    else if (!spoiler && this.filename.startsWith('SPOILER_'))
+      this.filename = this.filename.slice(8);
+    return this;
+  }
+
+  /** Convert to API format for MessagePayload. */
+  toJSON(): APIAttachmentPayload {
+    return {
+      id: this.id,
+      filename: this.filename,
+      description: this.description ?? undefined,
+    };
+  }
+}

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

@@ -0,0 +1,266 @@
+import { describe, it, expect } from 'vitest';
+import { EmbedBuilder } from './EmbedBuilder.js';
+
+describe('EmbedBuilder', () => {
+  describe('setVideo', () => {
+    it('sets video URL in toJSON output (type stays rich)', () => {
+      const url = 'https://example.com/video.mp4';
+      const embed = new EmbedBuilder().setTitle('Video embed').setVideo(url);
+      const json = embed.toJSON();
+
+      expect(json.video).toEqual({ url });
+      expect(json.type).toBe('rich');
+    });
+
+    it('clears video when passed null', () => {
+      const embed = new EmbedBuilder().setVideo('https://example.com/video.mp4').setVideo(null);
+      const json = embed.toJSON();
+
+      expect(json.video).toBeUndefined();
+    });
+
+    it('accepts full EmbedMediaOptions with duration, width, height', () => {
+      const options = {
+        url: 'https://example.com/video.mp4',
+        duration: 120,
+        width: 1920,
+        height: 1080,
+      };
+      const embed = new EmbedBuilder().setTitle('Video').setVideo(options);
+      const json = embed.toJSON();
+
+      expect(json.video).toEqual({
+        url: options.url,
+        duration: 120,
+        width: 1920,
+        height: 1080,
+      });
+      expect(json.type).toBe('rich');
+    });
+  });
+
+  describe('setAudio', () => {
+    it('sets audio URL in toJSON output', () => {
+      const url = 'https://example.com/audio.mp3';
+      const embed = new EmbedBuilder().setTitle('Audio embed').setAudio(url);
+      const json = embed.toJSON();
+
+      expect(json.audio).toEqual({ url });
+      expect(json.type).toBe('rich');
+    });
+
+    it('clears audio when passed null', () => {
+      const embed = new EmbedBuilder().setAudio('https://example.com/audio.mp3').setAudio(null);
+      const json = embed.toJSON();
+
+      expect(json.audio).toBeUndefined();
+    });
+
+    it('accepts full EmbedMediaOptions with duration', () => {
+      const options = {
+        url: 'https://example.com/podcast.mp3',
+        duration: 3600,
+        content_type: 'audio/mpeg',
+      };
+      const embed = new EmbedBuilder().setTitle('Podcast').setAudio(options);
+      const json = embed.toJSON();
+
+      expect(json.audio).toEqual({
+        url: options.url,
+        duration: 3600,
+        content_type: 'audio/mpeg',
+      });
+    });
+  });
+
+  describe('setImage and setThumbnail', () => {
+    it('accept string URL (backward compatibility)', () => {
+      const embed = new EmbedBuilder()
+        .setImage('https://example.com/img.png')
+        .setThumbnail('https://example.com/thumb.png');
+      const json = embed.toJSON();
+
+      expect(json.image).toEqual({ url: 'https://example.com/img.png' });
+      expect(json.thumbnail).toEqual({ url: 'https://example.com/thumb.png' });
+    });
+
+    it('accept full EmbedMediaOptions with width and height', () => {
+      const embed = new EmbedBuilder()
+        .setImage({
+          url: 'https://example.com/img.png',
+          width: 800,
+          height: 600,
+        })
+        .setThumbnail({
+          url: 'https://example.com/thumb.png',
+          width: 128,
+          height: 128,
+        });
+      const json = embed.toJSON();
+
+      expect(json.image).toEqual({
+        url: 'https://example.com/img.png',
+        width: 800,
+        height: 600,
+      });
+      expect(json.thumbnail).toEqual({
+        url: 'https://example.com/thumb.png',
+        width: 128,
+        height: 128,
+      });
+    });
+  });
+
+  describe('validation', () => {
+    it('setTitle throws for over 256 chars', () => {
+      const embed = new EmbedBuilder();
+      expect(() => embed.setTitle('x'.repeat(257))).toThrow(RangeError);
+    });
+
+    it('setDescription throws for over 4096 chars', () => {
+      const embed = new EmbedBuilder();
+      expect(() => embed.setDescription('x'.repeat(4097))).toThrow(RangeError);
+    });
+
+    it('setURL throws for invalid URL', () => {
+      const embed = new EmbedBuilder();
+      expect(() => embed.setURL('not-a-valid-url')).toThrow('Invalid embed URL');
+    });
+
+    it('setImage throws for invalid media URL', () => {
+      const embed = new EmbedBuilder();
+      expect(() => embed.setImage({ url: 'invalid', width: 100 })).toThrow(
+        'Invalid embed media URL',
+      );
+    });
+
+    it('toJSON throws when total length exceeds 6000', () => {
+      const embed = new EmbedBuilder()
+        .setTitle('x'.repeat(256))
+        .setDescription('y'.repeat(2000))
+        .addFields(
+          { name: 'n'.repeat(256), value: 'v'.repeat(600) },
+          { name: 'n'.repeat(256), value: 'v'.repeat(600) },
+          { name: 'n'.repeat(256), value: 'v'.repeat(600) },
+          { name: 'n'.repeat(256), value: 'v'.repeat(600) },
+          { name: 'n'.repeat(256), value: 'v'.repeat(500) },
+        );
+      expect(() => embed.toJSON()).toThrow(RangeError);
+    });
+  });
+
+  describe('setAuthor and setFooter', () => {
+    it('setAuthor with name, url, iconURL', () => {
+      const embed = new EmbedBuilder().setAuthor({
+        name: 'Author',
+        url: 'https://example.com',
+        iconURL: 'https://example.com/icon.png',
+      });
+      const json = embed.toJSON();
+      expect(json.author).toEqual({
+        name: 'Author',
+        url: 'https://example.com',
+        icon_url: 'https://example.com/icon.png',
+      });
+    });
+
+    it('setFooter with text and iconURL', () => {
+      const embed = new EmbedBuilder().setFooter({
+        text: 'Footer text',
+        iconURL: 'https://example.com/footer.png',
+      });
+      const json = embed.toJSON();
+      expect(json.footer).toEqual({
+        text: 'Footer text',
+        icon_url: 'https://example.com/footer.png',
+      });
+    });
+
+    it('setAuthor null clears author', () => {
+      const embed = new EmbedBuilder().setAuthor({ name: 'A' }).setAuthor(null);
+      expect(embed.toJSON().author).toBeUndefined();
+    });
+  });
+
+  describe('setColor and setTimestamp', () => {
+    it('setColor accepts number, hex, RGB array', () => {
+      const embed = new EmbedBuilder().setColor(0xff0000);
+      expect(embed.toJSON().color).toBe(0xff0000);
+      embed.setColor('#00ff00');
+      expect(embed.toJSON().color).toBe(0x00ff00);
+      embed.setColor([0, 0, 255]);
+      expect(embed.toJSON().color).toBe(0x0000ff);
+    });
+
+    it('setColor null clears', () => {
+      const embed = new EmbedBuilder().setColor(0xff0000).setColor(null);
+      expect(embed.toJSON().color).toBeUndefined();
+    });
+
+    it('setTimestamp accepts Date and number', () => {
+      const d = new Date('2021-01-01T00:00:00Z');
+      const embed = new EmbedBuilder().setTitle('T').setTimestamp(d);
+      expect(embed.toJSON().timestamp).toBe('2021-01-01T00:00:00.000Z');
+      embed.setTimestamp(1609459200000);
+      expect(embed.toJSON().timestamp).toBe('2021-01-01T00:00:00.000Z');
+    });
+  });
+
+  describe('addFields and spliceFields', () => {
+    it('addFields adds multiple', () => {
+      const embed = new EmbedBuilder()
+        .setTitle('T')
+        .addFields({ name: 'A', value: '1' }, { name: 'B', value: '2', inline: true });
+      const json = embed.toJSON();
+      expect(json.fields).toHaveLength(2);
+      expect(json.fields![0]).toEqual({ name: 'A', value: '1', inline: undefined });
+      expect(json.fields![1]).toEqual({ name: 'B', value: '2', inline: true });
+    });
+
+    it('spliceFields replaces at index', () => {
+      const embed = new EmbedBuilder()
+        .setTitle('T')
+        .addFields({ name: 'A', value: '1' }, { name: 'B', value: '2' })
+        .spliceFields(1, 1, { name: 'X', value: 'replacement' });
+      const json = embed.toJSON();
+      expect(json.fields).toHaveLength(2);
+      expect(json.fields![1].name).toBe('X');
+    });
+  });
+
+  describe('EmbedBuilder.from', () => {
+    it('restores video from existing embed (type always rich)', () => {
+      const source = {
+        video: { url: 'https://media.tenor.com/videos/xyz.mp4' },
+      };
+      const rebuilt = EmbedBuilder.from(source);
+      const json = rebuilt.toJSON();
+
+      expect(json.video).toEqual(source.video);
+      expect(json.type).toBe('rich');
+    });
+
+    it('preserves video and audio with full metadata', () => {
+      const source = {
+        video: {
+          url: 'https://example.com/video.mp4',
+          duration: 90,
+          width: 1280,
+          height: 720,
+          flags: 0,
+        },
+        audio: {
+          url: 'https://example.com/audio.mp3',
+          duration: 180,
+          content_type: 'audio/mpeg',
+          flags: 0,
+        },
+      };
+      const rebuilt = EmbedBuilder.from(source);
+      const json = rebuilt.toJSON();
+
+      expect(json.video).toEqual(source.video);
+      expect(json.audio).toEqual(source.audio);
+    });
+  });
+});

package/core/packages/builders/src/messages/EmbedBuilder.ts

@@ -0,0 +1,239 @@
+import { APIEmbed, APIEmbedAuthor, APIEmbedFooter, APIEmbedMedia } from '@erinjs/types';
+import { resolveColor } from '@erinjs/util';
+
+/** Options for embed media (image, thumbnail, video, audio). */
+export interface EmbedMediaOptions {
+  url: string;
+  content_type?: string | null;
+  width?: number | null;
+  height?: number | null;
+  description?: string | null;
+  placeholder?: string | null;
+  duration?: number | null;
+  flags?: number | null;
+}
+
+const EMBED_MAX = {
+  title: 256,
+  description: 4096,
+  fields: 25,
+  fieldName: 256,
+  fieldValue: 1024,
+  footerText: 2048,
+  authorName: 256,
+  total: 6000,
+};
+
+function toEmbedMedia(input: string | EmbedMediaOptions): APIEmbedMedia {
+  if (typeof input === 'string') {
+    return { url: input };
+  }
+  if (!URL.canParse(input.url)) {
+    throw new Error('Invalid embed media URL');
+  }
+  const media: APIEmbedMedia = { url: input.url };
+  if (input.content_type != null) media.content_type = input.content_type;
+  if (input.width != null) media.width = input.width;
+  if (input.height != null) media.height = input.height;
+  if (input.description != null) media.description = input.description;
+  if (input.placeholder != null) media.placeholder = input.placeholder;
+  if (input.duration != null) media.duration = input.duration;
+  if (input.flags != null) media.flags = input.flags;
+  return media;
+}
+
+/** Author field for an embed. */
+export interface EmbedAuthorOptions {
+  name: string;
+  iconURL?: string;
+  url?: string;
+}
+
+/** Footer field for an embed. */
+export interface EmbedFooterOptions {
+  text: string;
+  iconURL?: string;
+}
+
+/** A single embed field (name, value, optional inline). */
+export interface EmbedFieldData {
+  name: string;
+  value: string;
+  inline?: boolean;
+}
+
+/**
+ * Builder for creating rich embeds. Use `toJSON()` when passing to `reply`, `send`, or `edit`.
+ * Embeds must have at least one of: title, description, fields, or image/thumbnail.
+ * A description-only embed (no title) is valid.
+ */
+export class EmbedBuilder {
+  public readonly data: Partial<APIEmbed> = {};
+
+  /** Set the embed title. Max 256 characters. */
+  setTitle(title: string | null): this {
+    if (title !== null && title.length > EMBED_MAX.title)
+      throw new RangeError(`Title must be ≤${EMBED_MAX.title} characters`);
+    this.data.title = title ?? undefined;
+    return this;
+  }
+
+  /** Set the embed description. Max 4096 characters. */
+  setDescription(description: string | null): this {
+    if (description !== null && description.length > EMBED_MAX.description)
+      throw new RangeError(`Description must be ≤${EMBED_MAX.description} characters`);
+    this.data.description = description ?? undefined;
+    return this;
+  }
+
+  /** Set the embed URL (title becomes a link). */
+  setURL(url: string | null): this {
+    if (url != null && url !== '' && !URL.canParse(url)) {
+      throw new Error('Invalid embed URL');
+    }
+    this.data.url = url ?? undefined;
+    return this;
+  }
+
+  /** Set the embed color. Number (hex), hex string, or `[r,g,b]` array. */
+  setColor(color: number | string | [number, number, number] | null): this {
+    if (color === null) {
+      this.data.color = undefined;
+      return this;
+    }
+    this.data.color = typeof color === 'number' ? color : resolveColor(color);
+    return this;
+  }
+
+  /** Set the embed timestamp. Omit for current time. */
+  setTimestamp(timestamp?: Date | number | null): this {
+    if (timestamp === undefined || timestamp === null) {
+      this.data.timestamp = undefined;
+      return this;
+    }
+    const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
+    this.data.timestamp = date.toISOString();
+    return this;
+  }
+
+  /** Set the embed author (name, optional icon URL and link). */
+  setAuthor(options: EmbedAuthorOptions | null): this {
+    if (!options) {
+      this.data.author = undefined;
+      return this;
+    }
+    const name = options.name.slice(0, EMBED_MAX.authorName);
+    const author: APIEmbedAuthor = { name };
+    if (options.url) author.url = options.url;
+    if (options.iconURL) author.icon_url = options.iconURL;
+    this.data.author = author;
+    return this;
+  }
+
+  /** Set the embed footer (text, optional icon URL). */
+  setFooter(options: EmbedFooterOptions | null): this {
+    if (!options) {
+      this.data.footer = undefined;
+      return this;
+    }
+    const text = options.text.slice(0, EMBED_MAX.footerText);
+    const footer: APIEmbedFooter = { text };
+    if (options.iconURL) footer.icon_url = options.iconURL;
+    this.data.footer = footer;
+    return this;
+  }
+
+  /** Set the embed image (URL string or full media options). */
+  setImage(input: string | EmbedMediaOptions | null): this {
+    this.data.image = input ? toEmbedMedia(input) : undefined;
+    return this;
+  }
+
+  /** Set the embed thumbnail (URL string or full media options). */
+  setThumbnail(input: string | EmbedMediaOptions | null): this {
+    this.data.thumbnail = input ? toEmbedMedia(input) : undefined;
+    return this;
+  }
+
+  /**
+   * Set the embed video. Supported by Fluxer.
+   * Embed stays type 'rich'; this adds the .video field.
+   * Include a title (e.g. setTitle) when using video.
+   *
+   * @param input - Video URL, full media options (e.g. duration for progress bars), or null to clear
+   */
+  setVideo(input: string | EmbedMediaOptions | null): this {
+    this.data.video = input ? toEmbedMedia(input) : undefined;
+    return this;
+  }
+
+  /**
+   * Set the embed audio. Supported by Fluxer.
+   *
+   * @param input - Audio URL, full media options, or null to clear
+   */
+  setAudio(input: string | EmbedMediaOptions | null): this {
+    this.data.audio = input ? toEmbedMedia(input) : undefined;
+    return this;
+  }
+
+  /** Add one or more fields. Max 25 fields. */
+  addFields(...fields: EmbedFieldData[]): this {
+    const current = (this.data.fields ?? []).slice();
+    for (const f of fields) {
+      if (current.length >= EMBED_MAX.fields) break;
+      current.push({
+        name: f.name.slice(0, EMBED_MAX.fieldName),
+        value: f.value.slice(0, EMBED_MAX.fieldValue),
+        inline: f.inline,
+      });
+    }
+    this.data.fields = current.length ? current : undefined;
+    return this;
+  }
+
+  spliceFields(index: number, deleteCount: number, ...fields: EmbedFieldData[]): this {
+    const current = (this.data.fields ?? []).slice();
+    const toAdd = fields.map((f) => ({
+      name: f.name.slice(0, EMBED_MAX.fieldName),
+      value: f.value.slice(0, EMBED_MAX.fieldValue),
+      inline: f.inline,
+    }));
+    current.splice(index, deleteCount, ...toAdd);
+    this.data.fields = current.length ? current : undefined;
+    return this;
+  }
+
+  /** Convert to API embed format for `reply`, `send`, or `edit`. */
+  toJSON(): APIEmbed {
+    const totalLength = [
+      this.data.title,
+      this.data.description,
+      ...(this.data.fields ?? []).flatMap((f) => [f.name, f.value]),
+      this.data.footer?.text,
+    ]
+      .filter(Boolean)
+      .join('').length;
+    if (totalLength > EMBED_MAX.total)
+      throw new RangeError(`Embed total length must be ≤${EMBED_MAX.total}`);
+    return { ...this.data, type: 'rich' } as APIEmbed;
+  }
+
+  /** Create an EmbedBuilder from an existing API embed. */
+  static from(data: APIEmbed): EmbedBuilder {
+    const b = new EmbedBuilder();
+    b.data.title = data.title ?? undefined;
+    b.data.description = data.description ?? undefined;
+    b.data.url = data.url ?? undefined;
+    b.data.color = data.color ?? undefined;
+    b.data.timestamp = data.timestamp ?? undefined;
+    b.data.author = data.author ?? undefined;
+    b.data.footer = data.footer ?? undefined;
+    b.data.image = data.image ?? undefined;
+    b.data.thumbnail = data.thumbnail ?? undefined;
+    b.data.video = data.video ?? undefined;
+    b.data.audio = data.audio ?? undefined;
+    b.data.fields = data.fields ?? undefined;
+    return b;
+  }
+}

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

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import { MessagePayload } from './MessagePayload.js';
+import { EmbedBuilder } from './EmbedBuilder.js';
+import { AttachmentBuilder } from './AttachmentBuilder.js';
+
+describe('MessagePayload', () => {
+  it('creates empty payload', () => {
+    const p = new MessagePayload();
+    expect(p.toJSON()).toEqual({});
+  });
+
+  it('setContent sets and clears', () => {
+    const p = new MessagePayload();
+    p.setContent('hello');
+    expect(p.data.content).toBe('hello');
+    p.setContent(null);
+    expect(p.data.content).toBeUndefined();
+  });
+
+  it('setContent throws for over 2000 chars', () => {
+    const p = new MessagePayload();
+    expect(() => p.setContent('x'.repeat(2001))).toThrow(RangeError);
+  });
+
+  it('setContent accepts exactly 2000 chars', () => {
+    const p = new MessagePayload();
+    p.setContent('x'.repeat(2000));
+    expect(p.data.content).toHaveLength(2000);
+  });
+
+  it('setEmbeds accepts EmbedBuilder and raw APIEmbed', () => {
+    const embed = new EmbedBuilder().setTitle('T').setDescription('D');
+    const p = new MessagePayload().setEmbeds([embed]);
+    expect(p.data.embeds).toHaveLength(1);
+    expect(p.data.embeds![0]).toEqual(embed.toJSON());
+  });
+
+  it('setEmbeds throws for more than 10', () => {
+    const p = new MessagePayload();
+    const embeds = Array.from({ length: 11 }, () =>
+      new EmbedBuilder().setTitle('x').setDescription('y'),
+    );
+    expect(() => p.setEmbeds(embeds)).toThrow(RangeError);
+  });
+
+  it('addEmbed adds one at a time', () => {
+    const p = new MessagePayload();
+    p.addEmbed(new EmbedBuilder().setTitle('1').setDescription('a'));
+    p.addEmbed(new EmbedBuilder().setTitle('2').setDescription('b'));
+    expect(p.data.embeds).toHaveLength(2);
+    expect(p.data.embeds![0].title).toBe('1');
+    expect(p.data.embeds![1].title).toBe('2');
+  });
+
+  it('setAttachments accepts AttachmentBuilder', () => {
+    const att = new AttachmentBuilder(0, 'file.png');
+    const p = new MessagePayload().setAttachments([att]);
+    expect(p.data.attachments).toEqual([{ id: 0, filename: 'file.png', description: undefined }]);
+  });
+
+  it('setAttachments accepts plain objects', () => {
+    const p = new MessagePayload().setAttachments([
+      { id: 0, filename: 'a.txt', description: 'desc' },
+    ]);
+    expect(p.data.attachments).toEqual([{ id: 0, filename: 'a.txt', description: 'desc' }]);
+  });
+
+  it('setReply sets message_reference', () => {
+    const p = new MessagePayload().setReply({
+      channel_id: 'c1',
+      message_id: 'm1',
+      guild_id: 'g1',
+    });
+    expect(p.data.message_reference).toEqual({
+      channel_id: 'c1',
+      message_id: 'm1',
+      guild_id: 'g1',
+    });
+  });
+
+  it('setReply omits guild_id when null', () => {
+    const p = new MessagePayload().setReply({
+      channel_id: 'c1',
+      message_id: 'm1',
+      guild_id: null,
+    });
+    expect(p.data.message_reference?.guild_id).toBeUndefined();
+  });
+
+  it('setTTS and setFlags', () => {
+    const p = new MessagePayload().setTTS(true).setFlags(64);
+    expect(p.data.tts).toBe(true);
+    expect(p.data.flags).toBe(64);
+  });
+
+  describe('MessagePayload.create', () => {
+    it('creates from string', () => {
+      const p = MessagePayload.create('Hi');
+      expect(p.data.content).toBe('Hi');
+    });
+
+    it('creates from options object', () => {
+      const p = MessagePayload.create({
+        content: 'Test',
+        embeds: [new EmbedBuilder().setTitle('E').setDescription('D')],
+        tts: true,
+      });
+      expect(p.data.content).toBe('Test');
+      expect(p.data.embeds).toHaveLength(1);
+      expect(p.data.tts).toBe(true);
+    });
+
+    it('creates empty when no args', () => {
+      const p = MessagePayload.create();
+      expect(p.toJSON()).toEqual({});
+    });
+  });
+});