@seedcord/core 0.3.1 → 0.4.1

package/dist/index.mjs

@@ -1,15 +1,50 @@
-import { a as WebhookUrl, b as InteractionRoutes, c as Subscriber, f as BuilderComponent, h as CommandMetadataKey, o as Subscribe, p as RowComponent, s as WebhookLog, t as Bus } from "./Bus-BvF4VShN.mjs";
-import { n as Commands, r as ContextMenus } from "./subscribers-wnMyNYZd.mjs";
-import { C as NotInDm, D as defineEffectGate, E as OnCooldown, F as storeInteractionRoute, H as Notice, N as selectMenuRouteOf, O as defineGate, P as storeComponentRoute, R as CustomId, S as NotAllowed, T as NotOwner, V as NoticeCard, 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-CuoA9cRh.mjs";
+import { A as translateSerializationError, C as NotInDm, D as defineEffectGate, E as OnCooldown, F as checkAckLegality, H as storeComponentRoute, I as sendTarget, K as NoticeCard, L as SelectMenuKind, M as publishResponse, O as defineGate, P as AckTrace, S as NotAllowed, T as NotOwner, U as storeInteractionRoute, V as selectMenuRouteOf, a as RequirePermissions, c as hasAll, d as pickNotice, h as runCheck, i as RequireBotPermissions, j as attemptWrite, k as serializeReply, l as missingNames, m as rollbackCommits, n as pageCursor, o as RequireRole, p as markCommits, q as Notice, r as Silence, t as PAGE_MAX, u as presentNames, v as HasDangerousPermissions, w as NotInGuild, x as NeedsAny, y as MissingPermissions, z as contextMenuRouteOf } from "./cursor-CaT051ii.mjs";
+import { A as RowComponent, d as WebhookLog, f as Subscriber, g as CommandMetadataKey, k as BuilderComponent, l as WebhookUrl, t as Bus, u as Subscribe, x as InteractionRoutes } from "./Bus-yJGE6Fs2.mjs";
+import { n as Commands, r as ContextMenus } from "./subscribers-DVa-Pr45.mjs";
 import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
 import "reflect-metadata";
+import { CustomId, setCustomIdErrors, setCustomIdErrors as setCustomIdErrors$1 } from "@seedcord/custom-id";
 import { ActionRowBuilder, ButtonBuilder, TextDisplayBuilder } from "@discordjs/builders";
-import { SeedcordErrorCode } from "@seedcord/errors";
-import { Logger } from "@seedcord/logger";
 import { ApplicationCommandType, 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/customId/Errors.ts
+/**
+* Thrown when a customId was minted by an older version of its shape.
+*
+* This is normal after the shape changes.
+*/
+var StaleCustomId = class extends Notice {
+	constructor(prefix) {
+		super(`Stale customId for "${prefix}".`);
+	}
+	render() {
+		return { components: [new NoticeCard("This button or menu is from an older version. Please run the command again.", "Outdated").component] };
+	}
+};
+/**
+* Thrown when a customId wire is corrupt or tampered with and cannot be trusted.
+*
+* It reports because this is an odd case that should not happen.
+*/
+var InvalidCustomId = class extends Notice {
+	constructor(detail) {
+		super(`Invalid customId. ${detail}`);
+		this.report = true;
+	}
+	render() {
+		return { components: [new NoticeCard("Something went wrong. Please try again.").component] };
+	}
+};
+setCustomIdErrors$1({
+	stale: (prefix) => new StaleCustomId(prefix),
+	invalid: (detail) => new InvalidCustomId(detail)
+});
+
+//#endregion
 //#region src/decorators/Command.ts
 function RegisterCommand(scope, guilds = []) {
 	return (ctor) => {
@@ -19,8 +54,8 @@ function RegisterCommand(scope, guilds = []) {
 			existingMeta.scope,
 			scope
 		]);
-		if (scope === "global" && guilds.length > 0) throw new SeedcordError(SeedcordErrorCode.DecoratorCommandGlobalWithGuilds);
-		if (scope === "guild" && (!Array.isArray(guilds) || guilds.length === 0)) throw new SeedcordError(SeedcordErrorCode.DecoratorCommandGuildWithoutGuilds);
+		if (scope === "global" && guilds.length > 0) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorCommandGlobalWithGuilds);
+		if (scope === "guild" && (!Array.isArray(guilds) || guilds.length === 0)) throw new SeedcordTypeError(SeedcordErrorCode.DecoratorCommandGuildWithoutGuilds);
 		const meta = scope === "global" ? { scope } : {
 			scope,
 			guilds
@@ -235,6 +270,7 @@ var BaseHandler = class {
 * @typeParam TSender - The transport's reply sender
 */
 var RepliableHandler = class extends BaseHandler {
+	/** The reply surface for this interaction. Pass the handler to reply from outside its class. */
 	sender;
 	routeId;
 	constructor(event, core, dispatch) {
@@ -242,10 +278,6 @@ var RepliableHandler = class extends BaseHandler {
 		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);
@@ -272,6 +304,172 @@ var RepliableHandler = class extends BaseHandler {
 	}
 };
 
+//#endregion
+//#region src/reply/BaseReplySender.ts
+/**
+* Tracks acknowledgement state and throws a translated `SeedcordError` on an illegal verb before any
+* transport call. Every verb runs the legality check, calls the transport's wire writer, then updates
+* the state and the ack trace. Each transport binds `TMessage` to its own created-message type and
+* supplies the writers.
+*/
+var BaseReplySender = class {
+	routeId;
+	telemetry;
+	state;
+	sent = /* @__PURE__ */ new Set();
+	ackedBy;
+	constructor(routeId, telemetry, initialState = "unacked") {
+		this.routeId = routeId;
+		this.telemetry = telemetry;
+		this.state = initialState;
+	}
+	report(method, startedAt, messageId) {
+		publishResponse(this.telemetry, {
+			routeId: this.routeId,
+			method,
+			startedAt,
+			outcome: "sent",
+			messageId
+		});
+	}
+	async attempt(method, startedAt, write) {
+		return await attemptWrite(this.telemetry, this.routeId, method, startedAt, write);
+	}
+	async reply(response, opts) {
+		this.checkLegality("reply");
+		const startedAt = performance.now();
+		const created = await this.attempt("reply", startedAt, () => this.writeReply(response, opts));
+		this.transition("reply", "replied");
+		const message = this.remember(this.requireMessage(created, "reply"));
+		this.report("reply", startedAt, message.id);
+		return message;
+	}
+	async defer(opts) {
+		this.checkLegality("defer");
+		const startedAt = performance.now();
+		await this.attempt("defer", startedAt, () => this.writeDefer(opts));
+		this.transition("defer", "deferred-reply");
+		this.report("defer", startedAt, null);
+	}
+	async deferUpdate() {
+		this.checkLegality("deferUpdate");
+		const startedAt = performance.now();
+		await this.attempt("deferUpdate", startedAt, () => this.writeDeferUpdate());
+		this.transition("deferUpdate", "deferred-update");
+		this.report("deferUpdate", startedAt, null);
+	}
+	/**
+	* After a deferUpdate the state stays deferred-update. Calling this again rewrites. The returned message
+	* is the source message, editable only through a bare `update` or `edit`. A targeted `edit` or `delete`
+	* of it throws the foreign-target error.
+	*/
+	async update(response) {
+		this.checkLegality("update");
+		const startedAt = performance.now();
+		if (this.state === "deferred-update") {
+			const edited = await this.attempt("update", startedAt, () => this.editOriginal(response));
+			this.report("update", startedAt, edited.id);
+			return edited;
+		}
+		const created = await this.attempt("update", startedAt, () => this.writeUpdate(response));
+		this.transition("update", "replied");
+		const message = this.remember(this.requireMessage(created, "update"));
+		this.report("update", startedAt, message.id);
+		return message;
+	}
+	async followUp(response, opts) {
+		this.checkLegality("followUp");
+		const startedAt = performance.now();
+		const created = await this.attempt("followUp", startedAt, () => this.writeFollowUp(response, opts));
+		const message = this.remember(created);
+		this.report("followUp", startedAt, message.id);
+		return message;
+	}
+	async edit(targetOrResponse, maybeResponse) {
+		this.checkLegality("edit");
+		const startedAt = performance.now();
+		if (maybeResponse === void 0) {
+			const edited = await this.attempt("edit", startedAt, () => this.editOriginal(targetOrResponse));
+			this.report("edit", startedAt, edited.id);
+			return edited;
+		}
+		const target = targetOrResponse;
+		if (!this.sent.has(target.id)) throw new SeedcordError(SeedcordErrorCode.ReplyForeignEditTarget, [
+			"edit",
+			target.id,
+			this.routeId
+		]);
+		const written = await this.attempt("edit", startedAt, () => this.writeEditTarget(target.id, maybeResponse));
+		const message = this.remember(written);
+		this.report("edit", startedAt, message.id);
+		return message;
+	}
+	async delete(target) {
+		this.checkLegality("delete");
+		const startedAt = performance.now();
+		if (target === void 0) {
+			await this.attempt("delete", startedAt, () => this.writeDeleteOriginal());
+			this.report("delete", startedAt, null);
+			return;
+		}
+		if (!this.sent.has(target.id)) throw new SeedcordError(SeedcordErrorCode.ReplyForeignEditTarget, [
+			"delete",
+			target.id,
+			this.routeId
+		]);
+		await this.attempt("delete", startedAt, () => this.writeDeleteTarget(target.id));
+		this.sent.delete(target.id);
+		this.report("delete", startedAt, null);
+	}
+	/** Routes to the verb the current ack state permits. Every state has a route, so the illegal-ack throw is unreachable. */
+	async send(response, opts) {
+		const target = sendTarget(this.state);
+		if (target === "reply") return await this.reply(response, opts);
+		if (target === "edit") return await this.edit(response);
+		return await this.followUp(response, opts);
+	}
+	/** Must be the initial response. */
+	async showModal(modal) {
+		this.checkLegality("showModal");
+		this.guardModalSource();
+		let data;
+		try {
+			data = modal.toJSON();
+		} catch (error) {
+			const name = modal.constructor?.name;
+			throw translateSerializationError(error, !name || name === "Object" ? "modal" : name, 0, this.routeId);
+		}
+		const startedAt = performance.now();
+		await this.attempt("showModal", startedAt, () => this.writeModal(data));
+		this.transition("showModal", "replied");
+		this.report("showModal", startedAt, null);
+	}
+	serialize(response) {
+		return serializeReply(response, this.routeId);
+	}
+	remember(created) {
+		this.sent.add(created.id);
+		return created;
+	}
+	requireMessage(created, method) {
+		if (!created) throw new SeedcordError(SeedcordErrorCode.ReplyCallbackMissingMessage, [method, this.routeId]);
+		return created;
+	}
+	async editOriginal(response) {
+		const edited = await this.writeEditOriginal(response);
+		if (this.state !== "deferred-update") this.remember(edited);
+		return edited;
+	}
+	checkLegality(method) {
+		checkAckLegality(method, this.state, this.routeId, this.ackedBy);
+	}
+	transition(method, state) {
+		this.state = state;
+		this.ackedBy = new AckTrace(method);
+	}
+	guardModalSource() {}
+};
+
 //#endregion
 //#region src/stops/Fault.ts
 /**
@@ -314,8 +512,12 @@ var Fault = class extends Notice {
 
 //#endregion
 //#region src/gates/combinators.ts
+const ALREADY_JOINED = / [&|] /;
+function joinNames(gates, separator) {
+	return gates.map((gate) => ALREADY_JOINED.test(gate.name) ? `(${gate.name})` : gate.name).join(separator);
+}
 function and(...gates) {
-	return defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
+	return defineGate(joinNames(gates, " & "), async (ctx) => {
 		for (const gate of gates) await runCheck(gate, ctx);
 	});
 }
@@ -326,7 +528,7 @@ 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 defineGate(joinNames(gates, " | "), async (ctx) => {
 		const summaries = [];
 		let everyArmHasSummary = true;
 		for (const gate of gates) {
@@ -660,7 +862,7 @@ var ResolvedEmoji = class {
 function paginate(items, page, perPage) {
 	if (!Number.isSafeInteger(perPage) || perPage <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);
 	const totalPages = Math.max(1, Math.ceil(items.length / perPage));
-	const clamped = Math.min(Math.max(Math.trunc(page), 0), totalPages - 1);
+	const clamped = Math.min(Math.max(Number.isNaN(page) ? 0 : Math.trunc(page), 0), totalPages - 1);
 	const start = clamped * perPage;
 	return {
 		items: items.slice(start, start + perPage),
@@ -812,8 +1014,8 @@ var PaginatorBase = class {
 		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) {
+	/** Build one page as a {@link ReplyResponse}. Each transport wraps this in a `page()` taking its handler. */
+	async buildPage(ctx, n) {
 		const view = await this.config.source.page(ctx, n);
 		return renderPage(view, this.cursor, this.config);
 	}
@@ -835,7 +1037,7 @@ function perPageOf(opts) {
 * @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 {
+var ArraySourceBase = class {
 	load;
 	perPage;
 	constructor(load, opts) {
@@ -855,7 +1057,7 @@ var ArraySource = class {
 * @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 {
+var CursorSourceBase = class {
 	fetch;
 	perPage;
 	constructor(fetch, opts) {
@@ -863,7 +1065,7 @@ var CursorSource = class {
 		this.perPage = perPageOf(opts);
 	}
 	async page(ctx, n) {
-		const page = Math.max(0, Math.trunc(n));
+		const page = Number.isFinite(n) ? Math.max(0, Math.trunc(n)) : 0;
 		const { items, hasNext } = await this.fetch(ctx, page, this.perPage);
 		return {
 			items: [...items],
@@ -878,8 +1080,8 @@ var CursorSource = class {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.3.1";
+const version = "0.4.1";
 
 //#endregion
-export { ArraySource, AutocompleteRoute, BaseHandler, BuilderComponent, Bus, ButtonRoute, Commands, ContextMenus, Cooldown, CursorSource, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, MessageContextMenuRoute, ModalRoute, Notice, OwnerOnly, PaginatorBase, RegisterCommand, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, ResolvedEmoji, RowComponent, SelectMenuKind, SelectMenuRoute, ShutdownPhase, Silence, SlashRoute, StartupPhase, Subscribe, Subscriber, UserContextMenuRoute, WebhookLog, WebhookUrl, and, assertPermissions, defineEffectGate, defineGate, mergeRoles, or, paginate, version };
+export { ArraySourceBase, AutocompleteRoute, BaseHandler, BaseReplySender, BuilderComponent, Bus, ButtonRoute, Commands, ContextMenus, Cooldown, CursorSourceBase, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, MessageContextMenuRoute, ModalRoute, Notice, OwnerOnly, PaginatorBase, RegisterCommand, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, ResolvedEmoji, RowComponent, SelectMenuKind, SelectMenuRoute, ShutdownPhase, Silence, SlashRoute, StartupPhase, Subscribe, Subscriber, UserContextMenuRoute, WebhookLog, WebhookUrl, and, assertPermissions, defineEffectGate, defineGate, mergeRoles, or, paginate, setCustomIdErrors, version };
 //# sourceMappingURL=index.mjs.map