@azurioh/discord-kernel 0.1.0

package/src/discord/components/interactive-message/interactive-message-collector.ts

@@ -0,0 +1,374 @@
+import type {
+	ActionRowBuilder,
+	AnySelectMenuInteraction,
+	Attachment,
+	ButtonInteraction,
+	ChatInputCommandInteraction,
+	CollectedMessageInteraction,
+	ContainerBuilder,
+	EmbedBuilder,
+	InteractionUpdateOptions,
+	MessageActionRowComponentBuilder,
+	MessageMentionOptions,
+} from "discord.js";
+import type { Button, ComponentContext } from "@/discord/interaction/button";
+import type { Card } from "@/discord/ui/card";
+import { type MessageFile, planMessageAttachments } from "@/discord/ui/message-attachments";
+import { describeError } from "@/errors";
+import type { Logger } from "@/logger";
+
+/** How long an interactive message stays live without a click. */
+export const COLLECTOR_IDLE_MS = 5 * 60 * 1000;
+
+/**
+ * What every layout a message can render shares: the files it carries and who
+ * it may notify.
+ */
+interface InteractiveMessagePayloadBase {
+	/**
+	 * The files this message carries, as its **whole** set — an embed or a
+	 * card's `thumbnail`/`gallery` refers to one by name, as
+	 * `attachment://<name>`.
+	 *
+	 * Leaving the key out means "leave the message's attachments alone", which
+	 * is what a view carrying no file of its own must do: stating an empty set
+	 * would strip whatever the message was sent with. A view that does own its
+	 * files states them on every render, empty included, since that is what
+	 * makes removing one show up.
+	 */
+	files?: MessageFile[];
+	/**
+	 * Who this message may notify.
+	 *
+	 * Stated by a view that renders text it does not own — user-authored content
+	 * carrying mentions — so looking at a preview never pings the people it
+	 * names. Left out means Discord's own default, which is what a view building
+	 * every string itself wants.
+	 */
+	allowedMentions?: MessageMentionOptions;
+}
+
+/**
+ * The message payload shape shared by the initial reply and every update.
+ *
+ * A discriminated union rather than one shape with an optional `card`:
+ * Discord's `IS_COMPONENTS_V2` flag is **irreversible** (once a message carries
+ * it, an edit can never clear it) and a message carrying it may hold **no**
+ * embed at all — so "embeds" and "card" are not two options on the same
+ * message, they are two kinds of message, and mixing their fields must fail to
+ * compile rather than build a payload Discord would refuse.
+ *
+ * `layout` defaults to `"embeds"` — it is optional on that branch alone — so
+ * every payload a view already returns (`{ embeds, components }`, no `layout`
+ * key at all) keeps satisfying this type unchanged: nothing that predates the
+ * card layout has to name the one it was always using.
+ */
+export type InteractiveMessagePayload<S = never> =
+	| (InteractiveMessagePayloadBase & {
+			layout?: "embeds";
+			embeds: EmbedBuilder[];
+			components: ActionRowBuilder<MessageActionRowComponentBuilder>[];
+	  })
+	| (InteractiveMessagePayloadBase & {
+			layout: "card";
+			card: Card<S>;
+			/**
+			 * Rows shown beside the card rather than inside it — a screen's own
+			 * controls (reset, back, done). A Components V2 message accepts several
+			 * top-level components: the `Container` `card` compiles to is one, and
+			 * each of these is an `ActionRow` next to it. Omitted, or empty, for a
+			 * payload with no screen-level controls to show right now (a closed
+			 * screen).
+			 */
+			controls?: ActionRowBuilder<MessageActionRowComponentBuilder>[];
+			/**
+			 * Never present on this branch — declared anyway so that
+			 * `InteractiveMessagePayload<S>["components"]`, used elsewhere purely to
+			 * name the action-row array type, keeps resolving instead of erroring on
+			 * a key one arm of the union does not have.
+			 */
+			components?: never;
+	  });
+
+/**
+ * The payload as discord.js takes it on an edit, given what the message already
+ * carries: a file already up there under a wanted name is kept rather than
+ * uploaded a second time, so an unrelated re-render neither drops nor re-sends
+ * it.
+ *
+ * A payload stating no files touches neither field, leaving the message's own
+ * attachments alone.
+ *
+ * `state` is only read for a `"card"` payload — it is what `Card.apply` needs
+ * to render the container — and is otherwise unused. No caller building an
+ * `"embeds"` payload has ever had to pass it, and still does not: it is the
+ * third, optional parameter existing two-argument calls already omit.
+ */
+export function toMessageEditOptions<S>(
+	payload: InteractiveMessagePayload<S>,
+	existing: readonly Attachment[],
+	state?: S,
+): InteractionUpdateOptions {
+	const { files, allowedMentions } = payload;
+	const mentions = allowedMentions === undefined ? {} : { allowedMentions };
+	const attachments = files === undefined ? {} : planMessageAttachments(existing, files);
+
+	if (payload.layout === "card") {
+		if (state === undefined) {
+			// Only reachable once a caller actually builds a `"card"` payload
+			// without threading the state its `Card` needs — a programming error
+			// in that caller, not something a member's click can trigger.
+			throw new Error(
+				'toMessageEditOptions: a "card" layout payload needs the state its Card was ' +
+					"declared over to call Card.apply, and none was given.",
+			);
+		}
+		return {
+			components: [payload.card.apply(state, false), ...(payload.controls ?? [])],
+			...mentions,
+			...attachments,
+		};
+	}
+
+	const { embeds, components } = payload;
+	return { embeds, components, ...mentions, ...attachments };
+}
+
+/**
+ * The single mutable cell shared by the view and the collector. Kept explicit
+ * rather than captured as a closure variable so the two always read the same
+ * reference.
+ */
+export interface StateStore<S> {
+	read(): S;
+	write(next: S): void;
+}
+
+/** Hold a state the collector can advance in place. */
+export function createStateStore<S>(initial: S): StateStore<S> {
+	let state = initial;
+	return {
+		read: () => state,
+		write: (next) => {
+			state = next;
+		},
+	};
+}
+
+/**
+ * What {@link InteractiveView.disabledControls} hands back: enough of a payload
+ * to neutralise the message's controls in place, in whichever layout the view
+ * renders.
+ *
+ * Not `Pick<InteractiveMessagePayload<S>, "components">` alone — on the card
+ * branch that type is `{ components?: never }`, since a card carries `render`'s
+ * controls beside its one container rather than inside it, as top-level
+ * `components` of its own kind. The second arm is what lets a card screen hand
+ * back its neutralised container *and* its neutralised outer row together —
+ * `Card.apply(state, true)` for the former, the same `createActionRow(...,
+ * { disableAll: true })` `render` already builds the row with for the latter —
+ * see {@link import("@/discord/ui/card").Card}.
+ */
+export type DisabledInteractiveMessageComponents<S> =
+	| Pick<InteractiveMessagePayload<S>, "components">
+	| {
+			readonly components: readonly (
+				| ContainerBuilder
+				| ActionRowBuilder<MessageActionRowComponentBuilder>
+			)[];
+	  };
+
+/**
+ * Turns a state into a message payload. Everything sent to Discord goes through
+ * here, so the collector never builds a payload of its own and the initial
+ * render can never drift from the updates.
+ */
+export interface InteractiveView<S> {
+	render(state: S): InteractiveMessagePayload<S>;
+	disabledControls(state: S): DisabledInteractiveMessageComponents<S>;
+}
+
+/**
+ * What a pick hands to its handler: the triggering interaction, the values
+ * Discord sent back already unwrapped, and the same `state`/`update` pairing a
+ * button's {@link ComponentContext} carries.
+ */
+export interface SelectComponentContext<S> {
+	readonly interaction: AnySelectMenuInteraction;
+	readonly values: readonly string[];
+	readonly state: S;
+	update(next: S): Promise<void>;
+}
+
+/**
+ * A select menu's behaviour inside an interactive message: the custom id the
+ * collector routes on, and what a pick does with the current state.
+ *
+ * Only the behaviour, unlike {@link Button} which also renders itself: a
+ * compiled select menu's rendering does not vary with the state, so it stays
+ * where the rest of the message is built — in the view.
+ */
+export interface InteractiveSelect<S> {
+	readonly id: string;
+	onSelect(ctx: SelectComponentContext<S>): Promise<void> | void;
+}
+
+export interface InteractiveMessageCollectorDeps<S> {
+	interaction: ChatInputCommandInteraction;
+	response: Awaited<ReturnType<ChatInputCommandInteraction["editReply"]>>;
+	buttons: Button<S>[];
+	/** Omitted by a message whose controls are all buttons. */
+	selects?: InteractiveSelect<S>[];
+	view: InteractiveView<S>;
+	store: StateStore<S>;
+	ownerId: string;
+	idleMs: number;
+	/**
+	 * Run once the message stops reacting, whichever way it ended — an explicit
+	 * {@link InteractiveMessageHandle.stop} or the idle deadline.
+	 *
+	 * This is where work that must not repeat at every click belongs: a settings
+	 * screen pushing its result to whatever it configures, so what it configures
+	 * never shows the half-finished states an administrator passed through. A
+	 * failure is logged, never thrown — the message has already ended.
+	 */
+	onEnd?: () => Promise<void> | void;
+	logger: Logger;
+}
+
+/**
+ * Attach the interaction/idle wiring to an already-sent message: it owns the
+ * collector, routes each interaction by custom ID to the button's `onClick` or
+ * the select menu's `onSelect`, scopes every interaction to the owner, and
+ * centralises error handling. Mirrors command `dispatch`.
+ *
+ * Generic over the state so the same mechanism serves anything whose controls
+ * react for a bounded lifetime — pagination, a settings screen, a confirmation.
+ * Persistent components that must survive a restart belong to the
+ * {@link import("@/discord/components/component-router").ComponentRouter}
+ * instead: this state lives in memory and dies on idle.
+ */
+export interface InteractiveMessageHandle {
+	/**
+	 * End the message's interactive life **without** neutralising its controls.
+	 *
+	 * For callers that have already rendered a final state — a confirmed
+	 * deletion, say — where the usual "disable on end" edit would target a
+	 * message, or a channel, that no longer exists. `onEnd` still runs.
+	 */
+	stop(): void;
+}
+
+export function mountInteractiveMessageCollector<S>(
+	deps: InteractiveMessageCollectorDeps<S>,
+): InteractiveMessageHandle {
+	const { interaction, response, buttons, view, store, ownerId, idleMs, logger } = deps;
+	const selects = deps.selects ?? [];
+
+	function renderOnto(collected: CollectedMessageInteraction, next: S): InteractionUpdateOptions {
+		return toMessageEditOptions(
+			view.render(next),
+			[...collected.message.attachments.values()],
+			next,
+		);
+	}
+
+	function createClickContext(clicked: ButtonInteraction): ComponentContext<S> {
+		return {
+			interaction: clicked,
+			state: store.read(),
+			update: async (next) => {
+				store.write(next);
+				await clicked.update(renderOnto(clicked, next));
+			},
+		};
+	}
+
+	function createPickContext(picked: AnySelectMenuInteraction): SelectComponentContext<S> {
+		return {
+			interaction: picked,
+			values: picked.values,
+			state: store.read(),
+			update: async (next) => {
+				store.write(next);
+				await picked.update(renderOnto(picked, next));
+			},
+		};
+	}
+
+	async function route(collected: CollectedMessageInteraction): Promise<void> {
+		if (collected.isButton()) {
+			const target = buttons.find((entry) => entry.id === collected.customId);
+			await target?.onClick?.(createClickContext(collected));
+			return;
+		}
+		if (collected.isAnySelectMenu()) {
+			const target = selects.find((entry) => entry.id === collected.customId);
+			await target?.onSelect(createPickContext(collected));
+		}
+	}
+
+	async function handleCollected(collected: CollectedMessageInteraction): Promise<void> {
+		try {
+			await route(collected);
+		} catch (error) {
+			// At `error`, and with everything the throw carried: whatever lands here
+			// left the click unanswered — Discord tells the administrator the
+			// interaction failed — so it is a defect to be found, not a hiccup. The
+			// custom id says which control it was, since the state that produced it
+			// is gone by the time anybody reads this.
+			logger.error(
+				{ err: describeError(error), customId: collected.customId },
+				"Failed to update interactive message",
+			);
+		}
+	}
+
+	function disableOnEnd(): void {
+		// The message outlives the collector, so leave the controls visibly inert
+		// instead of letting clicks fail silently.
+		interaction.editReply(view.disabledControls(store.read())).catch((error) => {
+			logger.warn({ err: describeError(error) }, "Failed to disable interactive message controls");
+		});
+	}
+
+	/**
+	 * A caller that stops the message itself has already rendered the final state,
+	 * so the disabling edit would be at best redundant and at worst aimed at
+	 * something that is gone. `onEnd` still runs: it answers "the message is over",
+	 * not "the message timed out".
+	 */
+	let stoppedByCaller = false;
+
+	async function handleEnd(): Promise<void> {
+		if (!stoppedByCaller) {
+			disableOnEnd();
+		}
+		try {
+			await deps.onEnd?.();
+		} catch (error) {
+			logger.warn({ err: describeError(error) }, "Failed to close interactive message");
+		}
+	}
+
+	// No `componentType`: the collector takes every message component the view
+	// renders — buttons and select menus alike — and `route` sorts them out.
+	const collector = response.createMessageComponentCollector({
+		// `idle` rearms on every collected interaction, so each click grants a
+		// fresh window rather than counting down from the first render.
+		idle: idleMs,
+		filter: (collected) => collected.user.id === ownerId,
+	});
+
+	collector.on("collect", handleCollected);
+	// One `end` listener for both ways out, so nothing an ending owes — inert
+	// controls, `onEnd` — depends on which one happened.
+	collector.on("end", handleEnd);
+
+	return {
+		stop() {
+			stoppedByCaller = true;
+			collector.stop();
+		},
+	};
+}

