@minesa-org/mini-interaction 0.1.12 → 0.1.13

package/dist/clients/MiniInteraction.d.ts

@@ -14,6 +14,7 @@ export type MiniInteractionOptions = {
     utilsDirectory?: string | false;
     fetchImplementation?: typeof fetch;
     verifyKeyImplementation?: VerifyKeyFunction;
+    timeoutConfig?: InteractionTimeoutConfig;
 };
 /** Payload structure for role connection metadata registration. */
 export type RoleConnectionMetadataField = {
@@ -37,6 +38,15 @@ export type MiniInteractionHandlerResult = {
         error: string;
     };
 };
+/** Configuration for interaction timeout handling. */
+export type InteractionTimeoutConfig = {
+    /** Maximum time in milliseconds to wait for initial response (default: 2800ms) */
+    initialResponseTimeout?: number;
+    /** Whether to enable timeout warnings (default: true) */
+    enableTimeoutWarnings?: boolean;
+    /** Whether to force deferReply for slow operations (default: true) */
+    autoDeferSlowOperations?: boolean;
+};
 /** Handler signature invoked for Discord button interactions. */
 export type MiniInteractionButtonHandler = (interaction: ButtonInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
 /** Handler signature invoked for Discord string select menu interactions. */
@@ -147,6 +157,7 @@ export declare class MiniInteraction {
     private readonly commandsDirectory;
     private readonly componentsDirectory;
     readonly utilsDirectory: string | null;
+    private readonly timeoutConfig;
     private readonly commands;
     private readonly componentHandlers;
     private readonly modalHandlers;
@@ -160,7 +171,7 @@ 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, }: MiniInteractionOptions);
+    constructor({ applicationId, publicKey, commandsDirectory, componentsDirectory, utilsDirectory, fetchImplementation, verifyKeyImplementation, timeoutConfig, }: MiniInteractionOptions);
     private normalizeCommandData;
     private registerCommand;
     /**
@@ -260,8 +271,8 @@ export declare class MiniInteraction {
      * The following placeholders are available in the HTML file:
      * - `{{username}}`, `{{discriminator}}`, `{{user_id}}`, `{{user_tag}}`
      * - `{{access_token}}`, `{{refresh_token}}`, `{{token_type}}`, `{{scope}}`, `{{expires_at}}`
-         * - `{{state}}`
-         */
+     * - `{{state}}`
+     */
     connectedOAuthPage(filePath: string): DiscordOAuthCallbackTemplates["success"];
     /**
      * Loads an HTML file and returns an error template that can be reused for all failure cases.
@@ -277,7 +288,7 @@ export declare class MiniInteraction {
     private loadHtmlTemplate;
     /**
      * Replaces placeholder tokens in a template with escaped HTML values.
- */
+     */
     private renderHtmlTemplate;
     /**
      * Normalizes placeholder tokens to the bare key the HTML renderer expects.

package/dist/clients/MiniInteraction.js

@@ -30,6 +30,7 @@ export class MiniInteraction {
     commandsDirectory;
     componentsDirectory;
     utilsDirectory;
+    timeoutConfig;
     commands = new Map();
     componentHandlers = new Map();
     modalHandlers = new Map();
@@ -43,7 +44,7 @@ export class MiniInteraction {
     /**
      * Creates a new MiniInteraction client with optional command auto-loading and custom runtime hooks.
      */
