@azurioh/discord-kernel 0.1.0

package/src/errors/business-error.ts

@@ -0,0 +1,49 @@
+export type ErrorSeverity = "warning" | "error";
+
+/**
+ * Optional catalog reference carried by a {@link BusinessError}. When present,
+ * the command pipeline renders the translated text for the interaction's
+ * locale; `message` stays the English source used for logs and as fallback.
+ * Declared structurally (not imported from `core/i18n`'s `LocalizedText`) to
+ * keep this file a pure error declaration; the shapes are checked compatible
+ * where the pipeline resolves it.
+ */
+export interface ErrorTranslation {
+	readonly key: string;
+	readonly params?: Readonly<Record<string, string | number>>;
+}
+
+/**
+ * Base class for expected, user-facing errors. Anything that is NOT a
+ * {@link BusinessError} is treated as unexpected: it is logged with an incident
+ * reference and the user sees a generic message.
+ */
+export abstract class BusinessError extends Error {
+	abstract readonly severity: ErrorSeverity;
+
+	constructor(
+		message: string,
+		readonly translation?: ErrorTranslation,
+	) {
+		super(message);
+	}
+}
+
+/** Benign business error (invalid input, missing resource, conflict). */
+export class WarningError extends BusinessError {
+	override readonly severity = "warning" as const;
+}
+
+/** Serious business error that still carries a user-facing message. */
+export class CriticalError extends BusinessError {
+	override readonly severity = "error" as const;
+}
+
+/** The referenced resource does not exist. */
+export class NotFoundError extends WarningError {}
+
+/** User input failed validation. */
+export class ValidationError extends WarningError {}
+
+/** The action conflicts with the current state (e.g. a duplicate). */
+export class ConflictError extends WarningError {}

package/src/errors/describe-error.ts

@@ -0,0 +1,73 @@
+/**
+ * An error as a log record keeps it: what it says, where it came from, and
+ * whatever it is wrapping.
+ *
+ * `message` alone is not enough for the errors this bot actually hits. A
+ * builder that refuses a payload throws `CombinedPropertyError`, whose own
+ * message is the constant "Received one or more errors" — everything that
+ * names the offending field lives in the errors nested under it. Logging the
+ * message and dropping the rest turns a precise complaint into a sentence that
+ * says nothing.
+ */
+export interface DescribedError {
+	readonly message: string;
+	readonly name?: string;
+	readonly stack?: string;
+	/**
+	 * What this error wraps: the entries of an aggregate, or the `cause` a
+	 * rethrow attached.
+	 */
+	readonly causes?: DescribedError[];
+}
+
+/**
+ * How deep the wrapping is followed. Aggregates nest two or three levels in
+ * practice; the bound is there so a cyclic `cause` cannot spin.
+ */
+const MAX_DEPTH = 5;
+
+/** How many entries of one aggregate are kept, so a wide failure stays readable. */
+const MAX_CAUSES = 10;
+
+/**
+ * The errors nested inside one, whatever shape it wraps them in.
+ *
+ * `AggregateError` and shapeshift's `CombinedError` both expose `errors` as a
+ * plain array; shapeshift's `CombinedPropertyError` uses the same field but
+ * pairs each error with the property it came from, as `[key, error]`. Taking
+ * the last element of an entry reads both, and keeping the key out of the way
+ * costs nothing — the nested message names the constraint that failed.
+ */
+function aggregated(error: object): unknown[] {
+	const { errors } = error as { errors?: unknown };
+	if (!Array.isArray(errors)) {
+		return [];
+	}
+	return errors
+		.slice(0, MAX_CAUSES)
+		.map((entry) => (Array.isArray(entry) ? entry[entry.length - 1] : entry));
+}
+
+/**
+ * Render an unknown thrown value for a structured log.
+ *
+ * Use it wherever an error is caught to be reported rather than handled:
+ * `logger.error({ err: describeError(error) }, "…")`.
+ */
+export function describeError(error: unknown, depth = 0): DescribedError {
+	if (!(error instanceof Error)) {
+		return { message: String(error) };
+	}
+	const causes =
+		depth >= MAX_DEPTH
+			? []
+			: [...aggregated(error), ...(error.cause === undefined ? [] : [error.cause])].map((nested) =>
+					describeError(nested, depth + 1),
+				);
+	return {
+		message: error.message,
+		name: error.name,
+		...(error.stack === undefined ? {} : { stack: error.stack }),
+		...(causes.length === 0 ? {} : { causes }),
+	};
+}

