@seedcord/core 0.12.0-next.0 → 0.12.0-next.2

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { F as Kv, H as InteractionKind, I as KvCollection, K as MiddlewareKind, L as DispatchContext, S as ReplyTelemetry, Y as Notice, _ as ResponseOutcome, a as Bus, b as SubscriptionKey, d as AttemptedWrite, g as ResponseFailed, h as ResponseAttempt, i as CoreBase, m as FaultSource, n as StartupPhase, p as DispatchOutcome, t as ShutdownPhase, u as Subscriber, v as ResponseSent, w as AckState, x as Subscriptions, y as SubscriptionData } from "./phases-Dojnr-ng.mjs";
-import { $ as SlashRouteBrand, A as Gate, B as HandlerOutcome, Bt as UserContextMenuRegistry, C as GateNoticeOptions, D as JoinNames, Dt as RowComponent, E as IntersectRequired, Et as BuilderComponent, F as defineGate, G as RegisterInteractionMiddleware, I as SerializedReply, It as ContextMenuKind, J as ComponentDefsBrand, M as GuildPermissionsContext, N as RequiredOf, O as TwoOrMore, Ot as BuilderType, P as defineEffectGate, Pt as SlashRegistry, R as DispatchResult, Rt as MessageContextMenuRegistry, S as PermissionScope, Tt as RegisterCommand, V as HandlerResult, W as InteractionMiddlewareOptions, X as ContextMenuKindBrand, Y as ComponentKindBrand, Z as ContextMenuNamesBrand, _ as RequirePermissions, a as Subscribe, at as InjectedContextMenuMap, b as RequireRoleOptions, c as PageCursor, d as AutocompleteOptions, et as CommandInfo, g as RequireBotPermissions, h as ResolvedEmoji, i as WebhookFile, it as InjectedCommandMap, j as GateContextBase, k as EffectGate, kt as RowType, n as WebhookLog, nt as ContextMenuInfo, o as SubscribeOptions, q as AutocompleteRouteBrand, r as WebhookReport, rt as ContextMenus, t as WebhookUrl, tt as Commands, v as RequirePermissionsOptions, wt as GuildTarget, y as RequireRole, z as EventDispatchResult, zt as NamesFor } from "./index-Boo33hh3.mjs";
+import { C as AckState, F as KvCollection, H as InteractionKind, I as DispatchContext, K as MiddlewareKind, P as Kv, X as NoticeConstructor, Y as Notice, _ as ResponseSent, a as Bus, b as Subscriptions, d as DispatchOutcome, f as FaultSource, g as ResponseOutcome, h as ResponseFailed, i as CoreBase, l as AttemptedWrite, m as ResponseAttempt, n as StartupPhase, t as ShutdownPhase, v as SubscriptionData, x as ReplyTelemetry, y as SubscriptionKey } from "./phases-C2QCSqRu.mjs";
+import { $ as ContextMenuInfo, A as RequiredOf, C as JoinNames, Ct as BuilderComponent, D as Gate, E as EffectGate, Et as RowType, F as DispatchResult, Ft as MessageContextMenuRegistry, G as ComponentDefsBrand, H as RegisterInteractionMiddleware, I as EventDispatchResult, It as NamesFor, J as ContextMenuNamesBrand, K as ComponentKindBrand, L as HandlerOutcome, Lt as UserContextMenuRegistry, M as defineGate, N as SerializedReply, Nt as ContextMenuKind, O as GateContextBase, Q as Commands, R as HandlerResult, S as IntersectRequired, St as RegisterCommand, T as AppPermissionsContext, Tt as BuilderType, V as InteractionMiddlewareOptions, W as AutocompleteRouteBrand, X as SlashRouteBrand, Z as CommandInfo, a as Subscribe, b as ResolvedEmoji, et as ContextMenus, g as AutocompleteOptions, i as WebhookFile, j as defineEffectGate, jt as SlashRegistry, k as GuildPermissionsContext, n as WebhookLog, nt as InjectedContextMenuMap, o as SubscribeOptions, p as PageCursor, q as ContextMenuKindBrand, r as WebhookReport, s as Subscriber, t as WebhookUrl, tt as InjectedCommandMap, w as TwoOrMore, wt as RowComponent, xt as GuildTarget } from "./index-DGHng1IN.mjs";
 import { n as PluginTypes, t as Generated } from "./Generated-ByC53_A2.mjs";
 import "reflect-metadata";
 import { AnyCustomId, AnyCustomId as AnyCustomId$1, CustomId, CustomIdField, CustomIdShape, DecodedParams, DecodedRoute, FieldOptions, decodeFor, prefixOf, setCustomIdErrors } from "@seedcord/custom-id";
