@azurioh/discord-kernel 0.1.0

package/src/discord/events/event-router.ts

@@ -0,0 +1,53 @@
+import type { Client } from "discord.js";
+import type { DiscordEvent, EventListener } from "@/discord/events/types";
+import type { Logger } from "@/logger";
+
+/**
+ * Wrap a handler so a thrown error is logged instead of escaping to the
+ * process-level `error` event: a failing handler must never take the bot down.
+ */
+function createEventListener(event: DiscordEvent, logger: Logger): EventListener {
+	return async (...args) => {
+		try {
+			await event.execute(...args);
+		} catch (error) {
+			logger.error(
+				{ event: event.name, err: error instanceof Error ? error.message : String(error) },
+				"Event handler failed",
+			);
+		}
+	};
+}
+
+/**
+ * Binds registered {@link DiscordEvent}s to a client. This is the only place in
+ * the app that calls `client.on`/`client.once`.
+ */
+export class EventRouter {
+	private readonly events: DiscordEvent[] = [];
+
+	constructor(private readonly logger: Logger) {}
+
+	register(event: DiscordEvent): this {
+		this.events.push(event);
+		return this;
+	}
+
+	registerAll(events: Iterable<DiscordEvent>): this {
+		for (const event of events) {
+			this.register(event);
+		}
+		return this;
+	}
+
+	bind(client: Client): void {
+		for (const event of this.events) {
+			const listener = createEventListener(event, this.logger);
+			if (event.once) {
+				client.once(event.name, listener);
+			} else {
+				client.on(event.name, listener);
+			}
+		}
+	}
+}

package/src/discord/events/types.ts

@@ -0,0 +1,17 @@
+import type { ClientEvents } from "discord.js";
+
+/**
+ * A typed Discord gateway event handler. `name` is keyed to discord.js'
+ * {@link ClientEvents}, so `args` are inferred per event with no `any`.
+ */
+export interface DiscordEvent<K extends keyof ClientEvents = keyof ClientEvents> {
+	readonly name: K;
+	readonly once?: boolean;
+	execute(...args: ClientEvents[K]): Promise<void> | void;
+}
+
+/**
+ * The listener actually handed to discord.js. It is type-erased over every event
+ * name because the router holds heterogeneous events in a single collection.
+ */
+export type EventListener = (...args: ClientEvents[keyof ClientEvents]) => Promise<void>;

package/src/discord/i18n.ts