package/src/errors/incident-ref.ts

@@ -0,0 +1,10 @@
+import { randomUUID } from "node:crypto";
+
+/**
+ * Generate a unique incident reference attached to unexpected errors. The same
+ * value is logged server-side and shown to the user, so a support request can be
+ * traced back to a single log line.
+ */
+export function createIncidentRef(): string {
+	return randomUUID();
+}

package/src/errors/index.ts

@@ -0,0 +1,12 @@
+export {
+	BusinessError,
+	ConflictError,
+	CriticalError,
+	type ErrorSeverity,
+	type ErrorTranslation,
+	NotFoundError,
+	ValidationError,
+	WarningError,
+} from "@/errors/business-error";
+export { type DescribedError, describeError } from "@/errors/describe-error";
+export { createIncidentRef } from "@/errors/incident-ref";

package/src/i18n/business-message.ts

@@ -0,0 +1,23 @@
+import type { BusinessError } from "@/errors";
+import type { Locale } from "@/i18n/locale";
+import type { Translator } from "@/i18n/translator";
+
+/**
+ * The user-facing wording of an expected failure: the catalog entry it points
+ * at, or its English source when it carries none.
+ *
+ * Lives beside the translator rather than with any one surface: the command
+ * pipeline, the `ComponentRouter` and every collector-scoped screen owe the same
+ * answer to the same failure, and a screen that has to translate its own
+ * refusals must not reach into another module to do it.
+ */
+export function resolveBusinessMessage(
+	error: BusinessError,
+	translator: Translator,
+	locale: Locale,
+): string {
+	if (error.translation === undefined) {
+		return error.message;
+	}
+	return translator.translate(locale, error.translation.key, error.translation.params);
+}

package/src/i18n/catalog.ts

@@ -0,0 +1,41 @@
+import { DuplicateTranslationKeyError } from "@/i18n/errors";
+
+/**
+ * One translatable message. `en` is mandatory by construction — it is the last
+ * link of every fallback chain, so a missing translation can only ever degrade
+ * to English, never to a broken reply. Templates carry `{name}` placeholders
+ * interpolated by the translator.
+ */
+export interface CatalogEntry {
+	readonly en: string;
+	readonly fr?: string;
+}
+
+/**
+ * A set of keyed message templates. Keys are namespaced `<owner>.<area>.<name>`
+ * (e.g. `core.presenter.success-title`, `comms.event.created`) so two modules
+ * can never collide accidentally.
+ */
+export type Catalog = Readonly<Record<string, CatalogEntry>>;
+
+/**
+ * Accumulates the core catalog and every module's catalog at boot. Registration
+ * is fail-fast: a duplicate key throws {@link DuplicateTranslationKeyError}
+ * instead of silently letting one module's copy shadow another's.
+ */
+export class TranslationRegistry {
+	private readonly entries = new Map<string, CatalogEntry>();
+
+	register(catalog: Catalog): void {
+		for (const [key, entry] of Object.entries(catalog)) {
+			if (this.entries.has(key)) {
+				throw new DuplicateTranslationKeyError(key);
+			}
+			this.entries.set(key, entry);
+		}
+	}
+
+	get(key: string): CatalogEntry | undefined {
+		return this.entries.get(key);
+	}
+}

package/src/i18n/errors.ts

