@nectar-js/nectar 0.1.0 → 0.3.0

package/dist/{index-DGMxBsub.d.ts → index-IqoTGJFM.d.ts}

@@ -1,4 +1,4 @@
-import { ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, Client, ClientEvents, ClientOptions, GatewayIntentBits, Interaction, MentionableSelectMenuInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, PermissionResolvable, RoleSelectMenuInteraction, StringSelectMenuInteraction, UserContextMenuCommandInteraction, UserSelectMenuInteraction } from "discord.js";
+import { Attachment, ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, Client, ClientEvents, ClientOptions, CommandInteractionOption, GatewayIntentBits, Interaction, MentionableSelectMenuInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, PermissionResolvable, RoleSelectMenuInteraction, StringSelectMenuInteraction, User, UserContextMenuCommandInteraction, UserSelectMenuInteraction } from "discord.js";
 import { ApplicationCommandType, ApplicationIntegrationType, ChannelType, InteractionContextType, LocalizationMap, RESTPostAPIApplicationCommandsJSONBody } from "discord-api-types/v10";
 //#region src/version.d.ts
 /** From package.json, which sits one level up from both `src/` and `dist/`. */
@@ -69,7 +69,15 @@ interface CommandMeta extends TopLevelMeta {
   options?: CommandOption[];
   nameLocalizations?: LocalizationMap;
   descriptionLocalizations?: LocalizationMap;
+  /**
+   * Defer the reply before the handler runs, so a slow handler doesn't miss Discord's three
+   * second window. `"ephemeral"` defers with an ephemeral reply. The handler then answers with
+   * `editReply()`.
+   */
+  defer?: boolean | "ephemeral";
 }