@@ -0,0 +1,173 @@
+import type { Catalog } from "@/i18n";
+
+/** Catalog keys for the framework's own feedback, under the `core.` namespace. */
+export const CORE_MESSAGES = {
+	presenterSuccessTitle: "core.presenter.success-title",
+	presenterWarningTitle: "core.presenter.warning-title",
+	presenterErrorTitle: "core.presenter.error-title",
+	presenterDenialTitle: "core.presenter.denial-title",
+	presenterIncidentFooter: "core.presenter.incident-footer",
+	unknownSubcommand: "core.command.unknown-subcommand",
+	genericError: "core.command.generic-error",
+	cooldownWait: "core.cooldown.wait",
+	guardPermissionDenied: "core.guard.permission-denied",
+	guardRoleDenied: "core.guard.role-denied",
+	guardGuildOnly: "core.guard.guild-only",
+} as const;
+
+/**
+ * Catalog keys for the settings editor's own chrome — the wording that is the
+ * same whatever is being edited.
+ *
+ * Deliberately *not* the wording of the settings themselves: a field's label and
+ * its one-line hint name something only the calling module knows about, so those
+ * stay in that module's catalog and reach the editor as keys.
+ */
+export const SETTINGS_EDITOR_MESSAGES = {
+	modalTitle: "core.settings-editor.modal-title",
+	modalHelper: "core.settings-editor.modal-helper",
+	modalUploadLabel: "core.settings-editor.modal-upload-label",
+	modalUploadHelper: "core.settings-editor.modal-upload-helper",
+	modalImageUrlLabel: "core.settings-editor.modal-image-url-label",
+	modalImageHelper: "core.settings-editor.modal-image-helper",
+	modalImageHelperUploaded: "core.settings-editor.modal-image-helper-uploaded",
+	fieldSaved: "core.settings-editor.field-saved",
+	fieldCleared: "core.settings-editor.field-cleared",
+	fieldUploaded: "core.settings-editor.field-uploaded",
+	resetButton: "core.settings-editor.reset-button",
+	resetConfirmTitle: "core.settings-editor.reset-confirm-title",
+	resetConfirmDescription: "core.settings-editor.reset-confirm-description",
+	resetConfirmButton: "core.settings-editor.reset-confirm-button",
+	resetCancelButton: "core.settings-editor.reset-cancel-button",
+	resetDone: "core.settings-editor.reset-done",
+	resetCancelled: "core.settings-editor.reset-cancelled",
+	backButton: "core.settings-editor.back-button",
+	/**
+	 * A card screen's per-entry button: what selecting the entry from the old
+	 * field menu used to do, now spelled on the button that replaces it. One
+	 * wording for a field that opens a modal, another for one that descends a
+	 * level — both generic enough that no card screen has ever needed its own.
+	 */
+	editFieldButton: "core.settings-editor.edit-field-button",
+	openLevelButton: "core.settings-editor.open-level-button",
+} as const;
+
+/**
+ * The framework's own strings: presenter titles, the incident footer, dispatch
+ * fallbacks and the default cooldown notice. Registered by the composition root
+ * before any module catalog.
+ */
+export const CORE_CATALOG: Catalog = {
+	[CORE_MESSAGES.presenterSuccessTitle]: { en: "Success", fr: "Succès" },
+	[CORE_MESSAGES.presenterWarningTitle]: { en: "Warning", fr: "Avertissement" },
+	[CORE_MESSAGES.presenterErrorTitle]: { en: "Error", fr: "Erreur" },
+	[CORE_MESSAGES.presenterDenialTitle]: { en: "Access denied", fr: "Accès refusé" },
+	[CORE_MESSAGES.presenterIncidentFooter]: {
+		en: "Ref: {reference} · contact an admin if this persists",
+		fr: "Réf : {reference} · contactez un admin si le problème persiste",
+	},
+	[CORE_MESSAGES.unknownSubcommand]: {
+		en: "Unknown subcommand.",
+		fr: "Sous-commande inconnue.",
+	},
+	[CORE_MESSAGES.genericError]: {
+		en: "Something went wrong.",
+		fr: "Une erreur est survenue.",
+	},
+	[CORE_MESSAGES.cooldownWait]: {
+		en: "Slow down — try again in {seconds}s.",
+		fr: "Doucement — réessayez dans {seconds}s.",
+	},
+	[CORE_MESSAGES.guardPermissionDenied]: {
+		en: "You do not have permission to use this command. Missing: {missing}.",
+		fr: "Vous n'avez pas la permission d'utiliser cette commande. Manquant : {missing}.",
+	},
+	[CORE_MESSAGES.guardRoleDenied]: {
+		en: "You do not have the role required to use this command.",
+		fr: "Vous n'avez pas le rôle requis pour utiliser cette commande.",
+	},
+	[CORE_MESSAGES.guardGuildOnly]: {
+		en: "This command can only be used in a server.",
+		fr: "Cette commande ne peut être utilisée que sur un serveur.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalTitle]: {
+		en: "Edit: {field}",
+		fr: "Modifier : {field}",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalHelper]: {
+		en: "Leave empty to clear your customisation and go back to the default.",
+		fr: "Laisse vide pour effacer ta personnalisation et revenir à la valeur par défaut.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalUploadLabel]: {
+		en: "Upload an image",
+		fr: "Envoyer une image",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalUploadHelper]: {
+		en: "PNG, JPEG, GIF or WebP, up to {max} MiB. An upload wins over the address below.",
+		fr: "PNG, JPEG, GIF ou WebP, jusqu'à {max} Mio. Un envoi l'emporte sur l'adresse ci-dessous.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalImageUrlLabel]: {
+		en: "…or an image address",
+		fr: "…ou une adresse d'image",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalImageHelper]: {
+		en: "An http(s) address. Leave both empty to restore the default.",
+		fr: "Une adresse http(s). Laisse les deux vides pour revenir au défaut.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.modalImageHelperUploaded]: {
+		en: "An image is uploaded; it cannot be shown here. Empty both to restore the default.",
+		fr: "Une image est envoyée ; impossible de la réafficher. Vide les deux pour le défaut.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.fieldSaved]: {
+		en: "✅ {field} updated.",
+		fr: "✅ {field} mis à jour.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.fieldCleared]: {
+		en: "✅ {field} cleared — the default is used again.",
+		fr: "✅ {field} effacé — la valeur par défaut est de nouveau utilisée.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.fieldUploaded]: {
+		en: "✅ {field} updated with your upload.",
+		fr: "✅ {field} mis à jour avec ton envoi.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetButton]: {
+		en: "Reset everything",
+		fr: "Tout réinitialiser",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetConfirmTitle]: {
+		en: "Reset every field?",
+		fr: "Réinitialiser tous les champs ?",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetConfirmDescription]: {
+		en: "Every field goes back to its default. An uploaded image is not merely unset — its file is deleted for good and cannot be recovered. The preview below is what you are about to lose.",
+		fr: "Chaque champ revient à sa valeur par défaut. Une image envoyée n'est pas simplement retirée : le fichier est supprimé définitivement et ne pourra pas être récupéré. L'aperçu ci-dessous est ce que tu es sur le point de perdre.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetConfirmButton]: {
+		en: "Reset for good",
+		fr: "Réinitialiser définitivement",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetCancelButton]: {
+		en: "Cancel",
+		fr: "Annuler",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetDone]: {
+		en: "✅ Every field is back to its default.",
+		fr: "✅ Tous les champs sont revenus à leur valeur par défaut.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.resetCancelled]: {
+		en: "Nothing was reset. Your customisation is untouched.",
+		fr: "Rien n'a été réinitialisé. Ta personnalisation est intacte.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.backButton]: {
+		en: "Back",
+		fr: "Retour",
+	},
+	[SETTINGS_EDITOR_MESSAGES.editFieldButton]: {
+		en: "Edit",
+		fr: "Modifier",
+	},
+	[SETTINGS_EDITOR_MESSAGES.openLevelButton]: {
+		en: "Open",
+		fr: "Ouvrir",
+	},
+};

