baff.js 0.0.0-stage → 0.1.0

package/dist/esm/builders/components/LayoutBuilders.d.ts

@@ -0,0 +1,63 @@
+import type { APIComponent } from '../../types.js';
+import { type ColorResolvable } from '../EmbedBuilder.js';
+import { ButtonBuilder } from './ButtonBuilder.js';
+import { ComponentBuilder, type ComponentInput } from './shared.js';
+export declare class TextDisplayBuilder extends ComponentBuilder {
+    private content?;
+    constructor(content?: string);
+    setContent(content: string): this;
+    toJSON(): APIComponent;
+}
+export declare class ThumbnailBuilder extends ComponentBuilder {
+    private media?;
+    private description?;
+    private spoiler;
+    setURL(mediaUrl: string): this;
+    setDescription(description: string): this;
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(): APIComponent;
+}
+export declare class MediaGalleryItemBuilder {
+    private media?;
+    private description?;
+    private spoiler;
+    setURL(mediaUrl: string): this;
+    setDescription(description: string): this;
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(path?: string): Record<string, unknown>;
+}
+export declare class MediaGalleryBuilder extends ComponentBuilder {
+    private items;
+    addItems(...items: (MediaGalleryItemBuilder | {
+        media: {
+            url: string;
+        };
+        description?: string;
+        spoiler?: boolean;
+    })[]): this;
+    toJSON(): APIComponent;
+}
+export declare class SeparatorBuilder extends ComponentBuilder {
+    private divider;
+    private spacing;
+    setDivider(divider?: boolean): this;
+    setSpacing(spacing: number): this;
+    toJSON(): APIComponent;
+}
+export declare class SectionBuilder extends ComponentBuilder {
+    private texts;
+    private accessory?;
+    addTextDisplayComponents(...texts: (TextDisplayBuilder | string)[]): this;
+    setThumbnailAccessory(thumbnail: ThumbnailBuilder): this;
+    setButtonAccessory(button: ButtonBuilder): this;
+    toJSON(): APIComponent;
+}
+export declare class ContainerBuilder extends ComponentBuilder {
+    private children;
+    private accent?;
+    private spoiler;
+    addComponents(...components: ComponentInput[]): this;
+    setAccentColor(color: ColorResolvable | null): this;
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(): APIComponent;
+}

package/dist/esm/builders/components/LayoutBuilders.js