@@ -0,0 +1,11 @@
+/**
+ * Two catalogs declared the same translation key. Raised while modules register
+ * their catalogs at boot — a wiring mistake that must stop the boot, never a
+ * runtime condition.
+ */
+export class DuplicateTranslationKeyError extends Error {
+	constructor(readonly key: string) {
+		super(`Translation key "${key}" is registered twice`);
+		this.name = "DuplicateTranslationKeyError";
+	}
+}

package/src/i18n/index.ts

@@ -0,0 +1,11 @@
+export { resolveBusinessMessage } from "@/i18n/business-message";
+export { type Catalog, type CatalogEntry, TranslationRegistry } from "@/i18n/catalog";
+export { DuplicateTranslationKeyError } from "@/i18n/errors";
+export { type Locale, normalizeLocale, resolveLocale, SUPPORTED_LOCALES } from "@/i18n/locale";
+export {
+	createTranslator,
+	type LocalizedText,
+	type TranslationParams,
+	type Translator,
+	type TranslatorOptions,
+} from "@/i18n/translator";

package/src/i18n/locale.ts

@@ -0,0 +1,41 @@
+/**
+ * The languages the framework can render replies in. `en` is structurally the
+ * fallback source: every catalog entry must provide it (see `catalog.ts`), so
+ * adding a language here can degrade gracefully instead of failing lookups.
+ */
+export const SUPPORTED_LOCALES = ["en", "fr"] as const;
+
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+
+/**
+ * Map a raw Discord locale string (`en-US`, `en-GB`, `fr`, `de`…) to a
+ * supported base language. Regional variants collapse to their base tag, so
+ * both English variants resolve to `en` without duplicating catalog entries.
+ * Returns `undefined` for unsupported languages so callers can keep walking
+ * their fallback chain.
+ */
+export function normalizeLocale(raw: string | null | undefined): Locale | undefined {
+	if (!raw) {
+		return undefined;
+	}
+	const base = raw.split("-")[0]?.toLowerCase();
+	return SUPPORTED_LOCALES.find((locale) => locale === base);
+}
+
+/**
+ * Pick the reply language for one message: the first supported candidate wins,
+ * otherwise the configured default. Callers list candidates in priority order
+ * (user locale, then guild locale).
+ */
+export function resolveLocale(
+	candidates: readonly (string | null | undefined)[],
+	defaultLocale: Locale,
+): Locale {
+	for (const candidate of candidates) {
+		const normalized = normalizeLocale(candidate);
+		if (normalized !== undefined) {
+			return normalized;
+		}
+	}
+	return defaultLocale;
+}

package/src/i18n/translator.ts