@@ -7,8 +7,9 @@ import { ActionRowBuilder, ButtonBuilder } from "@discordjs/builders";
 import { APIMessageComponentEmoji, APIModalInteractionResponseCallbackData, ApplicationCommandType, ButtonStyle } from "discord-api-types/v10";
 import { Logger } from "@seedcord/logger";
 import { ValidDuration } from "@seedcord/utils";
+import { REST } from "@discordjs/rest";
 import { DeferOpts, EpochMs, KvDriver, KvEntry, LoggerChannelId, RenderContext, ReplyResponse, SendOpts, TypedExtract } from "@seedcord/types";
-import { Constructor, Promisable } from "type-fest";
+import { Constructor, LiteralUnion, Promisable } from "type-fest";
 //#region src/decorators/routes.d.ts
 type ComponentBrand = TypedExtract<InteractionKind, InteractionKind.Button | InteractionKind.Modal | InteractionKind.StringMenu | InteractionKind.UserMenu | InteractionKind.RoleMenu | InteractionKind.ChannelMenu | InteractionKind.MentionableMenu>;
 type AnyHandlerCtor = new (...args: never[]) => unknown;
@@ -30,15 +31,21 @@ type ComponentOf<TCtor extends AnyHandlerCtor> = InstanceType<TCtor> extends {
 type DefsOf<TCtor extends AnyHandlerCtor> = InstanceType<TCtor> extends {
   [ComponentDefsBrand]?: infer Defs extends readonly AnyCustomId$1[];
 } ? Defs : never;
-type AssertSlashRoute<Route extends keyof SlashRegistry, TCtor extends AnyHandlerCtor> = [Route] extends [SlashRouteOf<TCtor>] ? [SlashRouteOf<TCtor>] extends [Route] ? TCtor : Constructor<['SlashHandler declares a route that the SlashRoute decorator does not list', SlashRouteOf<TCtor>]> : Constructor<['SlashRoute does not match the SlashHandler generic', Route]>;
-type AssertAutocompleteRoute<Route extends keyof SlashRegistry, TCtor extends AnyHandlerCtor> = [Route] extends [AutocompleteRouteOf<TCtor>] ? [AutocompleteRouteOf<TCtor>] extends [Route] ? TCtor : Constructor<['AutocompleteHandler declares a command that the AutocompleteRoute decorator does not list', AutocompleteRouteOf<TCtor>]> : Constructor<['AutocompleteRoute does not match the AutocompleteHandler generic', Route]>;
-type AssertContextMenuRoute<Kind extends ContextMenuKind, Names extends NamesFor<Kind>, TCtor extends AnyHandlerCtor> = [Kind] extends [ContextMenuKindOf<TCtor>] ? [ContextMenuKindOf<TCtor>] extends [Kind] ? [Names] extends [ContextMenuNamesOf<TCtor>] ? [ContextMenuNamesOf<TCtor>] extends [Names] ? TCtor : Constructor<['ContextMenuHandler declares a name that the ContextMenuRoute decorator does not list', ContextMenuNamesOf<TCtor>]> : Constructor<['ContextMenuRoute lists a name that the ContextMenuHandler generic does not declare', Names]> : Constructor<['ContextMenuHandler declares a kind that the ContextMenuRoute decorator does not match', ContextMenuKindOf<TCtor>]> : Constructor<['ContextMenuRoute does not match the ContextMenuHandler generic', Kind]>;
-type AssertComponentRoute<Brand extends ComponentBrand, Defs extends readonly AnyCustomId$1[], TCtor extends AnyHandlerCtor> = [ComponentOf<TCtor>] extends [Brand] ? [Brand] extends [ComponentOf<TCtor>] ? [DefsOf<TCtor>] extends [Defs] ? TCtor : Constructor<['the customId definitions do not match the handler generic', DefsOf<TCtor>]> : Constructor<['the decorator does not match the handler kind', ComponentOf<TCtor>]> : Constructor<['the decorator does not match the handler kind', ComponentOf<TCtor>]>;
+type SameSet<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
+type Mismatch<Message extends string, Decorator, Generic> = Constructor<[Message, {
+  decorator: Decorator;
+  generic: Generic;
+}]>;
+type AssertNames<Names extends string, Registered, Declared, Decorator extends string, Handler extends string, TCtor extends AnyHandlerCtor> = [Names] extends [Registered] ? SameSet<Names, Declared> extends true ? TCtor : Mismatch<`${Decorator} does not match the ${Handler} generic`, Names, Declared> : Constructor<[`${Decorator} lists a command that is not registered`, Exclude<Names, Registered>]>;
+type AssertSlashRoute<Route extends string, TCtor extends AnyHandlerCtor> = AssertNames<Route, keyof SlashRegistry, SlashRouteOf<TCtor>, 'SlashRoute', 'SlashHandler', TCtor>;
+type AssertAutocompleteRoute<Route extends string, TCtor extends AnyHandlerCtor> = AssertNames<Route, keyof SlashRegistry, AutocompleteRouteOf<TCtor>, 'AutocompleteRoute', 'AutocompleteHandler', TCtor>;
+type AssertContextMenuRoute<Kind extends ContextMenuKind, Names extends string, TCtor extends AnyHandlerCtor> = SameSet<Kind, ContextMenuKindOf<TCtor>> extends true ? AssertNames<Names, NamesFor<Kind>, ContextMenuNamesOf<TCtor>, 'ContextMenuRoute', 'ContextMenuHandler', TCtor> : Mismatch<'ContextMenuRoute does not match the ContextMenuHandler kind', Kind, ContextMenuKindOf<TCtor>>;
+type AssertComponentRoute<Brand extends ComponentBrand, Defs extends readonly AnyCustomId$1[], TCtor extends AnyHandlerCtor> = SameSet<Brand, ComponentOf<TCtor>> extends true ? [DefsOf<TCtor>] extends [Defs] ? TCtor : Mismatch<'the customId definitions do not match the handler generic', Defs, DefsOf<TCtor>> : Mismatch<'the decorator does not match the handler kind', Brand, ComponentOf<TCtor>>;
 /**
  * Routes one or more slash commands to a `SlashHandler`.
  *
- * Pass the same route string(s) as the handler's generic. A single command reads `this.options`, several
- * commands branch with `this.match`. The decorator routes and the generic must match exactly. Listing
+ * Pass the same route string(s) as the handler's generic. On a handler for one command, read
+ * `this.options`. On a handler for several, branch with `this.match`. The decorator routes and the generic must match exactly. Listing
  * fewer or more than the handler declares is a compile error. Subcommands use a slash path.
  *
  * @param routes - The route string(s) this handler serves, e.g. `'ban'`, `'ban', 'kick'`, or `'demo/setup'`.
@@ -53,12 +60,12 @@ type AssertComponentRoute<Brand extends ComponentBrand, Defs extends readonly An
  * }
  * ```
  */
-export declare function SlashRoute<const Route extends keyof SlashRegistry>(...routes: Route[]): <TCtor extends AnyHandlerCtor>(constructor: AssertSlashRoute<Route, TCtor>) => void;
+export declare function SlashRoute<const Route extends LiteralUnion<keyof SlashRegistry, string>>(...routes: Route[]): <TCtor extends AnyHandlerCtor>(constructor: AssertSlashRoute<Route, TCtor>) => void;
 /**
  * Routes one or more commands' autocomplete to an `AutocompleteHandler`.
  *
  * Pass the same command route string(s) as the handler's generic. One command branches with `this.match`
- * over its autocompletable fields, several commands share one handler whose arms span every command's
+ * over its autocompletable fields, several commands share one handler whose cases span every command's
  * fields. Listing fewer or more commands than the handler declares is a compile error, since the
  * decorator routes and the generic must match exactly.
  *
@@ -74,7 +81,7 @@ export declare function SlashRoute<const Route extends keyof SlashRegistry>(...r
  * }
  * ```
  */
-export declare function AutocompleteRoute<const Route extends keyof SlashRegistry>(...routes: Route[]): <TCtor extends AnyHandlerCtor>(constructor: AssertAutocompleteRoute<Route, TCtor>) => void;
+export declare function AutocompleteRoute<const Route extends LiteralUnion<keyof SlashRegistry, string>>(...routes: Route[]): <TCtor extends AnyHandlerCtor>(constructor: AssertAutocompleteRoute<Route, TCtor>) => void;
 /**
  * Routes one or more user context-menu commands to a `UserContextMenuHandler`.
  *
@@ -93,7 +100,7 @@ export declare function AutocompleteRoute<const Route extends keyof SlashRegistr
  * }
  * ```
  */
-export declare function UserContextMenuRoute<const Names extends NamesFor<ApplicationCommandType.User>>(...names: Names[]): <TCtor extends AnyHandlerCtor>(constructor: AssertContextMenuRoute<ApplicationCommandType.User, Names, TCtor>) => void;
+export declare function UserContextMenuRoute<const Names extends LiteralUnion<NamesFor<ApplicationCommandType.User>, string>>(...names: Names[]): <TCtor extends AnyHandlerCtor>(constructor: AssertContextMenuRoute<ApplicationCommandType.User, Names, TCtor>) => void;
 /**
  * Routes one or more message context-menu commands to a `MessageContextMenuHandler`.
  *
@@ -112,7 +119,7 @@ export declare function UserContextMenuRoute<const Names extends NamesFor<Applic
  * }
  * ```
  */
-export declare function MessageContextMenuRoute<const Names extends NamesFor<ApplicationCommandType.Message>>(...names: Names[]): <TCtor extends AnyHandlerCtor>(constructor: AssertContextMenuRoute<ApplicationCommandType.Message, Names, TCtor>) => void;
+export declare function MessageContextMenuRoute<const Names extends LiteralUnion<NamesFor<ApplicationCommandType.Message>, string>>(...names: Names[]): <TCtor extends AnyHandlerCtor>(constructor: AssertContextMenuRoute<ApplicationCommandType.Message, Names, TCtor>) => void;
 /**
  * Routes button interactions to handler classes.
  *
@@ -140,7 +147,7 @@ export declare function ModalRoute<const Defs extends readonly AnyCustomId$1[]>(
  * Routes string select menu interactions to a `StringMenuHandler`.
  *
  * Pass the {@link CustomId} definition(s) this handler decodes and list the same ones in the handler's
- * generic. The handler reads the chosen option values from `this.values`.
+ * generic. Read the chosen option values from `this.values`.
  *
  * @param defs - The customId definition(s) this handler decodes, one per route.
  * @decorator
@@ -249,12 +256,14 @@ export declare abstract class BaseHandler<Event, TCore extends CoreBase> {
   protected readonly logger: Logger;
   /** The bag for this dispatch. Each interaction gets its own. Every handler for one event shares a single bag. */
   protected readonly dispatch: DispatchContext;
+  /** The route that started this dispatch. Each handler base narrows it to its own routes. */
+  protected readonly route: string;
   protected constructor(event: Event, core: TCore, dispatch: DispatchContext, channel?: LoggerChannelId);
   /**
    * Holds the main logic of your handler. The dispatcher calls it after the handler's gates pass, so a
    * gate that refuses stops `execute()` from running.
    */
-  abstract execute(): Promise<void>;
+  abstract execute(): Promisable<void>;
 }
 //#endregion
 //#region src/reply/BaseReplySender.d.ts