@@ -0,0 +1,169 @@
+import { ComponentType, SeparatorSpacing } from '../../util/constants.js';
+import { resolveColor } from '../EmbedBuilder.js';
+import { fail, range, resolveJSON, text, url } from '../validate.js';
+import { ComponentBuilder } from './shared.js';
+const code = 'INVALID_COMPONENT';
+export class TextDisplayBuilder extends ComponentBuilder {
+    content;
+    constructor(content) {
+        super();
+        this.content = content;
+    }
+    setContent(content) {
+        this.content = content;
+        return this;
+    }
+    toJSON() {
+        return { ...this.base(ComponentType.TextDisplay), content: text(code, 'textDisplay.content', this.content, 4000) };
+    }
+}
+export class ThumbnailBuilder extends ComponentBuilder {
+    media;
+    description;
+    spoiler = false;
+    setURL(mediaUrl) {
+        this.media = mediaUrl;
+        return this;
+    }
+    setDescription(description) {
+        this.description = description;
+        return this;
+    }
+    setSpoiler(spoiler = true) {
+        this.spoiler = spoiler;
+        return this;
+    }
+    toJSON() {
+        const out = this.base(ComponentType.Thumbnail);
+        out.media = { url: url(code, 'thumbnail.url', this.media, false) };
+        const description = text(code, 'thumbnail.description', this.description, 1024, { optional: true });
+        if (description !== undefined)
+            out.description = description;
+        out.spoiler = this.spoiler;
+        return out;
+    }
+}
+export class MediaGalleryItemBuilder {
+    media;
+    description;
+    spoiler = false;
+    setURL(mediaUrl) {
+        this.media = mediaUrl;
+        return this;
+    }
+    setDescription(description) {
+        this.description = description;
+        return this;
+    }
+    setSpoiler(spoiler = true) {
+        this.spoiler = spoiler;
+        return this;
+    }
+    toJSON(path = 'mediaGallery.items[0]') {
+        const out = { media: { url: url(code, `${path}.url`, this.media, false) } };
+        const description = text(code, `${path}.description`, this.description, 1024, { optional: true });
+        if (description !== undefined)
+            out.description = description;
+        out.spoiler = this.spoiler;
+        return out;
+    }
+}
+export class MediaGalleryBuilder extends ComponentBuilder {
+    items = [];
+    addItems(...items) {
+        this.items.push(...items);
+        return this;
+    }
+    toJSON() {
+        if (!this.items.length || this.items.length > 10)
+            fail(code, 'mediaGallery.items', 'needs 1-10 items.');
+        const items = this.items.map((item, i) => {
+            const path = `mediaGallery.items[${i}]`;
+            if (item instanceof MediaGalleryItemBuilder)
+                return item.toJSON(path);
+            const built = new MediaGalleryItemBuilder().setURL(item.media.url);
+            if (item.description)
+                built.setDescription(item.description);
+            if (item.spoiler)
+                built.setSpoiler();
+            return built.toJSON(path);
+        });
+        return { ...this.base(ComponentType.MediaGallery), items };
+    }
+}
+export class SeparatorBuilder extends ComponentBuilder {
+    divider = true;
+    spacing = SeparatorSpacing.Small;
+    setDivider(divider = true) {
+        this.divider = divider;
+        return this;
+    }
+    setSpacing(spacing) {
+        this.spacing = spacing;
+        return this;
+    }
+    toJSON() {
+        if (this.spacing !== 1 && this.spacing !== 2)
+            fail(code, 'separator.spacing', 'must be Small (1) or Large (2).');
+        return { ...this.base(ComponentType.Separator), divider: this.divider, spacing: this.spacing };
+    }
+}
+export class SectionBuilder extends ComponentBuilder {
+    texts = [];
+    accessory;
+    addTextDisplayComponents(...texts) {
+        this.texts.push(...texts);
+        return this;
+    }
+    setThumbnailAccessory(thumbnail) {
+        this.accessory = thumbnail;
+        return this;
+    }
+    setButtonAccessory(button) {
+        this.accessory = button;
+        return this;
+    }
+    toJSON() {
+        if (!this.texts.length || this.texts.length > 3)
+            fail(code, 'section.components', 'needs 1-3 text displays.');
+        if (!this.accessory)
+            fail(code, 'section.accessory', 'is required: a thumbnail or a button.');
+        return {
+            ...this.base(ComponentType.Section),
+            components: this.texts.map((t) => (typeof t === 'string' ? new TextDisplayBuilder(t) : t).toJSON()),
+            accessory: this.accessory.toJSON()
+        };
+    }
+}
+export class ContainerBuilder extends ComponentBuilder {
+    children = [];
+    accent;
+    spoiler = false;
+    addComponents(...components) {
+        this.children.push(...components);
+        return this;
+    }
+    setAccentColor(color) {
+        this.accent = color === null ? undefined : resolveColor(color);
+        return this;
+    }
+    setSpoiler(spoiler = true) {
+        this.spoiler = spoiler;
+        return this;
+    }
+    toJSON() {
+        if (!this.children.length)
+            fail(code, 'container.components', 'needs at least one component.');
+        const allowed = [ComponentType.ActionRow, ComponentType.Section, ComponentType.TextDisplay, ComponentType.MediaGallery, ComponentType.Separator];
+        const components = this.children.map((child, i) => {
+            const json = resolveJSON(child);
+            if (!allowed.includes(json.type))
+                fail(code, `container.components[${i}]`, 'can be an action row, section, text display, media gallery or separator.');
+            return json;
+        });
+        const out = { ...this.base(ComponentType.Container), components, spoiler: this.spoiler };
+        if (this.accent !== undefined)
+            out.accent_color = range(code, 'container.accentColor', this.accent, 0, 0xffffff);
+        return out;
+    }
+}

package/dist/esm/builders/components/ModalBuilder.d.ts

