@julanzw/ttoolbox-discordjs-framework 1.0.1

package/dist/utils/editAndReply.js

@@ -0,0 +1,85 @@
+import { MessageFlags, } from 'discord.js';
+import { InteractionError } from '../classes/InteractionError.class.js';
+/**
+ * Safely replies to an interaction, handling deferred/replied states.
+ *
+ * @param interaction - The interaction to reply to
+ * @param content - The message content
+ * @param ephemeral - Whether the reply should be ephemeral
+ * @param embeds - Optional embeds to include
+ * @param components - Optional components to include
+ * @param files - Optional files to attach
+ * @returns The message that was sent
+ * @throws {InteractionError} If the interaction is too old or fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await safeReply(interaction, 'Hello!', true);
+ * } catch (err) {
+ *   if (err instanceof InteractionError && err.reason === 'expired') {
+ *     this.logger?.warn('Interaction expired', 'command');
+ *   }
+ * }
+ * ```
+ */
+export async function safeReply(interaction, content, ephemeral = false, embeds, components, files) {
+    // Check if interaction is too old
+    const now = Date.now();
+    const threeMinutes = 3 * 60 * 1000;
+    if (now - interaction.createdTimestamp > threeMinutes) {
+        throw new InteractionError('Interaction is older than 3 minutes', interaction.id, 'expired');
+    }
+    const payload = {
+        ...(content ? { content } : {}),
+        ...(ephemeral ? { flags: MessageFlags.Ephemeral } : {}),
+        ...(embeds ? { embeds } : {}),
+        ...(components ? { components } : {}),
+        ...(files ? { files } : {}),
+    };
+    try {
+        if (!interaction.replied && !interaction.deferred) {
+            await interaction.reply(payload);
+            return await interaction.fetchReply();
+        }
+        else {
+            return await interaction.followUp(payload);
+        }
+    }
+    catch (err) {
+        throw new InteractionError(
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        `Failed to reply to interaction: ${err.message}`, interaction.id, 'failed');
+    }
+}
+/**
+ * Safely edits an interaction reply.
+ *
+ * @param interaction - The interaction to edit
+ * @param content - The new message content
+ * @param embeds - Optional embeds to include
+ * @param components - Optional components to include
+ * @returns The edited message
+ * @throws {InteractionError} If the interaction is too old or fails
+ */
+export async function safeEdit(interaction, content, embeds, components) {
+    // Check if interaction is too old
+    const now = Date.now();
+    const threeMinutes = 3 * 60 * 1000;
+    if (now - interaction.createdTimestamp > threeMinutes) {
+        throw new InteractionError('Interaction is older than 3 minutes', interaction.id, 'expired');
+    }
+    const editPayload = {
+        ...(content ? { content } : {}),
+        ...(embeds ? { embeds } : {}),
+        ...(components ? { components } : {}),
+    };
+    try {
+        return await interaction.editReply(editPayload);
+    }
+    catch (err) {
+        throw new InteractionError(
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        `Failed to edit interaction: ${err.message}`, interaction.id, 'failed');
+    }
+}

package/dist/utils/embeds.d.ts

@@ -0,0 +1,55 @@
+import { APIEmbedField, ColorResolvable, EmbedBuilder, ButtonStyle, ButtonBuilder, ActionRowBuilder } from 'discord.js';
+import { PaginationButtonLocation } from '../types/button.js';
+/**
+ * Util function for building an embed
+ *
+ * @param title - The title of the embed
+ * @param fields - The fields of the embed
+ * @param description - The description of the embed, optional
+ * @param footer - The footer of the embed, optional
+ * @param timestamp - If the embed should have a timestamp, defaults to false
+ * @param color - The color of the embed, defaults to STANDARD_COLOR
+ * @param customize - A function to customize the embed further, defaults to no customization
+ *
+ * @returns An EmbedBuilder instance with the specified properties
+ */
+export declare function embedBuilder({ title, fields, description, footer, timestamp, color, customize, }: {
+    title: string;
+    fields?: APIEmbedField[];
+    description?: string;
+    footer?: string;
+    timestamp?: boolean;
+    color?: ColorResolvable;
+    customize?: (embed: EmbedBuilder) => EmbedBuilder;
+}): EmbedBuilder;
+/**
+ * Creates a single button based on its type and config.
+ *
+ * @param type - The button type of the button (prev, next, edit, delete, etc)
+ * @param actionId - The base action ID for the button
+ * @param disabled - Whether the button should be disabled, defaults to false
+ * @param label - Optional label for the button, defaults to type-based label
+ * @param style - Optional style for the button, defaults to secondary
+ *
+ * @return A ButtonBuilder instance configured with the specified properties
+ */
+export declare function createButton({ type, disabled, label, style, customId, }: {
+    type: string;
+    disabled?: boolean;
+    label?: string;
+    style?: ButtonStyle;
+    customId?: string;
+}): ButtonBuilder;
+/**
+ * Creates an `ButtonBuilder[]` with a prev and next button (in that order).
+ *
+ * @param index - The current index of the item being paginated
+ * @param total - The total number of pages
+ *
+ * @returns An `ButtonBuilder[]` containing the buttons
+ */
+export declare function createPaginationButtons(index: number, total: number): ButtonBuilder[];
+export declare function createButtonsRow(normalButtons: ButtonBuilder[], pagination?: {
+    buttons: ButtonBuilder[];
+    location: PaginationButtonLocation;
+}): ActionRowBuilder<ButtonBuilder>;

