@minesa-org/mini-interaction 0.1.13 → 0.2.0

package/dist/builders/ActionRowBuilder.d.ts

@@ -1,25 +1,23 @@
 import type { APIActionRowComponent } from "discord-api-types/v10";
 import type { JSONEncodable } from "./shared.js";
-import type { MiniComponentActionRow } from "../types/ComponentTypes.js";
+import type { ActionRowComponent } from "../types/ComponentTypes.js";
 /** Values accepted when composing component action rows. */
-export type ActionRowComponentLike<T extends MiniComponentActionRow> = JSONEncodable<T> | T;
-/** Builder for Discord action row components. */
-export declare class ActionRowBuilder<T extends MiniComponentActionRow = MiniComponentActionRow> implements JSONEncodable<APIActionRowComponent<T>> {
+export type ActionRowComponentLike<T extends ActionRowComponent> = JSONEncodable<T> | T;
+/** Builder for creating Action Row components. */
+export declare class ActionRowBuilder<T extends ActionRowComponent> implements JSONEncodable<APIActionRowComponent<T>> {
     private components;
+    constructor(data?: Partial<APIActionRowComponent<T>>);
     /**
-     * Creates a new action row builder with optional seed components.
+     * Adds components to this action row.
+     *
+     * @param components - The components to add (can be builders or raw objects).
      */
-    constructor(components?: Iterable<ActionRowComponentLike<T>>);
+    addComponents(...components: (T | JSONEncodable<T>)[]): this;
     /**
-     * Appends additional components to the action row.
-     */
-    addComponents(...components: ActionRowComponentLike<T>[]): this;
-    /**
-     * Replaces the current action row contents.
-     */
-    setComponents(components: Iterable<ActionRowComponentLike<T>>): this;
-    /**
-     * Serialises the builder into an API compatible action row payload.
+     * Sets the components for this action row, replacing any existing ones.
+     *
+     * @param components - The new components to set.
      */
+    setComponents(...components: (T | JSONEncodable<T>)[]): this;
     toJSON(): APIActionRowComponent<T>;
 }

package/dist/builders/ActionRowBuilder.js

@@ -1,35 +1,33 @@
 import { ComponentType } from "discord-api-types/v10";
 import { resolveJSONEncodable } from "./shared.js";
-/** Builder for Discord action row components. */
+/** Builder for creating Action Row components. */
 export class ActionRowBuilder {
-    components;
-    /**
-     * Creates a new action row builder with optional seed components.
-     */
-    constructor(components = []) {
-        this.components = Array.from(components);
+    components = [];
+    constructor(data = {}) {
+        this.components = [...(data.components ?? [])];
     }
     /**
-     * Appends additional components to the action row.
+     * Adds components to this action row.
+     *
+     * @param components - The components to add (can be builders or raw objects).
      */
     addComponents(...components) {
-        this.components.push(...components);
+        this.components.push(...components.map((c) => resolveJSONEncodable(c)));
         return this;
     }
     /**
-     * Replaces the current action row contents.
+     * Sets the components for this action row, replacing any existing ones.
+     *
+     * @param components - The new components to set.
      */
-    setComponents(components) {
-        this.components = Array.from(components);
+    setComponents(...components) {
+        this.components = components.map((c) => resolveJSONEncodable(c));
         return this;
     }
-    /**
-     * Serialises the builder into an API compatible action row payload.
-     */
     toJSON() {
         return {
             type: ComponentType.ActionRow,
-            components: this.components.map((component) => resolveJSONEncodable(component)),
+            components: [...this.components],
         };
     }
 }

package/dist/clients/MiniInteraction.d.ts

@@ -1,12 +1,12 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { APIInteractionResponse, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIContextMenuApplicationCommandsJSONBody, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody } from "discord-api-types/v10";
-import type { MiniInteractionCommand } from "../types/Commands.js";
+import type { InteractionCommand } from "../types/Commands.js";
 import { RoleConnectionMetadataTypes } from "../types/RoleConnectionMetadataTypes.js";
 import { type MessageComponentInteraction, type ButtonInteraction, type StringSelectInteraction, type RoleSelectInteraction, type UserSelectInteraction, type ChannelSelectInteraction, type MentionableSelectInteraction } from "../utils/MessageComponentInteraction.js";
 import { type ModalSubmitInteraction } from "../utils/ModalSubmitInteraction.js";
 import { type OAuthConfig, type OAuthTokens, type DiscordUser } from "../oauth/DiscordOAuth.js";
 /** Configuration parameters for the MiniInteraction client. */
-export type MiniInteractionOptions = {
+export type InteractionClientOptions = {
     applicationId: string;
     publicKey: string;
     commandsDirectory?: string | false;
@@ -26,13 +26,13 @@ export type RoleConnectionMetadataField = {
 /**
  * HTTP request information needed to validate and handle Discord interaction payloads.
  */
-export type MiniInteractionRequest = {
+export type InteractionRequest = {
     body: string | Uint8Array;
     signature?: string;
     timestamp?: string;
 };
 /** Result payload returned by request handlers when processing an interaction. */
-export type MiniInteractionHandlerResult = {
+export type InteractionHandlerResult = {
     status: number;
     body: APIInteractionResponse | {
         error: string;
@@ -46,25 +46,36 @@ export type InteractionTimeoutConfig = {
     enableTimeoutWarnings?: boolean;
     /** Whether to force deferReply for slow operations (default: true) */
     autoDeferSlowOperations?: boolean;
+    /** Whether to enable debug logging for interaction responses (default: false) */
+    enableResponseDebugLogging?: boolean;
+};
+/** Enhanced timeout configuration with response acknowledgment settings. */
+export type InteractionTimeoutConfigV2 = InteractionTimeoutConfig & {
+    /** Time to wait for Discord acknowledgment after sending response (default: 500ms) */
+    responseAcknowledgmentTimeout?: number;
+    /** Maximum retries for response acknowledgment (default: 2) */
+    responseAcknowledgmentRetries?: number;
+    /** Delay between acknowledgment retries (default: 100ms) */
+    responseAcknowledgmentRetryDelay?: number;
 };
 /** Handler signature invoked for Discord button interactions. */
-export type MiniInteractionButtonHandler = (interaction: ButtonInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type ButtonComponentHandler = (interaction: ButtonInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord string select menu interactions. */
-export type MiniInteractionStringSelectHandler = (interaction: StringSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type StringSelectComponentHandler = (interaction: StringSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord role select menu interactions. */
-export type MiniInteractionRoleSelectHandler = (interaction: RoleSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type RoleSelectComponentHandler = (interaction: RoleSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord user select menu interactions. */
-export type MiniInteractionUserSelectHandler = (interaction: UserSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type UserSelectComponentHandler = (interaction: UserSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord channel select menu interactions. */
-export type MiniInteractionChannelSelectHandler = (interaction: ChannelSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type ChannelSelectComponentHandler = (interaction: ChannelSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord mentionable select menu interactions. */
-export type MiniInteractionMentionableSelectHandler = (interaction: MentionableSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type MentionableSelectComponentHandler = (interaction: MentionableSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord message component interactions (generic). */
-export type MiniInteractionComponentHandler = (interaction: MessageComponentInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type ComponentHandler = (interaction: MessageComponentInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord modal submit interactions. */
-export type MiniInteractionModalHandler = (interaction: ModalSubmitInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+export type ModalHandler = (interaction: ModalSubmitInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Unified handler signature that accepts any component or modal interaction. */
-export type MiniInteractionHandler = MiniInteractionButtonHandler | MiniInteractionStringSelectHandler | MiniInteractionRoleSelectHandler | MiniInteractionUserSelectHandler | MiniInteractionChannelSelectHandler | MiniInteractionMentionableSelectHandler | MiniInteractionComponentHandler | MiniInteractionModalHandler;
+export type InteractionHandler = ButtonComponentHandler | StringSelectComponentHandler | RoleSelectComponentHandler | UserSelectComponentHandler | ChannelSelectComponentHandler | MentionableSelectComponentHandler | ComponentHandler | ModalHandler;
 type CommandDataPayload = RESTPostAPIChatInputApplicationCommandsJSONBody | RESTPostAPIContextMenuApplicationCommandsJSONBody | RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody;
 /**
  * Structure describing a component or modal handler mapped to a custom id.
@@ -73,19 +84,19 @@ type CommandDataPayload = RESTPostAPIChatInputApplicationCommandsJSONBody | REST
  * - Other files are treated as component handlers
  * You can use this type for both - the system will figure out which one it is.
  */
-export type MiniInteractionComponent = {
+export type ComponentCommand = {
     customId: string;
-    handler: MiniInteractionHandler;
+    handler: InteractionHandler;
 };
 /** Structure describing a modal handler mapped to a custom id. */
-export type MiniInteractionModal = {
+export type ModalCommand = {
     customId: string;
-    handler: MiniInteractionModalHandler;
+    handler: ModalHandler;
 };
 /** Node.js HTTP handler compatible with frameworks like Express or Next.js API routes. */
-export type MiniInteractionNodeHandler = (request: IncomingMessage, response: ServerResponse) => void;
+export type InteractionNodeHandler = (request: IncomingMessage, response: ServerResponse) => void;
 /** Web Fetch API compatible request handler for platforms such as Cloudflare Workers. */
-export type MiniInteractionFetchHandler = (request: Request) => Promise<Response>;
+export type InteractionFetchHandler = (request: Request) => Promise<Response>;
 /** Context passed to OAuth success handlers and templates. */
 export type DiscordOAuthAuthorizeContext = {
     tokens: OAuthTokens;
@@ -162,6 +173,7 @@ export declare class MiniInteraction {
     private readonly componentHandlers;
     private readonly modalHandlers;
     private readonly htmlTemplateCache;
+    private readonly interactionStates;
     private commandsLoaded;
     private loadCommandsPromise;
     private componentsLoaded;
@@ -171,7 +183,52 @@ export declare class MiniInteraction {
     /**
      * Creates a new MiniInteraction client with optional command auto-loading and custom runtime hooks.
      */
-    constructor({ applicationId, publicKey, commandsDirectory, componentsDirectory, utilsDirectory, fetchImplementation, verifyKeyImplementation, timeoutConfig, }: MiniInteractionOptions);
+    constructor({ applicationId, publicKey, commandsDirectory, componentsDirectory, utilsDirectory, fetchImplementation, verifyKeyImplementation, timeoutConfig, }: InteractionClientOptions);
+    /**
+     * Tracks the state of an interaction to prevent race conditions and double responses.
+     */
+    private trackInteractionState;
+    /**
+     * Checks if an interaction can still respond (not expired and not already responded).
+     */
+    private canRespond;
+    /**
+     * Logs response timing and acknowledgment for debugging.
+     */
+    private logResponseTiming;
+    /**
+     * Simulates waiting for Discord acknowledgment to help debug timing issues.
+     * Note: This is a best-effort simulation since actual acknowledgment happens at the HTTP level.
+     */
+    private simulateAcknowledgmentWait;
+    /**
+     * Enables or disables debug logging for interaction responses and timing.
+     * Useful for troubleshooting "didn't respond in time" errors.
+     *
+     * @param enabled - Whether to enable debug logging
+     */
+    setResponseDebugLogging(enabled: boolean): void;
+    /**
+     * Gets the current state of an interaction.
+     */
+    private getInteractionState;
+    /**
+     * Gets the current state of an interaction for debugging purposes.
+     *
+     * @param interactionId - The interaction ID to check
+     * @returns The current interaction state or null if not found
+     */
+    getInteractionStateInfo(interactionId: string): {
+        state: "pending" | "deferred" | "responded" | "expired";
+        timestamp: number;
+        token: string;
+        responseCount: number;
+    } | null;
+    /**
+     * Clears expired interaction states to prevent memory leaks.
+     * Call this periodically to clean up old interaction data.
+     */
+    cleanupExpiredInteractions(): number;
     private normalizeCommandData;
     private registerCommand;
     /**
@@ -179,37 +236,37 @@ export declare class MiniInteraction {
      *
      * @param command - The command definition to register.
      */
-    useCommand(command: MiniInteractionCommand): this;
+    useCommand(command: InteractionCommand): this;
     /**
      * Registers multiple command handlers with the client.
      *
      * @param commands - The command definitions to register.
      */
-    useCommands(commands: MiniInteractionCommand[]): this;
+    useCommands(commands: InteractionCommand[]): this;
     /**
      * Registers a single component handler mapped to a custom identifier.
      *
      * @param component - The component definition to register.
      */
-    useComponent(component: MiniInteractionComponent): this;
+    useComponent(component: ComponentCommand): this;
     /**
      * Registers multiple component handlers in a single call.
      *
      * @param components - The component definitions to register.
      */
-    useComponents(components: MiniInteractionComponent[]): this;
+    useComponents(components: ComponentCommand[]): this;
     /**
      * Registers a single modal handler mapped to a custom identifier.
      *
      * @param modal - The modal definition to register.
      */
-    useModal(modal: MiniInteractionModal): this;
+    useModal(modal: ModalCommand): this;
     /**
      * Registers multiple modal handlers in a single call.
      *
      * @param modals - The modal definitions to register.
      */
-    useModals(modals: MiniInteractionModal[]): this;
+    useModals(modals: ModalCommand[]): this;
     /**
      * Recursively loads components from the configured components directory.
      *
@@ -245,12 +302,12 @@ export declare class MiniInteraction {
      *
      * @param request - The request payload containing headers and body data.
      */
-    handleRequest(request: MiniInteractionRequest): Promise<MiniInteractionHandlerResult>;
+    handleRequest(request: InteractionRequest): Promise<InteractionHandlerResult>;
     /**
      * Creates a Node.js style request handler compatible with Express, Next.js API routes,
      * Vercel serverless functions, and any runtime that expects a `(req, res)` listener.
      */
-    createNodeHandler(): MiniInteractionNodeHandler;
+    createNodeHandler(): InteractionNodeHandler;
     /**
      * Generates a lightweight verification handler that serves an HTML page with an embedded OAuth link.
      *
@@ -264,7 +321,7 @@ export declare class MiniInteraction {
      * - `{{OAUTH_STATE}}` - HTML-escaped OAuth state value.
      * - Custom placeholder name (from {@link DiscordOAuthVerificationPageOptions.placeholder}) and its `_RAW` variant.
      */
-    discordOAuthVerificationPage(options?: DiscordOAuthVerificationPageOptions): MiniInteractionNodeHandler;
+    discordOAuthVerificationPage(options?: DiscordOAuthVerificationPageOptions): InteractionNodeHandler;
     /**
      * Loads an HTML file and returns a success template that replaces useful placeholders.
      *
@@ -300,11 +357,11 @@ export declare class MiniInteraction {
      * This helper keeps the user-side implementation tiny while still exposing hooks for
      * storing metadata or validating the OAuth state value.
      */
-    discordOAuthCallback(options: DiscordOAuthCallbackOptions): MiniInteractionNodeHandler;
+    discordOAuthCallback(options: DiscordOAuthCallbackOptions): InteractionNodeHandler;
     /**
      * Creates a Fetch API compatible handler for runtimes like Workers or Deno.
      */
-    createFetchHandler(): MiniInteractionFetchHandler;
+    createFetchHandler(): InteractionFetchHandler;
     /**
      * Checks if the provided directory path exists on disk.
      */

package/dist/clients/MiniInteraction.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ApplicationCommandType, InteractionResponseType, InteractionType, } from "discord-api-types/v10";
 import { verifyKey } from "discord-interactions";
+import { resolveJSONEncodable } from "../builders/shared.js";
 import { DISCORD_BASE_URL } from "../utils/constants.js";
 import { createCommandInteraction } from "../utils/CommandInteractionOptions.js";
 import { createMessageComponentInteraction, } from "../utils/MessageComponentInteraction.js";
@@ -35,6 +36,7 @@ export class MiniInteraction {
     componentHandlers = new Map();
     modalHandlers = new Map();
     htmlTemplateCache = new Map();
+    interactionStates = new Map();
     commandsLoaded = false;
     loadCommandsPromise = null;
     componentsLoaded = false;
@@ -75,15 +77,131 @@ export class MiniInteraction {
             initialResponseTimeout: 2800, // Leave 200ms buffer before Discord's 3s limit
             enableTimeoutWarnings: true,
             autoDeferSlowOperations: true,
+            enableResponseDebugLogging: false,
+            responseAcknowledgmentTimeout: 500, // 500ms to wait for acknowledgment
+            responseAcknowledgmentRetries: 2,
+            responseAcknowledgmentRetryDelay: 100,
             ...timeoutConfig,
         };
     }
+    /**
+     * Tracks the state of an interaction to prevent race conditions and double responses.
+     */
+    trackInteractionState(interactionId, token, state) {
+        const existing = this.interactionStates.get(interactionId);
+        const now = Date.now();
+        this.interactionStates.set(interactionId, {
+            state,
+            timestamp: now,
+            token,
+            responseCount: existing ? existing.responseCount + 1 : 1,
+        });
+        if (this.timeoutConfig.enableResponseDebugLogging) {
+            console.log(`[MiniInteraction:DEBUG] Interaction ${interactionId} state: ${state} (${existing ? existing.responseCount + 1 : 1} responses)`);
+        }
+    }
+    /**
+     * Checks if an interaction can still respond (not expired and not already responded).
+     */
+    canRespond(interactionId) {
+        const state = this.getInteractionState(interactionId);
+        if (!state)
+            return true; // New interaction
+        // Check if expired (15 minutes)
+        if (Date.now() - state.timestamp > 900000) {
+            this.trackInteractionState(interactionId, state.token, 'expired');
+            return false;
+        }
+        // Check if already responded
+        if (state.state === 'responded') {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Logs response timing and acknowledgment for debugging.
+     */
+    logResponseTiming(interactionId, operation, startTime, success) {
+        if (!this.timeoutConfig.enableResponseDebugLogging)
+            return;
+        const elapsed = Date.now() - startTime;
+        const status = success ? 'SUCCESS' : 'FAILED';
+        console.log(`[MiniInteraction:DEBUG] ${operation} for interaction ${interactionId}: ${status} (${elapsed}ms)`);
+        if (success && elapsed > 2000) {
+            console.warn(`[MiniInteraction:WARN] ${operation} took ${elapsed}ms - consider using deferReply() for slow operations`);
+        }
+    }
+    /**
+     * Simulates waiting for Discord acknowledgment to help debug timing issues.
+     * Note: This is a best-effort simulation since actual acknowledgment happens at the HTTP level.
+     */
+    async simulateAcknowledgmentWait(interactionId, operation) {
+        if (!this.timeoutConfig.enableResponseDebugLogging)
+            return;
+        const timeout = this.timeoutConfig.responseAcknowledgmentTimeout || 500;
+        const retries = this.timeoutConfig.responseAcknowledgmentRetries || 2;
+        const retryDelay = this.timeoutConfig.responseAcknowledgmentRetryDelay || 100;
+        console.log(`[MiniInteraction:DEBUG] Waiting for acknowledgment of ${operation} for interaction ${interactionId}...`);
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            await new Promise(resolve => setTimeout(resolve, attempt === 0 ? timeout : retryDelay));
+            // In a real implementation, this would verify Discord actually received the response
+            // For now, we just simulate the wait time
+            const state = this.getInteractionState(interactionId);
+            if (state?.state === 'responded' || state?.state === 'deferred') {
+                console.log(`[MiniInteraction:DEBUG] Acknowledgment confirmed for ${operation} after ${attempt + 1} attempts`);
+                return;
+            }
+        }
+        console.warn(`[MiniInteraction:WARN] Acknowledgment timeout for ${operation} on interaction ${interactionId}`);
+    }
+    /**
+     * Enables or disables debug logging for interaction responses and timing.
+     * Useful for troubleshooting "didn't respond in time" errors.
+     *
+     * @param enabled - Whether to enable debug logging
+     */
+    setResponseDebugLogging(enabled) {
+        this.timeoutConfig.enableResponseDebugLogging = enabled;
+        console.log(`[MiniInteraction] Response debug logging ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Gets the current state of an interaction.
+     */
+    getInteractionState(interactionId) {
+        return this.interactionStates.get(interactionId);
+    }
+    /**
+     * Gets the current state of an interaction for debugging purposes.
+     *
+     * @param interactionId - The interaction ID to check
+     * @returns The current interaction state or null if not found
+     */
+    getInteractionStateInfo(interactionId) {
+        const state = this.interactionStates.get(interactionId);
+        return state ? { ...state } : null; // Return a copy to prevent external modification
+    }
+    /**
+     * Clears expired interaction states to prevent memory leaks.
+     * Call this periodically to clean up old interaction data.
+     */
+    cleanupExpiredInteractions() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, state] of this.interactionStates.entries()) {
+            // Remove interactions older than 15 minutes
+            if (now - state.timestamp > 900000) {
+                this.interactionStates.delete(id);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            console.log(`[MiniInteraction] Cleaned up ${cleaned} expired interactions`);
+        }
+        return cleaned;
+    }
     normalizeCommandData(data) {
         if (typeof data === "object" && data !== null) {
-            const toJSON = data.toJSON;
-            if (typeof toJSON === "function") {
-                return toJSON.call(data);
-            }
+            return resolveJSONEncodable(data);
         }
         return data;
     }
@@ -400,23 +518,34 @@ export class MiniInteraction {
             };
         }
         if (interaction.type === InteractionType.ApplicationCommand) {
+            // Track interaction start
+            this.trackInteractionState(interaction.id, interaction.token, 'pending');
             return this.handleApplicationCommand(interaction);
         }
         if (interaction.type === InteractionType.MessageComponent) {
+            // Track interaction start
+            this.trackInteractionState(interaction.id, interaction.token, 'pending');
             return this.handleMessageComponent(interaction);
         }
         if (interaction.type === InteractionType.ModalSubmit) {
+            // Track interaction start
+            this.trackInteractionState(interaction.id, interaction.token, 'pending');
             return this.handleModalSubmit(interaction);
         }
-        // Check total processing time
+        // Check total processing time and log potential timeout issues
         const totalProcessingTime = Date.now() - requestStartTime;
         if (this.timeoutConfig.enableTimeoutWarnings &&
             totalProcessingTime >
                 this.timeoutConfig.initialResponseTimeout * 0.9) {
-            console.warn(`[MiniInteraction] WARNING: Interaction processing took ${totalProcessingTime}ms ` +
+            console.warn(`[MiniInteraction] CRITICAL: Interaction processing took ${totalProcessingTime}ms ` +
                 `(${Math.round((totalProcessingTime / 3000) * 100)}% of Discord's 3-second limit). ` +
+                `This may cause "didn't respond in time" errors. ` +
                 `Consider optimizing or using deferReply() for slow operations.`);
         }
+        // Log successful response timing for debugging
+        if (this.timeoutConfig.enableResponseDebugLogging) {
+            console.log(`[MiniInteraction:DEBUG] Request completed in ${totalProcessingTime}ms`);
+        }
         return {
             status: 400,
             body: {
@@ -1195,7 +1324,11 @@ export class MiniInteraction {
                 // Check if it's a chat input (slash) command
                 if (commandInteraction.data.type ===
                     ApplicationCommandType.ChatInput) {
-                    const interactionWithHelpers = createCommandInteraction(commandInteraction);
+                    const interactionWithHelpers = createCommandInteraction(commandInteraction, {
+                        canRespond: (id) => this.canRespond(id),
+                        trackResponse: (id, token, state) => this.trackInteractionState(id, token, state),
+                        logTiming: (id, op, start, success) => this.logResponseTiming(id, op, start, success),
+                    });
                     response = await command.handler(interactionWithHelpers);
                     resolvedResponse =
                         response ?? interactionWithHelpers.getResponse();

package/dist/index.d.ts

@@ -5,21 +5,21 @@ export { CommandBuilder, CommandContext, IntegrationType, } from "./commands/Com
 export { UserCommandBuilder, MessageCommandBuilder, AppCommandBuilder, } from "./commands/ContextMenuCommandBuilder.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 { UserContextMenuInteraction, MessageContextMenuInteraction, AppCommandInteraction, } from "./utils/ContextMenuInteraction.js";
-export type { MiniInteractionFetchHandler, MiniInteractionNodeHandler, MiniInteractionHandlerResult, MiniInteractionRequest, MiniInteractionOptions, DiscordOAuthAuthorizeContext, DiscordOAuthCallbackOptions, DiscordOAuthCallbackTemplates, DiscordOAuthErrorTemplateContext, DiscordOAuthServerErrorTemplateContext, DiscordOAuthStateTemplateContext, DiscordOAuthSuccessTemplateContext, DiscordOAuthVerificationPageOptions, } from "./clients/MiniInteraction.js";
-export type { MiniInteractionCommand, SlashCommandHandler, UserCommandHandler, MessageCommandHandler, AppCommandHandler, CommandHandler, } from "./types/Commands.js";
-export type { MiniInteractionComponent, MiniInteractionButtonHandler, MiniInteractionStringSelectHandler, MiniInteractionRoleSelectHandler, MiniInteractionUserSelectHandler, MiniInteractionChannelSelectHandler, MiniInteractionMentionableSelectHandler, MiniInteractionComponentHandler, MiniInteractionModal, MiniInteractionModalHandler, MiniInteractionHandler, } from "./clients/MiniInteraction.js";
-export type { MessageComponentInteraction, ButtonInteraction, StringSelectInteraction, RoleSelectInteraction, UserSelectInteraction, ChannelSelectInteraction, MentionableSelectInteraction, ResolvedUserOption as ComponentResolvedUserOption, ResolvedMentionableOption as ComponentResolvedMentionableOption, } from "./utils/MessageComponentInteraction.js";
-export type { ModalSubmitInteraction } from "./utils/ModalSubmitInteraction.js";
+export { CommandInteraction, MentionableOption, ResolvedUserOption, } from "./utils/CommandInteractionOptions.js";
+export { UserContextMenuInteraction, MessageContextMenuInteraction, AppCommandInteraction, } from "./utils/ContextMenuInteraction.js";
+export type { InteractionFetchHandler, InteractionNodeHandler, InteractionHandlerResult, InteractionRequest, InteractionClientOptions, DiscordOAuthAuthorizeContext, DiscordOAuthCallbackOptions, DiscordOAuthCallbackTemplates, DiscordOAuthErrorTemplateContext, DiscordOAuthServerErrorTemplateContext, DiscordOAuthStateTemplateContext, DiscordOAuthSuccessTemplateContext, DiscordOAuthVerificationPageOptions, } from "./clients/MiniInteraction.js";
+export type { InteractionCommand, SlashCommandHandler, UserCommandHandler, MessageCommandHandler, AppCommandHandler, CommandHandler, } from "./types/Commands.js";
+export type { ComponentCommand, ButtonComponentHandler, StringSelectComponentHandler, RoleSelectComponentHandler, UserSelectComponentHandler, ChannelSelectComponentHandler, MentionableSelectComponentHandler, ComponentHandler, ModalCommand, ModalHandler, InteractionHandler, } from "./clients/MiniInteraction.js";
+export { MessageComponentInteraction, ButtonInteraction, StringSelectInteraction, RoleSelectInteraction, UserSelectInteraction, ChannelSelectInteraction, MentionableSelectInteraction, ResolvedUserOption as ComponentResolvedUserOption, ResolvedMentionableOption as ComponentResolvedMentionableOption, } from "./utils/MessageComponentInteraction.js";
+export { ModalSubmitInteraction } from "./utils/ModalSubmitInteraction.js";
 export { RoleConnectionMetadataTypes } from "./types/RoleConnectionMetadataTypes.js";
 export { ChannelType } from "./types/ChannelType.js";
-export { InteractionFollowUpFlags, InteractionReplyFlags, } from "./types/InteractionFlags.js";
+export { InteractionFollowUpFlags, InteractionReplyFlags, InteractionFlags, } from "./types/InteractionFlags.js";
 export { ButtonStyle } from "./types/ButtonStyle.js";
 export { SeparatorSpacingSize } from "./types/SeparatorSpacingSize.js";
 export { TextInputStyle } from "discord-api-types/v10";
 export { MiniPermFlags } from "./types/PermissionFlags.js";
-export type { MiniComponentActionRow, MiniComponentMessageActionRow, } from "./types/ComponentTypes.js";
+export type { ActionRowComponent, MessageActionRowComponent, } from "./types/ComponentTypes.js";
 export * from "./builders/index.js";
 export { MiniDataBuilder } from "./database/MiniDataBuilder.js";
 export type { DataField } from "./database/MiniDataBuilder.js";

package/dist/index.js

@@ -3,9 +3,13 @@ export { MiniInteraction } from "./clients/MiniInteraction.js";
 export { CommandBuilder, CommandContext, IntegrationType, } from "./commands/CommandBuilder.js";
 export { UserCommandBuilder, MessageCommandBuilder, AppCommandBuilder, } from "./commands/ContextMenuCommandBuilder.js";
 export { CommandInteractionOptionResolver, createCommandInteraction, } from "./utils/CommandInteractionOptions.js";
+export { CommandInteraction, MentionableOption, ResolvedUserOption, } from "./utils/CommandInteractionOptions.js";
+export { UserContextMenuInteraction, MessageContextMenuInteraction, AppCommandInteraction, } from "./utils/ContextMenuInteraction.js";
+export { MessageComponentInteraction, ButtonInteraction, StringSelectInteraction, RoleSelectInteraction, UserSelectInteraction, ChannelSelectInteraction, MentionableSelectInteraction, ResolvedUserOption as ComponentResolvedUserOption, ResolvedMentionableOption as ComponentResolvedMentionableOption, } from "./utils/MessageComponentInteraction.js";
+export { ModalSubmitInteraction } from "./utils/ModalSubmitInteraction.js";
 export { RoleConnectionMetadataTypes } from "./types/RoleConnectionMetadataTypes.js";
 export { ChannelType } from "./types/ChannelType.js";
-export { InteractionFollowUpFlags, InteractionReplyFlags, } from "./types/InteractionFlags.js";
+export { InteractionFollowUpFlags, InteractionReplyFlags, InteractionFlags, } from "./types/InteractionFlags.js";
 export { ButtonStyle } from "./types/ButtonStyle.js";
 export { SeparatorSpacingSize } from "./types/SeparatorSpacingSize.js";
 export { TextInputStyle } from "discord-api-types/v10";

package/dist/types/Commands.d.ts

@@ -1,7 +1,8 @@
 import type { APIInteractionResponse, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIContextMenuApplicationCommandsJSONBody, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody } from "discord-api-types/v10";
 import type { CommandInteraction } from "../utils/CommandInteractionOptions.js";
 import type { UserContextMenuInteraction, MessageContextMenuInteraction, AppCommandInteraction } from "../utils/ContextMenuInteraction.js";
-import type { MiniInteractionComponent, MiniInteractionModal } from "../clients/MiniInteraction.js";
+import type { JSONEncodable } from "../builders/shared.js";
+import type { ComponentCommand, ModalCommand } from "../clients/MiniInteraction.js";
 import type { CommandBuilder } from "../commands/CommandBuilder.js";
 import type { MessageCommandBuilder, UserCommandBuilder, AppCommandBuilder } from "../commands/ContextMenuCommandBuilder.js";
 /** Handler signature for slash command executions within MiniInteraction. */
@@ -15,19 +16,19 @@ export type AppCommandHandler = (interaction: AppCommandInteraction) => Promise<
 /** Union of all command handler types. */
 export type CommandHandler = SlashCommandHandler | UserCommandHandler | MessageCommandHandler | AppCommandHandler;
 /** Structure representing a slash command definition and its runtime handler. */
-export type MiniInteractionCommand = {
-    data: RESTPostAPIChatInputApplicationCommandsJSONBody | RESTPostAPIContextMenuApplicationCommandsJSONBody | RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody | CommandBuilder | UserCommandBuilder | MessageCommandBuilder | AppCommandBuilder;
+export type InteractionCommand = {
+    data: RESTPostAPIChatInputApplicationCommandsJSONBody | RESTPostAPIContextMenuApplicationCommandsJSONBody | RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody | CommandBuilder | UserCommandBuilder | MessageCommandBuilder | AppCommandBuilder | JSONEncodable<RESTPostAPIChatInputApplicationCommandsJSONBody | RESTPostAPIContextMenuApplicationCommandsJSONBody | RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody>;
     handler: CommandHandler;
     /**
      * Optional array of component handlers related to this command.
      * These will be automatically registered when the command is loaded.
  */
-    components?: MiniInteractionComponent[];
+    components?: ComponentCommand[];
     /**
      * Optional array of modal handlers related to this command.
      * These will be automatically registered when the command is loaded.
      */
-    modals?: MiniInteractionModal[];
+    modals?: ModalCommand[];
 };
 /** Map of command names to their registered MiniInteraction command definitions. */
-export type MiniInteractionCommandsMap = Map<string, MiniInteractionCommand>;
+export type InteractionCommandsMap = Map<string, InteractionCommand>;

package/dist/types/ComponentTypes.d.ts

@@ -1,5 +1,5 @@
 import type { APIComponentInActionRow, APIComponentInMessageActionRow } from "discord-api-types/v10";
-/** * Components that can appear inside a Discord action row container. */
-export type MiniComponentMessageActionRow = APIComponentInMessageActionRow;
-/** Components that are valid inside message action rows. */
-export type MiniComponentActionRow = APIComponentInActionRow;
+/** Defines a component structure for use in ActionRow builders. */
+export type ActionRowComponent = APIComponentInActionRow;
+/** Defines a message component structure for use in message builders. */
+export type MessageActionRowComponent = APIComponentInMessageActionRow;

package/dist/types/InteractionFlags.d.ts

@@ -1,10 +1,9 @@
-/** Flags available when responding directly to an interaction. */
-export declare enum InteractionReplyFlags {
-    Ephemeral = 64,
-    IsComponentsV2 = 32768
-}
-/** Flags available when sending a follow-up message for an interaction. */
-export declare enum InteractionFollowUpFlags {
+/** Flags available for interaction responses. */
+export declare enum InteractionFlags {
     Ephemeral = 64,
     IsComponentsV2 = 32768
 }
+/** @deprecated Use InteractionFlags instead. */
+export { InteractionFlags as InteractionReplyFlags };
+/** @deprecated Use InteractionFlags instead. */
+export { InteractionFlags as InteractionFollowUpFlags };

package/dist/types/InteractionFlags.js

@@ -1,12 +1,10 @@
-/** Flags available when responding directly to an interaction. */
-export var InteractionReplyFlags;
-(function (InteractionReplyFlags) {
-    InteractionReplyFlags[InteractionReplyFlags["Ephemeral"] = 64] = "Ephemeral";
-    InteractionReplyFlags[InteractionReplyFlags["IsComponentsV2"] = 32768] = "IsComponentsV2";
-})(InteractionReplyFlags || (InteractionReplyFlags = {}));
-/** Flags available when sending a follow-up message for an interaction. */
-export var InteractionFollowUpFlags;
-(function (InteractionFollowUpFlags) {
-    InteractionFollowUpFlags[InteractionFollowUpFlags["Ephemeral"] = 64] = "Ephemeral";
-    InteractionFollowUpFlags[InteractionFollowUpFlags["IsComponentsV2"] = 32768] = "IsComponentsV2";
-})(InteractionFollowUpFlags || (InteractionFollowUpFlags = {}));
+/** Flags available for interaction responses. */
+export var InteractionFlags;
+(function (InteractionFlags) {
+    InteractionFlags[InteractionFlags["Ephemeral"] = 64] = "Ephemeral";
+    InteractionFlags[InteractionFlags["IsComponentsV2"] = 32768] = "IsComponentsV2";
+})(InteractionFlags || (InteractionFlags = {}));
+/** @deprecated Use InteractionFlags instead. */
+export { InteractionFlags as InteractionReplyFlags };
+/** @deprecated Use InteractionFlags instead. */
+export { InteractionFlags as InteractionFollowUpFlags };

package/dist/utils/CommandInteractionOptions.d.ts

@@ -4,6 +4,7 @@ export type ResolvedUserOption = {
     user: APIUser;
     member?: APIInteractionDataResolvedGuildMember;
 };
+export declare const ResolvedUserOption: {};
 export type MentionableOption = {
     type: "user";
     value: ResolvedUserOption;
@@ -11,6 +12,7 @@ export type MentionableOption = {
     type: "role";
     value: APIRole;
 };
+export declare const MentionableOption: {};
 /**
  * Provides ergonomic helpers for extracting typed command options from Discord interactions.
  */
@@ -150,11 +152,20 @@ export interface CommandInteraction extends Omit<APIChatInputApplicationCommandI
         toJSON(): APIModalInteractionResponseCallbackData;
     }): APIModalInteractionResponse;
     withTimeoutProtection<T>(operation: () => Promise<T>, deferOptions?: DeferReplyOptions): Promise<T>;
+    canRespond?(interactionId: string): boolean;
+    trackResponse?(interactionId: string, token: string, state: 'responded' | 'deferred'): void;
+    logTiming?(interactionId: string, operation: string, startTime: number, success: boolean): void;
 }
+export declare const CommandInteraction: {};
 /**
  * Wraps a raw application command interaction with helper methods and option resolvers.
  *
  * @param interaction - The raw interaction payload from Discord.
+ * @param helpers - Optional helper methods for state management and logging.
  * @returns A helper-augmented interaction object.
  */
-export declare function createCommandInteraction(interaction: APIChatInputApplicationCommandInteraction): CommandInteraction;
+export declare function createCommandInteraction(interaction: APIChatInputApplicationCommandInteraction, helpers?: {
+    canRespond?: (interactionId: string) => boolean;
+    trackResponse?: (interactionId: string, token: string, state: 'responded' | 'deferred') => void;
+    logTiming?: (interactionId: string, operation: string, startTime: number, success: boolean) => void;
+}): CommandInteraction;

package/dist/utils/CommandInteractionOptions.js

@@ -1,5 +1,7 @@
 import { ApplicationCommandOptionType, InteractionResponseType, } from "discord-api-types/v10";
 import { normaliseInteractionMessageData, normaliseMessageFlags, } from "./interactionMessageHelpers.js";
+export const ResolvedUserOption = {};
+export const MentionableOption = {};
 /** Maps application command option types to human-readable labels for error messages. */
 const OPTION_TYPE_LABEL = {
     [ApplicationCommandOptionType.Subcommand]: "subcommand",
@@ -314,13 +316,15 @@ export class CommandInteractionOptionResolver {
         return records?.[id];
     }
 }
+export const CommandInteraction = {};
 /**
  * Wraps a raw application command interaction with helper methods and option resolvers.
  *
  * @param interaction - The raw interaction payload from Discord.
+ * @param helpers - Optional helper methods for state management and logging.
  * @returns A helper-augmented interaction object.
  */
-export function createCommandInteraction(interaction) {
+export function createCommandInteraction(interaction, helpers) {
     const options = new CommandInteractionOptionResolver(interaction.data.options, interaction.data.resolved);
     let capturedResponse = null;
     /**
@@ -371,7 +375,17 @@ export function createCommandInteraction(interaction) {
             return capturedResponse;
         },
         reply(data) {
-            return createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
+            // Validate interaction can respond
+            if (!this.canRespond?.(this.id)) {
+                throw new Error('Interaction cannot respond: already responded or expired');
+            }
+            const startTime = Date.now();
+            const response = createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
+            // Track response
+            this.trackResponse?.(this.id, this.token, 'responded');
+            // Log timing if debug enabled
+            this.logTiming?.(this.id, 'reply', startTime, true);
+            return response;
         },
         followUp(data) {
             return createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
@@ -380,12 +394,32 @@ export function createCommandInteraction(interaction) {
             return createMessageResponse(InteractionResponseType.UpdateMessage, data);
         },
         editReply(data) {
-            return createMessageResponse(InteractionResponseType.UpdateMessage, data);
+            // Validate interaction can respond
+            if (!this.canRespond?.(this.id)) {
+                throw new Error('Interaction cannot edit reply: already responded, expired, or not deferred');
+            }
+            const startTime = Date.now();
+            const response = createMessageResponse(InteractionResponseType.UpdateMessage, data);
+            // Track response
+            this.trackResponse?.(this.id, this.token, 'responded');
+            // Log timing if debug enabled
+            this.logTiming?.(this.id, 'editReply', startTime, true);
+            return response;
         },
         deferReply(options) {
-            return createDeferredResponse(options?.flags !== undefined
+            // Validate interaction can respond
+            if (!this.canRespond?.(this.id)) {
+                throw new Error('Interaction cannot defer: already responded or expired');
+            }
+            const startTime = Date.now();
+            const response = createDeferredResponse(options?.flags !== undefined
                 ? { flags: options.flags }
                 : undefined);
+            // Track deferred state
+            this.trackResponse?.(this.id, this.token, 'deferred');
+            // Log timing if debug enabled
+            this.logTiming?.(this.id, 'deferReply', startTime, true);
+            return response;
         },
         showModal(data) {
             const resolvedData = typeof data === "object" &&
@@ -432,6 +466,10 @@ export function createCommandInteraction(interaction) {
                 throw error;
             }
         },
+        // Helper methods for state management
+        canRespond: helpers?.canRespond,
+        trackResponse: helpers?.trackResponse,
+        logTiming: helpers?.logTiming,
     };
     return commandInteraction;
 }

package/dist/utils/ContextMenuInteraction.d.ts

@@ -20,6 +20,7 @@ export type UserContextMenuInteraction = APIUserApplicationCommandInteraction &
     /** Resolved user targeted by this user context menu command. */
     targetUser?: APIUser;
 };
+export declare const UserContextMenuInteraction: {};
 /**
  * Message context menu interaction with helper methods.
  */
@@ -27,10 +28,12 @@ export type MessageContextMenuInteraction = APIMessageApplicationCommandInteract
     /** Resolved message targeted by this message context menu command. */
     targetMessage?: APIMessage;
 };
+export declare const MessageContextMenuInteraction: {};
 /**
  * Primary entry point interaction with helper methods.
  */
 export type AppCommandInteraction = APIPrimaryEntryPointCommandInteraction & ContextMenuInteractionHelpers;
+export declare const AppCommandInteraction: {};
 /**
  * Wraps a raw user context menu interaction with helper methods.
  *

package/dist/utils/ContextMenuInteraction.js

@@ -1,5 +1,8 @@
 import { InteractionResponseType, } from "discord-api-types/v10";
 import { normaliseInteractionMessageData, normaliseMessageFlags, } from "./interactionMessageHelpers.js";
+export const UserContextMenuInteraction = {};
+export const MessageContextMenuInteraction = {};
+export const AppCommandInteraction = {};
 function createContextMenuInteractionHelpers() {
     let capturedResponse = null;
     const captureResponse = (response) => {

package/dist/utils/MessageComponentInteraction.d.ts

@@ -5,6 +5,7 @@ export type ResolvedUserOption = {
     user: APIUser;
     member?: APIInteractionDataResolvedGuildMember;
 };
+export declare const ResolvedUserOption: {};
 /** Resolved mentionable option (either a user or role). */
 export type ResolvedMentionableOption = {
     type: "user";
@@ -13,6 +14,7 @@ export type ResolvedMentionableOption = {
     type: "role";
     value: APIRole;
 };
+export declare const ResolvedMentionableOption: {};
 /**
  * Base helper methods available on all component interactions.
  */
@@ -33,6 +35,7 @@ type BaseComponentInteractionHelpers = {
 export interface ButtonInteraction extends Omit<APIMessageComponentInteraction, "data">, BaseComponentInteractionHelpers {
     data: APIMessageButtonInteractionData;
 }
+export declare const ButtonInteraction: {};
 /**
  * String select menu interaction with helper methods.
  */
@@ -41,6 +44,7 @@ export interface StringSelectInteraction extends Omit<APIMessageComponentInterac
     values: string[];
     getStringValues: () => string[];
 }
+export declare const StringSelectInteraction: {};
 /**
  * Role select menu interaction with helper methods.
  */
@@ -49,6 +53,7 @@ export interface RoleSelectInteraction extends Omit<APIMessageComponentInteracti
     values: string[];
     getRoles: () => APIRole[];
 }
+export declare const RoleSelectInteraction: {};
 /**
  * User select menu interaction with helper methods.
  */
@@ -57,6 +62,7 @@ export interface UserSelectInteraction extends Omit<APIMessageComponentInteracti
     values: string[];
     getUsers: () => ResolvedUserOption[];
 }
+export declare const UserSelectInteraction: {};
 /**
  * Channel select menu interaction with helper methods.
  */
@@ -65,6 +71,7 @@ export interface ChannelSelectInteraction extends Omit<APIMessageComponentIntera
     values: string[];
     getChannels: () => APIInteractionDataResolvedChannel[];
 }
+export declare const ChannelSelectInteraction: {};
 /**
  * Mentionable select menu interaction with helper methods.
  */
@@ -73,6 +80,7 @@ export interface MentionableSelectInteraction extends Omit<APIMessageComponentIn
     values: string[];
     getMentionables: () => ResolvedMentionableOption[];
 }
+export declare const MentionableSelectInteraction: {};
 /**
  * Represents a component interaction augmented with helper response methods.
  *
@@ -120,6 +128,7 @@ export type MessageComponentInteraction = APIMessageComponentInteraction & {
      */
     getMentionables: () => ResolvedMentionableOption[];
 };
+export declare const MessageComponentInteraction: {};
 /**
  * Wraps a raw component interaction with helper methods mirroring Discord's expected responses.
  *

package/dist/utils/MessageComponentInteraction.js

@@ -1,5 +1,14 @@
 import { InteractionResponseType, } from "discord-api-types/v10";
 import { normaliseInteractionMessageData, normaliseMessageFlags, } from "./interactionMessageHelpers.js";
+export const ResolvedUserOption = {};
+export const ResolvedMentionableOption = {};
+export const ButtonInteraction = {};
+export const StringSelectInteraction = {};
+export const RoleSelectInteraction = {};
+export const UserSelectInteraction = {};
+export const ChannelSelectInteraction = {};
+export const MentionableSelectInteraction = {};
+export const MessageComponentInteraction = {};
 /**
  * Wraps a raw component interaction with helper methods mirroring Discord's expected responses.
  *

package/dist/utils/ModalSubmitInteraction.d.ts

@@ -19,6 +19,7 @@ export type ModalSubmitInteraction = APIModalSubmitInteraction & {
      */
     getTextInputValues: () => Map<string, string>;
 };
+export declare const ModalSubmitInteraction: {};
 /**
  * Wraps a raw modal submit interaction with helper methods.
  *

package/dist/utils/ModalSubmitInteraction.js

@@ -1,5 +1,6 @@
 import { InteractionResponseType, } from "discord-api-types/v10";
 import { normaliseInteractionMessageData, normaliseMessageFlags, } from "./interactionMessageHelpers.js";
+export const ModalSubmitInteraction = {};
 /**
  * Wraps a raw modal submit interaction with helper methods.
  *

package/dist/utils/interactionMessageHelpers.d.ts

@@ -1,10 +1,17 @@
 import type { APIInteractionResponseCallbackData, MessageFlags } from "discord-api-types/v10";
-import type { InteractionFollowUpFlags, InteractionReplyFlags } from "../types/InteractionFlags.js";
+import type { APIActionRowComponent, APIComponentInMessageActionRow, APIContainerComponent } from "discord-api-types/v10";
+import type { JSONEncodable } from "../builders/shared.js";
+import type { InteractionFlags } from "../types/InteractionFlags.js";
 /** Union of helper flag enums and raw Discord message flags. */
-export type MessageFlagLike = MessageFlags | InteractionReplyFlags | InteractionFollowUpFlags;
+export type MessageFlagLike = MessageFlags | InteractionFlags;
+/** Top-level components allowed in messages (ActionRows or Containers) */
+export type TopLevelComponent = APIActionRowComponent<APIComponentInMessageActionRow> | APIContainerComponent;
 /** Message payload accepted by helper reply/edit functions. */
-export type InteractionMessageData = Omit<APIInteractionResponseCallbackData, "flags"> & {
-    flags?: MessageFlagLike | MessageFlagLike[];
+export type InteractionMessageData = {
+    content?: string;
+    components?: TopLevelComponent[] | JSONEncodable<TopLevelComponent>[] | JSONEncodable<TopLevelComponent[]>;
+    embeds?: unknown[];
+    flags?: InteractionFlags;
 };
 /** Deferred response payload recognised by helper methods. */
 export type DeferredResponseData = {

package/dist/utils/interactionMessageHelpers.js

@@ -1,4 +1,5 @@
-import { ComponentType, MessageFlags as RawMessageFlags, } from "discord-api-types/v10";
+import { resolveJSONEncodable } from "../builders/shared.js";
+import { ComponentType, } from "discord-api-types/v10";
 const COMPONENTS_V2_TYPES = new Set([
     ComponentType.Container,
     ComponentType.Section,
@@ -37,36 +38,18 @@ export function normaliseInteractionMessageData(data) {
     if (!data) {
         return undefined;
     }
-    // Auto-convert builders to JSON
-    const normalisedComponents = data.components
-        ? data.components.map((component) => resolveComponentLike(component))
-        : undefined;
-    const normalisedEmbeds = data.embeds
-        ? data.embeds.map((embed) => resolveComponentLike(embed))
-        : undefined;
-    const usesComponentsV2 = Array.isArray(normalisedComponents)
-        ? containsComponentsV2(normalisedComponents)
-        : false;
-    const normalisedFlags = normaliseMessageFlags(data.flags);
-    const finalFlags = usesComponentsV2
-        ? ((normalisedFlags ?? 0) |
-            RawMessageFlags.IsComponentsV2)
-        : normalisedFlags;
-    const needsNormalisation = finalFlags !== data.flags ||
-        normalisedComponents !== data.components ||
-        normalisedEmbeds !== data.embeds;
-    if (!needsNormalisation) {
-        return data;
+    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+    const responseData = { ...data };
+    if (data.components) {
+        const components = resolveJSONEncodable(data.components);
+        if (Array.isArray(components)) {
+            responseData.components = components.map((c) => resolveJSONEncodable(c));
+        }
+    }
+    if (data.embeds) {
+        responseData.embeds = data.embeds.map((e) => resolveJSONEncodable(e));
     }
-    const { flags: _flags, components: _components, embeds: _embeds, ...rest } = data;
-    return {
-        ...rest,
-        ...(normalisedComponents !== undefined
-            ? { components: normalisedComponents }
-            : {}),
-        ...(normalisedEmbeds !== undefined ? { embeds: normalisedEmbeds } : {}),
-        ...(finalFlags !== undefined ? { flags: finalFlags } : {}),
-    };
+    return responseData;
 }
 function containsComponentsV2(components) {
     return components.some((component) => componentUsesComponentsV2(component));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@minesa-org/mini-interaction",
-	"version": "0.1.13",
+	"version": "0.2.0",
 	"description": "Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).",
 	"type": "module",
 	"main": "dist/index.js",