@seedcord/core 0.1.0-next.3 → 0.1.0-next.5

package/dist/{CustomId-DV7daU7r.cjs → permissions-DQL5ViZn.cjs}

@@ -1,8 +1,9 @@
+require("reflect-metadata");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
-let _seedcord_utils = require("@seedcord/utils");
-let _discordjs_builders = require("@discordjs/builders");
 let discord_api_types_v10 = require("discord-api-types/v10");
+let _discordjs_builders = require("@discordjs/builders");
+let _seedcord_utils = require("@seedcord/utils");
 
 //#region src/metadataKeys.ts
 let InteractionRoutes = /* @__PURE__ */ function(InteractionRoutes) {
@@ -38,6 +39,7 @@ const EventMetadataKey = Symbol("seedcord:event:metadata");
 const CommandMetadataKey = Symbol("seedcord:command:metadata");
 const GatedMetadataKey = Symbol("seedcord:gated:metadata");
 const SubscribeMetadataKey = Symbol("seedcord:subscribe:metadata");
+const WebhookUrlMetadataKey = Symbol("seedcord:webhookUrl:metadata");
 
 //#endregion
 //#region src/stops/Notice.ts
@@ -314,92 +316,6 @@ var NoticeCard = class extends BuilderComponent {
 	}
 };
 
