@seedcord/core 0.1.0-next.4 → 0.1.0-next.5

package/dist/{CustomId--QizzBOn.d.mts → AutocompleteOptions-eB87SZ4a.d.mts}

@@ -1,7 +1,37 @@
+import { t as IsNever } from "./is-never-Ddaba1Su.mjs";
+import { APIMessageTopLevelComponent, APIModalInteractionResponseCallbackData, ApplicationCommandType, ChannelType, Snowflake } from "discord-api-types/v10";
 import { ActionRowBuilder, ButtonBuilder, ChannelSelectMenuBuilder, CheckboxBuilder, CheckboxGroupBuilder, CheckboxGroupOptionBuilder, ContainerBuilder, ContextMenuCommandBuilder, EmbedBuilder, FileBuilder, FileUploadBuilder, LabelBuilder, MediaGalleryBuilder, MentionableSelectMenuBuilder, ModalBuilder, RadioGroupBuilder, RadioGroupOptionBuilder, RoleSelectMenuBuilder, SectionBuilder, SeparatorBuilder, SlashCommandBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, TextDisplayBuilder, TextInputBuilder, UserSelectMenuBuilder } from "@discordjs/builders";
-import { Snowflake } from "discord-api-types/v10";
-import { Config, IRateLimiter, RenderContext, ReplyResponse } from "@seedcord/types";
+import { Config, DeferOpts, IRateLimiter, RenderContext, ReplyResponse, SendOpts } from "@seedcord/types";
 
+//#region src/registries/SlashOptionRegistry.d.ts
+/** 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 {
+  kind: OptionKind;
+  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/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/gateway' {
+ *   interface SlashOptionRegistry {
+ *     ban: { target: { kind: 'user'; required: true }; reason: { kind: 'string'; required: false } };
+ *     'demo/setup': { channel: { kind: 'channel'; required: true } };
+ *   }
+ * }
+ * ```
+ */
+interface SlashOptionRegistry {}
+//#endregion
 //#region src/components/builderTypes.d.ts
 /**
  * Available Discord.js builder classes for use with BuilderComponent for commands, embeds, modals, etc.
@@ -189,6 +219,214 @@ declare function RegisterCommand(scope: 'global'): (ctor: CommandCtor) => void;
  */
 declare function RegisterCommand(scope: 'guild', guilds: string[]): (ctor: CommandCtor) => void;
 //#endregion
