@minesa-org/mini-interaction 0.1.12 → 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;
@@ -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 = {
@@ -25,36 +26,56 @@ 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;
     };
 };
+/** 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;
+    /** 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.
@@ -63,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;
@@ -147,10 +168,12 @@ 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;
     private readonly htmlTemplateCache;
+    private readonly interactionStates;
     private commandsLoaded;
     private loadCommandsPromise;
     private componentsLoaded;
@@ -160,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, }: 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;
     /**
@@ -168,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.
      *
@@ -234,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.
      *
@@ -253,15 +321,15 @@ 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.
      *
      * 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 +345,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.
@@ -289,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.
      */