package/src/discord/components/interactive-message/mount-interactive-message.ts

@@ -0,0 +1,71 @@
+import { type ChatInputCommandInteraction, MessageFlags } from "discord.js";
+import {
+	COLLECTOR_IDLE_MS,
+	createStateStore,
+	type InteractiveMessageHandle,
+	type InteractiveSelect,
+	type InteractiveView,
+	mountInteractiveMessageCollector,
+	type StateStore,
+	toMessageEditOptions,
+} from "@/discord/components/interactive-message/interactive-message-collector";
+import type { Button } from "@/discord/interaction/button";
+import type { Logger } from "@/logger";
+
+export interface InteractiveMessageOptions<S> {
+	initialState: S;
+	buttons: Button<S>[];
+	/** Omitted by a message whose controls are all buttons. */
+	selects?: InteractiveSelect<S>[];
+	view: InteractiveView<S>;
+	ownerId: string;
+	/** Run once the message stops reacting, whichever way it ended. */
+	onEnd?: () => Promise<void> | void;
+	logger: Logger;
+	idleMs?: number;
+}
+
+/**
+ * Send an interactive message and keep its controls live for a bounded time:
+ * renders the initial state, then hands the message to the collector.
+ *
+ * Callers that have already sent their message — or that decide case by case
+ * whether it is worth collecting at all — use
+ * {@link mountInteractiveMessageCollector} directly.
+ *
+ * Call it on an already-deferred interaction.
+ */
+export async function mountInteractiveMessage<S>(
+	interaction: ChatInputCommandInteraction,
+	options: InteractiveMessageOptions<S>,
+): Promise<InteractiveMessageHandle & { readonly store: StateStore<S> }> {
+	const store = createStateStore(options.initialState);
+	const initial = options.view.render(store.read());
+	// A deferred reply carries no attachment yet, so every file the first render
+	// states is uploaded — there is nothing up there that could be kept instead.
+	const editOptions = toMessageEditOptions(initial, [], store.read());
+	const response = await interaction.editReply(
+		// `IS_COMPONENTS_V2` is set on the *first* send only, never again: Discord
+		// treats it as irreversible on a message — an edit can never clear it —
+		// so posing it here and only here is what keeps a later re-render from
+		// trying to flip a flag Discord would refuse to change.
+		initial.layout === "card"
+			? { ...editOptions, flags: MessageFlags.IsComponentsV2 }
+			: editOptions,
+	);
+
+	const handle = mountInteractiveMessageCollector({
+		interaction,
+		response,
+		buttons: options.buttons,
+		selects: options.selects,
+		view: options.view,
+		store,
+		ownerId: options.ownerId,
+		...(options.onEnd === undefined ? {} : { onEnd: options.onEnd }),
+		idleMs: options.idleMs ?? COLLECTOR_IDLE_MS,
+		logger: options.logger,
+	});
+
+	return { ...handle, store };
+}

