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

package/dist/index.mjs

@@ -1,9 +1,13 @@
-import { D as storeComponentRoute, E as selectMenuRouteOf, F as BuilderComponent, I as RowComponent, O as storeInteractionRoute, P as NoticeCard, R as Notice, S as SelectMenuKind, W as InteractionRoutes, _ as NotInGuild, a as pickNotice, b as defineEffectGate, c as rollbackCommits, g as NotInDm, h as NotAllowed, i as RequireRole, j as CustomId, l as runCheck, m as NeedsAny, n as RequireBotPermissions, r as RequirePermissions, s as markCommits, v as NotOwner, w as contextMenuRouteOf, x as defineGate, y as OnCooldown, z as CommandMetadataKey } from "./permissions-RVCBhL2n.mjs";
-import { n as StartupPhase, t as ShutdownPhase } from "./phases-BfpAG6w3.mjs";
+import { a as RowComponent, f as InteractionRoutes, i as BuilderComponent, s as CommandMetadataKey } from "./publishDefault-CldnxcT2.mjs";
+import { C as NotInDm, D as defineEffectGate, E as OnCooldown, F as storeInteractionRoute, G as ContextMenus, H as Notice, N as selectMenuRouteOf, O as defineGate, P as storeComponentRoute, R as CustomId, S as NotAllowed, T as NotOwner, V as NoticeCard, W as Commands, a as RequirePermissions, c as hasAll, d as pickNotice, h as runCheck, i as RequireBotPermissions, j as contextMenuRouteOf, k as SelectMenuKind, l as missingNames, m as rollbackCommits, n as pageCursor, o as RequireRole, p as markCommits, r as Silence, t as PAGE_MAX, u as presentNames, v as HasDangerousPermissions, w as NotInGuild, x as NeedsAny, y as MissingPermissions } from "./cursor-BvSH8tgw.mjs";
+import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
+import { a as WebhookLog, i as Subscribe, o as Subscriber, r as WebhookUrl, t as Bus } from "./subscribers-DuxdM2cS.mjs";
 import "reflect-metadata";
+import { ActionRowBuilder, ButtonBuilder, TextDisplayBuilder } from "@discordjs/builders";
+import { Logger } from "@seedcord/logger";
+import { ButtonStyle } from "discord-api-types/v10";
 import { SeedcordErrorCode } from "@seedcord/errors";
 import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
-import { Logger } from "@seedcord/logger";
 import { parseDuration } from "@seedcord/utils";
 
 //#region src/decorators/Command.ts
@@ -191,10 +195,10 @@ var BaseHandler = class {
 	event;
 	logger;
 	dispatch;
-	constructor(event, core, dispatch) {
+	constructor(event, core, dispatch, channel) {
 		this.core = core;
 		this.event = event;
-		this.logger = new Logger(this.constructor.name);
+		this.logger = new Logger(this.constructor.name, { channel });
 		this.dispatch = dispatch;
 	}
 };
@@ -214,7 +218,7 @@ var RepliableHandler = class extends BaseHandler {
 	sender;
 	routeId;
 	constructor(event, core, dispatch) {
-		super(event, core, dispatch);
+		super(event, core, dispatch, "interactions");
 		this.routeId = dispatch?.routeId ?? this.constructor.name;
 		this.sender = this.buildSender(event, core, this.routeId);
 	}
@@ -494,33 +498,112 @@ function Cooldown(duration, options) {
 }
 
 //#endregion
-//#region src/stops/Silence.ts
+//#region src/permissions/assert.ts
 /**
-* Throw to stop a handler with no reply and no report.
+* 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 framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
-* Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
-* leave the user with no reply for an interaction.
+* 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 { Silence } from '@seedcord/gateway';
+* 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]
+* });
+* ```
 *
-* // before any reply or defer, drop the interaction with no reply and no report
-* if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');
+* @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
+* });
 * ```
 */
-var Silence = class extends Error {
-	reason;
-	/**
-	* @param reason - Optional note written only to a debug log, never shown to the user or reported.
-	*/
-	constructor(reason) {
-		super(reason ?? "Silence");
-		this.reason = reason;
-		Error.captureStackTrace(this, this.constructor);
+function assertPermissions(check) {
+	const { subject, permissions, scope, inverse = false, missingNotice, dangerousNotice } = check;
+	if (inverse) {
+		const present = presentNames(permissions, scope);
+		if (present.length === 0) return;
+		throw new (dangerousNotice ?? HasDangerousPermissions)(void 0, subject, present);
 	}
-};
+	if (hasAll(permissions, scope)) return;
+	throw new (missingNotice ?? MissingPermissions)(void 0, subject, 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
@@ -548,11 +631,215 @@ 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 ButtonBuilder().setCustomId(this.cursor.encode({
+			page: Math.min(Math.max(0, target), PAGE_MAX),
+			slot: CONTROL_SLOT[key]
+		})).setStyle(cosmetics?.style ?? 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 SeedcordRangeError(SeedcordErrorCode.PaginationEmptyControls);
+		if (keys.length > MAX_BUTTONS_PER_ROW) throw new SeedcordRangeError(SeedcordErrorCode.PaginationTooManyControls, [keys.length]);
+		const seen = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			if (seen.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.PaginationDuplicateControls, [key]);
+			seen.add(key);
+		}
+		return new 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 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 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 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 = 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 SeedcordRangeError(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.6";
+const version = "0.1.0-next.8";
 
 //#endregion
-export { AutocompleteRoute, BaseHandler, BuilderComponent, ButtonRoute, ContextMenuRoute, Cooldown, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, ModalRoute, Notice, OwnerOnly, RegisterCommand, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, RowComponent, SelectMenuKind, SelectMenuRoute, ShutdownPhase, Silence, SlashRoute, StartupPhase, and, defineEffectGate, defineGate, or, paginate, version };
+export { ArraySource, AutocompleteRoute, BaseHandler, BuilderComponent, Bus, ButtonRoute, Commands, ContextMenuRoute, ContextMenus, Cooldown, CursorSource, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, ModalRoute, Notice, OwnerOnly, PaginatorBase, RegisterCommand, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, RowComponent, SelectMenuKind, SelectMenuRoute, ShutdownPhase, Silence, SlashRoute, StartupPhase, Subscribe, Subscriber, WebhookLog, WebhookUrl, and, assertPermissions, defineEffectGate, defineGate, mergeRoles, or, paginate, version };
 //# sourceMappingURL=index.mjs.map