@kevlid/discordmenus 0.0.2

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @kevlid/discordmenus
+
+```js
+const fs = require("fs");
+const path = require("path");
+const { Client, GatewayIntentBits, REST, Routes, SlashCommandBuilder } = require("discord.js");
+const { MenuManager, MenuBuilder, CustomIdPrefix, fromDiscordJS } = require("@kevlid/discordmenus");
+
+const DATA = path.join(__dirname, "menu-data.json");
+const store = new Map(
+    Object.entries(fs.existsSync(DATA) ? JSON.parse(fs.readFileSync(DATA, "utf8")) : { prefix: "!" }),
+);
+
+function persist() {
+    fs.writeFileSync(DATA, JSON.stringify(Object.fromEntries(store), null, 2));
+}
+
+const builder = new MenuBuilder()
+    .setKey("settings")
+    .setTitle("Settings")
+    .createCategory(c => c.setKey("main"))
+    .addString(o => o.setKey("prefix").setTitle("Prefix").setMinLength(1).setMaxLength(5).setPreview(true));
+
+const manager = new MenuManager();
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+client.once("ready", async () => {
+    await manager.registerMenu(builder, {
+        get: (key) => store.get(key),
+        save: (key, value) => {
+            store.set(key, value);
+            persist();
+        },
+    });
+    await new REST().setToken(process.env.BOT_TOKEN).put(
+        Routes.applicationGuildCommands(client.user.id, process.env.GUILD_ID),
+        { body: [new SlashCommandBuilder().setName("menu").setDescription("Open").toJSON()] },
+    );
+});
+
+client.on("interactionCreate", async (interaction) => {
+    if (interaction.isChatInputCommand() && interaction.commandName === "menu") {
+        await interaction.deferReply();
+        await interaction.editReply(
+            await manager.renderMenu("settings", { userId: interaction.user.id }),
+        );
+        return;
+    }
+    if (interaction.customId?.startsWith(CustomIdPrefix)) {
+        const body = await manager.handleInteraction(fromDiscordJS(interaction));
+        await interaction.client.rest.post(
+            Routes.interactionCallback(interaction.id, interaction.token),
+            { body },
+        );
+    }
+});
+
+client.login(process.env.BOT_TOKEN);
+```

package/index.d.ts

