@azurioh/discord-kernel 0.1.0

package/src/discord/api-errors.ts

@@ -0,0 +1,91 @@
+import { DiscordAPIError, RESTJSONErrorCodes } from "discord.js";
+
+/**
+ * Discord answers a rate limit with an HTTP status, not a JSON error code, so
+ * this one cannot come from {@link RESTJSONErrorCodes}.
+ */
+const TOO_MANY_REQUESTS_STATUS = 429;
+
+/**
+ * Codes meaning "the entity you asked about no longer exists". They are benign:
+ * a channel was deleted, a member left, a message was removed, an interaction
+ * token expired. The right reaction is to clean up local state, never to alert.
+ */
+const UNKNOWN_RESOURCE_CODES: ReadonlySet<number> = new Set([
+	RESTJSONErrorCodes.UnknownAccount,
+	RESTJSONErrorCodes.UnknownApplication,
+	RESTJSONErrorCodes.UnknownChannel,
+	RESTJSONErrorCodes.UnknownGuild,
+	RESTJSONErrorCodes.UnknownIntegration,
+	RESTJSONErrorCodes.UnknownInvite,
+	RESTJSONErrorCodes.UnknownMember,
+	RESTJSONErrorCodes.UnknownMessage,
+	RESTJSONErrorCodes.UnknownPermissionOverwrite,
+	RESTJSONErrorCodes.UnknownRole,
+	RESTJSONErrorCodes.UnknownToken,
+	RESTJSONErrorCodes.UnknownUser,
+	RESTJSONErrorCodes.UnknownEmoji,
+	RESTJSONErrorCodes.UnknownWebhook,
+	RESTJSONErrorCodes.UnknownBan,
+	RESTJSONErrorCodes.UnknownGuildTemplate,
+	RESTJSONErrorCodes.UnknownSticker,
+	RESTJSONErrorCodes.UnknownInteraction,
+	RESTJSONErrorCodes.UnknownApplicationCommand,
+	RESTJSONErrorCodes.UnknownVoiceState,
+	RESTJSONErrorCodes.UnknownStageInstance,
+]);
+
+/** Codes meaning the bot is simply not allowed to do this — actionable by an admin. */
+const MISSING_ACCESS_CODES: ReadonlySet<number> = new Set([
+	RESTJSONErrorCodes.MissingAccess,
+	RESTJSONErrorCodes.MissingPermissions,
+]);
+
+/** Codes Discord uses for a per-resource throttle, alongside the HTTP 429 status. */
+const RATE_LIMIT_CODES: ReadonlySet<number> = new Set([
+	RESTJSONErrorCodes.ChannelSendRateLimit,
+	RESTJSONErrorCodes.ServerSendRateLimit,
+	RESTJSONErrorCodes.ServiceResourceIsBeingRateLimited,
+]);
+
+/**
+ * Narrow an unknown rejection to a Discord REST error. Adapters catch `unknown`,
+ * so every predicate below starts here rather than trusting a `code` property
+ * that any object could carry.
+ */
+export function isDiscordAPIError(error: unknown): error is DiscordAPIError {
+	return error instanceof DiscordAPIError;
+}
+
+/**
+ * The targeted guild/channel/member/message/interaction is gone. Treat as a
+ * benign outcome: drop the stale reference instead of logging an incident.
+ */
+export function isUnknownResource(error: unknown): boolean {
+	if (!isDiscordAPIError(error)) {
+		return false;
+	}
+	return typeof error.code === "number" && UNKNOWN_RESOURCE_CODES.has(error.code);
+}
+
+/**
+ * The bot lacks a permission or access to the resource. Actionable by a server
+ * admin, so it deserves a clear message rather than a generic incident.
+ */
+export function isMissingAccess(error: unknown): boolean {
+	if (!isDiscordAPIError(error)) {
+		return false;
+	}
+	return typeof error.code === "number" && MISSING_ACCESS_CODES.has(error.code);
+}
+
+/** Discord is throttling us: back off and retry rather than surface a failure. */
+export function isRateLimited(error: unknown): boolean {
+	if (!isDiscordAPIError(error)) {
+		return false;
+	}
+	if (error.status === TOO_MANY_REQUESTS_STATUS) {
+		return true;
+	}
+	return typeof error.code === "number" && RATE_LIMIT_CODES.has(error.code);
+}

package/src/discord/channel-exporter.ts

