@seedcord/core 0.11.0 → 0.12.0-next.2

package/dist/subscribers-CGuVjbrg.mjs

@@ -0,0 +1,982 @@
+import { A as InteractionRouteKeys, C as CommandMetadataKey, D as InteractionKind, N as BuilderComponent, O as InteractionMetadataKey, S as assertUniqueKeys, k as InteractionMiddlewareMetadataKey, x as PublishDefault } from "./Bus-VJw-QpoY.mjs";
+import "reflect-metadata";
+import { CustomId, decodeFor } from "@seedcord/custom-id";
+import { TextDisplayBuilder } from "@discordjs/builders";
+import { ApplicationCommandType, Routes } from "discord-api-types/v10";
+import { SeedcordErrorCode, paint } from "@seedcord/errors";
+import { SeedcordError, SeedcordTypeError } from "@seedcord/errors/internal";
+import { Logger } from "@seedcord/logger";
+import { asError, isStringArray, pluralize, routeLeavesOf } from "@seedcord/utils/internal";
+import { toEpochSeconds } from "@seedcord/utils";
+
+//#region src/stops/NoticeCard.ts
+var NoticeCard = class extends BuilderComponent {
+	constructor(description, title = "Cannot Proceed") {
+		super("container");
+		this.instance.addTextDisplayComponents(new TextDisplayBuilder().setContent(`### ${title}\n${description}`));
+	}
+};
+
+//#endregion
+//#region src/stops/Notice.ts
+/**
+* Base class for a user-facing refusal or a reported fault.
+*
+* Throw a `Notice` to stop a handler and reply to the user. The framework catches it at the controller
+* boundary and renders {@link Notice.render}, which always decides what the user sees. With `report`
+* false that render is all that happens. With `report` true the framework also logs the fault and
+* publishes it to the `handledException` bus. A raw, non-Notice throw shows the generic message.
+*
+* @example
+* ```ts
+* import { Notice, BuilderComponent, type RenderContext, type ReplyResponse } from '@seedcord/gateway';
+* import { TextDisplayBuilder } from '@discordjs/builders';
+*
+* // reading `.component` applies the configured bot color to the container accent
+* class TooPoorCard extends BuilderComponent<'container'> {
+*     constructor(balance: number) {
+*         super('container');
+*         this.instance.addTextDisplayComponents(
+*             new TextDisplayBuilder().setContent(`### Insufficient balance\nYou need more than ${balance} coins.`)
+*         );
+*     }
+* }
+*
+* class TooPoor extends Notice {
+*     constructor(private readonly balance: number) {
+*         super(`balance ${balance} is below the cost`);
+*     }
+*
+*     override render(_ctx: RenderContext): ReplyResponse {
+*         return { components: [new TooPoorCard(this.balance).component] };
+*     }
+* }
+*
+* // in a handler, throwing stops the handler and replies with render(ctx)
+* if (wallet.balance < cost) throw new TooPoor(wallet.balance);
+* ```
+*/
+var Notice = class extends Error {
+	/**
+	* Whether this denial is a reported fault. True also logs it and publishes it to the `handledException`
+	* bus. The user always sees {@link Notice.render} either way.
+	*
+	* @defaultValue `false`
+	*/
+	report = false;
+	/**
+	* Whether the reply is ephemeral, seen only by the invoking user. Set it false for a refusal the
+	* whole channel should see.
+	*
+	* @defaultValue `true`
+	*/
+	ephemeral = true;
+	/**
+	* A short one-line reason. When every gate in an {@link or} refuses and each one sets this, `or`
+	* throws a refusal listing them under `You need to meet at least one of these:`. Write a verb phrase that
+	* finishes that line, for example, "be the bot owner".
+	*/
+	summary;
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+		Error.captureStackTrace(this, this.constructor);
+	}
+	/**
+	* Builds what the user sees. Called fresh each time the denial is shown, so the builders are new
+	* and the bot color resolves at render time. By default it returns seedcord's refusal card with the message as
+	* its text. Override it to show your own components.
+	*/
+	render(_ctx) {
+		return { components: [new NoticeCard(this.message).component] };
+	}
+};
+
+//#endregion
+//#region src/commands/contextMenuLeaves.ts
+function contextMenuLeaves(commands) {
+	const user = /* @__PURE__ */ new Set();
+	const message = /* @__PURE__ */ new Set();
+	for (const command of commands) if (command.type === ApplicationCommandType.User) user.add(command.name);
+	else if (command.type === ApplicationCommandType.Message) message.add(command.name);
+	return {
+		user,
+		message
+	};
+}
+
+//#endregion
+//#region src/commands/scopes.ts
+const GLOBAL_ID = "global";
+const allOf$1 = new Intl.ListFormat("en", { type: "conjunction" });
+function commandsRoute(applicationId, scope) {
+	return scope === "global" ? Routes.applicationCommands(applicationId) : Routes.applicationGuildCommands(applicationId, scope);
+}
+function globalFirst(scopes) {
+	return [...scopes].toSorted(([a], [b]) => Number(b === GLOBAL_ID) - Number(a === GLOBAL_ID));
+}
+function scopeIdsOf(target) {
+	return target.scope === "global" ? [GLOBAL_ID] : target.guilds;
+}
+function skippedNote(skipped, guildLabel) {
+	const guilds = skipped.filter((scope) => scope !== GLOBAL_ID).map(guildLabel);
+	const parts = [...skipped.includes("global") ? ["the global commands"] : [], ...guilds.length > 0 ? [`the commands in ${allOf$1.format(guilds)}`] : []];
+	return `Skipped ${allOf$1.format(parts)} because they match the last deploy.`;
+}
+
+//#endregion
+//#region src/miscellaneous/guarded.ts
+function accessorStore() {
+	return Object.create(null);
+}
+function clearStore(store) {
+	for (const key of Object.keys(store)) Reflect.deleteProperty(store, key);
+}
+function guardedAccessor(accessor, storage) {
+	return new Proxy(storage, { get(target, key, receiver) {
+		if (typeof key !== "string" || Object.hasOwn(target, key)) return Reflect.get(target, key, receiver);
+		throw new SeedcordError(SeedcordErrorCode.CoreAccessorUnresolved, [accessor, key]);
+	} });
+}
+
+//#endregion
+//#region src/commands/linkCommands.ts
+const MULTI_GUILD = Symbol("seedcord:commands:multi-guild");
+function commandRefOf({ name, type }) {
+	return {
+		name,
+		type: type ?? ApplicationCommandType.ChatInput
+	};
+}
+function commandKey(command) {
+	const { type, name } = commandRefOf(command);
+	return `${type}:${name}`;
+}
+function indexById(commands) {
+	return new Map(commands.map((command) => [command.id, command]));
+}
+function isSlash(json) {
+	return commandRefOf(json).type === ApplicationCommandType.ChatInput;
+}
+function uniqueRefs(refs) {
+	return [...new Map(refs.map((ref) => [commandKey(ref), ref])).values()];
+}
+function deployedIds(deploy) {
+	const ids = /* @__PURE__ */ new Map();
+	for (const [scope, collection] of deploy) {
+		if (scope === "global") continue;
+		for (const command of collection.values()) {
+			const key = commandKey(command);
+			const existing = ids.get(key);
+			if (existing === void 0) ids.set(key, command.id);
+			else if (existing !== command.id) ids.set(key, MULTI_GUILD);
+		}
+	}
+	for (const command of deploy.get("global")?.values() ?? []) ids.set(commandKey(command), command.id);
+	return ids;
+}
+function allDeployed(deploy) {
+	return [...deploy.values()].flatMap((collection) => [...collection.values()]);
+}
+function mentionOf(route, id) {
+	const spaced = route.replaceAll("/", " ");
+	return id ? `</${spaced}:${id}>` : `/${spaced}`;
+}
+var CommandLinker = class {
+	deploy;
+	ids;
+	constructor(deploy) {
+		this.deploy = deploy;
+		this.ids = deployedIds(deploy);
+	}
+	link(all) {
+		const slash = all.filter(isSlash);
+		const leaves = contextMenuLeaves(all);
+		const inCode = uniqueRefs([
+			...slash.map(commandRefOf),
+			...[...leaves.user].map((name) => ({
+				name,
+				type: ApplicationCommandType.User
+			})),
+			...[...leaves.message].map((name) => ({
+				name,
+				type: ApplicationCommandType.Message
+			}))
+		]);
+		return {
+			commands: this.slashRoutes(slash),
+			contextMenus: {
+				user: this.menus(leaves.user, ApplicationCommandType.User),
+				message: this.menus(leaves.message, ApplicationCommandType.Message)
+			},
+			multiGuild: inCode.filter((ref) => this.ids.get(commandKey(ref)) === MULTI_GUILD),
+			notInCode: this.notInCode(inCode)
+		};
+	}
+	slashRoutes(slash) {
+		const commands = accessorStore();
+		for (const command of slash) {
+			const id = this.idOf(commandRefOf(command));
+			for (const { route, description } of routeLeavesOf(command)) commands[route] = {
+				mention: mentionOf(route, id),
+				...id && { id },
+				route,
+				description
+			};
+		}
+		return commands;
+	}
+	menus(names, kind) {
+		const menus = accessorStore();
+		for (const name of names) {
+			const id = this.idOf({
+				name,
+				type: kind
+			});
+			menus[name] = {
+				...id && { id },
+				name,
+				kind
+			};
+		}
+		return menus;
+	}
+	idOf(ref) {
+		const id = this.ids.get(commandKey(ref));
+		return id === MULTI_GUILD ? void 0 : id;
+	}
+	notInCode(inCode) {
+		const inCodeKeys = new Set(inCode.map(commandKey));
+		const extra = /* @__PURE__ */ new Map();
+		for (const command of allDeployed(this.deploy)) {
+			const key = commandKey(command);
+			if (!inCodeKeys.has(key)) extra.set(key, commandRefOf(command));
+		}
+		return [...extra.values()];
+	}
+};
+function linkCommands(deploy, all) {
+	return new CommandLinker(deploy).link(all);
+}
+
+//#endregion
+//#region src/commands/CommandInjector.ts
+const commandStorage = accessorStore();
+const userMenuStorage = accessorStore();
+const messageMenuStorage = accessorStore();
+/**
+* The bot's deployed slash commands, keyed by {@link SlashRegistry}. A server bot fills these after
+* each deploy. An edge bot fills them on its first request, from the ids `seedcord build` wrote into
+* the worker.
+*
+* @throws A **SeedcordError** when you read a command before the bot fills it.
+*
+* @example
+* ```ts
+* import { Commands } from '@seedcord/gateway';
+*
+* await this.reply(`Try ${Commands['config/set'].mention}`);
+*
+* // a help listing
+* const lines = Object.values(Commands).map((c) => `${c.mention} ${c.description}`);
+* ```
+*/
+const Commands = guardedAccessor("Commands", commandStorage);
+/**
+* The bot's deployed context-menu commands. A server bot fills these after each deploy. An edge bot
+* fills them on its first request, from the ids `seedcord build` wrote into the worker.
+*
+* @throws A **SeedcordError** when you read a command before the bot fills it.
+*
+* @example
+* ```ts
+* import { ContextMenus } from '@seedcord/gateway';
+*
+* const id = ContextMenus.user['View Profile'].id;
+* ```
+*/
+const ContextMenus = {
+	user: guardedAccessor("ContextMenus.user", userMenuStorage),
+	message: guardedAccessor("ContextMenus.message", messageMenuStorage)
+};
+function installLinks({ commands, contextMenus }) {
+	const pairs = [
+		[commandStorage, commands],
+		[userMenuStorage, contextMenus.user],
+		[messageMenuStorage, contextMenus.message]
+	];
+	for (const [store, values] of pairs) {
+		clearStore(store);
+		Object.assign(store, values);
+	}
+}
+const KIND_LABELS = {
+	[ApplicationCommandType.ChatInput]: "slash command",
+	[ApplicationCommandType.User]: "user menu",
+	[ApplicationCommandType.Message]: "message menu",
+	[ApplicationCommandType.PrimaryEntryPoint]: "entry point command"
+};
+function multiGuildWarning({ name, type }) {
+	const consequence = type === ApplicationCommandType.ChatInput ? "so its mention stays plain text (not clickable)" : "so its id stays unset";
+	return `${paint.sky.bold(name)} is deployed to multiple guilds, ${consequence}.`;
+}
+function warnLinks(logger, { multiGuild, notInCode }) {
+	for (const ref of multiGuild) logger.warn(multiGuildWarning(ref));
+	for (const { name, type } of notInCode) logger.warn(`The ${KIND_LABELS[type]} ${paint.sky.bold(name)} is deployed on Discord with no command for it in your code.`);
+}
+/** @internal */
+var CommandInjector = class {
+	logger = new Logger("Commands", { channel: "bot" });
+	inject(deploy, all) {
+		const linked = linkCommands(deploy, all.map((command) => command.toJSON()));
+		installLinks(linked);
+		warnLinks(this.logger, linked);
+		const routes = Object.values(linked.commands);
+		const clickable = routes.filter((command) => command.id !== void 0).length;
+		this.logger.utils.summary("Linked commands", {
+			clickable,
+			plain: routes.length - clickable,
+			"context menus": Object.keys(linked.contextMenus.user).length + Object.keys(linked.contextMenus.message).length
+		});
+	}
+};
+
+//#endregion
+//#region src/decorators/Command.ts
+const ConfigGuilds = "config";
+function RegisterCommand(scope = "config", guilds = []) {
+	return (ctor) => {
+		const existingMeta = Reflect.getOwnMetadata(CommandMetadataKey, ctor);
+		if (existingMeta) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorCommandAlreadyRegistered, [
+			ctor.name,
+			decoratorCall(existingMeta.scope),
+			decoratorCall(scope)
+		]);
+		if (scope === "global" && guilds.length > 0) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorCommandGlobalWithGuilds, [ctor.name]);
+		if (scope === "guild" && (!Array.isArray(guilds) || guilds.length === 0)) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorCommandGuildWithoutGuilds, [ctor.name]);
+		const meta = scope === "guild" ? {
+			scope,
+			guilds
+		} : { scope };
+		Reflect.defineMetadata(CommandMetadataKey, meta, ctor);
+	};
+}
+function decoratorCall(scope) {
+	if (scope === "global") return "@RegisterCommand('global')";
+	if (scope === "guild") return "@RegisterCommand('guild', [...])";
+	return "@RegisterCommand()";
+}
+
+//#endregion
+//#region src/customId/routing.ts
+/**
+* route decorators store a handler's customId defs here, so the component base can decode
+* against them at runtime.
+*
+* @internal
+*/
+const ComponentDefsKey = Symbol.for("seedcord:custom-id:component-defs");
+/**
+* throws `CustomIdHandlerRouteMissing` when the class has no stored defs. a drifted or corrupt wire
+* throws `StaleCustomId` or `InvalidCustomId`.
+*
+* @internal
+*/
+function decodeComponentRoute(handlerClass, wire) {
+	const defs = Reflect.getMetadata(ComponentDefsKey, handlerClass);
+	if (!defs) throw new SeedcordTypeError(SeedcordErrorCode.CustomIdHandlerRouteMissing, [handlerClass.name]);
+	return decodeFor(defs, wire);
+}
+
+//#endregion
+//#region src/decorators/interactionRoutes.ts
+function interactionRoutesOf(constructor) {
+	const pairs = [];
+	for (const route of Object.values(InteractionKind)) {
+		const meta = Reflect.getMetadata(InteractionRouteKeys[route], constructor);
+		if (isStringArray(meta)) pairs.push([route, meta]);
+	}
+	return pairs;
+}
+function routeDecoratorOf(kind) {
+	return `@${kind.charAt(0).toUpperCase()}${kind.slice(1)}Route`;
+}
+function storeInteractionRoute(route, routes, constructor, fix = "Remove the repeat.") {
+	const key = InteractionRouteKeys[route];
+	const saved = Reflect.getMetadata(key, constructor);
+	const existing = isStringArray(saved) ? saved : [];
+	const toStore = typeof routes === "string" ? [routes] : routes;
+	const own = Reflect.getOwnMetadata(key, constructor);
+	assertUniqueKeys(routeDecoratorOf(route), constructor, [...isStringArray(own) ? own : [], ...toStore], fix);
+	Reflect.defineMetadata(key, [...existing, ...toStore], constructor);
+	Reflect.defineMetadata(InteractionMetadataKey, true, constructor);
+}
+function storeComponentRoute(route, defs, constructor) {
+	storeInteractionRoute(route, defs.map((def) => def.prefix), constructor, "Remove the repeat, or give each customId its own prefix.");
+	Reflect.defineMetadata(ComponentDefsKey, defs, constructor);
+}
+function contextMenuRouteOf(kind) {
+	return kind === ApplicationCommandType.User ? "userContextMenu" : "messageContextMenu";
+}
+
+//#endregion
+//#region src/decorators/middleware.ts
+/**
+* Registers an interaction middleware. It runs after the dispatcher builds the handler and before its
+* gates, over that handler's reply surface.
+*
+* @param options - The kinds this middleware runs on and its ordering.
+* @decorator
+*
+* @example
+* ```ts
+* \@RegisterInteractionMiddleware({ kinds: [InteractionKind.Button], priority: 10 })
+* class Audit extends InteractionMiddleware<InteractionKind.Button> {
+*     async execute() {
+*         this.logger.info(this.dispatch.routeId);
+*     }
+* }
+* ```
+*
+* @throws A **SeedcordTypeError** when `priority` is not a finite number.
+*/
+function RegisterInteractionMiddleware(options = {}) {
+	return function(ctor) {
+		const priority = Number(options.priority ?? 0);
+		if (!Number.isFinite(priority)) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorInvalidMiddlewarePriority, [ctor.name, String(options.priority)]);
+		if (options.kinds?.length === 0) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorEmptyMiddlewareFilter, [ctor.name, "kinds"]);
+		const metadata = {
+			priority,
+			...options.kinds && { kinds: options.kinds }
+		};
+		Reflect.defineMetadata(InteractionMiddlewareMetadataKey, metadata, ctor);
+	};
+}
+/** @internal */
+function interactionMiddlewareMetaOf(constructor) {
+	return Reflect.getMetadata(InteractionMiddlewareMetadataKey, constructor);
+}
+
+//#endregion
+//#region src/reply/ackLegality.ts
+const showModalReason = {
+	reason: "this interaction was already acknowledged",
+	alternative: "showModal() must be the initial response."
+};
+function deferReason(what) {
+	return {
+		reason: `this interaction was already acknowledged with ${what}`,
+		alternative: "A deferral can only be the initial response."
+	};
+}
+const ILLEGAL = {
+	reply: {
+		"deferred-reply": {
+			reason: "this interaction was already deferred",
+			alternative: "Use edit() to fill the deferred reply or followUp() for a new message."
+		},
+		"deferred-update": {
+			reason: "this interaction was already acknowledged with a deferred update",
+			alternative: "Use followUp() for a new message."
+		},
+		replied: {
+			reason: "this interaction was already replied to",
+			alternative: "Use followUp() for a new message or edit() to rewrite the reply."
+		}
+	},
+	defer: {
+		"deferred-reply": deferReason("a deferred reply"),
+		"deferred-update": deferReason("a deferred update"),
+		replied: deferReason("a reply")
+	},
+	deferUpdate: {
+		"deferred-reply": deferReason("a deferred reply"),
+		"deferred-update": deferReason("a deferred update"),
+		replied: deferReason("a reply")
+	},
+	update: {
+		"deferred-reply": {
+			reason: "this interaction was deferred as a reply",
+			alternative: "update() only rewrites a source message. Use edit() to fill the placeholder."
+		},
+		replied: {
+			reason: "this interaction was already replied to",
+			alternative: "update() rewrites a source message. Use edit() or followUp() instead."
+		}
+	},
+	followUp: { unacked: {
+		reason: "this interaction has not been acknowledged yet",
+		alternative: "Ack first with reply() or defer()."
+	} },
+	edit: { unacked: {
+		reason: "nothing has been sent yet",
+		alternative: "Send with reply() or defer() first. After that, edit() rewrites it."
+	} },
+	delete: { unacked: {
+		reason: "nothing has been sent yet",
+		alternative: "Acknowledge first with reply() or defer(). After that, delete() removes the reply."
+	} },
+	showModal: {
+		"deferred-reply": showModalReason,
+		"deferred-update": showModalReason,
+		replied: showModalReason
+	}
+};
+const SEND_TARGET = {
+	unacked: "reply",
+	"deferred-reply": "edit",
+	"deferred-update": "followUp",
+	replied: "followUp"
+};
+function checkAckLegality(method, state, routeId, ackedBy) {
+	if (method === "send") return;
+	const illegal = ILLEGAL[method][state];
+	if (!illegal) return;
+	throw new SeedcordError(SeedcordErrorCode.ReplyIllegalAckState, [
+		method,
+		illegal.reason,
+		illegal.alternative,
+		routeId
+	], { cause: ackedBy });
+}
+function sendTarget(state) {
+	return SEND_TARGET[state];
+}
+
+//#endregion
+//#region src/reply/AckTrace.ts
+var AckTrace = class extends Error {
+	constructor(method) {
+		super(`${method}() acknowledged this interaction`);
+		this.name = "AckTrace";
+	}
+};
+
+//#endregion
+//#region src/miscellaneous/lazyLogger.ts
+function lazyLogger(label, options) {
+	let logger;
+	return () => logger ??= new Logger(label, options);
+}
+
+//#endregion
+//#region src/reply/responseReport.ts
+const logger = lazyLogger("Reply", { channel: "interactions" });
+/** @internal */
+function publishResponse(telemetry, report) {
+	const durationMs = performance.now() - report.startedAt;
+	const { routeId } = telemetry.dispatch;
+	const write = {
+		dispatchId: telemetry.dispatch.id,
+		routeId,
+		interactionId: telemetry.interactionId,
+		method: report.method,
+		durationMs
+	};
+	telemetry.bus[PublishDefault]("responseAttempted", report.outcome === "failed" ? {
+		...write,
+		outcome: "failed",
+		messageId: null,
+		error: report.error
+	} : {
+		...write,
+		outcome: "sent",
+		messageId: report.messageId
+	});
+	logger().trace(`${paint.sky.bold(routeId)} ${report.method} ${report.outcome} ${paint.mute("in")} ${Math.round(durationMs)}ms`);
+}
+async function reportedWrite(telemetry, method, write) {
+	const startedAt = performance.now();
+	const result = await attemptWrite(telemetry, method, startedAt, write);
+	publishResponse(telemetry, {
+		method,
+		startedAt,
+		outcome: "sent",
+		messageId: null
+	});
+	return result;
+}
+async function attemptWrite(telemetry, method, startedAt, write) {
+	try {
+		return await write();
+	} catch (caught) {
+		publishResponse(telemetry, {
+			method,
+			startedAt,
+			outcome: "failed",
+			error: asError(caught)
+		});
+		throw caught;
+	}
+}
+
+//#endregion
+//#region src/reply/translateSerialization.ts
+const allOf = new Intl.ListFormat("en", { type: "conjunction" });
+const MAX_DEPTH = 8;
+const OPERATOR_WORD = {
+	"<=": "at most",
+	">=": "at least",
+	"<": "fewer than",
+	">": "more than"
+};
+const KIND_WORD = {
+	string: "a string",
+	number: "a number",
+	boolean: "a boolean",
+	bigint: "a bigint",
+	array: "a list",
+	tuple: "a list",
+	date: "a date",
+	object: "an object"
+};
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : null;
+}
+function firstLine(message) {
+	if (typeof message !== "string") return "unknown validation failure";
+	return message.split("\n")[0] ?? message;
+}
+const GIVEN_PREVIEW_LIMIT = 40;
+function gotPhrase(given) {
+	if (given === void 0) return "nothing";
+	if (given === null) return "null";
+	if (typeof given === "string") {
+		if (given.length === 0) return "an empty string";
+		if (given.length > GIVEN_PREVIEW_LIMIT) return `${given.length} characters`;
+		return JSON.stringify(given);
+	}
+	if (Array.isArray(given)) return given.length === 0 ? "an empty list" : `${given.length} items`;
+	if (typeof given === "number" || typeof given === "bigint" || typeof given === "boolean") return String(given);
+	if (typeof given === "object") return given.constructor?.name ?? "an object";
+	return typeof given;
+}
+function needPhrase(expected, given) {
+	const bounds = [...expected.matchAll(/expected(\.length)?\s*(<=|>=|<|>)\s*(\d+)/g)];
+	if (bounds.length === 0) return null;
+	const phrases = bounds.map(([, lengthPart, operator, limit]) => {
+		const word = OPERATOR_WORD[operator ?? ""] ?? operator ?? "";
+		if (!lengthPart) return `${word} ${limit}`;
+		const unit = typeof given === "string" ? "character" : "item";
+		return `${word} ${limit} ${pluralize(Number(limit), unit)}`;
+	});
+	return allOf.format(phrases);
+}
+function instanceName(expected) {
+	if (typeof expected === "function" && expected.name) return expected.name;
+	return "specific class instance";
+}
+function describeLeaf(record) {
+	if (typeof record.constraint === "string") {
+		const need = typeof record.expected === "string" ? needPhrase(record.expected, record.given) : null;
+		if (need) return `need ${need}, got ${gotPhrase(record.given)}`;
+		return `${firstLine(record.message)}${"given" in record ? ` (got ${gotPhrase(record.given)})` : ""}`;
+	}
+	if (typeof record.expected === "function") return `need a ${instanceName(record.expected)}, got ${gotPhrase(record.given)}`;
+	if (typeof record.validator === "string") {
+		const kind = KIND_WORD[record.validator.replace(/^s\./, "").replace(/\(.*$/, "")];
+		if (kind) return `need ${kind}, got ${gotPhrase(record.given)}`;
+		return `${firstLine(record.message)}, got ${gotPhrase(record.given)}`;
+	}
+	return firstLine(record.message);
+}
+function describeUnion(branches, depth) {
+	const records = [];
+	for (const branch of branches) {
+		const record = asRecord(branch);
+		if (record) records.push(record);
+	}
+	const bounded = records.find((record) => typeof record.constraint === "string");
+	if (bounded) return describeLeaf(bounded);
+	const names = [];
+	let allInstances = records.length > 0;
+	for (const record of records) if (typeof record.expected === "function") names.push(instanceName(record.expected));
+	else allInstances = false;
+	if (allInstances) return `need a ${[...new Set(names)].join(" or ")}, got ${gotPhrase(records[0]?.given)}`;
+	return detailOf(branches[0], depth + 1);
+}
+function detailOf(value, depth) {
+	const record = asRecord(value);
+	if (!record || depth >= MAX_DEPTH) return firstLine(record?.message);
+	if (Array.isArray(record.errors) && record.errors.length > 0) {
+		const errors = record.errors;
+		const [first] = errors;
+		if (Array.isArray(first)) {
+			const [key, inner] = first;
+			return `${String(key)}: ${detailOf(inner, depth + 1)}`;
+		}
+		return describeUnion(errors, depth);
+	}
+	return describeLeaf(record);
+}
+function translateSerializationError(error, componentClass, index, routeId) {
+	const detail = detailOf(error, 0);
+	return new SeedcordError(SeedcordErrorCode.ReplyComponentSerialization, [
+		componentClass,
+		index,
+		detail,
+		routeId
+	], { cause: error });
+}
+
+//#endregion
+//#region src/reply/serializeReply.ts
+function serializeReply(response, routeId) {
+	if (typeof response === "string") try {
+		return { components: [new TextDisplayBuilder().setContent(response).toJSON()] };
+	} catch (error) {
+		throw translateSerializationError(error, "TextDisplayBuilder", 0, routeId);
+	}
+	return {
+		components: response.components.map((component, index) => {
+			try {
+				return "toJSON" in component ? component.toJSON() : component;
+			} catch (error) {
+				const name = component?.constructor?.name;
+				throw translateSerializationError(error, !name || name === "Object" ? "component" : name, index, routeId);
+			}
+		}),
+		...response.allowedMentions && { allowedMentions: response.allowedMentions },
+		...response.files && { files: response.files }
+	};
+}
+
+//#endregion
+//#region src/notices/index.ts
+var NotOwner = class extends Notice {
+	constructor() {
+		super("Only the bot owner can use this.");
+		this.summary = "be the bot owner";
+	}
+};
+var NotInGuild = class extends Notice {
+	constructor() {
+		super("This can only be used in a server.");
+		this.summary = "be in a server";
+	}
+};
+var NotInDm = class extends Notice {
+	constructor() {
+		super("This can only be used in a direct message.");
+		this.summary = "be in a direct message";
+	}
+};
+function retryAt(resetAt) {
+	return `<t:${toEpochSeconds(resetAt)}:R>`;
+}
+var OnCooldown = class extends Notice {
+	resetAt;
+	constructor(resetAt) {
+		super(`You are doing that too fast. Try again ${retryAt(resetAt)}.`);
+		this.resetAt = resetAt;
+		this.summary = `try again ${retryAt(resetAt)}`;
+	}
+};
+var NotAllowed = class extends Notice {
+	constructor() {
+		super("not allowed");
+	}
+	render() {
+		return { components: [new NoticeCard("You are not allowed to use this command.").component] };
+	}
+};
+var NeedsAny = class extends Notice {
+	summaries;
+	constructor(summaries) {
+		super("not allowed");
+		this.summaries = [...new Set(summaries)];
+	}
+	render() {
+		const bullets = this.summaries.map((summary) => `• ${summary}`).join("\n");
+		return { components: [new NoticeCard(`You need to meet at least one of these:\n${bullets}`).component] };
+	}
+};
+var MissingRole = class extends Notice {
+	constructor(roleId) {
+		super(`You need the <@&${roleId}> role to use this.`);
+		this.summary = `hold the <@&${roleId}> role`;
+	}
+};
+var PermissionsUnresolved = class extends Notice {
+	constructor() {
+		super("Your server member data could not be resolved. Try again.");
+	}
+};
+var PermissionListNotice = class extends Notice {
+	permissions;
+	lead;
+	constructor(message, subject, permissions, wording) {
+		super(message);
+		this.permissions = permissions;
+		const [prefix, words] = subject === null ? ["", wording.caller] : [`${subject} `, wording.subject];
+		this.lead = `${prefix}${words.lead}`;
+		this.summary = `${prefix}${words.summary} ${permissions.join(", ")}`;
+	}
+	render() {
+		const bullets = this.permissions.map((perm) => `• ${perm}`).join("\n");
+		return { components: [new NoticeCard(`${this.lead}\n${bullets}`).component] };
+	}
+};
+var MissingPermissions = class extends PermissionListNotice {
+	constructor(subject, permissions) {
+		super("A required permission is missing.", subject, permissions, {
+			caller: {
+				lead: "You are missing the following permission entries:",
+				summary: "hold"
+			},
+			subject: {
+				lead: "is missing the following permission entries:",
+				summary: "needs"
+			}
+		});
+	}
+};
+var HasPresentPermissions = class extends PermissionListNotice {
+	constructor(subject, permissions) {
+		super("A refused permission is held.", subject, permissions, {
+			caller: {
+				lead: "You hold permissions that aren't allowed here:",
+				summary: "not hold"
+			},
+			subject: {
+				lead: "holds permissions that aren't allowed here:",
+				summary: "must not hold"
+			}
+		});
+	}
+};
+
+//#endregion
+//#region src/stops/Fault.ts
+/**
+* A generic fault you throw after catching an error you do not have a specific message for.
+*
+* The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to
+* `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`
+* to show the generic reply without the bus publish. The original error is stored as the standard
+* `cause`, so the real stack reaches the webhook. When the user should see a real message for a fault,
+* subclass {@link Notice} and write your own `render` instead.
+*
+* The framework also renders this for an unhandled throw, where it points the user at
+* `ctx.developerUsername`.
+*
+* @example
+* ```ts
+* import { Fault } from '@seedcord/gateway';
+*
+* try {
+*     await db.write(record);
+* } catch (cause) {
+*     // user sees the generic reply with the uuid, and the real error rides along as cause for the webhook
+*     throw new Fault({ cause });
+*
+*     // pass report: false to show the same reply without publishing to the handledException bus
+*     // throw new Fault({ cause, report: false });
+* }
+* ```
+*/
+var Fault = class extends Notice {
+	constructor(options) {
+		super("A fault occurred", options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.report = options?.report ?? true;
+	}
+	render(ctx) {
+		const contact = ctx.developerUsername ?? "the developer";
+		return { components: [new NoticeCard(`Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
+	}
+};
+
+//#endregion
+//#region src/gates/effects.ts
+const commitQueues = /* @__PURE__ */ new WeakMap();
+function isEffectGate(gate) {
+	return typeof gate.commit === "function";
+}
+async function runCheck(gate, ctx) {
+	await gate.check(ctx);
+	if (!isEffectGate(gate)) return;
+	let queue = commitQueues.get(ctx);
+	if (!queue) {
+		queue = [];
+		commitQueues.set(ctx, queue);
+	}
+	queue.push(() => gate.commit(ctx));
+}
+async function runCommits(ctx) {
+	const queue = commitQueues.get(ctx);
+	if (!queue) return;
+	for (const commit of queue) await commit();
+}
+function discardCommits(ctx) {
+	commitQueues.delete(ctx);
+}
+function markCommits(ctx) {
+	return commitQueues.get(ctx)?.length ?? 0;
+}
+function rollbackCommits(ctx, mark) {
+	const queue = commitQueues.get(ctx);
+	if (queue && queue.length > mark) queue.length = mark;
+}
+
+//#endregion
+//#region src/stops/Silence.ts
+/**
+* Throw to stop a handler with no reply and no report.
+*
+* The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
+* Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
+* leave the user with no reply for an interaction.
+*
+* @example
+* ```ts
+* import { Silence } from '@seedcord/gateway';
+*
+* // a helper under a guildMemberAdd handler, stopping when this guild configured nothing to send
+* const template = await settings.welcome(member.guild.id);
+* if (!template) throw new Silence('no welcome message set');
+* ```
+*/
+var Silence = class extends Error {
+	reason;
+	/**
+	* @param reason - Optional note written only to a debug log, never shown to the user or reported.
+	*/
+	constructor(reason) {
+		super(reason ?? "Silence");
+		this.reason = reason;
+		Error.captureStackTrace(this, this.constructor);
+	}
+};
+
+//#endregion
+//#region src/miscellaneous/ResolvedEmoji.ts
+/**
+* A resolved custom emoji. Renders as `<:name:id>` in message content, or `<a:name:id>` when animated,
+* and passes straight to a builder's `setEmoji`.
+*/
+var ResolvedEmoji = class {
+	name;
+	id;
+	animated;
+	constructor(name, id, animated = false) {
+		this.name = name;
+		this.id = id;
+		this.animated = animated;
+	}
+	toString() {
+		return `<${this.animated ? "a" : ""}:${this.name}:${this.id}>`;
+	}
+};
+
+//#endregion
+//#region src/pagination/cursor.ts
+const PAGE_MAX = 1e6;
+const SLOT_MAX = 4;
+/** Build the page cursor for a paginator. */
+function pageCursor(prefix) {
+	return new CustomId(prefix).int("page", 0, PAGE_MAX).int("slot", 0, SLOT_MAX);
+}
+
+//#endregion
+export { GLOBAL_ID as $, RegisterInteractionMiddleware as A, RegisterCommand as B, attemptWrite as C, AckTrace as D, lazyLogger as E, storeComponentRoute as F, warnLinks as G, Commands as H, storeInteractionRoute as I, indexById as J, commandKey as K, ComponentDefsKey as L, contextMenuRouteOf as M, interactionRoutesOf as N, checkAckLegality as O, routeDecoratorOf as P, guardedAccessor as Q, decodeComponentRoute as R, translateSerializationError as S, reportedWrite as T, ContextMenus as U, CommandInjector as V, installLinks as W, accessorStore as X, linkCommands as Y, clearStore as Z, NotInGuild as _, discardCommits as a, Notice as at, PermissionsUnresolved as b, runCheck as c, HasPresentPermissions as d, commandsRoute as et, MissingPermissions as f, NotInDm as g, NotAllowed as h, Silence as i, contextMenuLeaves as it, interactionMiddlewareMetaOf as j, sendTarget as k, runCommits as l, NeedsAny as m, pageCursor as n, scopeIdsOf as nt, markCommits as o, NoticeCard as ot, MissingRole as p, commandRefOf as q, ResolvedEmoji as r, skippedNote as rt, rollbackCommits as s, PAGE_MAX as t, globalFirst as tt, Fault as u, NotOwner as v, publishResponse as w, serializeReply as x, OnCooldown as y, ConfigGuilds as z };
+//# sourceMappingURL=subscribers-CGuVjbrg.mjs.map