package/src/discord/interaction/button.ts

@@ -0,0 +1,75 @@
+import { ActionRowBuilder, ButtonBuilder, type ButtonInteraction, ButtonStyle } from "discord.js";
+
+export type ButtonStyleName = "primary" | "secondary" | "success" | "danger";
+
+const BUTTON_STYLES: Record<ButtonStyleName, ButtonStyle> = {
+	primary: ButtonStyle.Primary,
+	secondary: ButtonStyle.Secondary,
+	success: ButtonStyle.Success,
+	danger: ButtonStyle.Danger,
+};
+
+/**
+ * Interaction context handed to a button's `onClick`, mirroring the command
+ * {@link import("@/discord/command/context").Context}: it exposes the
+ * triggering interaction, the current state, and an `update` that re-renders the
+ * message with the next state.
+ */
+export interface ComponentContext<S> {
+	readonly interaction: ButtonInteraction;
+	readonly state: S;
+	update(next: S): Promise<void>;
+}
+
+export interface ButtonDef<S> {
+	id: string;
+	label?: string;
+	emoji?: string;
+	style?: ButtonStyleName;
+	disabled?: (state: S) => boolean;
+	onClick?: (ctx: ComponentContext<S>) => Promise<void> | void;
+}
+
+/**
+ * Type-erased compiled button: knows how to render itself for a given state
+ * (`apply`) and how to react to a click (`onClick`) — the component analogue of
+ * a compiled subcommand. A button is *behaviour*, not a passive widget, which is
+ * why it lives in the interaction layer rather than a UI/embed module.
+ */
+export interface Button<S> {
+	readonly id: string;
+	readonly onClick?: (ctx: ComponentContext<S>) => Promise<void> | void;
+	apply(state: S, forceDisabled?: boolean): ButtonBuilder;
+}
+
+/** Declare a button: a definition bundling construction (`apply`) and behaviour (`onClick`). */
+export function createButton<S>(def: ButtonDef<S>): Button<S> {
+	const style = BUTTON_STYLES[def.style ?? "secondary"];
+	return {
+		id: def.id,
+		onClick: def.onClick,
+		apply(state, forceDisabled = false) {
+			const builder = new ButtonBuilder().setCustomId(def.id).setStyle(style);
+			if (def.label !== undefined) {
+				builder.setLabel(def.label);
+			}
+			if (def.emoji !== undefined) {
+				builder.setEmoji(def.emoji);
+			}
+			builder.setDisabled(forceDisabled || (def.disabled?.(state) ?? false));
+			return builder;
+		},
+	};
+}
+
+/** Group buttons into a single action row, applying each against the current state. */
+export function createActionRow<S>(
+	buttons: Button<S>[],
+	state: S,
+	options: { disableAll?: boolean } = {},
+): ActionRowBuilder<ButtonBuilder> {
+	const disableAll = options.disableAll ?? false;
+	return new ActionRowBuilder<ButtonBuilder>().addComponents(
+		...buttons.map((entry) => entry.apply(state, disableAll)),
+	);
+}

package/src/discord/interaction/interaction-router.ts

@@ -0,0 +1,28 @@
+import type { Interaction } from "discord.js";
+
+/**
+ * Anything that can consume a gateway interaction. `handle` returns `true` when
+ * it claimed the interaction, `false` to let the next dispatcher try. This is the
+ * seam that lets the whole app share a single `interactionCreate` listener.
+ */
+export interface InteractionDispatcher {
+	handle(interaction: Interaction): Promise<boolean>;
+}
+
+/**
+ * Aggregates {@link InteractionDispatcher}s behind one entry point so the app
+ * registers a *single* `interactionCreate` listener (wired at the composition
+ * root, attached in `bootstrap/lifecycle`). Dispatchers are tried in order and
+ * the first to claim the interaction wins — no global state, no singleton.
+ */
+export class InteractionRouter {
+	constructor(private readonly dispatchers: readonly InteractionDispatcher[]) {}
+
+	async dispatch(interaction: Interaction): Promise<void> {
+		for (const dispatcher of this.dispatchers) {
+			if (await dispatcher.handle(interaction)) {
+				return;
+			}
+		}
+	}
+}