@seedcord/core 0.1.0-next.4 → 0.1.0-next.6

package/dist/index.cjs

@@ -1,14 +1,16 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_CustomId = require('./CustomId-DV7daU7r.cjs');
+const require_permissions = require('./permissions-DSW_EZfN.cjs');
+const require_phases = require('./phases-C_BGNyVo.cjs');
 require("reflect-metadata");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
+let _seedcord_logger = require("@seedcord/logger");
 let _seedcord_utils = require("@seedcord/utils");
 
 //#region src/decorators/Command.ts
 function RegisterCommand(scope, guilds = []) {
 	return (ctor) => {
-		const existingMeta = Reflect.getOwnMetadata(require_CustomId.CommandMetadataKey, ctor);
+		const existingMeta = Reflect.getOwnMetadata(require_permissions.CommandMetadataKey, ctor);
 		if (existingMeta) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.DecoratorCommandAlreadyRegistered, [
 			ctor.name,
 			existingMeta.scope,
@@ -20,7 +22,138 @@ function RegisterCommand(scope, guilds = []) {
 			scope,
 			guilds
 		};
-		Reflect.defineMetadata(require_CustomId.CommandMetadataKey, meta, ctor);
+		Reflect.defineMetadata(require_permissions.CommandMetadataKey, meta, ctor);
+	};
+}
+
+//#endregion
+//#region src/decorators/routes.ts
+/**
+* Routes one or more slash commands to a `SlashHandler`.
+*
+* Pass the same route string(s) as the handler's generic. A single command reads `this.options`, several
+* commands branch with `this.match`. The decorator routes and the generic must match exactly, so listing
+* fewer or more than the handler declares is a compile error. Subcommands use a slash path.
+*
+* @param routes - The route string(s) this handler serves, e.g. `'ban'`, `'ban', 'kick'`, or `'demo/setup'`.
+* @decorator
+* @example
+* ```ts
+* \@SlashRoute('ban')
+* class BanHandler extends SlashHandler<'ban'> {
+*     async execute() {
+*         const target = this.options.getUser('target');
+*     }
+* }
+* ```
+*/
+function SlashRoute(...routes) {
+	return function(constructor) {
+		require_permissions.storeInteractionRoute("slash", routes, constructor);
+	};
+}
+/**
+* Routes one or more commands' autocomplete to an `AutocompleteHandler`.
+*
+* Pass the same command route string(s) as the handler's generic. One command branches with `this.match`
+* over its autocompletable fields, several commands share one handler whose arms span every command's
+* fields. The decorator routes and the generic must match exactly, so listing fewer or more than the
+* handler declares is a compile error.
+*
+* @param routes - The command route string(s) this handler serves, e.g. `'search'` or `'search', 'find'`.
+* @decorator
+* @example
+* ```ts
+* \@AutocompleteRoute('search')
+* class SearchAutocomplete extends AutocompleteHandler<'search'> {
+*     async execute() {
+*         await this.match({ query: (value, respond) => respond([{ name: value, value }]) });
+*     }
+* }
+* ```
+*/
+function AutocompleteRoute(...routes) {
+	return function(constructor) {
+		require_permissions.storeInteractionRoute("autocomplete", routes, constructor);
+	};
+}
+/**
+* Routes one or more context-menu commands to a `ContextMenuHandler`.
+*
+* Pass the kind (`ApplicationCommandType.User` or `ApplicationCommandType.Message`) and the command name(s),
+* each checked against that kind's registry, so a typo is a compile error. The handler's generic must
+* declare the same kind, cross-checked both directions. Context menus carry no options, so a multi-name
+* handler reads `this.target` uniformly with no branch.
+*
+* @param kind - The context-menu kind, `ApplicationCommandType.User` or `ApplicationCommandType.Message`.
+* @param names - The command name(s) this handler serves, keyed off the matching registry.
+* @decorator
+* @example
+* ```ts
+* \@ContextMenuRoute(ApplicationCommandType.User, 'View Profile')
+* class ViewProfile extends ContextMenuHandler<ApplicationCommandType.User> {
+*     async execute() {
+*         const user = this.target;
+*     }
+* }
+* ```
+*/
+function ContextMenuRoute(kind, ...names) {
+	return function(constructor) {
+		require_permissions.storeInteractionRoute(require_permissions.contextMenuRouteOf(kind), names, constructor);
+	};
+}
+/**
+* Routes button interactions to handler classes.
+*
+* Pass the {@link CustomId} definition(s) this handler decodes and list the same ones in the handler's
+* generic. Passing different definitions to the decorator and the generic is a compile error. Routing
+* matches the stable prefix, so a wire minted from an older shape still reaches the handler, where
+* reading this.params throws StaleCustomId and the controller boundary turns it into a reply.
+*
+* @param defs - The customId definition(s) this handler decodes, one per route.
+* @decorator
+*/
+function ButtonRoute(...defs) {
+	return function(constructor) {
+		require_permissions.storeComponentRoute("button", defs, constructor);
+	};
+}
+/**
+* Routes modal submissions to handler classes.
+*
+* Pass the {@link CustomId} definition(s) this handler decodes and list the same ones in the handler's
+* generic. Passing different definitions to the decorator and the generic is a compile error. Routing
+* matches the stable prefix, so an older-shape wire still reaches the handler and throws StaleCustomId
+* on read, the same as a button route.
+*
+* @param defs - The customId definition(s) this handler decodes, one per route.
+* @decorator
+*/
+function ModalRoute(...defs) {
+	return function(constructor) {
+		require_permissions.storeComponentRoute("modal", defs, constructor);
+	};
+}
+/**
+* Routes select menu interactions to handler classes.
+*
+* Pass the select kind and the {@link CustomId} definition(s) this handler decodes. The handler's
+* generic must list the same kind and definitions, or it is a compile error.
+*
+* @param type - Select menu kind from {@link SelectMenuKind}.
+* @param defs - The customId definition(s) this handler decodes, one per route.
+* @decorator
+*
+* @example
+* ```typescript
+* \@SelectMenuRoute(SelectMenuKind.User, AssignId)
+* class AssignSelect extends SelectMenuHandler<SelectMenuKind.User, [typeof AssignId]> {}
+* ```
+*/
+function SelectMenuRoute(type, ...defs) {
+	return function(constructor) {
+		require_permissions.storeComponentRoute(require_permissions.selectMenuRouteOf(type), defs, constructor);
 	};
 }
 
@@ -46,88 +179,75 @@ var DispatchContext = class {
 };
 
 //#endregion
-//#region src/gates/Gate.ts
+//#region src/handlers/BaseHandler.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, so a mismatch error can name the gate.
-* @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 `seedcord`
+* Base class every transport handler extends. Don't register handlers directly, use the more specific
+* handler subclasses.
 *
-* @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();
-* });
-* ```
+* @typeParam Event - The event or interaction this handler processes
+* @typeParam TCore - The transport's Core
 */
-function defineGate(name, fn) {
-	return {
-		name,
-		check: async (ctx) => fn(ctx)
-	};
-}
+var BaseHandler = class {
+	core;
+	event;
+	logger;
+	dispatch;
+	constructor(event, core, dispatch) {
+		this.core = core;
+		this.event = event;
+		this.logger = new _seedcord_logger.Logger(this.constructor.name);
+		this.dispatch = dispatch;
+	}
+};
+
+//#endregion
+//#region src/handlers/RepliableHandler.ts
 /**
-* 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 name captured as a literal, so a mismatch error can name the gate.
-* @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 `seedcord`
-* @see {@link Cooldown}
+* Shared base the repliable handlers on both transports extend. Defines the reply members over the sender
+* the transport builds.
 *
-* @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);
-*         }
-*     );
-* }
-* ```
+* @typeParam Event - The repliable interaction type this handler processes
+* @typeParam TCore - The transport's Core
+* @typeParam TMessage - The transport's created-message lens
+* @typeParam TSender - The transport's reply sender
 */
