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

package/dist/{CustomId-epJayEGO.mjs → permissions-RVCBhL2n.mjs}

@@ -1,8 +1,9 @@
+import "reflect-metadata";
 import { SeedcordErrorCode } from "@seedcord/errors";
 import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
-import { toEpochSeconds } from "@seedcord/utils";
+import { ApplicationCommandType, InteractionContextType, PermissionFlagsBits } from "discord-api-types/v10";
 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 } from "discord-api-types/v10";
+import { prettify, toEpochSeconds } from "@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:${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
 /**
@@ -816,5 +732,340 @@ function decodeFor(defs, wire) {
 }
 
 //#endregion
-export { EventMetadataKey as C, InteractionRoutes as D, InteractionRouteKeys as E, MiddlewareMetadataKey as O, CommandMetadataKey as S, InteractionMetadataKey as T, NoticeCard as _, discardCommits as a, setBotColor as b, runCheck as c, NeedsAny as d, NotAllowed as f, OnCooldown as g, NotOwner as h, pickNotice as i, SubscribeMetadataKey as k, runCommits as l, NotInGuild as m, decodeFor as n, markCommits as o, NotInDm as p, prefixOf as r, rollbackCommits as s, CustomId as t, GateNotice as u, BuilderComponent as v, GatedMetadataKey as w, Notice as x, RowComponent as y };
-//# sourceMappingURL=CustomId-epJayEGO.mjs.map
+//#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 SeedcordError(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");
+}
+/**
+* Every stored route kind and its route strings on a decorated constructor. The build's manifest
+* emitter reads the same pairs.
+*/
+function interactionRoutesOf(constructor) {
+	const pairs = [];
+	for (const route of Object.values(InteractionRoutes)) {
+		const meta = Reflect.getMetadata(InteractionRouteKeys[route], constructor);
+		if (areRoutes(meta)) pairs.push([route, meta]);
+	}
+	return pairs;
+}
+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 === 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:${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(PermissionFlagsBits).map(([key, bit]) => [bit, prettify(key)]));
+const ADMINISTRATOR = 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
+export { decodeComponentRoute as A, EventMetadataKey as B, areRoutes as C, storeComponentRoute as D, selectMenuRouteOf as E, BuilderComponent as F, MiddlewareMetadataKey as G, InteractionMetadataKey as H, RowComponent as I, SubscribeMetadataKey as K, setBotColor as L, decodeFor as M, prefixOf as N, storeInteractionRoute as O, NoticeCard as P, Notice as R, SelectMenuKind as S, interactionRoutesOf as T, InteractionRouteKeys as U, GatedMetadataKey as V, InteractionRoutes as W, NotInGuild as _, pickNotice as a, defineEffectGate as b, rollbackCommits as c, GateNotice as d, MissingPermissions as f, NotInDm as g, NotAllowed as h, RequireRole as i, CustomId as j, ComponentDefsKey as k, runCheck as l, NeedsAny as m, RequireBotPermissions as n, discardCommits as o, MissingRole as p, WebhookUrlMetadataKey as q, RequirePermissions as r, markCommits as s, PermissionNames as t, runCommits as u, NotOwner as v, contextMenuRouteOf as w, defineGate as x, OnCooldown as y, CommandMetadataKey as z };
+//# sourceMappingURL=permissions-RVCBhL2n.mjs.map