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

package/dist/index.d.mts

@@ -1,3 +1,7 @@
+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
 /**
  * Maps each user context-menu command name to a presence marker. Populated by `seedcord codegen`, which
@@ -56,9 +60,323 @@ interface SlashOption {
  */
 interface SlashOptionRegistry {}
 //#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.
+ *
+ * @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 { PermissionFlagsBits } from 'discord.js';
+ *
+ * \@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.
+ *
+ * @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`
+ *
+ * @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.
+ *
+ * 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 {
+  /**
+   * 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 `'user'`
+   */
+  per?: 'user' | 'guild' | 'channel';
+  /**
+   * Uses allowed inside one window before the gate refuses.
+   *
+   * @defaultValue `1`
+   */
+  limit?: number;
+  /**
+   * 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>`.
+   */
+  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;
+}
+/**
+ * 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
+/**
+ * A generic fault you throw after catching an error you do not have a specific message for.
+ *
+ * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to
+ * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`
+ * to show the generic reply without the bus publish. The original error is stored as the standard
+ * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,
+ * subclass {@link Notice} and write your own `render` instead.
+ *
+ * The framework also renders this for an unhandled throw, where it points the user at
+ * `ctx.developerUsername`.
+ *
+ * @example
+ * ```ts
+ * import { Fault } from 'seedcord';
+ *
+ * try {
+ *     await db.write(record);
+ * } catch (cause) {
+ *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook
+ *     throw new Fault({ cause });
+ *
+ *     // pass report: false to show the same reply without publishing to the handledException bus
+ *     // throw new Fault({ cause, report: false });
+ * }
+ * ```
+ */
+declare class Fault extends Notice {
+  constructor(options?: {
+    cause?: unknown;
+    report?: boolean;
+  });
+  render(ctx: RenderContext): ReplyResponse;
+}
+//#endregion
+//#region src/stops/Silence.d.ts
+/**
+ * Throw to stop a handler with no reply and no report.
+ *
+ * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
+ * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
+ * leave the user with no reply for an interaction.
+ *
+ * @example
+ * ```ts
+ * import { Silence } from 'seedcord';
+ *
+ * // 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');
+ * ```
+ */
+declare class Silence extends Error {
+  readonly reason?: string | undefined;
+  /**
+   * @param reason - Optional note written only to a debug log, never shown to the user or reported.
+   */
+  constructor(reason?: string | undefined);
+}
+//#endregion
+//#region src/pagination/PageView.d.ts
+/**
+ * One rendered page of a paginated list.
+ *
+ * @typeParam Item - The item type.
+ */
+interface PageView<Item> {
+  items: Item[];
+  /** Zero-based, already clamped into range. */
+  page: number;
+  perPage: number;
+  /** The total page count, or `undefined` for a cursor source that has no cheap total. */
+  totalPages?: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+}
+//#endregion
+//#region src/pagination/paginate.d.ts
+/**
+ * Pure page math, usable headless. Clamps `page` into range and slices the window.
+ *
+ * @param items - The full list to page over.
+ * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
+ * @param perPage - The page size. Must be a positive integer.
+ * @returns The sliced {@link PageView}, with `totalPages` always known.
+ * @throws SeedcordRangeError when `perPage` is not a positive integer.
+ */
+declare function paginate<Item>(items: readonly Item[], page: number, perPage: number): PageView<Item>;
+//#endregion
 //#region src/index.d.ts
 /** Package version */
 declare const version: string;
 //#endregion
-export { type MessageContextMenuRegistry, type OptionKind, type SlashOption, type SlashOptionRegistry, type UserContextMenuRegistry, 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