-function defineEffectGate(name, check, commit) {
-	return {
-		name,
-		check: async (ctx) => check(ctx),
-		commit: async (ctx) => commit(ctx)
-	};
-}
+var RepliableHandler = class extends BaseHandler {
+	sender;
+	routeId;
+	constructor(event, core, dispatch) {
+		super(event, core, dispatch);
+		this.routeId = dispatch?.routeId ?? this.constructor.name;
+		this.sender = this.buildSender(event, core, this.routeId);
+	}
+	/** @internal The dispatcher's fault boundary replies through the live ack state. */
+	getSender() {
+		return this.sender;
+	}
+	/** Send the initial response, exactly once. */
+	reply(response, opts) {
+		return this.sender.reply(response, opts);
+	}
+	/** Show a "thinking" placeholder, then fill it later with {@link edit}. */
+	defer(opts) {
+		return this.sender.defer(opts);
+	}
+	/** Send a new message once the interaction is acknowledged. */
+	followUp(response, opts) {
+		return this.sender.followUp(response, opts);
+	}
+	edit(targetOrResponse, maybeResponse) {
+		if (maybeResponse === void 0) return this.sender.edit(targetOrResponse);
+		return this.sender.edit(targetOrResponse, maybeResponse);
+	}
+	/** Routes to reply, followUp, or edit based on the current ack state. */
+	send(response, opts) {
+		return this.sender.send(response, opts);
+	}
+	/** Delete the initial reply or deferred placeholder. Pass a target to delete a message a prior send returned. */
+	delete(target) {
+		return target === void 0 ? this.sender.delete() : this.sender.delete(target);
+	}
+};
 
 //#endregion
 //#region src/stops/Fault.ts