@@ -0,0 +1,48 @@
+/**
+ * Port for handing a channel to whatever export/archive pipeline is wired up at
+ * the composition root, before the channel is otherwise disposed of.
+ *
+ * This is the seam that lets one feature use another's capability without
+ * importing it: a module that closes channels can ask for the content to be
+ * archived first, while knowing nothing about who archives it — or whether
+ * anyone does. The composition root decides what implements this, exactly as it
+ * does for `Logger` and `DatabaseConnection`.
+ */
+export interface ChannelExportOptions {
+	/** A caller-chosen base name (no extension) for the produced archive file. */
+	readonly fileName?: string;
+}
+
+/**
+ * Where one export actually ended up.
+ *
+ * Reported rather than assumed, because a caller usually has to tell the person
+ * who triggered the export where to find the result — and because an
+ * implementation may have a preferred destination it could not reach. The two
+ * destinations are deliberately coarse: `discord`, meaning the archive was
+ * posted as a message attachment, and `cloud`, meaning it was uploaded
+ * somewhere and only a link came back.
+ */
+export interface ChannelExportOutcome {
+	readonly destinationUsed: "discord" | "cloud";
+	/** True when cloud delivery was configured, failed, and Discord took over. */
+	readonly fellBackFromCloud: boolean;
+	readonly cloudUrl?: string;
+}
+
+export interface ChannelExporter {
+	/**
+	 * Export `channelId`'s content and deliver the result.
+	 *
+	 * `deliverToChannelId` is where a Discord-delivered archive is posted — also
+	 * the fallback when cloud delivery is configured but fails. `guildId` is what
+	 * an implementation resolves that guild's destination preference from, so the
+	 * caller does not have to know one exists.
+	 */
+	exportChannel(
+		channelId: string,
+		deliverToChannelId: string,
+		guildId: string,
+		options?: ChannelExportOptions,
+	): Promise<ChannelExportOutcome>;
+}

package/src/discord/command/autocomplete-dispatcher.ts

@@ -0,0 +1,54 @@
+import type { Interaction } from "discord.js";
+import type { SlashCommand } from "@/discord/command/types";
+import type { InteractionDispatcher } from "@/discord/interaction/interaction-router";
+import type { Logger } from "@/logger";
+
+/**
+ * The slice of the command registry this dispatcher needs. Depending on a
+ * one-method port rather than on `CommandRouter` keeps the two dispatchers
+ * decoupled while sharing a single registration — the alternative, a second map
+ * of commands, would drift the moment a command is registered in only one.
+ */
+export interface CommandLookup {
+	get(name: string): SlashCommand | undefined;
+}
+
+/**
+ * Answers option autocomplete requests. It is an {@link InteractionDispatcher}
+ * aggregated by the shared {@link InteractionRouter}, never a second
+ * `client.on("interactionCreate")` — the whole app keeps exactly one listener.
+ */
+export class AutocompleteDispatcher implements InteractionDispatcher {
+	constructor(
+		private readonly commands: CommandLookup,
+		private readonly logger: Logger,
+	) {}
+
+	/** Claim autocomplete interactions; ignore everything else. */
+	async handle(interaction: Interaction): Promise<boolean> {
+		if (!interaction.isAutocomplete()) {
+			return false;
+		}
+
+		const command = this.commands.get(interaction.commandName);
+		if (!command?.autocomplete) {
+			return false;
+		}
+
+		// A failing suggestion must never surface to the user: Discord shows no
+		// error for autocomplete, it just leaves the box spinning until it times
+		// out. Swallow, log, and let the command reply with an empty list.
+		try {
+			await command.autocomplete(interaction);
+		} catch (error) {
+			this.logger.error(
+				{
+					command: interaction.commandName,
+					err: error instanceof Error ? error.message : String(error),
+				},
+				"Autocomplete handler failed",
+			);
+		}
+		return true;
+	}
+}

package/src/discord/command/autocomplete.ts