@@ -320,7 +329,7 @@ export declare abstract class BaseReplySender<TMessage extends {
 //#region src/handlers/RepliableHandler.d.ts
 /**
  * Shared base the repliable handlers on both transports extend. Defines the reply members over one sender.
- * A handler builds its own through `buildSender`. A middleware takes the handler's.
+ * The dispatch run builds that sender and passes it to the handler and each middleware.
  *
  * @typeParam Event - The repliable interaction type this handler processes
  * @typeParam TCore - The transport's Core
@@ -333,8 +342,7 @@ export declare abstract class RepliableHandler<Event, TCore extends CoreBase, TM
 }, TNative, TSender extends BaseReplySender<TMessage, TNative>> extends BaseHandler<Event, TCore> {
   /** The reply surface for this interaction. Pass the handler to reply from outside its class. */
   readonly sender: TSender;
-  protected constructor(event: Event, core: TCore, dispatch: DispatchContext, sender?: TSender);
-  protected abstract buildSender(event: Event, core: TCore, dispatch: DispatchContext): TSender;
+  protected constructor(event: Event, core: TCore, dispatch: DispatchContext, sender: TSender);
   /** Send the initial response, exactly once. */
   protected reply(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage>;
   /** Show a "thinking" placeholder, then fill it later with {@link edit}. */
@@ -352,12 +360,12 @@ export declare abstract class RepliableHandler<Event, TCore extends CoreBase, TM
 //#endregion
 //#region src/gates/combinators.d.ts
 /**
- * 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
+ * Runs each gate in order and refuses on the first refusal. Takes two or more gates. The required
+ * context is the intersection of their contexts, so an event-only and an interaction-only gate cannot be
  * combined.
  *
- * @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.
+ * @typeParam Gates - The tuple of two or more gates, run left to right.
+ * @param gates - The gates to run in order, all refused on the first refusal.
  *
  * @see {@link or}
  *
@@ -379,13 +387,13 @@ 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. A handler that matches any one arm fits. When every
- * arm refuses it throws the trailing {@link OrOptions} `fail` if given, else a list built from each
- * refusal's `summary`, else a default refusal. The trailing options object does not count as an arm.
+ * Runs each gate in order and passes on the first gate that passes. Takes two or more gates. The
+ * required context is the union of their contexts. A handler that matches any one gate fits. When every
+ * gate refuses it throws the trailing {@link OrOptions} `fail` if given, else a list built from each
+ * refusal's `summary`, else a default refusal. The trailing options object does not count as a gate.
  *
- * @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.
+ * @typeParam Gates - The tuple of two or more gates, tried left to right.
+ * @param gates - The gates to try in order, with an optional trailing {@link OrOptions} object.
  *
  * @see {@link and}
  *
@@ -404,19 +412,26 @@ export declare function or<Gates extends TwoOrMore<Gate<GateContextBase>>>(...ga
 /**
  * @example
  * ```ts
- * // custom refusal when every arm refuses
+ * // custom refusal when every gate refuses
  * or(OwnerOnly(), RequireRole('123456789012345678'), { fail: new NotAllowedNotice() });
  * ```
  */
 export declare function or<Gates extends TwoOrMore<Gate<GateContextBase>>>(...args: [...Gates, OrOptions]): Gate<RequiredOf<Gates[number]>, JoinNames<Gates, ' | '>>;
 //#endregion
+//#region src/gates/catalog/options.d.ts
+/** The override a gate with a single refusal accepts. */
+interface GateNoticeOptions {
+  /** Your Notice class, constructed and thrown in place of the default refusal. */
+  notice?: NoticeConstructor;
+}
+//#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.
+ * Agnostic, so it attaches to interaction and event handlers alike. With no `ownerIds` configured it refuses every caller. Pass a Notice class as `notice` to replace the refusal.
  *
- * @param options - Reword the default refusal with `message`, or replace it with `notice`.
+ * @param options - Replace the refusal with a Notice class as `notice`.
  *
  * @see the `@Gated` decorator from your transport package
  *
@@ -433,8 +448,8 @@ export declare function or<Gates extends TwoOrMore<Gate<GateContextBase>>>(...ar
  *
  * @example
  * ```ts
- * // reword the refusal, keeping the embed styling
- * OwnerOnly({ message: 'Owners only.' });
+ * // OwnersOnly is your own Notice class
+ * OwnerOnly({ notice: OwnersOnly });
  * ```
  */
 export declare function OwnerOnly(options?: GateNoticeOptions): Gate<GateContextBase, 'OwnerOnly'>;
@@ -443,7 +458,7 @@ export declare function OwnerOnly(options?: GateNoticeOptions): Gate<GateContext
  *
  * Agnostic. 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`.
+ * @param options - Replace the refusal with a Notice class as `notice`.
  *
  * @see the `@Gated` decorator from your transport package
  *
@@ -466,7 +481,7 @@ export declare function GuildOnly(options?: GateNoticeOptions): Gate<GateContext
  *
  * Agnostic, fitting 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`.
+ * @param options - Replace the refusal with a Notice class as `notice`.
  *
  * @see the `@Gated` decorator from your transport package
  *
@@ -486,16 +501,18 @@ export declare function DmOnly(options?: GateNoticeOptions): Gate<GateContextBas
 //#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.
+ * window. `notice` replaces the refusal.
  *
  * @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>.`
- * });
+ * // one use per channel, refusing with your own Notice class
+ * class SlowDown extends Notice {
+ *     public constructor(resetAt: EpochMs) {
+ *         super(`Slow down. Try again <t:${toEpochSeconds(resetAt)}:R>.`);
+ *     }
+ * }
+ *
+ * Cooldown('10s', { per: 'channel', notice: SlowDown });
  * ```
  *
  * @example
@@ -517,16 +534,8 @@ interface CooldownOptions {
    * @defaultValue `1`
    */
   limit?: number;
-  /**
-   * Reword the refusal, keeping the standard notice card. Receives the epoch ms the key frees up, to
-   * show the retry time with `<t:${Math.round(resetAt / 1000)}:R>`.
-   */
-  message?: (resetAt: EpochMs) => string;
-  /**
-   * Replace the refusal Notice entirely, for full control or a translated copy. Receives the epoch ms the
-   * key frees up.
-   */
-  notice?: (resetAt: EpochMs) => Notice;
+  /** Your Notice class, constructed with the epoch ms the key frees up and thrown in place of the default refusal. */
+  notice?: NoticeConstructor<[resetAt: EpochMs]>;
 }
 /**
  * Allows `limit` uses per window, scoped by `per`. A number `duration` is **seconds**, and a string is
@@ -534,10 +543,10 @@ interface CooldownOptions {
  * 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.
  * The key combines the handler's route with the window settings, keeping two different handlers on separate
- * windows. Reword the refusal with {@link CooldownOptions.message} or replace it with {@link CooldownOptions.notice}.
+ * windows. Replace the refusal with {@link CooldownOptions.notice}.
  *
  * @param duration - A number is seconds, and a string is a duration like `30m` or `24h`.
- * @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal text with `message` or `notice`.
+ * @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal with `notice`.
  * @throws A **SeedcordTypeError** when `duration` is a string that doesn't parse.
  * @throws A **SeedcordRangeError** when `duration` is zero or negative.
  *
@@ -576,26 +585,35 @@ interface CooldownOptions {
  */
 export declare function Cooldown(duration: number | ValidDuration, options?: CooldownOptions): EffectGate<GateContextBase, 'Cooldown'>;
 //#endregion
+//#region src/permissions/bits.d.ts
+/**
+ * The permission flag bits a caller or the bot must hold. Pass the `PermissionFlagsBits` values from
+ * `discord-api-types/v10` (or `discord.js`).
+ */
+type PermissionScope = readonly bigint[];
+//#endregion
 //#region src/permissions/assert.d.ts
-/** Replacement notices for the two refusals {@link assertPermissions} raises. */
-interface PermissionNoticeOverrides {
-  missingNotice?: new (message: string | undefined, subject: string, missingPerms: readonly string[]) => Notice;
-  dangerousNotice?: new (message: string | undefined, subject: string, dangerousPerms: readonly string[]) => Notice;
-}
+/**
+ * A Notice class for a permission refusal. seedcord constructs it with the subject and the permission names
+ * the refusal lists. A null subject is the caller.
+ */
+type PermissionNoticeConstructor = NoticeConstructor<[subject: string | null, permissions: readonly string[]]>;
 /** The check {@link assertPermissions} runs. */
-interface PermissionAssertion extends PermissionNoticeOverrides {
-  /** Mention string for who is checked, used as the refusal's subject. */
-  subject: string;
+interface PermissionAssertion {
+  /** Mention string for who is checked, used as the refusal's subject. Null addresses the caller. */
+  subject: string | null;
   /** The effective permission bitfield the subject holds, computed by the caller. */
   permissions: bigint;
   /** The permission flag bits to check. */
   scope: PermissionScope;
   /** Refuse when the subject holds a scope bit. */
   inverse?: boolean;
+  /** Your Notice class, thrown in place of the default refusal. seedcord constructs it with the missing names, or the held ones under `inverse`. */
+  notice?: PermissionNoticeConstructor | undefined;
 }
 /**
  * Refuses when the subject is missing a permission in `scope`, or with `inverse` when it holds one.
- * The Administrator bit passes any scope, and on the inverse arm it reports every bit in `scope`.
+ * The Administrator bit passes any scope, and with `inverse` it reports every bit in `scope`.
  *
  * The caller computes `permissions`, gateway off a discord.js role, member, or channel, and HTTP off the
  * bitfield the interaction payload carries.
@@ -640,14 +658,12 @@ interface PermissionAssertion extends PermissionNoticeOverrides {
  * ```ts
  * import { Notice } from '@seedcord/core';
  *
- * // a replacement notice takes the same three arguments the default one does
  * class CannotBan extends Notice {
  *     public constructor(
- *         message: string | undefined,
- *         private readonly subject: string,
+ *         private readonly subject: string | null,
  *         private readonly missing: readonly string[]
  *     ) {
- *         super(message ?? 'You cannot ban here.');
+ *         super('You cannot ban here.');
  *     }
  *
  *     public render(): ReplyResponse {
@@ -659,11 +675,140 @@ interface PermissionAssertion extends PermissionNoticeOverrides {
  *     subject: `<@${member.id}>`,
  *     permissions: member.permissions.bitfield,
  *     scope: [PermissionFlagsBits.BanMembers],
- *     missingNotice: CannotBan
+ *     notice: CannotBan
  * });
  * ```
  */
-export declare function assertPermissions(check: PermissionAssertion): void;
+export declare function assertPermissions({ subject, permissions, scope, inverse, notice }: PermissionAssertion): void;
+//#endregion
+//#region src/gates/catalog/permissions.d.ts
+/**
+ * Options for {@link RequireBotPermissions}.
+ */
+interface RequireBotPermissionsOptions {
+  /**
+   * The set the check reads. `'channel'` reads the effective channel set the payload carries, what
+   * Discord enforces in the invoked channel. `'guild'` reads the base set from roles, available on the
+   * gateway transport only.
+   *
+   * @defaultValue `'channel'`
+   */
+  in?: 'channel' | 'guild';
+  /** Your Notice class, constructed and thrown in place of the refusal outside a guild. */
+  notInGuild?: NoticeConstructor;
+  /** Your Notice class, constructed and thrown in place of the refusal when a permission is missing. */
+  missing?: PermissionNoticeConstructor;
+}
+/**
+ * Options for {@link RequirePermissions}.
+ */
+interface RequirePermissionsOptions extends RequireBotPermissionsOptions {
+  /** Your Notice class, constructed and thrown in place of the refusal when the member's permissions are unavailable inside a guild. */
+  unresolved?: NoticeConstructor;
+}
+/**
+ * Options for {@link RequireRole}.
+ */
+interface RequireRoleOptions {
+  /** Your Notice class, constructed and thrown in place of the refusal outside a guild. */
+  notInGuild?: NoticeConstructor;
+  /** Your Notice class, constructed with the role id and thrown in place of the refusal when the caller lacks the role. */
+  missingRole?: NoticeConstructor<[roleId: string]>;
+}
+/**
+ * Requires the caller to hold every permission in `scope`. Refuses outside a guild first, then when the
+ * member's permissions are unavailable, then when a permission is missing. The Administrator bit passes any
+ * scope.
+ *
+ * The default `'channel'` scope reads the effective channel set the payload carries, what Discord enforces
+ * in the invoked channel. The `'guild'` scope reads the base set from roles and requires a
+ * {@link GuildPermissionsContext}, so it fits a gateway handler only.
+ *
+ * @param scope - The permission flag bits the caller must all hold.
+ * @param options - Pick the scope with `in`. Replace a refusal with a Notice class as `notInGuild`, `unresolved`, or `missing`.
+ *
+ * @see the `@Gated` decorator from your transport package
+ *
+ * @example
+ * ```ts
+ * import { PermissionFlagsBits } from 'discord-api-types/v10';
+ *
+ * \@Gated(RequirePermissions([PermissionFlagsBits.BanMembers]))
+ * \@SlashRoute('ban')
+ * class BanHandler extends SlashHandler<'ban'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // the base set from roles, on a gateway handler
+ * RequirePermissions([PermissionFlagsBits.BanMembers], { in: 'guild' });
+ * ```
+ */
+export declare function RequirePermissions(scope: PermissionScope, options: RequirePermissionsOptions & {
+  in: 'guild';
+}): Gate<GuildPermissionsContext, 'RequirePermissions'>;
+export declare function RequirePermissions(scope: PermissionScope, options?: RequirePermissionsOptions & {
+  in?: 'channel';
+}): Gate<GateContextBase, 'RequirePermissions'>;
+/**
+ * Requires the bot to hold every permission in `scope`. Refuses outside a guild first, then when a
+ * permission is missing. The Administrator bit passes any scope.
+ *
+ * The default `'channel'` scope reads the bot's effective channel set (wire `app_permissions`), what
+ * Discord enforces in the invoked channel. The `'guild'` scope reads the bot's base set from roles and
+ * requires a {@link GuildPermissionsContext}, fitting a gateway handler only. The channel scope requires an
+ * {@link AppPermissionsContext}. An event handler takes `in: 'guild'`.
+ *
+ * @param scope - The permission flag bits the bot must all hold.
+ * @param options - Pick the scope with `in`. Replace a refusal with a Notice class as `notInGuild` or `missing`.
+ * @throws A **SeedcordError** when the `'guild'` scope runs and the bot's own member isn't cached.
+ *
+ * @see the `@Gated` decorator from your transport package
+ *
+ * @example
+ * ```ts
+ * import { PermissionFlagsBits } from 'discord-api-types/v10';
+ *
+ * \@Gated(RequireBotPermissions([PermissionFlagsBits.ManageMessages]))
+ * \@SlashRoute('purge')
+ * class PurgeHandler extends SlashHandler<'purge'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+export declare function RequireBotPermissions(scope: PermissionScope, options: RequireBotPermissionsOptions & {
+  in: 'guild';
+}): Gate<GuildPermissionsContext, 'RequireBotPermissions'>;
+export declare function RequireBotPermissions(scope: PermissionScope, options?: RequireBotPermissionsOptions & {
+  in?: 'channel';
+}): Gate<AppPermissionsContext, 'RequireBotPermissions'>;
+/**
+ * Requires the caller to hold `roleId`, read from the member's role ids. Refuses outside a guild first,
+ * then when the role is missing. Roles are guild-global, so there is no scope dimension.
+ *
+ * @param roleId - The role snowflake the caller must hold.
+ * @param options - Replace a refusal with a Notice class as `notInGuild` or `missingRole`.
+ *
+ * @see the `@Gated` decorator from your transport package
+ *
+ * @example
+ * ```ts
+ * \@Gated(RequireRole('123456789012345678'))
+ * \@SlashRoute('vip')
+ * class VipHandler extends SlashHandler<'vip'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+export declare function RequireRole(roleId: string, options?: RequireRoleOptions): Gate<GateContextBase, 'RequireRole'>;
 //#endregion
 //#region src/permissions/mergeRoles.d.ts
 /**
@@ -1001,5 +1146,5 @@ export declare function buildKey(prefix: string, ...parts: readonly (string | nu
 /** Package version */
 export declare const version: string;
 //#endregion
-export { type AnyCustomId, type AttemptedWrite, type AutocompleteOptions, BuilderComponent, type BuilderType, Bus, type CommandInfo, Commands, type ContextMenuInfo, ContextMenus, type ControlCosmetics, type ControlKey, type CooldownOptions, type CoreBase, CustomId, type CustomIdField, type CustomIdShape, type DecodedParams, type DecodedRoute, DispatchContext, type DispatchOutcome, type DispatchResult, type EffectGate, type EventDispatchResult, type FaultSource, type FieldOptions, type Gate, type GateContextBase, type GateNoticeOptions, type Generated, type GuildPermissionsContext, type GuildTarget, type HandlerOutcome, type HandlerResult, type InjectedCommandMap, type InjectedContextMenuMap, InteractionKind, type InteractionMiddlewareOptions, type ItemRender, type Kv, type KvCollection, type MessageContextMenuRegistry, type MiddlewareKind, type ModalLike, Notice, type PageRender, type PageSourceBase, type PageView, type PaginatorConfig, type PaginatorControls, type PermissionAssertion, type PermissionNoticeOverrides, type PermissionScope, type PluginTypes, RegisterCommand, RegisterInteractionMiddleware, RequireBotPermissions, RequirePermissions, type RequirePermissionsOptions, RequireRole, type RequireRoleOptions, type RequiredOf, ResolvedEmoji, type ResponseAttempt, type ResponseFailed, type ResponseOutcome, type ResponseSent, RowComponent, type RowType, ShutdownPhase, type SlashRegistry, StartupPhase, Subscribe, type SubscribeOptions, Subscriber, type SubscriptionData, type SubscriptionKey, type Subscriptions, type UserContextMenuRegistry, type WebhookFile, WebhookLog, type WebhookReport, WebhookUrl, decodeFor, defineEffectGate, defineGate, prefixOf, setCustomIdErrors };
+export { type AnyCustomId, type AppPermissionsContext, type AttemptedWrite, type AutocompleteOptions, BuilderComponent, type BuilderType, Bus, type CommandInfo, Commands, type ContextMenuInfo, ContextMenus, type ControlCosmetics, type ControlKey, type CooldownOptions, type CoreBase, CustomId, type CustomIdField, type CustomIdShape, type DecodedParams, type DecodedRoute, type DispatchContext, type DispatchOutcome, type DispatchResult, type EffectGate, type EventDispatchResult, type FaultSource, type FieldOptions, type Gate, type GateContextBase, type GateNoticeOptions, type Generated, type GuildPermissionsContext, type GuildTarget, type HandlerOutcome, type HandlerResult, type InjectedCommandMap, type InjectedContextMenuMap, InteractionKind, type InteractionMiddlewareOptions, type ItemRender, type Kv, type KvCollection, type MessageContextMenuRegistry, type MiddlewareKind, type ModalLike, Notice, type NoticeConstructor, type PageRender, type PageSourceBase, type PageView, type PaginatorConfig, type PaginatorControls, type PermissionAssertion, type PermissionNoticeConstructor, type PermissionScope, type PluginTypes, type REST, RegisterCommand, RegisterInteractionMiddleware, type RequireBotPermissionsOptions, type RequirePermissionsOptions, type RequireRoleOptions, type RequiredOf, ResolvedEmoji, type ResponseAttempt, type ResponseFailed, type ResponseOutcome, type ResponseSent, RowComponent, type RowType, ShutdownPhase, type SlashRegistry, StartupPhase, Subscribe, type SubscribeOptions, Subscriber, type SubscriptionData, type SubscriptionKey, type Subscriptions, type UserContextMenuRegistry, type WebhookFile, WebhookLog, type WebhookReport, WebhookUrl, decodeFor, defineEffectGate, defineGate, prefixOf, setCustomIdErrors };
 //# sourceMappingURL=index.d.mts.map