@azurioh/discord-kernel 0.1.0

package/package.json

@@ -0,0 +1,89 @@
+{
+	"name": "@azurioh/discord-kernel",
+	"version": "0.1.0",
+	"description": "Framework kernel for Discord bots: command DSL, guards, interaction routing, composed components, i18n, ports (Presenter, Logger, DatabaseConnection, Authorizer, Scheduler).",
+	"keywords": [
+		"discord",
+		"discord.js",
+		"discord-bot",
+		"framework",
+		"clean-architecture",
+		"hexagonal",
+		"typescript",
+		"i18n"
+	],
+	"license": "MIT",
+	"author": "Alan Cunin (https://github.com/Azurioh)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Azurioh/discord-kernel.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Azurioh/discord-kernel/issues"
+	},
+	"homepage": "https://github.com/Azurioh/discord-kernel#readme",
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		"./errors": {
+			"types": "./dist/errors/index.d.ts",
+			"default": "./dist/errors/index.js"
+		},
+		"./i18n": {
+			"types": "./dist/i18n/index.d.ts",
+			"default": "./dist/i18n/index.js"
+		},
+		"./discord/components/interactive-message": {
+			"types": "./dist/discord/components/interactive-message/index.d.ts",
+			"default": "./dist/discord/components/interactive-message/index.js"
+		},
+		"./discord/components/paginator": {
+			"types": "./dist/discord/components/paginator/index.d.ts",
+			"default": "./dist/discord/components/paginator/index.js"
+		},
+		"./discord/components/settings-editor": {
+			"types": "./dist/discord/components/settings-editor/index.d.ts",
+			"default": "./dist/discord/components/settings-editor/index.js"
+		},
+		"./*": {
+			"types": "./dist/*.d.ts",
+			"default": "./dist/*.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.json",
+		"lint": "biome ci",
+		"format": "biome check --write",
+		"knip": "knip",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"node-cron": "4.6.0"
+	},
+	"peerDependencies": {
+		"discord.js": "^14.27.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.7",
+		"@types/node": "24.13.3",
+		"discord.js": "14.27.0",
+		"knip": "^6.15.0",
+		"tsc-alias": "^1.8.16",
+		"typescript": "^5.9.3",
+		"vite-tsconfig-paths": "^6.1.1",
+		"vitest": "^4.1.8"
+	},
+	"packageManager": "pnpm@11.20.0"
+}

package/src/authz/authorizer.ts

@@ -0,0 +1,76 @@
+/** Permission tiers, lowest to highest. `editor` implies `viewer`. */
+export type PermissionLevel = "viewer" | "editor";
+
+/** Numeric rank for comparing levels (`editor` ≥ `viewer`). */
+export const LEVEL_RANK: Record<PermissionLevel, number> = {
+	viewer: 1,
+	editor: 2,
+};
+
+/** A single grant: either a role or a user, at a given level. */
+export interface PermissionGrant {
+	readonly targetType: "role" | "user";
+	readonly targetId: string;
+	readonly level: PermissionLevel;
+}
+
+/** The full set of grants, split by target kind for cheap resolution. */
+export interface PermissionGrants {
+	readonly roles: Record<string, PermissionLevel>;
+	readonly users: Record<string, PermissionLevel>;
+}
+
+/**
+ * Cross-cutting authorization port for feature-level permission tiers (as
+ * opposed to Discord's own per-command `defaultMemberPermissions`/guild
+ * permissions, which gate *visibility* and native capabilities). A module
+ * grants a role or a user a level; a guard checks whether a member meets the
+ * level required for an action.
+ *
+ * Deliberately has no notion of "admin": a bot-wide administrator bypass is a
+ * Discord permission concern, composed at the guard level with
+ * `anyOf(createPermissionGuard([Administrator]), requireLevel(...))` — keeping
+ * this port focused on the one thing it owns, feature-level grants.
+ */
+export interface Authorizer {
+	/** Whether the user (directly, or via one of their roles) meets `required`. */
+	meetsLevel(
+		userId: string,
+		roleIds: readonly string[],
+		required: PermissionLevel,
+	): Promise<boolean>;
+	grantRole(roleId: string, level: PermissionLevel): Promise<void>;
+	grantUser(userId: string, level: PermissionLevel): Promise<void>;
+	/** Returns whether a grant existed to remove. */
+	revokeRole(roleId: string): Promise<boolean>;
+	/** Returns whether a grant existed to remove. */
+	revokeUser(userId: string): Promise<boolean>;
+	listGrants(): Promise<PermissionGrants>;
+}
+
+/**
+ * Shared resolution used by every adapter: a direct user grant wins over role
+ * grants; otherwise the highest matching role level applies. Returns whether
+ * the resolved level meets `required`.
+ */
+export function meetsResolvedLevel(
+	grants: PermissionGrants,
+	userId: string,
+	roleIds: readonly string[],
+	required: PermissionLevel,
+): boolean {
+	const userLevel = grants.users[userId];
+	let resolved: PermissionLevel | null = userLevel ?? null;
+	if (!resolved) {
+		for (const roleId of roleIds) {
+			const roleLevel = grants.roles[roleId];
+			if (roleLevel && (!resolved || LEVEL_RANK[roleLevel] > LEVEL_RANK[resolved])) {
+				resolved = roleLevel;
+			}
+		}
+	}
+	if (!resolved) {
+		return false;
+	}
+	return LEVEL_RANK[resolved] >= LEVEL_RANK[required];
+}

