@seedcord/core 0.1.0-next.0 → 0.1.0-next.2

package/dist/CustomId-Bq6WagiA.mjs

@@ -0,0 +1,820 @@
+import { SeedcordErrorCode } from "@seedcord/errors";
+import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
+import { toEpochSeconds } from "@seedcord/utils";
+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";
+
+//#region src/metadataKeys.ts
+let InteractionRoutes = /* @__PURE__ */ function(InteractionRoutes) {
+	InteractionRoutes["Slash"] = "slash";
+	InteractionRoutes["Button"] = "button";
+	InteractionRoutes["Modal"] = "modal";
+	InteractionRoutes["StringMenu"] = "stringMenu";
+	InteractionRoutes["UserMenu"] = "userMenu";
+	InteractionRoutes["RoleMenu"] = "roleMenu";
+	InteractionRoutes["ChannelMenu"] = "channelMenu";
+	InteractionRoutes["MentionableMenu"] = "mentionableMenu";
+	InteractionRoutes["MessageContextMenu"] = "messageContextMenu";
+	InteractionRoutes["UserContextMenu"] = "userContextMenu";
+	InteractionRoutes["Autocomplete"] = "autocomplete";
+	return InteractionRoutes;
+}({});
+const InteractionMetadataKey = Symbol("seedcord:interaction:metadata");
+const InteractionRouteKeys = {
+	["slash"]: Symbol("seedcord:interaction:slash"),
+	["button"]: Symbol("seedcord:interaction:button"),
+	["modal"]: Symbol("seedcord:interaction:modal"),
+	["stringMenu"]: Symbol("seedcord:interaction:stringMenu"),
+	["userMenu"]: Symbol("seedcord:interaction:userMenu"),
+	["roleMenu"]: Symbol("seedcord:interaction:roleMenu"),
+	["channelMenu"]: Symbol("seedcord:interaction:channelMenu"),
+	["mentionableMenu"]: Symbol("seedcord:interaction:mentionableMenu"),
+	["messageContextMenu"]: Symbol("seedcord:interaction:messageContextMenu"),
+	["userContextMenu"]: Symbol("seedcord:interaction:userContextMenu"),
+	["autocomplete"]: Symbol("seedcord:interaction:autocomplete")
+};
+const MiddlewareMetadataKey = Symbol("seedcord:middleware:metadata");
+const EventMetadataKey = Symbol("seedcord:event:metadata");
+const CommandMetadataKey = Symbol("seedcord:command:metadata");
+const GatedMetadataKey = Symbol("seedcord:gated:metadata");
+const SubscribeMetadataKey = Symbol("seedcord:subscribe:metadata");
+
+//#endregion
+//#region src/stops/Notice.ts
+/**
+* Base class for a user-facing refusal or a reported fault.
+*
+* Throw a `Notice` to stop a handler and reply to the user. The framework catches it at the controller
+* boundary and renders {@link Notice.render}, which always decides what the user sees. With `report`
+* false that render is all that happens. With `report` true the framework also logs the fault and
+* publishes it to the `handledException` bus. A raw, non-Notice throw shows the generic message.
+*
+* @example
+* ```ts
+* import { Notice, BuilderComponent, type RenderContext, type ReplyResponse } from 'seedcord';
+* import { TextDisplayBuilder } from '@discordjs/builders';
+*
+* // reading `.component` applies the configured bot color to the container accent
+* class TooPoorCard extends BuilderComponent<'container'> {
+*     constructor(balance: number) {
+*         super('container');
+*         this.instance.addTextDisplayComponents(
+*             new TextDisplayBuilder().setContent(`### Insufficient balance\nYou need more than ${balance} coins.`)
+*         );
+*     }
+* }
+*
+* class TooPoor extends Notice {
+*     constructor(private readonly balance: number) {
+*         super(`balance ${balance} is below the cost`);
+*     }
+*
+*     render(_ctx: RenderContext): ReplyResponse {
+*         return { components: [new TooPoorCard(this.balance).component] };
+*     }
+* }
+*
+* // in a handler, throwing stops the handler and replies with render(ctx)
+* if (wallet.balance < cost) throw new TooPoor(wallet.balance);
+* ```
+*/
+var Notice = class extends Error {
+	/**
+	* Whether this denial is a reported fault. True also logs it and publishes it to the `handledException`
+	* bus. The user always sees {@link Notice.render} either way.
+	*
+	* @defaultValue `false`
+	*/
+	report = false;
+	/**
+	* Whether the reply is ephemeral, so only the invoking user sees it. Set it false for a refusal the
+	* whole channel should see.
+	*
+	* @defaultValue `true`
+	*/
+	ephemeral = true;
+	/**
+	* A short one-line reason. When every arm of an `or` gate refuses and each refusal sets this, `or`
+	* lists them instead of showing a neutral message.
+	*/
+	summary;
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+		Error.captureStackTrace(this, this.constructor);
+	}
+};
+
+//#endregion
+//#region src/components/botColorHolder.ts
+const DEFAULT_COLOR = "Default";
+let current = DEFAULT_COLOR;
+function setBotColor(color) {
+	current = color ?? DEFAULT_COLOR;
+}
+function getBotColor() {
+	return current;
+}
+
+//#endregion
+//#region src/components/builderTypes.ts
+/**
+* Available Discord.js builder classes for use with BuilderComponent for commands, embeds, modals, etc.
+*
+* @internal
+*/
+const BuilderTypes = {
+	command: SlashCommandBuilder,
+	context_menu: ContextMenuCommandBuilder,
+	subcommand: SlashCommandSubcommandBuilder,
+	group: SlashCommandSubcommandGroupBuilder,
+	embed: EmbedBuilder,
+	modal: ModalBuilder,
+	label: LabelBuilder,
+	text_input: TextInputBuilder,
+	file_upload: FileUploadBuilder,
+	checkbox: CheckboxBuilder,
+	checkbox_group: CheckboxGroupBuilder,
+	checkbox_group_option: CheckboxGroupOptionBuilder,
+	radio_group: RadioGroupBuilder,
+	radio_group_option: RadioGroupOptionBuilder,
+	button: ButtonBuilder,
+	menu_string: StringSelectMenuBuilder,
+	menu_option_string: StringSelectMenuOptionBuilder,
+	menu_user: UserSelectMenuBuilder,
+	menu_channel: ChannelSelectMenuBuilder,
+	menu_mentionable: MentionableSelectMenuBuilder,
+	menu_role: RoleSelectMenuBuilder,
+	container: ContainerBuilder,
+	text_display: TextDisplayBuilder,
+	file: FileBuilder,
+	media: MediaGalleryBuilder,
+	section: SectionBuilder,
+	separator: SeparatorBuilder
+};
+/**
+* Available Discord.js action row classes for use with RowComponent for Select Menus and Buttons
+*
+* @internal
+*/
+const RowTypes = {
+	button: ActionRowBuilder,
+	menu_string: ActionRowBuilder,
+	menu_user: ActionRowBuilder,
+	menu_channel: ActionRowBuilder,
+	menu_mentionable: ActionRowBuilder,
+	menu_role: ActionRowBuilder
+};
+
+//#endregion
+//#region src/components/colors.ts
+const Colors = {
+	Aqua: 1752220,
+	Blue: 3447003,
+	Blurple: 5793266,
+	DarkAqua: 1146986,
+	DarkBlue: 2123412,
+	DarkButNotBlack: 2895667,
+	DarkerGrey: 8359053,
+	DarkGold: 12745742,
+	DarkGreen: 2067276,
+	DarkGrey: 9936031,
+	DarkNavy: 2899536,
+	DarkOrange: 11027200,
+	DarkPurple: 7419530,
+	DarkRed: 10038562,
+	DarkVividPink: 11342935,
+	Default: 0,
+	Fuchsia: 15418782,
+	Gold: 15844367,
+	Green: 5763719,
+	Grey: 9807270,
+	Greyple: 10070709,
+	LightGrey: 12370112,
+	LuminousVividPink: 15277667,
+	Navy: 3426654,
+	NotQuiteBlack: 2303786,
+	Orange: 15105570,
+	Purple: 10181046,
+	Red: 15548997,
+	White: 16777215,
+	Yellow: 16705372
+};
+
+//#endregion
+//#region src/components/resolveColor.ts
+const MAX_COLOR = 16777215;
+const RED_SHIFT = 16;
+const GREEN_SHIFT = 8;
+const palette = Colors;
+/**
+* Resolves a {@link BotColor} to the integer Discord expects.
+*
+* Ported from discord.js (Apache-2.0), `resolveColor` in src/util/Util.js.
+*/
+function resolveColor(color) {
+	let resolved;
+	if (typeof color === "string") {
+		if (color === "Random") return Math.floor(Math.random() * 16777216);
+		if (color === "Default") return 0;
+		if (/^#?[\da-f]{6}$/i.test(color)) return Number.parseInt(color.replace("#", ""), 16);
+		resolved = palette[color];
+	} else if (typeof color === "number") resolved = color;
+	else resolved = (color[0] << RED_SHIFT) + (color[1] << GREEN_SHIFT) + color[2];
+	if (resolved === void 0 || !Number.isSafeInteger(resolved)) throw new SeedcordTypeError(SeedcordErrorCode.ColorUnresolvable, [JSON.stringify(color)]);
+	if (resolved < 0 || resolved > MAX_COLOR) throw new SeedcordRangeError(SeedcordErrorCode.ColorOutOfRange);
+	return resolved;
+}
+
+//#endregion
+//#region src/components/Component.ts
+/**
+* Base class for Discord component wrappers.
+*
+* @typeParam TComponent - The Discord.js component type being wrapped
+*
+* @internal
+*/
+var BaseComponent = class {
+	_component;
+	constructor(ComponentClass) {
+		this._component = new ComponentClass();
+	}
+	/**
+	* The wrapped builder, for calling Discord.js methods like setTitle() and setDescription() inside a subclass.
+	*
+	* @example this.instance.setTitle('My Modal')
+	*/
+	get instance() {
+		return this._component;
+	}
+};
+/**
+* Base class for Discord.js builder components
+*
+* Wraps Discord.js builders (SlashCommandBuilder, EmbedBuilder, etc.) with
+* Seedcord-specific defaults and helper methods.
+*
+* @typeParam BuilderKey - The type of Discord.js builder being wrapped
+*/
+var BuilderComponent = class extends BaseComponent {
+	type;
+	colorApplied = false;
+	constructor(type) {
+		const ComponentClass = BuilderTypes[type];
+		super(ComponentClass);
+		this.type = type;
+		if (this.instance instanceof SlashCommandBuilder || this.instance instanceof ContextMenuCommandBuilder) this.instance.setContexts(InteractionContextType.Guild);
+	}
+	get component() {
+		this.applyBotColor();
+		return this.instance;
+	}
+	applyBotColor() {
+		if (this.colorApplied) return;
+		this.colorApplied = true;
+		const color = getBotColor();
+		if (this.instance instanceof EmbedBuilder) {
+			if (this.instance.data.color === void 0) this.instance.setColor(resolveColor(color));
+		} else if (this.instance instanceof ContainerBuilder) {
+			const accent = this.instance.data.accent_color;
+			if (accent === null || accent === void 0) this.instance.setAccentColor(color === "Default" ? void 0 : resolveColor(color));
+		}
+	}
+};
+/**
+* Base class for Discord action row components
+*
+* Wraps Discord.js action row builder with Seedcord-specific defaults and helper methods.
+*
+* @typeParam RowKey - The Discord.js action row type being wrapped
+*/
+var RowComponent = class extends BaseComponent {
+	type;
+	constructor(type) {
+		const ComponentClass = RowTypes[type];
+		super(ComponentClass);
+		this.type = type;
+	}
+	get component() {
+		return this.instance;
+	}
+};
+
+//#endregion
+//#region src/stops/NoticeCard.ts
+/**
+* Built fresh inside a {@link Notice}'s `render` to back its ComponentsV2 reply. The title renders as
+* an h3 line with the description on the next line.
+*/
+var NoticeCard = class extends BuilderComponent {
+	constructor(description, title = "Cannot Proceed") {
+		super("container");
+		this.instance.addTextDisplayComponents(new TextDisplayBuilder().setContent(`### ${title}\n${description}`));
+	}
+};
+
+//#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
+/**
+* Thrown when a customId was minted by an older version of its shape.
+*
+* This is normal after the shape changes. The reply tells the user to run the command again.
+*/
+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.
+*
+* This should not happen in normal use, so it reports.
+*/
+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 rather than plain stringified tokens, so the 100-char Discord limit goes further. More string per string, basically.
+*
+* @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' }));
+*
+* // reading 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;
+	/** Like a zod shape */
+	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 so it costs the most wire space.
+	*
+	* @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;
+	}
+};
+/**
+* Find the customId whose prefix owns this wire, decode against it, and report which one matched.
+*
+* @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
+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-Bq6WagiA.mjs.map