package/src/discord/components/paginator/index.ts

@@ -0,0 +1,17 @@
+export {
+	mountPaginator,
+	type PaginatorOptions,
+} from "@/discord/components/paginator/mount-paginator";
+export {
+	clampPage,
+	createPageState,
+	isFirstPage,
+	isLastPage,
+	nextPage,
+	type PageState,
+	pageCount,
+	previousPage,
+	selectPageItems,
+} from "@/discord/components/paginator/page-state";
+export type { PaginatorLabels } from "@/discord/components/paginator/paginator-buttons";
+export type { PaginatorRender } from "@/discord/components/paginator/paginator-view";

package/src/discord/components/paginator/mount-paginator.ts

@@ -0,0 +1,69 @@
+import type { ChatInputCommandInteraction } from "discord.js";
+import {
+	COLLECTOR_IDLE_MS,
+	createStateStore,
+	mountInteractiveMessageCollector,
+	toMessageEditOptions,
+} from "@/discord/components/interactive-message";
+import { createPageState, pageCount } from "@/discord/components/paginator/page-state";
+import {
+	createPaginatorButtons,
+	type PaginatorLabels,
+	resolveLabels,
+} from "@/discord/components/paginator/paginator-buttons";
+import {
+	createPaginatorView,
+	type PaginatorRender,
+} from "@/discord/components/paginator/paginator-view";
+import type { Logger } from "@/logger";
+
+export interface PaginatorOptions<T> {
+	items: T[];
+	pageSize: number;
+	ownerId: string;
+	logger: Logger;
+	initialPage?: number;
+	idleMs?: number;
+	labels?: Partial<PaginatorLabels>;
+	render: PaginatorRender<T>;
+}
+
+/**
+ * A composed component: an embed plus previous/next buttons plus a collector.
+ * The collector itself is the generic
+ * {@link import("@/discord/components/interactive-message").mountInteractiveMessageCollector} —
+ * this module only contributes what is specific to pagination: the page state,
+ * the navigation buttons and the page view.
+ *
+ * Call it on an already-deferred interaction.
+ */
+export async function mountPaginator<T>(
+	interaction: ChatInputCommandInteraction,
+	options: PaginatorOptions<T>,
+): Promise<void> {
+	const { items, pageSize, ownerId, render, logger } = options;
+	const count = pageCount(items.length, pageSize);
+	const store = createStateStore(createPageState(options.initialPage ?? 1, count));
+	const buttons = createPaginatorButtons(count, resolveLabels(options.labels));
+	const view = createPaginatorView({ items, pageSize, count, render, buttons });
+
+	const response = await interaction.editReply(toMessageEditOptions(view.render(store.read()), []));
+
+	// A single page has nothing to navigate to, so it needs no collector at all —
+	// a pagination-specific rule, which is why it lives here and not in the
+	// generic mechanism.
+	if (count <= 1) {
+		return;
+	}
+
+	mountInteractiveMessageCollector({
+		interaction,
+		response,
+		buttons,
+		view,
+		store,
+		ownerId,
+		idleMs: options.idleMs ?? COLLECTOR_IDLE_MS,
+		logger,
+	});
+}

