baff.js 0.0.0-stage → 0.1.0

package/dist/cjs/util/formatters.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hideLinkEmbed = exports.hyperlink = exports.subtext = exports.heading = exports.blockQuote = exports.quote = exports.codeBlock = exports.inlineCode = exports.spoiler = exports.strikethrough = exports.underline = exports.italic = exports.bold = exports.formatEmoji = exports.hereMention = exports.everyoneMention = exports.channelMention = exports.roleMention = exports.userMention = void 0;
+exports.escapeMarkdown = escapeMarkdown;
+const userMention = (id) => `<@${id}>`;
+exports.userMention = userMention;
+const roleMention = (id) => `<@&${id}>`;
+exports.roleMention = roleMention;
+const channelMention = (id) => `<#${id}>`;
+exports.channelMention = channelMention;
+exports.everyoneMention = '@everyone';
+exports.hereMention = '@here';
+const formatEmoji = (id, name, animated = false) => `<${animated ? 'a' : ''}:${name}:${id}>`;
+exports.formatEmoji = formatEmoji;
+const bold = (text) => `**${text}**`;
+exports.bold = bold;
+const italic = (text) => `*${text}*`;
+exports.italic = italic;
+const underline = (text) => `__${text}__`;
+exports.underline = underline;
+const strikethrough = (text) => `~~${text}~~`;
+exports.strikethrough = strikethrough;
+const spoiler = (text) => `||${text}||`;
+exports.spoiler = spoiler;
+const inlineCode = (text) => `\`${text}\``;
+exports.inlineCode = inlineCode;
+const codeBlock = (content, language = '') => `\`\`\`${language}\n${content}\n\`\`\``;
+exports.codeBlock = codeBlock;
+const quote = (text) => `> ${text}`;
+exports.quote = quote;
+const blockQuote = (text) => `>>> ${text}`;
+exports.blockQuote = blockQuote;
+const heading = (text, level = 1) => `${'#'.repeat(level)} ${text}`;
+exports.heading = heading;
+const subtext = (text) => `-# ${text}`;
+exports.subtext = subtext;
+const hyperlink = (text, url) => `[${text}](${url})`;
+exports.hyperlink = hyperlink;
+const hideLinkEmbed = (url) => `<${url}>`;
+exports.hideLinkEmbed = hideLinkEmbed;
+function escapeMarkdown(text, options = {}) {
+    const on = (key) => options[key] !== false;
+    let chars = '\\';
+    if (on('italic') || on('bold'))
+        chars += '*';
+    if (on('italic') || on('underline'))
+        chars += '_';
+    if (on('strikethrough'))
+        chars += '~';
+    if (on('inlineCode') || on('codeBlock'))
+        chars += '`';
+    if (on('spoiler'))
+        chars += '|';
+    return text.replace(new RegExp(`[${chars.replace(/[\]\\^-]/g, '\\$&')}]`, 'g'), '\\$&');
+}

package/dist/esm/builders/EmbedBuilder.d.ts

@@ -0,0 +1,51 @@
+import type { APIEmbed } from '../types.js';
+export declare const EmbedLimits: {
+    readonly embeds: 10;
+    readonly fields: 25;
+    readonly title: 256;
+    readonly description: 4096;
+    readonly fieldName: 256;
+    readonly fieldValue: 1024;
+    readonly footer: 2048;
+    readonly author: 256;
+    readonly total: 6000;
+};
+export type ColorResolvable = number | `#${string}` | readonly [number, number, number];
+export declare function resolveColor(color: ColorResolvable): number;
+export declare class EmbedBuilder {
+    readonly data: APIEmbed;
+    constructor(data?: APIEmbed);
+    setTitle(title: string | null): this;
+    setDescription(description: string | null): this;
+    setURL(value: string | null): this;
+    setColor(color: ColorResolvable | null): this;
+    setTimestamp(timestamp?: Date | number | string | null): this;
+    setAuthor(author: {
+        name: string;
+        url?: string;
+        iconURL?: string;
+    } | null): this;
+    setFooter(footer: {
+        text: string;
+        iconURL?: string;
+    } | null): this;
+    setThumbnail(imageURL: string | null): this;
+    setImage(imageURL: string | null): this;
+    addFields(...fields: {
+        name: string;
+        value: string;
+        inline?: boolean;
+    }[]): this;
+    setFields(...fields: {
+        name: string;
+        value: string;
+        inline?: boolean;
+    }[]): this;
+    spliceFields(index: number, deleteCount: number, ...fields: {
+        name: string;
+        value: string;
+        inline?: boolean;
+    }[]): this;
+    get length(): number;
+    toJSON(): APIEmbed;
+}

