@minesa-org/mini-interaction 0.3.14 → 0.4.1

package/README.md

@@ -1,3 +1,144 @@
-# Mini Interaction
+# 🌌 Mini Interaction
 
-Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).
+> **Sleek, Modular, and Type-Safe Discord Interactions Framework.**
+
+Mini Interaction is a high-performance framework designed for building Discord HTTP/Webhook-based bots. It provides a modular architecture that separates concerns, making your bot easier to maintain, test, and scale.
+
+---
+
+## ✨ Features
+
+- **🚀 Modular Router**: Easily map commands, components, and modals to handlers.
+- **⚡ Core V10 Engine**: Native support for Discord API v10 payloads.
+- **🛡️ Type Safety**: Full TypeScript support with rich autocompletion.
+- **🧩 Fluent Builders**: Construct complex messages and components with a premium API.
+- **🔐 Integrated OAuth**: Simple handlers for Discord OAuth2 flows.
+- **🗃️ Mini Database**: Lightweight, document-based storage integration.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @minesa-org/mini-interaction
+```
+
+---
+
+## 🛠️ Quick Start
+
+Mini Interaction uses a modular approach with a dedicated Router and Context.
+
+### 1. Define your Router
+```ts
+import { InteractionRouter } from '@minesa-org/mini-interaction';
+
+const router = new InteractionRouter();
+
+// Register a slash command
+router.onCommand('ping', async (interaction, ctx) => {
+  return ctx.reply({ content: '🏓 Pong!' });
+});
+
+// Register a component handler
+router.onComponent('my_button', async (interaction, ctx) => {
+  return ctx.reply({ content: 'Button clicked!', ephemeral: true });
+});
+```
+
+### 2. Handle Interactions
+```ts
+import { 
+  verifyAndParseInteraction, 
+  InteractionContext, 
+  DiscordRestClient 
+} from '@minesa-org/mini-interaction';
+
+const rest = new DiscordRestClient({ 
+  applicationId: process.env.DISCORD_APP_ID, 
+  token: process.env.DISCORD_TOKEN 
+});
+
+// In your web server (e.g., Next.js, Vercel, Express)
+export async function POST(req) {
+  const body = await req.text();
+  const signature = req.headers.get('x-signature-ed25519');
+  const timestamp = req.headers.get('x-signature-timestamp');
+
+  // Verify and parse the interaction
+  const interaction = await verifyAndParseInteraction({
+    body,
+    signature,
+    timestamp,
+    publicKey: process.env.DISCORD_PUBLIC_KEY
+  });
+
+  if (interaction.type === 1) return Response.json({ type: 1 });
+
+  const ctx = new InteractionContext({ interaction, rest });
+  const response = await router.dispatch(interaction, ctx);
+
+  return Response.json(response ?? ctx.deferReply());
+}
+```
+
+---
+
+## 🎨 Message Builders
+
+Mini Interaction provides a rich set of builders to create beautiful Discord content.
+
+```ts
+import { ModalBuilder, TextInputBuilder, TextInputStyle } from '@minesa-org/mini-interaction';
+
+const modal = new ModalBuilder()
+  .setCustomId('feedback_form')
+  .setTitle('Send us Feedback')
+  .addComponents(
+    new TextInputBuilder()
+      .setCustomId('feedback_text')
+      .setLabel('Your Message')
+      .setStyle(TextInputStyle.Paragraph)
+      .setPlaceholder('Tell us what you think...')
+  );
+```
+
+---
+
+## 📡 Advanced Routing
+
+You can organize your handlers into separate modules for better scalability.
+
+```ts
+// components/modals.ts
+router.onModal('feedback_submit', async (interaction, ctx) => {
+  const feedback = interaction.getTextFieldValue('feedback_text');
+  // Process feedback...
+  return ctx.reply({ content: 'Thank you for your feedback!' });
+});
+```
+
+---
+
+## 🛡️ Error Handling
+
+Mini Interaction includes built-in validation to ensure your payloads follow Discord's requirements.
+
+```ts
+import { ValidationError } from '@minesa-org/mini-interaction';
+
+try {
+  const builder = new TextInputBuilder().setCustomId(''); // Too short!
+  builder.toJSON();
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(`Validation failed for ${error.component}: ${error.message}`);
+  }
+}
+```
+
+---
+
+## 📜 License
+
+MIT © [Minesa](https://github.com/minesa-org)

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;
 }