+/** How a command route defers, as the manifest records it. */
+type DeferMode = "reply" | "ephemeral";
 /** `export const meta` in a `route.ts` under `commands/`. Describes a parent command or subcommand group. */
 interface CommandRouteMeta extends TopLevelMeta {
   name?: string;
@@ -276,11 +284,18 @@ interface Trace {
   elapsed(): number;
 }
 type Params = Record<string, string | string[]>;
-interface InteractionContext<I = Interaction, P = Params> {
+/** Command option values by name. Untyped until the route is known. */
+type Options = Record<string, unknown>;
+interface InteractionContext<I = Interaction, P = Params, O = Options> {
   interaction: I;
   client: Client;
   route: RouteInfo;
   params: P;
+  /**
+   * The command's options by name, resolved through discord.js. Options the user left out
+   * are `null`. Empty for components and autocomplete.
+   */
+  options: O;
   env: Env;
   trace: Trace;
   /** What plugins provide. Empty without plugins. */
@@ -380,6 +395,8 @@ interface ManifestRouteBase {
 }
 interface ManifestCommandRoute extends ManifestRouteBase {
   kind: "command";
+  /** The reply to defer before the handler runs, from `meta.defer`. */
+  defer: DeferMode | null;
 }
 interface ManifestAutocompleteRoute extends ManifestRouteBase {
   kind: "autocomplete";
@@ -575,6 +592,11 @@ type Empty = Record<never, never>;
 type Declared<K extends string> = NectarRoutes extends Record<K, infer V> ? V : never;
 type Fallback<T, F> = [T] extends [never] ? F : T;
 type ComponentKindName = "button" | "modal" | `select:${SelectKind}`;
+/** One command option as the generated types describe it. */
+interface OptionSpecType {
+  type: OptionType;
+  required: boolean;
+}
 /** Component routes by path. Until types are generated, any string is accepted. */
 type ComponentRoutes = Fallback<Declared<"components">, Record<string, {
   kind: ComponentKindName;
@@ -584,7 +606,7 @@ type ComponentRoutes = Fallback<Declared<"components">, Record<string, {
 /** Command routes by path. Until types are generated, any string is accepted. */
 type CommandRoutes = Fallback<Declared<"commands">, Record<string, {
   type: CommandType;
-  options: Record<string, OptionType>;
+  options: Record<string, OptionSpecType>;
   context: Empty;
 }>>;
 type ComponentPath = keyof ComponentRoutes & string;
@@ -593,9 +615,16 @@ type Route<Routes, P extends string> = P extends keyof Routes ? Routes[P] : neve
 type ComponentInteraction<K> = K extends "button" ? ButtonInteraction : K extends "modal" ? ModalSubmitInteraction : K extends "select:string" ? StringSelectMenuInteraction : K extends "select:user" ? UserSelectMenuInteraction : K extends "select:role" ? RoleSelectMenuInteraction : K extends "select:channel" ? ChannelSelectMenuInteraction : K extends "select:mentionable" ? MentionableSelectMenuInteraction : never;
 type CommandInteraction<T> = T extends "chatInput" ? ChatInputCommandInteraction : T extends "user" ? UserContextMenuCommandInteraction : T extends "message" ? MessageContextMenuCommandInteraction : never;
 type Field<R, K extends string, F> = R extends Record<K, infer V> ? V : F;
+/** What `ctx.options` holds for each option type, as discord.js resolves it. */
+type OptionValue<T> = T extends "string" ? string : T extends "integer" | "number" ? number : T extends "boolean" ? boolean : T extends "user" ? User : T extends "channel" ? NonNullable<CommandInteractionOption["channel"]> : T extends "role" ? NonNullable<CommandInteractionOption["role"]> : T extends "mentionable" ? NonNullable<CommandInteractionOption["member" | "role" | "user"]> : T extends "attachment" ? Attachment : never;
+/** `ctx.options` for a command route: required options as their value, the rest `| null`. */
+type OptionValues<P extends CommandPath> = { [K in keyof Field<Route<CommandRoutes, P>, "options", Empty>]: Field<Route<CommandRoutes, P>, "options", Empty>[K] extends {
+  type: infer T;
+  required: infer R;
+} ? R extends true ? OptionValue<T> : OptionValue<T> | null : never; };
 type ComponentParams<P extends ComponentPath> = Field<Route<ComponentRoutes, P>, "params", Params>;
-type ComponentContext<P extends ComponentPath> = InteractionContext<ComponentInteraction<Field<Route<ComponentRoutes, P>, "kind", ComponentKindName>>, ComponentParams<P>> & Field<Route<ComponentRoutes, P>, "context", Empty>;
-type CommandContext<P extends CommandPath> = InteractionContext<CommandInteraction<Field<Route<CommandRoutes, P>, "type", CommandType>>, Empty> & Field<Route<CommandRoutes, P>, "context", Empty>;
+type ComponentContext<P extends ComponentPath> = InteractionContext<ComponentInteraction<Field<Route<ComponentRoutes, P>, "kind", ComponentKindName>>, ComponentParams<P>, Empty> & Field<Route<ComponentRoutes, P>, "context", Empty>;
+type CommandContext<P extends CommandPath> = InteractionContext<CommandInteraction<Field<Route<CommandRoutes, P>, "type", CommandType>>, Empty, OptionValues<P>> & Field<Route<CommandRoutes, P>, "context", Empty>;
 /** Every field is optional when the route has no parameters, so `customId("confirm")` works. */
 type ParamsArg<P extends ComponentPath> = Empty extends ComponentParams<P> ? [params?: ComponentParams<P>] : [params: ComponentParams<P>];
 /**
@@ -661,6 +690,21 @@ interface RoleOptions extends PolicyOptions {
 }
 /** Passes only when the invoking member holds the listed role IDs. */
 declare function requireRoles(roles: string | readonly string[], options?: RoleOptions): Middleware;
+interface CooldownOptions {
+  /**
+   * Who shares a cooldown: each user (default), everyone in a guild, or everyone. In a DM,
+   * `"guild"` falls back to the user.
+   */
+  scope?: "user" | "guild" | "global";
+  /** What the user sees while waiting, given the seconds left. */
+  message?: string | ((seconds: number) => string);
+}
+/**
+ * Passes once per `seconds` for each route and subject. The cooldown starts when the
+ * interaction passes, so a handler that throws still counts. Autocomplete is never held back.
+ * Cooldowns live in memory, per process, and reset on restart.
+ */
+declare function cooldown(seconds: number, options?: CooldownOptions): Middleware;
 //#endregion
 //#region src/registration/diff.d.ts
 interface CommandDiff {
@@ -675,7 +719,9 @@ interface CommandDiff {
 //#region src/registration/remote.d.ts
 /** The two calls registration needs. discord.js's `REST` satisfies this. */
 interface CommandRest {
-  get(route: `/${string}`): Promise<unknown>;
+  get(route: `/${string}`, options?: {
+    query: URLSearchParams;
+  }): Promise<unknown>;
   put(route: `/${string}`, options: {
     body: unknown;
   }): Promise<unknown>;
@@ -753,5 +799,5 @@ interface NectarRoutes {}
  */
 interface NectarServices {}
 //#endregion
-export { InteractionContext as $, defineComponent as A, OptionChoice as At, PluginChange as B, ComponentOptions as C, ChannelOption as Ct, Routed as D, CommandType as Dt, ComponentRoutes as E, CommandRouteMeta as Et, NectarConfig as F, version as Ft, definePlugin as G, PluginCommandContext as H, defineConfig as I, ContextExtension as J, EventMeta as K, validateConfig as L, defineEvent as M, SimpleOption as Mt, defineMiddleware as N, StringOption as Nt, customId as O, IntegerOption as Ot, ConfigError as P, TopLevelMeta as Pt, Extended as Q, NectarPlugin as R, ComponentKindName as S, SelectKind as St, ComponentPath as T, CommandOption as Tt, PluginError as U, PluginCommand as V, PluginGraph as W, ErrorHandler as X, Env as Y, EventContext as Z, requiredIntents as _, LoggerOptions as _t, SyncResult as a, RouteInfo as at, CommandRoutes as b, CustomIdTooLongError as bt, RegistrationError as c, RejectReason as ct, CommandDiff as d, SignalEmitter as dt, Logger as et, PolicyOptions as f, SignalType as ft, requireRoles as g, LogSink as gt, requirePermissions as h, LogRecord as ht, SyncOptions as i, Params as it, defineError as j, OptionType as jt, defineCommand as k, NumberOption as kt, RegistrationProblem as l, Signal as lt, guildOnly as m, LogLevel as mt, NectarServices as n, MiddlewareExtension as nt, UnsafeSyncError as o, Trace as ot, RoleOptions as p, LogFields as pt, EventMode as q, ScopeSync as r, Next as rt, syncCommands as s, InteractionMeta as st, NectarRoutes as t, Middleware as tt, Scope as u, SignalData as ut, CommandContext as v, ParamValidator as vt, ComponentParams as w, CommandMeta as wt, ComponentContext as x, MAX_CUSTOM_ID_LENGTH as xt, CommandPath as y, StandardSchemaLike as yt, PluginApp as z };
-//# sourceMappingURL=index-DGMxBsub.d.ts.map
+export { Env as $, OptionValues as A, CommandOption as At, defineConfig as B, version as Bt, ComponentContext as C, ParamValidator as Ct, ComponentPath as D, SelectKind as Dt, ComponentParams as E, MAX_CUSTOM_ID_LENGTH as Et, defineError as F, OptionChoice as Ft, PluginCommand as G, NectarPlugin as H, defineEvent as I, OptionType as It, PluginGraph as J, PluginCommandContext as K, defineMiddleware as L, SimpleOption as Lt, customId as M, CommandType as Mt, defineCommand as N, IntegerOption as Nt, ComponentRoutes as O, ChannelOption as Ot, defineComponent as P, NumberOption as Pt, ContextExtension as Q, ConfigError as R, StringOption as Rt, CommandRoutes as S, LoggerOptions as St, ComponentOptions as T, CustomIdTooLongError as Tt, PluginApp as U, validateConfig as V, PluginChange as W, EventMeta as X, definePlugin as Y, EventMode as Z, requirePermissions as _, SignalType as _t, SyncResult as a, Middleware as at, CommandContext as b, LogRecord as bt, RegistrationError as c, Options as ct, CommandDiff as d, Trace as dt, ErrorHandler as et, CooldownOptions as f, InteractionMeta as ft, guildOnly as g, SignalEmitter as gt, cooldown as h, SignalData as ht, SyncOptions as i, Logger as it, Routed as j, CommandRouteMeta as jt, OptionSpecType as k, CommandMeta as kt, RegistrationProblem as l, Params as lt, RoleOptions as m, Signal as mt, NectarServices as n, Extended as nt, UnsafeSyncError as o, MiddlewareExtension as ot, PolicyOptions as p, RejectReason as pt, PluginError as q, ScopeSync as r, InteractionContext as rt, syncCommands as s, Next as st, NectarRoutes as t, EventContext as tt, Scope as u, RouteInfo as ut, requireRoles as v, LogFields as vt, ComponentKindName as w, StandardSchemaLike as wt, CommandPath as x, LogSink as xt, requiredIntents as y, LogLevel as yt, NectarConfig as z, TopLevelMeta as zt };
+//# sourceMappingURL=index-IqoTGJFM.d.ts.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as InteractionContext, A as defineComponent, At as OptionChoice, B as PluginChange, C as ComponentOptions, Ct as ChannelOption, D as Routed, Dt as CommandType, E as ComponentRoutes, Et as CommandRouteMeta, F as NectarConfig, Ft as version, G as definePlugin, H as PluginCommandContext, I as defineConfig, J as ContextExtension, K as EventMeta, L as validateConfig, M as defineEvent, Mt as SimpleOption, N as defineMiddleware, Nt as StringOption, O as customId, Ot as IntegerOption, P as ConfigError, Pt as TopLevelMeta, Q as Extended, R as NectarPlugin, S as ComponentKindName, St as SelectKind, T as ComponentPath, Tt as CommandOption, U as PluginError, V as PluginCommand, W as PluginGraph, X as ErrorHandler, Y as Env, Z as EventContext, _ as requiredIntents, _t as LoggerOptions, a as SyncResult, at as RouteInfo, b as CommandRoutes, bt as CustomIdTooLongError, c as RegistrationError, ct as RejectReason, d as CommandDiff, dt as SignalEmitter, et as Logger, f as PolicyOptions, ft as SignalType, g as requireRoles, gt as LogSink, h as requirePermissions, ht as LogRecord, i as SyncOptions, it as Params, j as defineError, jt as OptionType, k as defineCommand, kt as NumberOption, l as RegistrationProblem, lt as Signal, m as guildOnly, mt as LogLevel, n as NectarServices, nt as MiddlewareExtension, o as UnsafeSyncError, ot as Trace, p as RoleOptions, pt as LogFields, q as EventMode, r as ScopeSync, rt as Next, s as syncCommands, st as InteractionMeta, t as NectarRoutes, tt as Middleware, u as Scope, ut as SignalData, v as CommandContext, vt as ParamValidator, w as ComponentParams, wt as CommandMeta, x as ComponentContext, xt as MAX_CUSTOM_ID_LENGTH, y as CommandPath, yt as StandardSchemaLike, z as PluginApp } from "./index-DGMxBsub.js";
-export { type ChannelOption, type CommandContext, type CommandDiff, type CommandMeta, type CommandOption, type CommandPath, type CommandRouteMeta, type CommandRoutes, type CommandType, type ComponentContext, type ComponentKindName, type ComponentOptions, type ComponentParams, type ComponentPath, type ComponentRoutes, ConfigError, type ContextExtension, CustomIdTooLongError, type Env, type ErrorHandler, type EventContext, type EventMeta, type EventMode, type Extended, type IntegerOption, type InteractionContext, type InteractionMeta, type LogFields, type LogLevel, type LogRecord, type LogSink, type Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, type Middleware, type MiddlewareExtension, type NectarConfig, type NectarPlugin, NectarRoutes, NectarServices, type Next, type NumberOption, type OptionChoice, type OptionType, type ParamValidator, type Params, type PluginApp, type PluginChange, type PluginCommand, type PluginCommandContext, PluginError, type PluginGraph, type PolicyOptions, RegistrationError, type RegistrationProblem, type RejectReason, type RoleOptions, type RouteInfo, type Routed, type Scope, type ScopeSync, type SelectKind, type Signal, type SignalData, type SignalEmitter, type SignalType, type SimpleOption, type StandardSchemaLike, type StringOption, type SyncOptions, type SyncResult, type TopLevelMeta, type Trace, UnsafeSyncError, customId, defineCommand, defineComponent, defineConfig, defineError, defineEvent, defineMiddleware, definePlugin, guildOnly, requirePermissions, requireRoles, requiredIntents, syncCommands, validateConfig, version };
+import { $ as Env, A as OptionValues, At as CommandOption, B as defineConfig, Bt as version, C as ComponentContext, Ct as ParamValidator, D as ComponentPath, Dt as SelectKind, E as ComponentParams, Et as MAX_CUSTOM_ID_LENGTH, F as defineError, Ft as OptionChoice, G as PluginCommand, H as NectarPlugin, I as defineEvent, It as OptionType, J as PluginGraph, K as PluginCommandContext, L as defineMiddleware, Lt as SimpleOption, M as customId, Mt as CommandType, N as defineCommand, Nt as IntegerOption, O as ComponentRoutes, Ot as ChannelOption, P as defineComponent, Pt as NumberOption, Q as ContextExtension, R as ConfigError, Rt as StringOption, S as CommandRoutes, St as LoggerOptions, T as ComponentOptions, Tt as CustomIdTooLongError, U as PluginApp, V as validateConfig, W as PluginChange, X as EventMeta, Y as definePlugin, Z as EventMode, _ as requirePermissions, _t as SignalType, a as SyncResult, at as Middleware, b as CommandContext, bt as LogRecord, c as RegistrationError, ct as Options, d as CommandDiff, dt as Trace, et as ErrorHandler, f as CooldownOptions, ft as InteractionMeta, g as guildOnly, gt as SignalEmitter, h as cooldown, ht as SignalData, i as SyncOptions, it as Logger, j as Routed, jt as CommandRouteMeta, k as OptionSpecType, kt as CommandMeta, l as RegistrationProblem, lt as Params, m as RoleOptions, mt as Signal, n as NectarServices, nt as Extended, o as UnsafeSyncError, ot as MiddlewareExtension, p as PolicyOptions, pt as RejectReason, q as PluginError, r as ScopeSync, rt as InteractionContext, s as syncCommands, st as Next, t as NectarRoutes, tt as EventContext, u as Scope, ut as RouteInfo, v as requireRoles, vt as LogFields, w as ComponentKindName, wt as StandardSchemaLike, x as CommandPath, xt as LogSink, y as requiredIntents, yt as LogLevel, z as NectarConfig, zt as TopLevelMeta } from "./index-IqoTGJFM.js";
+export { type ChannelOption, type CommandContext, type CommandDiff, type CommandMeta, type CommandOption, type CommandPath, type CommandRouteMeta, type CommandRoutes, type CommandType, type ComponentContext, type ComponentKindName, type ComponentOptions, type ComponentParams, type ComponentPath, type ComponentRoutes, ConfigError, type ContextExtension, type CooldownOptions, CustomIdTooLongError, type Env, type ErrorHandler, type EventContext, type EventMeta, type EventMode, type Extended, type IntegerOption, type InteractionContext, type InteractionMeta, type LogFields, type LogLevel, type LogRecord, type LogSink, type Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, type Middleware, type MiddlewareExtension, type NectarConfig, type NectarPlugin, NectarRoutes, NectarServices, type Next, type NumberOption, type OptionChoice, type OptionSpecType, type OptionType, type OptionValues, type Options, type ParamValidator, type Params, type PluginApp, type PluginChange, type PluginCommand, type PluginCommandContext, PluginError, type PluginGraph, type PolicyOptions, RegistrationError, type RegistrationProblem, type RejectReason, type RoleOptions, type RouteInfo, type Routed, type Scope, type ScopeSync, type SelectKind, type Signal, type SignalData, type SignalEmitter, type SignalType, type SimpleOption, type StandardSchemaLike, type StringOption, type SyncOptions, type SyncResult, type TopLevelMeta, type Trace, UnsafeSyncError, cooldown, customId, defineCommand, defineComponent, defineConfig, defineError, defineEvent, defineMiddleware, definePlugin, guildOnly, requirePermissions, requireRoles, requiredIntents, syncCommands, validateConfig, version };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { C as MAX_CUSTOM_ID_LENGTH, S as CustomIdTooLongError, T as version, l as encodeComponentRoute, n as definePlugin, t as PluginError } from "./plugins-CGvM19v9.js";
-import { l as defineConfig, n as syncCommands, o as requiredIntents, r as RegistrationError, s as ConfigError, t as UnsafeSyncError, u as validateConfig } from "./registration-CaE0QBT6.js";
+import { D as version, T as MAX_CUSTOM_ID_LENGTH, l as encodeComponentRoute, n as definePlugin, t as PluginError, w as CustomIdTooLongError } from "./plugins-C2uwN3-D.js";
+import { l as defineConfig, n as syncCommands, o as requiredIntents, r as RegistrationError, s as ConfigError, t as UnsafeSyncError, u as validateConfig } from "./registration-mUZJidnF.js";
 import { MessageFlags } from "discord-api-types/v10";
 //#region src/define.ts
 /**
@@ -72,6 +72,40 @@ function requireRoles(roles, options = {}) {
 		return next();
 	};
 }
+/**
+* Passes once per `seconds` for each route and subject. The cooldown starts when the
+* interaction passes, so a handler that throws still counts. Autocomplete is never held back.
+* Cooldowns live in memory, per process, and reset on restart.
+*/
+function cooldown(seconds, options = {}) {
+	if (!(seconds > 0)) throw new RangeError(`cooldown() needs a positive number of seconds.`);
+	const scope = options.scope ?? "user";
+	const message = options.message ?? ((left) => `Try again in ${left}s.`);
+	const until = /* @__PURE__ */ new Map();
+	return async (ctx, next) => {
+		const i = ctx.interaction;
+		if (typeof i.respond === "function") return next();
+		const now = Date.now();
+		const key = `${ctx.route.id}\n${subject(i, scope)}`;
+		const expires = until.get(key);
+		if (expires !== void 0 && expires > now) {
+			const left = Math.ceil((expires - now) / 1e3);
+			return deny(ctx, typeof message === "string" ? message : message(left));
+		}
+		if (until.size >= SWEEP_AT) {
+			for (const [k, t] of until) if (t <= now) until.delete(k);
+		}
+		until.set(key, now + seconds * 1e3);
+		return next();
+	};
+}
+/** Expired entries are dropped once the map reaches this size, so it stays bounded. */
+const SWEEP_AT = 1e3;
+function subject(i, scope) {
+	if (scope === "global") return "";
+	if (scope === "guild" && typeof i.guildId === "string") return `g:${i.guildId}`;
+	return `u:${i.user?.id ?? ""}`;
+}
 function inGuild(ctx) {
 	const i = ctx.interaction;
 	return typeof i.inGuild === "function" ? i.inGuild() : typeof i.guildId === "string";
@@ -100,6 +134,6 @@ async function deny(ctx, message) {
 	});
 }
 //#endregion
-export { ConfigError, CustomIdTooLongError, MAX_CUSTOM_ID_LENGTH, PluginError, RegistrationError, UnsafeSyncError, customId, defineCommand, defineComponent, defineConfig, defineError, defineEvent, defineMiddleware, definePlugin, guildOnly, requirePermissions, requireRoles, requiredIntents, syncCommands, validateConfig, version };
+export { ConfigError, CustomIdTooLongError, MAX_CUSTOM_ID_LENGTH, PluginError, RegistrationError, UnsafeSyncError, cooldown, customId, defineCommand, defineComponent, defineConfig, defineError, defineEvent, defineMiddleware, definePlugin, guildOnly, requirePermissions, requireRoles, requiredIntents, syncCommands, validateConfig, version };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/define.ts","../src/policy.ts"],"sourcesContent":["import type {\n  ButtonInteraction,\n  ChannelSelectMenuInteraction,\n  ChatInputCommandInteraction,\n  ClientEvents,\n  MentionableSelectMenuInteraction,\n  MessageContextMenuCommandInteraction,\n  ModalSubmitInteraction,\n  RoleSelectMenuInteraction,\n  StringSelectMenuInteraction,\n  UserContextMenuCommandInteraction,\n  UserSelectMenuInteraction,\n} from \"discord.js\";\nimport type { CommandType, OptionType } from \"./commands/meta.js\";\nimport type { SelectKind } from \"./components/compile.js\";\nimport type { ParamValidator } from \"./components/params.js\";\nimport { encodeComponentRoute } from \"./components/registry.js\";\nimport type { NectarRoutes } from \"./index.js\";\nimport type {\n  ContextExtension,\n  ErrorHandler,\n  EventContext,\n  Extended,\n  InteractionContext,\n  Middleware,\n  Next,\n  Params,\n} from \"./runtime/types.js\";\n\ntype Empty = Record<never, never>;\n\n/** `NectarRoutes[K]` when the generated types declare it, otherwise `never`. */\ntype Declared<K extends string> = NectarRoutes extends Record<K, infer V> ? V : never;\ntype Fallback<T, F> = [T] extends [never] ? F : T;\n\nexport type ComponentKindName = \"button\" | \"modal\" | `select:${SelectKind}`;\n\nexport interface ComponentRouteType {\n  kind: ComponentKindName;\n  params: Params;\n  context: object;\n}\n\nexport interface CommandRouteType {\n  type: CommandType;\n  options: Record<string, OptionType>;\n  context: object;\n}\n\n/** Component routes by path. Until types are generated, any string is accepted. */\nexport type ComponentRoutes = Fallback<\n  Declared<\"components\">,\n  Record<string, { kind: ComponentKindName; params: Params; context: Empty }>\n>;\n\n/** Command routes by path. Until types are generated, any string is accepted. */\nexport type CommandRoutes = Fallback<\n  Declared<\"commands\">,\n  Record<string, { type: CommandType; options: Record<string, OptionType>; context: Empty }>\n>;\n\nexport type ComponentPath = keyof ComponentRoutes & string;\nexport type CommandPath = keyof CommandRoutes & string;\n\ntype Route<Routes, P extends string> = P extends keyof Routes ? Routes[P] : never;\n\ntype ComponentInteraction<K> = K extends \"button\"\n  ? ButtonInteraction\n  : K extends \"modal\"\n    ? ModalSubmitInteraction\n    : K extends \"select:string\"\n      ? StringSelectMenuInteraction\n      : K extends \"select:user\"\n        ? UserSelectMenuInteraction\n        : K extends \"select:role\"\n          ? RoleSelectMenuInteraction\n          : K extends \"select:channel\"\n            ? ChannelSelectMenuInteraction\n            : K extends \"select:mentionable\"\n              ? MentionableSelectMenuInteraction\n              : never;\n\ntype CommandInteraction<T> = T extends \"chatInput\"\n  ? ChatInputCommandInteraction\n  : T extends \"user\"\n    ? UserContextMenuCommandInteraction\n    : T extends \"message\"\n      ? MessageContextMenuCommandInteraction\n      : never;\n\ntype Field<R, K extends string, F> = R extends Record<K, infer V> ? V : F;\n\nexport type ComponentParams<P extends ComponentPath> = Field<\n  Route<ComponentRoutes, P>,\n  \"params\",\n  Params\n>;\n\nexport type ComponentContext<P extends ComponentPath> = InteractionContext<\n  ComponentInteraction<Field<Route<ComponentRoutes, P>, \"kind\", ComponentKindName>>,\n  ComponentParams<P>\n> &\n  Field<Route<ComponentRoutes, P>, \"context\", Empty>;\n\nexport type CommandContext<P extends CommandPath> = InteractionContext<\n  CommandInteraction<Field<Route<CommandRoutes, P>, \"type\", CommandType>>,\n  Empty\n> &\n  Field<Route<CommandRoutes, P>, \"context\", Empty>;\n\n/** Every field is optional when the route has no parameters, so `customId(\"confirm\")` works. */\ntype ParamsArg<P extends ComponentPath> =\n  Empty extends ComponentParams<P> ? [params?: ComponentParams<P>] : [params: ComponentParams<P>];\n\n/**\n * The custom ID for a component route, ready for a discord.js builder.\n *\n * Typed against the generated route map: the path must exist and the parameters must match\n * the dynamic segments. Throws when a value is missing or the ID would exceed Discord's limit.\n */\nexport function customId<P extends ComponentPath>(route: P, ...args: ParamsArg<P>): string {\n  return encodeComponentRoute(route, (args[0] ?? {}) as Params);\n}\n\n/** A handler that remembers which route it was written for, so the compiler can check the file location. */\nexport type Routed<F> = F & { route: string };\n\nexport function defineCommand<P extends CommandPath>(\n  route: P,\n  handler: (ctx: CommandContext<P>) => unknown,\n): Routed<typeof handler> {\n  return routed(\"defineCommand\", route, handler);\n}\n\nexport interface ComponentOptions<P extends ComponentPath> {\n  /**\n   * Validators for the route's parameters, run on every incoming custom ID before middleware.\n   * A parameter without one accepts any string. When a validator fails the interaction is\n   * dropped and reported; the handler never sees it.\n   */\n  params?: { [K in keyof ComponentParams<P>]?: ParamValidator<ComponentParams<P>[K]> };\n}\n\nexport function defineComponent<P extends ComponentPath>(\n  route: P,\n  handler: (ctx: ComponentContext<P>) => unknown,\n  options: ComponentOptions<P> = {},\n): Routed<typeof handler> {\n  const defined = routed(\"defineComponent\", route, handler);\n  if (options.params !== undefined) Object.assign(defined, { params: options.params });\n  return defined;\n}\n\nexport function defineEvent<Name extends keyof ClientEvents>(\n  event: Name,\n  handler: (...args: [...ClientEvents[Name], EventContext]) => unknown,\n): Routed<typeof handler> {\n  return routed(\"defineEvent\", event, handler);\n}\n\n/**\n * `return next({ member })` types `member` onto every downstream context. Middleware that\n * calls `next()` without returning it adds nothing; pass the extension type explicitly if\n * you need both.\n */\nexport function defineMiddleware<E extends ContextExtension = Empty>(\n  middleware: (\n    ctx: InteractionContext,\n    next: Next,\n    // biome-ignore lint/suspicious/noConfusingVoidType: handlers that only call next() return void\n  ) => Promise<Extended<E> | undefined | void> | Extended<E> | undefined | void,\n): Middleware<E> {\n  if (typeof middleware !== \"function\") {\n    throw new TypeError(`defineMiddleware() expects a function, got ${typeof middleware}.`);\n  }\n  return middleware as Middleware<E>;\n}\n\nexport function defineError(handler: ErrorHandler): ErrorHandler {\n  if (typeof handler !== \"function\") {\n    throw new TypeError(`defineError() expects a function, got ${typeof handler}.`);\n  }\n  return handler;\n}\n\nfunction routed<F>(name: string, route: string, handler: F): Routed<F> {\n  if (typeof route !== \"string\" || route === \"\") {\n    throw new TypeError(`${name}() expects the route path as its first argument.`);\n  }\n  if (typeof handler !== \"function\") {\n    throw new TypeError(`${name}(\"${route}\") expects a handler function, got ${typeof handler}.`);\n  }\n  return Object.assign(handler, { route });\n}\n","import type { PermissionResolvable } from \"discord.js\";\nimport { MessageFlags } from \"discord-api-types/v10\";\nimport type { InteractionContext, Middleware } from \"./runtime/types.js\";\n\n/**\n * Opt-in policy middleware. Each returns a middleware that stops the chain and answers the\n * user with a short ephemeral message when the check fails. Registration-time permissions\n * (`meta.defaultMemberPermissions`) are a separate concept: Discord enforces those before the\n * interaction reaches the bot, and server admins can override them. These checks run in the\n * bot and cannot be overridden.\n *\n * Use them from a `middleware.ts`:\n *\n *     export default requirePermissions(\"BanMembers\");\n *\n * Or compose them with your own middleware by calling them inside it.\n */\n\nexport interface PolicyOptions {\n  /** What the user sees when the check fails. */\n  message?: string;\n}\n\n/** Passes only interactions that come from a guild. */\nexport function guildOnly(options: PolicyOptions = {}): Middleware {\n  const message = options.message ?? \"This only works in a server.\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    return next();\n  };\n}\n\n/** Passes only when the invoking member has every listed permission in the current channel. */\nexport function requirePermissions(\n  permissions: PermissionResolvable,\n  options: PolicyOptions = {},\n): Middleware {\n  const message = options.message ?? \"You do not have permission to do that.\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    const held = (ctx.interaction as GuildInteractionLike).memberPermissions;\n    if (held === null || held === undefined || !held.has(permissions)) return deny(ctx, message);\n    return next();\n  };\n}\n\nexport interface RoleOptions extends PolicyOptions {\n  /** `\"any\"` (default) passes with one matching role; `\"all\"` needs every listed role. */\n  mode?: \"any\" | \"all\";\n}\n\n/** Passes only when the invoking member holds the listed role IDs. */\nexport function requireRoles(\n  roles: string | readonly string[],\n  options: RoleOptions = {},\n): Middleware {\n  const wanted = typeof roles === \"string\" ? [roles] : [...roles];\n  const message = options.message ?? \"You do not have the role for that.\";\n  const mode = options.mode ?? \"any\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    const held = memberRoles(ctx.interaction as GuildInteractionLike);\n    const ok = mode === \"all\" ? wanted.every((r) => held.has(r)) : wanted.some((r) => held.has(r));\n    if (!ok) return deny(ctx, message);\n    return next();\n  };\n}\n\nfunction inGuild(ctx: InteractionContext): boolean {\n  const i = ctx.interaction as GuildInteractionLike;\n  return typeof i.inGuild === \"function\" ? i.inGuild() : typeof i.guildId === \"string\";\n}\n\n/**\n * Role IDs of the invoking member. discord.js gives a `GuildMember` with a role cache when the\n * guild is cached and a raw API member with an ID array otherwise.\n */\nfunction memberRoles(interaction: GuildInteractionLike): Set<string> {\n  const roles = interaction.member?.roles;\n  if (roles === undefined || roles === null) return new Set();\n  if (Array.isArray(roles)) return new Set(roles);\n  return new Set((roles as { cache: Map<string, unknown> }).cache.keys());\n}\n\n/** Answers the user, when the interaction can still be answered, and ends the chain. */\nasync function deny(ctx: InteractionContext, message: string): Promise<void> {\n  const i = ctx.interaction as RepliableLike;\n  if (typeof i.respond === \"function\") {\n    // Autocomplete cannot show a message. An empty list is the only quiet answer.\n    if (!i.responded) await i.respond([]);\n    return;\n  }\n  if (typeof i.reply !== \"function\" || i.replied || i.deferred) return;\n  await i.reply({ content: message, flags: MessageFlags.Ephemeral });\n}\n\ninterface GuildInteractionLike {\n  inGuild?: () => boolean;\n  guildId?: string | null;\n  memberPermissions?: { has(permission: PermissionResolvable): boolean } | null;\n  member?: { roles: readonly string[] | { cache: Map<string, unknown> } } | null;\n}\n\ninterface RepliableLike {\n  replied?: boolean;\n  deferred?: boolean;\n  responded?: boolean;\n  reply?: (options: { content: string; flags: MessageFlags }) => Promise<unknown>;\n  respond?: (choices: never[]) => Promise<unknown>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/define.ts","../src/policy.ts"],"sourcesContent":["import type {\n  Attachment,\n  ButtonInteraction,\n  ChannelSelectMenuInteraction,\n  ChatInputCommandInteraction,\n  ClientEvents,\n  CommandInteractionOption,\n  MentionableSelectMenuInteraction,\n  MessageContextMenuCommandInteraction,\n  ModalSubmitInteraction,\n  RoleSelectMenuInteraction,\n  StringSelectMenuInteraction,\n  User,\n  UserContextMenuCommandInteraction,\n  UserSelectMenuInteraction,\n} from \"discord.js\";\nimport type { CommandType, OptionType } from \"./commands/meta.js\";\nimport type { SelectKind } from \"./components/compile.js\";\nimport type { ParamValidator } from \"./components/params.js\";\nimport { encodeComponentRoute } from \"./components/registry.js\";\nimport type { NectarRoutes } from \"./index.js\";\nimport type {\n  ContextExtension,\n  ErrorHandler,\n  EventContext,\n  Extended,\n  InteractionContext,\n  Middleware,\n  Next,\n  Params,\n} from \"./runtime/types.js\";\n\ntype Empty = Record<never, never>;\n\n/** `NectarRoutes[K]` when the generated types declare it, otherwise `never`. */\ntype Declared<K extends string> = NectarRoutes extends Record<K, infer V> ? V : never;\ntype Fallback<T, F> = [T] extends [never] ? F : T;\n\nexport type ComponentKindName = \"button\" | \"modal\" | `select:${SelectKind}`;\n\nexport interface ComponentRouteType {\n  kind: ComponentKindName;\n  params: Params;\n  context: object;\n}\n\n/** One command option as the generated types describe it. */\nexport interface OptionSpecType {\n  type: OptionType;\n  required: boolean;\n}\n\nexport interface CommandRouteType {\n  type: CommandType;\n  options: Record<string, OptionSpecType>;\n  context: object;\n}\n\n/** Component routes by path. Until types are generated, any string is accepted. */\nexport type ComponentRoutes = Fallback<\n  Declared<\"components\">,\n  Record<string, { kind: ComponentKindName; params: Params; context: Empty }>\n>;\n\n/** Command routes by path. Until types are generated, any string is accepted. */\nexport type CommandRoutes = Fallback<\n  Declared<\"commands\">,\n  Record<string, { type: CommandType; options: Record<string, OptionSpecType>; context: Empty }>\n>;\n\nexport type ComponentPath = keyof ComponentRoutes & string;\nexport type CommandPath = keyof CommandRoutes & string;\n\ntype Route<Routes, P extends string> = P extends keyof Routes ? Routes[P] : never;\n\ntype ComponentInteraction<K> = K extends \"button\"\n  ? ButtonInteraction\n  : K extends \"modal\"\n    ? ModalSubmitInteraction\n    : K extends \"select:string\"\n      ? StringSelectMenuInteraction\n      : K extends \"select:user\"\n        ? UserSelectMenuInteraction\n        : K extends \"select:role\"\n          ? RoleSelectMenuInteraction\n          : K extends \"select:channel\"\n            ? ChannelSelectMenuInteraction\n            : K extends \"select:mentionable\"\n              ? MentionableSelectMenuInteraction\n              : never;\n\ntype CommandInteraction<T> = T extends \"chatInput\"\n  ? ChatInputCommandInteraction\n  : T extends \"user\"\n    ? UserContextMenuCommandInteraction\n    : T extends \"message\"\n      ? MessageContextMenuCommandInteraction\n      : never;\n\ntype Field<R, K extends string, F> = R extends Record<K, infer V> ? V : F;\n\n/** What `ctx.options` holds for each option type, as discord.js resolves it. */\ntype OptionValue<T> = T extends \"string\"\n  ? string\n  : T extends \"integer\" | \"number\"\n    ? number\n    : T extends \"boolean\"\n      ? boolean\n      : T extends \"user\"\n        ? User\n        : T extends \"channel\"\n          ? NonNullable<CommandInteractionOption[\"channel\"]>\n          : T extends \"role\"\n            ? NonNullable<CommandInteractionOption[\"role\"]>\n            : T extends \"mentionable\"\n              ? NonNullable<CommandInteractionOption[\"member\" | \"role\" | \"user\"]>\n              : T extends \"attachment\"\n                ? Attachment\n                : never;\n\n/** `ctx.options` for a command route: required options as their value, the rest `| null`. */\nexport type OptionValues<P extends CommandPath> = {\n  [K in keyof Field<Route<CommandRoutes, P>, \"options\", Empty>]: Field<\n    Route<CommandRoutes, P>,\n    \"options\",\n    Empty\n  >[K] extends { type: infer T; required: infer R }\n    ? R extends true\n      ? OptionValue<T>\n      : OptionValue<T> | null\n    : never;\n};\n\nexport type ComponentParams<P extends ComponentPath> = Field<\n  Route<ComponentRoutes, P>,\n  \"params\",\n  Params\n>;\n\nexport type ComponentContext<P extends ComponentPath> = InteractionContext<\n  ComponentInteraction<Field<Route<ComponentRoutes, P>, \"kind\", ComponentKindName>>,\n  ComponentParams<P>,\n  Empty\n> &\n  Field<Route<ComponentRoutes, P>, \"context\", Empty>;\n\nexport type CommandContext<P extends CommandPath> = InteractionContext<\n  CommandInteraction<Field<Route<CommandRoutes, P>, \"type\", CommandType>>,\n  Empty,\n  OptionValues<P>\n> &\n  Field<Route<CommandRoutes, P>, \"context\", Empty>;\n\n/** Every field is optional when the route has no parameters, so `customId(\"confirm\")` works. */\ntype ParamsArg<P extends ComponentPath> =\n  Empty extends ComponentParams<P> ? [params?: ComponentParams<P>] : [params: ComponentParams<P>];\n\n/**\n * The custom ID for a component route, ready for a discord.js builder.\n *\n * Typed against the generated route map: the path must exist and the parameters must match\n * the dynamic segments. Throws when a value is missing or the ID would exceed Discord's limit.\n */\nexport function customId<P extends ComponentPath>(route: P, ...args: ParamsArg<P>): string {\n  return encodeComponentRoute(route, (args[0] ?? {}) as Params);\n}\n\n/** A handler that remembers which route it was written for, so the compiler can check the file location. */\nexport type Routed<F> = F & { route: string };\n\nexport function defineCommand<P extends CommandPath>(\n  route: P,\n  handler: (ctx: CommandContext<P>) => unknown,\n): Routed<typeof handler> {\n  return routed(\"defineCommand\", route, handler);\n}\n\nexport interface ComponentOptions<P extends ComponentPath> {\n  /**\n   * Validators for the route's parameters, run on every incoming custom ID before middleware.\n   * A parameter without one accepts any string. When a validator fails the interaction is\n   * dropped and reported; the handler never sees it.\n   */\n  params?: { [K in keyof ComponentParams<P>]?: ParamValidator<ComponentParams<P>[K]> };\n}\n\nexport function defineComponent<P extends ComponentPath>(\n  route: P,\n  handler: (ctx: ComponentContext<P>) => unknown,\n  options: ComponentOptions<P> = {},\n): Routed<typeof handler> {\n  const defined = routed(\"defineComponent\", route, handler);\n  if (options.params !== undefined) Object.assign(defined, { params: options.params });\n  return defined;\n}\n\nexport function defineEvent<Name extends keyof ClientEvents>(\n  event: Name,\n  handler: (...args: [...ClientEvents[Name], EventContext]) => unknown,\n): Routed<typeof handler> {\n  return routed(\"defineEvent\", event, handler);\n}\n\n/**\n * `return next({ member })` types `member` onto every downstream context. Middleware that\n * calls `next()` without returning it adds nothing; pass the extension type explicitly if\n * you need both.\n */\nexport function defineMiddleware<E extends ContextExtension = Empty>(\n  middleware: (\n    ctx: InteractionContext,\n    next: Next,\n    // biome-ignore lint/suspicious/noConfusingVoidType: handlers that only call next() return void\n  ) => Promise<Extended<E> | undefined | void> | Extended<E> | undefined | void,\n): Middleware<E> {\n  if (typeof middleware !== \"function\") {\n    throw new TypeError(`defineMiddleware() expects a function, got ${typeof middleware}.`);\n  }\n  return middleware as Middleware<E>;\n}\n\nexport function defineError(handler: ErrorHandler): ErrorHandler {\n  if (typeof handler !== \"function\") {\n    throw new TypeError(`defineError() expects a function, got ${typeof handler}.`);\n  }\n  return handler;\n}\n\nfunction routed<F>(name: string, route: string, handler: F): Routed<F> {\n  if (typeof route !== \"string\" || route === \"\") {\n    throw new TypeError(`${name}() expects the route path as its first argument.`);\n  }\n  if (typeof handler !== \"function\") {\n    throw new TypeError(`${name}(\"${route}\") expects a handler function, got ${typeof handler}.`);\n  }\n  return Object.assign(handler, { route });\n}\n","import type { PermissionResolvable } from \"discord.js\";\nimport { MessageFlags } from \"discord-api-types/v10\";\nimport type { InteractionContext, Middleware } from \"./runtime/types.js\";\n\n/**\n * Opt-in policy middleware. Each returns a middleware that stops the chain and answers the\n * user with a short ephemeral message when the check fails. Registration-time permissions\n * (`meta.defaultMemberPermissions`) are a separate concept: Discord enforces those before the\n * interaction reaches the bot, and server admins can override them. These checks run in the\n * bot and cannot be overridden.\n *\n * Use them from a `middleware.ts`:\n *\n *     export default requirePermissions(\"BanMembers\");\n *\n * Or compose them with your own middleware by calling them inside it.\n */\n\nexport interface PolicyOptions {\n  /** What the user sees when the check fails. */\n  message?: string;\n}\n\n/** Passes only interactions that come from a guild. */\nexport function guildOnly(options: PolicyOptions = {}): Middleware {\n  const message = options.message ?? \"This only works in a server.\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    return next();\n  };\n}\n\n/** Passes only when the invoking member has every listed permission in the current channel. */\nexport function requirePermissions(\n  permissions: PermissionResolvable,\n  options: PolicyOptions = {},\n): Middleware {\n  const message = options.message ?? \"You do not have permission to do that.\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    const held = (ctx.interaction as GuildInteractionLike).memberPermissions;\n    if (held === null || held === undefined || !held.has(permissions)) return deny(ctx, message);\n    return next();\n  };\n}\n\nexport interface RoleOptions extends PolicyOptions {\n  /** `\"any\"` (default) passes with one matching role; `\"all\"` needs every listed role. */\n  mode?: \"any\" | \"all\";\n}\n\n/** Passes only when the invoking member holds the listed role IDs. */\nexport function requireRoles(\n  roles: string | readonly string[],\n  options: RoleOptions = {},\n): Middleware {\n  const wanted = typeof roles === \"string\" ? [roles] : [...roles];\n  const message = options.message ?? \"You do not have the role for that.\";\n  const mode = options.mode ?? \"any\";\n  return async (ctx, next) => {\n    if (!inGuild(ctx)) return deny(ctx, message);\n    const held = memberRoles(ctx.interaction as GuildInteractionLike);\n    const ok = mode === \"all\" ? wanted.every((r) => held.has(r)) : wanted.some((r) => held.has(r));\n    if (!ok) return deny(ctx, message);\n    return next();\n  };\n}\n\nexport interface CooldownOptions {\n  /**\n   * Who shares a cooldown: each user (default), everyone in a guild, or everyone. In a DM,\n   * `\"guild\"` falls back to the user.\n   */\n  scope?: \"user\" | \"guild\" | \"global\";\n  /** What the user sees while waiting, given the seconds left. */\n  message?: string | ((seconds: number) => string);\n}\n\n/**\n * Passes once per `seconds` for each route and subject. The cooldown starts when the\n * interaction passes, so a handler that throws still counts. Autocomplete is never held back.\n * Cooldowns live in memory, per process, and reset on restart.\n */\nexport function cooldown(seconds: number, options: CooldownOptions = {}): Middleware {\n  if (!(seconds > 0)) throw new RangeError(`cooldown() needs a positive number of seconds.`);\n  const scope = options.scope ?? \"user\";\n  const message = options.message ?? ((left: number) => `Try again in ${left}s.`);\n  const until = new Map<string, number>();\n  return async (ctx, next) => {\n    const i = ctx.interaction as SubjectLike;\n    if (typeof i.respond === \"function\") return next();\n    const now = Date.now();\n    const key = `${ctx.route.id}\\n${subject(i, scope)}`;\n    const expires = until.get(key);\n    if (expires !== undefined && expires > now) {\n      const left = Math.ceil((expires - now) / 1000);\n      return deny(ctx, typeof message === \"string\" ? message : message(left));\n    }\n    if (until.size >= SWEEP_AT) {\n      for (const [k, t] of until) if (t <= now) until.delete(k);\n    }\n    until.set(key, now + seconds * 1000);\n    return next();\n  };\n}\n\n/** Expired entries are dropped once the map reaches this size, so it stays bounded. */\nconst SWEEP_AT = 1000;\n\nfunction subject(i: SubjectLike, scope: NonNullable<CooldownOptions[\"scope\"]>): string {\n  if (scope === \"global\") return \"\";\n  if (scope === \"guild\" && typeof i.guildId === \"string\") return `g:${i.guildId}`;\n  return `u:${i.user?.id ?? \"\"}`;\n}\n\ninterface SubjectLike {\n  guildId?: string | null;\n  user?: { id: string } | null;\n  respond?: unknown;\n}\n\nfunction inGuild(ctx: InteractionContext): boolean {\n  const i = ctx.interaction as GuildInteractionLike;\n  return typeof i.inGuild === \"function\" ? i.inGuild() : typeof i.guildId === \"string\";\n}\n\n/**\n * Role IDs of the invoking member. discord.js gives a `GuildMember` with a role cache when the\n * guild is cached and a raw API member with an ID array otherwise.\n */\nfunction memberRoles(interaction: GuildInteractionLike): Set<string> {\n  const roles = interaction.member?.roles;\n  if (roles === undefined || roles === null) return new Set();\n  if (Array.isArray(roles)) return new Set(roles);\n  return new Set((roles as { cache: Map<string, unknown> }).cache.keys());\n}\n\n/** Answers the user, when the interaction can still be answered, and ends the chain. */\nasync function deny(ctx: InteractionContext, message: string): Promise<void> {\n  const i = ctx.interaction as RepliableLike;\n  if (typeof i.respond === \"function\") {\n    // Autocomplete cannot show a message. An empty list is the only quiet answer.\n    if (!i.responded) await i.respond([]);\n    return;\n  }\n  if (typeof i.reply !== \"function\" || i.replied || i.deferred) return;\n  await i.reply({ content: message, flags: MessageFlags.Ephemeral });\n}\n\ninterface GuildInteractionLike {\n  inGuild?: () => boolean;\n  guildId?: string | null;\n  memberPermissions?: { has(permission: PermissionResolvable): boolean } | null;\n  member?: { roles: readonly string[] | { cache: Map<string, unknown> } } | null;\n}\n\ninterface RepliableLike {\n  replied?: boolean;\n  deferred?: boolean;\n  responded?: boolean;\n  reply?: (options: { content: string; flags: MessageFlags }) => Promise<unknown>;\n  respond?: (choices: never[]) => Promise<unknown>;\n}\n"],"mappings":"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"}

package/dist/{plugins-CGvM19v9.js → plugins-C2uwN3-D.js}

@@ -91,6 +91,69 @@ function escapeValue(value) {
 }
 //#endregion
 //#region src/compiler/diagnostics.ts
+/** Every code the compiler reports. Each has an entry in the diagnostics reference. */
+const DIAGNOSTIC_CODES = [
+	"file-outside-category",
+	"unknown-category",
+	"file-in-wrong-category",
+	"invalid-segment",
+	"route-without-path",
+	"dynamic-segment-not-allowed",
+	"duplicate-param",
+	"catch-all-not-last",
+	"duplicate-route",
+	"module-load-failed",
+	"missing-handler",
+	"route-mismatch",
+	"missing-meta",
+	"invalid-meta",
+	"invalid-name",
+	"invalid-description",
+	"invalid-option",
+	"missing-route-meta",
+	"route-meta-without-path",
+	"unused-route-meta",
+	"mixed-command-and-subcommands",
+	"mixed-subcommand-and-group",
+	"command-too-deep",
+	"too-many-subcommands",
+	"context-menu-nested",
+	"top-level-field-on-group",
+	"top-level-field-on-subcommand",
+	"duplicate-command-name",
+	"too-many-commands",
+	"autocomplete-without-command",
+	"autocomplete-export-not-function",
+	"autocomplete-unknown-option",
+	"autocomplete-missing-handler",
+	"autocomplete-missing-file",
+	"missing-select-kind",
+	"invalid-select-kind",
+	"invalid-param-validator",
+	"catch-all-route",
+	"short-id-collision",
+	"duplicate-component-pattern",
+	"unknown-event",
+	"event-nested-path",
+	"event-mode-conflict",
+	"missing-intent",
+	"plugin-failed",
+	"plugin-invalid-change",
+	"plugin-unknown-route",
+	"plugin-missing-file"
+];
+const REFERENCE = "https://nectar-js.github.io/nectar/reference/diagnostics";
+/** The reference entry for a compiler code. Codes from plugins have none. */
+function docsUrl(code) {
+	return DIAGNOSTIC_CODES.includes(code) ? `${REFERENCE}#${code}` : void 0;
+}
+/** A value's type as a message puts it: `missing`, `a number`, `an array`. */
+function typeOf(value) {
+	if (value === void 0) return "missing";
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
 var Diagnostics = class {
 	items = [];
 	error(code, message, location = {}) {
@@ -184,11 +247,11 @@ const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 */
 function parseSegment(dirName) {
 	if (dirName.startsWith("[") || dirName.endsWith("]")) {
-		if (!dirName.startsWith("[") || !dirName.endsWith("]")) return fail(`"${dirName}" has an unmatched bracket. Dynamic segments look like [name].`);
+		if (!dirName.startsWith("[") || !dirName.endsWith("]")) return fail(`"${dirName}" has an unmatched bracket. Parameters look like [name].`);
 		const inner = dirName.slice(1, -1);
 		const isCatchAll = inner.startsWith("...");
 		const name = isCatchAll ? inner.slice(3) : inner;
-		if (!PARAM_NAME.test(name)) return fail(`"${dirName}" is not a valid parameter name. Use letters, digits, and underscores, and do not start with a digit.`);
+		if (!PARAM_NAME.test(name)) return fail(`"${dirName}" has an invalid parameter name. Parameters become keys of ctx.params, so use letters, digits, and underscores, and don't start with a digit.`);
 		return ok({
 			type: isCatchAll ? "catchAll" : "dynamic",
 			name
@@ -197,13 +260,13 @@ function parseSegment(dirName) {
 	if (dirName.startsWith("(") || dirName.endsWith(")")) {
 		if (!dirName.startsWith("(") || !dirName.endsWith(")")) return fail(`"${dirName}" has an unmatched parenthesis. Route groups look like (name).`);
 		const name = dirName.slice(1, -1);
-		if (!STATIC_NAME.test(name)) return fail(`"${dirName}" is not a valid group name. Use letters, digits, hyphens, and underscores.`);
+		if (!STATIC_NAME.test(name)) return fail(`"${dirName}" isn't a valid group name. Use letters, digits, hyphens, and underscores.`);
 		return ok({
 			type: "group",
 			name
 		});
 	}
-	if (!STATIC_NAME.test(dirName)) return fail(`"${dirName}" is not a valid segment name. Use letters, digits, hyphens, and underscores, and start with a letter or digit.`);
+	if (!STATIC_NAME.test(dirName)) return fail(`"${dirName}" can't be part of a route path. Use letters, digits, hyphens, and underscores, and start with a letter or digit.`);
 	return ok({
 		type: "static",
 		name: dirName
@@ -240,11 +303,11 @@ function fail(reason) {
 function paramValidatorsOf(handler, route) {
 	const declared = handler.params;
 	if (declared === void 0) return {};
-	if (typeof declared !== "object" || declared === null || Array.isArray(declared)) throw new Error(`\`params\` must be an object of validators, got ${typeof declared}.`);
+	if (typeof declared !== "object" || declared === null || Array.isArray(declared)) throw new Error(`params is ${typeOf(declared)}, not an object of validators.`);
 	const validators = {};
 	for (const [name, validator] of Object.entries(declared)) {
-		if (!route.params.includes(name)) throw new Error(`\`params\` validates "${name}", which is not a parameter of this route. ${route.params.length === 0 ? "It has none." : `It has: ${route.params.join(", ")}.`}`);
-		if (!isValidator(validator)) throw new Error(`\`params.${name}\` must be a function or a Standard Schema, got ${typeof validator}.`);
+		if (!route.params.includes(name)) throw new Error(`params validates "${name}", which is not a parameter of this route. ${route.params.length === 0 ? "It has none." : `It has: ${route.params.join(", ")}.`}`);
+		if (!isValidator(validator)) throw new Error(`params.${name} is ${typeOf(validator)}. A validator is a function or a Standard Schema.`);
 		validators[name] = validator;
 	}
 	return validators;
@@ -337,7 +400,7 @@ async function compileRoute(route, diagnostics) {
 	const last = route.segments.at(-1);
 	const catchAll = last?.type === "catchAll" ? last.name : null;
 	const overhead = 8 + route.params.length;
-	if (catchAll !== null) diagnostics.warn("catch-all-route", `${formatSegment(last)} accepts any number of values. Every value counts against Discord's 100 character custom ID limit, and generation throws when it is exceeded.`, {
+	if (catchAll !== null) diagnostics.warn("catch-all-route", `${formatSegment(last)} takes any number of values. They all count toward Discord's 100 character limit on custom IDs, and customId() throws when an ID goes over.`, {
 		file: route.file,
 		route: route.id
 	});
@@ -345,17 +408,17 @@ async function compileRoute(route, diagnostics) {
 	try {
 		module = await loadModule(route.file);
 	} catch (error) {
-		diagnostics.error("module-load-failed", `Could not import this file: ${error instanceof Error ? error.message : String(error)}`, {
+		diagnostics.error("module-load-failed", `The compiler imports every route file to read its exports, and this one threw: ${error instanceof Error ? error.message : String(error)}`, {
 			file: route.file,
 			route: route.id
 		});
 		return null;
 	}
-	if (!checkDeclaredRoute(module, route, diagnostics)) return null;
+	if (!checkHandler(module, route, diagnostics)) return null;
 	try {
 		paramValidatorsOf(module.default, route);
 	} catch (error) {
-		diagnostics.error("invalid-param-validator", `${error instanceof Error ? error.message : String(error)} Pass validators as defineComponent's third argument: { params: { name: (value) => ... } }.`, {
+		diagnostics.error("invalid-param-validator", `${error instanceof Error ? error.message : String(error)} Validators go in defineComponent's third argument, like { params: { id: (value) => ... } }.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -375,13 +438,23 @@ async function compileRoute(route, diagnostics) {
 		overhead
 	};
 }
-/** A handler made with `defineComponent(path, ...)` must name the route its file sits in. */
-function checkDeclaredRoute(module, route, diagnostics, expected = route.path) {
+/**
+* The default export is the handler Nectar calls, and one made with `defineComponent(path, ...)`
+* or the like must name the route its file sits in.
+*/
+function checkHandler(module, route, diagnostics, expected = route.path) {
 	const handler = module.default;
-	if (typeof handler !== "function") return true;
+	if (typeof handler !== "function") {
+		const define = route.kind === "command" ? "defineCommand" : route.kind === "event" ? "defineEvent" : "defineComponent";
+		diagnostics.error("missing-handler", `This ${path.basename(route.file)} ${handler === void 0 ? "has no default export" : `exports ${typeOf(handler)} as its default`}. Nectar calls the default export when the route runs, so export the handler, like export default ${define}("${expected}", handler).`, {
+			file: route.file,
+			route: route.id
+		});
+		return false;
+	}
 	const declared = handler.route;
 	if (declared === void 0 || declared === expected) return true;
-	diagnostics.error("route-mismatch", `This file is the route "${expected}" but its handler declares "${String(declared)}". Update the string or move the file.`, {
+	diagnostics.error("route-mismatch", `This file's route is "${expected}", but its handler says "${String(declared)}". The string types the handler, so it has to match where the file is. Change it to "${expected}", or move the file.`, {
 		file: route.file,
 		route: route.id
 	});
@@ -390,14 +463,14 @@ function checkDeclaredRoute(module, route, diagnostics, expected = route.path) {
 function validateSelectKind(module, route, diagnostics) {
 	const kind = module.kind;
 	if (kind === void 0) {
-		diagnostics.error("missing-select-kind", "select.ts must export `kind`: \"string\", \"user\", \"role\", \"channel\", or \"mentionable\".", {
+		diagnostics.error("missing-select-kind", "This select.ts doesn't export kind, which says what the select menu picks from: \"string\", \"user\", \"role\", \"channel\", or \"mentionable\". Add one, like export const kind = \"string\".", {
 			file: route.file,
 			route: route.id
 		});
 		return null;
 	}
 	if (typeof kind !== "string" || !SELECT_KINDS.has(kind)) {
-		diagnostics.error("invalid-select-kind", `\`kind\` is ${describe$1(kind)}. Expected "string", "user", "role", "channel", or "mentionable".`, {
+		diagnostics.error("invalid-select-kind", `kind is ${describe$1(kind)}. Use "string", "user", "role", "channel", or "mentionable".`, {
 			file: route.file,
 			route: route.id
 		});
@@ -413,7 +486,7 @@ function detectShortIdCollisions(routes, diagnostics) {
 			seen.set(route.shortId, route);
 			continue;
 		}
-		diagnostics.error("short-id-collision", `${route.id} and ${existing.id} hash to the same short ID "${route.shortId}", so their custom IDs would be indistinguishable. Rename one of the directories.`, {
+		diagnostics.error("short-id-collision", `${route.id} and ${existing.id} hash to the same short ID, "${route.shortId}", so Nectar can't tell their custom IDs apart. Rename a directory in one of them.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -421,7 +494,8 @@ function detectShortIdCollisions(routes, diagnostics) {
 }
 /**
 * Two routes of the same kind whose paths differ only in parameter names, like
-* `tickets/[id]/close` and `tickets/[ticketId]/close`, would both claim the same custom IDs.
+* `tickets/[id]/close` and `tickets/[ticketId]/close`. Their hashes differ, but they take the
+* same values in the same places, so they are one route split in two.
 */
 function detectDuplicatePatterns(routes, diagnostics) {
 	const seen = /* @__PURE__ */ new Map();
@@ -434,7 +508,7 @@ function detectDuplicatePatterns(routes, diagnostics) {
 			continue;
 		}
 		if (existing.id === route.id) continue;
-		diagnostics.error("duplicate-component-pattern", `${route.id} has the same shape as ${existing.id} (${relative(existing.file)}). Parameter names do not make routes distinct.`, {
+		diagnostics.error("duplicate-component-pattern", `${route.id} is the same path as ${existing.id} in ${relative(existing.file)}, with a different parameter name. Parameter names don't make routes distinct. Merge the two and keep one name.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -484,9 +558,10 @@ function toManifest(graph, outDir) {
 		};
 	};
 	const routes = [];
-	for (const command of graph.commands) for (const route of Object.values(command.handlers)) routes.push({
+	for (const command of graph.commands) for (const [key, route] of Object.entries(command.handlers)) routes.push({
 		...base(route),
-		kind: "command"
+		kind: "command",
+		defer: command.defer[key] ?? null
 	});
 	for (const entry of graph.autocomplete) routes.push({
 		...base(entry.route),
@@ -591,23 +666,24 @@ async function applyPlugins(graph, plugins) {
 function apply(graph, plugin, change) {
 	const type = isRecord(change) ? change.type : void 0;
 	if (type !== "middleware" && type !== "diagnostic") {
-		graph.diagnostics.error("plugin-invalid-change", `Plugin "${plugin}" returned a change of type ${JSON.stringify(type)}. Known types: middleware, diagnostic.`);
+		graph.diagnostics.error("plugin-invalid-change", `Plugin "${plugin}" returned a change with type ${JSON.stringify(type)}. A change's type is "middleware" or "diagnostic".`);
 		return;
 	}
 	if (change.type === "diagnostic") {
 		const { severity, code, message, file, route } = change;
-		const where = {
+		graph.diagnostics.items.push({
+			code,
+			severity: severity === "error" ? "error" : "warning",
+			message,
 			...file === void 0 ? {} : { file },
 			...route === void 0 ? {} : { route }
-		};
-		if (severity === "error") graph.diagnostics.error(code, message, where);
-		else graph.diagnostics.warn(code, message, where);
+		});
 		return;
 	}
 	const routes = graph.routes.filter((r) => r.id === change.route && (change.kind === void 0 || r.kind === change.kind));
 	const target = change.kind === void 0 ? change.route : `${change.route} (${change.kind})`;
 	if (routes.length === 0) {
-		graph.diagnostics.error("plugin-unknown-route", `Plugin "${plugin}" adds middleware to route "${target}", which does not exist.`);
+		graph.diagnostics.error("plugin-unknown-route", `Plugin "${plugin}" adds middleware to route "${target}", which does not exist. Route IDs look like "command:moderation/ban".`);
 		return;
 	}
 	if (routes.some((r) => r.category === "event")) {
@@ -658,6 +734,6 @@ var PluginError = class extends Error {
 	}
 };
 //#endregion
-export { MAX_CUSTOM_ID_LENGTH as C, CustomIdTooLongError as S, version as T, parseSegment as _, MANIFEST_FILE as a, loadModule as b, writeManifest as c, checkDeclaredRoute as d, compileComponents as f, formatSegment as g, paramValidatorsOf as h, pluginGraph as i, encodeComponentRoute as l, findInvalidParam as m, definePlugin as n, stableStringify as o, customIdFor as p, applyPlugins as r, toManifest as s, PluginError as t, registerComponentRoutes as u, enableModuleReloading as v, decodeCustomId as w, Diagnostics as x, invalidateModuleGraph as y };
+export { typeOf as C, version as D, decodeCustomId as E, docsUrl as S, MAX_CUSTOM_ID_LENGTH as T, parseSegment as _, MANIFEST_FILE as a, loadModule as b, writeManifest as c, checkHandler as d, compileComponents as f, formatSegment as g, paramValidatorsOf as h, pluginGraph as i, encodeComponentRoute as l, findInvalidParam as m, definePlugin as n, stableStringify as o, customIdFor as p, applyPlugins as r, toManifest as s, PluginError as t, registerComponentRoutes as u, enableModuleReloading as v, CustomIdTooLongError as w, Diagnostics as x, invalidateModuleGraph as y };
 
-//# sourceMappingURL=plugins-CGvM19v9.js.map
+//# sourceMappingURL=plugins-C2uwN3-D.js.map