@minesa-org/mini-interaction 0.3.13 → 0.4.0

package/README.md

@@ -1,3 +1,34 @@
 # Mini Interaction
 
-Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).
+Discord interactions framework for HTTP/webhook bots with direct Discord API v10 payload compatibility.
+
+## Quick start (slash command)
+```ts
+import { LegacyMiniInteractionAdapter } from '@minesa-org/mini-interaction';
+
+const adapter = new LegacyMiniInteractionAdapter({ publicKey, applicationId, token });
+adapter.router.onCommand('ping', async (_interaction, ctx) => ctx.reply({ content: 'pong' }));
+```
+
+## Modal example (label + upload + select)
+```ts
+import {
+  ModalBuilder,
+  LabelBuilder,
+  TextInputBuilder,
+  FileUploadBuilder,
+  ModalRoleSelectMenuBuilder,
+} from '@minesa-org/mini-interaction';
+```
+
+## Radio example
+```ts
+import { RadioBuilder } from '@minesa-org/mini-interaction';
+
+const radio = new RadioBuilder()
+  .setCustomId('flavor')
+  .addOptions({ label: 'Vanilla', value: 'v', default: true }, { label: 'Chocolate', value: 'c' });
+```
+
+## Error handling
+Catch `ValidationError` from builders to surface actionable diagnostics.

package/dist/builders/FileUploadBuilder.d.ts

@@ -1,37 +1,17 @@
-import { type APIFileUploadComponent } from "discord-api-types/v10";
-import type { JSONEncodable } from "./shared.js";
-/** Shape describing initial file upload data accepted by the builder. */
+import { type APIFileUploadComponent } from 'discord-api-types/v10';
+import { type JSONEncodable } from './shared.js';
 export type FileUploadBuilderData = {
     customId?: string;
     minValues?: number;
     maxValues?: number;
     required?: boolean;
 };
-/** Builder for Discord file upload components used in modals. */
 export declare class FileUploadBuilder implements JSONEncodable<APIFileUploadComponent> {
-    private data;
-    /**
-     * Creates a new file upload builder with optional seed data.
-     */
+    private readonly data;
     constructor(data?: FileUploadBuilderData);
-    /**
-     * Sets the custom identifier for this file upload component.
-     */
     setCustomId(customId: string): this;
-    /**
-     * Sets the minimum number of files that must be uploaded (min 0, max 10).
-     */
     setMinValues(minValues: number): this;
-    /**
-     * Sets the maximum number of files that can be uploaded (max 10).
-     */
     setMaxValues(maxValues: number): this;
-    /**
-     * Sets whether files are required before submitting the modal.
-     */
     setRequired(required: boolean): this;
-    /**
-     * Serialises the builder into an API compatible file upload component payload.
-     */
     toJSON(): APIFileUploadComponent;
 }

package/dist/builders/FileUploadBuilder.js