+//#region src/metadataKeys.d.ts
+declare enum InteractionRoutes {
+  Slash = "slash",
+  Button = "button",
+  Modal = "modal",
+  StringMenu = "stringMenu",
+  UserMenu = "userMenu",
+  RoleMenu = "roleMenu",
+  ChannelMenu = "channelMenu",
+  MentionableMenu = "mentionableMenu",
+  MessageContextMenu = "messageContextMenu",
+  UserContextMenu = "userContextMenu",
+  Autocomplete = "autocomplete"
+}
+declare const InteractionMetadataKey: unique symbol;
+declare const InteractionRouteKeys: Record<InteractionRoutes, symbol>;
+declare const MiddlewareMetadataKey: unique symbol;
+declare const EventMetadataKey: unique symbol;
+declare const CommandMetadataKey: unique symbol;
+declare const GatedMetadataKey: unique symbol;
+declare const SubscribeMetadataKey: unique symbol;
+declare const WebhookUrlMetadataKey: unique symbol;
+//#endregion
+//#region src/customId/Field.d.ts
+/**
+ * One field in a customId shape, its wire kind plus the type it decodes to.
+ *
+ * @internal
+ */
+interface CustomIdField<Decoded> {
+  /** Which wire encoding this field uses. */
+  readonly kind: 'snowflake' | 'uuid' | 'int' | 'bool' | 'oneOf' | 'string';
+  /** Lower bound, for a bounded int field. */
+  readonly min?: number;
+  /** Upper bound, for a bounded int field. */
+  readonly max?: number;
+  /** The allowed values, for a oneOf field. */
+  readonly choices?: readonly string[];
+  /** Phantom only, carries the decoded type and is never set at runtime. */
+  readonly decoded?: Decoded;
+}
+/**
+ * The set of fields a customId carries, keyed by name.
+ *
+ * @internal
+ */
+type CustomIdShape = Record<string, CustomIdField<unknown>>;
+/**
+ * The decoded result, each field name mapped to its decoded type.
+ *
+ * @internal
+ */
+type DecodedParams<Shape extends CustomIdShape> = { [Name in keyof Shape]: Shape[Name] extends CustomIdField<infer Decoded> ? Decoded : never };
+//#endregion
+//#region src/customId/CustomId.d.ts
+/** Strip the layout hash off the routeKey to recover the stable prefix the controller routes by. @internal */
+declare function prefixOf(wire: string): string;
+/**
+ * A typed customId. The single source of truth shared by the component that mints it and the handler
+ * that reads it. This gives you typed reads on the `.customId` field in components. Values are packed into a compact wire string rather than plain stringified tokens, so the 100-char Discord limit goes further. More string per string, basically.
+ *
+ * @typeParam Prefix - The stable route prefix, e.g. 'approve'.
+ * @typeParam Shape - The accumulated fields, filled in by the chain.
+ *
+ * @example
+ * ```ts
+ * const ApproveId = new CustomId('approve')
+ *     .snowflake('userId')
+ *     .oneOf('action', ['approve', 'deny']);
+ *
+ * // Set the custom id on a button when creating it.
+ * new ButtonBuilder().setCustomId(ApproveId.encode({ userId: '123', action: 'approve' }));
+ *
+ * // reading in the handler: userId comes back a string
+ * const { userId, action } = this.params; // userId: string, action: 'approve' | 'deny'
+ * await this.event.guild?.members.fetch(userId);
+ * ```
+ */
+declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}> {
+  /** The stable route prefix, e.g. 'approve'. */
+  readonly prefix: Prefix;
+  /** Like a zod shape */
+  readonly shape: Shape;
+  /** The prefix plus a short hash of the shape, the part of the wire before the colon. */
+  readonly routeKey: string;
+  constructor(prefix: Prefix, shape?: Shape);
+  private add;
+  /**
+   * Add a Discord ID field, decoded as a string (the `Snowflake` type from discord-api-types).
+   *
+   * @example
+   * ```ts
+   * new CustomId('ban').snowflake('userId');
+   * ```
+   */
+  snowflake<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<Snowflake>>>;
+  /**
+   * Add a UUID field, decoded as a lowercase uuid string.
+   *
+   * @example
+   * ```ts
+   * new CustomId('ticket').uuid('ticketId');
+   * ```
+   */
+  uuid<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
+  /**
+   * Add an integer field with no bounds, for a value up to 2^53.
+   *
+   * @example
+   * ```ts
+   * new CustomId('shop').int('amount');
+   * ```
+   */
+  int<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  /**
+   * Add an integer field bounded by min and max, so it packs into fewer characters on the wire.
+   *
+   * @example
+   * ```ts
+   * new CustomId('paginate').int('page', 1, 50);
+   * ```
+   */
+  int<Name extends string>(name: Name, min: number, max: number): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  /**
+   * Add a boolean flag.
+   *
+   * @example
+   * ```ts
+   * new CustomId('settings').bool('silent');
+   * ```
+   */
+  bool<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<boolean>>>;
+  /**
+   * Add a field that is one value from a fixed list, decoded as the literal union. No `as const` needed.
+   *
+   * @example
+   * ```ts
+   * new CustomId('poll').oneOf('choice', ['yes', 'no', 'abstain']);
+   * ```
+   */
+  oneOf<Name extends string, const Choices extends NonEmptyTuple<string>>(name: Name, choices: Choices): CustomId<Prefix, Shape & Record<Name, CustomIdField<Choices[number]>>>;
+  /**
+   * Add a free short text field. Avoid it where possible, it cannot be packed so it costs the most wire space.
+   *
+   * @example
+   * ```ts
+   * new CustomId('note').str('message');
+   * ```
+   */
+  str<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
+  /**
+   * Mint a wire string from values. Throws if a value is out of its field's range or the wire is over 100 chars.
+   *
+   * @param values - One value per field, typed by the chain.
+   * @returns The wire string to put on the component's customId.
+   */
+  encode(values: DecodedParams<Shape>): string;
+  /**
+   * Read a wire string back into values.
+   *
+   * - This will refuse with a default Notice when the shape changed since the wire was minted.
+   * - Or refuse with a different default Notice on a corrupt or foreign wire.
+   *
+   * @param wire - The customId string from the interaction.
+   * @returns The decoded values, typed by the chain.
+   */
+  decode(wire: string): DecodedParams<Shape>;
+  /** True if this wire was minted from this customId's prefix, ignoring the shape hash. */
+  owns(wire: string): boolean;
+}
+/**
+ * Any customId, for places where the exact prefix and shape do not matter.
+ *
+ * @internal
+ */
+type AnyCustomId = CustomId<string, CustomIdShape>;
+/**
+ * The outcome of decoding a wire against several customIds, the matched prefix paired with its values.
+ *
+ * @internal
+ */
+type DecodedRoute<Defs extends readonly AnyCustomId[]> = { [Index in keyof Defs]: Defs[Index] extends AnyCustomId ? {
+  readonly prefix: Defs[Index]['prefix'];
+  readonly params: DecodedParams<Defs[Index]['shape']>;
+} : never }[number];
+/**
+ * Find the customId whose prefix owns this wire, decode against it, and report which one matched.
+ *
+ * @internal
+ */
+declare function decodeFor<Defs extends readonly AnyCustomId[]>(defs: Defs, wire: string): DecodedRoute<Defs>;
+//#endregion
+//#region src/decorators/interactionRoutes.d.ts
+/** The select menu kinds the select route decorators take. */
+declare enum SelectMenuKind {
+  String = "string",
+  User = "user",
+  Role = "role",
+  Channel = "channel",
+  Mentionable = "mentionable"
+}
+type RoutableConstructor = new (...args: never[]) => unknown;
+declare function areRoutes(routes: unknown): routes is string[];
+declare function storeInteractionRoute(route: InteractionRoutes, routes: string | readonly string[], constructor: RoutableConstructor): void;
+declare function storeComponentRoute(route: InteractionRoutes, defs: readonly AnyCustomId[], constructor: RoutableConstructor): void;
+declare function selectMenuRouteOf(kind: SelectMenuKind): InteractionRoutes;
+declare function contextMenuRouteOf(kind: ApplicationCommandType.User | ApplicationCommandType.Message): InteractionRoutes;
+//#endregion
 //#region src/interfaces/CoreBase.d.ts
 /**
  * The transport-agnostic slice of the running framework, what core code (gates, notices, plugins'
@@ -202,11 +440,90 @@ interface CoreBase {
   readonly rateLimiter: IRateLimiter;
 }
 //#endregion
+//#region src/reply/AckTrace.d.ts
+/** The first ack's stack, passed as the throw cause so a double-ack points to both lines. */
+declare class AckTrace extends Error {
+  constructor(method: ReplyMethod);
+}
+//#endregion
+//#region src/reply/ackLegality.d.ts
+type AckState = 'unacked' | 'deferred-reply' | 'deferred-update' | 'replied';
+type ReplyMethod = 'reply' | 'defer' | 'deferUpdate' | 'update' | 'followUp' | 'edit' | 'delete' | 'send' | 'showModal';
+/** Throws before any API call. `ackedBy` becomes the throw cause, its stack points at the first ack. */
+declare function checkAckLegality(method: ReplyMethod, state: AckState, routeId: string, ackedBy?: AckTrace): void;
+declare function sendTarget(state: AckState): 'reply' | 'edit' | 'followUp';
+//#endregion
+//#region src/reply/serializeReply.d.ts
+/** Serialized message data the transport wire writers consume. */
+interface SerializedReply {
+  readonly components: APIMessageTopLevelComponent[];
+  readonly allowedMentions?: ReplyResponse['allowedMentions'];
+  readonly files?: ReplyResponse['files'];
+}
+/** Wraps a string in a TextDisplay component. */
+declare function serializeReply(response: ReplyResponse | string, routeId: string): SerializedReply;
+//#endregion
+//#region src/reply/BaseReplySender.d.ts
+/** The shape djs modal builders emit from `toJSON()`. */
+interface ModalLike {
+  toJSON(): APIModalInteractionResponseCallbackData;
+}
+/**
+ * Tracks acknowledgement state and throws a translated `SeedcordError` on an illegal verb before any
+ * transport call. Verbs execute the legality check, control the transport wire writer, then update the
+ * state and ack trace. Each transport binds `TMessage` to its created-message lens and supplies the
+ * writers.
+ */
+declare abstract class BaseReplySender<TMessage extends {
+  id: string;
+}> {
+  protected readonly routeId: string;
+  private state;
+  private readonly sent;
+  private ackedBy?;
+  protected constructor(routeId: string, initialState?: AckState);
+  reply(response: ReplyResponse | string, opts?: SendOpts): Promise<TMessage>;
+  defer(opts?: DeferOpts): Promise<void>;
+  deferUpdate(): Promise<void>;
+  /**
+   * After a deferUpdate the state stays deferred-update, so the rewrite repeats. The returned message
+   * is the source message, editable only through a bare `update` or `edit`. A targeted `edit` or `delete`
+   * of it throws the foreign-target error.
+   */
+  update(response: ReplyResponse | string): Promise<TMessage>;
+  followUp(response: ReplyResponse | string, opts?: SendOpts): Promise<TMessage>;
+  edit(response: ReplyResponse | string): Promise<TMessage>;
+  edit(target: TMessage, response: ReplyResponse | string): Promise<TMessage>;
+  delete(): Promise<void>;
+  delete(target: TMessage): Promise<void>;
+  /** Routes to the verb the current ack state permits. Every state has a route, so the illegal-ack throw is unreachable. */
+  send(response: ReplyResponse | string, opts?: SendOpts): Promise<TMessage>;
+  /** Must be the initial response. */
+  showModal(modal: ModalLike): Promise<void>;
+  protected serialize(response: ReplyResponse | string): SerializedReply;
+  protected remember(created: TMessage): TMessage;
+  private requireMessage;
+  private editOriginal;
+  private checkLegality;
+  private transition;
+  protected guardModalSource(): void;
+  protected abstract writeReply(response: ReplyResponse | string, opts?: SendOpts): Promise<TMessage | undefined>;
+  protected abstract writeDefer(opts?: DeferOpts): Promise<void>;
+  protected abstract writeDeferUpdate(): Promise<void>;
+  protected abstract writeUpdate(response: ReplyResponse | string): Promise<TMessage | undefined>;
+  protected abstract writeFollowUp(response: ReplyResponse | string, opts?: SendOpts): Promise<TMessage>;
+  protected abstract writeEditOriginal(response: ReplyResponse | string): Promise<TMessage>;
+  protected abstract writeEditTarget(targetId: string, response: ReplyResponse | string): Promise<TMessage>;
+  protected abstract writeDeleteOriginal(): Promise<void>;
+  protected abstract writeDeleteTarget(targetId: string): Promise<void>;
+  protected abstract writeModal(data: APIModalInteractionResponseCallbackData): Promise<void>;
+}
+//#endregion
 //#region src/gates/Gate.d.ts
 /**
  * The transport-agnostic gate context, the scalar identity of the acting user resolvable from any
  * transport's payload. Every field except `core` is nullable, since an event or DM may carry no
- * guild or member. Each transport extends it with its own rich arm. For e.g., the gateway adds the djs
+ * guild or member. Each transport extends it with its own arm. For example, the gateway adds the djs
  * `user`/`guild`/`member` objects and the live interaction or event payload.
  *
  * @example
@@ -236,13 +553,39 @@ interface GateContextBase {
    * channel-scoped permissions the payload contains, on a gateway event the member's guild-level ones.
    */
   readonly memberPermissions: bigint | null;