@@ -0,0 +1,78 @@
+import type { TranslationRegistry } from "@/i18n/catalog";
+import type { Locale } from "@/i18n/locale";
+import type { Logger } from "@/logger";
+
+/** Values interpolated into a template's `{name}` placeholders. */
+export type TranslationParams = Readonly<Record<string, string | number>>;
+
+/**
+ * A message that may be translated: either a plain string delivered verbatim
+ * (ad-hoc dynamic text, backward-compatible call sites) or a catalog key with
+ * its interpolation parameters. Accepted by guard denials, fallback errors and
+ * business errors, and resolved by the dispatch pipeline with the locale of the
+ * interaction being answered.
+ */
+export type LocalizedText = string | { readonly key: string; readonly params?: TranslationParams };
+
+/** Translates catalog keys for a resolved locale; never throws on lookup. */
+export interface Translator {
+	readonly defaultLocale: Locale;
+	translate(locale: Locale, key: string, params?: TranslationParams): string;
+	/** Resolve a {@link LocalizedText}: plain strings pass through untranslated. */
+	resolve(locale: Locale, text: LocalizedText): string;
+}
+
+export interface TranslatorOptions {
+	readonly defaultLocale: Locale;
+	readonly logger: Logger;
+}
+
+const PLACEHOLDER_PATTERN = /\{(\w+)\}/g;
+
+function interpolate(
+	template: string,
+	params: TranslationParams | undefined,
+	key: string,
+	logger: Logger,
+): string {
+	return template.replace(PLACEHOLDER_PATTERN, (placeholder, name: string) => {
+		const value = params?.[name];
+		if (value === undefined) {
+			// A missing value is a call-site bug, but the reply must still go out:
+			// keep the placeholder visible and leave a trace for the operator.
+			logger.warn({ key, placeholder: name }, "Missing interpolation parameter");
+			return placeholder;
+		}
+		return String(value);
+	});
+}
+
+/**
+ * Build the translator over a filled registry. Lookup order per call:
+ * requested locale → configured default → `en`. A key absent from the registry
+ * renders as the key itself (logged) — a lookup can degrade but never prevent
+ * a reply from being delivered.
+ */
+export function createTranslator(
+	registry: TranslationRegistry,
+	options: TranslatorOptions,
+): Translator {
+	const { defaultLocale, logger } = options;
+
+	const translate = (locale: Locale, key: string, params?: TranslationParams): string => {
+		const entry = registry.get(key);
+		if (entry === undefined) {
+			logger.warn({ key }, "Unknown translation key");
+			return key;
+		}
+		const template = entry[locale] ?? entry[defaultLocale] ?? entry.en;
+		return interpolate(template, params, key, logger);
+	};
+
+	return {
+		defaultLocale,
+		translate,
+		resolve: (locale, text) =>
+			typeof text === "string" ? text : translate(locale, text.key, text.params),
+	};
+}

package/src/logger.ts

