meocord/dist/decorator/guard.decorator.d.ts

MeoCord is a lightweight and modular framework for building scalable Discord bots using TypeScript and Discord.js. It simplifies bot development with an extensible architecture, TypeScript-first approach, and powerful CLI tools.

/**
 * MeoCord Framework
 * Copyright (C) 2025 Ukasyah Rahmatullah Zada
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
import 'reflect-metadata';
import { type GuardInterface } from '../interface/index.js';
/**
 * `@Guard()` decorator to mark a class as a Guard that later can be added on `@UseGuard` decorator.
 *
 * @example
 * ```typescript
 * @Guard()
 * export class ButtonInteractionGuard implements GuardInterface {
 *   private readonly logger = new Logger(ButtonInteractionGuard.name)
 *
 *   async canActivate(interaction: ButtonInteraction, { ownerId }: { ownerId: string }): Promise<boolean> {
 *     if (interaction.user.id !== ownerId) {
 *       this.logger.error(
 *         `User with id ${interaction.user.id} is not allowed to use this command that initiated by user with id ${ownerId}.`,
 *       )
 *       const embed = generateErrorEmbed(
 *         `Hi <@${interaction.user.id}>, this command can only be used by the person who initiated it: <@${ownerId}>.`,
 *       )
 *       await interaction.reply({
 *         embeds: [embed],
 *         flags: MessageFlagsBitField.Flags.Ephemeral,
 *       })
 *       return false
 *     }
 *     return true
 *   }
 * }
 * ```
 */
export declare function Guard(): (target: any) => void;
/**
 * Type for a guard with parameters.
 * This type defines a guard that requires additional parameters (other than the default constructor).
 */
interface GuardWithParams {
    /**
     * The guard class that needs to be instantiated.
     */
    provide: new (...args: any[]) => GuardInterface;
    /**
     * Parameters to be passed to the guard during instantiation.
     */
    params: Record<string, any>;
}
/**
 * `@UseGuard()` decorator to apply one or more guards to methods.
 * Guards are used to handle permission checks before executing a method.
 * Each guard must use `@Guard` decorator and implement the `canActivate` method, which determines
 * whether the method should be allowed to execute based on the provided interaction and arguments.
 * This decorator ensures that all guards pass validation before calling the original method.
 * Supports guards that are parameterized (accepting additional parameters).
 *
 * @param guards - One or more guard classes to apply. These can be regular guards or guards with additional parameters.
 *                 - If providing a guard with parameters, it should be an object with:
 *                   - `provide`: The guard class to instantiate. Must implement `GuardInterface`.
 *                   - `params`: A record of key-value pairs to be passed as additional properties to the guard instance.
 * @returns A method decorator function that applies the guards to the method.
 *
 * @example
 * ```typescript
 * @Command('profile-{id}', CommandType.BUTTON)
 * @UseGuard(
 *   { provide: RateLimiterGuard, params: { limit: 2, window: 3000 } },
 *   ButtonInteractionGuard
 * )
 * async showProfileById(interaction: ButtonInteraction, { id }: { id: string }) {
 *   await interaction.reply(`Profile ID: ${id}`)
 * }
 * ```
 */
export declare function UseGuard(...guards: ((new (...args: any[]) => GuardInterface) | GuardWithParams)[]): MethodDecorator;
export {};