+  /**
+   * The bot's permissions in the invoked channel, the wire `app_permissions` value. Null on gateway events.
+   */
+  readonly appPermissions: bigint | null;
   /**
    * The dispatched handler as `kind:route` (`slash:daily`, `button:confirm`), or null off a route (a
-   * plain event handler, or a gate run outside a handler). `runHandlerGates` populates it from the handler's
+   * plain event handler, or a gate run outside a handler). `runHandlerGates` sets it from the handler's
    * metadata. `Cooldown` uses it so its window is stable across restarts and isolates.
    */
   readonly routeId: string | null;
 }
+/**
+ * The context the guild-scoped permission gates require. It adds the base permission sets computed from
+ * roles alone, which only the gateway transport can provide from its cache. The http transport's context
+ * does not define these fields.
+ *
+ * @example
+ * ```ts
+ * // in:'guild' returns a Gate<GuildPermissionsContext>, which fits only a gateway handler
+ * \@Gated(RequirePermissions([PermissionFlagsBits.BanMembers], { in: 'guild' }))
+ * ```
+ */
+interface GuildPermissionsContext extends GateContextBase {
+  /**
+   * The member's base permission set, roles only, matching djs `GuildMember.permissions`. Null when the
+   * member is unavailable.
+   */
+  readonly memberGuildPermissions: bigint | null;
+  /**
+   * The bot's base permission set from the transport's cache. Null when the cached member is unavailable.
+   */
+  readonly appGuildPermissions: bigint | null;
+}
 declare const GateBrand: unique symbol;
 /**
  * A precondition attached to a handler. It refuses by throwing a `Notice` (a reply) or a `Silence`
@@ -462,10 +805,9 @@ type GateFitsWith<Provided, ProvidedLabel extends string, TGate, ReqLabel extend
 //#endregion
 //#region src/gates/catalog/options.d.ts
 /**
- * The override a catalog gate accepts, a one-line `message` reword or a full `notice` replacement. Accepted by
- * the agnostic gates ({@link OwnerOnly}, {@link GuildOnly}, {@link DmOnly}, {@link Cooldown}) and the gateway's
- * `RequireRole` and `Nsfw`. The gateway's `RequirePermissions` and `RequireBotPermissions` take
- * `RequirePermissionsOptions` instead.
+ * The override a catalog gate accepts. A one-line `message` reword or a full `notice` replacement. Accepted by
+ * the agnostic catalog gates and, nested per refusal, by {@link RequireRole}. {@link RequirePermissions} and
+ * {@link RequireBotPermissions} take `RequirePermissionsOptions` instead.
  *
  * @example
  * ```ts
@@ -487,174 +829,172 @@ interface GateNoticeOptions {
 }
 declare function pickNotice(options: GateNoticeOptions | undefined, makeDefault: (message?: string) => Notice): Notice;
 //#endregion
-//#region src/customId/Field.d.ts
+//#region src/gates/catalog/permissions.d.ts
 /**
- * One field in a customId shape, its wire kind plus the type it decodes to.
- *
- * @internal
+ * The permission flag bits a caller or the bot must hold. Pass the `PermissionFlagsBits` values from
+ * `discord-api-types/v10` (or `discord.js`).
  */
