@azurioh/discord-kernel 0.1.0

package/dist/discord/command/router.d.ts

@@ -0,0 +1,48 @@
+import { type Interaction } from "discord.js";
+import type { ContextMenuCommand, SlashCommand } from "../../discord/command/types";
+import type { InteractionDispatcher } from "../../discord/interaction/interaction-router";
+import type { Presenter } from "../../discord/presenter";
+import type { Translator } from "../../i18n";
+import type { Logger } from "../../logger";
+export interface CommandRouterDeps {
+    presenter: Presenter;
+    logger: Logger;
+    translator: Translator;
+}
+/**
+ * Owns the registered slash commands and dispatches chat-input interactions to
+ * them, injecting the shared {@link CommandRuntime}. Also registers the command
+ * definitions with Discord's API. It does not attach its own listener — it is an
+ * {@link InteractionDispatcher} driven by the shared {@link InteractionRouter}.
+ */
+export declare class CommandRouter implements InteractionDispatcher {
+    private readonly deps;
+    private readonly commands;
+    private readonly contextMenuCommands;
+    private readonly runtime;
+    constructor(deps: CommandRouterDeps);
+    /** Register a command (last registration of a name wins). */
+    register(command: SlashCommand): this;
+    /** Register many commands at once. */
+    registerAll(commands: Iterable<SlashCommand>): this;
+    /**
+     * Register a context-menu entry. Kept in its own map because Discord treats a
+     * slash command and a context-menu entry as distinct application command
+     * types, and therefore lets them share a name.
+     */
+    registerContextMenu(command: ContextMenuCommand): this;
+    registerAllContextMenus(commands: Iterable<ContextMenuCommand>): this;
+    /** Look up a registered slash command, for dispatchers that share this registry. */
+    get(name: string): SlashCommand | undefined;
+    /** Claim and dispatch chat-input and context-menu commands; ignore everything else. */
+    handle(interaction: Interaction): Promise<boolean>;
+    /**
+     * Push every registered command to its declared scope: commands with
+     * `guildIds` go to those guild(s) (instant availability), the rest are
+     * deployed globally (available on every server, slower to propagate). The
+     * global scope is always synced — even when empty — so stale global commands
+     * are pruned. Returns the number of commands deployed.
+     */
+    deployCommands(token: string, clientId: string): Promise<number>;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/discord/command/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/discord/command/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAEX,kBAAkB,EAElB,YAAY,EACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,qBAAqB;IAK9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAC7E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAEZ,IAAI,EAAE,iBAAiB;IAQpD,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKrC,sCAAsC;IACtC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI;IAOnD;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAKtD,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAOrE,oFAAoF;IACpF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI3C,uFAAuF;IACjF,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBxD;;;;;;OAMG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsCtE"}

package/dist/discord/command/router.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandRouter = void 0;
+const discord_js_1 = require("discord.js");
+/**
+ * Owns the registered slash commands and dispatches chat-input interactions to
+ * them, injecting the shared {@link CommandRuntime}. Also registers the command
+ * definitions with Discord's API. It does not attach its own listener — it is an
+ * {@link InteractionDispatcher} driven by the shared {@link InteractionRouter}.
+ */
+class CommandRouter {
+    deps;
+    commands = new Map();
+    contextMenuCommands = new Map();
+    runtime;
+    constructor(deps) {
+        this.deps = deps;
+        this.runtime = {
+            presenter: deps.presenter,
+            logger: deps.logger,
+            translator: deps.translator,
+        };
+    }
+    /** Register a command (last registration of a name wins). */
+    register(command) {
+        this.commands.set(command.data.name, command);
+        return this;
+    }
+    /** Register many commands at once. */
+    registerAll(commands) {
+        for (const command of commands) {
+            this.register(command);
+        }
+        return this;
+    }
+    /**
+     * Register a context-menu entry. Kept in its own map because Discord treats a
+     * slash command and a context-menu entry as distinct application command
+     * types, and therefore lets them share a name.
+     */
+    registerContextMenu(command) {
+        this.contextMenuCommands.set(command.data.name, command);
+        return this;
+    }
+    registerAllContextMenus(commands) {
+        for (const command of commands) {
+            this.registerContextMenu(command);
+        }
+        return this;
+    }
+    /** Look up a registered slash command, for dispatchers that share this registry. */
+    get(name) {
+        return this.commands.get(name);
+    }
+    /** Claim and dispatch chat-input and context-menu commands; ignore everything else. */
+    async handle(interaction) {
+        if (interaction.isChatInputCommand()) {
+            const command = this.commands.get(interaction.commandName);
+            if (!command) {
+                return false;
+            }
+            await command.dispatch(interaction, this.runtime);
+            return true;
+        }
+        if (interaction.isContextMenuCommand()) {
+            const command = this.contextMenuCommands.get(interaction.commandName);
+            if (!command) {
+                return false;
+            }
+            await command.dispatch(interaction, this.runtime);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Push every registered command to its declared scope: commands with
+     * `guildIds` go to those guild(s) (instant availability), the rest are
+     * deployed globally (available on every server, slower to propagate). The
+     * global scope is always synced — even when empty — so stale global commands
+     * are pruned. Returns the number of commands deployed.
+     */
+    async deployCommands(token, clientId) {
+        const rest = new discord_js_1.REST({ version: "10" }).setToken(token);
+        const global = [];
+        const byGuild = new Map();
+        let deployed = 0;
+        const all = [
+            ...this.commands.values(),
+            ...this.contextMenuCommands.values(),
+        ];
+        for (const command of all) {
+            const body = command.data.toJSON ? command.data.toJSON() : null;
+            if (body === null) {
+                continue;
+            }
+            deployed += 1;
+            if (command.guildIds && command.guildIds.length > 0) {
+                for (const guildId of command.guildIds) {
+                    const bucket = byGuild.get(guildId) ?? [];
+                    bucket.push(body);
+                    byGuild.set(guildId, bucket);
+                }
+            }
+            else {
+                global.push(body);
+            }
+        }
+        await rest.put(discord_js_1.Routes.applicationCommands(clientId), { body: global });
+        this.deps.logger.info({ count: global.length }, "Global slash commands deployed");
+        for (const [guildId, body] of byGuild) {
+            await rest.put(discord_js_1.Routes.applicationGuildCommands(clientId, guildId), { body });
+            this.deps.logger.info({ guildId, count: body.length }, "Guild slash commands deployed");
+        }
+        return deployed;
+    }
+}
+exports.CommandRouter = CommandRouter;
+//# sourceMappingURL=router.js.map

package/dist/discord/command/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../src/discord/command/router.ts"],"names":[],"mappings":";;;AAAA,2CAA4D;AAkB5D;;;;;GAKG;AACH,MAAa,aAAa;IAKI;IAJZ,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC3C,mBAAmB,GAAG,IAAI,GAAG,EAA8B,CAAC;IAC5D,OAAO,CAAiB;IAEzC,YAA6B,IAAuB;QAAvB,SAAI,GAAJ,IAAI,CAAmB;QACnD,IAAI,CAAC,OAAO,GAAG;YACd,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC3B,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,QAAQ,CAAC,OAAqB;QAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACb,CAAC;IAED,sCAAsC;IACtC,WAAW,CAAC,QAAgC;QAC3C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,OAA2B;QAC9C,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,uBAAuB,CAAC,QAAsC;QAC7D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oFAAoF;IACpF,GAAG,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,MAAM,CAAC,WAAwB;QACpC,IAAI,WAAW,CAAC,kBAAkB,EAAE,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;YAC3D,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,OAAO,KAAK,CAAC;YACd,CAAC;YACD,MAAM,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAClD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,WAAW,CAAC,oBAAoB,EAAE,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;YACtE,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,OAAO,KAAK,CAAC;YACd,CAAC;YACD,MAAM,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAClD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAAC,KAAa,EAAE,QAAgB;QACnD,MAAM,IAAI,GAAG,IAAI,iBAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzD,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;QAC7C,IAAI,QAAQ,GAAG,CAAC,CAAC;QAEjB,MAAM,GAAG,GAAwB;YAChC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;YACzB,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE;SACpC,CAAC;QAEF,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAChE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBACnB,SAAS;YACV,CAAC;YACD,QAAQ,IAAI,CAAC,CAAC;YACd,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrD,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;oBACxC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;oBAC1C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAClB,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC9B,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACF,CAAC;QAED,MAAM,IAAI,CAAC,GAAG,CAAC,mBAAM,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,gCAAgC,CAAC,CAAC;QAElF,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;YACvC,MAAM,IAAI,CAAC,GAAG,CAAC,mBAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,+BAA+B,CAAC,CAAC;QACzF,CAAC;QAED,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD;AArHD,sCAqHC"}

package/dist/discord/command/types.d.ts

@@ -0,0 +1,51 @@
+import type { AutocompleteInteraction, ChatInputCommandInteraction, ContextMenuCommandInteraction } from "discord.js";
+import type { Presenter } from "../../discord/presenter";
+import type { Translator } from "../../i18n";
+import type { Logger } from "../../logger";
+/**
+ * Per-request dependencies injected into the command pipeline by the router.
+ * Passing these at dispatch time (rather than importing singletons) keeps the
+ * framework free of global state and trivially testable.
+ */
+export interface CommandRuntime {
+    readonly presenter: Presenter;
+    readonly logger: Logger;
+    readonly translator: Translator;
+}
+/**
+ * The framework's slash-command contract. `data` is a discord.js builder (or
+ * anything with `.toJSON()`); `dispatch` routes an interaction using the
+ * supplied runtime. `guildIds` restricts deployment to specific guild(s); when
+ * omitted the command is deployed globally (available on every server).
+ */
+export interface SlashCommand {
+    readonly data: {
+        name: string;
+        toJSON?: () => unknown;
+    };
+    readonly guildIds?: readonly string[];
+    dispatch(interaction: ChatInputCommandInteraction, runtime: CommandRuntime): Promise<void>;
+    /**
+     * Answer an autocomplete request for one of this command's options. Present
+     * only when at least one option declares a resolver, so the dispatcher can
+     * skip commands that never autocomplete.
+     */
+    autocomplete?(interaction: AutocompleteInteraction): Promise<void>;
+}
+/**
+ * A context-menu (a.k.a. application) command: the entry a user gets by
+ * right-clicking a member or a message. It shares deployment and permissions
+ * with a slash command, but carries no name to type and no options — only the
+ * target the user clicked.
+ */
+export interface ContextMenuCommand {
+    readonly data: {
+        name: string;
+        toJSON?: () => unknown;
+    };
+    readonly guildIds?: readonly string[];
+    dispatch(interaction: ContextMenuCommandInteraction, runtime: CommandRuntime): Promise<void>;
+}
+/** Anything the command router can register and deploy to Discord. */
+export type DeployableCommand = SlashCommand | ContextMenuCommand;
+//# sourceMappingURL=types.d.ts.map

package/dist/discord/command/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/discord/command/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,6BAA6B,EAC7B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAA;KAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,2BAA2B,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3F;;;;OAIG;IACH,YAAY,CAAC,CAAC,WAAW,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAA;KAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,6BAA6B,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F;AAED,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,kBAAkB,CAAC"}

package/dist/discord/command/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/discord/command/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/discord/command/types.ts"],"names":[],"mappings":""}

package/dist/discord/components/component-router.d.ts

@@ -0,0 +1,116 @@
+import { type AnySelectMenuInteraction, type ButtonInteraction, type Interaction, type ModalSubmitInteraction } from "discord.js";
+import type { InteractionDispatcher } from "../../discord/interaction/interaction-router";
+import { type PermissionBit } from "../../discord/permissions";
+import type { Presenter } from "../../discord/presenter";
+import { type Translator } from "../../i18n";
+import type { Logger } from "../../logger";
+/**
+ * Interactions a {@link ComponentHandler} can be routed: message components
+ * (buttons, any select menu) and modal submissions.
+ */
+export type RoutableInteraction = ButtonInteraction | AnySelectMenuInteraction | ModalSubmitInteraction;
+/** Per-dispatch dependencies, injected by the router (mirrors `CommandRuntime`). */
+export interface ComponentRuntime {
+    readonly presenter: Presenter;
+    readonly logger: Logger;
+    readonly translator: Translator;
+}
+/**
+ * Who may act on a component.
+ *
+ * A command declares its audience through `defaultMemberPermissions` + a
+ * `Guard`, and `Guard` is typed on `CommandInteraction` — deliberately, so a
+ * guard cannot be attached to a button. That leaves a component with no
+ * framework-level place to state who may click it, and the only thing standing
+ * between a member and a destructive button is whether whoever wrote the
+ * handler remembered to check. Every existing handler does; nothing makes the
+ * next one.
+ *
+ * So the answer is required by the type. There is no default and no optional
+ * field: a handler that says nothing does not compile, and "anyone may click
+ * this" has to be written down and justified rather than reached by omission.
+ */
+export type ComponentAuthorization = 
+/** Any member may click. `because` is why that is safe, not decoration. */
+{
+    readonly kind: "anyone";
+    readonly because: string;
+}
+/** The router denies unless the member holds every listed permission. */
+ | {
+    readonly kind: "permissions";
+    readonly required: readonly PermissionBit[];
+}
+/**
+ * The handler decides for itself, because the answer depends on state the
+ * router cannot see — whether this member opened *this* ticket, say.
+ */
+ | {
+    readonly kind: "handler";
+    readonly because: string;
+};
+/** Any member may click; `because` records why that is acceptable. */
+export declare function openToAnyone(because: string): ComponentAuthorization;
+/** The router denies the click unless the member holds every permission. */
+export declare function requiresPermissions(...required: readonly PermissionBit[]): ComponentAuthorization;
+/**
+ * The decision needs per-resource state, so the handler makes it. `because`
+ * names the rule it applies, so a reviewer can go and check that it does.
+ */
+export declare function checkedByHandler(because: string): ComponentAuthorization;
+/**
+ * A persistent component handler, routed by `customId`. It claims an interaction
+ * whose customId equals `customId` or starts with `${customId}:`, so dynamic
+ * state can be appended after a colon (e.g. handler `role` claims `role:add:123`).
+ *
+ * Best practice — handler (this) vs collector ({@link import("../../discord/components/paginator").mountPaginator}):
+ * use a **handler** for *persistent* components that must keep working forever and
+ * survive a restart (role pickers, ticket/verify buttons); the bot has no
+ * in-memory closure after a restart, so encode state in the customId (or refetch
+ * it). Use a **collector** for *transient*, single-message, owner-scoped flows
+ * with a lifetime (pagination, a confirm dialog) — its state lives in memory and
+ * dies on idle.
+ */
+export interface ComponentHandler {
+    readonly customId: string;
+    /** Who may act on this component. Required: see {@link ComponentAuthorization}. */
+    readonly authorize: ComponentAuthorization;
+    handle(interaction: RoutableInteraction, runtime: ComponentRuntime): Promise<void> | void;
+}
+/** Declare a {@link ComponentHandler}. Identity helper kept for a consistent DSL. */
+export declare function createComponentHandler(handler: ComponentHandler): ComponentHandler;
+export interface ComponentRouterDeps {
+    presenter: Presenter;
+    logger: Logger;
+    translator: Translator;
+}
+/**
+ * Routes persistent component/modal interactions to registered handlers by
+ * `customId`, injecting the shared {@link ComponentRuntime}. It does not attach
+ * its own listener — it is an {@link InteractionDispatcher} driven by the shared
+ * {@link import("../../discord/interaction/interaction-router").InteractionRouter},
+ * so commands and components share a single `interactionCreate` listener.
+ */
+export declare class ComponentRouter implements InteractionDispatcher {
+    private readonly deps;
+    private readonly handlers;
+    private readonly runtime;
+    constructor(deps: ComponentRouterDeps);
+    register(handler: ComponentHandler): this;
+    registerAll(handlers: Iterable<ComponentHandler>): this;
+    private match;
+    /** Claim and route component/modal interactions by `customId`; ignore the rest. */
+    handle(interaction: Interaction): Promise<boolean>;
+    /**
+     * Enforce the handler's declared audience. Only `permissions` is enforceable
+     * here — the other two kinds are statements about a decision made elsewhere,
+     * and their value is that the handler had to state one.
+     *
+     * `memberPermissions` is `null` outside a guild; that is a denial, since an
+     * unknown permission set must never be read as a granted one — the same rule
+     * `createPermissionGuard` follows for commands.
+     */
+    private passesAuthorization;
+    private localeOf;
+}
+//# sourceMappingURL=component-router.d.ts.map

package/dist/discord/components/component-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-router.d.ts","sourceRoot":"","sources":["../../../src/discord/components/component-router.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEhB,KAAK,sBAAsB,EAC3B,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC5B,iBAAiB,GACjB,wBAAwB,GACxB,sBAAsB,CAAC;AAE1B,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB;AACjC,2EAA2E;AACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACvD,yEAAyE;GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE;AAC/E;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAEpE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,sBAAsB,CAEjG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAExE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1F;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAElF;AAED,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;CACvB;AAMD;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;IAIhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAEd,IAAI,EAAE,mBAAmB;IAQtD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAKzC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAOvD,OAAO,CAAC,KAAK;IAMb,mFAAmF;IAC7E,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BxD;;;;;;;;OAQG;YACW,mBAAmB;IAuBjC,OAAO,CAAC,QAAQ;CAMhB"}

package/dist/discord/components/component-router.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentRouter = void 0;
+exports.openToAnyone = openToAnyone;
+exports.requiresPermissions = requiresPermissions;
+exports.checkedByHandler = checkedByHandler;
+exports.createComponentHandler = createComponentHandler;
+const discord_js_1 = require("discord.js");
+const i18n_1 = require("../../discord/i18n");
+const permissions_1 = require("../../discord/permissions");
+const i18n_2 = require("../../i18n");
+/** Any member may click; `because` records why that is acceptable. */
+function openToAnyone(because) {
+    return { kind: "anyone", because };
+}
+/** The router denies the click unless the member holds every permission. */
+function requiresPermissions(...required) {
+    return { kind: "permissions", required };
+}
+/**
+ * The decision needs per-resource state, so the handler makes it. `because`
+ * names the rule it applies, so a reviewer can go and check that it does.
+ */
+function checkedByHandler(because) {
+    return { kind: "handler", because };
+}
+/** Declare a {@link ComponentHandler}. Identity helper kept for a consistent DSL. */
+function createComponentHandler(handler) {
+    return handler;
+}
+function isRoutable(interaction) {
+    return interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit();
+}
+/**
+ * Routes persistent component/modal interactions to registered handlers by
+ * `customId`, injecting the shared {@link ComponentRuntime}. It does not attach
+ * its own listener — it is an {@link InteractionDispatcher} driven by the shared
+ * {@link import("../../discord/interaction/interaction-router").InteractionRouter},
+ * so commands and components share a single `interactionCreate` listener.
+ */
+class ComponentRouter {
+    deps;
+    handlers = [];
+    runtime;
+    constructor(deps) {
+        this.deps = deps;
+        this.runtime = {
+            presenter: deps.presenter,
+            logger: deps.logger,
+            translator: deps.translator,
+        };
+    }
+    register(handler) {
+        this.handlers.push(handler);
+        return this;
+    }
+    registerAll(handlers) {
+        for (const handler of handlers) {
+            this.register(handler);
+        }
+        return this;
+    }
+    match(customId) {
+        return this.handlers.find((handler) => customId === handler.customId || customId.startsWith(`${handler.customId}:`));
+    }
+    /** Claim and route component/modal interactions by `customId`; ignore the rest. */
+    async handle(interaction) {
+        if (!isRoutable(interaction)) {
+            return false;
+        }
+        const handler = this.match(interaction.customId);
+        if (!handler) {
+            return false;
+        }
+        // Before the handler runs, so a declared permission cannot be bypassed by a
+        // handler that forgot to check it.
+        if (!(await this.passesAuthorization(interaction, handler))) {
+            return true;
+        }
+        try {
+            await handler.handle(interaction, this.runtime);
+        }
+        catch (error) {
+            this.deps.logger.error({
+                customId: interaction.customId,
+                err: error instanceof Error ? error.message : String(error),
+            }, "Component handler failed");
+        }
+        return true;
+    }
+    /**
+     * Enforce the handler's declared audience. Only `permissions` is enforceable
+     * here — the other two kinds are statements about a decision made elsewhere,
+     * and their value is that the handler had to state one.
+     *
+     * `memberPermissions` is `null` outside a guild; that is a denial, since an
+     * unknown permission set must never be read as a granted one — the same rule
+     * `createPermissionGuard` follows for commands.
+     */
+    async passesAuthorization(interaction, handler) {
+        if (handler.authorize.kind !== "permissions") {
+            return true;
+        }
+        const missing = (0, permissions_1.missingPermissions)(interaction.memberPermissions, handler.authorize.required);
+        if (missing.length === 0) {
+            return true;
+        }
+        const locale = this.localeOf(interaction);
+        const message = this.deps.translator.translate(locale, i18n_1.CORE_MESSAGES.guardPermissionDenied, {
+            missing: (0, permissions_1.formatPermissions)(missing),
+        });
+        await interaction.reply({
+            embeds: [this.deps.presenter.denial(message, locale)],
+            flags: discord_js_1.MessageFlags.Ephemeral,
+        });
+        return false;
+    }
+    localeOf(interaction) {
+        return (0, i18n_2.resolveLocale)([interaction.locale, interaction.guildLocale], this.deps.translator.defaultLocale);
+    }
+}
+exports.ComponentRouter = ComponentRouter;
+//# sourceMappingURL=component-router.js.map

package/dist/discord/components/component-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-router.js","sourceRoot":"","sources":["../../../src/discord/components/component-router.ts"],"names":[],"mappings":"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"}

package/dist/discord/components/interactive-message/index.d.ts

@@ -0,0 +1,3 @@
+export { COLLECTOR_IDLE_MS, createStateStore, type DisabledInteractiveMessageComponents, type InteractiveMessageCollectorDeps, type InteractiveMessageHandle, type InteractiveMessagePayload, type InteractiveSelect, type InteractiveView, mountInteractiveMessageCollector, type SelectComponentContext, type StateStore, toMessageEditOptions, } from "../../../discord/components/interactive-message/interactive-message-collector";
+export { type InteractiveMessageOptions, mountInteractiveMessage, } from "../../../discord/components/interactive-message/mount-interactive-message";
+//# sourceMappingURL=index.d.ts.map

package/dist/discord/components/interactive-message/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/discord/components/interactive-message/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,oCAAoC,EACzC,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,gCAAgC,EAChC,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,oBAAoB,GACpB,MAAM,wEAAwE,CAAC;AAChF,OAAO,EACN,KAAK,yBAAyB,EAC9B,uBAAuB,GACvB,MAAM,oEAAoE,CAAC"}

package/dist/discord/components/interactive-message/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountInteractiveMessage = exports.toMessageEditOptions = exports.mountInteractiveMessageCollector = exports.createStateStore = exports.COLLECTOR_IDLE_MS = void 0;
+var interactive_message_collector_1 = require("../../../discord/components/interactive-message/interactive-message-collector");
+Object.defineProperty(exports, "COLLECTOR_IDLE_MS", { enumerable: true, get: function () { return interactive_message_collector_1.COLLECTOR_IDLE_MS; } });
+Object.defineProperty(exports, "createStateStore", { enumerable: true, get: function () { return interactive_message_collector_1.createStateStore; } });
+Object.defineProperty(exports, "mountInteractiveMessageCollector", { enumerable: true, get: function () { return interactive_message_collector_1.mountInteractiveMessageCollector; } });
+Object.defineProperty(exports, "toMessageEditOptions", { enumerable: true, get: function () { return interactive_message_collector_1.toMessageEditOptions; } });
+var mount_interactive_message_1 = require("../../../discord/components/interactive-message/mount-interactive-message");
+Object.defineProperty(exports, "mountInteractiveMessage", { enumerable: true, get: function () { return mount_interactive_message_1.mountInteractiveMessage; } });
+//# sourceMappingURL=index.js.map

package/dist/discord/components/interactive-message/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/discord/components/interactive-message/index.ts"],"names":[],"mappings":";;;AAAA,wHAagF;AAZ/E,kIAAA,iBAAiB,OAAA;AACjB,iIAAA,gBAAgB,OAAA;AAOhB,iJAAA,gCAAgC,OAAA;AAGhC,qIAAA,oBAAoB,OAAA;AAErB,gHAG4E;AAD3E,oIAAA,uBAAuB,OAAA"}