@minesa-org/mini-interaction 0.1.12 → 0.2.0

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.
  */
@@ -149,11 +151,21 @@ export interface CommandInteraction extends Omit<APIChatInputApplicationCommandI
     showModal(data: APIModalInteractionResponseCallbackData | {
         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" &&
@@ -398,6 +432,44 @@ 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;
+            }
+        },
+        // 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.12",
+	"version": "0.2.0",
 	"description": "Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).",
 	"type": "module",
 	"main": "dist/index.js",