@minesa-org/mini-interaction 0.0.1

package/dist/commands/CommandBuilder.js

@@ -0,0 +1,687 @@
+import { ApplicationCommandOptionType, ApplicationCommandType, } from "discord-api-types/v10";
+/** Maximum number of options allowed on a slash command or subcommand. */
+const MAX_COMMAND_OPTIONS = 25;
+/** Maximum number of choices allowed on choice-enabled options. */
+const MAX_CHOICES = 25;
+/** Maximum length of command or option names enforced by Discord. */
+const MAX_NAME_LENGTH = 32;
+/** Maximum description length permitted for commands and options. */
+const MAX_DESCRIPTION_LENGTH = 100;
+/** Maximum length of string option values supported by Discord. */
+const MAX_STRING_LENGTH = 6000;
+/** Minimum length of string option values. */
+const MIN_STRING_LENGTH = 0;
+/** Valid command and option name pattern as defined by Discord's API. */
+const COMMAND_NAME_REGEX = /^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$/u;
+/**
+ * Ensures an option or command name satisfies Discord's requirements.
+ */
+function assertName(name, lowerCase = true) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("Option name must be a non-empty string");
+    }
+    if (name.length > MAX_NAME_LENGTH || !COMMAND_NAME_REGEX.test(name)) {
+        throw new RangeError(`Option name "${name}" must match ${COMMAND_NAME_REGEX.source} and be at most ${MAX_NAME_LENGTH} characters long`);
+    }
+    if (lowerCase && name !== name.toLowerCase()) {
+        throw new RangeError(`Command and option names must be lowercase. Received "${name}"`);
+    }
+}
+/** Validates that a description string meets Discord's length constraints. */
+function assertDescription(description) {
+    if (typeof description !== "string" || description.length === 0) {
+        throw new TypeError("Description must be a non-empty string");
+    }
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+        throw new RangeError(`Description must be between 1 and ${MAX_DESCRIPTION_LENGTH} characters long`);
+    }
+}
+/** Creates a deep copy of an option payload to avoid accidental mutation. */
+function cloneOption(option) {
+    return JSON.parse(JSON.stringify(option));
+}
+/** Supported integration types for Discord application commands. */
+export var IntegrationType;
+(function (IntegrationType) {
+    IntegrationType[IntegrationType["GuildInstall"] = 0] = "GuildInstall";
+    IntegrationType[IntegrationType["UserInstall"] = 1] = "UserInstall";
+})(IntegrationType || (IntegrationType = {}));
+/** Supported contexts where a command can be invoked. */
+export var CommandContext;
+(function (CommandContext) {
+    CommandContext[CommandContext["Guild"] = 0] = "Guild";
+    CommandContext[CommandContext["Bot"] = 1] = "Bot";
+    CommandContext[CommandContext["DM"] = 2] = "DM";
+})(CommandContext || (CommandContext = {}));
+/**
+ * Provides shared builder utilities for application command option definitions.
+ */
+class BaseOptionBuilder {
+    data;
+    /**
+     * Creates a new option builder wrapper around an underlying option payload.
+     */
+    constructor(data) {
+        this.data = data;
+    }
+    /**
+     * Sets the option name while validating Discord's requirements.
+     */
+    setName(name) {
+        assertName(name);
+        this.data.name = name;
+        return this;
+    }
+    /**
+     * Sets localized translations for the option name.
+     */
+    setNameLocalizations(localizations) {
+        this.data.name_localizations = localizations ?? null;
+        return this;
+    }
+    /**
+     * Sets the option description while validating Discord's length requirements.
+     */
+    setDescription(description) {
+        assertDescription(description);
+        this.data.description = description;
+        return this;
+    }
+    /**
+     * Sets localized translations for the option description.
+     */
+    setDescriptionLocalizations(localizations) {
+        this.data.description_localizations = localizations ?? null;
+        return this;
+    }
+    /**
+     * Produces a deep copy of the built option payload for safe reuse.
+     */
+    toJSON() {
+        return cloneOption(this.data);
+    }
+}
+/**
+ * Extends {@link BaseOptionBuilder} with helpers specific to basic command options.
+ */
+class BaseCommandOptionBuilder extends BaseOptionBuilder {
+    /**
+     * Marks the option as required within its parent context.
+     */
+    setRequired(required = true) {
+        this.data.required = required;
+        return this;
+    }
+}
+/** Builder for attachment command options. */
+class AttachmentOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Attachment,
+            name: "",
+            description: "",
+        });
+    }
+}
+/** Builder for user command options. */
+class UserOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.User,
+            name: "",
+            description: "",
+        });
+    }
+}
+/** Builder for role command options. */
+class RoleOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Role,
+            name: "",
+            description: "",
+        });
+    }
+}
+/** Builder for mentionable command options. */
+class MentionableOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Mentionable,
+            name: "",
+            description: "",
+        });
+    }
+}
+/** Builder for channel command options with channel type filtering support. */
+class ChannelOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Channel,
+            name: "",
+            description: "",
+        });
+    }
+    /**
+     * Limits selectable channels to the provided channel types.
+     */
+    addChannelTypes(...channelTypes) {
+        if (channelTypes.length === 0) {
+            delete this.data.channel_types;
+            return this;
+        }
+        this.data.channel_types = [
+            ...channelTypes,
+        ];
+        return this;
+    }
+}
+/** Builder for string command options, including choice and autocomplete support. */
+class StringOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.String,
+            name: "",
+            description: "",
+        });
+    }
+    /**
+     * Adds a single choice option for the string command option.
+     */
+    addChoice(name, value) {
+        return this.addChoices({ name, value });
+    }
+    /**
+     * Adds multiple choice entries for the string command option.
+     */
+    addChoices(...choices) {
+        if (choices.length === 0) {
+            return this;
+        }
+        if (this.data.autocomplete) {
+            throw new Error("Cannot set choices when autocomplete is enabled");
+        }
+        this.data.choices ??= [];
+        if (this.data.choices.length + choices.length > MAX_CHOICES) {
+            throw new RangeError(`A maximum of ${MAX_CHOICES} choices can be set for an option`);
+        }
+        for (const choice of choices) {
+            assertName(choice.name, false);
+            this.data.choices.push({ ...choice });
+        }
+        return this;
+    }
+    /**
+     * Replaces the existing choice set with the provided entries.
+     */
+    setChoices(...choices) {
+        this.data.choices = [];
+        return this.addChoices(...choices);
+    }
+    /**
+     * Enables or disables autocomplete for the string option.
+     */
+    setAutocomplete(autocomplete = true) {
+        if (autocomplete && this.data.choices?.length) {
+            throw new Error("Cannot enable autocomplete when choices are already set");
+        }
+        this.data.autocomplete = autocomplete;
+        if (autocomplete) {
+            this.data.choices = [];
+        }
+        return this;
+    }
+    /**
+     * Sets the minimum string length accepted for the option value.
+     */
+    setMinLength(minLength) {
+        if (minLength < MIN_STRING_LENGTH || minLength > MAX_STRING_LENGTH) {
+            throw new RangeError(`minLength must be between ${MIN_STRING_LENGTH} and ${MAX_STRING_LENGTH}`);
+        }
+        this.data.min_length = minLength;
+        return this;
+    }
+    /**
+     * Sets the maximum string length accepted for the option value.
+     */
+    setMaxLength(maxLength) {
+        if (maxLength < 1 || maxLength > MAX_STRING_LENGTH) {
+            throw new RangeError(`maxLength must be between 1 and ${MAX_STRING_LENGTH}`);
+        }
+        this.data.max_length = maxLength;
+        return this;
+    }
+}
+/** Builder for numeric command options with choice and range support. */
+class NumberOptionBuilder extends BaseCommandOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Number,
+            name: "",
+            description: "",
+        });
+    }
+    /**
+     * Adds a single numeric choice for the option.
+     */
+    addChoice(name, value) {
+        return this.addChoices({ name, value });
+    }
+    /**
+     * Adds multiple numeric choice entries for the option.
+     */
+    addChoices(...choices) {
+        if (choices.length === 0) {
+            return this;
+        }
+        if (this.data.autocomplete) {
+            throw new Error("Cannot set choices when autocomplete is enabled");
+        }
+        this.data.choices ??= [];
+        if (this.data.choices.length + choices.length > MAX_CHOICES) {
+            throw new RangeError(`A maximum of ${MAX_CHOICES} choices can be set for an option`);
+        }
+        for (const choice of choices) {
+            assertName(choice.name, false);
+            this.data.choices.push({ ...choice });
+        }
+        return this;
+    }
+    /**
+     * Replaces the current choice set with the provided entries.
+     */
+    setChoices(...choices) {
+        this.data.choices = [];
+        return this.addChoices(...choices);
+    }
+    /**
+     * Enables or disables autocomplete for the numeric option.
+     */
+    setAutocomplete(autocomplete = true) {
+        if (autocomplete && this.data.choices?.length) {
+            throw new Error("Cannot enable autocomplete when choices are already set");
+        }
+        this.data.autocomplete = autocomplete;
+        if (autocomplete) {
+            this.data.choices = [];
+        }
+        return this;
+    }
+    /**
+     * Sets the minimum numeric value allowed for the option.
+     */
+    setMinValue(minValue) {
+        this.data.min_value = minValue;
+        return this;
+    }
+    /**
+     * Sets the maximum numeric value allowed for the option.
+     */
+    setMaxValue(maxValue) {
+        this.data.max_value = maxValue;
+        return this;
+    }
+}
+/**
+ * Resolves the JSON payload for a builder, allowing callback overrides to return custom builders.
+ */
+function resolveBuilder(builder, callback) {
+    const result = callback?.(builder);
+    if (result && result !== builder) {
+        return result.toJSON();
+    }
+    return builder.toJSON();
+}
+/** Builder used to compose individual slash command subcommands. */
+class SubcommandBuilder extends BaseOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.Subcommand,
+            name: "",
+            description: "",
+            options: [],
+        });
+    }
+    /**
+     * Ensures the subcommand does not exceed Discord's option limit.
+     */
+    assertOptionLimit(additional = 1) {
+        const current = this.data.options?.length ?? 0;
+        if (current + additional > MAX_COMMAND_OPTIONS) {
+            throw new RangeError(`A subcommand can only contain up to ${MAX_COMMAND_OPTIONS} options`);
+        }
+    }
+    /**
+     * Adds a string option configured through the supplied callback.
+     */
+    addStringOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new StringOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds a number option configured through the supplied callback.
+     */
+    addNumberOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new NumberOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds an attachment option configured through the supplied callback.
+     */
+    addAttachmentOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new AttachmentOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds a user option configured through the supplied callback.
+     */
+    addUserOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new UserOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds a role option configured through the supplied callback.
+     */
+    addRoleOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new RoleOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds a mentionable option configured through the supplied callback.
+     */
+    addMentionableOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new MentionableOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Adds a channel option configured through the supplied callback.
+     */
+    addChannelOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new ChannelOptionBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Produces a serialisable representation of the subcommand configuration.
+     */
+    toJSON() {
+        return {
+            ...this.data,
+            options: this.data.options?.map((option) => cloneOption(option)) ?? [],
+        };
+    }
+}
+/** Builder used to compose groups of subcommands. */
+class SubcommandGroupBuilder extends BaseOptionBuilder {
+    constructor() {
+        super({
+            type: ApplicationCommandOptionType.SubcommandGroup,
+            name: "",
+            description: "",
+            options: [],
+        });
+    }
+    /**
+     * Ensures the group does not exceed Discord's subcommand limit.
+     */
+    assertSubcommandLimit(additional = 1) {
+        const current = this.data.options?.length ?? 0;
+        if (current + additional > MAX_COMMAND_OPTIONS) {
+            throw new RangeError(`A subcommand group can only contain up to ${MAX_COMMAND_OPTIONS} subcommands`);
+        }
+    }
+    /**
+     * Adds a subcommand configured through the supplied callback.
+     */
+    addSubcommand(callback) {
+        this.assertSubcommandLimit();
+        const option = resolveBuilder(new SubcommandBuilder(), callback);
+        this.data.options?.push(option);
+        return this;
+    }
+    /**
+     * Produces a serialisable representation of the subcommand group configuration.
+     */
+    toJSON() {
+        return {
+            ...this.data,
+            options: this.data.options?.map((option) => cloneOption(option)) ?? [],
+        };
+    }
+}
+/** Fluent builder for constructing Discord chat input command payloads. */
+export class CommandBuilder {
+    data = {
+        type: ApplicationCommandType.ChatInput,
+    };
+    /**
+     * Ensures the command does not exceed Discord's option limit.
+     */
+    assertOptionLimit(additional = 1) {
+        const current = this.data.options?.length ?? 0;
+        if (current + additional > MAX_COMMAND_OPTIONS) {
+            throw new RangeError(`A command can only contain up to ${MAX_COMMAND_OPTIONS} options`);
+        }
+    }
+    /**
+     * Sets the command name while validating Discord's requirements.
+     */
+    setName(name) {
+        assertName(name);
+        this.data.name = name;
+        return this;
+    }
+    /**
+     * Sets localized translations for the command name.
+     */
+    setNameLocalizations(localizations) {
+        this.data.name_localizations = localizations ?? null;
+        return this;
+    }
+    /**
+     * Sets the command description while enforcing Discord's length rules.
+     */
+    setDescription(description) {
+        assertDescription(description);
+        this.data.description = description;
+        return this;
+    }
+    /**
+     * Sets localized translations for the command description.
+     */
+    setDescriptionLocalizations(localizations) {
+        this.data.description_localizations = localizations ?? null;
+        return this;
+    }
+    /**
+     * Configures the default member permissions required to use the command.
+     */
+    setDefaultMemberPermissions(permissions) {
+        if (permissions === null) {
+            this.data.default_member_permissions = null;
+            return this;
+        }
+        if (typeof permissions === "bigint") {
+            this.data.default_member_permissions = permissions.toString();
+            return this;
+        }
+        if (typeof permissions === "number") {
+            this.data.default_member_permissions =
+                Math.floor(permissions).toString();
+            return this;
+        }
+        this.data.default_member_permissions = permissions;
+        return this;
+    }
+    /**
+     * Sets whether the command is available in direct messages.
+     */
+    setDMPermission(dmPermission) {
+        this.data.dm_permission = dmPermission;
+        return this;
+    }
+    /**
+     * Marks the command as not safe for work.
+     */
+    setNSFW(nsfw) {
+        this.data.nsfw = nsfw;
+        return this;
+    }
+    /**
+     * Limits the contexts in which the command can appear.
+     */
+    setContexts(contexts) {
+        this.data.contexts = contexts ? [...contexts] : null;
+        return this;
+    }
+    /**
+     * Specifies the integration types supported by the command.
+     */
+    setIntegrationTypes(integrationTypes) {
+        this.data.integration_types = [...integrationTypes];
+        return this;
+    }
+    /**
+     * Adds a subcommand to the command definition.
+     */
+    addSubcommand(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new SubcommandBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a subcommand group to the command definition.
+     */
+    addSubcommandGroup(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new SubcommandGroupBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a string option to the command definition.
+     */
+    addStringOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new StringOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a number option to the command definition.
+     */
+    addNumberOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new NumberOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds an attachment option to the command definition.
+     */
+    addAttachmentOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new AttachmentOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a user option to the command definition.
+     */
+    addUserOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new UserOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a role option to the command definition.
+     */
+    addRoleOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new RoleOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a mentionable option to the command definition.
+     */
+    addMentionableOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new MentionableOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Adds a channel option to the command definition.
+     */
+    addChannelOption(callback) {
+        this.assertOptionLimit();
+        const option = resolveBuilder(new ChannelOptionBuilder(), callback);
+        this.data.options ??= [];
+        this.data.options.push(option);
+        return this;
+    }
+    /**
+     * Produces the final REST payload for the configured command.
+     */
+    toJSON() {
+        const { name, description } = this.data;
+        if (!name) {
+            throw new Error("Command name has not been set");
+        }
+        if (!description) {
+            throw new Error("Command description has not been set");
+        }
+        const contexts = this.data.contexts;
+        const integrationTypes = this.data.integration_types;
+        return {
+            ...this.data,
+            name,
+            description,
+            contexts: contexts === null
+                ? null
+                : Array.isArray(contexts)
+                    ? [...contexts]
+                    : undefined,
+            integration_types: Array.isArray(integrationTypes)
+                ? [...integrationTypes]
+                : integrationTypes ?? undefined,
+            options: this.data.options?.map((option) => cloneOption(option)) ?? [],
+        };
+    }
+    /**
+     * Allows the builder to be coerced into its JSON payload automatically.
+     */
+    valueOf() {
+        return this.toJSON();
+    }
+    /**
+     * Formats the command as JSON when inspected in Node.js runtimes.
+     */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toJSON();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/** Entry point re-exporting MiniInteraction helpers, builders, and shared types. */
+export { MiniInteraction } from "./clients/MiniInteraction.js";
+export type { RoleConnectionMetadataField } from "./clients/MiniInteraction.js";
+export { CommandBuilder, CommandContext, IntegrationType, } from "./commands/CommandBuilder.js";
+export type { AttachmentOptionBuilder, ChannelOptionBuilder, MentionableOptionBuilder, NumberOptionBuilder, RoleOptionBuilder, StringOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, UserOptionBuilder, } from "./commands/CommandBuilder.js";
+export { CommandInteractionOptionResolver, createCommandInteraction, } from "./utils/CommandInteractionOptions.js";
+export type { CommandInteraction, MentionableOption, ResolvedUserOption, } from "./utils/CommandInteractionOptions.js";
+export type { MiniInteractionFetchHandler, MiniInteractionNodeHandler, MiniInteractionHandlerResult, MiniInteractionRequest, MiniInteractionOptions, } from "./clients/MiniInteraction.js";
+export type { MiniInteractionCommand, SlashCommandHandler, } from "./types/Commands.js";
+export type { MiniInteractionComponent, MiniInteractionComponentHandler, } from "./clients/MiniInteraction.js";
+export { RoleConnectionMetadataTypes } from "./types/RoleConnectionMetadataTypes.js";
+export { ChannelType } from "./types/ChannelType.js";
+export { InteractionFollowUpFlags, InteractionReplyFlags, } from "./types/InteractionFlags.js";
+export { ButtonStyle } from "./types/ButtonStyle.js";
+export type { MiniComponentActionRow, MiniComponentMessageActionRow, } from "./types/ComponentTypes.js";
+export * from "./builders/index.js";