package/dist/utils/embeds.js

@@ -0,0 +1,94 @@
+import { EmbedBuilder, ButtonStyle, ButtonBuilder, ActionRowBuilder, } from 'discord.js';
+/**
+ * Util function for building an embed
+ *
+ * @param title - The title of the embed
+ * @param fields - The fields of the embed
+ * @param description - The description of the embed, optional
+ * @param footer - The footer of the embed, optional
+ * @param timestamp - If the embed should have a timestamp, defaults to false
+ * @param color - The color of the embed, defaults to STANDARD_COLOR
+ * @param customize - A function to customize the embed further, defaults to no customization
+ *
+ * @returns An EmbedBuilder instance with the specified properties
+ */
+export function embedBuilder({ title, fields, description, footer, timestamp = false, color = '#3F48CC', customize = (e) => e, }) {
+    let embed = new EmbedBuilder().setTitle(title).setColor(color);
+    if (fields && fields.length > 0)
+        embed = embed.setFields(fields);
+    if (description)
+        embed = embed.setDescription(description);
+    if (footer)
+        embed = embed.setFooter({ text: footer });
+    if (timestamp)
+        embed = embed.setTimestamp();
+    return customize(embed);
+}
+/**
+ * Creates a single button based on its type and config.
+ *
+ * @param type - The button type of the button (prev, next, edit, delete, etc)
+ * @param actionId - The base action ID for the button
+ * @param disabled - Whether the button should be disabled, defaults to false
+ * @param label - Optional label for the button, defaults to type-based label
+ * @param style - Optional style for the button, defaults to secondary
+ *
+ * @return A ButtonBuilder instance configured with the specified properties
+ */
+export function createButton({ type, disabled = false, label, style, customId, }) {
+    const button = new ButtonBuilder()
+        .setCustomId(customId ?? `${type}`)
+        .setDisabled(disabled);
+    switch (type) {
+        case 'prev':
+            return button
+                .setLabel(label ?? 'Previous')
+                .setStyle(ButtonStyle.Secondary);
+        case 'next':
+            return button.setLabel(label ?? 'Next').setStyle(ButtonStyle.Secondary);
+        case 'edit':
+            return button.setLabel(label ?? 'Edit').setStyle(ButtonStyle.Primary);
+        case 'delete':
+            return button.setLabel(label ?? 'Delete').setStyle(ButtonStyle.Danger);
+        default:
+            return button
+                .setLabel(label ?? 'Unknown')
+                .setStyle(style ?? ButtonStyle.Secondary);
+    }
+}
+/**
+ * Creates an `ButtonBuilder[]` with a prev and next button (in that order).
+ *
+ * @param index - The current index of the item being paginated
+ * @param total - The total number of pages
+ *
+ * @returns An `ButtonBuilder[]` containing the buttons
+ */
+export function createPaginationButtons(index, total) {
+    const buttons = [
+        createButton({
+            type: 'prev',
+            disabled: index === 0,
+        }),
+        createButton({
+            type: 'next',
+            disabled: index === total - 1,
+        }),
+    ];
+    return buttons;
+}
+export function createButtonsRow(normalButtons, pagination) {
+    if (pagination && pagination.buttons.length === 2) {
+        switch (pagination.location) {
+            case 'embrace':
+                return new ActionRowBuilder().addComponents(pagination.buttons[0], ...normalButtons, pagination.buttons[1]);
+            case 'start':
+                return new ActionRowBuilder().addComponents(...pagination.buttons, ...normalButtons);
+            case 'end':
+                return new ActionRowBuilder().addComponents(...normalButtons, ...pagination.buttons);
+        }
+    }
+    else {
+        return new ActionRowBuilder().addComponents(...normalButtons);
+    }
+}