@@ -0,0 +1,76 @@
+import type { AutocompleteInteraction } from "discord.js";
+import { type CompiledSubcommand, routeKey } from "@/discord/command/create-command";
+import type { Choice, Options } from "@/discord/command/options";
+
+/**
+ * Serving option autocomplete. Kept beside the DSL because resolving *which*
+ * option is focused needs the same route table `createCommand` builds — the
+ * dispatcher only decides that an interaction is an autocomplete request.
+ */
+
+/** Discord refuses more than this many suggestions in one response. */
+const MAX_CHOICES = 25;
+
+/**
+ * Answer a focused option's autocomplete request.
+ *
+ * Nothing here is allowed to throw: Discord surfaces no error for a failed
+ * autocomplete, it just leaves the input spinning until it times out, so an
+ * empty list is the only sane failure mode. The caller logs; the user keeps
+ * typing.
+ */
+export async function respondWithSuggestions(
+	interaction: AutocompleteInteraction,
+	options: Options,
+): Promise<void> {
+	const focused = interaction.options.getFocused(true);
+	const option = options[focused.name];
+	const resolver = option?.autocomplete;
+
+	if (!resolver) {
+		await interaction.respond([]);
+		return;
+	}
+
+	// The resolver is the only part that can fail (it usually hits a database).
+	// Answering an empty list keeps the picker responsive; rethrowing after the
+	// response lets the dispatcher log the cause without leaving the user hanging.
+	let choices: readonly Choice[];
+	try {
+		choices = await resolver(interaction);
+	} catch (error) {
+		await interaction.respond([]);
+		throw error;
+	}
+
+	await interaction.respond(truncate(choices));
+}
+
+/**
+ * Discord rejects the whole response when it carries more than 25 choices, so a
+ * resolver returning more is trimmed rather than failing outright — a partial
+ * list is still useful to the user typing.
+ */
+function truncate(choices: readonly Choice[]): Choice[] {
+	return choices.slice(0, MAX_CHOICES);
+}
+
+/**
+ * The options a given autocomplete interaction applies to: the focused option
+ * belongs to the invoked subcommand, not to the command as a whole.
+ */
+export function resolveRouteOptions(
+	interaction: AutocompleteInteraction,
+	routes: Map<string, CompiledSubcommand>,
+	flatOptions: Options | null,
+): Options {
+	if (flatOptions) {
+		return flatOptions;
+	}
+	const group = interaction.options.getSubcommandGroup(false);
+	const name = interaction.options.getSubcommand(false);
+	if (name === null) {
+		return {};
+	}
+	return routes.get(routeKey(group, name))?.options ?? {};
+}

package/src/discord/command/context.ts

@@ -0,0 +1,85 @@
+import { type ChatInputCommandInteraction, type EmbedBuilder, MessageFlags } from "discord.js";
+import type { Options, Values } from "@/discord/command/options";
+import type { Presenter } from "@/discord/presenter";
+import { type Locale, resolveLocale, type TranslationParams, type Translator } from "@/i18n";
+import type { Logger } from "@/logger";
+
+/**
+ * The handler-facing surface of a dispatched subcommand: the raw interaction,
+ * the parsed & typed options, the locale resolved for this interaction, a
+ * translate helper bound to it, and convenience responders that route through
+ * the injected {@link Presenter}.
+ */
+export interface Context<O extends Options> {
+	readonly interaction: ChatInputCommandInteraction;
+	readonly options: Values<O>;
+	/** Reply language: user's client locale → guild locale → configured default. */
+	readonly locale: Locale;
+	/** Translate a catalog key for this interaction's locale. */
+	t(key: string, params?: TranslationParams): string;
+	reply(embed: EmbedBuilder): Promise<void>;
+	confirm(message: string): Promise<void>;
+	error(message: string): Promise<void>;
+	deny(message: string): Promise<void>;
+}
+
+/**
+ * Deliver an embed regardless of the interaction's lifecycle state, and never
+ * throw: a failed delivery (e.g. an expired/unknown interaction, code 10062)
+ * must not escape a handler and reach the client's unhandled `error` event,
+ * which would crash the process. Visibility on a deferred interaction is fixed
+ * at deferReply time, so editReply carries no flags.
+ */
+export async function sendEmbed(
+	interaction: ChatInputCommandInteraction,
+	embed: EmbedBuilder,
+	ephemeral: boolean,
+	logger: Logger,
+): Promise<void> {
+	const flags = ephemeral ? MessageFlags.Ephemeral : undefined;
+	try {
+		if (interaction.deferred) {
+			await interaction.editReply({ embeds: [embed] });
+			return;
+		}
+		if (interaction.replied) {
+			await interaction.followUp({ embeds: [embed], flags });
+			return;
+		}
+		await interaction.reply({ embeds: [embed], flags });
+	} catch (error) {
+		logger.error(
+			{
+				commandName: interaction.commandName,
+				interactionId: interaction.id,
+				err: error instanceof Error ? error.message : String(error),
+			},
+			"Failed to deliver interaction response",
+		);
+	}
+}
+
+export function createContext<O extends Options>(
+	interaction: ChatInputCommandInteraction,
+	options: Values<O>,
+	ephemeral: boolean,
+	presenter: Presenter,
+	logger: Logger,
+	translator: Translator,
+): Context<O> {
+	const locale = resolveLocale(
+		[interaction.locale, interaction.guildLocale],
+		translator.defaultLocale,
+	);
+	return {
+		interaction,
+		options,
+		locale,
+		t: (key, params) => translator.translate(locale, key, params),
+		reply: (embed) => sendEmbed(interaction, embed, ephemeral, logger),
+		confirm: (message) =>
+			sendEmbed(interaction, presenter.confirmation(message, locale), ephemeral, logger),
+		error: (message) => sendEmbed(interaction, presenter.error(message, locale), ephemeral, logger),
+		deny: (message) => sendEmbed(interaction, presenter.denial(message, locale), ephemeral, logger),
+	};
+}