-interface CustomIdField<Decoded> {
-  /** Which wire encoding this field uses. */
-  readonly kind: 'snowflake' | 'uuid' | 'int' | 'bool' | 'oneOf' | 'string';
-  /** Lower bound, for a bounded int field. */
-  readonly min?: number;
-  /** Upper bound, for a bounded int field. */
-  readonly max?: number;
-  /** The allowed values, for a oneOf field. */
-  readonly choices?: readonly string[];
-  /** Phantom only, carries the decoded type and is never set at runtime. */
-  readonly decoded?: Decoded;
-}
+type PermissionScope = readonly bigint[];
+/** Permission bit to its prettified human-readable name, for the missing-permission refusal. */
+declare const PermissionNames: Map<bigint, string>;
 /**
- * The set of fields a customId carries, keyed by name.
- *
- * @internal
+ * Options for {@link RequirePermissions} and {@link RequireBotPermissions}.
  */
-type CustomIdShape = Record<string, CustomIdField<unknown>>;
+interface RequirePermissionsOptions {
+  /**
+   * 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';
+  /** Reword or replace the refusal shown when the set is unavailable (outside a guild, or unresolved inside one). */
+  notInGuild?: GateNoticeOptions;
+  /** Reword or replace the refusal shown when a permission is missing. */
+  missing?: GateNoticeOptions;
+}
 /**
- * The decoded result, each field name mapped to its decoded type.
- *
- * @internal
+ * Options for {@link RequireRole}.
  */