-    constructor({ applicationId, publicKey, commandsDirectory, componentsDirectory, utilsDirectory, fetchImplementation, verifyKeyImplementation, }) {
+    constructor({ applicationId, publicKey, commandsDirectory, componentsDirectory, utilsDirectory, fetchImplementation, verifyKeyImplementation, timeoutConfig, }) {
         if (!applicationId) {
             throw new Error("[MiniInteraction] applicationId is required");
         }
@@ -70,6 +71,12 @@ export class MiniInteraction {
             utilsDirectory === false
                 ? null
                 : this.resolveUtilsDirectory(utilsDirectory);
+        this.timeoutConfig = {
+            initialResponseTimeout: 2800, // Leave 200ms buffer before Discord's 3s limit
+            enableTimeoutWarnings: true,
+            autoDeferSlowOperations: true,
+            ...timeoutConfig,
+        };
     }
     normalizeCommandData(data) {
         if (typeof data === "object" && data !== null) {
@@ -94,12 +101,14 @@ export class MiniInteraction {
             data: normalizedData,
         };
         this.commands.set(commandName, normalizedCommand);
-        if (normalizedCommand.components && Array.isArray(normalizedCommand.components)) {
+        if (normalizedCommand.components &&
+            Array.isArray(normalizedCommand.components)) {
             for (const component of normalizedCommand.components) {
                 this.useComponent(component);
             }
         }
-        if (normalizedCommand.modals && Array.isArray(normalizedCommand.modals)) {
+        if (normalizedCommand.modals &&
+            Array.isArray(normalizedCommand.modals)) {
             for (const modal of normalizedCommand.modals) {
                 this.useModal(modal);
             }
@@ -354,6 +363,7 @@ export class MiniInteraction {
      * @param request - The request payload containing headers and body data.
      */
     async handleRequest(request) {
+        const requestStartTime = Date.now();
         const { body, signature, timestamp } = request;
         if (!signature || !timestamp) {
             return {
@@ -398,6 +408,15 @@ export class MiniInteraction {
         if (interaction.type === InteractionType.ModalSubmit) {
             return this.handleModalSubmit(interaction);
         }
+        // Check total processing time
+        const totalProcessingTime = Date.now() - requestStartTime;
+        if (this.timeoutConfig.enableTimeoutWarnings &&
+            totalProcessingTime >
+                this.timeoutConfig.initialResponseTimeout * 0.9) {
+            console.warn(`[MiniInteraction] WARNING: Interaction processing took ${totalProcessingTime}ms ` +
+                `(${Math.round((totalProcessingTime / 3000) * 100)}% of Discord's 3-second limit). ` +
+                `Consider optimizing or using deferReply() for slow operations.`);
+        }
         return {
             status: 400,
             body: {
@@ -511,8 +530,8 @@ export class MiniInteraction {
      * The following placeholders are available in the HTML file:
      * - `{{username}}`, `{{discriminator}}`, `{{user_id}}`, `{{user_tag}}`
      * - `{{access_token}}`, `{{refresh_token}}`, `{{token_type}}`, `{{scope}}`, `{{expires_at}}`
-         * - `{{state}}`
-         */
+     * - `{{state}}`
+     */
     connectedOAuthPage(filePath) {
         const template = this.loadHtmlTemplate(filePath);
         return ({ user, tokens, state }) => {
@@ -569,7 +588,7 @@ export class MiniInteraction {
     }
     /**
      * Replaces placeholder tokens in a template with escaped HTML values.
- */
+     */
     renderHtmlTemplate(template, values, options) {
         const rawKeys = options?.rawKeys instanceof Set
             ? options.rawKeys
@@ -666,7 +685,9 @@ export class MiniInteraction {
                     const location = typeof options.successRedirect === "function"
                         ? options.successRedirect(authorizeContext)
                         : options.successRedirect;
-                    if (location && !response.headersSent && !response.writableEnded) {
+                    if (location &&
+                        !response.headersSent &&
+                        !response.writableEnded) {
                         response.statusCode = 302;
                         response.setHeader("location", location);
                         response.end();
@@ -1057,27 +1078,32 @@ export class MiniInteraction {
         }
         try {
             const interactionWithHelpers = createMessageComponentInteraction(interaction);
-            const response = await handler(interactionWithHelpers);
-            const resolvedResponse = response ?? interactionWithHelpers.getResponse();
-            if (!resolvedResponse) {
-                return {
-                    status: 500,
-                    body: {
-                        error: `[MiniInteraction] Component "${customId}" did not return a response. ` +
-                            "Return an APIInteractionResponse to acknowledge the interaction.",
-                    },
-                };
-            }
+            // Wrap component handler with timeout
+            const timeoutWrapper = createTimeoutWrapper(async () => {
+                const response = await handler(interactionWithHelpers);
+                const resolvedResponse = response ?? interactionWithHelpers.getResponse();
+                if (!resolvedResponse) {
+                    throw new Error(`Component "${customId}" did not return a response. ` +
+                        "Return an APIInteractionResponse to acknowledge the interaction.");
+                }
+                return resolvedResponse;
+            }, this.timeoutConfig.initialResponseTimeout, `Component "${customId}"`, this.timeoutConfig.enableTimeoutWarnings);
+            const resolvedResponse = await timeoutWrapper();
             return {
                 status: 200,
                 body: resolvedResponse,
             };
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("Handler timeout")) {
+                console.error(`[MiniInteraction] CRITICAL: Component "${customId}" timed out. ` +
+                    `This will result in "didn't respond in time" errors for users.`);
+            }
             return {
                 status: 500,
                 body: {
-                    error: `[MiniInteraction] Component "${customId}" failed: ${String(error)}`,
+                    error: `[MiniInteraction] Component "${customId}" failed: ${errorMessage}`,
                 },
             };
         }
@@ -1107,27 +1133,32 @@ export class MiniInteraction {
         }
         try {
             const interactionWithHelpers = createModalSubmitInteraction(interaction);
-            const response = await handler(interactionWithHelpers);
-            const resolvedResponse = response ?? interactionWithHelpers.getResponse();
-            if (!resolvedResponse) {
-                return {
-                    status: 500,
-                    body: {
-                        error: `[MiniInteraction] Modal "${customId}" did not return a response. ` +
-                            "Return an APIInteractionResponse to acknowledge the interaction.",
-                    },
-                };
-            }
+            // Wrap modal handler with timeout
+            const timeoutWrapper = createTimeoutWrapper(async () => {
+                const response = await handler(interactionWithHelpers);
+                const resolvedResponse = response ?? interactionWithHelpers.getResponse();
+                if (!resolvedResponse) {
+                    throw new Error(`Modal "${customId}" did not return a response. ` +
+                        "Return an APIInteractionResponse to acknowledge the interaction.");
+                }
+                return resolvedResponse;
+            }, this.timeoutConfig.initialResponseTimeout, `Modal "${customId}"`, this.timeoutConfig.enableTimeoutWarnings);
+            const resolvedResponse = await timeoutWrapper();
             return {
                 status: 200,
                 body: resolvedResponse,
             };
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("Handler timeout")) {
+                console.error(`[MiniInteraction] CRITICAL: Modal "${customId}" timed out. ` +
+                    `This will result in "didn't respond in time" errors for users.`);
+            }
             return {
                 status: 500,
                 body: {
-                    error: `[MiniInteraction] Modal "${customId}" failed: ${String(error)}`,
+                    error: `[MiniInteraction] Modal "${customId}" failed: ${errorMessage}`,
                 },
             };
         }
@@ -1159,41 +1190,50 @@ export class MiniInteraction {
         try {
             let response;
             let resolvedResponse = null;
-            // Check if it's a chat input (slash) command
-            if (commandInteraction.data.type ===
-                ApplicationCommandType.ChatInput) {
-                const interactionWithHelpers = createCommandInteraction(commandInteraction);
-                response = await command.handler(interactionWithHelpers);
-                resolvedResponse =
-                    response ?? interactionWithHelpers.getResponse();
-            }
-            else if (commandInteraction.data.type === ApplicationCommandType.User) {
-                // User context menu command
-                const interactionWithHelpers = createUserContextMenuInteraction(commandInteraction);
-                response = await command.handler(interactionWithHelpers);
-                resolvedResponse =
-                    response ?? interactionWithHelpers.getResponse();
-            }
-            else if (commandInteraction.data.type ===
-                ApplicationCommandType.PrimaryEntryPoint) {
-                const interactionWithHelpers = createAppCommandInteraction(commandInteraction);
-                response = await command.handler(interactionWithHelpers);
-                resolvedResponse =
-                    response ?? interactionWithHelpers.getResponse();
-            }
-            else if (commandInteraction.data.type === ApplicationCommandType.Message) {
-                // Message context menu command
-                const interactionWithHelpers = createMessageContextMenuInteraction(commandInteraction);
-                response = await command.handler(interactionWithHelpers);
-                resolvedResponse =
-                    response ?? interactionWithHelpers.getResponse();
-            }
-            else {
-                // Unknown command type
-                response = await command.handler(commandInteraction);
-                resolvedResponse = response ?? null;
-            }
+            // Create a timeout wrapper for the command handler
+            const timeoutWrapper = createTimeoutWrapper(async () => {
+                // Check if it's a chat input (slash) command
+                if (commandInteraction.data.type ===
+                    ApplicationCommandType.ChatInput) {
+                    const interactionWithHelpers = createCommandInteraction(commandInteraction);
+                    response = await command.handler(interactionWithHelpers);
+                    resolvedResponse =
+                        response ?? interactionWithHelpers.getResponse();
+                }
+                else if (commandInteraction.data.type ===
+                    ApplicationCommandType.User) {
+                    // User context menu command
+                    const interactionWithHelpers = createUserContextMenuInteraction(commandInteraction);
+                    response = await command.handler(interactionWithHelpers);
+                    resolvedResponse =
+                        response ?? interactionWithHelpers.getResponse();
+                }
+                else if (commandInteraction.data.type ===
+                    ApplicationCommandType.PrimaryEntryPoint) {
+                    const interactionWithHelpers = createAppCommandInteraction(commandInteraction);
+                    response = await command.handler(interactionWithHelpers);
+                    resolvedResponse =
+                        response ?? interactionWithHelpers.getResponse();
+                }
+                else if (commandInteraction.data.type ===
+                    ApplicationCommandType.Message) {
+                    // Message context menu command
+                    const interactionWithHelpers = createMessageContextMenuInteraction(commandInteraction);
+                    response = await command.handler(interactionWithHelpers);
+                    resolvedResponse =
+                        response ?? interactionWithHelpers.getResponse();
+                }
+                else {
+                    // Unknown command type
+                    response = await command.handler(commandInteraction);
+                    resolvedResponse = response ?? null;
+                }
+            }, this.timeoutConfig.initialResponseTimeout, `Command "${commandName}"`, this.timeoutConfig.enableTimeoutWarnings);
+            await timeoutWrapper();
             if (!resolvedResponse) {
+                console.error(`[MiniInteraction] Command "${commandName}" did not return a response. ` +
+                    "This indicates the handler completed but no response was generated. " +
+                    "Check that deferReply(), reply(), showModal(), or a direct response is returned.");
                 return {
                     status: 500,
                     body: {
@@ -1209,10 +1249,18 @@ export class MiniInteraction {
             };
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Check if this was a timeout error
+            if (errorMessage.includes("Handler timeout")) {
+                console.error(`[MiniInteraction] CRITICAL: Command "${commandName}" timed out before responding to Discord. ` +
+                    `This will result in "didn't respond in time" errors for users. ` +
+                    `Handler took longer than ${this.timeoutConfig.initialResponseTimeout}ms to complete. ` +
+                    `Consider using deferReply() for operations that take more than 3 seconds.`);
+            }
             return {
                 status: 500,
                 body: {
-                    error: `[MiniInteraction] Command "${commandName}" failed: ${String(error)}`,
+                    error: `[MiniInteraction] Command "${commandName}" failed: ${errorMessage}`,
                 },
             };
         }
@@ -1382,3 +1430,45 @@ function resolveOAuthConfig(provided) {
         redirectUri,
     };
 }
+/**
+ * Wraps a handler function with timeout detection and error handling.
+ */
+function createTimeoutWrapper(handler, timeoutMs, handlerName, enableWarnings = true) {
+    return async (...args) => {
+        const startTime = Date.now();
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                const elapsed = Date.now() - startTime;
+                console.error(`[MiniInteraction] ${handlerName} timed out after ${elapsed}ms (limit: ${timeoutMs}ms)`);
+                reject(new Error(`Handler timeout: ${handlerName} exceeded ${timeoutMs}ms limit`));
+            }, timeoutMs);
+        });
+        try {
+            const result = await Promise.race([
+                Promise.resolve(handler(...args)),
+                timeoutPromise,
+            ]);
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            const elapsed = Date.now() - startTime;
+            if (enableWarnings && elapsed > timeoutMs * 0.8) {
+                console.warn(`[MiniInteraction] ${handlerName} completed in ${elapsed}ms (${Math.round((elapsed / timeoutMs) * 100)}% of timeout limit)`);
+            }
+            return result;
+        }
+        catch (error) {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            // Re-throw the error with additional context
+            if (error instanceof Error &&
+                error.message.includes("Handler timeout")) {
+                throw error;
+            }
+            console.error(`[MiniInteraction] ${handlerName} failed:`, error);
+            throw error;
+        }
+    };
+}

package/dist/utils/CommandInteractionOptions.d.ts

@@ -149,6 +149,7 @@ export interface CommandInteraction extends Omit<APIChatInputApplicationCommandI
     showModal(data: APIModalInteractionResponseCallbackData | {
         toJSON(): APIModalInteractionResponseCallbackData;
     }): APIModalInteractionResponse;
+    withTimeoutProtection<T>(operation: () => Promise<T>, deferOptions?: DeferReplyOptions): Promise<T>;
 }
 /**
  * Wraps a raw application command interaction with helper methods and option resolvers.

package/dist/utils/CommandInteractionOptions.js

@@ -398,6 +398,40 @@ export function createCommandInteraction(interaction) {
                 data: resolvedData,
             });
         },
+        /**
+         * Creates a delayed response wrapper that automatically defers if the operation takes too long.
+         * Use this for operations that might exceed Discord's 3-second limit.
+         *
+         * @param operation - The async operation to perform
+         * @param deferOptions - Options for automatic deferral
+         */
+        async withTimeoutProtection(operation, deferOptions) {
+            const startTime = Date.now();
+            let deferred = false;
+            // Set up a timer to auto-defer after 2.5 seconds
+            const deferTimer = setTimeout(async () => {
+                if (!deferred) {
+                    console.warn("[MiniInteraction] Auto-deferring interaction due to slow operation. " +
+                        "Consider using deferReply() explicitly for better user experience.");
+                    this.deferReply(deferOptions);
+                    deferred = true;
+                }
+            }, 2500);
+            try {
+                const result = await operation();
+                clearTimeout(deferTimer);
+                const elapsed = Date.now() - startTime;
+                if (elapsed > 2000 && !deferred) {
+                    console.warn(`[MiniInteraction] Operation completed in ${elapsed}ms. ` +
+                        "Consider using deferReply() for operations > 2 seconds.");
+                }
+                return result;
+            }
+            catch (error) {
+                clearTimeout(deferTimer);
+                throw error;
+            }
+        },
     };
     return commandInteraction;
 }

package/package.json

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