package/src/authz/require-level-guard.ts

@@ -0,0 +1,42 @@
+import type { BaseInteraction, CommandInteraction } from "discord.js";
+import type { Authorizer, PermissionLevel } from "@/authz/authorizer";
+import type { Guard } from "@/discord/command/guard";
+import type { LocalizedText } from "@/i18n";
+
+/**
+ * Role IDs held by the interacting member, resolved without a network call:
+ * `interaction.member.roles` is either the cached `GuildMemberRoleManager` (a
+ * cached-guild interaction) or a plain array of IDs (the raw API shape for an
+ * uncached one) — both are handled so the guard never has to fetch the member.
+ *
+ * Typed on the base `Interaction`, not on the command flavour a guard takes: a
+ * control clicked inside a message carries the member exactly the same way, and
+ * a rule that has to hold on both paths must be able to ask both.
+ */
+export function memberRoleIds(interaction: BaseInteraction): string[] {
+	const member = interaction.member;
+	if (!member || typeof member !== "object" || !("roles" in member)) {
+		return [];
+	}
+	const roles = member.roles;
+	return Array.isArray(roles) ? roles : Array.from(roles.cache.keys());
+}
+
+/**
+ * Deny unless the member meets `required` on the injected {@link Authorizer}
+ * (directly, or via one of their roles). Compose with a Discord-permission
+ * guard through `anyOf(...)` when a bot-wide administrator bypass is wanted —
+ * this guard alone knows nothing about Discord permissions.
+ */
+export function requireLevel(
+	authz: Authorizer,
+	required: PermissionLevel,
+	denyMessage: LocalizedText,
+): Guard {
+	return {
+		async check(interaction: CommandInteraction) {
+			const ok = await authz.meetsLevel(interaction.user.id, memberRoleIds(interaction), required);
+			return ok ? { ok: true } : { ok: false, message: denyMessage };
+		},
+	};
+}

package/src/clock.ts

@@ -0,0 +1,18 @@
+/**
+ * Abstraction over the current time. Injecting a clock (instead of calling
+ * `new Date()` directly) lets domain/application code be tested deterministically
+ * and keeps those layers free of ambient I/O.
+ */
+export interface Clock {
+	now(): Date;
+}
+
+/** The real clock, backed by the system time. */
+export const systemClock: Clock = {
+	now: () => new Date(),
+};
+
+/** A fixed clock for tests. */
+export function fixedClock(instant: Date): Clock {
+	return { now: () => new Date(instant) };
+}

package/src/concurrency/keyed-queue.ts

@@ -0,0 +1,50 @@
+/**
+ * Serialises asynchronous work per key while leaving distinct keys concurrent.
+ */
+export interface KeyedQueue {
+	/** Run `task` after every task already queued for `key` has settled. */
+	run<T>(key: string, task: () => Promise<T>): Promise<T>;
+	/** Number of keys with work in flight — exposed so tests can assert no leak. */
+	readonly size: number;
+}
+
+/**
+ * Gateway handlers fire concurrently for the same entity (two rapid events on one
+ * channel, a member joining twice, an event replay after a resume), so
+ * read-modify-write logic keyed on that entity interleaves and corrupts state.
+ * Chaining per key restores ordering without a global lock, which would
+ * needlessly serialise unrelated guilds.
+ */
+export function createKeyedQueue(): KeyedQueue {
+	const chains = new Map<string, Promise<unknown>>();
+
+	return {
+		get size() {
+			return chains.size;
+		},
+		run<T>(key: string, task: () => Promise<T>): Promise<T> {
+			const previous = chains.get(key) ?? Promise.resolve();
+			// The chain continues on the *settled* tail: a rejected task must not
+			// poison the queue for the tasks behind it, while `result` keeps the
+			// rejection observable by this caller alone.
+			const settledTail = previous.then(
+				() => undefined,
+				() => undefined,
+			);
+			const result = settledTail.then(task);
+			const tail = result.then(
+				() => undefined,
+				() => undefined,
+			);
+			chains.set(key, tail);
+			// Only the task that is still the tail may drop the entry, otherwise a
+			// later enqueue would be forgotten and the Map would grow unbounded.
+			void tail.then(() => {
+				if (chains.get(key) === tail) {
+					chains.delete(key);
+				}
+			});
+			return result;
+		},
+	};
+}