@@ -1,59 +1,22 @@
-import { ComponentType, } from "discord-api-types/v10";
-/** Builder for Discord file upload components used in modals. */
+import { ComponentType } from 'discord-api-types/v10';
+import { assertDefined, assertRange, assertStringLength, ValidationError } from '../types/validation.js';
 export class FileUploadBuilder {
     data;
-    /**
-     * Creates a new file upload builder with optional seed data.
-     */
-    constructor(data = {}) {
-        this.data = {
-            customId: data.customId,
-            minValues: data.minValues,
-            maxValues: data.maxValues,
-            required: data.required,
-        };
-    }
-    /**
-     * Sets the custom identifier for this file upload component.
-     */
-    setCustomId(customId) {
-        this.data.customId = customId;
-        return this;
-    }
-    /**
-     * Sets the minimum number of files that must be uploaded (min 0, max 10).
-     */
-    setMinValues(minValues) {
-        this.data.minValues = minValues;
-        return this;
-    }
-    /**
-     * Sets the maximum number of files that can be uploaded (max 10).
-     */
-    setMaxValues(maxValues) {
-        this.data.maxValues = maxValues;
-        return this;
-    }
-    /**
-     * Sets whether files are required before submitting the modal.
-     */
-    setRequired(required) {
-        this.data.required = required;
-        return this;
-    }
-    /**
-     * Serialises the builder into an API compatible file upload component payload.
-     */
+    constructor(data = {}) { this.data = { ...data }; }
+    setCustomId(customId) { this.data.customId = customId; return this; }
+    setMinValues(minValues) { this.data.minValues = minValues; return this; }
+    setMaxValues(maxValues) { this.data.maxValues = maxValues; return this; }
+    setRequired(required) { this.data.required = required; return this; }
     toJSON() {
-        if (!this.data.customId) {
-            throw new Error("[FileUploadBuilder] custom_id is required.");
+        const customId = assertDefined('FileUploadBuilder', 'custom_id', this.data.customId);
+        assertStringLength('FileUploadBuilder', 'custom_id', customId, 1, 100);
+        if (this.data.minValues !== undefined)
+            assertRange('FileUploadBuilder', 'min_values', this.data.minValues, 0, 10);
+        if (this.data.maxValues !== undefined)
+            assertRange('FileUploadBuilder', 'max_values', this.data.maxValues, 1, 10);
+        if (this.data.minValues !== undefined && this.data.maxValues !== undefined && this.data.minValues > this.data.maxValues) {
+            throw new ValidationError('FileUploadBuilder', 'min_values', 'cannot be greater than max_values');
         }
-        return {
-            type: ComponentType.FileUpload,
-            custom_id: this.data.customId,
-            min_values: this.data.minValues,
-            max_values: this.data.maxValues,
-            required: this.data.required,
-        };
+        return { type: ComponentType.FileUpload, custom_id: customId, min_values: this.data.minValues, max_values: this.data.maxValues, required: this.data.required };
     }
 }

package/dist/builders/LabelBuilder.d.ts

@@ -1,35 +1,16 @@
-import { type APILabelComponent, type APIComponentInLabel } from "discord-api-types/v10";
-import type { JSONEncodable } from "./shared.js";
-/** Values accepted when composing label components. */
+import { type APIComponentInLabel, type APILabelComponent } from 'discord-api-types/v10';
+import { type JSONEncodable } from './shared.js';
 export type LabelComponentLike = JSONEncodable<APIComponentInLabel> | APIComponentInLabel;
-/** Shape describing initial label data accepted by the builder. */
 export type LabelBuilderData = {
     label?: string;
     description?: string;
     component?: LabelComponentLike;
 };
-/** Builder for Discord label components used in modals. */
 export declare class LabelBuilder implements JSONEncodable<APILabelComponent> {
-    private data;
-    /**
-     * Creates a new label builder with optional seed data.
-     */
+    private readonly data;
     constructor(data?: LabelBuilderData);
-    /**
-     * Sets the label text (max 45 characters).
-     */
     setLabel(label: string): this;
-    /**
-     * Sets the optional description text (max 100 characters).
-     */
     setDescription(description: string): this;
-    /**
-     * Sets the component within the label.
-     * Can be a TextInput, SelectMenu, or FileUpload component.
-     */
     setComponent(component: LabelComponentLike): this;
-    /**
-     * Serialises the builder into an API compatible label component payload.
-     */
     toJSON(): APILabelComponent;
 }

package/dist/builders/LabelBuilder.js

@@ -1,55 +1,21 @@
-import { ComponentType, } from "discord-api-types/v10";
-import { resolveJSONEncodable } from "./shared.js";
-/** Builder for Discord label components used in modals. */
+import { ComponentType } from 'discord-api-types/v10';
+import { resolveJSONEncodable } from './shared.js';
+import { ValidationError, assertDefined, assertStringLength } from '../types/validation.js';
 export class LabelBuilder {
     data;
-    /**
-     * Creates a new label builder with optional seed data.
-     */
-    constructor(data = {}) {
-        this.data = {
-            label: data.label,
-            description: data.description,
-            component: data.component,
-        };
-    }
-    /**
-     * Sets the label text (max 45 characters).
-     */
-    setLabel(label) {
-        this.data.label = label;
-        return this;
-    }
-    /**
-     * Sets the optional description text (max 100 characters).
-     */
-    setDescription(description) {
-        this.data.description = description;
-        return this;
-    }
-    /**
-     * Sets the component within the label.
-     * Can be a TextInput, SelectMenu, or FileUpload component.
-     */
-    setComponent(component) {
-        this.data.component = component;
-        return this;
-    }
-    /**
-     * Serialises the builder into an API compatible label component payload.
-     */
+    constructor(data = {}) { this.data = { ...data }; }
+    setLabel(label) { this.data.label = label; return this; }
+    setDescription(description) { this.data.description = description; return this; }
+    setComponent(component) { this.data.component = component; return this; }
     toJSON() {
-        if (!this.data.label) {
-            throw new Error("[LabelBuilder] label is required.");
-        }
-        if (!this.data.component) {
-            throw new Error("[LabelBuilder] component is required.");
-        }
-        return {
-            type: ComponentType.Label,
-            label: this.data.label,
-            description: this.data.description,
-            component: resolveJSONEncodable(this.data.component),
-        };
+        const label = assertDefined('LabelBuilder', 'label', this.data.label);
+        const component = assertDefined('LabelBuilder', 'component', this.data.component);
+        assertStringLength('LabelBuilder', 'label', label, 1, 45);
+        if (this.data.description)
+            assertStringLength('LabelBuilder', 'description', this.data.description, 1, 100);
+        const resolved = resolveJSONEncodable(component);
+        if (!('type' in resolved))
+            throw new ValidationError('LabelBuilder', 'component', 'must contain a valid component payload');
+        return { type: ComponentType.Label, label, description: this.data.description, component: resolved };
     }
 }

package/dist/builders/ModalBuilder.d.ts

@@ -1,40 +1,16 @@
-import type { APIModalInteractionResponseCallbackComponent, APIModalInteractionResponseCallbackData, APITextInputComponent, APIComponentInLabel, APISelectMenuComponent, APIFileUploadComponent } from "discord-api-types/v10";
-import type { JSONEncodable } from "./shared.js";
-/** Values accepted when composing modal component rows. */
-export type ModalComponentLike = JSONEncodable<APIModalInteractionResponseCallbackComponent> | APIModalInteractionResponseCallbackComponent | JSONEncodable<APITextInputComponent> | APITextInputComponent | JSONEncodable<APIComponentInLabel> | APIComponentInLabel | JSONEncodable<APISelectMenuComponent> | APISelectMenuComponent | JSONEncodable<APIFileUploadComponent> | APIFileUploadComponent;
-/** Shape describing initial modal data accepted by the builder. */
+import { type APIModalInteractionResponseCallbackData, type APIModalInteractionResponseCallbackComponent } from 'discord-api-types/v10';
+import { type JSONEncodable } from './shared.js';
+export type ModalComponentLike = JSONEncodable<APIModalInteractionResponseCallbackComponent> | APIModalInteractionResponseCallbackComponent;
 export type ModalBuilderData = {
     customId?: string;
     title?: string;
     components?: Iterable<ModalComponentLike>;
 };
-/** Builder for Discord modal interaction responses. */
 export declare class ModalBuilder implements JSONEncodable<APIModalInteractionResponseCallbackData> {
-    private customId?;
-    private title?;
-    private components;
-    /**
-     * Creates a new modal builder with optional seed data.
-     */
+    private readonly data;
     constructor(data?: ModalBuilderData);
-    /**
-     * Sets the custom identifier returned when the modal is submitted.
-     */
     setCustomId(customId: string): this;
-    /**
-     * Sets the modal title displayed to users.
-     */
     setTitle(title: string): this;
-    /**
-     * Appends component rows to the modal body.
-     */
     addComponents(...components: ModalComponentLike[]): this;
-    /**
-     * Replaces all component rows for the modal.
-     */
-    setComponents(components: Iterable<ModalComponentLike>): this;
-    /**
-     * Serialises the builder into an API compatible modal response payload.
-     */
     toJSON(): APIModalInteractionResponseCallbackData;
 }

package/dist/builders/ModalBuilder.js

@@ -1,92 +1,31 @@
-import { ComponentType } from "discord-api-types/v10";
-import { resolveJSONEncodable } from "./shared.js";
-/** Builder for Discord modal interaction responses. */
+import { ComponentType } from 'discord-api-types/v10';
+import { resolveJSONEncodable } from './shared.js';
+import { ValidationError, assertDefined, assertStringLength } from '../types/validation.js';
 export class ModalBuilder {
-    customId;
-    title;
-    components;
-    /**
-     * Creates a new modal builder with optional seed data.
-     */
+    data;
     constructor(data = {}) {
-        this.customId = data.customId;
-        this.title = data.title;
-        this.components = data.components ? Array.from(data.components) : [];
+        this.data = { ...data, components: data.components ? Array.from(data.components) : [] };
     }
-    /**
-     * Sets the custom identifier returned when the modal is submitted.
-     */
-    setCustomId(customId) {
-        this.customId = customId;
-        return this;
-    }
-    /**
-     * Sets the modal title displayed to users.
-     */
-    setTitle(title) {
-        this.title = title;
-        return this;
-    }
-    /**
-     * Appends component rows to the modal body.
-     */
+    setCustomId(customId) { this.data.customId = customId; return this; }
+    setTitle(title) { this.data.title = title; return this; }
     addComponents(...components) {
-        this.components.push(...components);
-        return this;
-    }
-    /**
-     * Replaces all component rows for the modal.
-     */
-    setComponents(components) {
-        this.components = Array.from(components);
+        this.data.components = [...(this.data.components ?? []), ...components];
         return this;
     }
-    /**
-     * Serialises the builder into an API compatible modal response payload.
-     */
     toJSON() {
-        if (!this.customId) {
-            throw new Error("[ModalBuilder] custom id is required.");
+        const customId = assertDefined('ModalBuilder', 'custom_id', this.data.customId);
+        const title = assertDefined('ModalBuilder', 'title', this.data.title);
+        assertStringLength('ModalBuilder', 'custom_id', customId, 1, 100);
+        assertStringLength('ModalBuilder', 'title', title, 1, 45);
+        const components = Array.from(this.data.components ?? []).map((c) => resolveJSONEncodable(c));
+        if (components.length === 0 || components.length > 5) {
+            throw new ValidationError('ModalBuilder', 'components', 'must contain between 1 and 5 components');
         }
-        if (!this.title) {
-            throw new Error("[ModalBuilder] title is required.");
-        }
-        if (this.components.length === 0) {
-            throw new Error("[ModalBuilder] at least one component is required.");
-        }
-        if (this.components.length > 5) {
-            throw new Error("[ModalBuilder] no more than 5 components can be provided.");
-        }
-        // Auto-wrap components that need wrapping
-        const normalizedComponents = this.components.map((component) => {
-            const resolved = resolveJSONEncodable(component);
-            if (!resolved ||
-                typeof resolved !== "object" ||
-                !("type" in resolved)) {
-                return resolved;
+        for (const component of components) {
+            if (component.type !== ComponentType.ActionRow && component.type !== ComponentType.Label) {
+                throw new ValidationError('ModalBuilder', 'components', `invalid modal top-level component type ${component.type}`);
             }
-            const componentType = resolved.type;
-            // If it's a TextInput, SelectMenu, or FileUpload component, wrap it in an ActionRow
-            // (ActionRows in modals are deprecated, but still supported for backwards compatibility)
-            if (componentType === ComponentType.TextInput ||
-                componentType === ComponentType.StringSelect ||
-                componentType === ComponentType.UserSelect ||
-                componentType === ComponentType.RoleSelect ||
-                componentType === ComponentType.MentionableSelect ||
-                componentType === ComponentType.ChannelSelect ||
-                componentType === ComponentType.FileUpload ||
-                componentType === ComponentType.Label) {
-                return {
-                    type: ComponentType.ActionRow,
-                    components: [resolved],
-                };
-            }
-            return resolved;
-        });
-        return {
-            custom_id: this.customId,
-            title: this.title,
-            components: normalizedComponents,
-        };
+        }
+        return { custom_id: customId, title, components };
     }
 }

package/dist/builders/ModalChannelSelectMenuBuilder.d.ts

@@ -1,6 +1,5 @@
-import { SelectMenuDefaultValueType, type APIChannelSelectComponent, type APISelectMenuDefaultValue, ChannelType } from "discord-api-types/v10";
-import type { JSONEncodable } from "./shared.js";
-/** Shape describing initial modal channel select menu data accepted by the builder. */
+import { ChannelType, SelectMenuDefaultValueType, type APIChannelSelectComponent, type APISelectMenuDefaultValue } from 'discord-api-types/v10';
+import type { JSONEncodable } from './shared.js';
 export type ModalChannelSelectMenuBuilderData = {
     customId?: string;
     placeholder?: string;
@@ -11,51 +10,16 @@ export type ModalChannelSelectMenuBuilderData = {
     channelTypes?: ChannelType[];
     defaultValues?: APISelectMenuDefaultValue<SelectMenuDefaultValueType.Channel>[];
 };
-/** Builder for Discord channel select menu components in modals. */
 export declare class ModalChannelSelectMenuBuilder implements JSONEncodable<APIChannelSelectComponent> {
-    private data;
-    /**
-     * Creates a new modal channel select menu builder with optional seed data.
-     */
+    private readonly data;
     constructor(data?: ModalChannelSelectMenuBuilderData);
-    /**
-     * Sets the unique custom identifier for the select menu interaction.
-     */
     setCustomId(customId: string): this;
-    /**
-     * Sets or clears the placeholder text displayed when no channel is selected.
-     */
-    setPlaceholder(placeholder: string | null | undefined): this;
-    /**
-     * Sets the minimum number of channels that must be selected.
-     */
-    setMinValues(minValues: number | null | undefined): this;
-    /**
-     * Sets the maximum number of channels that can be selected.
-     */
-    setMaxValues(maxValues: number | null | undefined): this;
-    /**
-     * Toggles whether the select menu is disabled.
-     */
+    setPlaceholder(placeholder?: string): this;
+    setMinValues(minValues?: number): this;
+    setMaxValues(maxValues?: number): this;
     setDisabled(disabled: boolean): this;
-    /**
-     * Marks the select menu as required in the modal.
-     */
     setRequired(required: boolean): this;
-    /**
-     * Replaces the default channel selections displayed when the menu renders.
-     */
+    setChannelTypes(channelTypes: ChannelType[]): this;
     setDefaultValues(defaultValues: Iterable<APISelectMenuDefaultValue<SelectMenuDefaultValueType.Channel>>): this;
-    /**
-     * Sets the channel types allowed in the select menu.
-     */
-    setChannelTypes(...channelTypes: ChannelType[]): this;
-    /**
-     * Adds channel types allowed in the select menu.
-     */
-    addChannelTypes(...channelTypes: ChannelType[]): this;
-    /**
-     * Serialises the builder into an API compatible channel select menu payload.
-     */
     toJSON(): APIChannelSelectComponent;
 }

package/dist/builders/ModalChannelSelectMenuBuilder.js

@@ -1,115 +1,30 @@
-import { ComponentType, SelectMenuDefaultValueType, } from "discord-api-types/v10";
-/** Builder for Discord channel select menu components in modals. */
+import { ComponentType, SelectMenuDefaultValueType } from 'discord-api-types/v10';
+import { assertDefined, assertRange, assertStringLength, ValidationError } from '../types/validation.js';
 export class ModalChannelSelectMenuBuilder {
     data;
-    /**
-     * Creates a new modal channel select menu builder with optional seed data.
-     */
-    constructor(data = {}) {
-        this.data = {
-            customId: data.customId,
-            placeholder: data.placeholder,
-            minValues: data.minValues,
-            maxValues: data.maxValues,
-            disabled: data.disabled,
-            required: data.required,
-            channelTypes: data.channelTypes,
-            defaultValues: data.defaultValues
-                ? data.defaultValues.map((value) => ({
-                    ...value,
-                    type: SelectMenuDefaultValueType.Channel,
-                }))
-                : undefined,
-        };
-    }
-    /**
-     * Sets the unique custom identifier for the select menu interaction.
-     */
-    setCustomId(customId) {
-        this.data.customId = customId;
-        return this;
-    }
-    /**
-     * Sets or clears the placeholder text displayed when no channel is selected.
-     */
-    setPlaceholder(placeholder) {
-        this.data.placeholder = placeholder ?? undefined;
-        return this;
-    }
-    /**
-     * Sets the minimum number of channels that must be selected.
-     */
-    setMinValues(minValues) {
-        this.data.minValues = minValues ?? undefined;
-        return this;
-    }
-    /**
-     * Sets the maximum number of channels that can be selected.
-     */
-    setMaxValues(maxValues) {
-        this.data.maxValues = maxValues ?? undefined;
-        return this;
-    }
-    /**
-     * Toggles whether the select menu is disabled.
-     */
-    setDisabled(disabled) {
-        this.data.disabled = disabled;
-        return this;
-    }
-    /**
-     * Marks the select menu as required in the modal.
-     */
-    setRequired(required) {
-        this.data.required = required;
-        return this;
-    }
-    /**
-     * Replaces the default channel selections displayed when the menu renders.
-     */
+    constructor(data = {}) { this.data = { ...data }; }
+    setCustomId(customId) { this.data.customId = customId; return this; }
+    setPlaceholder(placeholder) { this.data.placeholder = placeholder; return this; }
+    setMinValues(minValues) { this.data.minValues = minValues; return this; }
+    setMaxValues(maxValues) { this.data.maxValues = maxValues; return this; }
+    setDisabled(disabled) { this.data.disabled = disabled; return this; }
+    setRequired(required) { this.data.required = required; return this; }
+    setChannelTypes(channelTypes) { this.data.channelTypes = [...channelTypes]; return this; }
     setDefaultValues(defaultValues) {
-        this.data.defaultValues = Array.from(defaultValues, (value) => ({
-            ...value,
-            type: SelectMenuDefaultValueType.Channel,
-        }));
-        return this;
-    }
-    /**
-     * Sets the channel types allowed in the select menu.
-     */
-    setChannelTypes(...channelTypes) {
-        this.data.channelTypes = channelTypes.flat();
-        return this;
-    }
-    /**
-     * Adds channel types allowed in the select menu.
-     */
-    addChannelTypes(...channelTypes) {
-        this.data.channelTypes ??= [];
-        this.data.channelTypes.push(...channelTypes.flat());
+        this.data.defaultValues = Array.from(defaultValues, (v) => ({ ...v, type: SelectMenuDefaultValueType.Channel }));
         return this;
     }
-    /**
-     * Serialises the builder into an API compatible channel select menu payload.
-     */
     toJSON() {
-        const { customId } = this.data;
-        if (!customId) {
-            throw new Error("[ModalChannelSelectMenuBuilder] custom id is required.");
-        }
-        return {
-            type: ComponentType.ChannelSelect,
-            custom_id: customId,
-            placeholder: this.data.placeholder,
-            min_values: this.data.minValues,
-            max_values: this.data.maxValues,
-            disabled: this.data.disabled,
-            required: this.data.required,
-            channel_types: this.data.channelTypes,
-            default_values: this.data.defaultValues?.map((value) => ({
-                ...value,
-                type: SelectMenuDefaultValueType.Channel,
-            })),
-        };
+        const customId = assertDefined('ModalChannelSelectMenuBuilder', 'custom_id', this.data.customId);
+        assertStringLength('ModalChannelSelectMenuBuilder', 'custom_id', customId, 1, 100);
+        if (this.data.placeholder)
+            assertStringLength('ModalChannelSelectMenuBuilder', 'placeholder', this.data.placeholder, 1, 150);
+        if (this.data.minValues !== undefined)
+            assertRange('ModalChannelSelectMenuBuilder', 'min_values', this.data.minValues, 0, 25);
+        if (this.data.maxValues !== undefined)
+            assertRange('ModalChannelSelectMenuBuilder', 'max_values', this.data.maxValues, 1, 25);
+        if (this.data.minValues !== undefined && this.data.maxValues !== undefined && this.data.minValues > this.data.maxValues)
+            throw new ValidationError('ModalChannelSelectMenuBuilder', 'min_values', 'cannot exceed max_values');
+        return { type: ComponentType.ChannelSelect, custom_id: customId, placeholder: this.data.placeholder, min_values: this.data.minValues, max_values: this.data.maxValues, disabled: this.data.disabled, required: this.data.required, channel_types: this.data.channelTypes, default_values: this.data.defaultValues };
     }
 }