-type DecodedParams<Shape extends CustomIdShape> = { [Name in keyof Shape]: Shape[Name] extends CustomIdField<infer Decoded> ? Decoded : never };
-//#endregion
-//#region src/customId/CustomId.d.ts
-/** Strip the layout hash off the routeKey to recover the stable prefix the controller routes by. @internal */
-declare function prefixOf(wire: string): string;
+interface RequireRoleOptions {
+  /** Reword or replace the refusal shown outside a guild. */
+  notInGuild?: GateNoticeOptions;
+  /** Reword or replace the refusal shown when the caller lacks the role. */
+  missingRole?: GateNoticeOptions;
+}
 /**
- * A typed customId. The single source of truth shared by the component that mints it and the handler
- * that reads it. This gives you typed reads on the `.customId` field in components. Values are packed into a compact wire string rather than plain stringified tokens, so the 100-char Discord limit goes further. More string per string, basically.
+ * Requires the caller to hold every permission in `scope`. Refuses outside a guild first, then when a
+ * permission is missing. The Administrator bit passes any scope.
  *
- * @typeParam Prefix - The stable route prefix, e.g. 'approve'.
- * @typeParam Shape - The accumulated fields, filled in by the chain.
+ * 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`, and override each refusal with `notInGuild` or `missing`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
  *
  * @example
  * ```ts
- * const ApproveId = new CustomId('approve')
- *     .snowflake('userId')
- *     .oneOf('action', ['approve', 'deny']);
+ * import { PermissionFlagsBits } from 'discord-api-types/v10';
  *
- * // Set the custom id on a button when creating it.
- * new ButtonBuilder().setCustomId(ApproveId.encode({ userId: '123', action: 'approve' }));
+ * \@Gated(RequirePermissions([PermissionFlagsBits.BanMembers]))
+ * \@SlashRoute('ban')
+ * class BanHandler extends SlashHandler<'ban'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
  *
- * // reading in the handler: userId comes back a string
- * const { userId, action } = this.params; // userId: string, action: 'approve' | 'deny'
- * await this.event.guild?.members.fetch(userId);
+ * @example
+ * ```ts
+ * // the base set from roles, on a gateway handler
+ * RequirePermissions([PermissionFlagsBits.BanMembers], { in: 'guild' });
  * ```
  */
-declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}> {
-  /** The stable route prefix, e.g. 'approve'. */
-  readonly prefix: Prefix;
-  /** Like a zod shape */
-  readonly shape: Shape;
-  /** The prefix plus a short hash of the shape, the part of the wire before the colon. */
-  readonly routeKey: string;
-  constructor(prefix: Prefix, shape?: Shape);
-  private add;
-  /**
-   * Add a Discord ID field, decoded as a string (the `Snowflake` type from discord-api-types).
-   *
-   * @example
-   * ```ts
-   * new CustomId('ban').snowflake('userId');
-   * ```
-   */
-  snowflake<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<Snowflake>>>;
-  /**
-   * Add a UUID field, decoded as a lowercase uuid string.
-   *
-   * @example
-   * ```ts
-   * new CustomId('ticket').uuid('ticketId');
-   * ```
-   */
-  uuid<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
-  /**
-   * Add an integer field with no bounds, for a value up to 2^53.
-   *
-   * @example
-   * ```ts
-   * new CustomId('shop').int('amount');
-   * ```
-   */
-  int<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
-  /**
-   * Add an integer field bounded by min and max, so it packs into fewer characters on the wire.
-   *
-   * @example
-   * ```ts
-   * new CustomId('paginate').int('page', 1, 50);
-   * ```
-   */
-  int<Name extends string>(name: Name, min: number, max: number): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
-  /**
-   * Add a boolean flag.
-   *
-   * @example
-   * ```ts
-   * new CustomId('settings').bool('silent');
-   * ```
-   */
-  bool<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<boolean>>>;
-  /**
-   * Add a field that is one value from a fixed list, decoded as the literal union. No `as const` needed.
-   *
-   * @example
-   * ```ts
-   * new CustomId('poll').oneOf('choice', ['yes', 'no', 'abstain']);
-   * ```
-   */
-  oneOf<Name extends string, const Choices extends NonEmptyTuple<string>>(name: Name, choices: Choices): CustomId<Prefix, Shape & Record<Name, CustomIdField<Choices[number]>>>;
-  /**
-   * Add a free short text field. Avoid it where possible, it cannot be packed so it costs the most wire space.
-   *
-   * @example
-   * ```ts
-   * new CustomId('note').str('message');
-   * ```
-   */
-  str<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
-  /**
-   * Mint a wire string from values. Throws if a value is out of its field's range or the wire is over 100 chars.
-   *
-   * @param values - One value per field, typed by the chain.
-   * @returns The wire string to put on the component's customId.
-   */
-  encode(values: DecodedParams<Shape>): string;
-  /**
-   * Read a wire string back into values.
-   *
-   * - This will refuse with a default Notice when the shape changed since the wire was minted.
-   * - Or refuse with a different default Notice on a corrupt or foreign wire.
-   *
-   * @param wire - The customId string from the interaction.
-   * @returns The decoded values, typed by the chain.
-   */
-  decode(wire: string): DecodedParams<Shape>;
-  /** True if this wire was minted from this customId's prefix, ignoring the shape hash. */
-  owns(wire: string): boolean;
-}
+declare function RequirePermissions(scope: PermissionScope, options: RequirePermissionsOptions & {
+  in: 'guild';
+}): Gate<GuildPermissionsContext, 'RequirePermissions'>;
+declare function RequirePermissions(scope: PermissionScope, options?: RequirePermissionsOptions & {
+  in?: 'channel';
+}): Gate<GateContextBase, 'RequirePermissions'>;
 /**
- * Any customId, for places where the exact prefix and shape do not matter.
+ * 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.
  *
- * @internal
+ * 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}, so it fits a gateway handler only. `app_permissions` is
+ * absent on gateway events, the channel scope refuses there as unresolved, use `in: 'guild'` on an
+ * event handler.
+ *
+ * @param scope - The permission flag bits the bot must all hold.
+ * @param options - Pick the scope with `in`, and override each refusal with `notInGuild` or `missing`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
+ *
+ * @example
+ * ```ts
+ * import { PermissionFlagsBits } from 'discord-api-types/v10';
+ *
+ * \@Gated(RequireBotPermissions([PermissionFlagsBits.ManageMessages]))
+ * \@SlashRoute('purge')
+ * class PurgeHandler extends SlashHandler<'purge'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
  */