@@ -0,0 +1,36 @@
+import type { APIComponent } from '../../types.js';
+import { ActionRowBuilder } from './ActionRowBuilder.js';
+import { ComponentBuilder } from './shared.js';
+export declare class TextInputBuilder extends ComponentBuilder {
+    private customId?;
+    private label?;
+    private style;
+    private placeholder?;
+    private minLength;
+    private maxLength;
+    private required;
+    private value?;
+    setCustomId(customId: string): this;
+    setLabel(label: string): this;
+    setStyle(style: number | 'short' | 'paragraph'): this;
+    setPlaceholder(placeholder: string): this;
+    setMinLength(length: number): this;
+    setMaxLength(length: number): this;
+    setRequired(required?: boolean): this;
+    setValue(value: string): this;
+    toJSON(): APIComponent;
+}
+export declare class ModalBuilder {
+    private customId?;
+    private title?;
+    private rows;
+    setCustomId(customId: string): this;
+    setTitle(title: string): this;
+    addComponents(...rows: (ActionRowBuilder | TextInputBuilder)[]): this;
+    setComponents(...rows: (ActionRowBuilder | TextInputBuilder)[]): this;
+    toJSON(): {
+        title: string;
+        custom_id: string;
+        components: APIComponent[];
+    };
+}

package/dist/esm/builders/components/ModalBuilder.js

@@ -0,0 +1,113 @@
+import { ComponentType, TextInputStyle } from '../../util/constants.js';
+import { fail, range, text } from '../validate.js';
+import { ActionRowBuilder } from './ActionRowBuilder.js';
+import { ComponentBuilder } from './shared.js';
+export class TextInputBuilder extends ComponentBuilder {
+    customId;
+    label;
+    style = TextInputStyle.Short;
+    placeholder;
+    minLength = 0;
+    maxLength = 4000;
+    required = true;
+    value;
+    setCustomId(customId) {
+        this.customId = customId;
+        return this;
+    }
+    setLabel(label) {
+        this.label = label;
+        return this;
+    }
+    setStyle(style) {
+        this.style = style === 'short' ? 1 : style === 'paragraph' ? 2 : style;
+        return this;
+    }
+    setPlaceholder(placeholder) {
+        this.placeholder = placeholder;
+        return this;
+    }
+    setMinLength(length) {
+        this.minLength = length;
+        return this;
+    }
+    setMaxLength(length) {
+        this.maxLength = length;
+        return this;
+    }
+    setRequired(required = true) {
+        this.required = required;
+        return this;
+    }
+    setValue(value) {
+        this.value = value;
+        return this;
+    }
+    toJSON() {
+        const code = 'INVALID_COMPONENT';
+        if (this.style !== 1 && this.style !== 2)
+            fail(code, 'textInput.style', 'must be Short (1) or Paragraph (2).');
+        range(code, 'textInput.minLength', this.minLength, 0, 4000);
+        range(code, 'textInput.maxLength', this.maxLength, 1, 4000);
+        if (this.minLength > this.maxLength)
+            fail(code, 'textInput', 'has minLength above maxLength.');
+        const out = this.base(ComponentType.TextInput);
+        out.custom_id = text(code, 'textInput.customId', this.customId, 100);
+        out.style = this.style;
+        out.label = text(code, 'textInput.label', this.label, 45);
+        const placeholder = text(code, 'textInput.placeholder', this.placeholder, 100, { optional: true });
+        if (placeholder !== undefined)
+            out.placeholder = placeholder;
+        out.min_length = this.minLength;
+        out.max_length = this.maxLength;
+        out.required = this.required;
+        const value = text(code, 'textInput.value', this.value, 4000, { optional: true });
+        if (value !== undefined) {
+            if ([...value].length > this.maxLength)
+                fail(code, 'textInput.value', 'is longer than maxLength.');
+            out.value = value;
+        }
+        return out;
+    }
+}
+export class ModalBuilder {
+    customId;
+    title;
+    rows = [];
+    setCustomId(customId) {
+        this.customId = customId;
+        return this;
+    }
+    setTitle(title) {
+        this.title = title;
+        return this;
+    }
+    addComponents(...rows) {
+        this.rows.push(...rows);
+        return this;
+    }
+    setComponents(...rows) {
+        this.rows = [...rows];
+        return this;
+    }
+    toJSON() {
+        const code = 'INVALID_COMPONENT';
+        if (!this.rows.length || this.rows.length > 5)
+            fail(code, 'modal.components', 'needs 1-5 rows, each with one text input.');
+        const seen = new Set();
+        const components = this.rows.map((row) => {
+            const wrapped = row instanceof ActionRowBuilder ? row : new ActionRowBuilder().addComponents(row);
+            const json = wrapped.toModalJSON();
+            const id = json.components[0].custom_id;
+            if (seen.has(id))
+                fail(code, 'modal.components', `custom id "${id}" is used twice.`);
+            seen.add(id);
+            return json;
+        });
+        return {
+            title: text(code, 'modal.title', this.title, 45),
+            custom_id: text(code, 'modal.customId', this.customId, 100),
+            components
+        };
+    }
+}

