@seedcord/core 0.1.0-next.7 → 0.1.0-next.8

package/dist/index.cjs

@@ -1,12 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_publishDefault = require('./publishDefault-l0NQ-SHo.cjs');
-const require_Silence = require('./Silence-DiP95iwD.cjs');
-const require_phases = require('./phases-C_BGNyVo.cjs');
-const require_subscribers = require('./subscribers-B1G6_LlK.cjs');
+const require_publishDefault = require('./publishDefault-CVlwYUS5.cjs');
+const require_cursor = require('./cursor-BMkFAwO2.cjs');
+const require_phases = require('./phases-DcuDHoQl.cjs');
+const require_subscribers = require('./subscribers-BSJoyKNN.cjs');
 require("reflect-metadata");
+let _discordjs_builders = require("@discordjs/builders");
+let _seedcord_logger = require("@seedcord/logger");
+let discord_api_types_v10 = require("discord-api-types/v10");
 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
@@ -51,7 +53,7 @@ function RegisterCommand(scope, guilds = []) {
 */
 function SlashRoute(...routes) {
 	return function(constructor) {
-		require_Silence.storeInteractionRoute("slash", routes, constructor);
+		require_cursor.storeInteractionRoute("slash", routes, constructor);
 	};
 }
 /**
@@ -76,7 +78,7 @@ function SlashRoute(...routes) {
 */
 function AutocompleteRoute(...routes) {
 	return function(constructor) {
-		require_Silence.storeInteractionRoute("autocomplete", routes, constructor);
+		require_cursor.storeInteractionRoute("autocomplete", routes, constructor);
 	};
 }
 /**
@@ -102,7 +104,7 @@ function AutocompleteRoute(...routes) {
 */
 function ContextMenuRoute(kind, ...names) {
 	return function(constructor) {
-		require_Silence.storeInteractionRoute(require_Silence.contextMenuRouteOf(kind), names, constructor);
+		require_cursor.storeInteractionRoute(require_cursor.contextMenuRouteOf(kind), names, constructor);
 	};
 }
 /**
@@ -118,7 +120,7 @@ function ContextMenuRoute(kind, ...names) {
 */
 function ButtonRoute(...defs) {
 	return function(constructor) {
-		require_Silence.storeComponentRoute("button", defs, constructor);
+		require_cursor.storeComponentRoute("button", defs, constructor);
 	};
 }
 /**
@@ -134,7 +136,7 @@ function ButtonRoute(...defs) {
 */
 function ModalRoute(...defs) {
 	return function(constructor) {
-		require_Silence.storeComponentRoute("modal", defs, constructor);
+		require_cursor.storeComponentRoute("modal", defs, constructor);
 	};
 }
 /**
@@ -155,7 +157,7 @@ function ModalRoute(...defs) {
 */
 function SelectMenuRoute(type, ...defs) {
 	return function(constructor) {
-		require_Silence.storeComponentRoute(require_Silence.selectMenuRouteOf(type), defs, constructor);
+		require_cursor.storeComponentRoute(require_cursor.selectMenuRouteOf(type), defs, constructor);
 	};
 }
 
@@ -280,21 +282,21 @@ var RepliableHandler = class extends BaseHandler {
 * }
 * ```
 */
-var Fault = class extends require_Silence.Notice {
+var Fault = class extends require_cursor.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_Silence.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_cursor.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 require_Silence.defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
-		for (const gate of gates) await require_Silence.runCheck(gate, ctx);
+	return require_cursor.defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
+		for (const gate of gates) await require_cursor.runCheck(gate, ctx);
 	});
 }
 function isOrOptions(arg) {
@@ -304,17 +306,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 require_Silence.defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
+	return require_cursor.defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
 		const summaries = [];
 		let everyArmHasSummary = true;
 		for (const gate of gates) {
-			const mark = require_Silence.markCommits(ctx);
+			const mark = require_cursor.markCommits(ctx);
 			try {
-				await require_Silence.runCheck(gate, ctx);
+				await require_cursor.runCheck(gate, ctx);
 				return;
 			} catch (error) {
-				if (error instanceof require_Silence.Notice && !(error instanceof Fault) && !error.report) {
-					require_Silence.rollbackCommits(ctx, mark);
+				if (error instanceof require_cursor.Notice && !(error instanceof Fault) && !error.report) {
+					require_cursor.rollbackCommits(ctx, mark);
 					if (error.summary === void 0) everyArmHasSummary = false;
 					else summaries.push(error.summary);
 					continue;
@@ -323,8 +325,8 @@ function or(...args) {
 			}
 		}
 		if (options) throw typeof options.fail === "function" ? options.fail(ctx) : options.fail;
-		if (everyArmHasSummary && summaries.length > 0) throw new require_Silence.NeedsAny(summaries);
-		throw new require_Silence.NotAllowed();
+		if (everyArmHasSummary && summaries.length > 0) throw new require_cursor.NeedsAny(summaries);
+		throw new require_cursor.NotAllowed();
 	});
 }
 
@@ -357,10 +359,10 @@ function or(...args) {
 * ```
 */
 function OwnerOnly(options) {
-	return require_Silence.defineGate("OwnerOnly", (ctx) => {
+	return require_cursor.defineGate("OwnerOnly", (ctx) => {
 		const owners = ctx.core.config.ownerIds ?? [];
 		if (ctx.userId !== null && owners.includes(ctx.userId)) return;
-		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotOwner(message));
+		throw require_cursor.pickNotice(options, (message) => new require_cursor.NotOwner(message));
 	});
 }
 /**
@@ -386,9 +388,9 @@ function OwnerOnly(options) {
 * ```
 */
 function GuildOnly(options) {
-	return require_Silence.defineGate("GuildOnly", (ctx) => {
+	return require_cursor.defineGate("GuildOnly", (ctx) => {
 		if (ctx.guildId) return;
-		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotInGuild(message));
+		throw require_cursor.pickNotice(options, (message) => new require_cursor.NotInGuild(message));
 	});
 }
 /**
@@ -412,9 +414,9 @@ function GuildOnly(options) {
 * ```
 */
 function DmOnly(options) {
-	return require_Silence.defineGate("DmOnly", (ctx) => {
+	return require_cursor.defineGate("DmOnly", (ctx) => {
 		if (!ctx.guildId) return;
-		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotInDm(message));
+		throw require_cursor.pickNotice(options, (message) => new require_cursor.NotInDm(message));
 	});
 }
 
@@ -486,16 +488,124 @@ 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 require_Silence.defineEffectGate("Cooldown", async (ctx) => {
+	return require_cursor.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_Silence.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
+		throw new require_cursor.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
 	}, async (ctx) => {
 		await ctx.core.rateLimiter.charge(keyOf(ctx), window);
 	});
 }
 
+//#endregion
+//#region src/permissions/assert.ts
+/**
+* Refuses when the subject is missing a permission in `scope`, or with `inverse` when it holds one.
+* The Administrator bit passes any scope, and on the inverse arm it reports every bit in `scope`.
+*
+* The caller computes `permissions`, gateway off a discord.js role, member, or channel, and HTTP off the
+* bitfield the interaction payload carries.
+*
+* @throws A {@link Notice} listing the missing or present permissions.
+*
+* @example
+* ```ts
+* import { assertPermissions } from '@seedcord/core';
+* import { PermissionFlagsBits } from 'discord-api-types/v10';
+*
+* // gateway, the bits come off a discord.js member
+* assertPermissions({
+*     subject: `<@${member.id}>`,
+*     permissions: member.permissions.bitfield,
+*     scope: [PermissionFlagsBits.BanMembers]
+* });
+* ```
+*
+* @example
+* ```ts
+* // HTTP, the payload carries the member's bits as a string
+* assertPermissions({
+*     subject: `<@${this.event.member.user.id}>`,
+*     permissions: BigInt(this.event.member.permissions),
+*     scope: [PermissionFlagsBits.ManageMessages]
+* });
+* ```
+*
+* @example
+* ```ts
+* // inverse, refuse a role that carries Administrator
+* assertPermissions({
+*     subject: `<@&${role.id}>`,
+*     permissions: role.permissions.bitfield,
+*     scope: [PermissionFlagsBits.Administrator],
+*     inverse: true
+* });
+* ```
+*
+* @example
+* ```ts
+* import { Notice } from '@seedcord/core';
+*
+* // a replacement notice takes the same three arguments the default one does
+* class CannotBan extends Notice {
+*     public constructor(
+*         message: string | undefined,
+*         private readonly subject: string,
+*         private readonly missing: readonly string[]
+*     ) {
+*         super(message ?? 'You cannot ban here.');
+*     }
+*
+*     public render(): ReplyResponse {
+*         return { components: [new BanDenied(this.subject, this.missing).component] };
+*     }
+* }
+*
+* assertPermissions({
+*     subject: `<@${member.id}>`,
+*     permissions: member.permissions.bitfield,
+*     scope: [PermissionFlagsBits.BanMembers],
+*     missingNotice: CannotBan
+* });
+* ```
+*/
+function assertPermissions(check) {
+	const { subject, permissions, scope, inverse = false, missingNotice, dangerousNotice } = check;
+	if (inverse) {
+		const present = require_cursor.presentNames(permissions, scope);
+		if (present.length === 0) return;
+		throw new (dangerousNotice ?? require_cursor.HasDangerousPermissions)(void 0, subject, present);
+	}
+	if (require_cursor.hasAll(permissions, scope)) return;
+	throw new (missingNotice ?? require_cursor.MissingPermissions)(void 0, subject, require_cursor.missingNames(permissions, scope));
+}
+
+//#endregion
+//#region src/permissions/mergeRoles.ts
+/**
+* The role ids a member holds after adding and removing the given sets. Removals win over additions.
+*
+* This does not write the roles. Apply the result with `member.roles.set()` on gateway, or PATCH the member over HTTP.
+*
+* @param current - The role ids the member holds.
+* @param add - The role ids to add.
+* @param remove - The role ids to remove.
+* @returns The merged role ids.
+*
+* @example
+* ```ts
+* import { mergeRoles } from '@seedcord/core';
+*
+* // gateway
+* const ids = mergeRoles(member.roles.cache.map((role) => role.id), ['123'], ['456']);
+* await member.roles.set(ids);
+* ```
+*/
+function mergeRoles(current, add, remove) {
+	return [...new Set(current).union(new Set(add)).difference(new Set(remove))];
+}
+
 //#endregion
 //#region src/pagination/paginate.ts
 /**
@@ -522,37 +632,246 @@ function paginate(items, page, perPage) {
 	};
 }
 
+//#endregion
+//#region src/pagination/controls.ts
+const DEFAULT_LABEL = {
+	first: "First",
+	prev: "Prev",
+	indicator: "",
+	next: "Next",
+	last: "Last"
+};
+const CONTROL_SLOT = {
+	first: 0,
+	prev: 1,
+	indicator: 2,
+	next: 3,
+	last: 4
+};
+const MAX_BUTTONS_PER_ROW = 5;
+var Controls = class {
+	cursor;
+	view;
+	constructor(cursor, view) {
+		this.cursor = cursor;
+		this.view = view;
+	}
+	button(key, cosmetics) {
+		const { target, disabled } = this.navState(key);
+		const defaultLabel = key === "indicator" ? this.indicatorText() : DEFAULT_LABEL[key];
+		const label = cosmetics?.label ?? (key === "indicator" || !cosmetics?.emoji ? defaultLabel : void 0);
+		const button = new _discordjs_builders.ButtonBuilder().setCustomId(this.cursor.encode({
+			page: Math.min(Math.max(0, target), require_cursor.PAGE_MAX),
+			slot: CONTROL_SLOT[key]
+		})).setStyle(cosmetics?.style ?? discord_api_types_v10.ButtonStyle.Secondary).setDisabled(disabled);
+		if (label !== void 0) button.setLabel(label);
+		if (cosmetics?.emoji) button.setEmoji(cosmetics.emoji);
+		return button;
+	}
+	navState(key) {
+		const { page, totalPages, hasPrev, hasNext } = this.view;
+		const knownTotal = totalPages !== void 0;
+		return {
+			target: {
+				first: 0,
+				prev: page - 1,
+				indicator: page,
+				next: page + 1,
+				last: knownTotal ? totalPages - 1 : page
+			}[key],
+			disabled: {
+				first: !hasPrev,
+				prev: !hasPrev,
+				indicator: true,
+				next: !hasNext || page + 1 > 1e6,
+				last: !hasNext || !knownTotal || totalPages - 1 > 1e6
+			}[key]
+		};
+	}
+	row(...keys) {
+		if (keys.length === 0) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationEmptyControls);
+		if (keys.length > MAX_BUTTONS_PER_ROW) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationTooManyControls, [keys.length]);
+		const seen = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			if (seen.has(key)) throw new _seedcord_errors_internal.SeedcordTypeError(_seedcord_errors.SeedcordErrorCode.PaginationDuplicateControls, [key]);
+			seen.add(key);
+		}
+		return new _discordjs_builders.ActionRowBuilder().addComponents(keys.map((key) => this.button(key)));
+	}
+	indicatorText() {
+		const { page, totalPages } = this.view;
+		return totalPages === void 0 ? `Page ${page + 1}` : `Page ${page + 1} of ${totalPages}`;
+	}
+};
+
+//#endregion
+//#region src/pagination/render.ts
+var PageContainer = class extends require_publishDefault.BuilderComponent {
+	constructor(view, renderItem, controlRow) {
+		super("container");
+		const base = view.page * view.perPage;
+		let lines = [];
+		const flush = () => {
+			if (lines.length === 0) return;
+			this.instance.addTextDisplayComponents(new _discordjs_builders.TextDisplayBuilder().setContent(lines.join("\n")));
+			lines = [];
+		};
+		view.items.forEach((item, offset) => {
+			const rendered = renderItem(item, base + offset);
+			if (typeof rendered === "string") {
+				lines.push(rendered);
+				return;
+			}
+			flush();
+			this.instance.addSectionComponents(rendered.component);
+		});
+		flush();
+		this.instance.addActionRowComponents(controlRow);
+	}
+};
+function toReplyResponse(renderable) {
+	if (typeof renderable === "string") return { components: [new _discordjs_builders.TextDisplayBuilder().setContent(renderable)] };
+	if (Array.isArray(renderable)) return { components: renderable };
+	return renderable;
+}
+const ARRAY_KEYS = [
+	"first",
+	"prev",
+	"indicator",
+	"next",
+	"last"
+];
+const CURSOR_KEYS = [
+	"prev",
+	"indicator",
+	"next"
+];
+/**
+* A `render` override builds the whole tree, otherwise the default container lists the items and appends
+* the controls (all five for a known total, prev/indicator/next for a cursor source).
+*/
+function renderPage(view, cursor, config) {
+	const controls = new Controls(cursor, view);
+	if (config.render) return toReplyResponse(config.render(view, controls));
+	return { components: [new PageContainer(view, config.renderItem ?? String, controls.row(...view.totalPages === void 0 ? CURSOR_KEYS : ARRAY_KEYS)).component] };
+}
+
+//#endregion
+//#region src/pagination/PaginatorBase.ts
+/**
+* Holds a paginator's cursor and renders one page. Each transport extends this to add the nav handler and
+* the method that sends the first page.
+*
+* @typeParam Item - The item type, inferred from the source.
+* @typeParam Prefix - The route prefix, inferred from `config.prefix`.
+* @typeParam Ctx - The transport's page context.
+*/
+var PaginatorBase = class {
+	/** The page cursor, pass it to your `@ButtonRoute`. */
+	cursor;
+	config;
+	constructor(config) {
+		this.cursor = require_cursor.pageCursor(config.prefix);
+		this.config = config;
+	}
+	/** Render a page as a {@link ReplyResponse}. To post it elsewhere, add `flags: MessageFlags.IsComponentsV2`. */
+	async page(ctx, n) {
+		return renderPage(await this.config.source.page(ctx, n), this.cursor, this.config);
+	}
+};
+
+//#endregion
+//#region src/pagination/sources.ts
+const DEFAULT_PER_PAGE = 10;
+function perPageOf(opts) {
+	const perPage = opts?.perPage ?? DEFAULT_PER_PAGE;
+	if (!Number.isSafeInteger(perPage) || perPage <= 0) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);
+	return perPage;
+}
+/**
+* A source for a bounded list you can load whole. It loads the full list on every click, then slices the
+* page via {@link paginate}, so the real total is known (a real last button, "Page X of Y"). Cache inside
+* your loader if the load is expensive.
+*
+* @typeParam Item - The item type, inferred from the loader's return.
+* @typeParam Ctx - The transport's page context. Each transport exports a subclass that fixes it.
+*/
+var ArraySource = class {
+	load;
+	perPage;
+	constructor(load, opts) {
+		this.load = load;
+		this.perPage = perPageOf(opts);
+	}
+	async page(ctx, n) {
+		return paginate(await this.load(ctx), n, this.perPage);
+	}
+};
+/**
+* A source for a large or unknown-length set you fetch one page at a time (SQL LIMIT/OFFSET, a paged API).
+* The fetcher receives the page index and the page size and reports whether a next page exists. A cursor
+* source has no cheap total, so `totalPages` is undefined, the last button is omitted, and the indicator
+* reads "Page X".
+*
+* @typeParam Item - The item type, inferred from the fetcher's slice.
+* @typeParam Ctx - The transport's page context. Each transport exports a subclass that fixes it.
+*/
+var CursorSource = class {
+	fetch;
+	perPage;
+	constructor(fetch, opts) {
+		this.fetch = fetch;
+		this.perPage = perPageOf(opts);
+	}
+	async page(ctx, n) {
+		const page = Math.max(0, Math.trunc(n));
+		const { items, hasNext } = await this.fetch(ctx, page, this.perPage);
+		return {
+			items: [...items],
+			page,
+			perPage: this.perPage,
+			hasPrev: page > 0,
+			hasNext
+		};
+	}
+};
+
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.0-next.7";
+const version = "0.1.0-next.8";
 
 //#endregion
+exports.ArraySource = ArraySource;
 exports.AutocompleteRoute = AutocompleteRoute;
 exports.BaseHandler = BaseHandler;
 exports.BuilderComponent = require_publishDefault.BuilderComponent;
 exports.Bus = require_subscribers.Bus;
 exports.ButtonRoute = ButtonRoute;
+exports.Commands = require_cursor.Commands;
 exports.ContextMenuRoute = ContextMenuRoute;
+exports.ContextMenus = require_cursor.ContextMenus;
 exports.Cooldown = Cooldown;
-exports.CustomId = require_Silence.CustomId;
+exports.CursorSource = CursorSource;
+exports.CustomId = require_cursor.CustomId;
 exports.DispatchContext = DispatchContext;
 exports.DmOnly = DmOnly;
 exports.Fault = Fault;
 exports.GuildOnly = GuildOnly;
 exports.ModalRoute = ModalRoute;
-exports.Notice = require_Silence.Notice;
+exports.Notice = require_cursor.Notice;
 exports.OwnerOnly = OwnerOnly;
+exports.PaginatorBase = PaginatorBase;
 exports.RegisterCommand = RegisterCommand;
 exports.RepliableHandler = RepliableHandler;
-exports.RequireBotPermissions = require_Silence.RequireBotPermissions;
-exports.RequirePermissions = require_Silence.RequirePermissions;
-exports.RequireRole = require_Silence.RequireRole;
+exports.RequireBotPermissions = require_cursor.RequireBotPermissions;
+exports.RequirePermissions = require_cursor.RequirePermissions;
+exports.RequireRole = require_cursor.RequireRole;
 exports.RowComponent = require_publishDefault.RowComponent;
-exports.SelectMenuKind = require_Silence.SelectMenuKind;
+exports.SelectMenuKind = require_cursor.SelectMenuKind;
 exports.SelectMenuRoute = SelectMenuRoute;
 exports.ShutdownPhase = require_phases.ShutdownPhase;
-exports.Silence = require_Silence.Silence;
+exports.Silence = require_cursor.Silence;
 exports.SlashRoute = SlashRoute;
 exports.StartupPhase = require_phases.StartupPhase;
 exports.Subscribe = require_subscribers.Subscribe;
@@ -560,8 +879,10 @@ exports.Subscriber = require_subscribers.Subscriber;
 exports.WebhookLog = require_subscribers.WebhookLog;
 exports.WebhookUrl = require_subscribers.WebhookUrl;
 exports.and = and;
-exports.defineEffectGate = require_Silence.defineEffectGate;
-exports.defineGate = require_Silence.defineGate;
+exports.assertPermissions = assertPermissions;
+exports.defineEffectGate = require_cursor.defineEffectGate;
+exports.defineGate = require_cursor.defineGate;
+exports.mergeRoles = mergeRoles;
 exports.or = or;
 exports.paginate = paginate;
 exports.version = version;