-type AnyCustomId = CustomId<string, CustomIdShape>;
+declare function RequireBotPermissions(scope: PermissionScope, options: RequirePermissionsOptions & {
+  in: 'guild';
+}): Gate<GuildPermissionsContext, 'RequireBotPermissions'>;
+declare function RequireBotPermissions(scope: PermissionScope, options?: RequirePermissionsOptions & {
+  in?: 'channel';
+}): Gate<GateContextBase, 'RequireBotPermissions'>;
 /**
- * The outcome of decoding a wire against several customIds, the matched prefix paired with its values.
+ * 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.
  *
- * @internal
+ * @param roleId - The role snowflake the caller must hold.
+ * @param options - Override each refusal, the outside-guild one with `notInGuild` and the missing-role one with `missingRole`.
+ *
+ * @see the `@Gated` decorator from `seedcord`
+ *
+ * @example
+ * ```ts
+ * \@Gated(RequireRole('123456789012345678'))
+ * \@SlashRoute('vip')
+ * class VipHandler extends SlashHandler<'vip'> {
+ *     async execute() {
+ *         // ...
+ *     }
+ * }
+ * ```
  */
-type DecodedRoute<Defs extends readonly AnyCustomId[]> = { [Index in keyof Defs]: Defs[Index] extends AnyCustomId ? {
-  readonly prefix: Defs[Index]['prefix'];
-  readonly params: DecodedParams<Defs[Index]['shape']>;
-} : never }[number];
+declare function RequireRole(roleId: string, options?: RequireRoleOptions): Gate<GateContextBase, 'RequireRole'>;
+//#endregion
+//#region src/inputs/AutocompleteOptions.d.ts
+type Row<Route extends keyof SlashOptionRegistry> = SlashOptionRegistry[Route];
+type EntryFor<Route extends keyof SlashOptionRegistry, Name extends PropertyKey> = Route extends unknown ? Name extends keyof Row<Route> ? Row<Route>[Name] : never : never;
+type AutocompletableNames<Route extends keyof SlashOptionRegistry> = Route extends unknown ? { [Name in keyof Row<Route>]: Row<Route>[Name] extends {
+  autocomplete: true;
+} ? Name : never }[keyof Row<Route>] : never;
+type ChoiceValueOf<Entry> = Entry extends {
+  kind: 'string';
+} ? string : Entry extends {
+  kind: 'integer' | 'number';
+} ? number : never;
+/** The focused option. `value` is the raw partial Discord delivers mid-type, always a string regardless of kind. */
+interface FocusedField<Route extends keyof SlashOptionRegistry> {
+  name: AutocompletableNames<Route>;
+  value: string;
+}
+type NamesOfKind<Route extends keyof SlashOptionRegistry, Kind extends OptionKind> = Route extends unknown ? { [Name in keyof Row<Route>]: Row<Route>[Name] extends {
+  kind: Kind;
+} ? Name : never }[keyof Row<Route>] : never;
+type ResolvedValue<Entry> = Entry extends {
+  choices: readonly (infer Choice)[];
+} ? Choice : Entry extends {
+  kind: 'string';
+} ? string : Entry extends {
+  kind: 'integer' | 'number';
+} ? number : Entry extends {
+  kind: 'boolean';
+} ? boolean : never;
+type Getter<Route extends keyof SlashOptionRegistry, Kind extends OptionKind, Method extends string> = IsNever<NamesOfKind<Route, Kind>> extends true ? unknown : Record<Method, <Name extends NamesOfKind<Route, Kind>>(name: Name) => ResolvedValue<EntryFor<Route, Name>> | null>;
 /**
- * Find the customId whose prefix owns this wire, decode against it, and report which one matched.
+ * The sibling-option view for an autocomplete handler. Only the four kinds Discord resolves during
+ * autocomplete appear (string, integer, number, boolean), every read is `T | null` because a sibling is
+ * partial while the user types the focused field, and a getter appears only when a registered command has
+ * an option of that kind.
  *
- * @internal
+ * @typeParam Route - One or more route keys from {@link SlashOptionRegistry}.
  */