package/src/discord/components/paginator/page-state.ts

@@ -0,0 +1,45 @@
+/** What the paginator remembers between two clicks: the page being displayed (1-based). */
+export interface PageState {
+	page: number;
+}
+
+/** Total number of pages for a collection, never below 1. */
+export function pageCount(total: number, pageSize: number): number {
+	return Math.max(1, Math.ceil(total / pageSize));
+}
+
+/** Clamp a page number into the valid `[1, count]` range. */
+export function clampPage(page: number, count: number): number {
+	return Math.min(Math.max(page, 1), count);
+}
+
+/** Opening state, clamped so a caller-supplied out-of-range page stays valid. */
+export function createPageState(page: number, count: number): PageState {
+	return { page: clampPage(page, count) };
+}
+
+/** Transition one page back; a no-op on the first page. */
+export function previousPage(state: PageState, count: number): PageState {
+	return { page: clampPage(state.page - 1, count) };
+}
+
+/** Transition one page forward; a no-op on the last page. */
+export function nextPage(state: PageState, count: number): PageState {
+	return { page: clampPage(state.page + 1, count) };
+}
+
+/** Whether the "previous" affordance has nothing left to go back to. */
+export function isFirstPage(state: PageState): boolean {
+	return state.page <= 1;
+}
+
+/** Whether the "next" affordance has nothing left to go forward to. */
+export function isLastPage(state: PageState, count: number): boolean {
+	return state.page >= count;
+}
+
+/** Slice of the collection visible on the current page. */
+export function selectPageItems<T>(items: T[], state: PageState, pageSize: number): T[] {
+	const start = (state.page - 1) * pageSize;
+	return items.slice(start, start + pageSize);
+}