package/dist/esm/builders/components/SelectMenuBuilder.d.ts

@@ -0,0 +1,80 @@
+import type { APIComponent } from '../../types.js';
+import { ComponentBuilder, type EmojiInput } from './shared.js';
+export interface SelectOptionData {
+    label: string;
+    value: string;
+    description?: string;
+    emoji?: EmojiInput;
+    default?: boolean;
+}
+export declare class StringSelectMenuOptionBuilder {
+    data: Partial<SelectOptionData>;
+    constructor(data?: Partial<SelectOptionData>);
+    setLabel(label: string): this;
+    setValue(value: string): this;
+    setDescription(description: string): this;
+    setEmoji(emoji: EmojiInput): this;
+    setDefault(value?: boolean): this;
+    toJSON(path?: string): Record<string, unknown>;
+}
+declare abstract class SelectMenuBase extends ComponentBuilder {
+    protected customId?: string;
+    protected placeholder?: string;
+    protected min: number;
+    protected max: number;
+    protected disabled: boolean;
+    protected abstract readonly kind: number;
+    setCustomId(customId: string): this;
+    setPlaceholder(placeholder: string): this;
+    setMinValues(min: number): this;
+    setMaxValues(max: number): this;
+    setDisabled(disabled?: boolean): this;
+    protected finish(out: APIComponent, defaults: number): APIComponent;
+}
+export declare class StringSelectMenuBuilder extends SelectMenuBase {
+    protected readonly kind: 3;
+    private options;
+    addOptions(...options: (StringSelectMenuOptionBuilder | SelectOptionData)[]): this;
+    setOptions(...options: (StringSelectMenuOptionBuilder | SelectOptionData)[]): this;
+    toJSON(): APIComponent;
+}
+declare abstract class EntitySelectBuilder extends SelectMenuBase {
+    protected abstract readonly allowed: readonly string[];
+    protected defaults: {
+        id: string;
+        type: string;
+    }[];
+    protected addDefaults(...values: {
+        id: string;
+        type: string;
+    }[]): this;
+    protected build(): APIComponent;
+    toJSON(): APIComponent;
+}
+export declare class UserSelectMenuBuilder extends EntitySelectBuilder {
+    protected readonly kind: 5;
+    protected readonly allowed: string[];
+    setDefaultUsers(...ids: string[]): this;
+}
+export declare class RoleSelectMenuBuilder extends EntitySelectBuilder {
+    protected readonly kind: 6;
+    protected readonly allowed: string[];
+    setDefaultRoles(...ids: string[]): this;
+}
+export declare class MentionableSelectMenuBuilder extends EntitySelectBuilder {
+    protected readonly kind: 7;
+    protected readonly allowed: string[];
+    setDefaultValues(...values: {
+        id: string;
+        type: 'user' | 'role';
+    }[]): this;
+}
+export declare class ChannelSelectMenuBuilder extends EntitySelectBuilder {
+    protected readonly kind: 8;
+    protected readonly allowed: string[];
+    private types;
+    setDefaultChannels(...ids: string[]): this;
+    setChannelTypes(...types: (string | number)[]): this;
+    toJSON(): APIComponent;
+}
+export {};

package/dist/esm/builders/components/SelectMenuBuilder.js

