@minesa-org/mini-interaction 0.0.1

package/dist/builders/StringSelectMenuBuilder.d.ts

@@ -0,0 +1,56 @@
+import { type APISelectMenuOption, type APIStringSelectComponent } from "discord-api-types/v10";
+import type { JSONEncodable } from "./shared.js";
+/** Shape describing initial string select menu data accepted by the builder. */
+export type StringSelectMenuBuilderData = {
+    customId?: string;
+    placeholder?: string;
+    minValues?: number;
+    maxValues?: number;
+    disabled?: boolean;
+    required?: boolean;
+    options?: APISelectMenuOption[];
+};
+/** Builder for Discord string select menu components. */
+export declare class StringSelectMenuBuilder implements JSONEncodable<APIStringSelectComponent> {
+    private data;
+    /**
+     * Creates a new string select menu builder with optional seed data.
+     */
+    constructor(data?: StringSelectMenuBuilderData);
+    /**
+     * Sets the unique custom identifier for the select menu interaction.
+     */
+    setCustomId(customId: string): this;
+    /**
+     * Sets or clears the placeholder text displayed when no option is selected.
+     */
+    setPlaceholder(placeholder: string | null | undefined): this;
+    /**
+     * Sets the minimum number of options that must be selected.
+     */
+    setMinValues(minValues: number | null | undefined): this;
+    /**
+     * Sets the maximum number of options that can be selected.
+     */
+    setMaxValues(maxValues: number | null | undefined): this;
+    /**
+     * Toggles whether the select menu is disabled.
+     */
+    setDisabled(disabled: boolean): this;
+    /**
+     * Marks the select menu options as required.
+     */
+    setRequired(required: boolean): this;
+    /**
+     * Appends new option entries to the select menu.
+     */
+    addOptions(...options: APISelectMenuOption[]): this;
+    /**
+     * Replaces the current option set with the provided iterable.
+     */
+    setOptions(options: Iterable<APISelectMenuOption>): this;
+    /**
+     * Serialises the builder into an API compatible string select menu payload.
+     */
+    toJSON(): APIStringSelectComponent;
+}

package/dist/builders/StringSelectMenuBuilder.js

@@ -0,0 +1,100 @@
+import { ComponentType, } from "discord-api-types/v10";
+/** Builder for Discord string select menu components. */
+export class StringSelectMenuBuilder {
+    data;
+    /**
+     * Creates a new string select menu builder with optional seed data.
+     */
+    constructor(data = {}) {
+        this.data = {
+            customId: data.customId,
+            placeholder: data.placeholder,
+            minValues: data.minValues,
+            maxValues: data.maxValues,
+            disabled: data.disabled,
+            required: data.required,
+            options: data.options ? [...data.options] : [],
+        };
+    }
+    /**
+     * Sets the unique custom identifier for the select menu interaction.
+     */
+    setCustomId(customId) {
+        this.data.customId = customId;
+        return this;
+    }
+    /**
+     * Sets or clears the placeholder text displayed when no option is selected.
+     */
+    setPlaceholder(placeholder) {
+        this.data.placeholder = placeholder ?? undefined;
+        return this;
+    }
+    /**
+     * Sets the minimum number of options that must be selected.
+     */
+    setMinValues(minValues) {
+        this.data.minValues = minValues ?? undefined;
+        return this;
+    }
+    /**
+     * Sets the maximum number of options that can be selected.
+     */
+    setMaxValues(maxValues) {
+        this.data.maxValues = maxValues ?? undefined;
+        return this;
+    }
+    /**
+     * Toggles whether the select menu is disabled.
+     */
+    setDisabled(disabled) {
+        this.data.disabled = disabled;
+        return this;
+    }
+    /**
+     * Marks the select menu options as required.
+     */
+    setRequired(required) {
+        this.data.required = required;
+        return this;
+    }
+    /**
+     * Appends new option entries to the select menu.
+     */
+    addOptions(...options) {
+        this.data.options.push(...options.map((option) => ({ ...option })));
+        return this;
+    }
+    /**
+     * Replaces the current option set with the provided iterable.
+     */
+    setOptions(options) {
+        this.data.options = Array.from(options, (option) => ({ ...option }));
+        return this;
+    }
+    /**
+     * Serialises the builder into an API compatible string select menu payload.
+     */
+    toJSON() {
+        const { customId, options } = this.data;
+        if (!customId) {
+            throw new Error("[StringSelectMenuBuilder] custom id is required.");
+        }
+        if (options.length === 0) {
+            throw new Error("[StringSelectMenuBuilder] at least one option is required.");
+        }
+        if (options.length > 25) {
+            throw new Error("[StringSelectMenuBuilder] no more than 25 options can be provided.");
+        }
+        return {
+            type: ComponentType.StringSelect,
+            custom_id: customId,
+            placeholder: this.data.placeholder,
+            min_values: this.data.minValues,
+            max_values: this.data.maxValues,
+            disabled: this.data.disabled,
+            required: this.data.required,
+            options: options.map((option) => ({ ...option })),
+        };
+    }
+}