-declare function decodeFor<Defs extends readonly AnyCustomId[]>(defs: Defs, wire: string): DecodedRoute<Defs>;
+type AutocompleteOptions<Route extends keyof SlashOptionRegistry> = Getter<Route, 'string', 'getString'> & Getter<Route, 'integer', 'getInteger'> & Getter<Route, 'number', 'getNumber'> & Getter<Route, 'boolean', 'getBoolean'>;
 //#endregion
-export { BuilderComponent as C, RowType as E, RegisterCommand as S, BuilderType as T, RequiredOf as _, CustomIdField as a, CoreBase as b, pickNotice as c, JoinNames as d, TwoOrMore as f, GateContextBase as g, Gate as h, prefixOf as i, GateFitsWith as l, EffectGate as m, CustomId as n, DecodedParams as o, Notice as p, decodeFor as r, GateNoticeOptions as s, AnyCustomId as t, IntersectRequired as u, defineEffectGate as v, RowComponent as w, CommandMeta as x, defineGate as y };
-//# sourceMappingURL=CustomId--QizzBOn.d.mts.map
+export { InteractionMetadataKey as $, serializeReply as A, contextMenuRouteOf as B, GuildPermissionsContext as C, BaseReplySender as D, defineGate as E, AckTrace as F, CustomId as G, storeComponentRoute as H, CoreBase as I, CustomIdField as J, decodeFor as K, RoutableConstructor as L, ReplyMethod as M, checkAckLegality as N, ModalLike as O, sendTarget as P, GatedMetadataKey as Q, SelectMenuKind as R, GateContextBase as S, defineEffectGate as T, storeInteractionRoute as U, selectMenuRouteOf as V, AnyCustomId as W, CommandMetadataKey as X, DecodedParams as Y, EventMetadataKey as Z, JoinNames as _, FocusedField as a, CommandMeta as at, EffectGate as b, RequireBotPermissions as c, BuilderComponent as ct, RequireRole as d, RowType as dt, InteractionRouteKeys as et, RequireRoleOptions as f, OptionKind as ft, IntersectRequired as g, GateFitsWith as h, EntryFor as i, WebhookUrlMetadataKey as it, AckState as j, SerializedReply as k, RequirePermissions as l, RowComponent as lt, pickNotice as m, SlashOptionRegistry as mt, AutocompleteOptions as n, MiddlewareMetadataKey as nt, PermissionNames as o, RegisterCommand as ot, GateNoticeOptions as p, SlashOption as pt, prefixOf as q, ChoiceValueOf as r, SubscribeMetadataKey as rt, PermissionScope as s, Constructor as st, AutocompletableNames as t, InteractionRoutes as tt, RequirePermissionsOptions as u, BuilderType as ut, TwoOrMore as v, RequiredOf as w, Gate as x, Notice as y, areRoutes as z };
+//# sourceMappingURL=AutocompleteOptions-eB87SZ4a.d.mts.map