@seedcord/core 0.11.0 → 0.12.0-next.2

package/dist/Bus-VJw-QpoY.mjs

@@ -0,0 +1,986 @@
+import "reflect-metadata";
+import { ActionRowBuilder, ButtonBuilder, ChannelSelectMenuBuilder, CheckboxBuilder, CheckboxGroupBuilder, CheckboxGroupOptionBuilder, ContainerBuilder, ContextMenuCommandBuilder, EmbedBuilder, FileBuilder, FileUploadBuilder, LabelBuilder, MediaGalleryBuilder, MentionableSelectMenuBuilder, ModalBuilder, RadioGroupBuilder, RadioGroupOptionBuilder, RoleSelectMenuBuilder, SectionBuilder, SeparatorBuilder, SlashCommandBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, TextDisplayBuilder, TextInputBuilder, UserSelectMenuBuilder } from "@discordjs/builders";
+import { InteractionContextType, MessageFlags, Routes, SeparatorSpacingSize } from "discord-api-types/v10";
+import { SeedcordErrorCode, paint } from "@seedcord/errors";
+import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
+import { Logger } from "@seedcord/logger";
+import { pluralize } from "@seedcord/utils/internal";
+import { filterCirculars, stripAnsi, timestampFromSnowflake } from "@seedcord/utils";
+import { TypedEventEmitter } from "@seedcord/event-emitter";
+import { Envapter } from "envapt";
+import { DiscordAPIError, REST } from "@discordjs/rest";
+
+//#region src/components/botColorHolder.ts
+const DEFAULT_COLOR = "Default";
+let readBotColor = () => void 0;
+function bindBotColor(read) {
+	readBotColor = read;
+}
+function getBotColor() {
+	return readBotColor() ?? DEFAULT_COLOR;
+}
+
+//#endregion
+//#region src/components/builderTypes.ts
+/**
+* Available Discord.js builder classes for use with BuilderComponent for commands, embeds, modals, etc.
+*
+* @internal
+*/
+const BuilderTypes = {
+	command: SlashCommandBuilder,
+	context_menu: ContextMenuCommandBuilder,
+	subcommand: SlashCommandSubcommandBuilder,
+	group: SlashCommandSubcommandGroupBuilder,
+	embed: EmbedBuilder,
+	modal: ModalBuilder,
+	label: LabelBuilder,
+	text_input: TextInputBuilder,
+	file_upload: FileUploadBuilder,
+	checkbox: CheckboxBuilder,
+	checkbox_group: CheckboxGroupBuilder,
+	checkbox_group_option: CheckboxGroupOptionBuilder,
+	radio_group: RadioGroupBuilder,
+	radio_group_option: RadioGroupOptionBuilder,
+	button: ButtonBuilder,
+	menu_string: StringSelectMenuBuilder,
+	menu_option_string: StringSelectMenuOptionBuilder,
+	menu_user: UserSelectMenuBuilder,
+	menu_channel: ChannelSelectMenuBuilder,
+	menu_mentionable: MentionableSelectMenuBuilder,
+	menu_role: RoleSelectMenuBuilder,
+	container: ContainerBuilder,
+	text_display: TextDisplayBuilder,
+	file: FileBuilder,
+	media: MediaGalleryBuilder,
+	section: SectionBuilder,
+	separator: SeparatorBuilder
+};
+/**
+* Available Discord.js action row classes for use with RowComponent for Select Menus and Buttons
+*
+* @internal
+*/
+const RowTypes = {
+	button: ActionRowBuilder,
+	menu_string: ActionRowBuilder,
+	menu_user: ActionRowBuilder,
+	menu_channel: ActionRowBuilder,
+	menu_mentionable: ActionRowBuilder,
+	menu_role: ActionRowBuilder
+};
+
+//#endregion
+//#region src/components/colors.ts
+const Colors = {
+	Aqua: 1752220,
+	Blue: 3447003,
+	Blurple: 5793266,
+	DarkAqua: 1146986,
+	DarkBlue: 2123412,
+	DarkButNotBlack: 2895667,
+	DarkerGrey: 8359053,
+	DarkGold: 12745742,
+	DarkGreen: 2067276,
+	DarkGrey: 9936031,
+	DarkNavy: 2899536,
+	DarkOrange: 11027200,
+	DarkPurple: 7419530,
+	DarkRed: 10038562,
+	DarkVividPink: 11342935,
+	Default: 0,
+	Fuchsia: 15418782,
+	Gold: 15844367,
+	Green: 5763719,
+	Grey: 9807270,
+	Greyple: 10070709,
+	LightGrey: 12370112,
+	LuminousVividPink: 15277667,
+	Navy: 3426654,
+	NotQuiteBlack: 2303786,
+	Orange: 15105570,
+	Purple: 10181046,
+	Red: 15548997,
+	White: 16777215,
+	Yellow: 16705372
+};
+
+//#endregion
+//#region src/components/resolveColor.ts
+const MAX_COLOR = 16777215;
+const RED_SHIFT = 16;
+const GREEN_SHIFT = 8;
+const palette = Colors;
+/**
+* Resolves a {@link BotColor} to the integer Discord expects.
+*
+* Ported from discord.js (Apache-2.0), `resolveColor` in src/util/Util.js.
+*/
+function resolveColor(color) {
+	let resolved;
+	if (typeof color === "string") {
+		if (color === "Random") return Math.floor(Math.random() * 16777216);
+		if (color === "Default") return 0;
+		if (/^#?[\da-f]{6}$/i.test(color)) return Number.parseInt(color.replace("#", ""), 16);
+		resolved = palette[color];
+	} else if (typeof color === "number") resolved = color;
+	else resolved = (color[0] << RED_SHIFT) + (color[1] << GREEN_SHIFT) + color[2];
+	if (resolved === void 0 || !Number.isSafeInteger(resolved)) throw new SeedcordTypeError(SeedcordErrorCode.ColorUnresolvable, [JSON.stringify(color)]);
+	if (resolved < 0 || resolved > MAX_COLOR) throw new SeedcordRangeError(SeedcordErrorCode.ColorOutOfRange, [resolved]);
+	return resolved;
+}
+
+//#endregion
+//#region src/components/Component.ts
+/** @internal */
+var BaseComponent = class {
+	_component;
+	constructor(ComponentClass) {
+		this._component = new ComponentClass();
+	}
+	/**
+	* The wrapped builder, for calling Discord.js methods like setTitle() and setDescription() inside a subclass.
+	*
+	* @example this.instance.setTitle('My Modal')
+	*/
+	get instance() {
+		return this._component;
+	}
+};
+/**
+* Base class for Discord.js builder components
+*
+* Wraps Discord.js builders (SlashCommandBuilder, EmbedBuilder, etc.) with
+* Seedcord-specific defaults and helper methods.
+*
+* @typeParam BuilderKey - The type of Discord.js builder being wrapped
+*/
+var BuilderComponent = class extends BaseComponent {
+	type;
+	colorApplied = false;
+	constructor(type) {
+		const ComponentClass = BuilderTypes[type];
+		super(ComponentClass);
+		this.type = type;
+		if (this.instance instanceof SlashCommandBuilder || this.instance instanceof ContextMenuCommandBuilder) this.instance.setContexts(InteractionContextType.Guild);
+	}
+	get component() {
+		this.applyBotColor();
+		return this.instance;
+	}
+	applyBotColor() {
+		if (this.colorApplied) return;
+		this.colorApplied = true;
+		const color = getBotColor();
+		if (this.instance instanceof EmbedBuilder) {
+			if (this.instance.data.color === void 0) this.instance.setColor(resolveColor(color));
+		} else if (this.instance instanceof ContainerBuilder) {
+			const accent = this.instance.data.accent_color;
+			if (accent === null || accent === void 0) this.instance.setAccentColor(color === "Default" ? void 0 : resolveColor(color));
+		}
+	}
+};
+const BUILDER_COMPONENT = Symbol.for("seedcord:core:builder-component");
+Object.defineProperty(BuilderComponent.prototype, BUILDER_COMPONENT, { value: true });
+/** @internal */
+function isBuilderComponentClass(value) {
+	if (typeof value !== "function") return false;
+	const proto = value.prototype;
+	return typeof proto === "object" && proto !== null && BUILDER_COMPONENT in proto;
+}
+/**
+* Base class for Discord action row components
+*
+* Wraps Discord.js action row builder with Seedcord-specific defaults and helper methods.
+*
+* @typeParam RowKey - The Discord.js action row type being wrapped
+*/
+var RowComponent = class extends BaseComponent {
+	type;
+	constructor(type) {
+		const ComponentClass = RowTypes[type];
+		super(ComponentClass);
+		this.type = type;
+	}
+	get component() {
+		return this.instance;
+	}
+};
+
+//#endregion
+//#region src/metadataKeys.ts
+/**
+* Every interaction kind seedcord routes.
+*/
+let InteractionKind = /* @__PURE__ */ function(InteractionKind) {
+	InteractionKind["Slash"] = "slash";
+	InteractionKind["Button"] = "button";
+	InteractionKind["Modal"] = "modal";
+	InteractionKind["StringMenu"] = "stringMenu";
+	InteractionKind["UserMenu"] = "userMenu";
+	InteractionKind["RoleMenu"] = "roleMenu";
+	InteractionKind["ChannelMenu"] = "channelMenu";
+	InteractionKind["MentionableMenu"] = "mentionableMenu";
+	InteractionKind["MessageContextMenu"] = "messageContextMenu";
+	InteractionKind["UserContextMenu"] = "userContextMenu";
+	InteractionKind["Autocomplete"] = "autocomplete";
+	return InteractionKind;
+}({});
+const CommandMetadataKey = Symbol.for("seedcord:command:metadata");
+const InteractionMetadataKey = Symbol.for("seedcord:interaction:metadata");
+const InteractionMiddlewareMetadataKey = Symbol.for("seedcord:middleware:interaction:metadata");
+const EventMiddlewareMetadataKey = Symbol.for("seedcord:middleware:event:metadata");
+const SubscribeMetadataKey = Symbol.for("seedcord:subscribe:metadata");
+const EventMetadataKey = Symbol.for("seedcord:event:metadata");
+const GatedMetadataKey = Symbol.for("seedcord:gated:metadata");
+const WebhookUrlMetadataKey = Symbol.for("seedcord:webhook-url:metadata");
+const InteractionRouteKeys = {
+	["slash"]: Symbol.for("seedcord:interaction:slash"),
+	["button"]: Symbol.for("seedcord:interaction:button"),
+	["modal"]: Symbol.for("seedcord:interaction:modal"),
+	["stringMenu"]: Symbol.for("seedcord:interaction:string-menu"),
+	["userMenu"]: Symbol.for("seedcord:interaction:user-menu"),
+	["roleMenu"]: Symbol.for("seedcord:interaction:role-menu"),
+	["channelMenu"]: Symbol.for("seedcord:interaction:channel-menu"),
+	["mentionableMenu"]: Symbol.for("seedcord:interaction:mentionable-menu"),
+	["messageContextMenu"]: Symbol.for("seedcord:interaction:message-context-menu"),
+	["userContextMenu"]: Symbol.for("seedcord:interaction:user-context-menu"),
+	["autocomplete"]: Symbol.for("seedcord:interaction:autocomplete")
+};
+
+//#endregion
+//#region src/decorators/assertUniqueKeys.ts
+function assertUniqueKeys(decorator, ctor, keys, fix = "Remove one of the two tuples.") {
+	const seen = /* @__PURE__ */ new Set();
+	for (const key of keys) {
+		if (seen.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorDuplicateKey, [
+			decorator,
+			ctor.name,
+			key,
+			fix
+		]);
+		seen.add(key);
+	}
+}
+
+//#endregion
+//#region src/subscribers/publishDefault.ts
+/** @internal PublishableKey excludes this key so publish() never emits it externally. */
+const PublishDefault = Symbol("seedcord:bus:publish-default");
+
+//#endregion
+//#region src/lifecycle/phases.ts
+/**
+* Startup phases, in run order.
+*/
+let StartupPhase = /* @__PURE__ */ function(StartupPhase) {
+	/** Nothing connected. Plugin init runs here by default. */
+	StartupPhase[StartupPhase["Configuration"] = 1] = "Configuration";
+	/** The gateway session opens, and http runs its REST-only startup work. */
+	StartupPhase[StartupPhase["Login"] = 2] = "Login";
+	/** Handlers are live and interactions dispatch. */
+	StartupPhase[StartupPhase["Ready"] = 3] = "Ready";
+	return StartupPhase;
+}({});
+/**
+* Shutdown phases, in run order.
+*/
+let ShutdownPhase = /* @__PURE__ */ function(ShutdownPhase) {
+	/** Stop taking new interactions and requests. */
+	ShutdownPhase[ShutdownPhase["Unbind"] = 1] = "Unbind";
+	/** Waits for in-flight work to settle and stops internal services. */
+	ShutdownPhase[ShutdownPhase["Drain"] = 2] = "Drain";
+	/** External resources close. Plugin dispose runs here by default. */
+	ShutdownPhase[ShutdownPhase["Disconnect"] = 3] = "Disconnect";
+	/** The client disconnects last so in-flight handlers can still reference it during drain. */
+	ShutdownPhase[ShutdownPhase["Logout"] = 4] = "Logout";
+	/**
+	* Resources seedcord holds for the bot, like the `config.kv` driver, close after every plugin
+	* has stopped. Only seedcord runs work here.
+	*/
+	ShutdownPhase[ShutdownPhase["Release"] = 5] = "Release";
+	return ShutdownPhase;
+}({});
+
+//#endregion
+//#region src/kv/MemoryDriver.ts
+const SWEEP_GAP_MS = 6e4;
+/**
+* The default `config.kv`. It keeps every key in a `Map` and loses them on restart. On serverless,
+* each running copy keeps its own.
+*/
+var MemoryDriver = class {
+	#entries = /* @__PURE__ */ new Map();
+	#lastSweep = Date.now();
+	get(key) {
+		this.#maybeSweep();
+		return this.#live(key)?.value;
+	}
+	set(key, value, ttlMs) {
+		this.#maybeSweep();
+		this.#entries.set(key, {
+			value,
+			expiresAt: ttlMs === void 0 ? void 0 : Date.now() + ttlMs
+		});
+	}
+	delete(key) {
+		this.#entries.delete(key);
+	}
+	*entries(prefix) {
+		this.#maybeSweep();
+		for (const key of this.#entries.keys()) {
+			const entry = key.startsWith(prefix) ? this.#live(key) : void 0;
+			if (entry) yield [key, entry.value];
+		}
+	}
+	[Symbol.dispose]() {
+		this.#entries.clear();
+	}
+	#live(key) {
+		const entry = this.#entries.get(key);
+		if (entry?.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+			this.#entries.delete(key);
+			return;
+		}
+		return entry;
+	}
+	#maybeSweep() {
+		const now = Date.now();
+		if (now - this.#lastSweep < SWEEP_GAP_MS) return;
+		this.#lastSweep = now;
+		for (const key of this.#entries.keys()) this.#live(key);
+	}
+};
+
+//#endregion
+//#region src/dispatch/OnceTracker.ts
+var OnceTracker = class {
+	spent = /* @__PURE__ */ new WeakMap();
+	isSpent(entry, key) {
+		return entry.frequency === "once" && (this.spent.get(entry.ctor)?.has(key) ?? false);
+	}
+	claim(entry, key) {
+		if (entry.frequency !== "once") return true;
+		const keys = this.spent.get(entry.ctor) ?? /* @__PURE__ */ new Set();
+		if (keys.has(key)) return false;
+		this.spent.set(entry.ctor, keys.add(key));
+		return true;
+	}
+};
+
+//#endregion
+//#region src/reply/flags.ts
+function sendFlags(opts) {
+	let flags = MessageFlags.IsComponentsV2;
+	if (opts?.ephemeral ?? true) flags |= MessageFlags.Ephemeral;
+	if (opts?.silent) flags |= MessageFlags.SuppressNotifications;
+	return flags;
+}
+function deferFlags(opts) {
+	return opts?.ephemeral ?? true ? MessageFlags.Ephemeral : 0;
+}
+
+//#endregion
+//#region src/subscribers/ReportThrottle.ts
+var ReportThrottle = class ReportThrottle {
+	windowMs;
+	now;
+	static perCore = /* @__PURE__ */ new WeakMap();
+	static for(core) {
+		let throttle = ReportThrottle.perCore.get(core);
+		if (!throttle) {
+			throttle = new ReportThrottle();
+			ReportThrottle.perCore.set(core, throttle);
+		}
+		return throttle;
+	}
+	windows = /* @__PURE__ */ new Map();
+	constructor(windowMs = 6e4, now = () => Date.now()) {
+		this.windowMs = windowMs;
+		this.now = now;
+	}
+	take(key) {
+		const window = this.windows.get(key);
+		if (window && this.now() - window.lastSentAt < this.windowMs) {
+			window.suppressedSinceSend += 1;
+			return null;
+		}
+		const suppressed = window?.suppressedSinceSend ?? 0;
+		this.windows.set(key, {
+			lastSentAt: this.now(),
+			suppressedSinceSend: 0
+		});
+		return suppressed;
+	}
+	restore(key, suppressed) {
+		const window = this.windows.get(key);
+		if (window) window.suppressedSinceSend += suppressed + 1;
+	}
+};
+
+//#endregion
+//#region src/handlers/runCase.ts
+async function runCase(handler, cases, kind, value, ...args) {
+	const callback = Object.hasOwn(cases, value) ? cases[value] : void 0;
+	if (typeof callback !== "function") throw new SeedcordTypeError(SeedcordErrorCode.MatchCaseMissing, [
+		handler.constructor.name,
+		kind,
+		value
+	]);
+	return await callback(...args);
+}
+
+//#endregion
+//#region src/subscribers/Subscriber.ts
+/**
+* Abstract base class for handling application subscribers.
+*
+* Pass the subscription key(s) as the generic, the same one(s) as `@Subscribe`. On a single-key subscriber, read
+* `this.data` directly. On a subscriber for several keys, branch with `this.match`, keyed by subscription key.
+*
+* @typeParam Keys - One or more subscription keys, like `'userJoin'` or `'userJoin' | 'userLeave'`.
+* @typeParam TCore - The transport's Core
+*/
+var Subscriber = class {
+	core;
+	key;
+	logger;
+	#payload;
+	constructor(payload, core, key) {
+		this.core = core;
+		this.key = key;
+		this.#payload = payload;
+		this.logger = new Logger(this.constructor.name, { channel: "subscribers" });
+	}
+	/** The published payload. It's `never` on a subscriber for several keys, where `this.match` reads it. */
+	get data() {
+		return this.#payload;
+	}
+	/**
+	* Run the case for the published key. Use this only when the subscriber is registered for several
+	* keys. On a single-key subscriber, read `this.data` directly.
+	*
+	* Provide one case per registered key. Each case receives that key's own payload. A missing key or an unknown
+	* key is a compile error.
+	*
+	* @typeParam Ret - The type that every case must return. Leave it out to get the union of what the cases return.
+	* @throws A **SeedcordTypeError** with `MatchCaseMissing` when the published key doesn't have a case.
+	*
+	* @example
+	* ```ts
+	* import { Subscribe, Subscriber } from '@seedcord/gateway';
+	*
+	* \@Subscribe(['interactionDispatched'], ['eventDispatched'])
+	* class Metrics extends Subscriber<'interactionDispatched' | 'eventDispatched'> {
+	*     async execute() {
+	*         await this.match({
+	*             interactionDispatched: (data) => this.logger.info(data.routeId),
+	*             eventDispatched: (data) => this.logger.info(data.name)
+	*         });
+	*     }
+	* }
+	* ```
+	*/
+	async match(cases) {
+		return await runCase(this, cases, "subscription key", this.key, this.#payload);
+	}
+};
+
+//#endregion
+//#region src/subscribers/bases/webhookHelpers.ts
+const DISCORD_WEBHOOK_REGEX = new RegExp(String.raw`^https?:\/\/(?:canary\.|ptb\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/[\w$-]+$`);
+function isDiscordWebhookUrl(value) {
+	return URL.canParse(value) && DISCORD_WEBHOOK_REGEX.test(value);
+}
+function jsonAttachment(name, description, data) {
+	const content = filterCirculars(data);
+	return {
+		name,
+		description,
+		data: new TextEncoder().encode(JSON.stringify(content, void 0, 2))
+	};
+}
+function breakBackticks(text) {
+	return text.replaceAll("```", "`​`​`");
+}
+const REPORT_BUDGET = 1800;
+function body(value) {
+	const raw = Error.isError(value) ? value.stack ?? `${value.name}: ${value.message}` : String(value);
+	return breakBackticks(stripAnsi(raw));
+}
+function clamp(text, budget) {
+	if (text.length <= budget) return text;
+	return budget > 0 ? `${text.slice(0, budget - 1)}…` : "";
+}
+function omittedLine(count) {
+	return `\n\nand ${count} more ${pluralize(count, "failure")}`;
+}
+function memberReport(members, budget) {
+	const room = Math.max(budget - omittedLine(members.length).length, 0);
+	const share = Math.floor(room / members.length);
+	let report = "";
+	let shown = 0;
+	for (const [index, member] of members.entries()) {
+		const heading = `\n\nFailure ${index + 1} of ${members.length}:\n`;
+		const entry = heading + clamp(body(member), Math.max(share - heading.length, 0));
+		if (report.length + entry.length > room) break;
+		report += entry;
+		shown++;
+	}
+	const hidden = members.length - shown;
+	return hidden > 0 ? report + omittedLine(hidden) : report;
+}
+function errorReport(error) {
+	let head = body(error);
+	if (Error.isError(error.cause)) head += `\n\nCaused by:\n${body(error.cause)}`;
+	const members = error instanceof AggregateError ? error.errors : [];
+	if (members.length === 0) return clamp(head, REPORT_BUDGET);
+	const report = clamp(head, REPORT_BUDGET - omittedLine(members.length).length);
+	return report + memberReport(members, REPORT_BUDGET - report.length);
+}
+var WebhookSeparator = class extends BuilderComponent {
+	constructor() {
+		super("separator");
+		this.instance.setSpacing(SeparatorSpacingSize.Small).setDivider(true);
+	}
+};
+
+//#endregion
+//#region src/subscribers/bases/WebhookSender.ts
+const HTTP_NOT_FOUND = 404;
+const HTTP_UNAUTHORIZED = 401;
+var WebhookSender = class {
+	rest = new REST();
+	route;
+	constructor(url) {
+		const match = /\/webhooks\/(\d+)\/([\w$-]+)$/.exec(url);
+		if (!match?.[1] || !match[2]) throw new SeedcordTypeError(SeedcordErrorCode.CoreWebhookUrlInvalid, [new.target.name]);
+		this.route = Routes.webhook(match[1], match[2]);
+	}
+	async verify() {
+		try {
+			await this.rest.get(this.route, { auth: false });
+			return "ok";
+		} catch (error) {
+			return error instanceof DiscordAPIError && (error.status === HTTP_NOT_FOUND || error.status === HTTP_UNAUTHORIZED) ? "missing" : "unreachable";
+		}
+	}
+	async send(options) {
+		const { flags, username, avatarUrl, components, files } = options;
+		await this.rest.post(this.route, {
+			auth: false,
+			query: new URLSearchParams({
+				with_components: "true",
+				wait: "true"
+			}),
+			body: {
+				flags,
+				username,
+				...avatarUrl && { avatar_url: avatarUrl },
+				components: components.map((component) => component.toJSON()),
+				...files?.length && { attachments: files.map((file, id) => ({
+					id,
+					filename: file.name,
+					description: file.description
+				})) }
+			},
+			...files?.length && { files: files.map((file) => ({
+				name: file.name,
+				data: file.data
+			})) }
+		});
+	}
+};
+
+//#endregion
+//#region src/subscribers/bases/WebhookLog.ts
+/**
+* Base class for subscribers that deliver their event to a Discord webhook.
+*
+* Declare the url's environment variable with `@WebhookUrl` and implement {@link report}. The base
+* resolves the url, validates it, reuses one sender per url, and sends. Registration skips a reporter
+* whose variable is unset and warns at boot.
+*
+* @typeParam KeyOfSubscribers - The subscription key or keys that this reporter receives, the same ones as `@Subscribe`
+* @typeParam TCore - The transport's Core
+*/
+var WebhookLog = class WebhookLog extends Subscriber {
+	static senders = /* @__PURE__ */ new Map();
+	/**
+	* Events sharing this key collapse into one card per minute. Return `null` to send every event.
+	*/
+	throttleKey() {
+		return null;
+	}
+	async execute() {
+		const envKey = WebhookLog.envKeyOf(this.constructor);
+		const url = WebhookLog.urlOf(envKey);
+		if (url === null) throw new SeedcordError(SeedcordErrorCode.ConfigMissingEnv, [envKey]);
+		const key = this.throttleKey();
+		const throttle = ReportThrottle.for(this.core);
+		const suppressed = key === null ? 0 : throttle.take(key);
+		if (suppressed === null) {
+			this.logger.trace(`counted a repeat into the next ${paint.sky.bold(this.constructor.name)} card`);
+			return;
+		}
+		try {
+			const { username, avatarUrl, components, files } = await this.report(suppressed);
+			await WebhookLog.senderFor(url).send({
+				flags: sendFlags({ ephemeral: false }),
+				username: username ?? this.constructor.name,
+				avatarUrl,
+				components,
+				files
+			});
+		} catch (error) {
+			if (key !== null) throttle.restore(key, suppressed);
+			this.logger.error("Webhook report failed", error);
+		}
+	}
+	/** @internal */
+	static senderFor(url) {
+		let sender = WebhookLog.senders.get(url);
+		if (!sender) {
+			sender = new WebhookSender(url);
+			WebhookLog.senders.set(url, sender);
+		}
+		return sender;
+	}
+	/** @internal */
+	static envKeyOf(ctor) {
+		const envKey = Reflect.getMetadata(WebhookUrlMetadataKey, ctor);
+		if (!envKey) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorWebhookUrlMissing, [ctor.name]);
+		return envKey;
+	}
+	/** @internal Returns null when the env var is unset, throws when set but malformed. */
+	static urlOf(envKey) {
+		const raw = Envapter.get(envKey)?.trim();
+		if (!raw) return null;
+		if (!isDiscordWebhookUrl(raw)) throw new SeedcordError(SeedcordErrorCode.ConfigInvalidEnv, [envKey, "the webhook URL from the channel's Integrations settings"]);
+		return raw;
+	}
+};
+
+//#endregion
+//#region src/subscribers/decorators/Subscribe.ts
+/**
+* Registers a subscriber class with one or more subscription keys.
+*
+* Supply one `[key, options?]` tuple per key. The subscriber's generic must list the same keys.
+*
+* @decorator
+* @example
+* ```ts
+* \@Subscribe(['userJoin'])
+* class WelcomeHandler extends Subscriber<'userJoin'> {
+*     async execute() {
+*         this.logger.info(`${this.data.userId} joined`);
+*     }
+* }
+* ```
+* @example
+* ```ts
+* \@Subscribe(['userJoin', { frequency: 'once' }], ['userLeave'])
+* class Presence extends Subscriber<'userJoin' | 'userLeave'> {
+*     async execute() {
+*         await this.match({
+*             userJoin: (data) => this.logger.info(`${data.userId} joined`),
+*             userLeave: (data) => this.logger.info(`${data.userId} left`)
+*         });
+*     }
+* }
+* ```
+*/
+function Subscribe(...defs) {
+	return function(constructor) {
+		const entries = defs.map(([key, options]) => ({
+			key,
+			frequency: options?.frequency ?? "on"
+		}));
+		assertUniqueKeys("@Subscribe", constructor, entries.map((entry) => entry.key));
+		Reflect.defineMetadata(SubscribeMetadataKey, entries, constructor);
+	};
+}
+
+//#endregion
+//#region src/subscribers/decorators/WebhookUrl.ts
+/**
+* Declares the environment variable a {@link WebhookLog} reporter reads its webhook url from.
+*
+* An unset variable disables the reporter with a boot warning. A set but malformed value throws
+* at boot.
+*
+* @param envKey - The environment variable name holding the webhook url
+* @decorator
+* @example
+* ```ts
+* \@Subscribe(['memberBanned'])
+* \@WebhookUrl('BAN_LOG_WEBHOOK_URL')
+* class BanLog extends WebhookLog<'memberBanned'> {
+*   report() {
+*     return { components: [new BanCard(this.data).component] };
+*   }
+* }
+* ```
+*/
+function WebhookUrl(envKey) {
+	return function(constructor) {
+		Reflect.defineMetadata(WebhookUrlMetadataKey, envKey, constructor);
+	};
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/subscribers/default/HandledException.ts
+let HandledException = class HandledException extends WebhookLog {
+	throttleKey() {
+		return `handledException:${this.data.origin}:${this.data.denial.name}`;
+	}
+	report(suppressed) {
+		return {
+			username: "Handled Exception",
+			components: [new HandledExceptionContainer(this.data, suppressed).component],
+			files: [jsonAttachment("source.json", "The raw source the fault came from", this.data.source.raw)]
+		};
+	}
+};
+HandledException = __decorate([Subscribe(["handledException"]), WebhookUrl("HANDLED_EXCEPTION_WEBHOOK_URL")], HandledException);
+var HandledExceptionContainer = class extends BuilderComponent {
+	constructor(data, suppressed) {
+		super("container");
+		const { denial, uuid, source } = data;
+		this.instance.addTextDisplayComponents((text) => text.setContent(faultSummary(denial, source))).addSeparatorComponents(new WebhookSeparator().component).addTextDisplayComponents((text) => text.setContent(`### UUID \`${uuid}\`\n\`\`\`${breakBackticks(causeStack(denial))}\`\`\``)).addSeparatorComponents(new WebhookSeparator().component).addTextDisplayComponents((text) => text.setContent("### Source")).addFileComponents((file) => file.setURL("attachment://source.json"));
+		this.addSuppressedCount(suppressed);
+	}
+	addSuppressedCount(suppressed) {
+		if (suppressed === 0) return;
+		this.instance.addTextDisplayComponents((text) => text.setContent(`-# ${suppressed} more of these since the last report`));
+	}
+};
+function faultSummary(denial, source) {
+	const head = stripAnsi(`### A handled fault was reported: \`${denial.name}\`\n**Message:** ${denial.message}\n`);
+	if (source.kind === "event") return `${head}**Event:** ${source.eventName}\n**Handler:** ${source.handler}\n**User ID:** \`${source.userId ?? "n/a"}\`\n**Guild ID:** \`${source.guildId ?? "n/a"}\`\n**Channel ID:** \`${source.channelId ?? "n/a"}\``;
+	return `${head}**Kind:** ${source.interactionKind}\n**Command:** ${source.command ?? "n/a"}\n**CustomId:** ${source.customId ?? "n/a"}\n**User ID:** \`${source.userId}\`\n**Guild ID:** \`${source.guildId ?? "n/a"}\`\n**Channel ID:** \`${source.channelId ?? "n/a"}\`\n**Interaction ID:** \`${source.interactionId}\``;
+}
+function causeStack(denial) {
+	const { cause } = denial;
+	if (Error.isError(cause)) return stripAnsi(cause.stack ?? cause.message);
+	if (typeof cause === "string") return stripAnsi(cause);
+	if (typeof cause === "bigint" || typeof cause === "symbol" || typeof cause === "function") return cause.toString();
+	if (cause !== void 0) try {
+		return JSON.stringify(cause);
+	} catch {
+		return "[unserializable cause]";
+	}
+	return stripAnsi(denial.stack ?? "No cause recorded.");
+}
+
+//#endregion
+//#region src/subscribers/default/UnknownException.ts
+let UnknownException = class UnknownException extends WebhookLog {
+	throttleKey() {
+		return `unknownException:${this.data.origin}:${nameOf(this.data.error)}`;
+	}
+	report(suppressed) {
+		const { metadata } = this.data;
+		return {
+			username: "Unknown Exception",
+			components: [new UnhandledErrorContainer(this.data, suppressed).component],
+			files: metadata ? [jsonAttachment("metadata.json", "Metadata associated with the error", metadata)] : void 0
+		};
+	}
+};
+UnknownException = __decorate([Subscribe(["unknownException"]), WebhookUrl("UNKNOWN_EXCEPTION_WEBHOOK_URL")], UnknownException);
+function nameOf(error) {
+	return error.name === "Error" ? error.constructor.name : error.name;
+}
+var UnhandledErrorContainer = class extends BuilderComponent {
+	constructor(data, suppressed) {
+		super("container");
+		const { uuid, error, guild, user, metadata } = data;
+		this.instance.addTextDisplayComponents((text) => text.setContent(`### An unknown exception was thrown\n**Guild ID:** \`${guild?.id ?? "Not used in a guild"}\`\n**Guild Name:** ${guild?.name ?? "Not used in a guild"}\n**User ID:** \`${user?.id ?? "Missing user info"}\`\n**Username:** ${user?.username ?? "Missing user info"}\n`)).addSeparatorComponents(new WebhookSeparator().component).addTextDisplayComponents((text) => text.setContent(`### UUID \`${uuid}\`\n\`\`\`${errorReport(error)}\`\`\``));
+		this.addTimestampsIfAvailable(error);
+		this.addMetadataIfAvailable(metadata);
+		this.addSuppressedCount(suppressed);
+	}
+	addSuppressedCount(suppressed) {
+		if (suppressed === 0) return;
+		this.instance.addTextDisplayComponents((text) => text.setContent(`-# ${suppressed} more of these since the last report`));
+	}
+	addTimestampsIfAvailable(error) {
+		if (!(error instanceof DiscordAPIError)) return;
+		const now = Date.now();
+		const snowflake = error.url.match(/\/interactions\/(\d+)\//)?.[1];
+		if (!snowflake) return void 0;
+		const interactionTs = timestampFromSnowflake(snowflake);
+		const diff = now - interactionTs;
+		const seconds = Math.floor(diff / 1e3);
+		const millis = diff % 1e3;
+		this.instance.addSeparatorComponents(new WebhookSeparator().component).addTextDisplayComponents((text) => text.setContent(`### Timestamps\n- **\`Interaction sent\` :** ${new Date(interactionTs).toISOString()} (${interactionTs})\n- **\`Error logged    \` :** ${new Date(now).toISOString()} (${now})\n- **\`Offset          \` :** ${seconds}s ${millis}ms`));
+	}
+	addMetadataIfAvailable(metadata) {
+		if (!metadata) return;
+		this.instance.addSeparatorComponents(new WebhookSeparator().component).addTextDisplayComponents((text) => text.setContent("### Metadata")).addFileComponents((file) => file.setURL("attachment://metadata.json"));
+	}
+};
+
+//#endregion
+//#region src/subscribers/slots.ts
+const RegisterDefaults = Symbol("seedcord:bus:register-defaults");
+const VerifyWebhooks = Symbol("seedcord:bus:verify-webhooks");
+const RegisteredCount = Symbol("seedcord:bus:registered-count");
+const RegisterSubscriber = Symbol("seedcord:bus:register");
+const UnregisterSubscriber = Symbol("seedcord:bus:unregister");
+
+//#endregion
+//#region src/subscribers/Bus.ts
+const loggerSlot = Symbol("seedcord:bus:logger");
+/**
+* Registers and dispatches subscribers. Subscribers run on a programmatic or framework publish.
+* Accessed via `core.bus`. Do not construct it directly.
+*/
+var Bus = class extends TypedEventEmitter {
+	core;
+	logger = new Logger("Subscribers", { channel: "subscribers" });
+	/** @internal */
+	[loggerSlot] = this.logger;
+	subscribersMap = /* @__PURE__ */ new Map();
+	onceRuns = new OnceTracker();
+	webhookProbes = /* @__PURE__ */ new Map();
+	constructor(core) {
+		super();
+		this.core = core;
+	}
+	/** @internal keep this inside start(). a bad webhook url thrown outside it never resets the singleton guard */
+	[RegisterDefaults]() {
+		for (const ctor of [UnknownException, HandledException]) this[RegisterSubscriber](ctor);
+	}
+	/** @internal */
+	[RegisterSubscriber](ctor) {
+		if (!this.probeWebhook(ctor)) return;
+		for (const registration of registrationsFor(ctor)) {
+			let registrations = this.subscribersMap.get(registration.key);
+			if (!registrations) {
+				registrations = [];
+				this.subscribersMap.set(registration.key, registrations);
+			}
+			registrations.push(registration);
+		}
+	}
+	/** @internal */
+	[UnregisterSubscriber](ctor, keys) {
+		for (const key of keys ?? [...this.subscribersMap.keys()]) {
+			const registrations = this.subscribersMap.get(key);
+			if (!registrations) continue;
+			const index = registrations.findIndex((entry) => entry.ctor === ctor);
+			if (index !== -1) registrations.splice(index, 1);
+		}
+	}
+	/** @internal */
+	get [RegisteredCount]() {
+		return new Set([...this.subscribersMap.values()].flat().map((entry) => entry.ctor)).size;
+	}
+	/** @internal registration already skipped every reporter with no url set */
+	async [VerifyWebhooks]() {
+		const missing = [];
+		await Promise.all([...this.webhookProbes].map(async ([url, envKeys]) => {
+			const result = await WebhookLog.senderFor(url).verify();
+			if (result === "missing") missing.push(...envKeys);
+			else if (result === "unreachable") this.logger.warn(`could not verify webhook at ${envKeys.map((key) => paint.amber.bold(key)).join(", ")}`);
+		}));
+		if (missing.length > 0) throw new SeedcordError(SeedcordErrorCode.ConfigWebhookNotFound, [missing.join(", ")]);
+	}
+	probeWebhook(ctor) {
+		if (!(ctor.prototype instanceof WebhookLog)) return true;
+		const envKey = WebhookLog.envKeyOf(ctor);
+		const url = WebhookLog.urlOf(envKey);
+		if (url === null) {
+			this.logger.warn(`${paint.sky.bold(ctor.name)} is off because ${paint.amber.bold(envKey)} is not set`);
+			return false;
+		}
+		const envKeys = this.webhookProbes.get(url) ?? [];
+		if (!envKeys.includes(envKey)) envKeys.push(envKey);
+		this.webhookProbes.set(url, envKeys);
+		return true;
+	}
+	/**
+	* Publishes an event to its subscribers and native listeners.
+	*
+	* Fire-and-forget. Subscriber handlers run asynchronously and this returns before they finish.
+	* Errors thrown by a subscriber or by an `on()` listener are caught and logged, never surfaced
+	* here. One throwing listener does not stop the others. Subscribers on one key run concurrently
+	* and carry no ordering guarantee. A `'once'` subscriber is marked as executed when it starts,
+	* even if it throws. It never runs twice.
+	*
+	* The framework's own keys are excluded. Subscribe to those and listen with `on`. The framework
+	* is their only publisher.
+	*
+	* @param event - The subscription key to publish
+	* @param data - Payload passed to each subscriber
+	* @returns Whether the underlying emitter had native listeners for the event
+	*/
+	publish(event, data) {
+		return this.dispatchKey(event, data);
+	}
+	/**
+	* @deprecated Call {@link Bus.publish} to reach subscribers and listeners together.
+	* @throws A **SeedcordTypeError** every time, with `CoreBusEmitUnavailable`. `emit` reaches only the `on()` listeners.
+	*/
+	emit(event, ..._args) {
+		throw new SeedcordTypeError(SeedcordErrorCode.CoreBusEmitUnavailable, [String(event)]);
+	}
+	/** @internal the framework's own publish path, keyed by a symbol no public entry exports */
+	[PublishDefault](event, data) {
+		return this.dispatchKey(event, data);
+	}
+	dispatchKey(event, data) {
+		this.processSubscriber(event, data);
+		return this.emitSafe(event, ...[data]);
+	}
+	onListenerError(error, event) {
+		this.logger.error(`listener for ${String(event)} threw`, error);
+	}
+	async processSubscriber(subscriberName, data) {
+		const registrations = this.subscribersMap.get(subscriberName);
+		if (!registrations) return;
+		const pending = registrations.reduce((acc, entry) => {
+			if (!this.onceRuns.claim(entry, subscriberName)) return acc;
+			acc.push(this.runSubscriber(entry, subscriberName, data));
+			return acc;
+		}, []);
+		await Promise.allSettled(pending);
+	}
+	async runSubscriber(entry, subscriberName, data) {
+		let name = "<unresolved>";
+		try {
+			const Ctor = entry.ctor;
+			name = Ctor.name;
+			await new Ctor(data, this.core, subscriberName).execute();
+		} catch (err) {
+			this.logger.error(`Error in subscriber ${paint.mute(String(subscriberName))} handler ${paint.sky.bold(name)}:`, err);
+		}
+	}
+};
+function registrationsFor(ctor) {
+	return Reflect.getMetadata(SubscribeMetadataKey, ctor).map(({ key, frequency }) => ({
+		key,
+		frequency,
+		ctor
+	}));
+}
+/** @internal */
+function busLoggerOf(bus) {
+	return bus[loggerSlot];
+}
+
+//#endregion
+export { InteractionRouteKeys as A, CommandMetadataKey as C, InteractionKind as D, GatedMetadataKey as E, isBuilderComponentClass as F, bindBotColor as I, WebhookUrlMetadataKey as M, BuilderComponent as N, InteractionMetadataKey as O, RowComponent as P, assertUniqueKeys as S, EventMiddlewareMetadataKey as T, OnceTracker as _, RegisterSubscriber as a, StartupPhase as b, VerifyWebhooks as c, WebhookLog as d, Subscriber as f, sendFlags as g, deferFlags as h, RegisterDefaults as i, SubscribeMetadataKey as j, InteractionMiddlewareMetadataKey as k, WebhookUrl as l, ReportThrottle as m, busLoggerOf as n, RegisteredCount as o, runCase as p, registrationsFor as r, UnregisterSubscriber as s, Bus as t, Subscribe as u, MemoryDriver as v, EventMetadataKey as w, PublishDefault as x, ShutdownPhase as y };
+//# sourceMappingURL=Bus-VJw-QpoY.mjs.map