package/dist/builders/index.d.ts

@@ -0,0 +1,14 @@
+/** Re-exports component builders and shared types for convenience. */
+export { ActionRowBuilder } from "./ActionRowBuilder.js";
+export type { ActionRowComponentLike } from "./ActionRowBuilder.js";
+export { ButtonBuilder } from "./ButtonBuilder.js";
+export type { ButtonBuilderData } from "./ButtonBuilder.js";
+export { StringSelectMenuBuilder } from "./StringSelectMenuBuilder.js";
+export type { StringSelectMenuBuilderData } from "./StringSelectMenuBuilder.js";
+export { RoleSelectMenuBuilder } from "./RoleSelectMenuBuilder.js";
+export type { RoleSelectMenuBuilderData } from "./RoleSelectMenuBuilder.js";
+export { ChannelSelectMenuBuilder } from "./ChannelSelectMenuBuilder.js";
+export type { ChannelSelectMenuBuilderData } from "./ChannelSelectMenuBuilder.js";
+export { ModalBuilder } from "./ModalBuilder.js";
+export type { ModalBuilderData, ModalComponentLike } from "./ModalBuilder.js";
+export type { JSONEncodable } from "./shared.js";

package/dist/builders/index.js

@@ -0,0 +1,7 @@
+/** Re-exports component builders and shared types for convenience. */
+export { ActionRowBuilder } from "./ActionRowBuilder.js";
+export { ButtonBuilder } from "./ButtonBuilder.js";
+export { StringSelectMenuBuilder } from "./StringSelectMenuBuilder.js";
+export { RoleSelectMenuBuilder } from "./RoleSelectMenuBuilder.js";
+export { ChannelSelectMenuBuilder } from "./ChannelSelectMenuBuilder.js";
+export { ModalBuilder } from "./ModalBuilder.js";

package/dist/builders/shared.d.ts

@@ -0,0 +1,8 @@
+/** Interface describing objects capable of encoding themselves as JSON payloads. */
+export interface JSONEncodable<T> {
+    toJSON(): T;
+}
+/** Type guard that checks whether a value provides a `toJSON` method. */
+export declare function isJSONEncodable<T>(value: JSONEncodable<T> | unknown): value is JSONEncodable<T>;
+/** Normalises a value that might either be a JSON encodable object or plain payload. */
+export declare function resolveJSONEncodable<T>(value: JSONEncodable<T> | T): T;

package/dist/builders/shared.js

@@ -0,0 +1,11 @@
+/** Type guard that checks whether a value provides a `toJSON` method. */
+export function isJSONEncodable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "toJSON" in value &&
+        typeof value.toJSON === "function");
+}
+/** Normalises a value that might either be a JSON encodable object or plain payload. */
+export function resolveJSONEncodable(value) {
+    return isJSONEncodable(value) ? value.toJSON() : value;
+}

package/dist/clients/MiniInteraction.d.ts

