@erinjs/core 1.0.0 → 1.2.4

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

@@ -1,69 +0,0 @@
-/**
- * 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

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

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

@@ -1,118 +0,0 @@
-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({});
-    });
-  });
-});