@minesa-org/mini-interaction 0.4.0 → 0.4.3

package/dist/clients/MiniInteraction.d.ts

@@ -1,441 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { APIInteractionResponse, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIContextMenuApplicationCommandsJSONBody, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody } from "discord-api-types/v10";
-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 InteractionClientOptions = {
-    applicationId?: string;
-    publicKey?: string;
-    commandsDirectory?: string | false;
-    componentsDirectory?: string | false;
-    utilsDirectory?: string | false;
-    debug?: boolean;
-    fetchImplementation?: typeof fetch;
-    verifyKeyImplementation?: VerifyKeyFunction;
-    timeoutConfig?: InteractionTimeoutConfig;
-};
-/** Payload structure for role connection metadata registration. */
-export type RoleConnectionMetadataField = {
-    key: string;
-    name: string;
-    description: string;
-    type: RoleConnectionMetadataTypes;
-};
-/**
- * HTTP request information needed to validate and handle Discord interaction payloads.
- */
-export type InteractionRequest = {
-    body: string | Uint8Array;
-    signature?: string;
-    timestamp?: string;
-};
-/** Result payload returned by request handlers when processing an interaction. */
-export type InteractionHandlerResult = {
-    status: number;
-    body: APIInteractionResponse | {
-        error: string;
-    };
-    /**
-     * Promise that resolves when all background work (like editReply) completes.
-     * Pass this to Vercel's waitUntil() to prevent premature termination.
-     *
-     * @example
-     * ```typescript
-     * // In Next.js App Router
-     * import { waitUntil } from '@vercel/functions';
-     *
-     * export async function POST(request: Request) {
-     *   const result = await client.handleRequest({ ... });
-     *   if (result.backgroundWork) {
-     *     waitUntil(result.backgroundWork);
-     *   }
-     *   return Response.json(result.body, { status: result.status });
-     * }
-     * ```
-     */
-    backgroundWork?: Promise<void>;
-};
-/** 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;
-};
-/** Handler signature invoked for Discord button interactions. */
-export type ButtonComponentHandler = (interaction: ButtonInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord string select menu interactions. */
-export type StringSelectComponentHandler = (interaction: StringSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord role select menu interactions. */
-export type RoleSelectComponentHandler = (interaction: RoleSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord user select menu interactions. */
-export type UserSelectComponentHandler = (interaction: UserSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord channel select menu interactions. */
-export type ChannelSelectComponentHandler = (interaction: ChannelSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord mentionable select menu interactions. */
-export type MentionableSelectComponentHandler = (interaction: MentionableSelectInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord message component interactions (generic). */
-export type ComponentHandler = (interaction: MessageComponentInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Handler signature invoked for Discord modal submit interactions. */
-export type ModalHandler = (interaction: ModalSubmitInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
-/** Unified handler signature that accepts any component or modal interaction. */
-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.
- * When auto-loading from the components directory:
- * - Files in `components/modals/` are treated as modal handlers
- * - 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 ComponentCommand = {
-    customId: string;
-    handler: InteractionHandler;
-};
-/** Structure describing a modal handler mapped to a custom id. */
-export type ModalCommand = {
-    customId: string;
-    handler: ModalHandler;
-};
-/** Node.js HTTP handler compatible with frameworks like Express or Next.js API routes. */
-export type InteractionNodeHandler = (request: IncomingMessage, response: ServerResponse) => void;
-/** Web Fetch API compatible request handler for platforms such as Cloudflare Workers. */
-export type InteractionFetchHandler = (request: Request) => Promise<Response>;
-/** Context passed to OAuth success handlers and templates. */
-export type DiscordOAuthAuthorizeContext = {
-    tokens: OAuthTokens;
-    user: DiscordUser;
-    state: string | null;
-    request: IncomingMessage;
-    response: ServerResponse;
-};
-/** Context provided to templates that only need access to the state value. */
-export type DiscordOAuthStateTemplateContext = {
-    state: string | null;
-};
-/** Context provided to templates that display OAuth error messages. */
-export type DiscordOAuthErrorTemplateContext = DiscordOAuthStateTemplateContext & {
-    error: string;
-};
-/** Context provided to templates used for successful authorisation messages. */
-export type DiscordOAuthSuccessTemplateContext = DiscordOAuthStateTemplateContext & {
-    user: DiscordUser;
-    tokens: OAuthTokens;
-};
-/** Context provided to templates that handle server side failures. */
-export type DiscordOAuthServerErrorTemplateContext = DiscordOAuthStateTemplateContext;
-/** Template functions used to render HTML responses during the OAuth flow. */
-export type DiscordOAuthCallbackTemplates = {
-    success: (context: DiscordOAuthSuccessTemplateContext) => string;
-    missingCode: (context: DiscordOAuthStateTemplateContext) => string;
-    oauthError: (context: DiscordOAuthErrorTemplateContext) => string;
-    invalidState: (context: DiscordOAuthStateTemplateContext) => string;
-    serverError: (context: DiscordOAuthServerErrorTemplateContext) => string;
-};
-/** Options accepted by {@link MiniInteraction.discordOAuthCallback}. */
-export type DiscordOAuthCallbackOptions = {
-    oauth?: OAuthConfig;
-    onAuthorize?: (context: DiscordOAuthAuthorizeContext) => Promise<void> | void;
-    validateState?: (state: string | null, request: IncomingMessage) => Promise<boolean> | boolean;
-    successRedirect?: string | ((context: DiscordOAuthAuthorizeContext) => string | null | undefined);
-    templates?: Partial<DiscordOAuthCallbackTemplates>;
-};
-/** Options accepted by {@link MiniInteraction.discordOAuthVerificationPage}. */
-export type DiscordOAuthVerificationPageOptions = {
-    oauth?: OAuthConfig;
-    scopes?: string[];
-    /**
-     * Path to the HTML file to load. Relative paths resolve from {@link process.cwd}.
-     *
-     * @defaultValue "index.html"
-     */
-    htmlFile?: string;
-    /**
-     * Placeholder token (with or without the `{{ }}` wrapper) that will be replaced with the generated OAuth URL.
-     *
-     * @defaultValue "OAUTH_URL"
-     */
-    placeholder?: string;
-};
-/**
- * Minimal interface describing a function capable of verifying Discord interaction signatures.
- */
-type VerifyKeyFunction = (message: string | Uint8Array, signature: string, timestamp: string, publicKey: string) => boolean | Promise<boolean>;
-/**
- * Lightweight client for registering, loading, and handling Discord slash command interactions.
- */
-export declare class MiniInteraction {
-    readonly applicationId: string;
-    readonly publicKey: string;
-    private readonly fetchImpl;
-    private readonly verifyKeyImpl;
-    private readonly commandsDirectory;
-    private readonly componentsDirectory;
-    readonly utilsDirectory: string | null;
-    private readonly debug;
-    private readonly timeoutConfig;
-    private readonly commands;
-    private readonly componentHandlers;
-    private readonly modalHandlers;
-    private readonly htmlTemplateCache;
-    private readonly interactionStates;
-    private commandsLoaded;
-    private loadCommandsPromise;
-    private componentsLoaded;
-    private loadComponentsPromise;
-    private registerCommandsPromise;
-    private registerCommandsSignature;
-    private vercelWaitUntil;
-    private searchedForVercel;
-    /**
-     * Creates a new MiniInteraction client with optional command auto-loading and custom runtime hooks.
-     */
-    constructor(options?: InteractionClientOptions);
-    private log;
-    private trackInteractionState;
-    /**
-     * Checks if an interaction can still respond (not expired and not already responded).
-     */
-    private canRespond;
-    /**
-     * Gets the current state of an interaction.
-     */
-    private getInteractionState;
-    /**
-     * Clears expired interaction states to prevent memory leaks.
-     * Call this periodically to clean up old interaction data.
-     */
-    cleanupExpiredInteractions(): number;
-    /**
-     * Attempt to find a waitUntil implementation in the environment (e.g. Vercel or Cloudflare).
-     */
-    private getAutoWaitUntil;
-    private normalizeCommandData;
-    private registerCommand;
-    /**
-     * Registers a single command handler with the client.
-     *
-     * @param command - The command definition to register.
-     */
-    useCommand(command: InteractionCommand): this;
-    /**
-     * Registers multiple command handlers with the client.
-     *
-     * @param commands - The command definitions to register.
-     */
-    useCommands(commands: InteractionCommand[]): this;
-    /**
-     * Registers a single component handler mapped to a custom identifier.
-     *
-     * @param component - The component definition to register.
-     */
-    useComponent(component: ComponentCommand): this;
-    /**
-     * Registers multiple component handlers in a single call.
-     *
-     * @param components - The component definitions to register.
-     */
-    useComponents(components: ComponentCommand[]): this;
-    /**
-     * Registers a single modal handler mapped to a custom identifier.
-     *
-     * @param modal - The modal definition to register.
-     */
-    useModal(modal: ModalCommand): this;
-    /**
-     * Registers multiple modal handlers in a single call.
-     *
-     * @param modals - The modal definitions to register.
-     */
-    useModals(modals: ModalCommand[]): this;
-    /**
-     * Recursively loads components from the configured components directory.
-     *
-     * @param directory - Optional directory override for component discovery.
-     */
-    loadComponentsFromDirectory(directory?: string): Promise<this>;
-    /**
-     * Recursively loads commands from the configured commands directory.
-     *
-     * @param directory - Optional directory override for command discovery.
-     */
-    loadCommandsFromDirectory(directory?: string): Promise<this>;
-    /**
-     * Lists the raw command data payloads for registration with Discord.
-     */
-    listCommandData(): CommandDataPayload[];
-    /**
-     * Registers commands with Discord's REST API.
-     *
-     * @param botToken - The bot token authorising the registration request.
-     * @param commands - Optional command list to register instead of auto-loaded commands.
-     */
-    registerCommands(botToken: string, commands?: CommandDataPayload[]): Promise<unknown>;
-    /**
-     * Registers role connection metadata with Discord's REST API.
-     *
-     * @param botToken - The bot token authorising the request.
-     * @param metadata - The metadata collection to register.
-     */
-    registerMetadata(botToken: string, metadata: RoleConnectionMetadataField[]): Promise<unknown>;
-    /**
-     * Validates and handles a single Discord interaction request.
-     *
-     * @param request - The request payload containing headers and body data.
-     */
-    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(options?: {
-        waitUntil?: (promise: Promise<void>) => void;
-    }): InteractionNodeHandler;
-    /**
-     * Generates a lightweight verification handler that serves an HTML page with an embedded OAuth link.
-     *
-     * This is primarily used when Discord asks for a verification URL while setting up Linked Roles.
-     * Provide an HTML file that contains the `{{OAUTH_URL}}` placeholder (or a custom placeholder defined in options)
-     * and this helper will replace the token with a freshly generated OAuth link on every request.
-     *
-     * Available placeholders:
-     * - `{{OAUTH_URL}}` - HTML-escaped OAuth URL for links/buttons.
-     * - `{{OAUTH_URL_RAW}}` - raw OAuth URL, ideal for `<script>` usage.
-     * - `{{OAUTH_STATE}}` - HTML-escaped OAuth state value.
-     * - Custom placeholder name (from {@link DiscordOAuthVerificationPageOptions.placeholder}) and its `_RAW` variant.
-     */
-    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}}`
-     */
-    connectedOAuthPage(filePath: string): DiscordOAuthCallbackTemplates["success"];
-    /**
-     * Loads an HTML file and returns an error template that can be reused for all failure cases.
-     *
-     * The following placeholders are available in the HTML file:
-     * - `{{error}}`
-     * - `{{state}}`
-     */
-    failedOAuthPage(filePath: string): ((context: DiscordOAuthErrorTemplateContext) => string) & ((context: DiscordOAuthStateTemplateContext) => string);
-    /**
-     * Resolves an HTML template from disk and caches the result for reuse.
-     */
-    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.
-     */
-    private normalizeTemplateKey;
-    /**
-     * Creates a minimal Discord OAuth callback handler that renders helpful HTML responses.
-     *
-     * This helper keeps the user-side implementation tiny while still exposing hooks for
-     * storing metadata or validating the OAuth state value.
-     */
-    discordOAuthCallback(options: DiscordOAuthCallbackOptions): InteractionNodeHandler;
-    /**
-     * Creates a Fetch API compatible handler for runtimes like Workers or Deno.
-     */
-    /**
-     * Generates a Fetch-standard request handler compatible with Cloudflare Workers,
-     * Bun, Deno, and Next.js Edge Runtime.
-     */
-    createFetchHandler(options?: {
-        waitUntil?: (promise: Promise<void>) => void;
-    }): InteractionFetchHandler;
-    /**
-     * Checks if the provided directory path exists on disk.
-     */
-    private pathExists;
-    /**
-     * Recursively collects all command module file paths from the target directory.
-     */
-    private collectModuleFiles;
-    /**
-     * Determines whether the provided file path matches a supported command file extension.
-     */
-    private isSupportedModuleFile;
-    /**
-     * Dynamically imports and validates a command module from disk.
-     * Supports multiple export patterns:
-     * - export default { data, handler }
-     * - export const command = { data, handler }
-     * - export const ping_command = { data, handler }
-     * - export const data = ...; export const handler = ...;
-     */
-    private importCommandModule;
-    /**
-     * Dynamically imports and validates a component module from disk.
-     * Also handles modal components if they're in a "modals" subdirectory.
-     * Supports multiple export patterns:
-     * - export default { customId, handler }
-     * - export const component = { customId, handler }
-     * - export const ping_button = { customId, handler }
-     * - export const customId = "..."; export const handler = ...;
-     * - export const components = [{ customId, handler }, ...]
-     */
-    private importComponentModule;
-    /**
-     * Normalises the request body into a UTF-8 string for signature validation and parsing.
-     */
-    private normalizeBody;
-    /**
-     * Ensures components have been loaded from disk once before being accessed.
-     */
-    private ensureComponentsLoaded;
-    /**
-     * Ensures commands have been loaded from disk once before being accessed.
-     */
-    private ensureCommandsLoaded;
-    /**
-     * Resolves the absolute commands directory path from configuration.
-     */
-    private resolveCommandsDirectory;
-    /**
-     * Resolves the absolute components directory path from configuration.
-     */
-    private resolveComponentsDirectory;
-    /**
-     * Resolves the absolute utilities directory path from configuration.
-     */
-    private resolveUtilsDirectory;
-    /**
-     * Resolves a directory relative to the project "src" or "dist" folders with optional overrides.
-     */
-    private resolveDirectory;
-    /**
-     * Handles execution of a message component interaction.
-     */
-    private handleMessageComponent;
-    /**
-     * Handles execution of a modal submit interaction.
-     */
-    private handleModalSubmit;
-    /**
-     * Handles execution of an application command interaction.
-     */
-    private handleApplicationCommand;
-    /**
-     * Sends a follow-up response or edits an existing response via Discord's interaction webhooks.
-     * This is used for interactions that have already been acknowledged (e.g., via deferReply).
-     *
-     * Includes retry logic to handle race conditions where the ACK hasn't reached Discord yet.
-     */
-    private sendFollowUp;
-}
-export {};