@seedcord/core 0.12.0-next.0 → 0.12.0-next.3

package/dist/{subscribers-D4_HZcgw.mjs → subscribers-CGuVjbrg.mjs}

@@ -1,14 +1,23 @@
-import { D as InteractionMiddlewareMetadataKey, E as InteractionMetadataKey, O as InteractionRouteKeys, T as InteractionKind, b as PublishDefault, j as BuilderComponent, x as CommandMetadataKey } from "./Bus-W1K-uMeO.mjs";
+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, PermissionFlagsBits, Routes } from "discord-api-types/v10";
+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 { prettify, toEpochSeconds } from "@seedcord/utils";
+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.
@@ -38,7 +47,7 @@ import { prettify, toEpochSeconds } from "@seedcord/utils";
 *         super(`balance ${balance} is below the cost`);
 *     }
 *
-*     render(_ctx: RenderContext): ReplyResponse {
+*     override render(_ctx: RenderContext): ReplyResponse {
 *         return { components: [new TooPoorCard(this.balance).component] };
 *     }
 * }
@@ -63,7 +72,7 @@ var Notice = class extends Error {
 	*/
 	ephemeral = true;
 	/**
-	* A short one-line reason. When every arm of an {@link or} gate refuses and each one sets this, `or`
+	* 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".
 	*/
@@ -73,14 +82,13 @@ var Notice = class extends Error {
 		this.name = new.target.name;
 		Error.captureStackTrace(this, this.constructor);
 	}
-};
-
-//#endregion
-//#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}`));
+	/**
+	* 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] };
 	}
 };
 
@@ -309,7 +317,7 @@ const KIND_LABELS = {
 	[ApplicationCommandType.PrimaryEntryPoint]: "entry point command"
 };
 function multiGuildWarning({ name, type }) {
-	const consequence = type === ApplicationCommandType.ChatInput ? "falling back to plain text (not clickable)" : "leaving its id unset";
+	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 }) {
@@ -390,16 +398,21 @@ function interactionRoutesOf(constructor) {
 	}
 	return pairs;
 }
-function storeInteractionRoute(route, routes, constructor) {
+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);
+	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) {
@@ -484,7 +497,7 @@ const ILLEGAL = {
 	update: {
 		"deferred-reply": {
 			reason: "this interaction was deferred as a reply",
-			alternative: "The placeholder is yours via edit(). update() rewrites a source message."
+			alternative: "update() only rewrites a source message. Use edit() to fill the placeholder."
 		},
 		replied: {
 			reason: "this interaction was already replied to",
@@ -497,11 +510,11 @@ const ILLEGAL = {
 	} },
 	edit: { unacked: {
 		reason: "nothing has been sent yet",
-		alternative: "Send with reply() or defer() first, then edit() rewrites it."
+		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(), then delete() removes it."
+		alternative: "Acknowledge first with reply() or defer(). After that, delete() removes the reply."
 	} },
 	showModal: {
 		"deferred-reply": showModalReason,
@@ -540,12 +553,15 @@ var AckTrace = class extends Error {
 };
 
 //#endregion
-//#region src/reply/responseReport.ts
-let replyLogger;
-function logger() {
-	replyLogger ??= new Logger("Reply", { channel: "interactions" });
-	return replyLogger;
+//#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;
@@ -725,122 +741,33 @@ function serializeReply(response, routeId) {
 	};
 }
 
-//#endregion
-//#region src/gates/Gate.ts
-/**
-* Builds a {@link Gate} from a check. The check refuses by throwing a Notice or a Silence and passes
-* by returning. The required context is inferred from `ctx`, so annotate it as narrowly as the fields
-* the check reads. No annotation defaults to {@link GateContextBase}, an agnostic gate that fits every
-* handler.
-*
-* @typeParam Name - The gate's name, captured as a literal for mismatch errors.
-* @typeParam Ctx - The context the check reads, inferred from the `ctx` annotation.
-*
-* @param name - The gate's name, used in mismatch errors.
-* @param fn - The check, which refuses by throwing a Notice or a Silence and passes by returning.
-*
-* @see {@link defineEffectGate}
-* @see the `@Gated` decorator from your transport package
-*
-* @example
-* ```ts
-* // a gate factory that takes its own option and closes over it
-* function MinRoles(min: number): Gate<GateContextBase, 'MinRoles'> {
-*     return defineGate('MinRoles', (ctx) => {
-*         if (ctx.memberRoleIds.length < min) throw new NotEnoughRoles(min);
-*     });
-* }
-* ```
-*
-* @example
-* ```ts
-* // agnostic gate (no ctx annotation): fits any handler
-* const Owner = defineGate('owner', (ctx) => {
-*     if (!ctx.userId) throw new NotOwner();
-* });
-* ```
-*/
-function defineGate(name, fn) {
-	return {
-		name,
-		check: async (ctx) => fn(ctx)
-	};
-}
-/**
-* Builds an {@link EffectGate} from a `check` and a `commit`. `check` peeks and refuses by throwing, and
-* `commit` applies the side effect, running only once the whole gate set passes so a later refusal never
-* commits. In an `or`, a refusing arm's queued commit is rolled back. This is how {@link Cooldown} peeks
-* in `check` and charges the slot in `commit`.
-*
-* @typeParam Name - The gate's literal name, used to name a mismatch error.
-* @typeParam Ctx - The context both `check` and `commit` read, inferred from the `ctx` annotation.
-*
-* @param name - The gate's name, used in mismatch errors.
-* @param check - Peeks and refuses by throwing, without applying the side effect.
-* @param commit - Applies the side effect, running only after the whole gate set passes.
-*
-* @see {@link defineGate}
-* @see the `@Gated` decorator from your transport package
-* @see {@link Cooldown}
-*
-* @example
-* ```ts
-* // an effect-gate factory that takes its own limit and closes over it
-* function UsesPerDay(max: number): EffectGate<GateContextBase, 'UsesPerDay'> {
-*     return defineEffectGate(
-*         'UsesPerDay',
-*         (ctx) => {
-*             // peek and refuse by throwing. do not mutate yet
-*             if (usedToday(ctx.userId) >= max) throw new OutOfUsesNotice(max);
-*         },
-*         (ctx) => {
-*             // runs only after the whole gate set passes
-*             recordUse(ctx.userId);
-*         }
-*     );
-* }
-* ```
-*/
-function defineEffectGate(name, check, commit) {
-	return {
-		name,
-		check: async (ctx) => check(ctx),
-		commit: async (ctx) => commit(ctx)
-	};
-}
-
 //#endregion
 //#region src/notices/index.ts