-//#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 NotInGuild = class extends GateNotice {
-	constructor(message = "This can only be used in a server.") {
-		super(message);
-	}
-};
-var NotInDm = class extends GateNotice {
-	constructor(message = "This can only be used in a direct message.") {
-		super(message);
-	}
-};
-var OnCooldown = class extends GateNotice {
-	resetAt;
-	constructor(resetAt, message) {
-		super(message ?? `You are doing that too fast. Try again <t:${(0, _seedcord_utils.toEpochSeconds)(resetAt)}:R>.`);
-		this.resetAt = 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 = summaries;
-	}
-	render() {
-		return { components: [new NoticeCard(`You need any of:\n${this.summaries.map((summary) => `• ${summary}`).join("\n")}`).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/gates/catalog/options.ts
-function pickNotice(options, makeDefault) {
-	return options?.notice ?? makeDefault(options?.message);
-}
-
 //#endregion
 //#region src/customId/Errors.ts
 /**
@@ -815,6 +731,329 @@ function decodeFor(defs, wire) {
 	};
 }
 
+//#endregion
+//#region src/customId/routing.ts
+/**
+* The route decorators store a handler's customId definitions here so the component base can decode
+* against them at runtime.
+*
+* @internal
+*/
+const ComponentDefsKey = Symbol("seedcord:customId:componentDefs");
+/**
+* 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 _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.CustomIdHandlerRouteMissing, [handlerClass.name]);
+	return decodeFor(defs, wire);
+}
+
+//#endregion
+//#region src/decorators/interactionRoutes.ts
+/** The select menu kinds the select route decorators take. */
+let SelectMenuKind = /* @__PURE__ */ function(SelectMenuKind) {
+	SelectMenuKind["String"] = "string";
+	SelectMenuKind["User"] = "user";
+	SelectMenuKind["Role"] = "role";
+	SelectMenuKind["Channel"] = "channel";
+	SelectMenuKind["Mentionable"] = "mentionable";
+	return SelectMenuKind;
+}({});
+function areRoutes(routes) {
+	return Array.isArray(routes) && routes.every((route) => typeof route === "string");
+}
+function storeInteractionRoute(route, routes, constructor) {
+	const key = InteractionRouteKeys[route];
+	const saved = Reflect.getMetadata(key, constructor);
+	const existing = areRoutes(saved) ? saved : [];
+	const toStore = typeof routes === "string" ? [routes] : routes;
+	Reflect.defineMetadata(key, [...existing, ...toStore], constructor);
+	Reflect.defineMetadata(InteractionMetadataKey, true, constructor);
+}
+function storeComponentRoute(route, defs, constructor) {
+	storeInteractionRoute(route, defs.map((def) => def.prefix), constructor);
+	Reflect.defineMetadata(ComponentDefsKey, defs, constructor);
+}
+const SELECT_ROUTES = {
+	["string"]: "stringMenu",
+	["user"]: "userMenu",
+	["role"]: "roleMenu",
+	["channel"]: "channelMenu",
+	["mentionable"]: "mentionableMenu"
+};
+function selectMenuRouteOf(kind) {
+	return SELECT_ROUTES[kind];
+}
+function contextMenuRouteOf(kind) {
+	return kind === discord_api_types_v10.ApplicationCommandType.User ? "userContextMenu" : "messageContextMenu";
+}
+
+//#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, 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`
+*
+* @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 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}
+*
+* @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 NotInGuild = class extends GateNotice {
+	constructor(message = "This can only be used in a server.") {
+		super(message);
+	}
+};
+var NotInDm = class extends GateNotice {
+	constructor(message = "This can only be used in a direct message.") {
+		super(message);
+	}
+};
+var OnCooldown = class extends GateNotice {
+	resetAt;
+	constructor(resetAt, message) {
+		super(message ?? `You are doing that too fast. Try again <t:${(0, _seedcord_utils.toEpochSeconds)(resetAt)}:R>.`);
+		this.resetAt = 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 = summaries;
+	}
+	render() {
+		return { components: [new NoticeCard(`You need any of:\n${this.summaries.map((summary) => `• ${summary}`).join("\n")}`).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."));
+	}
+};
+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;
+	}
+	render() {
+		const bullets = this.missingPerms.map((perm) => `• ${perm}`).join("\n");
+		return { components: [new NoticeCard(`${this.customLead ?? `${this.subject === null ? "You are" : `${this.subject} is`} missing the following permission entries:`}\n\n${bullets}`).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/gates/catalog/options.ts
+function pickNotice(options, makeDefault) {
+	return options?.notice ?? makeDefault(options?.message);
+}
+
+//#endregion
+//#region src/gates/catalog/permissions.ts
+/** Permission bit to its prettified human-readable name, for the missing-permission refusal. */
+const PermissionNames = new Map(Object.entries(discord_api_types_v10.PermissionFlagsBits).map(([key, bit]) => [bit, (0, _seedcord_utils.prettify)(key)]));
+const ADMINISTRATOR = discord_api_types_v10.PermissionFlagsBits.Administrator;
+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 hasAll(held, scope) {
+	if ((held & ADMINISTRATOR) === ADMINISTRATOR) return true;
+	return scope.every((bit) => (held & bit) === bit);
+}
+function missingNames(held, scope) {
+	return scope.reduce((names, bit) => {
+		if ((held & bit) !== bit) names.push(PermissionNames.get(bit) ?? String(bit));
+		return names;
+	}, []);
+}
+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 `seedcord`
+*
+* @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
 Object.defineProperty(exports, 'BuilderComponent', {
   enumerable: true,
@@ -828,6 +1067,12 @@ Object.defineProperty(exports, 'CommandMetadataKey', {
     return CommandMetadataKey;
   }
 });
+Object.defineProperty(exports, 'ComponentDefsKey', {
+  enumerable: true,
+  get: function () {
+    return ComponentDefsKey;
+  }
+});
 Object.defineProperty(exports, 'CustomId', {
   enumerable: true,
   get: function () {
@@ -876,6 +1121,18 @@ Object.defineProperty(exports, 'MiddlewareMetadataKey', {
     return MiddlewareMetadataKey;
   }
 });
+Object.defineProperty(exports, 'MissingPermissions', {
+  enumerable: true,
+  get: function () {
+    return MissingPermissions;
+  }
+});
+Object.defineProperty(exports, 'MissingRole', {
+  enumerable: true,
+  get: function () {
+    return MissingRole;
+  }
+});
 Object.defineProperty(exports, 'NeedsAny', {
   enumerable: true,
   get: function () {
@@ -924,24 +1181,90 @@ Object.defineProperty(exports, 'OnCooldown', {
     return OnCooldown;
   }
 });
+Object.defineProperty(exports, 'PermissionNames', {
+  enumerable: true,
+  get: function () {
+    return PermissionNames;
+  }
+});
+Object.defineProperty(exports, 'RequireBotPermissions', {
+  enumerable: true,
+  get: function () {
+    return RequireBotPermissions;
+  }
+});
+Object.defineProperty(exports, 'RequirePermissions', {
+  enumerable: true,
+  get: function () {
+    return RequirePermissions;
+  }
+});
+Object.defineProperty(exports, 'RequireRole', {
+  enumerable: true,
+  get: function () {
+    return RequireRole;
+  }
+});
 Object.defineProperty(exports, 'RowComponent', {
   enumerable: true,
   get: function () {
     return RowComponent;
   }
 });
+Object.defineProperty(exports, 'SelectMenuKind', {
+  enumerable: true,
+  get: function () {
+    return SelectMenuKind;
+  }
+});
 Object.defineProperty(exports, 'SubscribeMetadataKey', {
   enumerable: true,
   get: function () {
     return SubscribeMetadataKey;
   }
 });
+Object.defineProperty(exports, 'WebhookUrlMetadataKey', {
+  enumerable: true,
+  get: function () {
+    return WebhookUrlMetadataKey;
+  }
+});
+Object.defineProperty(exports, 'areRoutes', {
+  enumerable: true,
+  get: function () {
+    return areRoutes;
+  }
+});
+Object.defineProperty(exports, 'contextMenuRouteOf', {
+  enumerable: true,
+  get: function () {
+    return contextMenuRouteOf;
+  }
+});
+Object.defineProperty(exports, 'decodeComponentRoute', {
+  enumerable: true,
+  get: function () {
+    return decodeComponentRoute;
+  }
+});
 Object.defineProperty(exports, 'decodeFor', {
   enumerable: true,
   get: function () {
     return decodeFor;
   }
 });
+Object.defineProperty(exports, 'defineEffectGate', {
+  enumerable: true,
+  get: function () {
+    return defineEffectGate;
+  }
+});
+Object.defineProperty(exports, 'defineGate', {
+  enumerable: true,
+  get: function () {
+    return defineGate;
+  }
+});
 Object.defineProperty(exports, 'discardCommits', {
   enumerable: true,
   get: function () {
@@ -984,10 +1307,28 @@ Object.defineProperty(exports, 'runCommits', {
     return runCommits;
   }
 });
+Object.defineProperty(exports, 'selectMenuRouteOf', {
+  enumerable: true,
+  get: function () {
+    return selectMenuRouteOf;
+  }
+});
 Object.defineProperty(exports, 'setBotColor', {
   enumerable: true,
   get: function () {
     return setBotColor;
   }
 });
-//# sourceMappingURL=CustomId-DV7daU7r.cjs.map
+Object.defineProperty(exports, 'storeComponentRoute', {
+  enumerable: true,
+  get: function () {
+    return storeComponentRoute;
+  }
+});
+Object.defineProperty(exports, 'storeInteractionRoute', {
+  enumerable: true,
+  get: function () {
+    return storeInteractionRoute;
+  }
+});
+//# sourceMappingURL=permissions-DQL5ViZn.cjs.map