package/src/concurrency/run-with-concurrency.ts

@@ -0,0 +1,44 @@
+/**
+ * Runs every task in `items` through `worker`, never letting more than `limit`
+ * run at once, and resolves once all have settled. Results are returned in the
+ * same order as `items`, regardless of completion order.
+ *
+ * Exists so callers that must fan out many independent async calls (e.g.
+ * fetching a reaction's user list per distinct emoji across thousands of
+ * messages) can bound how many are in flight without going fully sequential —
+ * without pulling in an external dependency for what is, in essence, a small
+ * counter and a queue (the same shape of problem `keyed-queue.ts` already
+ * solves for *serialised* per-key work, just bounding *parallel* work here
+ * instead).
+ */
+export async function runWithConcurrency<T, R>(
+	items: readonly T[],
+	limit: number,
+	worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	if (items.length === 0) {
+		return [];
+	}
+
+	// `noUncheckedIndexedAccess` makes every `results[i]` a possible `undefined`
+	// at the type level; asserting it away here is correct because every index
+	// is written exactly once below, before this array is ever returned.
+	const results = new Array<R>(items.length) as R[];
+	let nextIndex = 0;
+
+	async function runNext(): Promise<void> {
+		const currentIndex = nextIndex;
+		nextIndex += 1;
+		if (currentIndex >= items.length) {
+			return;
+		}
+		const item = items[currentIndex] as T;
+		results[currentIndex] = await worker(item, currentIndex);
+		await runNext();
+	}
+
+	const workerCount = Math.max(1, Math.min(limit, items.length));
+	await Promise.all(Array.from({ length: workerCount }, runNext));
+
+	return results;
+}

package/src/config/env.ts

@@ -0,0 +1,58 @@
+/**
+ * Generic, dependency-free helpers for reading and validating environment
+ * variables. The concrete application config (which keys exist, their defaults)
+ * is assembled by the composition root in `bootstrap/config.ts` — the core only
+ * provides the primitives so any bot can declare its own shape.
+ */
+
+import { InvalidEnvError, MissingEnvError } from "@/config/errors";
+
+type Env = Record<string, string | undefined>;
+
+/** Read a required variable, throwing {@link MissingEnvError} when absent. */
+export function requireEnv(key: string, env: Env = process.env): string {
+	const value = env[key];
+	if (value === undefined || value.trim() === "") {
+		throw new MissingEnvError(key);
+	}
+	return value;
+}
+
+/** Read an optional variable, returning `fallback` (or `undefined`) when absent. */
+export function optionalEnv(
+	key: string,
+	fallback?: string,
+	env: Env = process.env,
+): string | undefined {
+	const value = env[key];
+	if (value === undefined || value.trim() === "") {
+		return fallback;
+	}
+	return value;
+}
+
+/** Read a boolean variable (`true`/`1`/`yes` are truthy). */
+export function boolEnv(key: string, fallback: boolean, env: Env = process.env): boolean {
+	const value = env[key]?.trim().toLowerCase();
+	if (value === undefined || value === "") {
+		return fallback;
+	}
+	return value === "true" || value === "1" || value === "yes";
+}
+
+/** Read a variable constrained to a fixed set of values. */
+export function enumEnv<const T extends readonly string[]>(
+	key: string,
+	allowed: T,
+	fallback: T[number],
+	env: Env = process.env,
+): T[number] {
+	const value = env[key]?.trim();
+	if (value === undefined || value === "") {
+		return fallback;
+	}
+	if (!allowed.includes(value)) {
+		throw new InvalidEnvError(key, `one of ${allowed.join(", ")}`);
+	}
+	return value as T[number];
+}