-var GateNotice = class extends Notice {
-	render() {
-		return { components: [new NoticeCard(this.message).component] };
-	}
-};
-var NotOwner = class extends GateNotice {
-	constructor(message = "Only the bot owner can use this.") {
-		super(message);
+var NotOwner = class extends Notice {
+	constructor() {
+		super("Only the bot owner can use this.");
 		this.summary = "be the bot owner";
 	}
 };
-var NotInGuild = class extends GateNotice {
-	constructor(message = "This can only be used in a server.") {
-		super(message);
+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 GateNotice {
-	constructor(message = "This can only be used in a direct message.") {
-		super(message);
+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 GateNotice {
+var OnCooldown = class extends Notice {
 	resetAt;
-	constructor(resetAt, message) {
-		super(message ?? `You are doing that too fast. Try again ${retryAt(resetAt)}.`);
+	constructor(resetAt) {
+		super(`You are doing that too fast. Try again ${retryAt(resetAt)}.`);
 		this.resetAt = resetAt;
 		this.summary = `try again ${retryAt(resetAt)}`;
 	}
@@ -864,45 +791,98 @@ var NeedsAny = class extends Notice {
 		return { components: [new NoticeCard(`You need to meet at least one of these:\n${bullets}`).component] };
 	}
 };
-var MissingRole = class extends GateNotice {
-	constructor(message, roleId) {
-		super(message ?? (roleId ? `You need the <@&${roleId}> role to use this.` : "You do not have the required role."));
-		this.summary = roleId ? `hold the <@&${roleId}> role` : "hold the required role";
+var MissingRole = class extends Notice {
+	constructor(roleId) {
+		super(`You need the <@&${roleId}> role to use this.`);
+		this.summary = `hold the <@&${roleId}> role`;
 	}
 };
-var MissingPermissions = class extends Notice {
-	subject;
-	missingPerms;
-	customLead;
-	constructor(message, subject, missingPerms) {
-		super(message ?? "A required permission is missing.");
-		this.subject = subject;
-		this.missingPerms = missingPerms;
-		this.customLead = message;
-		const names = missingPerms.join(", ");
-		this.summary = subject === null ? `hold ${names}` : `${subject} needs ${names}`;
+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.missingPerms.map((perm) => `• ${perm}`).join("\n");
-		const lead = this.customLead ?? `${this.subject === null ? "You are" : `${this.subject} is`} missing the following permission entries:`;
-		return { components: [new NoticeCard(`${lead}\n${bullets}`).component] };
+		const bullets = this.permissions.map((perm) => `• ${perm}`).join("\n");
+		return { components: [new NoticeCard(`${this.lead}\n${bullets}`).component] };
 	}
 };
-var HasDangerousPermissions = class extends Notice {
-	subject;
-	dangerousPerms;
-	customLead;
-	constructor(message, subject, dangerousPerms) {
-		super(message ?? "A dangerous permission is enabled.");
-		this.subject = subject;
-		this.dangerousPerms = dangerousPerms;
-		this.customLead = message;
-		this.summary = `${subject} must not hold ${dangerousPerms.join(", ")}`;
+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"
+			}
+		});
 	}
-	render() {
-		const bullets = this.dangerousPerms.map((perm) => `• ${perm}`).join("\n");
-		const lead = this.customLead ?? `${this.subject} has the following permission entries that must not be enabled:`;
-		return { components: [new NoticeCard(`${lead}\n${bullets}`).component] };
+};
+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] };
 	}
 };
 
@@ -938,100 +918,6 @@ function rollbackCommits(ctx, mark) {
 	if (queue && queue.length > mark) queue.length = mark;
 }
 
-//#endregion
-//#region src/gates/catalog/options.ts
-function pickNotice(options, makeDefault) {
-	return options?.notice ?? makeDefault(options?.message);
-}
-
-//#endregion
-//#region src/permissions/bits.ts
-const PermissionNames = new Map(Object.entries(PermissionFlagsBits).map(([key, bit]) => [bit, prettify(key)]));
-const ADMINISTRATOR = PermissionFlagsBits.Administrator;
-function nameOf(bit) {
-	return PermissionNames.get(bit) ?? String(bit);
-}
-function holds(held, bit) {
-	return (held & ADMINISTRATOR) === ADMINISTRATOR || (held & bit) === bit;
-}
-/** @internal */
-function hasAll(held, scope) {
-	return scope.every((bit) => holds(held, bit));
-}
-/** @internal only reached once hasAll failed, so the administrator bit is absent */
-function missingNames(held, scope) {
-	return scope.reduce((names, bit) => {
-		if ((held & bit) !== bit) names.push(nameOf(bit));
-		return names;
-	}, []);
-}
-/** @internal */
-function presentNames(held, scope) {
-	return scope.reduce((names, bit) => {
-		if (holds(held, bit)) names.push(nameOf(bit));
-		return names;
-	}, []);
-}
-
-//#endregion
-//#region src/gates/catalog/permissions.ts
-const MEMBER_CHECK = {
-	unresolved: "Your server member data could not be resolved. Try again.",
-	subject: null
-};
-const BOT_CHECK = {
-	unresolved: "The bot's permissions could not be resolved. Try again.",
-	subject: "The bot"
-};
-function refusePermissions(held, scope, options, guildId, kind) {
-	if (held === null) throw pickNotice(options?.notInGuild, (message) => new NotInGuild(message ?? (guildId ? kind.unresolved : void 0)));
-	if (hasAll(held, scope)) return;
-	throw pickNotice(options?.missing, (message) => new MissingPermissions(message, kind.subject, missingNames(held, scope)));
-}
-function RequirePermissions(scope, options) {
-	if (options?.in === "guild") return defineGate("RequirePermissions", (ctx) => {
-		refusePermissions(ctx.memberGuildPermissions, scope, options, ctx.guildId, MEMBER_CHECK);
-	});
-	return defineGate("RequirePermissions", (ctx) => {
-		refusePermissions(ctx.memberPermissions, scope, options, ctx.guildId, MEMBER_CHECK);
-	});
-}
-function RequireBotPermissions(scope, options) {
-	if (options?.in === "guild") return defineGate("RequireBotPermissions", (ctx) => {
-		refusePermissions(ctx.appGuildPermissions, scope, options, ctx.guildId, BOT_CHECK);
-	});
-	return defineGate("RequireBotPermissions", (ctx) => {
-		refusePermissions(ctx.appPermissions, scope, options, ctx.guildId, BOT_CHECK);
-	});
-}
-/**
-* Requires the caller to hold `roleId`, read from the member's role ids. Refuses outside a guild first,
-* then when the role is missing. Roles are guild-global, so there is no scope dimension.
-*
-* @param roleId - The role snowflake the caller must hold.
-* @param options - Override each refusal, the outside-guild one with `notInGuild` and the missing-role one with `missingRole`.
-*
-* @see the `@Gated` decorator from your transport package
-*
-* @example
-* ```ts
-* \@Gated(RequireRole('123456789012345678'))
-* \@SlashRoute('vip')
-* class VipHandler extends SlashHandler<'vip'> {
-*     async execute() {
-*         // ...
-*     }
-* }
-* ```
-*/
-function RequireRole(roleId, options) {
-	return defineGate("RequireRole", (ctx) => {
-		if (!ctx.guildId) throw pickNotice(options?.notInGuild, (message) => new NotInGuild(message));
-		if (ctx.memberRoleIds.includes(roleId)) return;
-		throw pickNotice(options?.missingRole, (message) => new MissingRole(message, roleId));
-	});
-}
-
 //#endregion
 //#region src/stops/Silence.ts
 /**
@@ -1092,5 +978,5 @@ function pageCursor(prefix) {
 }
 
 //#endregion
-export { commandKey as $, serializeReply as A, contextMenuRouteOf as B, NotAllowed as C, OnCooldown as D, NotOwner as E, AckTrace as F, decodeComponentRoute as G, storeComponentRoute as H, checkAckLegality as I, CommandInjector as J, ConfigGuilds as K, sendTarget as L, attemptWrite as M, publishResponse as N, defineEffectGate as O, reportedWrite as P, warnLinks as Q, RegisterInteractionMiddleware as R, NeedsAny as S, NotInGuild as T, storeInteractionRoute as U, interactionRoutesOf as V, ComponentDefsKey as W, ContextMenus as X, Commands as Y, installLinks as Z, runCommits as _, RequireBotPermissions as a, guardedAccessor as at, MissingPermissions as b, PermissionNames as c, globalFirst as ct, presentNames as d, contextMenuLeaves as dt, commandRefOf as et, pickNotice as f, NoticeCard as ft, runCheck as g, rollbackCommits as h, Silence as i, clearStore as it, translateSerializationError as j, defineGate as k, hasAll as l, scopeIdsOf as lt, markCommits as m, pageCursor as n, linkCommands as nt, RequirePermissions as o, GLOBAL_ID as ot, discardCommits as p, Notice as pt, RegisterCommand as q, ResolvedEmoji as r, accessorStore as rt, RequireRole as s, commandsRoute as st, PAGE_MAX as t, indexById as tt, missingNames as u, skippedNote as ut, GateNotice as v, NotInDm as w, MissingRole as x, HasDangerousPermissions as y, interactionMiddlewareMetaOf as z };
-//# sourceMappingURL=subscribers-D4_HZcgw.mjs.map
+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