@@ -158,21 +278,21 @@ function defineEffectGate(name, check, commit) {
 * }
 * ```
 */
-var Fault = class extends require_CustomId.Notice {
+var Fault = class extends require_permissions.Notice {
 	constructor(options) {
 		super("A fault occurred", options?.cause === void 0 ? void 0 : { cause: options.cause });
 		this.report = options?.report ?? true;
 	}
 	render(ctx) {
-		return { components: [new require_CustomId.NoticeCard(`Something went wrong. Please reach out to ${ctx.developerUsername ?? "the developer"} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
+		return { components: [new require_permissions.NoticeCard(`Something went wrong. Please reach out to ${ctx.developerUsername ?? "the developer"} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
 	}
 };
 
 //#endregion
 //#region src/gates/combinators.ts
 function and(...gates) {
-	return defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
-		for (const gate of gates) await require_CustomId.runCheck(gate, ctx);
+	return require_permissions.defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
+		for (const gate of gates) await require_permissions.runCheck(gate, ctx);
 	});
 }
 function isOrOptions(arg) {
@@ -182,17 +302,17 @@ function or(...args) {
 	const last = args.at(-1);
 	const options = last !== void 0 && isOrOptions(last) ? last : void 0;
 	const gates = options ? args.slice(0, -1) : args;
-	return defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
+	return require_permissions.defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
 		const summaries = [];
 		let everyArmHasSummary = true;
 		for (const gate of gates) {
-			const mark = require_CustomId.markCommits(ctx);
+			const mark = require_permissions.markCommits(ctx);
 			try {
-				await require_CustomId.runCheck(gate, ctx);
+				await require_permissions.runCheck(gate, ctx);
 				return;
 			} catch (error) {
-				if (error instanceof require_CustomId.Notice && !(error instanceof Fault) && !error.report) {
-					require_CustomId.rollbackCommits(ctx, mark);
+				if (error instanceof require_permissions.Notice && !(error instanceof Fault) && !error.report) {
+					require_permissions.rollbackCommits(ctx, mark);
 					if (error.summary === void 0) everyArmHasSummary = false;
 					else summaries.push(error.summary);
 					continue;
@@ -201,8 +321,8 @@ function or(...args) {
 			}
 		}
 		if (options) throw typeof options.fail === "function" ? options.fail(ctx) : options.fail;
-		if (everyArmHasSummary && summaries.length > 0) throw new require_CustomId.NeedsAny(summaries);
-		throw new require_CustomId.NotAllowed();
+		if (everyArmHasSummary && summaries.length > 0) throw new require_permissions.NeedsAny(summaries);
+		throw new require_permissions.NotAllowed();
 	});
 }
 
@@ -235,10 +355,10 @@ function or(...args) {
 * ```
 */
 function OwnerOnly(options) {
-	return defineGate("OwnerOnly", (ctx) => {
+	return require_permissions.defineGate("OwnerOnly", (ctx) => {
 		const owners = ctx.core.config.ownerIds ?? [];
 		if (ctx.userId !== null && owners.includes(ctx.userId)) return;
-		throw require_CustomId.pickNotice(options, (message) => new require_CustomId.NotOwner(message));
+		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotOwner(message));
 	});
 }
 /**
@@ -264,9 +384,9 @@ function OwnerOnly(options) {
 * ```
 */
 function GuildOnly(options) {
-	return defineGate("GuildOnly", (ctx) => {
+	return require_permissions.defineGate("GuildOnly", (ctx) => {
 		if (ctx.guildId) return;
-		throw require_CustomId.pickNotice(options, (message) => new require_CustomId.NotInGuild(message));
+		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotInGuild(message));
 	});
 }
 /**
@@ -290,9 +410,9 @@ function GuildOnly(options) {
 * ```
 */
 function DmOnly(options) {
-	return defineGate("DmOnly", (ctx) => {
+	return require_permissions.defineGate("DmOnly", (ctx) => {
 		if (!ctx.guildId) return;
-		throw require_CustomId.pickNotice(options, (message) => new require_CustomId.NotInDm(message));
+		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotInDm(message));
 	});
 }
 
@@ -364,11 +484,11 @@ function Cooldown(duration, options) {
 	};
 	const anonId = anonSeq++;
 	const keyOf = (ctx) => `cooldown:${ctx.routeId ?? `anon${anonId}`}:${per}:w${windowMs}:l${options?.limit ?? 1}:${scopeValue(ctx, per)}`;
-	return defineEffectGate("Cooldown", async (ctx) => {
+	return require_permissions.defineEffectGate("Cooldown", async (ctx) => {
 		const result = await ctx.core.rateLimiter.peek(keyOf(ctx), window);
 		if (!result.limited) return;
 		if (options?.notice) throw options.notice(result.resetAt);
-		throw new require_CustomId.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
+		throw new require_permissions.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
 	}, async (ctx) => {
 		await ctx.core.rateLimiter.charge(keyOf(ctx), window);
 	});
@@ -432,24 +552,38 @@ function paginate(items, page, perPage) {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.0-next.4";
+const version = "0.1.0-next.6";
 
 //#endregion
-exports.BuilderComponent = require_CustomId.BuilderComponent;
+exports.AutocompleteRoute = AutocompleteRoute;
+exports.BaseHandler = BaseHandler;
+exports.BuilderComponent = require_permissions.BuilderComponent;
+exports.ButtonRoute = ButtonRoute;
+exports.ContextMenuRoute = ContextMenuRoute;
 exports.Cooldown = Cooldown;
-exports.CustomId = require_CustomId.CustomId;
+exports.CustomId = require_permissions.CustomId;
 exports.DispatchContext = DispatchContext;
 exports.DmOnly = DmOnly;
 exports.Fault = Fault;
 exports.GuildOnly = GuildOnly;
-exports.Notice = require_CustomId.Notice;
+exports.ModalRoute = ModalRoute;
+exports.Notice = require_permissions.Notice;
 exports.OwnerOnly = OwnerOnly;
 exports.RegisterCommand = RegisterCommand;
-exports.RowComponent = require_CustomId.RowComponent;
+exports.RepliableHandler = RepliableHandler;
+exports.RequireBotPermissions = require_permissions.RequireBotPermissions;
+exports.RequirePermissions = require_permissions.RequirePermissions;
+exports.RequireRole = require_permissions.RequireRole;
+exports.RowComponent = require_permissions.RowComponent;
+exports.SelectMenuKind = require_permissions.SelectMenuKind;
+exports.SelectMenuRoute = SelectMenuRoute;
+exports.ShutdownPhase = require_phases.ShutdownPhase;
 exports.Silence = Silence;
+exports.SlashRoute = SlashRoute;
+exports.StartupPhase = require_phases.StartupPhase;
 exports.and = and;
-exports.defineEffectGate = defineEffectGate;
-exports.defineGate = defineGate;
+exports.defineEffectGate = require_permissions.defineEffectGate;
+exports.defineGate = require_permissions.defineGate;
 exports.or = or;
 exports.paginate = paginate;
 exports.version = version;