package/dist/esm/builders/EmbedBuilder.js

@@ -0,0 +1,145 @@
+import { BaffError } from '../errors/BaffError.js';
+import { fail, range, text, url } from './validate.js';
+export const EmbedLimits = {
+    embeds: 10,
+    fields: 25,
+    title: 256,
+    description: 4096,
+    fieldName: 256,
+    fieldValue: 1024,
+    footer: 2048,
+    author: 256,
+    total: 6000
+};
+export function resolveColor(color) {
+    if (typeof color === 'number')
+        return range('INVALID_EMBED', 'color', color, 0, 0xffffff);
+    if (typeof color === 'string') {
+        if (!/^#[0-9a-f]{6}$/i.test(color))
+            return fail('INVALID_EMBED', 'color', 'must be #rrggbb.');
+        return parseInt(color.slice(1), 16);
+    }
+    const [r, g, b] = color;
+    return (range('INVALID_EMBED', 'color', r, 0, 255) << 16) | (range('INVALID_EMBED', 'color', g, 0, 255) << 8) | range('INVALID_EMBED', 'color', b, 0, 255);
+}
+export class EmbedBuilder {
+    data;
+    constructor(data = {}) {
+        this.data = { ...data, fields: data.fields ? data.fields.map((f) => ({ ...f })) : undefined };
+    }
+    setTitle(title) {
+        this.data.title = title ?? undefined;
+        return this;
+    }
+    setDescription(description) {
+        this.data.description = description ?? undefined;
+        return this;
+    }
+    setURL(value) {
+        this.data.url = value ?? undefined;
+        return this;
+    }
+    setColor(color) {
+        this.data.color = color === null ? undefined : resolveColor(color);
+        return this;
+    }
+    setTimestamp(timestamp = new Date()) {
+        if (timestamp === null)
+            this.data.timestamp = undefined;
+        else {
+            const date = new Date(timestamp);
+            if (Number.isNaN(date.getTime()))
+                throw new BaffError('INVALID_EMBED', 'timestamp is not a valid date.');
+            this.data.timestamp = date.toISOString();
+        }
+        return this;
+    }
+    setAuthor(author) {
+        this.data.author = author ? { name: author.name, url: author.url, icon_url: author.iconURL } : undefined;
+        return this;
+    }
+    setFooter(footer) {
+        this.data.footer = footer ? { text: footer.text, icon_url: footer.iconURL } : undefined;
+        return this;
+    }
+    setThumbnail(imageURL) {
+        this.data.thumbnail = imageURL ? { url: imageURL } : undefined;
+        return this;
+    }
+    setImage(imageURL) {
+        this.data.image = imageURL ? { url: imageURL } : undefined;
+        return this;
+    }
+    addFields(...fields) {
+        this.data.fields = [...(this.data.fields ?? []), ...fields];
+        return this;
+    }
+    setFields(...fields) {
+        this.data.fields = [...fields];
+        return this;
+    }
+    spliceFields(index, deleteCount, ...fields) {
+        const next = [...(this.data.fields ?? [])];
+        next.splice(index, deleteCount, ...fields);
+        this.data.fields = next;
+        return this;
+    }
+    get length() {
+        const d = this.data;
+        const size = (s) => [...(s ?? '')].length;
+        return size(d.title) + size(d.description) + size(d.footer?.text) + size(d.author?.name) + (d.fields ?? []).reduce((sum, f) => sum + size(f.name) + size(f.value), 0);
+    }
+    toJSON() {
+        const d = this.data;
+        const code = 'INVALID_EMBED';
+        const out = {};
+        const title = text(code, 'title', d.title, EmbedLimits.title, { optional: true });
+        const description = text(code, 'description', d.description, EmbedLimits.description, { optional: true });
+        if (title !== undefined)
+            out.title = title;
+        if (description !== undefined)
+            out.description = description;
+        const link = url(code, 'url', d.url);
+        if (link)
+            out.url = link;
+        if (d.color !== undefined)
+            out.color = range(code, 'color', d.color, 0, 0xffffff);
+        if (d.timestamp)
+            out.timestamp = d.timestamp;
+        if (d.footer) {
+            out.footer = { text: text(code, 'footer.text', d.footer.text, EmbedLimits.footer) };
+            const icon = url(code, 'footer.iconURL', d.footer.icon_url);
+            if (icon)
+                out.footer.icon_url = icon;
+        }
+        if (d.author) {
+            out.author = { name: text(code, 'author.name', d.author.name, EmbedLimits.author) };
+            const authorUrl = url(code, 'author.url', d.author.url);
+            const icon = url(code, 'author.iconURL', d.author.icon_url);
+            if (authorUrl)
+                out.author.url = authorUrl;
+            if (icon)
+                out.author.icon_url = icon;
+        }
+        for (const key of ['image', 'thumbnail']) {
+            const media = d[key];
+            if (media)
+                out[key] = { url: url(code, key, media.url, false) };
+        }
+        if (d.fields?.length) {
+            if (d.fields.length > EmbedLimits.fields)
+                fail(code, 'fields', `can have up to ${EmbedLimits.fields} entries.`);
+            out.fields = d.fields.map((f, i) => ({
+                name: text(code, `fields[${i}].name`, f.name, EmbedLimits.fieldName),
+                value: text(code, `fields[${i}].value`, f.value, EmbedLimits.fieldValue),
+                inline: f.inline ?? false
+            }));
+        }
+        if (!Object.keys(out).filter((k) => k !== 'color' && k !== 'timestamp' && k !== 'url').length) {
+            fail(code, 'embed', 'is empty: give it a title, description, fields, image, thumbnail, author or footer.');
+        }
+        if (this.length > EmbedLimits.total)
+            fail(code, 'embed', `has ${this.length} characters; the limit is ${EmbedLimits.total} across all of a message's embeds.`);
+        return out;
+    }
+}

package/dist/esm/builders/SlashCommandBuilder.d.ts

@@ -0,0 +1,69 @@
+import type { APICommand, APICommandOption } from '../types.js';
+declare abstract class Named {
+    protected name?: string;
+    protected description?: string;
+    setName(name: string): this;
+    setDescription(description: string): this;
+    protected header(path: string): {
+        name: string;
+        description: string;
+    };
+}
+export declare abstract class OptionBuilder extends Named {
+    protected required: boolean;
+    abstract readonly type: string;
+    setRequired(required?: boolean): this;
+    toJSON(path?: string): APICommandOption;
+}
+export declare class StringOption extends OptionBuilder {
+    readonly type = "string";
+}
+export declare class IntegerOption extends OptionBuilder {
+    readonly type = "integer";
+}
+export declare class NumberOption extends OptionBuilder {
+    readonly type = "number";
+}
+export declare class BooleanOption extends OptionBuilder {
+    readonly type = "boolean";
+}
+export declare class UserOption extends OptionBuilder {
+    readonly type = "user";
+}
+export declare class ChannelOption extends OptionBuilder {
+    readonly type = "channel";
+}
+export declare class RoleOption extends OptionBuilder {
+    readonly type = "role";
+}
+type OptionInput<T> = T | ((option: T) => T);
+declare class OptionHolder extends Named {
+    protected plain: OptionBuilder[];
+    addStringOption(option: OptionInput<StringOption>): this;
+    addIntegerOption(option: OptionInput<IntegerOption>): this;
+    addNumberOption(option: OptionInput<NumberOption>): this;
+    addBooleanOption(option: OptionInput<BooleanOption>): this;
+    addUserOption(option: OptionInput<UserOption>): this;
+    addChannelOption(option: OptionInput<ChannelOption>): this;
+    addRoleOption(option: OptionInput<RoleOption>): this;
+}
+export declare class SubcommandBuilder extends OptionHolder {
+    toJSON(path?: string): APICommandOption;
+}
+export declare class SubcommandGroupBuilder extends Named {
+    private subcommands;
+    addSubcommand(sub: OptionInput<SubcommandBuilder>): this;
+    toJSON(path?: string): APICommandOption;
+}
+export declare class SlashCommandBuilder extends OptionHolder {
+    private nested;
+    addSubcommand(sub: OptionInput<SubcommandBuilder>): this;
+    addSubcommandGroup(group: OptionInput<SubcommandGroupBuilder>): this;
+    toJSON(): APICommand;
+}
+export declare class PrefixCommandBuilder extends Named {
+    private prefix?;
+    setPrefix(prefix: string): this;
+    toJSON(): APICommand;
+}
+export {};

package/dist/esm/builders/SlashCommandBuilder.js

@@ -0,0 +1,170 @@
+import { fail, text } from './validate.js';
+const code = 'INVALID_COMMAND';
+const NAME = /^[a-z0-9_-]{1,32}$/;
+const MAX_OPTIONS = 25;
+function checkName(path, name) {
+    if (typeof name !== 'string' || !NAME.test(name))
+        return fail(code, `${path}.name`, 'must be 1-32 lowercase letters, numbers, - or _.');
+    return name;
+}
+class Named {
+    name;
+    description;
+    setName(name) {
+        this.name = name;
+        return this;
+    }
+    setDescription(description) {
+        this.description = description;
+        return this;
+    }
+    header(path) {
+        return { name: checkName(path, this.name), description: text(code, `${path}.description`, this.description, 100) };
+    }
+}
+export class OptionBuilder extends Named {
+    required = false;
+    setRequired(required = true) {
+        this.required = required;
+        return this;
+    }
+    toJSON(path = 'option') {
+        return { ...this.header(path), type: this.type, required: this.required };
+    }
+}
+export class StringOption extends OptionBuilder {
+    type = 'string';
+}
+export class IntegerOption extends OptionBuilder {
+    type = 'integer';
+}
+export class NumberOption extends OptionBuilder {
+    type = 'number';
+}
+export class BooleanOption extends OptionBuilder {
+    type = 'boolean';
+}
+export class UserOption extends OptionBuilder {
+    type = 'user';
+}
+export class ChannelOption extends OptionBuilder {
+    type = 'channel';
+}
+export class RoleOption extends OptionBuilder {
+    type = 'role';
+}
+function build(input, make) {
+    return typeof input === 'function' ? input(make()) : input;
+}
+function checkPlain(path, options) {
+    if (options.length > MAX_OPTIONS)
+        fail(code, path, `can have up to ${MAX_OPTIONS} options.`);
+    const names = new Set();
+    let optionalSeen = false;
+    return options.map((option, i) => {
+        const json = option.toJSON(`${path}.options[${i}]`);
+        if (names.has(json.name))
+            fail(code, `${path}.options[${i}]`, `name "${json.name}" is used twice.`);
+        names.add(json.name);
+        if (json.required && optionalSeen)
+            fail(code, `${path}.options[${i}]`, `is required, so it must come before the optional options.`);
+        optionalSeen ||= !json.required;
+        return json;
+    });
+}
+class OptionHolder extends Named {
+    plain = [];
+    addStringOption(option) {
+        this.plain.push(build(option, () => new StringOption()));
+        return this;
+    }
+    addIntegerOption(option) {
+        this.plain.push(build(option, () => new IntegerOption()));
+        return this;
+    }
+    addNumberOption(option) {
+        this.plain.push(build(option, () => new NumberOption()));
+        return this;
+    }
+    addBooleanOption(option) {
+        this.plain.push(build(option, () => new BooleanOption()));
+        return this;
+    }
+    addUserOption(option) {
+        this.plain.push(build(option, () => new UserOption()));
+        return this;
+    }
+    addChannelOption(option) {
+        this.plain.push(build(option, () => new ChannelOption()));
+        return this;
+    }
+    addRoleOption(option) {
+        this.plain.push(build(option, () => new RoleOption()));
+        return this;
+    }
+}
+export class SubcommandBuilder extends OptionHolder {
+    toJSON(path = 'subcommand') {
+        const options = checkPlain(path, this.plain);
+        return { ...this.header(path), type: 'subcommand', options };
+    }
+}
+export class SubcommandGroupBuilder extends Named {
+    subcommands = [];
+    addSubcommand(sub) {
+        this.subcommands.push(build(sub, () => new SubcommandBuilder()));
+        return this;
+    }
+    toJSON(path = 'group') {
+        if (!this.subcommands.length)
+            fail(code, path, 'needs at least one subcommand.');
+        return { ...this.header(path), type: 'subcommand_group', options: checkNested(path, this.subcommands) };
+    }
+}
+function checkNested(path, list) {
+    if (list.length > MAX_OPTIONS)
+        fail(code, path, `can have up to ${MAX_OPTIONS} options.`);
+    const names = new Set();
+    return list.map((item, i) => {
+        const json = item.toJSON(`${path}.options[${i}]`);
+        if (names.has(json.name))
+            fail(code, `${path}.options[${i}]`, `name "${json.name}" is used twice.`);
+        names.add(json.name);
+        return json;
+    });
+}
+export class SlashCommandBuilder extends OptionHolder {
+    nested = [];
+    addSubcommand(sub) {
+        this.nested.push(build(sub, () => new SubcommandBuilder()));
+        return this;
+    }
+    addSubcommandGroup(group) {
+        this.nested.push(build(group, () => new SubcommandGroupBuilder()));
+        return this;
+    }
+    toJSON() {
+        const path = `command "${this.name ?? ''}"`;
+        const header = this.header('command');
+        if (this.nested.length && this.plain.length)
+            fail(code, path, 'has both subcommands and plain options: use one or the other.');
+        const options = this.nested.length ? checkNested(path, this.nested) : checkPlain(path, this.plain);
+        return { ...header, kind: 'slash', options };
+    }
+}
+export class PrefixCommandBuilder extends Named {
+    prefix;
+    setPrefix(prefix) {
+        this.prefix = prefix;
+        return this;
+    }
+    toJSON() {
+        const prefix = this.prefix;
+        if (!prefix || [...prefix].length > 5 || /\s/.test(prefix))
+            fail(code, 'command.prefix', 'must be 1-5 characters with no spaces.');
+        if (!this.name || [...this.name].length > 32 || /\s/.test(this.name))
+            fail(code, 'command.name', 'must be 1-32 characters with no spaces.');
+        const description = text(code, 'command.description', this.description, 100, { optional: true }) ?? '';
+        return { kind: 'prefix', prefix, name: this.name, description };
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { APIComponent } from '../../types.js';
+import { type Serializable } from '../validate.js';
+import { ComponentBuilder } from './shared.js';
+export declare class ActionRowBuilder<T extends Serializable = Serializable> extends ComponentBuilder {
+    components: (T | APIComponent)[];
+    constructor(data?: {
+        components?: (T | APIComponent)[];
+    });
+    addComponents(...components: (T | APIComponent)[]): this;
+    setComponents(...components: (T | APIComponent)[]): this;
+    toJSON(): APIComponent;
+    toModalJSON(): APIComponent;
+    private render;
+}

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

@@ -0,0 +1,41 @@
+import { ComponentType } from '../../util/constants.js';
+import { fail, resolveJSON } from '../validate.js';
+import { ComponentBuilder } from './shared.js';
+export class ActionRowBuilder extends ComponentBuilder {
+    components;
+    constructor(data = {}) {
+        super();
+        this.components = [...(data.components ?? [])];
+    }
+    addComponents(...components) {
+        this.components.push(...components);
+        return this;
+    }
+    setComponents(...components) {
+        this.components = [...components];
+        return this;
+    }
+    toJSON() {
+        return this.render(false);
+    }
+    toModalJSON() {
+        return this.render(true);
+    }
+    render(modal) {
+        const children = this.components.map((c) => resolveJSON(c));
+        const kinds = children.map((c) => c.type);
+        const code = 'INVALID_COMPONENT';
+        if (modal) {
+            if (kinds.length !== 1 || kinds[0] !== ComponentType.TextInput)
+                fail(code, 'modal row', 'needs exactly one text input.');
+        }
+        else if (kinds[0] === ComponentType.Button) {
+            if (kinds.length > 5 || kinds.some((k) => k !== ComponentType.Button))
+                fail(code, 'action row', 'can hold up to 5 buttons, all buttons.');
+        }
+        else if (kinds.length !== 1 || kinds[0] === ComponentType.TextInput || kinds[0] === undefined) {
+            fail(code, 'action row', 'needs 1-5 buttons, or exactly one select menu.');
+        }
+        return { ...this.base(ComponentType.ActionRow), components: children };
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { APIComponent } from '../../types.js';
+import { ComponentBuilder, type EmojiInput } from './shared.js';
+type StyleName = 'primary' | 'secondary' | 'success' | 'danger' | 'link';
+export declare class ButtonBuilder extends ComponentBuilder {
+    private customId?;
+    private label?;
+    private style?;
+    private emoji?;
+    private link?;
+    private disabled;
+    setCustomId(customId: string): this;
+    setLabel(label: string): this;
+    setStyle(style: number | StyleName): this;
+    setEmoji(emoji: EmojiInput): this;
+    setURL(link: string): this;
+    setDisabled(disabled?: boolean): this;
+    toJSON(): APIComponent;
+}
+export {};

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

@@ -0,0 +1,65 @@
+import { ButtonStyle, ComponentType } from '../../util/constants.js';
+import { fail, text, url } from '../validate.js';
+import { ComponentBuilder, emojiJSON } from './shared.js';
+const STYLE_NUMBERS = { primary: 1, secondary: 2, success: 3, danger: 4, link: 5 };
+export class ButtonBuilder extends ComponentBuilder {
+    customId;
+    label;
+    style;
+    emoji;
+    link;
+    disabled = false;
+    setCustomId(customId) {
+        this.customId = customId;
+        return this;
+    }
+    setLabel(label) {
+        this.label = label;
+        return this;
+    }
+    setStyle(style) {
+        const value = typeof style === 'string' ? STYLE_NUMBERS[style] : style;
+        if (!Number.isInteger(value) || value < 1 || value > 5)
+            fail('INVALID_COMPONENT', 'button.style', 'must be 1 (primary), 2 (secondary), 3 (success), 4 (danger) or 5 (link).');
+        this.style = value;
+        return this;
+    }
+    setEmoji(emoji) {
+        this.emoji = emoji;
+        return this;
+    }
+    setURL(link) {
+        this.link = link;
+        return this;
+    }
+    setDisabled(disabled = true) {
+        this.disabled = disabled;
+        return this;
+    }
+    toJSON() {
+        const code = 'INVALID_COMPONENT';
+        const style = this.style ?? (this.link ? ButtonStyle.Link : ButtonStyle.Primary);
+        const out = this.base(ComponentType.Button);
+        out.style = style;
+        const label = text(code, 'button.label', this.label, 80, { optional: true });
+        const emoji = emojiJSON('button.emoji', this.emoji);
+        if (label !== undefined)
+            out.label = label;
+        if (emoji)
+            out.emoji = emoji;
+        if (label === undefined && !emoji)
+            fail(code, 'button', 'needs a label (1-80 characters) or an emoji.');
+        if (style === ButtonStyle.Link) {
+            if (this.customId !== undefined)
+                fail(code, 'button', 'is a link button: it has a url and no custom id.');
+            out.url = url(code, 'button.url', this.link, false);
+        }
+        else {
+            if (this.link !== undefined)
+                fail(code, 'button', 'has a url, so its style must be Link.');
+            out.custom_id = text(code, 'button.customId', this.customId, 100);
+        }
+        out.disabled = this.disabled;
+        return out;
+    }
+}