package/src/discord/command/cooldown-guard.ts

@@ -0,0 +1,81 @@
+import type { CommandInteraction } from "discord.js";
+import { type Clock, systemClock } from "@/clock";
+import type { Guard, GuardResult } from "@/discord/command/guard";
+import { CORE_MESSAGES } from "@/discord/i18n";
+import type { LocalizedText } from "@/i18n";
+
+const ALLOW: GuardResult = { ok: true };
+const MILLISECONDS_PER_SECOND = 1000;
+
+/** How a cooldown window is shared between callers. */
+export type CooldownScope = "user" | "guild" | "global";
+
+export interface CooldownOptions {
+	/** Minimum delay between two accepted invocations, in milliseconds. */
+	windowMs: number;
+	/** Who shares the window. Defaults to `user`. */
+	scope?: CooldownScope;
+	/** Denial message; receives the whole seconds left before the next attempt. */
+	message?: (secondsLeft: number) => LocalizedText;
+	/** Injected for tests; defaults to the system clock. */
+	clock?: Clock;
+}
+
+function defaultMessage(secondsLeft: number): LocalizedText {
+	return { key: CORE_MESSAGES.cooldownWait, params: { seconds: secondsLeft } };
+}
+
+/**
+ * The key sharing one cooldown window. `global` is a constant so every caller
+ * collides on purpose; `guild` falls back to the user outside a guild, so a DM
+ * can never bypass a guild-scoped cooldown by having no guild id.
+ */
+function cooldownKey(interaction: CommandInteraction, scope: CooldownScope): string {
+	switch (scope) {
+		case "global":
+			return `${interaction.commandName}:global`;
+		case "guild":
+			return `${interaction.commandName}:guild:${interaction.guildId ?? interaction.user.id}`;
+		case "user":
+			return `${interaction.commandName}:user:${interaction.user.id}`;
+	}
+}
+
+/**
+ * Rate-limit a command per user, per guild or globally.
+ *
+ * Expired entries are pruned on access rather than by a timer: the map is only
+ * read when the command runs, so a background interval would keep the process
+ * awake for no benefit. Each guard instance owns its map, so two commands never
+ * share a window unless they share the guard.
+ */
+export function createCooldownGuard(options: CooldownOptions): Guard {
+	const { windowMs, scope = "user", message = defaultMessage, clock = systemClock } = options;
+	const lastUsed = new Map<string, number>();
+
+	return {
+		check(interaction: CommandInteraction): GuardResult {
+			const now = clock.now().getTime();
+			const key = cooldownKey(interaction, scope);
+			const previous = lastUsed.get(key);
+
+			if (previous !== undefined && now - previous < windowMs) {
+				const secondsLeft = Math.ceil((windowMs - (now - previous)) / MILLISECONDS_PER_SECOND);
+				return { ok: false, message: message(secondsLeft) };
+			}
+
+			lastUsed.set(key, now);
+			pruneExpired(lastUsed, now, windowMs);
+			return ALLOW;
+		},
+	};
+}
+
+/** Drop entries whose window has elapsed, so the map cannot grow without bound. */
+function pruneExpired(lastUsed: Map<string, number>, now: number, windowMs: number): void {
+	for (const [key, timestamp] of lastUsed) {
+		if (now - timestamp >= windowMs) {
+			lastUsed.delete(key);
+		}
+	}
+}