@minesa-org/mini-interaction 0.2.10 → 0.2.12

package/dist/utils/CommandInteractionOptions.d.ts

@@ -13,130 +13,32 @@ export type MentionableOption = {
     value: APIRole;
 };
 export declare const MentionableOption: {};
-/**
- * Provides ergonomic helpers for extracting typed command options from Discord interactions.
- */
 export declare class CommandInteractionOptionResolver {
     readonly raw: ReadonlyArray<APIApplicationCommandInteractionDataOption>;
     private readonly resolved;
     private readonly focusedOptions;
     private readonly subcommand;
     private readonly subcommandGroup;
-    /**
-     * Creates a new resolver from raw interaction options.
-     *
-     * @param options - The raw options provided by Discord.
-     * @param resolved - The resolved data map included with the interaction payload.
-     */
     constructor(options: APIApplicationCommandInteractionDataOption[] | undefined, resolved: APIInteractionDataResolved | undefined);
-    /**
-     * Retrieves the subcommand invoked by the user.
-     *
-     * @param required - Whether to throw when the subcommand is missing.
-     */
     getSubcommand(required?: boolean): string | null;
-    /**
-     * Retrieves the subcommand group invoked by the user.
-     *
-     * @param required - Whether to throw when the subcommand group is missing.
-     */
     getSubcommandGroup(required?: boolean): string | null;
-    /**
-     * Looks up a string option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getString(name: string, required?: boolean): string | null;
-    /**
-     * Looks up an integer option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getInteger(name: string, required?: boolean): number | null;
-    /**
-     * Looks up a numeric option by name.
-     *
-     * @param name - The option name to resolve.
-     */
     getNumber(name: string, required?: boolean): number | null;
-    /**
-     * Looks up a boolean option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getBoolean(name: string, required?: boolean): boolean | null;
-    /**
-     * Resolves a user option, including any guild member payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getUser(name: string, required?: boolean): ResolvedUserOption | null;
-    /**
-     * Resolves a role option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getRole(name: string, required?: boolean): APIRole | null;
-    /**
-     * Resolves a channel option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getChannel(name: string, required?: boolean): APIInteractionDataResolvedChannel | null;
-    /**
-     * Resolves an attachment option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getAttachment(name: string, required?: boolean): APIAttachment | null;
-    /**
-     * Resolves a mentionable option to either a role or user payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getMentionable(name: string, required?: boolean): MentionableOption | null;
-    /**
-     * Returns the raw option payload, bypassing type checks and casting.
-     *
-     * @param name - The option name to look up.
-     */
     getRawOption(name: string): APIApplicationCommandInteractionDataOption | null;
-    /**
-     * Extracts a strongly typed option, ensuring it exists and matches the expected type.
-     */
     private extractOption;
-    /**
-     * Resolves an attachment by identifier from the interaction's resolved payloads.
-     */
     private resolveAttachment;
-    /**
-     * Resolves a channel by identifier from the interaction's resolved payloads.
-     */
     private resolveChannel;
-    /**
-     * Resolves a role by identifier from the interaction's resolved payloads.
-     */
     private resolveRole;
-    /**
-     * Resolves a user and optional member by identifier from the interaction's resolved payloads.
-     */
     private resolveUser;
-    /**
-     * Retrieves a record from a resolved payload map by identifier.
-     */
     private getResolvedRecord;
 }
