@nectar-js/nectar 0.1.0

package/dist/index-DGMxBsub.d.ts

@@ -0,0 +1,757 @@
+import { ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, Client, ClientEvents, ClientOptions, GatewayIntentBits, Interaction, MentionableSelectMenuInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, PermissionResolvable, RoleSelectMenuInteraction, StringSelectMenuInteraction, 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/`. */
+declare const version: string;
+//#endregion
+//#region src/commands/meta.d.ts
+type CommandType = "chatInput" | "user" | "message";
+type OptionType = "string" | "integer" | "number" | "boolean" | "user" | "channel" | "role" | "mentionable" | "attachment";
+interface OptionChoice<Value extends string | number = string | number> {
+  name: string;
+  value: Value;
+  nameLocalizations?: LocalizationMap;
+}
+interface BaseOption {
+  name: string;
+  description: string;
+  required?: boolean;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+interface StringOption extends BaseOption {
+  type: "string";
+  choices?: OptionChoice<string>[];
+  autocomplete?: boolean;
+  minLength?: number;
+  maxLength?: number;
+}
+interface IntegerOption extends BaseOption {
+  type: "integer";
+  choices?: OptionChoice<number>[];
+  autocomplete?: boolean;
+  minValue?: number;
+  maxValue?: number;
+}
+interface NumberOption extends BaseOption {
+  type: "number";
+  choices?: OptionChoice<number>[];
+  autocomplete?: boolean;
+  minValue?: number;
+  maxValue?: number;
+}
+interface ChannelOption extends BaseOption {
+  type: "channel";
+  channelTypes?: ChannelType[];
+}
+interface SimpleOption extends BaseOption {
+  type: "boolean" | "user" | "role" | "mentionable" | "attachment";
+}
+type CommandOption = StringOption | IntegerOption | NumberOption | ChannelOption | SimpleOption;
+/**
+ * Registration settings that Discord only accepts on a top-level command.
+ * For a command with subcommands these live in the parent directory's `route.ts`.
+ */
+interface TopLevelMeta {
+  defaultMemberPermissions?: bigint | string | number | null;
+  nsfw?: boolean;
+  contexts?: InteractionContextType[];
+  integrationTypes?: ApplicationIntegrationType[];
+}
+/** `export const meta` in a `command.ts`. */
+interface CommandMeta extends TopLevelMeta {
+  /** Overrides the name derived from the directory. */
+  name?: string;
+  /** Required for chat input commands and subcommands. Must be omitted for context menus. */
+  description?: string;
+  /** Defaults to `"chatInput"`. Context menu commands cannot be nested or have options. */
+  type?: CommandType;
+  options?: CommandOption[];
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+/** `export const meta` in a `route.ts` under `commands/`. Describes a parent command or subcommand group. */
+interface CommandRouteMeta extends TopLevelMeta {
+  name?: string;
+  description: string;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+//#endregion
+//#region src/compiler/diagnostics.d.ts
+type Severity = "error" | "warning";
+//#endregion
+//#region src/compiler/routes.d.ts
+type RouteCategory = "command" | "component" | "event";
+type RouteKind = "command" | "autocomplete" | "button" | "select" | "modal" | "event";
+//#endregion
+//#region src/components/compile.d.ts
+type SelectKind = "string" | "user" | "role" | "channel" | "mentionable";
+//#endregion
+//#region src/components/customId.d.ts
+/** Discord rejects custom IDs longer than this. */
+declare const MAX_CUSTOM_ID_LENGTH = 100;
+declare class CustomIdTooLongError extends Error {
+  readonly customId: string;
+  readonly routeId: string;
+  constructor(customId: string, routeId: string);
+}
+//#endregion
+//#region src/components/params.d.ts
+/**
+ * A Standard Schema (https://standardschema.dev) validator, which zod, valibot, and arktype
+ * all produce. Only the result's `issues` are looked at: a schema that transforms the value
+ * does not change what the handler receives.
+ */
+interface StandardSchemaLike<V = unknown> {
+  "~standard": {
+    validate(value: V): {
+      issues?: ReadonlyArray<unknown> | undefined;
+    } | Promise<{
+      issues?: ReadonlyArray<unknown> | undefined;
+    }>;
+  };
+}
+/**
+ * Checks one custom ID parameter. A function passes by returning anything but `false` and
+ * fails by returning `false` or throwing. A schema fails by reporting issues.
+ */
+type ParamValidator<V = string | string[]> = ((value: V) => unknown) | StandardSchemaLike<V>;
+//#endregion
+//#region src/runtime/logger.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** Structured metadata attached to a log line. `error` is the thrown value, when there is one. */
+type LogFields = Record<string, unknown>;
+interface LogRecord {
+  level: LogLevel;
+  message: string;
+  /** Epoch milliseconds. */
+  at: number;
+  fields: LogFields;
+}
+/** Where log records go. The default prints to the console; an app can hand records to any library. */
+type LogSink = (record: LogRecord) => void;
+interface LoggerOptions {
+  /** Lowest level that reaches the sink. Defaults to `info`. */
+  level?: LogLevel;
+  sink?: LogSink;
+}
+//#endregion
+//#region src/runtime/signals.d.ts
+/** Structured, non-sensitive description of an interaction for logs and signals. */
+interface InteractionMeta {
+  type: "chatInput" | "userContextMenu" | "messageContextMenu" | "autocomplete" | "button" | "select" | "modal" | "unknown";
+  /** Full command name with subcommand group and subcommand, for commands and autocomplete. */
+  command?: string;
+  /** Custom ID with Nectar param values replaced by `*`. */
+  customId?: string;
+  guildId: string | null;
+  channelId: string | null;
+  userId: string | null;
+}
+interface RegistrationScopeResult {
+  scope: string;
+  /** A bulk overwrite was sent. */
+  applied: boolean;
+}
+/** Everything the runtime reports about itself, without the timestamp. */
+type SignalData = {
+  type: "interaction:start";
+  trace: string;
+  interaction: InteractionMeta;
+} | {
+  type: "route:match";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+} | {
+  type: "middleware:enter";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+  file: string;
+} | {
+  type: "handler:enter";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+} | {
+  type: "handler:complete";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+  /** Milliseconds the handler took. */
+  duration: number;
+} | {
+  type: "interaction:complete";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+  /** Milliseconds since the runtime received the interaction. */
+  duration: number;
+  /** `false` when a middleware stopped the chain before the handler. */
+  handled: boolean;
+} | {
+  type: "interaction:fail";
+  trace: string;
+  interaction: InteractionMeta;
+  route: RouteInfo;
+  error: unknown;
+  /** The `error.ts` that handled it, or `null` for the default boundary. */
+  boundary: string | null;
+} | {
+  /** The interaction was refused before any application code ran. */
+  type: "interaction:reject";
+  trace: string;
+  interaction: InteractionMeta;
+  reason: RejectReason;
+  /** Known when the route matched but a parameter failed validation. */
+  route?: RouteInfo;
+  /** The parameter that failed, for `invalid-param`. Its value is never included. */
+  param?: string;
+} | {
+  type: "event:fail";
+  event: string;
+  route: RouteInfo;
+  error: unknown;
+  boundary: string | null;
+} | {
+  type: "registration:start";
+  scopes: string[];
+} | {
+  type: "registration:complete";
+  scopes: RegistrationScopeResult[];
+  duration: number;
+} | {
+  type: "gateway:connect";
+  shard: number;
+  resumed: boolean;
+} | {
+  type: "gateway:disconnect";
+  shard: number;
+  code: number;
+} | {
+  type: "shutdown";
+};
+type RejectReason =
+/** A command, autocomplete option, or context menu Discord sent that no route serves. */
+"no-route" |
+/** An interaction type Nectar does not route at all. */
+"unknown-interaction" |
+/** A Nectar custom ID that cannot be decoded. */
+"malformed" |
+/** A decoded custom ID whose short ID names no route of that kind. */
+"unknown-route" |
+/** The wrong number of values for the route. */
+"param-count" |
+/** A route's own validator refused a value. */
+"invalid-param";
+type SignalType = SignalData["type"];
+type Signal = SignalData & {
+  /** Epoch milliseconds. */
+  at: number;
+};
+type SignalListener = (signal: Signal) => void;
+interface SignalEmitter {
+  /** Delivers every signal to `listener`. Returns a function that unsubscribes. */
+  on(listener: SignalListener): () => void;
+  emit(data: SignalData): void;
+}
+//#endregion
+//#region src/runtime/types.d.ts
+type Env = "development" | "test" | "production";
+interface RouteInfo {
+  id: string;
+  category: RouteCategory;
+  path: string;
+  /** Absolute path of the handler file. */
+  file: string;
+}
+interface Trace {
+  /** The interaction ID. */
+  id: string;
+  /** When the runtime received the interaction, epoch milliseconds. */
+  receivedAt: number;
+  /** Milliseconds since Discord created the interaction. Replies must land within 3000. */
+  elapsed(): number;
+}
+type Params = Record<string, string | string[]>;
+interface InteractionContext<I = Interaction, P = Params> {
+  interaction: I;
+  client: Client;
+  route: RouteInfo;
+  params: P;
+  env: Env;
+  trace: Trace;
+  /** What plugins provide. Empty without plugins. */
+  services: NectarServices;
+}
+interface EventContext {
+  client: Client;
+  route: RouteInfo;
+  env: Env;
+  services: NectarServices;
+}
+/** What a middleware's `next()` accepts: extra fields merged into the downstream context. */
+type ContextExtension = Record<string, unknown>;
+declare const extension: unique symbol;
+/** Carries the extension type through `next()`'s return value so `defineMiddleware` can infer it. */
+interface Extended<E extends ContextExtension> {
+  readonly [extension]?: E;
+}
+type Next = <E extends ContextExtension = Record<never, never>>(extension?: E) => Promise<Extended<E>>;
+type Middleware<E extends ContextExtension = ContextExtension> = ((ctx: InteractionContext, next: Next) => unknown) & Extended<E>;
+/** The context fields a middleware module adds downstream. `{}` for plain functions. */
+type MiddlewareExtension<M> = M extends {
+  default: Extended<infer E>;
+} ? ContextExtension extends E ? Record<never, never> : E : Record<never, never>;
+/**
+ * Return `"unhandled"` or throw to pass the error to the next boundary up. Returning anything
+ * else marks it handled.
+ */
+type ErrorHandler = (error: unknown, ctx: InteractionContext | EventContext) => unknown | Promise<unknown>;
+/**
+ * Framework logger. `fields` is structured metadata for the sink: route identity, trace, guild,
+ * user, and so on. The thrown value goes under `error`.
+ */
+interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+}
+//#endregion
+//#region src/cli/project.d.ts
+interface Project {
+  /** Directory holding the config file. Every relative config path resolves against it. */
+  root: string;
+  configFile: string;
+  /** With the overrides for `env` applied. */
+  config: NectarConfig;
+  appDir: string;
+  outDir: string;
+  env: Env;
+}
+//#endregion
+//#region src/events/compile.d.ts
+/** `export const meta` in an `event.ts`. Every field is optional. */
+interface EventMeta {
+  /** Remove the listener after the first call. */
+  once?: boolean;
+  /** Handlers of the same event run in ascending order. Ties break on route identity. Defaults to 0. */
+  order?: number;
+  /**
+   * How the handlers of this event run relative to each other. Every handler that sets it
+   * must agree. Defaults to `"sequential"`.
+   */
+  mode?: EventMode;
+}
+type EventMode = "sequential" | "concurrent";
+//#endregion
+//#region src/manifest/schema.d.ts
+declare const MANIFEST_VERSION = 1;
+/**
+ * The compiled app, as written to `.nectar/manifest.json`.
+ *
+ * Every file path is relative to `appDir`, with `/` separators, so a manifest built on one
+ * machine loads on another. `appDir` itself is relative to the manifest's own directory.
+ */
+interface Manifest {
+  version: typeof MANIFEST_VERSION;
+  /** `@nectar-js/nectar` version that produced this manifest. */
+  nectar: string;
+  appDir: string;
+  routes: ManifestRoute[];
+  commands: ManifestCommand[];
+  events: ManifestEvent[];
+}
+interface ManifestRouteBase {
+  /** Canonical identity, `<category>:<path>`. Unique together with `kind`. */
+  id: string;
+  category: RouteCategory;
+  path: string;
+  file: string;
+  /** Middleware files in execution order, root first. */
+  middleware: string[];
+  /** Error boundary files, nearest first. */
+  errors: string[];
+  /** Plugins that changed this route's chains, in config order. */
+  plugins: string[];
+}
+interface ManifestCommandRoute extends ManifestRouteBase {
+  kind: "command";
+}
+interface ManifestAutocompleteRoute extends ManifestRouteBase {
+  kind: "autocomplete";
+  /** Option names handled, each a named export of the file. */
+  options: string[];
+}
+interface ManifestComponentRoute extends ManifestRouteBase {
+  kind: "button" | "select" | "modal";
+  shortId: string;
+  params: string[];
+  catchAll: string | null;
+  selectKind: SelectKind | null;
+  overhead: number;
+}
+interface ManifestEventRoute extends ManifestRouteBase {
+  kind: "event";
+  event: string;
+  once: boolean;
+  order: number;
+}
+type ManifestRoute = ManifestCommandRoute | ManifestAutocompleteRoute | ManifestComponentRoute | ManifestEventRoute;
+interface ManifestCommand {
+  name: string;
+  type: number;
+  payload: RESTPostAPIApplicationCommandsJSONBody;
+  /** Handler position (`""`, `"sub"`, or `"group/sub"`) to command route ID. */
+  handlers: Record<string, string>;
+}
+interface ManifestEvent {
+  name: string;
+  mode: EventMode;
+  /** Event route IDs in execution order. */
+  handlers: string[];
+}
+//#endregion
+//#region src/plugins/index.d.ts
+/**
+ * A plugin takes part in compilation and the runtime lifecycle. A library that only exports
+ * functions for handlers to call does not need to be one.
+ */
+interface NectarPlugin {
+  /** Unique among the configured plugins. Named in diagnostics and in the manifest. */
+  name: string;
+  version?: string;
+  /**
+   * Runs after the route graph is validated and before the manifest is written. The graph is
+   * frozen; return changes and the compiler applies and checks them. Plugins run in config
+   * order, each seeing the changes of the ones before it.
+   */
+  transform?(graph: PluginGraph): Maybe<PluginChange[]> | Promise<Maybe<PluginChange[]>>;
+  /** Declarations appended to `.nectar/types.d.ts`. */
+  types?(graph: PluginGraph): Maybe<string>;
+  /** Extra `nectar <name>` commands. */
+  commands?: PluginCommand[];
+  /**
+   * Runs when the runtime starts, before any handler is imported and before login. A sharded
+   * bot runs it in every process. Returned services land on `ctx.services` for every handler
+   * and middleware.
+   */
+  start?(app: PluginApp): Maybe<Partial<NectarServices>> | Promise<Maybe<Partial<NectarServices>>>;
+  /** Runs on shutdown, after in-flight interactions drain and before the client is destroyed. */
+  stop?(app: PluginApp): void | Promise<void>;
+  /**
+   * Runs once per application, in the process that runs shard 0, after every `start`. For work
+   * that must not repeat per shard process: a scheduled job, a web server, posting stats.
+   */
+  startGlobal?(app: PluginApp): void | Promise<void>;
+  /** Runs on shutdown in the process that ran `startGlobal`, before any `stop`. */
+  stopGlobal?(app: PluginApp): void | Promise<void>;
+}
+/** A hook may return nothing, so a body without `return` type-checks. */
+type Maybe<T> = T | undefined | void;
+type PluginChange = {
+  type: "middleware";
+  /** Route ID, `<category>:<path>`. */
+  route: string;
+  /**
+   * Only the route of this kind. A command and its autocomplete share an ID; without
+   * `kind`, both get the middleware, as they would from a `middleware.ts`.
+   */
+  kind?: RouteKind;
+  /** Absolute path of a module whose default export is a middleware. */
+  file: string;
+  /** `outer` (default) runs before the app's own middleware, `inner` right before the handler. */
+  position?: "outer" | "inner";
+} | {
+  type: "diagnostic";
+  severity: Severity;
+  code: string;
+  message: string;
+  file?: string;
+  route?: string;
+};
+type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
+/** The compiled app as a plugin sees it: the manifest shape with absolute file paths, frozen. */
+interface PluginGraph {
+  readonly appDir: string;
+  readonly routes: DeepReadonly<ManifestRoute[]>;
+  readonly commands: DeepReadonly<ManifestCommand[]>;
+  readonly events: DeepReadonly<ManifestEvent[]>;
+}
+interface PluginApp {
+  readonly client: Client;
+  readonly env: Env;
+  readonly logger: Logger;
+  readonly signals: SignalEmitter;
+  readonly manifest: Manifest;
+}
+interface PluginCommand {
+  name: string;
+  description: string;
+  options?: Record<string, {
+    type: "boolean" | "string";
+    description: string;
+  }>;
+  /** Returns the exit code. */
+  run(ctx: PluginCommandContext): number | Promise<number>;
+}
+interface PluginCommandContext {
+  project: Project;
+  flags: Record<string, string | boolean | undefined>;
+  out(line: string): void;
+  err(line: string): void;
+}
+declare function definePlugin(plugin: NectarPlugin): NectarPlugin;
+/** A plugin misbehaved: threw from a hook, or provided something that clashes. */
+declare class PluginError extends Error {
+  readonly plugin: string;
+  readonly detail: string;
+  constructor(plugin: string, detail: string);
+}
+//#endregion
+//#region src/config.d.ts
+/** `nectar.config.ts`: `export default defineConfig({ ... })`. */
+interface NectarConfig {
+  /**
+   * Bot token. Usually `process.env.DISCORD_TOKEN`; the CLI falls back to that variable when
+   * this is omitted or empty.
+   */
+  token?: string | undefined;
+  /** Application ID, for command registration. Falls back to `DISCORD_APPLICATION_ID`. */
+  applicationId?: string | undefined;
+  intents: ClientOptions["intents"];
+  partials?: ClientOptions["partials"];
+  /** Extra discord.js client options. `intents` and `partials` above take precedence. */
+  client?: Partial<ClientOptions>;
+  /** Import every handler at startup. Defaults to `true` in production, `false` otherwise. */
+  eager?: boolean;
+  /** Overrides `NODE_ENV`. */
+  env?: Env;
+  /**
+   * Framework log level and sink. The default sink prints to the console; pass `sink` to hand
+   * records to your own logger. Handlers are free to log however they like.
+   */
+  logger?: LoggerOptions;
+  /** Called with every framework signal: interaction lifecycle, failures, gateway state, shutdown. */
+  observe?: (signal: Signal) => void;
+  /** Plugins, in the order their hooks run. This is the only way to register one. */
+  plugins?: NectarPlugin[];
+  /** Route directory, relative to the project root. Defaults to `app`. */
+  appDir?: string;
+  /** Build output, relative to the project root. Defaults to `.nectar`. */
+  outDir?: string;
+  dev?: {
+    /** Guilds that receive commands instantly while developing. */
+    guilds?: string[];
+  };
+  commands?: {
+    /**
+     * Where commands are registered outside development: everywhere, or only in the listed
+     * guilds. Defaults to `"global"`. Development always uses `dev.guilds`.
+     */
+    target?: "global" | string[];
+  };
+  /**
+   * Overrides for one environment, applied once the environment is known. Each key replaces
+   * the value above it; nested objects are not merged.
+   */
+  environments?: Partial<Record<Env, Partial<Omit<NectarConfig, "env" | "environments">>>>;
+}
+declare function defineConfig(config: NectarConfig): NectarConfig;
+declare class ConfigError extends Error {
+  readonly file: string;
+  readonly detail: string;
+  constructor(file: string, detail: string);
+}
+/** Checks a loaded config's shape. Discord validates intent and partial values itself at login. */
+declare function validateConfig(value: unknown, file: string): NectarConfig;
+//#endregion
+//#region src/define.d.ts
+type Empty = Record<never, never>;
+/** `NectarRoutes[K]` when the generated types declare it, otherwise `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}`;
+/** Component routes by path. Until types are generated, any string is accepted. */
+type ComponentRoutes = Fallback<Declared<"components">, Record<string, {
+  kind: ComponentKindName;
+  params: Params;
+  context: Empty;
+}>>;
+/** 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>;
+  context: Empty;
+}>>;
+type ComponentPath = keyof ComponentRoutes & string;
+type CommandPath = keyof CommandRoutes & string;
+type Route<Routes, P extends string> = P extends keyof Routes ? Routes[P] : never;
+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;
+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>;
+/** 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>];
+/**
+ * The custom ID for a component route, ready for a discord.js builder.
+ *
+ * Typed against the generated route map: the path must exist and the parameters must match
+ * the dynamic segments. Throws when a value is missing or the ID would exceed Discord's limit.
+ */
+declare function customId<P extends ComponentPath>(route: P, ...args: ParamsArg<P>): string;
+/** A handler that remembers which route it was written for, so the compiler can check the file location. */
+type Routed<F> = F & {
+  route: string;
+};
+declare function defineCommand<P extends CommandPath>(route: P, handler: (ctx: CommandContext<P>) => unknown): Routed<typeof handler>;
+interface ComponentOptions<P extends ComponentPath> {
+  /**
+   * Validators for the route's parameters, run on every incoming custom ID before middleware.
+   * A parameter without one accepts any string. When a validator fails the interaction is
+   * dropped and reported; the handler never sees it.
+   */
+  params?: { [K in keyof ComponentParams<P>]?: ParamValidator<ComponentParams<P>[K]>; };
+}
+declare function defineComponent<P extends ComponentPath>(route: P, handler: (ctx: ComponentContext<P>) => unknown, options?: ComponentOptions<P>): Routed<typeof handler>;
+declare function defineEvent<Name extends keyof ClientEvents>(event: Name, handler: (...args: [...ClientEvents[Name], EventContext]) => unknown): Routed<typeof handler>;
+/**
+ * `return next({ member })` types `member` onto every downstream context. Middleware that
+ * calls `next()` without returning it adds nothing; pass the extension type explicitly if
+ * you need both.
+ */
+declare function defineMiddleware<E extends ContextExtension = Empty>(middleware: (ctx: InteractionContext, next: Next) => Promise<Extended<E> | undefined | void> | Extended<E> | undefined | void): Middleware<E>;
+declare function defineError(handler: ErrorHandler): ErrorHandler;
+//#endregion
+//#region src/events/intents.d.ts
+type Intent = keyof typeof GatewayIntentBits;
+/** The intents an event route depends on, for tooling. Empty when it needs none. */
+declare function requiredIntents(event: string): readonly Intent[];
+//#endregion
+//#region src/policy.d.ts
+/**
+ * Opt-in policy middleware. Each returns a middleware that stops the chain and answers the
+ * user with a short ephemeral message when the check fails. Registration-time permissions
+ * (`meta.defaultMemberPermissions`) are a separate concept: Discord enforces those before the
+ * interaction reaches the bot, and server admins can override them. These checks run in the
+ * bot and cannot be overridden.
+ *
+ * Use them from a `middleware.ts`:
+ *
+ *     export default requirePermissions("BanMembers");
+ *
+ * Or compose them with your own middleware by calling them inside it.
+ */
+interface PolicyOptions {
+  /** What the user sees when the check fails. */
+  message?: string;
+}
+/** Passes only interactions that come from a guild. */
+declare function guildOnly(options?: PolicyOptions): Middleware;
+/** Passes only when the invoking member has every listed permission in the current channel. */
+declare function requirePermissions(permissions: PermissionResolvable, options?: PolicyOptions): Middleware;
+interface RoleOptions extends PolicyOptions {
+  /** `"any"` (default) passes with one matching role; `"all"` needs every listed role. */
+  mode?: "any" | "all";
+}
+/** Passes only when the invoking member holds the listed role IDs. */
+declare function requireRoles(roles: string | readonly string[], options?: RoleOptions): Middleware;
+//#endregion
+//#region src/registration/diff.d.ts
+interface CommandDiff {
+  /** Command names, `type:name` when the type is not chat input. */
+  added: string[];
+  removed: string[];
+  changed: string[];
+  unchanged: string[];
+  hasChanges: boolean;
+}
+//#endregion
+//#region src/registration/remote.d.ts
+/** The two calls registration needs. discord.js's `REST` satisfies this. */
+interface CommandRest {
+  get(route: `/${string}`): Promise<unknown>;
+  put(route: `/${string}`, options: {
+    body: unknown;
+  }): Promise<unknown>;
+}
+type Scope = "global" | {
+  guild: string;
+};
+//#endregion
+//#region src/registration/errors.d.ts
+interface RegistrationProblem {
+  /** Command name, or `null` when Discord rejected the request as a whole. */
+  command: string | null;
+  /** Dotted path inside the command, with option and choice indices replaced by their names. */
+  field: string;
+  message: string;
+}
+/** Discord rejected a bulk overwrite. Wraps the `DiscordAPIError` with per-command detail. */
+declare class RegistrationError extends Error {
+  readonly scope: Scope;
+  readonly problems: RegistrationProblem[];
+  readonly cause: unknown;
+  constructor(scope: Scope, problems: RegistrationProblem[], cause: unknown);
+  /** `null` when `error` is not a Discord API error. */
+  static from(error: unknown, scope: Scope, commands: RESTPostAPIApplicationCommandsJSONBody[]): RegistrationError | null;
+}
+//#endregion
+//#region src/registration/sync.d.ts
+interface SyncOptions {
+  rest: CommandRest;
+  applicationId: string;
+  commands: RESTPostAPIApplicationCommandsJSONBody[];
+  scopes: Scope[];
+  /** Directory holding `registration.json`. No cache when omitted. */
+  cacheDir?: string;
+  /** Compute diffs and report, but write nothing to Discord or the cache. */
+  dryRun?: boolean;
+  /** Proceed past the safety guard. */
+  force?: boolean;
+}
+interface ScopeSync {
+  scope: Scope;
+  /** `null` when the cache proved nothing changed and Discord was not consulted. */
+  diff: CommandDiff | null;
+  /** A bulk overwrite was sent. */
+  applied: boolean;
+}
+interface SyncResult {
+  scopes: ScopeSync[];
+  /** Why the guard would block this sync. Empty when it is safe. */
+  unsafe: string[];
+}
+/** Thrown instead of applying when the guard trips and `force` is not set. */
+declare class UnsafeSyncError extends Error {
+  readonly reasons: string[];
+  constructor(reasons: string[]);
+}
+/**
+ * Reconciles every scope: read remote, diff, bulk overwrite only when something differs.
+ * All scopes are read and checked before any is written, so a guard failure changes nothing.
+ */
+declare function syncCommands(options: SyncOptions): Promise<SyncResult>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Filled in by the generated `.nectar/types.d.ts` through module augmentation. Until then every
+ * route path is accepted and parameters are untyped.
+ */
+interface NectarRoutes {}
+/**
+ * What plugins put on `ctx.services`. A plugin declares its entry through module augmentation:
+ *
+ *     declare module "@nectar-js/nectar" {
+ *       interface NectarServices { audit: AuditLog }
+ *     }
+ */
+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