@seedcord/core 0.1.0-next.1 → 0.1.0-next.2

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { c as RowComponent, l as BuilderType, n as CustomId, s as BuilderComponent, u as RowType } from "./CustomId-BJF6mbJs.mjs";
-import { RenderContext, ReplyResponse } from "@seedcord/types";
+import { C as BuilderComponent, E as RowType, S as RegisterCommand, T as BuilderType, _ as RequiredOf, b as CoreBase, d as JoinNames, f as TwoOrMore, g as GateContextBase, h as Gate, m as EffectGate, n as CustomId, p as Notice, s as GateNoticeOptions, u as IntersectRequired, v as defineEffectGate, w as RowComponent, y as defineGate } from "./CustomId-Ddwg48VY.mjs";
+import { ValidDuration } from "@seedcord/utils";
+import { EpochMs, RenderContext, ReplyResponse } from "@seedcord/types";
 
 //#region src/registries/ContextMenuRegistry.d.ts
 /**
@@ -59,71 +60,230 @@ interface SlashOption {
  */
 interface SlashOptionRegistry {}
 //#endregion
-//#region src/stops/Notice.d.ts
+//#region src/gates/combinators.d.ts
 /**
- * Base class for a user-facing refusal or a reported fault.
+ * Runs each gate in order and refuses on the first refusal. Takes two or more arms. The required
+ * context is the intersection of the arms, so an event-only and an interaction-only gate cannot be
+ * combined.
  *
- * Throw a `Notice` to stop a handler and reply to the user. The framework catches it at the controller
- * boundary and renders {@link Notice.render}, which always decides what the user sees. With `report`
- * false that render is all that happens. With `report` true the framework also logs the fault and
- * publishes it to the `handledException` bus. A raw, non-Notice throw shows the generic message.
+ * @typeParam Gates - The tuple of two or more gate arms, run left to right.
+ * @param gates - The gate arms to run in order, all refused on the first refusal.
+ *
+ * @see {@link or}
  *
  * @example
  * ```ts
- * import { Notice, BuilderComponent, type RenderContext, type ReplyResponse } from 'seedcord';
- * import { TextDisplayBuilder } from '@discordjs/builders';
+ * import { PermissionFlagsBits } from 'discord.js';
  *
- * // reading `.component` applies the configured bot color to the container accent
- * class TooPoorCard extends BuilderComponent<'container'> {
- *     constructor(balance: number) {
- *         super('container');
- *         this.instance.addTextDisplayComponents(
- *             new TextDisplayBuilder().setContent(`### Insufficient balance\nYou need more than ${balance} coins.`)
- *         );
+ * \@Gated(and(GuildOnly(), RequirePermissions([PermissionFlagsBits.BanMembers])))
+ * \@SlashRoute('ban')
+ * class BanHandler extends SlashHandler<'ban'> {
+ *     async execute() {
+ *         // ...
  *     }
  * }
+ * ```
+ */
+declare function and<Gates extends TwoOrMore<Gate<GateContextBase>>>(...gates: Gates): Gate<IntersectRequired<Gates> & GateContextBase, JoinNames<Gates, ' & '>>;
+interface OrOptions {
+  fail: Notice | ((ctx: GateContextBase) => Notice);
+}
+/**
+ * Runs each gate in order and passes on the first arm that passes. Takes two or more arms. The
+ * required context is the union of the arms, so a handler that matches any one arm fits. When every
+ * arm refuses it throws the trailing {@link OrOptions} `fail` if given, else an auto list of the
+ * arms derived from the summary field, else a default refusal. The trailing options object does not
+ * count as an arm.
+ *
+ * @typeParam Gates - The tuple of two or more gate arms, tried left to right.
+ * @param gates - The gate arms to try in order, with an optional trailing {@link OrOptions} object.
  *
- * class TooPoor extends Notice {
- *     constructor(private readonly balance: number) {
- *         super(`balance ${balance} is below the cost`);
+ * @see {@link and}
+ *
+ * @example
+ * ```ts
+ * \@Gated(or(OwnerOnly(), RequireRole('123456789012345678')))
+ * \@SlashRoute('admin')
+ * class AdminHandler extends SlashHandler<'admin'> {
+ *     async execute() {
+ *         // ...
  *     }
+ * }
+ * ```
+ */
+declare function or<Gates extends TwoOrMore<Gate<GateContextBase>>>(...gates: Gates): Gate<RequiredOf<Gates[number]>, JoinNames<Gates, ' | '>>;
+/**
+ * @example
+ * ```ts
+ * // custom refusal when every arm refuses
+ * or(OwnerOnly(), RequireRole('123456789012345678'), { fail: new NotAllowedNotice() });
+ * ```
+ */
+declare function or<Gates extends TwoOrMore<Gate<GateContextBase>>>(...args: [...Gates, OrOptions]): Gate<RequiredOf<Gates[number]>, JoinNames<Gates, ' | '>>;
+//#endregion
+//#region src/gates/catalog/access.d.ts
+/**
+ * Passes only for a user id listed in `config.ownerIds`, else refuses.
+ *
+ * Agnostic, so it attaches to interaction and event handlers alike. With no `ownerIds` configured it refuses every caller. Pass {@link GateNoticeOptions} to reword or replace the refusal.
+ *
+ * @param options - Reword the default refusal with `message`, or replace it with `notice`.
  *
- *     render(_ctx: RenderContext): ReplyResponse {
- *         return { components: [new TooPoorCard(this.balance).component] };
+ * @see the `@Gated` decorator from `seedcord`
+ *
+ * @example
+ * ```ts
+ * \@Gated(OwnerOnly())
+ * \@SlashRoute('shutdown')
+ * class ShutdownHandler extends SlashHandler<'shutdown'> {
+ *     async execute() {
+ *         // ...
  *     }
  * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // reword the refusal, keeping the embed styling
+ * OwnerOnly({ message: 'Owners only.' });
+ * ```
+ */
+declare function OwnerOnly(options?: GateNoticeOptions): Gate<GateContextBase, 'OwnerOnly'>;
+/**
+ * Passes inside a guild, else refuses.
  *
- * // in a handler, throwing stops the handler and replies with render(ctx)
- * if (wallet.balance < cost) throw new TooPoor(wallet.balance);
+ * Agnostic, so it attaches to any handler kind. Often paired with `RequirePermissions` in an {@link and}.
+ *
+ * @param options - Reword the default refusal with `message`, or replace it with `notice`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
+ *
+ * @example
+ * ```ts
+ * import { PermissionFlagsBits } from 'discord.js';
+ *
+ * \@Gated(GuildOnly(), RequirePermissions([PermissionFlagsBits.Administrator]))
+ * \@SlashRoute('maintenance')
+ * class Maintenance extends SlashHandler<'maintenance'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
  * ```
  */