-/**
- * Represents a command interaction augmented with helper methods for easy responses.
- */
 export interface CommandInteraction extends Omit<APIChatInputApplicationCommandInteraction, "data"> {
     data: Omit<APIChatInputApplicationCommandInteraction["data"], "options"> & {
         options: CommandInteractionOptionResolver;
@@ -144,9 +46,9 @@ export interface CommandInteraction extends Omit<APIChatInputApplicationCommandI
     options: CommandInteractionOptionResolver;
     getResponse(): APIInteractionResponse | null;
     reply(data: InteractionMessageData): APIInteractionResponseChannelMessageWithSource;
-    followUp(data: InteractionMessageData): Promise<APIInteractionResponseChannelMessageWithSource>;
+    followUp(data: InteractionMessageData): Promise<void>;
     edit(data?: InteractionMessageData): APIInteractionResponseUpdateMessage;
-    editReply(data?: InteractionMessageData): Promise<APIInteractionResponseChannelMessageWithSource | APIInteractionResponseUpdateMessage>;
+    editReply(data?: InteractionMessageData): Promise<void>;
     deferReply(options?: DeferReplyOptions): APIInteractionResponseDeferredChannelMessageWithSource;
     showModal(data: APIModalInteractionResponseCallbackData | {
         toJSON(): APIModalInteractionResponseCallbackData;
@@ -158,13 +60,6 @@ export interface CommandInteraction extends Omit<APIChatInputApplicationCommandI
     sendFollowUp?(token: string, response: APIInteractionResponse, messageId?: string): Promise<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, helpers?: {
     canRespond?: (interactionId: string) => boolean;
     trackResponse?: (interactionId: string, token: string, state: 'responded' | 'deferred') => void;

package/dist/utils/CommandInteractionOptions.js

@@ -1,8 +1,7 @@
-import { ApplicationCommandOptionType, InteractionResponseType, InteractionType, } from "discord-api-types/v10";
+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",
     [ApplicationCommandOptionType.SubcommandGroup]: "subcommand group",
@@ -16,28 +15,12 @@ const OPTION_TYPE_LABEL = {
     [ApplicationCommandOptionType.Number]: "number",
     [ApplicationCommandOptionType.Attachment]: "attachment",
 };
-/**
- * Determines whether the provided option represents a subcommand.
- *
- * @param option - The option to inspect.
- */
 function isSubcommandOption(option) {
     return option.type === ApplicationCommandOptionType.Subcommand;
 }
-/**
- * Determines whether the provided option represents a subcommand group.
- *
- * @param option - The option to inspect.
- */
 function isSubcommandGroupOption(option) {
     return option.type === ApplicationCommandOptionType.SubcommandGroup;
 }
-/**
- * Extracts the most relevant option set from the raw command options hierarchy.
- *
- * @param options - The raw options array from the interaction payload.
- * @returns The resolved subcommand context and focused options for convenience accessors.
- */
 function resolveFocusedOptions(options) {
     if (!options || options.length === 0) {
         return { subcommandGroup: null, subcommand: null, options: [] };
@@ -71,21 +54,12 @@ function resolveFocusedOptions(options) {
         options: options,
     };
 }
-/**
- * Provides ergonomic helpers for extracting typed command options from Discord interactions.
- */
 export class CommandInteractionOptionResolver {
     raw;
     resolved;
     focusedOptions;
     subcommand;
     subcommandGroup;
-    /**
-     * Creates a new resolver from raw interaction options.
-     *
-     * @param options - The raw options provided by Discord.
-     * @param resolved - The resolved data map included with the interaction payload.
-     */
     constructor(options, resolved) {
         this.raw = Object.freeze([...(options ?? [])]);
         this.resolved = resolved;
@@ -94,11 +68,6 @@ export class CommandInteractionOptionResolver {
         this.subcommand = focused.subcommand;
         this.subcommandGroup = focused.subcommandGroup;
     }
-    /**
-     * Retrieves the subcommand invoked by the user.
-     *
-     * @param required - Whether to throw when the subcommand is missing.
-     */
     getSubcommand(required = true) {
         if (this.subcommand) {
             return this.subcommand;
@@ -108,11 +77,6 @@ export class CommandInteractionOptionResolver {
         }
         return null;
     }
-    /**
-     * Retrieves the subcommand group invoked by the user.
-     *
-     * @param required - Whether to throw when the subcommand group is missing.
-     */
     getSubcommandGroup(required = true) {
         if (this.subcommandGroup) {
             return this.subcommandGroup;
@@ -122,51 +86,22 @@ export class CommandInteractionOptionResolver {
         }
         return null;
     }
-    /**
-     * Looks up a string option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getString(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.String, required);
         return option ? option.value : null;
     }
-    /**
-     * Looks up an integer option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getInteger(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Integer, required);
         return option ? option.value : null;
     }
-    /**
-     * Looks up a numeric option by name.
-     *
-     * @param name - The option name to resolve.
-     */
     getNumber(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Number, required);
         return option ? option.value : null;
     }
-    /**
-     * Looks up a boolean option by name.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing.
-     */
     getBoolean(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Boolean, required);
         return option ? option.value : null;
     }
-    /**
-     * Resolves a user option, including any guild member payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getUser(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.User, required);
         if (!option) {
@@ -181,12 +116,6 @@ export class CommandInteractionOptionResolver {
         }
         return resolvedUser;
     }
-    /**
-     * Resolves a role option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getRole(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Role, required);
         if (!option) {
@@ -198,12 +127,6 @@ export class CommandInteractionOptionResolver {
         }
         return role ?? null;
     }
-    /**
-     * Resolves a channel option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getChannel(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Channel, required);
         if (!option) {
@@ -215,12 +138,6 @@ export class CommandInteractionOptionResolver {
         }
         return channel ?? null;
     }
-    /**
-     * Resolves an attachment option to its resolved payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getAttachment(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Attachment, required);
         if (!option) {
@@ -232,12 +149,6 @@ export class CommandInteractionOptionResolver {
         }
         return attachment ?? null;
     }
-    /**
-     * Resolves a mentionable option to either a role or user payload.
-     *
-     * @param name - The option name to resolve.
-     * @param required - Whether to throw when the option is missing or cannot be resolved.
-     */
     getMentionable(name, required = false) {
         const option = this.extractOption(name, ApplicationCommandOptionType.Mentionable, required);
         if (!option) {
@@ -256,17 +167,9 @@ export class CommandInteractionOptionResolver {
         }
         return null;
     }
-    /**
-     * Returns the raw option payload, bypassing type checks and casting.
-     *
-     * @param name - The option name to look up.
-     */
     getRawOption(name) {
         return (this.focusedOptions.find((option) => option.name === name) ?? null);
     }
-    /**
-     * Extracts a strongly typed option, ensuring it exists and matches the expected type.
-     */
     extractOption(name, type, required) {
         const option = this.focusedOptions.find((candidate) => candidate.name === name);
         if (!option) {
@@ -280,27 +183,15 @@ export class CommandInteractionOptionResolver {
         }
         return option;
     }
-    /**
-     * Resolves an attachment by identifier from the interaction's resolved payloads.
-     */
     resolveAttachment(id) {
         return this.getResolvedRecord(this.resolved?.attachments, id);
     }
-    /**
-     * Resolves a channel by identifier from the interaction's resolved payloads.
-     */
     resolveChannel(id) {
         return this.getResolvedRecord(this.resolved?.channels, id);
     }
-    /**
-     * Resolves a role by identifier from the interaction's resolved payloads.
-     */
     resolveRole(id) {
         return this.getResolvedRecord(this.resolved?.roles, id);
     }
-    /**
-     * Resolves a user and optional member by identifier from the interaction's resolved payloads.
-     */
     resolveUser(id) {
         const user = this.getResolvedRecord(this.resolved?.users, id);
         if (!user) {
@@ -309,29 +200,16 @@ export class CommandInteractionOptionResolver {
         const member = this.getResolvedRecord(this.resolved?.members, id);
         return { user, member: member ?? undefined };
     }
-    /**
-     * Retrieves a record from a resolved payload map by identifier.
-     */
     getResolvedRecord(records, id) {
         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, helpers) {
     const options = new CommandInteractionOptionResolver(interaction.data.options, interaction.data.resolved);
     let capturedResponse = null;
     let isDeferred = false;
     let hasResponded = false;
-    /**
-     * Stores the most recent response helper payload for later retrieval.
-     */
     const captureResponse = (response) => {
         capturedResponse = response;
         return response;
@@ -352,9 +230,6 @@ export function createCommandInteraction(interaction, helpers) {
         }
         return captureResponse({ type });
     }
-    /**
-     * Creates a deferred response while normalising any helper flag values.
-     */
     const createDeferredResponse = (data) => {
         if (!data) {
             return captureResponse({
@@ -377,70 +252,58 @@ export function createCommandInteraction(interaction, helpers) {
             return capturedResponse;
         },
         reply(data) {
-            // Validate interaction can respond
-            if (!this.canRespond?.(this.id)) {
+            if (this.canRespond && !this.canRespond(this.id)) {
                 throw new Error('Interaction cannot respond: already responded or expired');
             }
             const response = createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
-            // Track response
             this.trackResponse?.(this.id, this.token, 'responded');
             hasResponded = true;
-            // Notify acknowledgment
             this.onAck?.(response);
             return response;
         },
         async followUp(data) {
-            const response = createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
+            const normalisedData = normaliseInteractionMessageData(data);
+            if (!normalisedData) {
+                throw new Error('[MiniInteraction] followUp requires data');
+            }
+            const response = {
+                type: InteractionResponseType.ChannelMessageWithSource,
+                data: normalisedData,
+            };
             if (this.sendFollowUp) {
-                // Empty string for messageId means a new follow-up (POST)
                 await this.sendFollowUp(this.token, response, '');
             }
-            return response;
         },
         edit(data) {
             return createMessageResponse(InteractionResponseType.UpdateMessage, data);
         },
         async editReply(data) {
-            // Validate interaction can respond
-            if (!this.canRespond?.(this.id)) {
+            if (this.canRespond && !this.canRespond(this.id)) {
                 throw new Error('Interaction cannot edit reply: expired');
             }
-            // Slash commands (type 2) MUST use ChannelMessageWithSource (type 4) for their initial response,
-            // or UpdateMessage (type 7) if they are updating a component interaction message.
-            // However, for as-yet-unresponded slash commands, we need type 4.
-            const interactionAny = interaction;
-            const isComponent = interactionAny.type === InteractionType.MessageComponent;
-            let response;
-            if (isComponent) {
-                response = createMessageResponse(InteractionResponseType.UpdateMessage, data);
-            }
-            else {
-                response = createMessageResponse(InteractionResponseType.ChannelMessageWithSource, data);
+            const normalisedData = normaliseInteractionMessageData(data);
+            if (!normalisedData) {
+                throw new Error('[MiniInteraction] editReply requires data');
             }
-            // If it's already deferred or responded, we MUST use a webhook
-            if (this.sendFollowUp && (isDeferred || hasResponded)) {
+            const response = {
+                type: InteractionResponseType.ChannelMessageWithSource,
+                data: normalisedData,
+            };
+            if (this.sendFollowUp) {
                 await this.sendFollowUp(this.token, response, '@original');
-                // If we already sent an ACK (like a DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE), 
-                // we return the original captured response to avoid sending type 4/7 back to the initial POST.
-                return capturedResponse;
             }
-            // Track response
             this.trackResponse?.(this.id, this.token, 'responded');
             hasResponded = true;
-            return response;
         },
         deferReply(options) {
-            // Validate interaction can respond
-            if (!this.canRespond?.(this.id)) {
+            if (this.canRespond && !this.canRespond(this.id)) {
                 throw new Error('Interaction cannot defer: already responded or expired');
             }
             const response = createDeferredResponse(options?.flags !== undefined
                 ? { flags: options.flags }
                 : undefined);
-            // Track deferred state
             this.trackResponse?.(this.id, this.token, 'deferred');
             isDeferred = true;
-            // Notify acknowledgment
             this.onAck?.(response);
             return response;
         },
@@ -455,17 +318,9 @@ export function createCommandInteraction(interaction, helpers) {
                 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. " +
@@ -489,7 +344,6 @@ export function createCommandInteraction(interaction, helpers) {
                 throw error;
             }
         },
-        // Helper methods for state management
         canRespond: helpers?.canRespond,
         trackResponse: helpers?.trackResponse,
         onAck: helpers?.onAck,

package/package.json

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