@@ -0,0 +1,176 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { APIInteractionResponse, RESTPostAPIChatInputApplicationCommandsJSONBody } from "discord-api-types/v10";
+import type { MiniInteractionCommand } from "../types/Commands.js";
+import { RoleConnectionMetadataTypes } from "../types/RoleConnectionMetadataTypes.js";
+import { type MessageComponentInteraction } from "../utils/MessageComponentInteraction.js";
+/** Configuration parameters for the MiniInteraction client. */
+export type MiniInteractionOptions = {
+    applicationId: string;
+    publicKey: string;
+    commandsDirectory?: string | false;
+    fetchImplementation?: typeof fetch;
+    verifyKeyImplementation?: VerifyKeyFunction;
+};
+/** 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 MiniInteractionRequest = {
+    body: string | Uint8Array;
+    signature?: string;
+    timestamp?: string;
+};
+/** Result payload returned by request handlers when processing an interaction. */
+export type MiniInteractionHandlerResult = {
+    status: number;
+    body: APIInteractionResponse | {
+        error: string;
+    };
+};
+/** Handler signature invoked for Discord message component interactions. */
+export type MiniInteractionComponentHandler = (interaction: MessageComponentInteraction) => Promise<APIInteractionResponse | void> | APIInteractionResponse | void;
+/** Structure describing a component handler mapped to a custom id. */
+export type MiniInteractionComponent = {
+    customId: string;
+    handler: MiniInteractionComponentHandler;
+};
+/** Node.js HTTP handler compatible with frameworks like Express or Next.js API routes. */
+export type MiniInteractionNodeHandler = (request: IncomingMessage, response: ServerResponse) => void;
+/** Web Fetch API compatible request handler for platforms such as Cloudflare Workers. */
+export type MiniInteractionFetchHandler = (request: Request) => Promise<Response>;
+/**
+ * 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 baseUrl;
+    private readonly fetchImpl;
+    private readonly verifyKeyImpl;
+    private readonly commandsDirectory;
+    private readonly commands;
+    private readonly componentHandlers;
+    private commandsLoaded;
+    private loadCommandsPromise;
+    /**
+     * Creates a new MiniInteraction client with optional command auto-loading and custom runtime hooks.
+     */
+    constructor({ applicationId, publicKey, commandsDirectory, fetchImplementation, verifyKeyImplementation, }: MiniInteractionOptions);
+    /**
+     * Registers a single command handler with the client.
+     *
+     * @param command - The command definition to register.
+     */
+    useCommand(command: MiniInteractionCommand): this;
+    /**
+     * Registers multiple command handlers with the client.
+     *
+     * @param commands - The command definitions to register.
+     */
+    useCommands(commands: MiniInteractionCommand[]): this;
+    /**
+     * Registers a single component handler mapped to a custom identifier.
+     *
+     * @param component - The component definition to register.
+     */
+    useComponent(component: MiniInteractionComponent): this;
+    /**
+     * Registers multiple component handlers in a single call.
+     *
+     * @param components - The component definitions to register.
+     */
+    useComponents(components: MiniInteractionComponent[]): 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(): RESTPostAPIChatInputApplicationCommandsJSONBody[];
+    /**
+     * Registers slash 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?: RESTPostAPIChatInputApplicationCommandsJSONBody[]): 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: MiniInteractionRequest): Promise<MiniInteractionHandlerResult>;
+    /**
+     * Creates a Node.js style request handler that validates and processes interactions.
+     */
+    createNodeHandler(): MiniInteractionNodeHandler;
+    /**
+     * Alias for {@link createNodeHandler} for frameworks expecting a listener function.
+     */
+    createNodeListener(): MiniInteractionNodeHandler;
+    /**
+     * Convenience alias for {@link createNodeHandler} tailored to Vercel serverless functions.
+     */
+    createVercelHandler(): MiniInteractionNodeHandler;
+    /**
+     * Creates a Fetch API compatible handler for runtimes like Workers or Deno.
+     */
+    createFetchHandler(): MiniInteractionFetchHandler;
+    /**
+     * Checks if the provided directory path exists on disk.
+     */
+    private pathExists;
+    /**
+     * Recursively collects all command module file paths from the target directory.
+     */
+    private collectCommandFiles;
+    /**
+     * Determines whether the provided file path matches a supported command file extension.
+     */
+    private isSupportedCommandFile;
+    /**
+     * Dynamically imports and validates a command module from disk.
+     */
+    private importCommandModule;
+    /**
+     * Normalises the request body into a UTF-8 string for signature validation and parsing.
+     */
+    private normalizeBody;
+    /**
+     * Ensures commands have been loaded from disk once before being accessed.
+     */
+    private ensureCommandsLoaded;
+    /**
+     * Resolves the absolute commands directory path from configuration.
+     */
+    private resolveCommandsDirectory;
+    /**
+     * Handles execution of a message component interaction.
+     */
+    private handleMessageComponent;
+    /**
+     * Handles execution of an application command interaction.
+     */
+    private handleApplicationCommand;
+}
+export {};