@@ -0,0 +1,28 @@
+/**
+ * A single log call. Mirrors the pino calling convention so call sites can pass
+ * either a bare message or a structured record followed by a message:
+ * `logger.error({ err }, "Failed to do the thing")`.
+ */
+export interface LogFn {
+	(record: unknown, message?: string, ...args: unknown[]): void;
+	(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Structured application logger port.
+ *
+ * Declared structurally on purpose: `core` owns the contract and stays free of
+ * any vendor SDK, so the concrete implementation (pino, Sentry, a test double)
+ * lives in `infrastructure/logging` and can be swapped without touching call
+ * sites.
+ */
+export interface Logger {
+	trace: LogFn;
+	debug: LogFn;
+	info: LogFn;
+	warn: LogFn;
+	error: LogFn;
+	fatal: LogFn;
+	/** Derive a logger that stamps `bindings` onto every record it emits. */
+	child(bindings: Record<string, unknown>): Logger;
+}

package/src/module/module.ts

@@ -0,0 +1,42 @@
+import type { ContextMenuCommand, SlashCommand } from "@/discord/command/types";
+import type { ComponentHandler } from "@/discord/components/component-router";
+import type { DiscordEvent } from "@/discord/events/types";
+import type { Catalog } from "@/i18n";
+import type { ScheduledJob } from "@/scheduler/scheduler";
+
+/**
+ * A self-contained vertical feature slice. A module bundles everything it
+ * contributes to the bot — commands, gateway events, scheduled jobs — and an
+ * optional async `setup` for one-off work (creating indexes, migrations…).
+ *
+ * Modules are produced by factories that receive the application container (see
+ * `bootstrap/container.ts`), so all dependencies are injected — never imported
+ * as singletons. The core depends only on this output contract, never on how a
+ * module is wired.
+ */
+export interface BotModule {
+	/** Stable identifier, used in logs. */
+	readonly name: string;
+	readonly commands?: readonly SlashCommand[];
+	/** Right-click entries on a member or a message (the Apps submenu). */
+	readonly contextMenuCommands?: readonly ContextMenuCommand[];
+	/** Persistent component/modal handlers (routed by `customId`). */
+	readonly components?: readonly ComponentHandler[];
+	readonly events?: readonly DiscordEvent[];
+	readonly jobs?: readonly ScheduledJob[];
+	/**
+	 * The module's translation catalog (keys namespaced by module name). The
+	 * composition root registers it into the shared registry at boot — a
+	 * duplicate key across modules fails the boot, never a runtime lookup.
+	 */
+	readonly translations?: Catalog;
+	/** One-off initialisation run once at boot, after the client is ready. */
+	setup?(): Promise<void> | void;
+	/**
+	 * Symmetric counterpart of {@link setup}, awaited during graceful shutdown
+	 * before the client and the database are closed. Release what the module owns
+	 * and the framework cannot see — timers, collectors, third-party connections.
+	 * A rejecting teardown is logged and never aborts the shutdown of the others.
+	 */
+	teardown?(): Promise<void> | void;
+}

package/src/persistence/database.ts

@@ -0,0 +1,23 @@
+/**
+ * Driver-agnostic persistence port. It exists so the framework (boot, graceful
+ * shutdown) can own a database lifecycle without ever naming a vendor: adding a
+ * SQL or Redis driver must not require touching this file, only adding an
+ * adapter that satisfies this contract.
+ *
+ * Deliberately narrow: querying is not part of it. Query APIs differ too much
+ * between engines to be usefully abstracted here, so each adapter exposes its
+ * own (Mongo collections, SQL statements…) and repositories in the module
+ * `infrastructure/` layer are the only code allowed to use it.
+ */
+export interface DatabaseConnection {
+	/**
+	 * Discriminant identifying the concrete driver. Adapters narrow it to a
+	 * string literal so consumers can select an implementation by comparison
+	 * rather than by `instanceof`, which would force a vendor import.
+	 */
+	readonly driver: string;
+	/** Open the connection. Idempotent: safe to call from several call sites. */
+	connect(): Promise<void>;
+	/** Release the connection on graceful shutdown. */
+	close(): Promise<void>;
+}

package/src/resilience/retry.ts

@@ -0,0 +1,102 @@
+import { BusinessError } from "@/errors";
+
+const MIN_ATTEMPTS = 1;
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 200;
+const DEFAULT_MAX_DELAY_MS = 5_000;
+const DEFAULT_BACKOFF_FACTOR = 2;
+/** Share of the computed delay kept fixed; the rest is randomised (full jitter on 1 - RATIO). */
+const DEFAULT_JITTER_RATIO = 0.5;
+
+export interface RetryOptions {
+	/** Total number of tries, first attempt included. */
+	attempts?: number;
+	initialDelayMs?: number;
+	maxDelayMs?: number;
+	backoffFactor?: number;
+	jitterRatio?: number;
+	/** Decide whether a failure is worth another try. Default: anything but a permanent failure. */
+	shouldRetry?: (error: unknown, attempt: number) => boolean;
+	/** Injected so tests advance instantly instead of waiting on real timers. */
+	sleep?: (delayMs: number) => Promise<void>;
+	/** Injected randomness keeps the jitter deterministic under test. */
+	random?: () => number;
+}
+
+/** Everything the backoff needs once caller defaults have been resolved. */
+export interface BackoffOptions {
+	initialDelayMs: number;
+	maxDelayMs: number;
+	backoffFactor: number;
+	jitterRatio: number;
+	random: () => number;
+}
+
+/**
+ * A {@link BusinessError} describes an expected, user-facing failure (bad input,
+ * missing entity, conflict): repeating the call cannot change the outcome, so it
+ * is never retried. Everything else is assumed transient until proven otherwise.
+ */
+function isTransient(error: unknown): boolean {
+	return !(error instanceof BusinessError);
+}
+
+function defaultSleep(delayMs: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+}
+
+/**
+ * Exponential backoff with jitter. The jitter matters more than the curve itself:
+ * without it every caller that failed during the same outage retries in lockstep
+ * and hammers the dependency back down.
+ */
+export function computeBackoffDelay(attempt: number, options: BackoffOptions): number {
+	const exponential = options.initialDelayMs * options.backoffFactor ** (attempt - 1);
+	const capped = Math.min(exponential, options.maxDelayMs);
+	const fixed = capped * options.jitterRatio;
+	return Math.round(fixed + (capped - fixed) * options.random());
+}
+
+/**
+ * Run `task`, retrying transient failures until the attempt budget is spent, then
+ * rethrowing the last error. Vendor-free by design: callers pass their own
+ * `shouldRetry` (e.g. built on the Discord API predicates) so this stays usable
+ * for any I/O.
+ */
+export async function withRetry<T>(task: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+	// `Math.max` propagates NaN, and `attempt <= NaN` is false on the first pass:
+	// an unusable budget would skip the task entirely and reject with `undefined`.
+	// Floor to a valid count so a bad config still runs the task once.
+	const requested = options.attempts ?? DEFAULT_ATTEMPTS;
+	const attempts = Number.isFinite(requested)
+		? Math.max(MIN_ATTEMPTS, Math.floor(requested))
+		: DEFAULT_ATTEMPTS;
+	const shouldRetry = options.shouldRetry ?? isTransient;
+	const sleep = options.sleep ?? defaultSleep;
+	const backoff: BackoffOptions = {
+		initialDelayMs: options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS,
+		maxDelayMs: options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+		backoffFactor: options.backoffFactor ?? DEFAULT_BACKOFF_FACTOR,
+		jitterRatio: options.jitterRatio ?? DEFAULT_JITTER_RATIO,
+		random: options.random ?? Math.random,
+	};
+
+	let lastError: unknown;
+	for (let attempt = MIN_ATTEMPTS; attempt <= attempts; attempt += 1) {
+		try {
+			return await task();
+		} catch (error) {
+			lastError = error;
+			const isLastAttempt = attempt === attempts;
+			if (isLastAttempt || !shouldRetry(error, attempt)) {
+				throw error;
+			}
+			await sleep(computeBackoffDelay(attempt, backoff));
+		}
+	}
+	// Unreachable — the loop always returns or throws — but the compiler cannot
+	// prove the budget is non-empty, and a silent `undefined` would be worse.
+	throw lastError;
+}

package/src/scheduler/errors.ts

@@ -0,0 +1,40 @@
+/**
+ * Failures raised while a job's schedule is resolved. They live apart from the
+ * scheduler so a composition root can catch or re-map them without importing the
+ * scheduling logic, and so the scheduler file stays focused on behaviour.
+ */
+
+/** Base class for every malformed-schedule failure, so callers can catch the family. */
+export abstract class JobScheduleError extends Error {}
+
+/** Raised when a job declares both a cron expression and a fixed interval. */
+export class AmbiguousJobScheduleError extends JobScheduleError {
+	constructor(jobName: string) {
+		super(`Job ${jobName} declares both "cron" and "intervalMs": pick exactly one`);
+		this.name = "AmbiguousJobScheduleError";
+	}
+}
+
+/** Raised when a job declares neither a cron expression nor a fixed interval. */
+export class MissingJobScheduleError extends JobScheduleError {
+	constructor(jobName: string) {
+		super(`Job ${jobName} declares no schedule: it needs either "cron" or "intervalMs"`);
+		this.name = "MissingJobScheduleError";
+	}
+}
+
+/** Raised when a fixed interval is not a usable delay (non-finite or non-positive). */
+export class InvalidJobIntervalError extends JobScheduleError {
+	constructor(jobName: string, intervalMs: number) {
+		super(`Job ${jobName} declares an invalid "intervalMs" (${intervalMs}): expected > 0`);
+		this.name = "InvalidJobIntervalError";
+	}
+}
+
+/** Raised when two jobs declare the same stable identifier. */
+export class DuplicateJobNameError extends JobScheduleError {
+	constructor(jobName: string) {
+		super(`Job ${jobName} is declared more than once: scheduled job names must be unique`);
+		this.name = "DuplicateJobNameError";
+	}
+}