@seedcord/core 0.3.1 → 0.4.1

package/dist/{cursor-CuoA9cRh.mjs → cursor-CaT051ii.mjs}

@@ -1,9 +1,12 @@
-import { b as InteractionRoutes, f as BuilderComponent, v as InteractionMetadataKey, y as InteractionRouteKeys } from "./Bus-BvF4VShN.mjs";
+import { b as InteractionRouteKeys, k as BuilderComponent, x as InteractionRoutes, y as InteractionMetadataKey } from "./Bus-yJGE6Fs2.mjs";
+import { n as asError, t as PublishDefault } from "./publishDefault-D826XXDQ.mjs";
 import "reflect-metadata";
+import { CustomId, decodeFor } from "@seedcord/custom-id";
 import { TextDisplayBuilder } from "@discordjs/builders";
-import { SeedcordErrorCode } from "@seedcord/errors";
 import { ApplicationCommandType, PermissionFlagsBits } from "discord-api-types/v10";
-import { SeedcordError, SeedcordRangeError } from "@seedcord/errors/internal";
+import { SeedcordErrorCode, paint } from "@seedcord/errors";
+import { SeedcordError } from "@seedcord/errors/internal";
+import { Logger } from "@seedcord/logger";
 import { prettify, toEpochSeconds } from "@seedcord/utils";
 
 //#region src/stops/Notice.ts