package/src/discord/components/paginator/paginator-buttons.ts

@@ -0,0 +1,60 @@
+import {
+	isFirstPage,
+	isLastPage,
+	nextPage,
+	type PageState,
+	previousPage,
+} from "@/discord/components/paginator/page-state";
+import { type Button, createButton } from "@/discord/interaction/button";
+
+/** Custom IDs of the two navigation buttons; also what the collector routes on. */
+const PREV_ID = "paginator:prev";
+const NEXT_ID = "paginator:next";
+
+export interface PaginatorLabels {
+	previous: string;
+	next: string;
+	previousEmoji?: string;
+	nextEmoji?: string;
+}
+
+const DEFAULT_LABELS: PaginatorLabels = {
+	previous: "Previous",
+	next: "Next",
+	previousEmoji: "◀️",
+	nextEmoji: "▶️",
+};
+
+/** Complete a caller's partial labels with the defaults. */
+export function resolveLabels(labels?: Partial<PaginatorLabels>): PaginatorLabels {
+	return { ...DEFAULT_LABELS, ...labels };
+}
+
+/**
+ * The navigation buttons, bound to a fixed page count. Each button carries its
+ * own disabled predicate and transition, so the collector only has to hand a
+ * click to the matching button instead of knowing what the click means.
+ */
+export function createPaginatorButtons(
+	count: number,
+	labels: PaginatorLabels,
+): Button<PageState>[] {
+	return [
+		createButton<PageState>({
+			id: PREV_ID,
+			label: labels.previous,
+			emoji: labels.previousEmoji,
+			style: "secondary",
+			disabled: (current) => isFirstPage(current),
+			onClick: (ctx) => ctx.update(previousPage(ctx.state, count)),
+		}),
+		createButton<PageState>({
+			id: NEXT_ID,
+			label: labels.next,
+			emoji: labels.nextEmoji,
+			style: "secondary",
+			disabled: (current) => isLastPage(current, count),
+			onClick: (ctx) => ctx.update(nextPage(ctx.state, count)),
+		}),
+	];
+}