package/dist/utils/formatting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Util function for formatting a `Date` like 2000-01-01 into January 1st
+ *
+ * @param date - the date that needs formatting
+ * @returns the formatted date
+ */
+export declare function formatDateToString(date: Date): string;
+/**
+ * Util function to get the suffix of a number, e.g. 1st, 2nd, 3rd, 4th, etc.
+ *
+ * @param number - the number you want the suffix of
+ * @returns the suffix of the number
+ */
+export declare function getDaySuffix(number: number): "th" | "st" | "nd" | "rd";
+/**
+ * Util function to format a date into a string with the DD-MM-YYYY format
+ *
+ * @param date - The date to format
+ * @returns A formatted string in the format DD-MM-YYYY
+ */
+export declare function formatDateToDDMMYYYY(date: Date): string;
+/**
+ * Util function to format a date into a string with the YYYY-MM-DD HH:MM:SS format
+ * @param date - The date to format
+ * @returns A formatted string in YYYY-MM-DD HH:MM:SS format
+ */
+export declare function formatDateToYYYYMMDDHHMMSS(date: Date): string;
+/**
+ * Util function to format the first letter of a string
+ * @param str - input string
+ * @returns The formatted string
+ */
+export declare function capitalizeFirst(input: string): string;
+/**
+ * Formats a duration in milliseconds into a human-readable string.
+ * Examples:
+ *  - 4200 -> "4s"
+ *  - 65000 -> "1m 5s"
+ *  - 3723000 -> "1h 2m 3s"
+ *
+ * @param ms Duration in milliseconds
+ * @returns A formatted string
+ */
+export declare function formatDuration(ms: number): string;

package/dist/utils/formatting.js