@@ -0,0 +1,255 @@
+export type GetFunction = (
+    key: string,
+    options?: Record<string, unknown>,
+) => unknown | Promise<unknown>;
+
+export type SaveFunction = (
+    key: string,
+    value: unknown,
+    options?: Record<string, unknown>,
+) => unknown | Promise<unknown>;
+
+export type PermissionResolvable = string | number | bigint;
+
+export interface MenuManagerOptions {
+    get?: GetFunction;
+    save?: SaveFunction;
+}
+
+export interface RenderMenuOptions {
+    category?: number;
+    index?: number;
+    userId?: string;
+    guildId?: string;
+}
+
+export interface DiscordInteraction {
+    type: number;
+    id?: string;
+    token?: string;
+    applicationId?: string;
+    guildId?: string;
+    guildID?: string;
+    guild_id?: string;
+    user?: { id: string; [key: string]: unknown };
+    member?: {
+        user?: { id: string; [key: string]: unknown };
+        permissions?: string | bigint | number | { allow?: string | number | bigint } | null;
+        permission?: string | bigint | number | { allow?: string | number | bigint } | null;
+        [key: string]: unknown;
+    };
+    memberPermissions?: string | bigint | null;
+    data?: {
+        custom_id?: string;
+        customID?: string;
+        values?: string[];
+        components?: unknown[];
+        [key: string]: unknown;
+    };
+    customId?: string;
+    custom_id?: string;
+    values?: string[];
+    components?: unknown[];
+    [key: string]: unknown;
+}
+
+export interface DiscordComponent {
+    type: number;
+    [key: string]: unknown;
+}
+
+export interface RenderedMenu {
+    flags: number;
+    components: DiscordComponent[];
+}
+
+export interface InteractionResponse {
+    type: number;
+    data?: {
+        flags?: number;
+        content?: string;
+        title?: string;
+        custom_id?: string;
+        components?: DiscordComponent[];
+        [key: string]: unknown;
+    };
+}
+
+export declare class Builder {
+    readonly type: string;
+    readonly key: string | null;
+    readonly title: string | null;
+    readonly description: string | null;
+    readonly required: boolean;
+    setKey(key: string): this;
+    setTitle(title: string): this;
+    setDescription(description: string): this;
+    setRequired(required: boolean): this;
+}
+
+export declare class BooleanBuilder extends Builder {
+    setTrueLabel(label: string): this;
+    setFalseLabel(label: string): this;
+}
+
+export declare class StringBuilder extends Builder {
+    setPreview(enabled: boolean): this;
+    setMaxLength(length: number): this;
+    setMinLength(length: number): this;
+}
+
+export declare class NumberBuilder extends Builder {
+    setPreview(enabled: boolean): this;
+    setMaxValue(value: number): this;
+    setMinValue(value: number): this;
+}
+
+export declare class CategoryBuilder extends Builder {}
+
+export declare class StringListBuilder extends Builder {
+    setMinLength(length: number): this;
+    setMaxLength(length: number): this;
+}
+
+export declare class NumberListBuilder extends Builder {
+    setMinValue(value: number): this;
+    setMaxValue(value: number): this;
+}
+
+export declare class ObjectListBuilder extends Builder {
+    addString(callback: (builder: StringListBuilder) => void): this;
+    addNumber(callback: (builder: NumberListBuilder) => void): this;
+    addBoolean(callback: (builder: BooleanBuilder) => void): this;
+}
+
+export declare class ObjectBuilder extends Builder {
+    setPreview(enabled: boolean): this;
+    addString(callback: (builder: StringBuilder) => void): this;
+    addNumber(callback: (builder: NumberBuilder) => void): this;
+    addBoolean(callback: (builder: BooleanBuilder) => void): this;
+    addStringList(callback: (builder: StringListBuilder) => void): this;
+    addNumberList(callback: (builder: NumberListBuilder) => void): this;
+}
+
+export declare class StringSelectChoiceBuilder {
+    setDescription(desc: string): this;
+}
+
+export declare class StringSelectBuilder extends Builder {
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+    addChoice(
+        label: string,
+        value: string,
+        callback?: (choice: StringSelectChoiceBuilder) => void,
+    ): this;
+}
+
+export declare class UserSelectBuilder extends Builder {
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+}
+
+export declare class RoleSelectBuilder extends Builder {
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+}
+
+export declare class MentionableSelectBuilder extends Builder {
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+}
+
+export declare class ChannelSelectBuilder extends Builder {
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+    addChannelType(channelType: number): this;
+}
+
+export declare class MenuBuilder extends Builder {
+    setGetMethod(method: GetFunction): this;
+    setSaveMethod(method: SaveFunction): this;
+    setPermissions(permissions: (PermissionResolvable | PermissionResolvable[])[]): this;
+    createCategory(callback: (builder: CategoryBuilder) => void): this;
+    addString(callback: (builder: StringBuilder) => void): this;
+    addNumber(callback: (builder: NumberBuilder) => void): this;
+    addBoolean(callback: (builder: BooleanBuilder) => void): this;
+    addStringList(callback: (builder: StringListBuilder) => void): this;
+    addNumberList(callback: (builder: NumberListBuilder) => void): this;
+    addObject(callback: (builder: ObjectBuilder) => void): this;
+    addObjectList(callback: (builder: ObjectListBuilder) => void): this;
+    addStringSelect(callback: (builder: StringSelectBuilder) => void): this;
+    addUserSelect(callback: (builder: UserSelectBuilder) => void): this;
+    addRoleSelect(callback: (builder: RoleSelectBuilder) => void): this;
+    addMentionableSelect(callback: (builder: MentionableSelectBuilder) => void): this;
+    addChannelSelect(callback: (builder: ChannelSelectBuilder) => void): this;
+}
+
+export declare class MenuManager {
+    registerMenu(menu: MenuBuilder, options?: MenuManagerOptions): Promise<void>;
+    renderMenu(key: string, options?: RenderMenuOptions): Promise<RenderedMenu>;
+    menuFromCustomId(customId: string): { menu: unknown; menu_key: string };
+    handleComponent(interaction: DiscordInteraction): Promise<InteractionResponse>;
+    handleModal(interaction: DiscordInteraction): Promise<InteractionResponse>;
+    handleInteraction(interaction: DiscordInteraction): Promise<InteractionResponse>;
+}
+
+export interface StorageContext {
+    guildId?: string | null;
+    userId?: string | null;
+    [key: string]: unknown;
+}
+
+export interface MenuStorageOptions {
+    cache?: boolean;
+    cacheTTL?: number;
+    cacheMaxSize?: number;
+}
+
+export interface StorageHandler {
+    get: GetFunction;
+    save: SaveFunction;
+}
+
+export declare class MenuStorage {
+    constructor(options?: MenuStorageOptions);
+    get(key: string, ctx?: StorageContext): Promise<unknown>;
+    save(key: string, value: unknown, ctx?: StorageContext): Promise<void>;
+    cacheClear(guildId?: string): void;
+    handler(): StorageHandler;
+}
+
+export declare class MemoryMenuStorage extends MenuStorage {
+    data: Map<string, unknown>;
+    get(key: string, ctx?: StorageContext): Promise<unknown>;
+    save(key: string, value: unknown, ctx?: StorageContext): Promise<void>;
+}
+
+export declare const CustomIdPrefix: string;
+export declare const EphemeralMessageFlag: number;
+
+export declare const OptionTypes: {
+    readonly Menu: string;
+    readonly Category: string;
+    readonly String: string;
+    readonly Number: string;
+    readonly Boolean: string;
+    readonly List: string;
+    readonly Object: string;
+    readonly StringSelect: string;
+    readonly UserSelect: string;
+    readonly RoleSelect: string;
+    readonly MentionableSelect: string;
+    readonly ChannelSelect: string;
+};
+
+export declare function normalizeInteraction(
+    interaction: DiscordInteraction,
+): DiscordInteraction;
+export declare function fromEris(interaction: DiscordInteraction): DiscordInteraction;
+export declare function fromDiscordJS(interaction: DiscordInteraction): DiscordInteraction;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kevlid/discordmenus",
+  "version": "0.0.2",
+  "description": "Components v2 settings menus for Discord bots",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "author": "kevlid",
+  "license": "ISC",
+  "keywords": [
+    "discord",
+    "discord.js",
+    "menu",
+    "typescript",
+    "builder"
+  ],
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@kevlid/customids": "^1.0.0",
+    "discord.js": "^14.25.1",
+    "eris": "^0.18.0"
+  }
+}

package/src/builder.js

@@ -0,0 +1,50 @@
+const { formatKey } = require("./utils/formatKey");
+
+class Builder {
+    constructor(type, cost) {
+        if (typeof type !== "string") throw new TypeError("Type must be a string");
+        this.type = type;
+        this.key = null;
+        this.title = null;
+        this.description = null;
+        this.required = false;
+    }
+
+    setKey(key) {
+        this.key = formatKey(String(key));
+        return this;
+    }
+
+    setTitle(title) {
+        this.title = String(title);
+        return this;
+    }
+
+    setDescription(description) {
+        this.description = String(description);
+        return this;
+    }
+
+    setRequired(required) {
+        this.required = Boolean(required);
+        return this;
+    }
+
+    build() {
+        if (!this.key) throw new Error(this.type + " must have a key");
+        if (!this.title) {
+            this.title = this.key;
+        }
+        return {
+            type: this.type,
+            key: this.key,
+            title: this.title,
+            description: this.description,
+            required: this.required,
+        };
+    }
+}
+
+module.exports = {
+    Builder
+}