@@ -0,0 +1,183 @@
+import { ComponentType } from '../../util/constants.js';
+import { fail, range, text } from '../validate.js';
+import { ComponentBuilder, emojiJSON } from './shared.js';
+export class StringSelectMenuOptionBuilder {
+    data;
+    constructor(data = {}) {
+        this.data = data;
+    }
+    setLabel(label) {
+        this.data.label = label;
+        return this;
+    }
+    setValue(value) {
+        this.data.value = value;
+        return this;
+    }
+    setDescription(description) {
+        this.data.description = description;
+        return this;
+    }
+    setEmoji(emoji) {
+        this.data.emoji = emoji;
+        return this;
+    }
+    setDefault(value = true) {
+        this.data.default = value;
+        return this;
+    }
+    toJSON(path = 'option') {
+        const code = 'INVALID_COMPONENT';
+        const out = {
+            label: text(code, `${path}.label`, this.data.label, 100),
+            value: text(code, `${path}.value`, this.data.value, 100)
+        };
+        const description = text(code, `${path}.description`, this.data.description, 100, { optional: true });
+        const emoji = emojiJSON(`${path}.emoji`, this.data.emoji);
+        if (description !== undefined)
+            out.description = description;
+        if (emoji)
+            out.emoji = emoji;
+        out.default = this.data.default ?? false;
+        return out;
+    }
+}
+class SelectMenuBase extends ComponentBuilder {
+    customId;
+    placeholder;
+    min = 1;
+    max = 1;
+    disabled = false;
+    setCustomId(customId) {
+        this.customId = customId;
+        return this;
+    }
+    setPlaceholder(placeholder) {
+        this.placeholder = placeholder;
+        return this;
+    }
+    setMinValues(min) {
+        this.min = min;
+        return this;
+    }
+    setMaxValues(max) {
+        this.max = max;
+        return this;
+    }
+    setDisabled(disabled = true) {
+        this.disabled = disabled;
+        return this;
+    }
+    finish(out, defaults) {
+        const code = 'INVALID_COMPONENT';
+        out.custom_id = text(code, 'select.customId', this.customId, 100);
+        const placeholder = text(code, 'select.placeholder', this.placeholder, 150, { optional: true });
+        if (placeholder !== undefined)
+            out.placeholder = placeholder;
+        range(code, 'select.minValues', this.min, 0, 25);
+        range(code, 'select.maxValues', this.max, 1, 25);
+        if (this.min > this.max)
+            fail(code, 'select', 'has minValues above maxValues.');
+        if (defaults > this.max)
+            fail(code, 'select', 'has more default values than maxValues allows.');
+        out.min_values = this.min;
+        out.max_values = this.max;
+        out.disabled = this.disabled;
+        return out;
+    }
+}
+export class StringSelectMenuBuilder extends SelectMenuBase {
+    kind = ComponentType.StringSelect;
+    options = [];
+    addOptions(...options) {
+        this.options.push(...options);
+        return this;
+    }
+    setOptions(...options) {
+        this.options = [...options];
+        return this;
+    }
+    toJSON() {
+        const code = 'INVALID_COMPONENT';
+        if (!this.options.length || this.options.length > 25)
+            fail(code, 'select.options', 'needs 1-25 options.');
+        if (this.max > this.options.length)
+            fail(code, 'select.maxValues', `can't be more than the number of options (${this.options.length}).`);
+        const seen = new Set();
+        const options = this.options.map((option, i) => {
+            const builder = option instanceof StringSelectMenuOptionBuilder ? option : new StringSelectMenuOptionBuilder(option);
+            const json = builder.toJSON(`select.options[${i}]`);
+            if (seen.has(json.value))
+                fail(code, `select.options[${i}].value`, `"${json.value}" is used twice; option values must be unique.`);
+            seen.add(json.value);
+            return json;
+        });
+        const out = this.base(this.kind);
+        out.options = options;
+        return this.finish(out, options.filter((o) => o.default).length);
+    }
+}
+class EntitySelectBuilder extends SelectMenuBase {
+    defaults = [];
+    addDefaults(...values) {
+        for (const value of values) {
+            if (!this.allowed.includes(value.type))
+                fail('INVALID_COMPONENT', 'select.defaultValues', `type must be ${this.allowed.join(' or ')}.`);
+        }
+        this.defaults.push(...values);
+        return this;
+    }
+    build() {
+        const out = this.base(this.kind);
+        if (this.defaults.length)
+            out.default_values = this.defaults;
+        return this.finish(out, this.defaults.length);
+    }
+    toJSON() {
+        return this.build();
+    }
+}
+export class UserSelectMenuBuilder extends EntitySelectBuilder {
+    kind = ComponentType.UserSelect;
+    allowed = ['user'];
+    setDefaultUsers(...ids) {
+        return this.addDefaults(...ids.map((id) => ({ id, type: 'user' })));
+    }
+}
+export class RoleSelectMenuBuilder extends EntitySelectBuilder {
+    kind = ComponentType.RoleSelect;
+    allowed = ['role'];
+    setDefaultRoles(...ids) {
+        return this.addDefaults(...ids.map((id) => ({ id, type: 'role' })));
+    }
+}
+export class MentionableSelectMenuBuilder extends EntitySelectBuilder {
+    kind = ComponentType.MentionableSelect;
+    allowed = ['user', 'role'];
+    setDefaultValues(...values) {
+        return this.addDefaults(...values);
+    }
+}
+const CHANNEL_TYPES = new Set(['text', 'dm', 'voice', 'group_dm', 'category', 'announcement', 'thread', 'stage', 'forum', 0, 1, 2, 3, 4, 5, 10, 11, 12, 13, 15]);
+export class ChannelSelectMenuBuilder extends EntitySelectBuilder {
+    kind = ComponentType.ChannelSelect;
+    allowed = ['channel'];
+    types = [];
+    setDefaultChannels(...ids) {
+        return this.addDefaults(...ids.map((id) => ({ id, type: 'channel' })));
+    }
+    setChannelTypes(...types) {
+        for (const type of types) {
+            if (!CHANNEL_TYPES.has(type))
+                fail('INVALID_COMPONENT', 'select.channelTypes', `"${type}" is not a channel type.`);
+        }
+        this.types = [...new Set(types)];
+        return this;
+    }
+    toJSON() {
+        const out = this.build();
+        if (this.types.length)
+            out.channel_types = this.types;
+        return out;
+    }
+}