package/src/config/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Failures raised while reading environment variables. They live apart from the
+ * reading logic so a consumer can catch or re-map them without pulling in the
+ * `env` helpers, and so the helpers file stays focused on behaviour.
+ */
+
+/** Raised when a required environment variable is missing or empty. */
+export class MissingEnvError extends Error {
+	constructor(key: string) {
+		super(`Missing required environment variable: ${key}`);
+		this.name = "MissingEnvError";
+	}
+}
+
+/** Raised when an environment variable holds an invalid value. */
+export class InvalidEnvError extends Error {
+	constructor(key: string, expected: string) {
+		super(`Invalid environment variable ${key}: expected ${expected}`);
+		this.name = "InvalidEnvError";
+	}
+}

package/src/datetime.ts

@@ -0,0 +1,221 @@
+/**
+ * Wall-clock datetime input grammar: `YYYY-MM-DD` with an optional
+ * ` HH:MM` / `THH:MM` time (seconds optional). Matches the format documented to
+ * users in the slash-command options.
+ */
+const WALL_CLOCK_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+
+interface WallClock {
+	year: number;
+	month: number;
+	day: number;
+	hour: number;
+	minute: number;
+	second: number;
+}
+
+function parseWallClock(input: string): WallClock | null {
+	const match = WALL_CLOCK_PATTERN.exec(input.trim());
+	if (!match) {
+		return null;
+	}
+	const [, year, month, day, hour, minute, second] = match;
+	const wallClock: WallClock = {
+		year: Number(year),
+		month: Number(month),
+		day: Number(day),
+		hour: hour ? Number(hour) : 0,
+		minute: minute ? Number(minute) : 0,
+		second: second ? Number(second) : 0,
+	};
+	return isRealCalendarInstant(wallClock) ? wallClock : null;
+}
+
+/**
+ * Reject impossible values the regex alone allows (month 13, day 32, hour 25)
+ * by round-tripping through `Date.UTC` and checking nothing overflowed.
+ */
+function isRealCalendarInstant(wallClock: WallClock): boolean {
+	const date = new Date(
+		Date.UTC(
+			wallClock.year,
+			wallClock.month - 1,
+			wallClock.day,
+			wallClock.hour,
+			wallClock.minute,
+			wallClock.second,
+		),
+	);
+	return (
+		date.getUTCFullYear() === wallClock.year &&
+		date.getUTCMonth() === wallClock.month - 1 &&
+		date.getUTCDate() === wallClock.day &&
+		date.getUTCHours() === wallClock.hour &&
+		date.getUTCMinutes() === wallClock.minute &&
+		date.getUTCSeconds() === wallClock.second
+	);
+}
+
+/**
+ * Offset, in milliseconds, between the given instant and how that instant reads
+ * as a wall clock in `timeZone` (positive when the zone is ahead of UTC).
+ */
+function timeZoneOffsetMs(timestamp: number, timeZone: string): number {
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+	});
+	const parts = new Map<string, number>();
+	for (const { type, value } of formatter.formatToParts(new Date(timestamp))) {
+		if (type !== "literal") {
+			parts.set(type, Number(value));
+		}
+	}
+	const read = (key: string): number => {
+		const value = parts.get(key);
+		if (value === undefined) {
+			throw new RangeError(`Missing "${key}" in formatted parts for time zone "${timeZone}"`);
+		}
+		return value;
+	};
+	const asUtc = Date.UTC(
+		read("year"),
+		read("month") - 1,
+		read("day"),
+		read("hour"),
+		read("minute"),
+		read("second"),
+	);
+	return asUtc - timestamp;
+}
+
+/**
+ * Interpret a wall-clock datetime string as local time in `timeZone` and return
+ * the matching UTC instant. Discord renders stored timestamps in each viewer's
+ * own timezone, so an event entered as "18:00" guild-local must be stored as the
+ * equivalent UTC instant — otherwise it drifts by the guild's UTC offset.
+ * @throws RangeError When the input does not match the wall-clock grammar.
+ */
+export function zonedWallClockToUtc(input: string, timeZone: string): Date {
+	const wallClock = parseWallClock(input);
+	if (!wallClock) {
+		throw new RangeError(`Invalid wall-clock datetime: "${input}"`);
+	}
+	const utcGuess = Date.UTC(
+		wallClock.year,
+		wallClock.month - 1,
+		wallClock.day,
+		wallClock.hour,
+		wallClock.minute,
+		wallClock.second,
+	);
+	// Two passes: the offset read at `utcGuess` can be wrong across a DST
+	// transition (the guessed instant may land on the far side of the boundary
+	// from the target). Re-reading the offset at the first candidate pins the
+	// correct one for every time except the ~1h/year that either does not exist
+	// (spring-forward gap) or is ambiguous (fall-back overlap), which resolve
+	// deterministically to one side.
+	const firstOffset = timeZoneOffsetMs(utcGuess, timeZone);
+	const secondOffset = timeZoneOffsetMs(utcGuess - firstOffset, timeZone);
+	return new Date(utcGuess - secondOffset);
+}
+
+/** Whether `input` is a valid wall-clock datetime string. */
+export function isValidWallClock(input: string): boolean {
+	return parseWallClock(input) !== null;
+}
+
+/** `YYYY-MM-DD` of a date-only value, read in UTC (matches `Date`-only options). */
+export function dayString(date: Date): string {
+	return date.toISOString().slice(0, 10);
+}
+
+/** Start of `date`'s calendar day (00:00:00) anchored to `timeZone`. */
+export function startOfGuildDay(date: Date, timeZone: string): Date {
+	return zonedWallClockToUtc(`${dayString(date)} 00:00:00`, timeZone);
+}
+
+/** End of `date`'s calendar day (23:59:59) anchored to `timeZone`. */
+export function endOfGuildDay(date: Date, timeZone: string): Date {
+	return zonedWallClockToUtc(`${dayString(date)} 23:59:59`, timeZone);
+}
+
+/**
+ * Monday 00:00 (guild-local) of the week following `reference`'s week. Used to
+ * anchor "next week"/"week after next" ranges to the guild's own calendar
+ * rather than to UTC day boundaries, which can disagree with the guild's local
+ * week near midnight around the timezone offset.
+ */
+export function startOfNextGuildWeek(reference: Date, timeZone: string): Date {
+	// Both the weekday *and* the calendar date must be read in `timeZone`, not
+	// UTC: near midnight, the guild-local day can already differ from the UTC
+	// day, and mixing the two would misplace the coming Monday by a day.
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		weekday: "short",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	});
+	const weekdayIndex: Record<string, number> = {
+		Sun: 0,
+		Mon: 1,
+		Tue: 2,
+		Wed: 3,
+		Thu: 4,
+		Fri: 5,
+		Sat: 6,
+	};
+	const parts = new Map<string, string>();
+	for (const { type, value } of formatter.formatToParts(reference)) {
+		if (type !== "literal") {
+			parts.set(type, value);
+		}
+	}
+	const currentDay = weekdayIndex[parts.get("weekday") ?? ""] ?? 0;
+	// ISO week starts on Monday: ahead-days is 0 only when already Monday and we
+	// still want *next* week's Monday, hence the `=== 1 ? 7` special-case.
+	const daysUntilNextMonday = currentDay === 1 ? 7 : (8 - currentDay) % 7;
+	// Advance the *calendar date* (a pure Y-M-D operation, DST-agnostic) before
+	// re-anchoring to the timezone — advancing the UTC instant instead would
+	// drift by an hour across a DST transition inside the date range.
+	const year = Number(parts.get("year"));
+	const month = Number(parts.get("month"));
+	const day = Number(parts.get("day"));
+	const nextMondayUtcCalendarDay = new Date(Date.UTC(year, month - 1, day + daysUntilNextMonday));
+	return startOfGuildDay(nextMondayUtcCalendarDay, timeZone);
+}
+/**
+ * Add `days` guild-local calendar days to `instant`, re-anchoring to
+ * `timeZone`'s midnight. `instant` is assumed to already be a guild-local
+ * midnight (e.g. the result of {@link startOfGuildDay} or
+ * {@link startOfNextGuildWeek}); adding a fixed millisecond offset instead
+ * would drift by the DST delta whenever the interval crosses a transition —
+ * this reads the calendar date in `timeZone` first, so the result is always
+ * that timezone's actual midnight `days` later.
+ */
+export function addGuildDays(instant: Date, days: number, timeZone: string): Date {
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	});
+	const parts = new Map<string, string>();
+	for (const { type, value } of formatter.formatToParts(instant)) {
+		if (type !== "literal") {
+			parts.set(type, value);
+		}
+	}
+	const year = Number(parts.get("year"));
+	const month = Number(parts.get("month"));
+	const day = Number(parts.get("day"));
+	const shiftedUtcCalendarDay = new Date(Date.UTC(year, month - 1, day + days));
+	return startOfGuildDay(shiftedUtcCalendarDay, timeZone);
+}