@@ -60,8 +63,9 @@ var Notice = class extends Error {
 	*/
 	ephemeral = true;
 	/**
-	* A short one-line reason. When every arm of an `or` gate refuses and each refusal sets this, `or`
-	* lists them as the reply.
+	* A short one-line reason. When every arm of an {@link or} gate refuses and each one sets this, `or`
+	* throws a refusal listing them under `You need to meet at least one of these:`. Write a verb phrase that
+	* finishes that line, for example, "be the bot owner".
 	*/
 	summary;
 	constructor(message, options) {
@@ -80,419 +84,6 @@ var NoticeCard = class extends BuilderComponent {
 	}
 };
 
-//#endregion
-//#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] };
-	}
-};
-
-//#endregion
-//#region src/customId/codec.ts
-const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-const BASE = 64n;
-const CHAR_TO_VALUE = new Map([...ALPHABET].map((char, index) => [char, index]));
-const DELIMITER = "";
-const ESCAPE = "\x1B";
-/** @internal */
-const HASH_LENGTH = 3;
-const SAFE_MAX = BigInt(Number.MAX_SAFE_INTEGER);
-const SAFE_MIN = BigInt(Number.MIN_SAFE_INTEGER);
-function bigintToBase64(value) {
-	if (value === 0n) return ALPHABET.charAt(0);
-	let text = "";
-	for (let remaining = value; remaining > 0n; remaining /= BASE) text = ALPHABET.charAt(Number(remaining % BASE)) + text;
-	return text;
-}
-function base64ToBigint(text) {
-	let value = 0n;
-	for (const char of text) {
-		const digit = CHAR_TO_VALUE.get(char);
-		if (digit === void 0) throw new InvalidCustomId(`bad character ${JSON.stringify(char)}`);
-		value = value * BASE + BigInt(digit);
-	}
-	return value;
-}
-function zigzagEncode(value) {
-	const big = BigInt(value);
-	return big >= 0n ? big << 1n : (-big << 1n) - 1n;
-}
-function zigzagDecode(encoded) {
-	return (encoded & 1n) === 1n ? -(encoded + 1n >> 1n) : encoded >> 1n;
-}
-function escapeToken(text) {
-	return text.replaceAll(/[\x1B\x1F]/g, (char) => ESCAPE + char);
-}
-function unescapeToken(text) {
-	let out = "";
-	for (let i = 0; i < text.length; i++) {
-		if (text.charAt(i) !== ESCAPE) {
-			out += text.charAt(i);
-			continue;
-		}
-		const next = text.charAt(i + 1);
-		if (next === "") throw new InvalidCustomId("dangling escape at end of token");
-		out += next;
-		i++;
-	}
-	return out;
-}
-function splitTokens(body) {
-	const pieces = [];
-	let current = "";
-	for (let i = 0; i < body.length; i++) {
-		const char = body.charAt(i);
-		if (char === ESCAPE) {
-			current += char + body.charAt(i + 1);
-			i++;
-		} else if (char === DELIMITER) {
-			pieces.push(current);
-			current = "";
-		} else current += char;
-	}
-	pieces.push(current);
-	return pieces;
-}
-function isBounded(field) {
-	if (field.kind === "int") return field.min !== void 0 && field.max !== void 0;
-	return field.kind === "snowflake" || field.kind === "uuid" || field.kind === "bool" || field.kind === "oneOf";
-}
-function radixOf(field) {
-	switch (field.kind) {
-		case "snowflake": return 1n << 64n;
-		case "uuid": return 1n << 128n;
-		case "bool": return 2n;
-		case "oneOf":
-			if (!field.choices?.length) throw new InvalidCustomId("oneOf field has no choices");
-			return BigInt(field.choices.length);
-		case "int":
-			if (field.min === void 0 || field.max === void 0) throw new InvalidCustomId("bounded int field is missing a bound");
-			return BigInt(field.max) - BigInt(field.min) + 1n;
-		default: throw new InvalidCustomId(`field kind ${field.kind} has no radix`);
-	}
-}
-function boundedToBigint(field, name, value) {
-	const slot = boundedSlot(field, name, value);
-	if (slot < 0n || slot >= radixOf(field)) outOfRange(name, value);
-	return slot;
-}
-function boundedSlot(field, name, value) {
-	switch (field.kind) {
-		case "snowflake":
-			if (typeof value !== "string" || !/^\d+$/.test(value)) return outOfRange(name, value);
-			return BigInt(value);
-		case "uuid": {
-			if (typeof value !== "string") return outOfRange(name, value);
-			const hex = value.replaceAll("-", "");
-			if (!/^[0-9a-fA-F]{32}$/.test(hex)) return outOfRange(name, value);
-			return BigInt(`0x${hex}`);
-		}
-		case "bool": return value ? 1n : 0n;
-		case "oneOf": {
-			const index = (field.choices ?? []).indexOf(value);
-			return index === -1 ? outOfRange(name, value) : BigInt(index);
-		}
-		case "int":
-			if (!Number.isInteger(value)) return outOfRange(name, value);
-			return BigInt(value - (field.min ?? 0));
-		default: return outOfRange(name, value);
-	}
-}
-function outOfRange(name, value) {
-	throw new SeedcordRangeError(SeedcordErrorCode.CustomIdValueOutOfRange, [name, String(value)]);
-}
-function bigintToBoundedValue(field, slot) {
-	switch (field.kind) {
-		case "snowflake": return slot.toString();
-		case "uuid": return bigintToUuid(slot);
-		case "bool": return slot === 1n;
-		case "oneOf": return (field.choices ?? [])[Number(slot)];
-		case "int": return Number(slot) + (field.min ?? 0);
-		default: throw new InvalidCustomId(`field kind ${field.kind} is not bounded`);
-	}
-}
-function bigintToUuid(value) {
-	const hex = value.toString(16).padStart(32, "0");
-	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-function encodeUnboundedToken(field, name, value) {
-	if (field.kind === "int") {
-		if (!Number.isSafeInteger(value)) outOfRange(name, value);
-		return bigintToBase64(zigzagEncode(value));
-	}
-	return escapeToken(value);
-}
-function decodeUnboundedToken(field, piece) {
-	if (field.kind !== "int") return unescapeToken(piece);
-	if (piece === "") throw new InvalidCustomId("empty integer token");
-	const decoded = zigzagDecode(base64ToBigint(piece));
-	if (decoded > SAFE_MAX || decoded < SAFE_MIN) throw new InvalidCustomId("integer out of safe range");
-	return Number(decoded);
-}
-/** @internal */
-function computeLayoutHash(shape) {
-	const signature = JSON.stringify(Object.entries(shape).map(([name, field]) => [
-		name,
-		field.kind,
-		isBounded(field),
-		field.kind === "oneOf" ? field.choices ?? [] : null,
-		field.kind === "int" ? [field.min ?? null, field.max ?? null] : null
-	]));
-	const modulus = BASE ** BigInt(3);
-	let hash = 0n;
-	for (const char of signature) hash = (hash * 131n + BigInt(char.charCodeAt(0))) % modulus;
-	let text = "";
-	for (let i = 0; i < 3; i++) {
-		text = ALPHABET.charAt(Number(hash % BASE)) + text;
-		hash /= BASE;
-	}
-	return text;
-}
-/** @internal */
-function encodeBody(shape, values) {
-	const fields = Object.entries(shape);
-	const pieces = [];
-	const bounded = fields.filter(([, field]) => isBounded(field));
-	if (bounded.length > 0) {
-		let packed = 0n;
-		for (const [name, field] of bounded) packed = packed * radixOf(field) + boundedToBigint(field, name, values[name]);
-		pieces.push(bigintToBase64(packed));
-	}
-	for (const [name, field] of fields) if (!isBounded(field)) pieces.push(encodeUnboundedToken(field, name, values[name]));
-	return pieces.join(DELIMITER);
-}
-function unpackBounded(bounded, blob, result) {
-	if (blob === void 0 || blob === "") throw new InvalidCustomId("empty packed block");
-	let packed = base64ToBigint(blob);
-	for (const [name, field] of [...bounded].reverse()) {
-		const radix = radixOf(field);
-		result[name] = bigintToBoundedValue(field, packed % radix);
-		packed /= radix;
-	}
-	if (packed !== 0n) throw new InvalidCustomId("leftover bits after unpacking");
-}
-/** @internal */
-function decodeBody(shape, body) {
-	const fields = Object.entries(shape);
-	const bounded = fields.filter(([, field]) => isBounded(field));
-	const unbounded = fields.filter(([, field]) => !isBounded(field));
-	const expected = (bounded.length > 0 ? 1 : 0) + unbounded.length;
-	if (expected === 0) {
-		if (body !== "") throw new InvalidCustomId(`expected an empty body, got ${JSON.stringify(body)}`);
-		return {};
-	}
-	const pieces = splitTokens(body);
-	if (pieces.length !== expected) throw new InvalidCustomId(`expected ${expected} piece(s), got ${pieces.length}`);
-	const result = {};
-	let cursor = 0;
-	if (bounded.length > 0) {
-		unpackBounded(bounded, pieces[cursor], result);
-		cursor++;
-	}
-	for (const [name, field] of unbounded) {
-		const piece = pieces[cursor];
-		cursor++;
-		if (piece === void 0) throw new InvalidCustomId("missing trailing piece");
-		result[name] = decodeUnboundedToken(field, piece);
-	}
-	return result;
-}
-
-//#endregion
-//#region src/customId/CustomId.ts
-const MAX_WIRE_LENGTH = 100;
-function routeKeyOf(wire) {
-	const colon = wire.indexOf(":");
-	return colon === -1 ? "" : wire.slice(0, colon);
-}
-/** Strip the layout hash off the routeKey to recover the stable prefix the controller routes by. @internal */
-function prefixOf(wire) {
-	const key = routeKeyOf(wire);
-	return key.length <= 3 ? "" : key.slice(0, key.length - 3);
-}
-/**
-* A typed customId. The single source of truth shared by the component that mints it and the handler
-* that reads it. This gives you typed reads on the `.customId` field in components. Values are packed
-* into a compact wire string, which fits more of them inside Discord's 100-char limit.
-*
-* @typeParam Prefix - The stable route prefix, e.g. 'approve'.
-* @typeParam Shape - The accumulated fields, filled in by the chain.
-*
-* @example
-* ```ts
-* const ApproveId = new CustomId('approve')
-*     .snowflake('userId')
-*     .oneOf('action', ['approve', 'deny']);
-*
-* // Set the custom id on a button when creating it.
-* new ButtonBuilder().setCustomId(ApproveId.encode({ userId: '123', action: 'approve' }));
-*
-* // in the handler, userId comes back a string
-* const { userId, action } = this.params; // userId: string, action: 'approve' | 'deny'
-* await this.event.guild?.members.fetch(userId);
-* ```
-*/
-var CustomId = class CustomId {
-	/** The stable route prefix, e.g. 'approve'. */
-	prefix;
-	/** The field definitions accumulated by the chain, keyed by name. */
-	shape;
-	/** The prefix plus a short hash of the shape, the part of the wire before the colon. */
-	routeKey;
-	constructor(prefix, shape = {}) {
-		if (!prefix || /[:\x1B\x1F]/.test(prefix)) throw new SeedcordError(SeedcordErrorCode.CustomIdInvalidPrefix, [prefix]);
-		this.prefix = prefix;
-		this.shape = shape;
-		this.routeKey = prefix + computeLayoutHash(shape);
-	}
-	add(name, field) {
-		if (/^(?:0|[1-9]\d*)$/.test(name)) throw new SeedcordError(SeedcordErrorCode.CustomIdReservedFieldName, [name]);
-		if (name in this.shape) throw new SeedcordError(SeedcordErrorCode.CustomIdDuplicateFieldName, [name]);
-		const shape = {
-			...this.shape,
-			[name]: field
-		};
-		return new CustomId(this.prefix, shape);
-	}
-	/**
-	* Add a Discord ID field, decoded as a string (the `Snowflake` type from discord-api-types).
-	*
-	* @example
-	* ```ts
-	* new CustomId('ban').snowflake('userId');
-	* ```
-	*/
-	snowflake(name) {
-		return this.add(name, { kind: "snowflake" });
-	}
-	/**
-	* Add a UUID field, decoded as a lowercase uuid string.
-	*
-	* @example
-	* ```ts
-	* new CustomId('ticket').uuid('ticketId');
-	* ```
-	*/
-	uuid(name) {
-		return this.add(name, { kind: "uuid" });
-	}
-	int(name, min, max) {
-		if (min !== void 0 && max !== void 0 && min > max) throw new SeedcordError(SeedcordErrorCode.CustomIdInvalidBounds, [
-			name,
-			min,
-			max
-		]);
-		const field = min === void 0 || max === void 0 ? { kind: "int" } : {
-			kind: "int",
-			min,
-			max
-		};
-		return this.add(name, field);
-	}
-	/**
-	* Add a boolean flag.
-	*
-	* @example
-	* ```ts
-	* new CustomId('settings').bool('silent');
-	* ```
-	*/
-	bool(name) {
-		return this.add(name, { kind: "bool" });
-	}
-	/**
-	* Add a field that is one value from a fixed list, decoded as the literal union. No `as const` needed.
-	*
-	* @example
-	* ```ts
-	* new CustomId('poll').oneOf('choice', ['yes', 'no', 'abstain']);
-	* ```
-	*/
-	oneOf(name, choices) {
-		if (choices.length === 0) throw new SeedcordError(SeedcordErrorCode.CustomIdEmptyChoices, [name]);
-		return this.add(name, {
-			kind: "oneOf",
-			choices
-		});
-	}
-	/**
-	* Add a free short text field. Avoid it where possible. It cannot be packed, which makes it the most
-	* expensive field on the wire.
-	*
-	* @example
-	* ```ts
-	* new CustomId('note').str('message');
-	* ```
-	*/
-	str(name) {
-		return this.add(name, { kind: "string" });
-	}
-	/**
-	* Mint a wire string from values. Throws if a value is out of its field's range or the wire is over 100 chars.
-	*
-	* @param values - One value per field, typed by the chain.
-	* @returns The wire string to put on the component's customId.
-	*/
-	encode(values) {
-		const wire = `${this.routeKey}:${encodeBody(this.shape, values)}`;
-		if (wire.length > MAX_WIRE_LENGTH) throw new SeedcordRangeError(SeedcordErrorCode.CustomIdWireTooLong, [wire.length]);
-		return wire;
-	}
-	/**
-	* Read a wire string back into values.
-	*
-	* - This will refuse with a default Notice when the shape changed since the wire was minted.
-	* - Or refuse with a different default Notice on a corrupt or foreign wire.
-	*
-	* @param wire - The customId string from the interaction.
-	* @returns The decoded values, typed by the chain.
-	*/
-	decode(wire) {
-		const key = routeKeyOf(wire);
-		if (key !== this.routeKey) {
-			if (prefixOf(wire) === this.prefix) throw new StaleCustomId(this.prefix);
-			throw new InvalidCustomId(`routeKey ${JSON.stringify(key)} is not ${JSON.stringify(this.routeKey)}`);
-		}
-		return decodeBody(this.shape, wire.slice(key.length + 1));
-	}
-	/** True if this wire was minted from this customId's prefix, ignoring the shape hash. */
-	owns(wire) {
-		return prefixOf(wire) === this.prefix;
-	}
-};
-/** @internal */
-function decodeFor(defs, wire) {
-	const match = defs.find((def) => def.owns(wire));
-	if (!match) throw new InvalidCustomId(`no customId owns ${JSON.stringify(routeKeyOf(wire))}`);
-	return {
-		prefix: match.prefix,
-		params: match.decode(wire)
-	};
-}
-
 //#endregion
 //#region src/customId/routing.ts
 /**
@@ -566,6 +157,285 @@ function contextMenuRouteOf(kind) {
 	return kind === ApplicationCommandType.User ? "userContextMenu" : "messageContextMenu";
 }
 
+//#endregion
+//#region src/reply/ackLegality.ts
+const showModalReason = {
+	reason: "this interaction was already acknowledged",
+	alternative: "showModal() must be the initial response."
+};
+function deferReason(what) {
+	return {
+		reason: `this interaction was already acknowledged with ${what}`,
+		alternative: "A deferral can only be the initial response."
+	};
+}
+const ILLEGAL = {
+	reply: {
+		"deferred-reply": {
+			reason: "this interaction was already deferred",
+			alternative: "Use edit() to fill the deferred reply or followUp() for a new message."
+		},
+		"deferred-update": {
+			reason: "this interaction was already acknowledged with a deferred update",
+			alternative: "Use followUp() for a new message."
+		},
+		replied: {
+			reason: "this interaction was already replied to",
+			alternative: "Use followUp() for a new message or edit() to rewrite the reply."
+		}
+	},
+	defer: {
+		"deferred-reply": deferReason("a deferred reply"),
+		"deferred-update": deferReason("a deferred update"),
+		replied: deferReason("a reply")
+	},
+	deferUpdate: {
+		"deferred-reply": deferReason("a deferred reply"),
+		"deferred-update": deferReason("a deferred update"),
+		replied: deferReason("a reply")
+	},
+	update: {
+		"deferred-reply": {
+			reason: "this interaction was deferred as a reply",
+			alternative: "The placeholder is yours via edit(). update() rewrites a source message."
+		},
+		replied: {
+			reason: "this interaction was already replied to",
+			alternative: "update() rewrites a source message. Use edit() or followUp() instead."
+		}
+	},
+	followUp: { unacked: {
+		reason: "this interaction has not been acknowledged yet",
+		alternative: "Ack first with reply() or defer()."
+	} },
+	edit: { unacked: {
+		reason: "nothing has been sent yet",
+		alternative: "Send with reply() or defer() first, then edit() rewrites it."
+	} },
+	delete: { unacked: {
+		reason: "nothing has been sent yet",
+		alternative: "Acknowledge first with reply() or defer(), then delete() removes it."
+	} },
+	showModal: {
+		"deferred-reply": showModalReason,
+		"deferred-update": showModalReason,
+		replied: showModalReason
+	}
+};
+const SEND_TARGET = {
+	unacked: "reply",
+	"deferred-reply": "edit",
+	"deferred-update": "followUp",
+	replied: "followUp"
+};
+function checkAckLegality(method, state, routeId, ackedBy) {
+	if (method === "send") return;
+	const illegal = ILLEGAL[method][state];
+	if (!illegal) return;
+	throw new SeedcordError(SeedcordErrorCode.ReplyIllegalAckState, [
+		method,
+		illegal.reason,
+		illegal.alternative,
+		routeId
+	], { cause: ackedBy });
+}
+function sendTarget(state) {
+	return SEND_TARGET[state];
+}
+
+//#endregion
+//#region src/reply/AckTrace.ts
+var AckTrace = class extends Error {
+	constructor(method) {
+		super(`${method}() acknowledged this interaction`);
+		this.name = "AckTrace";
+	}
+};
+
+//#endregion
+//#region src/reply/responseReport.ts
+let replyLogger;
+function logger() {
+	replyLogger ??= new Logger("Reply", { channel: "interactions" });
+	return replyLogger;
+}
+/** @internal */
+function publishResponse(telemetry, report) {
+	const durationMs = performance.now() - report.startedAt;
+	const write = {
+		routeId: report.routeId,
+		interactionId: telemetry.interactionId,
+		method: report.method,
+		durationMs
+	};
+	telemetry.bus[PublishDefault]("responseAttempted", report.outcome === "failed" ? {
+		...write,
+		outcome: "failed",
+		messageId: null,
+		error: report.error
+	} : {
+		...write,
+		outcome: "sent",
+		messageId: report.messageId
+	});
+	logger().trace(`${paint.sky.bold(report.routeId)} ${report.method} ${report.outcome} ${paint.mute("in")} ${Math.round(durationMs)}ms`);
+}
+async function reportedWrite(telemetry, routeId, method, write) {
+	const startedAt = performance.now();
+	const result = await attemptWrite(telemetry, routeId, method, startedAt, write);
+	publishResponse(telemetry, {
+		routeId,
+		method,
+		startedAt,
+		outcome: "sent",
+		messageId: null
+	});
+	return result;
+}
+async function attemptWrite(telemetry, routeId, method, startedAt, write) {
+	try {
+		return await write();
+	} catch (caught) {
+		publishResponse(telemetry, {
+			routeId,
+			method,
+			startedAt,
+			outcome: "failed",
+			error: asError(caught)
+		});
+		throw caught;
+	}
+}
+
+//#endregion
+//#region src/reply/translateSerialization.ts
+const MAX_DEPTH = 8;
+const OPERATOR_WORD = {
+	"<=": "at most",
+	">=": "at least",
+	"<": "fewer than",
+	">": "more than"
+};
+const KIND_WORD = {
+	string: "a string",
+	number: "a number",
+	boolean: "a boolean",
+	bigint: "a bigint",
+	array: "a list",
+	tuple: "a list",
+	date: "a date",
+	object: "an object"
+};
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : null;
+}
+function firstLine(message) {
+	if (typeof message !== "string") return "unknown validation failure";
+	return message.split("\n")[0] ?? message;
+}
+const GIVEN_PREVIEW_LIMIT = 40;
+function gotPhrase(given) {
+	if (given === void 0) return "nothing";
+	if (given === null) return "null";
+	if (typeof given === "string") {
+		if (given.length === 0) return "an empty string";
+		if (given.length > GIVEN_PREVIEW_LIMIT) return `${given.length} characters`;
+		return JSON.stringify(given);
+	}
+	if (Array.isArray(given)) return given.length === 0 ? "an empty list" : `${given.length} items`;
+	if (typeof given === "number" || typeof given === "bigint" || typeof given === "boolean") return String(given);
+	if (typeof given === "object") return given.constructor?.name ?? "an object";
+	return typeof given;
+}
+function needPhrase(expected, given) {
+	const bounds = [...expected.matchAll(/expected(\.length)?\s*(<=|>=|<|>)\s*(\d+)/g)];
+	if (bounds.length === 0) return null;
+	return bounds.map(([, lengthPart, operator, limit]) => {
+		const word = OPERATOR_WORD[operator ?? ""] ?? operator ?? "";
+		if (!lengthPart) return `${word} ${limit}`;
+		const unit = typeof given === "string" ? "character" : "item";
+		return `${word} ${limit} ${Number(limit) === 1 ? unit : `${unit}s`}`;
+	}).join(" and ");
+}
+function instanceName(expected) {
+	if (typeof expected === "function" && expected.name) return expected.name;
+	return "specific class instance";
+}
+function describeLeaf(record) {
+	if (typeof record.constraint === "string") {
+		const need = typeof record.expected === "string" ? needPhrase(record.expected, record.given) : null;
+		if (need) return `need ${need}, got ${gotPhrase(record.given)}`;
+		return `${firstLine(record.message)}${"given" in record ? ` (got ${gotPhrase(record.given)})` : ""}`;
+	}
+	if (typeof record.expected === "function") return `need a ${instanceName(record.expected)}, got ${gotPhrase(record.given)}`;
+	if (typeof record.validator === "string") {
+		const kind = KIND_WORD[record.validator.replace(/^s\./, "").replace(/\(.*$/, "")];
+		if (kind) return `need ${kind}, got ${gotPhrase(record.given)}`;
+		return `${firstLine(record.message)}, got ${gotPhrase(record.given)}`;
+	}
+	return firstLine(record.message);
+}
+function describeUnion(branches, depth) {
+	const records = [];
+	for (const branch of branches) {
+		const record = asRecord(branch);
+		if (record) records.push(record);
+	}
+	const bounded = records.find((record) => typeof record.constraint === "string");
+	if (bounded) return describeLeaf(bounded);
+	const names = [];
+	let allInstances = records.length > 0;
+	for (const record of records) if (typeof record.expected === "function") names.push(instanceName(record.expected));
+	else allInstances = false;
+	if (allInstances) return `need a ${[...new Set(names)].join(" or ")}, got ${gotPhrase(records[0]?.given)}`;
+	return detailOf(branches[0], depth + 1);
+}
+function detailOf(value, depth) {
+	const record = asRecord(value);
+	if (!record || depth >= MAX_DEPTH) return firstLine(record?.message);
+	if (Array.isArray(record.errors) && record.errors.length > 0) {
+		const errors = record.errors;
+		const [first] = errors;
+		if (Array.isArray(first)) {
+			const [key, inner] = first;
+			return `${String(key)}: ${detailOf(inner, depth + 1)}`;
+		}
+		return describeUnion(errors, depth);
+	}
+	return describeLeaf(record);
+}
+function translateSerializationError(error, componentClass, index, routeId) {
+	const detail = detailOf(error, 0);
+	return new SeedcordError(SeedcordErrorCode.ReplyComponentSerialization, [
+		componentClass,
+		index,
+		detail,
+		routeId
+	], { cause: error });
+}
+
+//#endregion
+//#region src/reply/serializeReply.ts
+function serializeReply(response, routeId) {
+	if (typeof response === "string") try {
+		return { components: [new TextDisplayBuilder().setContent(response).toJSON()] };
+	} catch (error) {
+		throw translateSerializationError(error, "TextDisplayBuilder", 0, routeId);
+	}
+	return {
+		components: response.components.map((component, index) => {
+			try {
+				return component.toJSON();
+			} catch (error) {
+				const name = component.constructor?.name;
+				throw translateSerializationError(error, !name || name === "Object" ? "component" : name, index, routeId);
+			}
+		}),
+		...response.allowedMentions && { allowedMentions: response.allowedMentions },
+		...response.files && { files: response.files }
+	};
+}
+
 //#endregion
 //#region src/gates/Gate.ts
 /**
@@ -660,23 +530,30 @@ var GateNotice = class extends Notice {
 var NotOwner = class extends GateNotice {
 	constructor(message = "Only the bot owner can use this.") {
 		super(message);
+		this.summary = "be the bot owner";
 	}
 };
 var NotInGuild = class extends GateNotice {
 	constructor(message = "This can only be used in a server.") {
 		super(message);
+		this.summary = "be in a server";
 	}
 };
 var NotInDm = class extends GateNotice {
 	constructor(message = "This can only be used in a direct message.") {
 		super(message);
+		this.summary = "be in a direct message";
 	}
 };
+function retryAt(resetAt) {
+	return `<t:${toEpochSeconds(resetAt)}:R>`;
+}
 var OnCooldown = class extends GateNotice {
 	resetAt;
 	constructor(resetAt, message) {
-		super(message ?? `You are doing that too fast. Try again <t:${toEpochSeconds(resetAt)}:R>.`);
+		super(message ?? `You are doing that too fast. Try again ${retryAt(resetAt)}.`);
 		this.resetAt = resetAt;
+		this.summary = `try again ${retryAt(resetAt)}`;
 	}
 };
 var NotAllowed = class extends Notice {
@@ -691,16 +568,17 @@ var NeedsAny = class extends Notice {
 	summaries;
 	constructor(summaries) {
 		super("not allowed");
-		this.summaries = summaries;
+		this.summaries = [...new Set(summaries)];
 	}
 	render() {
 		const bullets = this.summaries.map((summary) => `• ${summary}`).join("\n");
-		return { components: [new NoticeCard(`You need any of:\n${bullets}`).component] };
+		return { components: [new NoticeCard(`You need to meet at least one of these:\n${bullets}`).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."));
+		this.summary = roleId ? `hold the <@&${roleId}> role` : "hold the required role";
 	}
 };
 var MissingPermissions = class extends Notice {
@@ -712,6 +590,8 @@ var MissingPermissions = class extends Notice {
 		this.subject = subject;
 		this.missingPerms = missingPerms;
 		this.customLead = message;
+		const names = missingPerms.join(", ");
+		this.summary = subject === null ? `hold ${names}` : `${subject} needs ${names}`;
 	}
 	render() {
 		const bullets = this.missingPerms.map((perm) => `• ${perm}`).join("\n");
@@ -728,6 +608,7 @@ var HasDangerousPermissions = class extends Notice {
 		this.subject = subject;
 		this.dangerousPerms = dangerousPerms;
 		this.customLead = message;
+		this.summary = `${subject} must not hold ${dangerousPerms.join(", ")}`;
 	}
 	render() {
 		const bullets = this.dangerousPerms.map((perm) => `• ${perm}`).join("\n");
@@ -875,8 +756,9 @@ function RequireRole(roleId, options) {
 * ```ts
 * import { Silence } from '@seedcord/gateway';
 *
-* // 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');
+* // a helper under a guildMemberAdd handler, stopping when this guild configured nothing to send
+* const template = await settings.welcome(member.guild.id);
+* if (!template) throw new Silence('no welcome message set');
 * ```
 */
 var Silence = class extends Error {
@@ -901,5 +783,5 @@ function pageCursor(prefix) {
 }
 
 //#endregion
-export { areRoutes as A, prefixOf as B, NotInDm as C, defineEffectGate as D, OnCooldown as E, storeInteractionRoute as F, Notice as H, ComponentDefsKey as I, decodeComponentRoute as L, interactionRoutesOf as M, selectMenuRouteOf as N, defineGate as O, storeComponentRoute as P, CustomId as R, NotAllowed as S, NotOwner as T, NoticeCard as V, GateNotice as _, RequirePermissions as a, MissingRole as b, hasAll as c, pickNotice as d, discardCommits as f, runCommits as g, runCheck as h, RequireBotPermissions as i, contextMenuRouteOf as j, SelectMenuKind as k, missingNames as l, rollbackCommits as m, pageCursor as n, RequireRole as o, markCommits as p, Silence as r, PermissionNames as s, PAGE_MAX as t, presentNames as u, HasDangerousPermissions as v, NotInGuild as w, NeedsAny as x, MissingPermissions as y, decodeFor as z };
-//# sourceMappingURL=cursor-CuoA9cRh.mjs.map
+export { translateSerializationError as A, interactionRoutesOf as B, NotInDm as C, defineEffectGate as D, OnCooldown as E, checkAckLegality as F, decodeComponentRoute as G, storeComponentRoute as H, sendTarget as I, NoticeCard as K, SelectMenuKind as L, publishResponse as M, reportedWrite as N, defineGate as O, AckTrace as P, areRoutes as R, NotAllowed as S, NotOwner as T, storeInteractionRoute as U, selectMenuRouteOf as V, ComponentDefsKey as W, GateNotice as _, RequirePermissions as a, MissingRole as b, hasAll as c, pickNotice as d, discardCommits as f, runCommits as g, runCheck as h, RequireBotPermissions as i, attemptWrite as j, serializeReply as k, missingNames as l, rollbackCommits as m, pageCursor as n, RequireRole as o, markCommits as p, Notice as q, Silence as r, PermissionNames as s, PAGE_MAX as t, presentNames as u, HasDangerousPermissions as v, NotInGuild as w, NeedsAny as x, MissingPermissions as y, contextMenuRouteOf as z };
+//# sourceMappingURL=cursor-CaT051ii.mjs.map