package/dist/esm/builders/components/shared.d.ts

@@ -0,0 +1,16 @@
+import type { APIComponent } from '../../types.js';
+import { type Serializable } from '../validate.js';
+export type EmojiInput = string | {
+    id?: string;
+    name?: string;
+    animated?: boolean;
+};
+export type ComponentInput<T extends Serializable = Serializable> = T | APIComponent;
+export declare function emojiJSON(path: string, emoji: EmojiInput | undefined): Record<string, unknown> | undefined;
+export declare function jsonList(list: readonly ComponentInput[]): APIComponent[];
+export declare abstract class ComponentBuilder {
+    protected componentId?: number;
+    setId(id: number): this;
+    protected base(type: number): APIComponent;
+    abstract toJSON(): APIComponent;
+}

package/dist/esm/builders/components/shared.js

@@ -0,0 +1,26 @@
+import { fail, resolveJSON } from '../validate.js';
+export function emojiJSON(path, emoji) {
+    if (emoji === undefined)
+        return undefined;
+    if (typeof emoji === 'string') {
+        if (!emoji.trim())
+            return fail('INVALID_COMPONENT', path, 'must be an emoji.');
+        return { name: emoji.trim() };
+    }
+    if (!emoji.id && !emoji.name)
+        return fail('INVALID_COMPONENT', path, 'needs a name (Unicode emoji) or an id (custom emoji).');
+    return emoji.id ? { id: emoji.id, name: emoji.name ?? 'emoji', animated: emoji.animated ?? false } : { name: emoji.name };
+}
+export function jsonList(list) {
+    return list.map((item) => resolveJSON(item));
+}
+export class ComponentBuilder {
+    componentId;
+    setId(id) {
+        this.componentId = id;
+        return this;
+    }
+    base(type) {
+        return this.componentId === undefined ? { type } : { type, id: this.componentId };
+    }
+}