-declare abstract class Notice extends Error {
+declare function GuildOnly(options?: GateNoticeOptions): Gate<GateContextBase, 'GuildOnly'>;
+/**
+ * Passes in a direct message, else refuses.
+ *
+ * Agnostic, so it attaches to any handler kind. The inverse of {@link GuildOnly}, so combining the two in an {@link and} can never pass.
+ *
+ * @param options - Reword the default refusal with `message`, or replace it with `notice`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
+ *
+ * @example
+ * ```ts
+ * \@Gated(DmOnly())
+ * \@SlashRoute('verify')
+ * class VerifyHandler extends SlashHandler<'verify'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+declare function DmOnly(options?: GateNoticeOptions): Gate<GateContextBase, 'DmOnly'>;
+//#endregion
+//#region src/gates/catalog/Cooldown.d.ts
+/**
+ * Options for {@link Cooldown}. `per` sets the bucket the window applies to and `limit` the uses allowed per
+ * window. `message` rewords the refusal and `notice` replaces it, both receiving the epoch ms the key frees
+ * up so the refusal can show the retry time.
+ *
+ * @example
+ * ```ts
+ * // one use per channel, rewording the refusal with the retry time
+ * Cooldown('10s', {
+ *     per: 'channel',
+ *     message: (resetAt) => `Slow down. Try again <t:${Math.round(resetAt / 1000)}:R>.`
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // five uses per minute, per user
+ * Cooldown('1m', { limit: 5 });
+ * ```
+ */
+interface CooldownOptions {
   /**
-   * Whether this denial is a reported fault. True also logs it and publishes it to the `handledException`
-   * bus. The user always sees {@link Notice.render} either way.
+   * The bucket the cooldown window applies to. 'user' scopes by user ID, falls back to global when the source carries no user id. 'guild' scopes by guild ID (falls back to global if no guild), and 'channel' scopes by channel ID (falls back to global if no channel).
    *
-   * @defaultValue `false`
+   * @defaultValue `'user'`
    */
-  report: boolean;
+  per?: 'user' | 'guild' | 'channel';
   /**
-   * Whether the reply is ephemeral, so only the invoking user sees it. Set it false for a refusal the
-   * whole channel should see.
+   * Uses allowed inside one window before the gate refuses.
    *
-   * @defaultValue `true`
+   * @defaultValue `1`
    */
-  ephemeral: boolean;
+  limit?: number;
   /**
-   * A short one-line reason. When every arm of an `or` gate refuses and each refusal sets this, `or`
-   * lists them instead of showing a neutral message.
+   * Reword the refusal, keeping the standard notice card. Receives the epoch ms the key frees up, so the
+   * text can include the retry time with `<t:${Math.round(resetAt / 1000)}:R>`.
    */
-  summary?: string;
-  protected constructor(message: string, options?: ErrorOptions);
+  message?: (resetAt: EpochMs) => string;
   /**
-   * Builds what the user sees. Called fresh each time the denial is shown, so the builders are new
-   * and the bot color resolves at render time rather than at construction time.
+   * Replace the refusal Notice entirely, for full control or a translated copy. Receives the epoch ms the
+   * key frees up.
    */
-  abstract render(ctx: RenderContext): ReplyResponse;
+  notice?: (resetAt: EpochMs) => Notice;
 }
+/**
+ * Allows `limit` uses per window, scoped by `per`. A number `duration` is **seconds**, a string is
+ * a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError** at construction. The
+ * slot is charged in commit, only after the whole gate set passes, so a later refusal never burns the cooldown.
+ * That split also means two requests racing the same key can both pass before either charges the slot.
+ * Each call gets its own bucket, so two handlers never share a window. Reword the refusal with {@link CooldownOptions.message}
+ * or replace it with {@link CooldownOptions.notice}.
+ *
+ * @param duration - A number is seconds, a string is a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError**.
+ * @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal text with `message` or `notice`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
+ * @see {@link IRateLimiter}
+ *
+ * @example
+ * ```ts
+ * // a number argument is SECONDS
+ * \@Gated(Cooldown(5))
+ * \@SlashRoute('daily')
+ * class DailyHandler extends SlashHandler<'daily'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // a string is a duration, here scoped per guild (the default is per user)
+ * Cooldown('30m', { per: 'guild' });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // a burst, 3 uses per 10 minutes per user, then it refuses until a slot frees
+ * \@Gated(Cooldown('10m', { limit: 3 }))
+ * \@SlashRoute('report')
+ * class ReportHandler extends SlashHandler<'report'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+declare function Cooldown(duration: number | ValidDuration, options?: CooldownOptions): EffectGate<GateContextBase, 'Cooldown'>;
 //#endregion
 //#region src/stops/Fault.d.ts
 /**
@@ -218,5 +378,5 @@ declare function paginate<Item>(items: readonly Item[], page: number, perPage: n
 /** Package version */
 declare const version: string;
 //#endregion
-export { BuilderComponent, type BuilderType, CustomId, Fault, type MessageContextMenuRegistry, Notice, type OptionKind, type PageView, RowComponent, type RowType, Silence, type SlashOption, type SlashOptionRegistry, type UserContextMenuRegistry, paginate, version };
+export { BuilderComponent, type BuilderType, Cooldown, type CooldownOptions, type CoreBase, CustomId, DmOnly, type EffectGate, Fault, type Gate, type GateContextBase, type GateNoticeOptions, GuildOnly, type MessageContextMenuRegistry, Notice, type OptionKind, OwnerOnly, type PageView, RegisterCommand, type RequiredOf, RowComponent, type RowType, Silence, type SlashOption, type SlashOptionRegistry, type UserContextMenuRegistry, and, defineEffectGate, defineGate, or, paginate, version };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,7 +1,113 @@
-import { a as Notice, i as NoticeCard, o as BuilderComponent, s as RowComponent, t as CustomId } from "./CustomId-XgZ2KDgT.mjs";
+import { S as CommandMetadataKey, _ as NoticeCard, c as runCheck, d as NeedsAny, f as NotAllowed, g as OnCooldown, h as NotOwner, i as pickNotice, m as NotInGuild, o as markCommits, p as NotInDm, s as rollbackCommits, t as CustomId, v as BuilderComponent, x as Notice, y as RowComponent } from "./CustomId-Bq6WagiA.mjs";
+import "reflect-metadata";
 import { SeedcordErrorCode } from "@seedcord/errors";
-import { SeedcordRangeError } from "@seedcord/errors/internal";
+import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
+import { parseDuration } from "@seedcord/utils";
 
+//#region src/decorators/Command.ts
+function RegisterCommand(scope, guilds = []) {
+	return (ctor) => {
+		const existingMeta = Reflect.getOwnMetadata(CommandMetadataKey, ctor);
+		if (existingMeta) throw new SeedcordError(SeedcordErrorCode.DecoratorCommandAlreadyRegistered, [
+			ctor.name,
+			existingMeta.scope,
+			scope
+		]);
+		if (scope === "global" && guilds.length > 0) throw new SeedcordError(SeedcordErrorCode.DecoratorCommandGlobalWithGuilds);
+		if (scope === "guild" && (!Array.isArray(guilds) || guilds.length === 0)) throw new SeedcordError(SeedcordErrorCode.DecoratorCommandGuildWithoutGuilds);
+		const meta = scope === "global" ? { scope } : {
+			scope,
+			guilds
+		};
+		Reflect.defineMetadata(CommandMetadataKey, meta, ctor);
+	};
+}
+
+//#endregion
+//#region src/gates/Gate.ts
+/**
+* Builds a {@link Gate} from a check. The check refuses by throwing a Notice or a Silence and passes
+* by returning. The required context is inferred from `ctx`, so annotate it as narrowly as the fields
+* the check reads. No annotation defaults to {@link GateContextBase}, an agnostic gate that fits every
+* handler.
+*
+* @typeParam Name - The gate's name captured as a literal, so a mismatch error can name the gate.
+* @typeParam Ctx - The context the check reads, inferred from the `ctx` annotation.
+*
+* @param name - The gate's name, used in mismatch errors.
+* @param fn - The check, which refuses by throwing a Notice or a Silence and passes by returning.
+*
+* @see {@link defineEffectGate}
+* @see the `@Gated` decorator from `seedcord`
+*
+* @example
+* ```ts
+* // a gate factory that takes its own option and closes over it
+* function MinRoles(min: number): Gate<GateContextBase, 'MinRoles'> {
+*     return defineGate('MinRoles', (ctx) => {
+*         if (ctx.memberRoleIds.length < min) throw new NotEnoughRoles(min);
+*     });
+* }
+* ```
+*
+* @example
+* ```ts
+* // agnostic gate (no ctx annotation): fits any handler
+* const Owner = defineGate('owner', (ctx) => {
+*     if (!ctx.userId) throw new NotOwner();
+* });
+* ```
+*/
+function defineGate(name, fn) {
+	return {
+		name,
+		check: async (ctx) => fn(ctx)
+	};
+}
+/**
+* Builds an {@link EffectGate} from a `check` and a `commit`. `check` peeks and refuses by throwing, and
+* `commit` applies the side effect, running only once the whole gate set passes so a later refusal never
+* commits. In an `or`, a refusing arm's queued commit is rolled back. This is how {@link Cooldown} peeks
+* in `check` and charges the slot in `commit`.
+*
+* @typeParam Name - The gate's name captured as a literal, so a mismatch error can name the gate.
+* @typeParam Ctx - The context both `check` and `commit` read, inferred from the `ctx` annotation.
+*
+* @param name - The gate's name, used in mismatch errors.
+* @param check - Peeks and refuses by throwing, without applying the side effect.
+* @param commit - Applies the side effect, running only after the whole gate set passes.
+*
+* @see {@link defineGate}
+* @see the `@Gated` decorator from `seedcord`
+* @see {@link Cooldown}
+*
+* @example
+* ```ts
+* // an effect-gate factory that takes its own limit and closes over it
+* function UsesPerDay(max: number): EffectGate<GateContextBase, 'UsesPerDay'> {
+*     return defineEffectGate(
+*         'UsesPerDay',
+*         (ctx) => {
+*             // peek and refuse by throwing, do not mutate yet
+*             if (usedToday(ctx.userId) >= max) throw new OutOfUsesNotice(max);
+*         },
+*         (ctx) => {
+*             // runs only after the whole gate set passes
+*             recordUse(ctx.userId);
+*         }
+*     );
+* }
+* ```
+*/
+function defineEffectGate(name, check, commit) {
+	return {
+		name,
+		check: async (ctx) => check(ctx),
+		commit: async (ctx) => commit(ctx)
+	};
+}
+
+//#endregion
 //#region src/stops/Fault.ts
 /**
 * A generic fault you throw after catching an error you do not have a specific message for.
@@ -40,6 +146,212 @@ var Fault = class extends Notice {
 	}
 };
 
+//#endregion
+//#region src/gates/combinators.ts
+function and(...gates) {
+	return defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
+		for (const gate of gates) await runCheck(gate, ctx);
+	});
+}
+function isOrOptions(arg) {
+	return !("check" in arg);
+}
+function or(...args) {
+	const last = args.at(-1);
+	const options = last !== void 0 && isOrOptions(last) ? last : void 0;
+	const gates = options ? args.slice(0, -1) : args;
+	return defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
+		const summaries = [];
+		let everyArmHasSummary = true;
+		for (const gate of gates) {
+			const mark = markCommits(ctx);
+			try {
+				await runCheck(gate, ctx);
+				return;
+			} catch (error) {
+				if (error instanceof Notice && !(error instanceof Fault) && !error.report) {
+					rollbackCommits(ctx, mark);
+					if (error.summary === void 0) everyArmHasSummary = false;
+					else summaries.push(error.summary);
+					continue;
+				}
+				throw error;
+			}
+		}
+		if (options) throw typeof options.fail === "function" ? options.fail(ctx) : options.fail;
+		if (everyArmHasSummary && summaries.length > 0) throw new NeedsAny(summaries);
+		throw new NotAllowed();
+	});
+}
+
+//#endregion
+//#region src/gates/catalog/access.ts
+/**
+* Passes only for a user id listed in `config.ownerIds`, else refuses.
+*
+* Agnostic, so it attaches to interaction and event handlers alike. With no `ownerIds` configured it refuses every caller. Pass {@link GateNoticeOptions} to reword or replace the refusal.
+*
+* @param options - Reword the default refusal with `message`, or replace it with `notice`.
+*
+* @see the `@Gated` decorator from `seedcord`
+*
+* @example
+* ```ts
+* \@Gated(OwnerOnly())
+* \@SlashRoute('shutdown')
+* class ShutdownHandler extends SlashHandler<'shutdown'> {
+*     async execute() {
+*         // ...
+*     }
+* }
+* ```
+*
+* @example
+* ```ts
+* // reword the refusal, keeping the embed styling
+* OwnerOnly({ message: 'Owners only.' });
+* ```
+*/
+function OwnerOnly(options) {
+	return defineGate("OwnerOnly", (ctx) => {
+		const owners = ctx.core.config.ownerIds ?? [];
+		if (ctx.userId !== null && owners.includes(ctx.userId)) return;
+		throw pickNotice(options, (message) => new NotOwner(message));
+	});
+}
+/**
+* Passes inside a guild, else refuses.
+*
+* Agnostic, so it attaches to any handler kind. Often paired with `RequirePermissions` in an {@link and}.
+*
+* @param options - Reword the default refusal with `message`, or replace it with `notice`.
+*
+* @see the `@Gated` decorator from `seedcord`
+*
+* @example
+* ```ts
+* import { PermissionFlagsBits } from 'discord.js';
+*
+* \@Gated(GuildOnly(), RequirePermissions([PermissionFlagsBits.Administrator]))
+* \@SlashRoute('maintenance')
+* class Maintenance extends SlashHandler<'maintenance'> {
+*     async execute() {
+*         // ...
+*     }
+* }
+* ```
+*/
+function GuildOnly(options) {
+	return defineGate("GuildOnly", (ctx) => {
+		if (ctx.guildId) return;
+		throw pickNotice(options, (message) => new NotInGuild(message));
+	});
+}
+/**
+* Passes in a direct message, else refuses.
+*
+* Agnostic, so it attaches to any handler kind. The inverse of {@link GuildOnly}, so combining the two in an {@link and} can never pass.
+*
+* @param options - Reword the default refusal with `message`, or replace it with `notice`.
+*
+* @see the `@Gated` decorator from `seedcord`
+*
+* @example
+* ```ts
+* \@Gated(DmOnly())
+* \@SlashRoute('verify')
+* class VerifyHandler extends SlashHandler<'verify'> {
+*     async execute() {
+*         // ...
+*     }
+* }
+* ```
+*/
+function DmOnly(options) {
+	return defineGate("DmOnly", (ctx) => {
+		if (!ctx.guildId) return;
+		throw pickNotice(options, (message) => new NotInDm(message));
+	});
+}
+
+//#endregion
+//#region src/gates/catalog/Cooldown.ts
+let bucketSeq = 0;
+function scopeValue(ctx, per) {
+	if (per === "guild") return ctx.guildId ?? "global";
+	if (per === "channel") return ctx.channelId ?? "global";
+	return ctx.userId ?? "global";
+}
+/**
+* Allows `limit` uses per window, scoped by `per`. A number `duration` is **seconds**, a string is
+* a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError** at construction. The
+* slot is charged in commit, only after the whole gate set passes, so a later refusal never burns the cooldown.
+* That split also means two requests racing the same key can both pass before either charges the slot.
+* Each call gets its own bucket, so two handlers never share a window. Reword the refusal with {@link CooldownOptions.message}
+* or replace it with {@link CooldownOptions.notice}.
+*
+* @param duration - A number is seconds, a string is a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError**.
+* @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal text with `message` or `notice`.
+*
+* @see the `@Gated` decorator from `seedcord`
+* @see {@link IRateLimiter}
+*
+* @example
+* ```ts
+* // a number argument is SECONDS
+* \@Gated(Cooldown(5))
+* \@SlashRoute('daily')
+* class DailyHandler extends SlashHandler<'daily'> {
+*     async execute() {
+*         // ...
+*     }
+* }
+* ```
+*
+* @example
+* ```ts
+* // a string is a duration, here scoped per guild (the default is per user)
+* Cooldown('30m', { per: 'guild' });
+* ```
+*
+* @example
+* ```ts
+* // a burst, 3 uses per 10 minutes per user, then it refuses until a slot frees
+* \@Gated(Cooldown('10m', { limit: 3 }))
+* \@SlashRoute('report')
+* class ReportHandler extends SlashHandler<'report'> {
+*     async execute() {
+*         // ...
+*     }
+* }
+* ```
+*/
+function Cooldown(duration, options) {
+	let windowMs;
+	if (typeof duration === "number") windowMs = duration * 1e3;
+	else {
+		const parsed = parseDuration(duration);
+		if (parsed === null) throw new SeedcordTypeError(SeedcordErrorCode.GateInvalidCooldownDuration, [duration]);
+		windowMs = parsed;
+	}
+	if (windowMs <= 0) throw new SeedcordTypeError(SeedcordErrorCode.GateInvalidCooldownDuration, [String(duration)]);
+	const bucket = `cooldown:${bucketSeq++}`;
+	const per = options?.per ?? "user";
+	const window = options?.limit === void 0 ? { windowMs } : {
+		windowMs,
+		limit: options.limit
+	};
+	const keyOf = (ctx) => `${bucket}:${scopeValue(ctx, per)}`;
+	return defineEffectGate("Cooldown", async (ctx) => {
+		const result = await ctx.core.rateLimiter.peek(keyOf(ctx), window);
+		if (!result.limited) return;
+		if (options?.notice) throw options.notice(result.resetAt);
+		throw new OnCooldown(result.resetAt, options?.message?.(result.resetAt));
+	}, async (ctx) => {
+		await ctx.core.rateLimiter.charge(keyOf(ctx), window);
+	});
+}
+
 //#endregion
 //#region src/stops/Silence.ts
 /**
@@ -98,8 +410,8 @@ function paginate(items, page, perPage) {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.0-next.1";
+const version = "0.1.0-next.2";
 
 //#endregion
-export { BuilderComponent, CustomId, Fault, Notice, RowComponent, Silence, paginate, version };
+export { BuilderComponent, Cooldown, CustomId, DmOnly, Fault, GuildOnly, Notice, OwnerOnly, RegisterCommand, RowComponent, Silence, and, defineEffectGate, defineGate, or, paginate, version };
 //# sourceMappingURL=index.mjs.map