@@ -0,0 +1,87 @@
+/**
+ * Util function for formatting a `Date` like 2000-01-01 into January 1st
+ *
+ * @param date - the date that needs formatting
+ * @returns the formatted date
+ */
+export function formatDateToString(date) {
+    const daySuffix = getDaySuffix(date.getDate());
+    return (date.toLocaleDateString('en-US', { month: 'long', day: 'numeric' }) +
+        daySuffix);
+}
+/**
+ * Util function to get the suffix of a number, e.g. 1st, 2nd, 3rd, 4th, etc.
+ *
+ * @param number - the number you want the suffix of
+ * @returns the suffix of the number
+ */
+export function getDaySuffix(number) {
+    if (number > 3 && number < 21)
+        return 'th';
+    switch (number % 10) {
+        case 1:
+            return 'st';
+        case 2:
+            return 'nd';
+        case 3:
+            return 'rd';
+        default:
+            return 'th';
+    }
+}
+/**
+ * Util function to format a date into a string with the DD-MM-YYYY format
+ *
+ * @param date - The date to format
+ * @returns A formatted string in the format DD-MM-YYYY
+ */
+export function formatDateToDDMMYYYY(date) {
+    const day = String(date.getDate()).padStart(2, '0');
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const year = date.getFullYear();
+    return `${day}-${month}-${year}`;
+}
+/**
+ * Util function to format a date into a string with the YYYY-MM-DD HH:MM:SS format
+ * @param date - The date to format
+ * @returns A formatted string in YYYY-MM-DD HH:MM:SS format
+ */
+export function formatDateToYYYYMMDDHHMMSS(date) {
+    return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+/**
+ * Util function to format the first letter of a string
+ * @param str - input string
+ * @returns The formatted string
+ */
+export function capitalizeFirst(input) {
+    if (!input)
+        return '';
+    const lower = input.toLowerCase();
+    return lower.charAt(0).toUpperCase() + lower.slice(1);
+}
+/**
+ * Formats a duration in milliseconds into a human-readable string.
+ * Examples:
+ *  - 4200 -> "4s"
+ *  - 65000 -> "1m 5s"
+ *  - 3723000 -> "1h 2m 3s"
+ *
+ * @param ms Duration in milliseconds
+ * @returns A formatted string
+ */
+export function formatDuration(ms) {
+    let seconds = Math.floor(ms / 1000);
+    const hours = Math.floor(seconds / 3600);
+    seconds %= 3600;
+    const minutes = Math.floor(seconds / 60);
+    seconds %= 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}

package/dist/utils/miliseconds.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Common time durations in milliseconds.
+ */
+export declare enum TIMES_MILISECONDS {
+    SECOND = 1000,
+    MINUTE = 60000,
+    TEN_MINUTES = 600000,
+    HOUR = 6000000,
+    DAY = 14400000
+}

package/dist/utils/miliseconds.js

@@ -0,0 +1,11 @@
+/**
+ * Common time durations in milliseconds.
+ */
+export var TIMES_MILISECONDS;
+(function (TIMES_MILISECONDS) {
+    TIMES_MILISECONDS[TIMES_MILISECONDS["SECOND"] = 1000] = "SECOND";
+    TIMES_MILISECONDS[TIMES_MILISECONDS["MINUTE"] = 60000] = "MINUTE";
+    TIMES_MILISECONDS[TIMES_MILISECONDS["TEN_MINUTES"] = 600000] = "TEN_MINUTES";
+    TIMES_MILISECONDS[TIMES_MILISECONDS["HOUR"] = 6000000] = "HOUR";
+    TIMES_MILISECONDS[TIMES_MILISECONDS["DAY"] = 14400000] = "DAY";
+})(TIMES_MILISECONDS || (TIMES_MILISECONDS = {}));

package/dist/utils/permissions.d.ts

@@ -0,0 +1,8 @@
+import { PermissionLevel } from '../types/permission.js';
+/**
+ * Utility function to return the proper permission bits
+ *
+ * @param level - the PermissionLevel the bits need to be returned of. Can be an array
+ * @returns the permission's bit value or null for unrestricted
+ */
+export declare function getPermissionsForLevel(level: PermissionLevel): bigint | null;

package/dist/utils/permissions.js

@@ -0,0 +1,24 @@
+import { PermissionFlagsBits, PermissionsBitField } from 'discord.js';
+/**
+ * Utility function to return the proper permission bits
+ *
+ * @param level - the PermissionLevel the bits need to be returned of. Can be an array
+ * @returns the permission's bit value or null for unrestricted
+ */
+export function getPermissionsForLevel(level) {
+    if (level === 'admin') {
+        return PermissionFlagsBits.Administrator;
+    }
+    if (level === 'owner' || level === 'disabled') {
+        // disable the command by default
+        return BigInt(0);
+    }
+    if (typeof level === 'bigint' || typeof level === 'number') {
+        return BigInt(level);
+    }
+    if (Array.isArray(level)) {
+        return new PermissionsBitField(level).bitfield;
+    }
+    // unrestricted
+    return null;
+}

package/dist/utils/slashCommandOptions.d.ts

@@ -0,0 +1,8 @@
+import { SlashCommandBooleanOption, SlashCommandChannelOption, SlashCommandIntegerOption, SlashCommandRoleOption, SlashCommandStringOption, SlashCommandUserOption } from 'discord.js';
+import { AllowedChannelTypeChannelOption } from '../types/channel.js';
+export declare const userOption: (name: string, desc: string, required?: boolean) => (opt: SlashCommandUserOption) => SlashCommandUserOption;
+export declare const integerOption: (name: string, desc: string, required?: boolean) => (opt: SlashCommandIntegerOption) => SlashCommandIntegerOption;
+export declare const stringOption: (name: string, desc: string, required?: boolean) => (opt: SlashCommandStringOption) => SlashCommandStringOption;
+export declare const channelOption: (name: string, desc: string, required?: boolean, channelType?: AllowedChannelTypeChannelOption | AllowedChannelTypeChannelOption[]) => (opt: SlashCommandChannelOption) => SlashCommandChannelOption;
+export declare const roleOption: (name: string, desc: string, required?: boolean) => (opt: SlashCommandRoleOption) => SlashCommandRoleOption;
+export declare const booleanOption: (name: string, desc: string, required?: boolean) => (opt: SlashCommandBooleanOption) => SlashCommandBooleanOption;

package/dist/utils/slashCommandOptions.js

@@ -0,0 +1,11 @@
+import { ChannelType, } from 'discord.js';
+export const userOption = (name, desc, required = true) => (opt) => opt.setName(name).setDescription(desc).setRequired(required);
+export const integerOption = (name, desc, required = true) => (opt) => opt.setName(name).setDescription(desc).setRequired(required);
+export const stringOption = (name, desc, required = true) => (opt) => opt.setName(name).setDescription(desc).setRequired(required);
+export const channelOption = (name, desc, required = true, channelType = [ChannelType.GuildText]) => (opt) => opt
+    .setName(name)
+    .setDescription(desc)
+    .setRequired(required)
+    .addChannelTypes(...(Array.isArray(channelType) ? channelType : [channelType]));
+export const roleOption = (name, desc, required = true) => (opt) => opt.setName(name).setDescription(desc).setRequired(required);
+export const booleanOption = (name, desc, required = true) => (opt) => opt.setName(name).setDescription(desc).setRequired(required);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@julanzw/ttoolbox-discordjs-framework",
+  "version": "1.0.1",
+  "description": "A Discord.js command framework with built-in handlers and utilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "discord",
+    "discord.js",
+    "bot",
+    "framework",
+    "commands",
+    "typescript"
+  ],
+  "author": "JulanZw",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JulanZw/ttoolbox-discordjs-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JulanZw/ttoolbox-discordjs-framework/issues"
+  },
+  "homepage": "https://github.com/JulanZw/ttoolbox-discordjs-framework#readme",
+  "peerDependencies": {
+    "discord.js": "^14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@prisma/client": "^6.11.1",
+    "@types/node": "^24.0.14",
+    "discord.js": "^14.21.0",
+    "typescript": "^5.8.3"
+  }
+}