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

package/dist/index.d.mts

@@ -1,10 +1,12 @@
-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--QizzBOn.mjs";
+import { ValidDuration } from "@seedcord/utils";
+import { ChannelType } from "discord-api-types/v10";
+import { EpochMs, RenderContext, ReplyResponse } from "@seedcord/types";
 
 //#region src/registries/ContextMenuRegistry.d.ts
 /**
  * Maps each user context-menu command name to a presence marker. Populated by `seedcord codegen`, which
- * reads every command's `toJSON()` and emits a `declare module 'seedcord'` augmentation, so
+ * reads every command's `toJSON()` and emits a `declare module '@seedcord/gateway'` augmentation, so
  * `keyof UserContextMenuRegistry` is the compile-time union of every registered user context-menu name.
  * Do not augment it by hand, run `seedcord codegen`.
  *
@@ -14,7 +16,7 @@ import { RenderContext, ReplyResponse } from "@seedcord/types";
  * @example
  * ```ts
  * // seedcord-gen.d.ts (emitted, committed)
- * declare module 'seedcord' {
+ * declare module '@seedcord/gateway' {
  *   interface UserContextMenuRegistry {
  *     'View Profile': true;
  *   }
@@ -32,7 +34,7 @@ interface UserContextMenuRegistry {}
 interface MessageContextMenuRegistry {}
 //#endregion
 //#region src/registries/SlashOptionRegistry.d.ts
-/** A slash option kind, named for the registry rather than the raw discord.js `ApplicationCommandOptionType` int. */
+/** A slash option kind as a plain string union (`string`, `channel`, ...), keyed to the registry. */
 type OptionKind = 'string' | 'integer' | 'number' | 'boolean' | 'user' | 'channel' | 'role' | 'mentionable' | 'attachment';
 /** The type-relevant shape of one slash option, as emitted by `seedcord codegen` into a registry row. */
 interface SlashOption {
@@ -40,16 +42,17 @@ interface SlashOption {
   required: boolean;
   choices?: readonly (string | number)[];
   autocomplete?: true;
+  channelTypes?: readonly ChannelType[];
 }
 /**
  * Maps each slash route string to its option table. Populated by `seedcord codegen`, which reads every
- * command's `toJSON()` and emits a `declare module 'seedcord'` augmentation, so `keyof SlashOptionRegistry`
+ * command's `toJSON()` and emits a `declare module '@seedcord/gateway'` augmentation, so `keyof SlashOptionRegistry`
  * is the compile-time union of every registered route. Do not augment it by hand, run `seedcord codegen`.
  *
  * @example
  * ```ts
  * // seedcord-gen.d.ts (emitted, committed)
- * declare module 'seedcord' {
+ * declare module '@seedcord/gateway' {
  *   interface SlashOptionRegistry {
  *     ban: { target: { kind: 'user'; required: true }; reason: { kind: 'string'; required: false } };
  *     'demo/setup': { channel: { kind: 'channel'; required: true } };
@@ -59,71 +62,250 @@ interface SlashOption {
  */
 interface SlashOptionRegistry {}
 //#endregion
-//#region src/stops/Notice.d.ts
+//#region src/dispatch/DispatchContext.d.ts
 /**
- * Base class for a user-facing refusal or a reported fault.
+ * The per-dispatch bag. Any code can merge fields into it by declaration merging, the
+ * same pattern as {@link SlashOptionRegistry}. It stays empty until one does, so `keyof DispatchState` is
+ * `never` and the bag is inert.
+ */
+interface DispatchState {}
+/**
+ * A typed bag allocated once per interaction dispatch and handed to the handler. The middleware and i18n
+ * work reads and writes it through {@link DispatchState}. Today the bag is empty, so it only carries the
+ * dispatched `routeId`.
+ */
+declare class DispatchContext {
+  readonly routeId: string | null;
+  private readonly state;
+  constructor(routeId: string | null);
+  set<Key extends keyof DispatchState>(key: Key, value: DispatchState[Key]): void;
+  get<Key extends keyof DispatchState>(key: Key): DispatchState[Key] | undefined;
+}
+//#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
+ * 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.
  *
- * class TooPoor extends Notice {
- *     constructor(private readonly balance: number) {
- *         super(`balance ${balance} is below the cost`);
+ * @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.
+ *
+ * @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`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
  *
- *     render(_ctx: RenderContext): ReplyResponse {
- *         return { components: [new TooPoorCard(this.balance).component] };
+ * @example
+ * ```ts
+ * \@Gated(OwnerOnly())
+ * \@SlashRoute('shutdown')
+ * class ShutdownHandler extends SlashHandler<'shutdown'> {
+ *     async execute() {
+ *         // ...
  *     }
  * }
+ * ```
  *
- * // in a handler, throwing stops the handler and replies with render(ctx)
- * if (wallet.balance < cost) throw new TooPoor(wallet.balance);
+ * @example
+ * ```ts
+ * // reword the refusal, keeping the embed styling
+ * OwnerOnly({ message: 'Owners only.' });
  * ```
  */
-declare abstract class Notice extends Error {
+declare function OwnerOnly(options?: GateNoticeOptions): Gate<GateContextBase, 'OwnerOnly'>;
+/**
+ * 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() {
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+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.
+ * The key combines the handler's route with the window settings, so two different handlers keep separate
+ * windows. 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
 /**
@@ -140,7 +322,7 @@ declare abstract class Notice extends Error {
  *
  * @example
  * ```ts
- * import { Fault } from 'seedcord';
+ * import { Fault } from '@seedcord/gateway';
  *
  * try {
  *     await db.write(record);
@@ -171,7 +353,7 @@ declare class Fault extends Notice {
  *
  * @example
  * ```ts
- * import { Silence } from 'seedcord';
+ * import { Silence } from '@seedcord/gateway';
  *
  * // before any reply or defer, drop the interaction with no reply and no report
  * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');
@@ -218,5 +400,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, DispatchContext, type DispatchState, 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