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

package/dist/CustomId-BJF6mbJs.d.mts

@@ -0,0 +1,317 @@
+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 { Snowflake } from "discord-api-types/v10";
+
+//#region src/components/builderTypes.d.ts
+/**
+ * Available Discord.js builder classes for use with BuilderComponent for commands, embeds, modals, etc.
+ *
+ * @internal
+ */
+declare const BuilderTypes: {
+  command: typeof SlashCommandBuilder;
+  context_menu: typeof ContextMenuCommandBuilder;
+  subcommand: typeof SlashCommandSubcommandBuilder;
+  group: typeof SlashCommandSubcommandGroupBuilder;
+  embed: typeof EmbedBuilder;
+  modal: typeof ModalBuilder;
+  label: typeof LabelBuilder;
+  text_input: typeof TextInputBuilder;
+  file_upload: typeof FileUploadBuilder;
+  checkbox: typeof CheckboxBuilder;
+  checkbox_group: typeof CheckboxGroupBuilder;
+  checkbox_group_option: typeof CheckboxGroupOptionBuilder;
+  radio_group: typeof RadioGroupBuilder;
+  radio_group_option: typeof RadioGroupOptionBuilder;
+  button: typeof ButtonBuilder;
+  menu_string: typeof StringSelectMenuBuilder;
+  menu_option_string: typeof StringSelectMenuOptionBuilder;
+  menu_user: typeof UserSelectMenuBuilder;
+  menu_channel: typeof ChannelSelectMenuBuilder;
+  menu_mentionable: typeof MentionableSelectMenuBuilder;
+  menu_role: typeof RoleSelectMenuBuilder;
+  container: typeof ContainerBuilder;
+  text_display: typeof TextDisplayBuilder;
+  file: typeof FileBuilder;
+  media: typeof MediaGalleryBuilder;
+  section: typeof SectionBuilder;
+  separator: typeof SeparatorBuilder;
+};
+/**
+ * Available Discord.js action row classes for use with RowComponent for Select Menus and Buttons
+ *
+ * @internal
+ */
+declare const RowTypes: {
+  button: typeof ActionRowBuilder<ButtonBuilder>;
+  menu_string: typeof ActionRowBuilder<StringSelectMenuBuilder>;
+  menu_user: typeof ActionRowBuilder<UserSelectMenuBuilder>;
+  menu_channel: typeof ActionRowBuilder<ChannelSelectMenuBuilder>;
+  menu_mentionable: typeof ActionRowBuilder<MentionableSelectMenuBuilder>;
+  menu_role: typeof ActionRowBuilder<RoleSelectMenuBuilder>;
+};
+/**
+ * Available Discord.js builder types for use with BuilderComponent
+ */
+type BuilderType = keyof typeof BuilderTypes;
+/**
+ * @internal
+ */
+type InstantiatedBuilder<BuilderKey extends BuilderType> = InstanceType<(typeof BuilderTypes)[BuilderKey]>;
+/**
+ * Available Discord.js action row types for use with RowComponent
+ */
+type RowType = keyof typeof RowTypes;
+/**
+ * @internal
+ */
+type InstantiatedActionRow<RowKey extends RowType> = InstanceType<(typeof RowTypes)[RowKey]>;
+//#endregion
+//#region src/components/Component.d.ts
+/**
+ * Base class for Discord component wrappers.
+ *
+ * @typeParam TComponent - The Discord.js component type being wrapped
+ *
+ * @internal
+ */
+declare abstract class BaseComponent<TComponent> {
+  private readonly _component;
+  protected constructor(ComponentClass: new () => TComponent);
+  /**
+   * Returns the live builder, ready to send in a Discord message or nest in another component.
+   *
+   * Configure it through `this.instance`. Reading this can apply the bot color (see
+   * {@link BuilderComponent}), so it has a side effect.
+   * @example new SomeComponent().component
+   */
+  abstract get component(): InstantiatedBuilder<BuilderType> | InstantiatedActionRow<RowType>;
+  /**
+   * The wrapped builder, for calling Discord.js methods like setTitle() and setDescription() inside a subclass.
+   *
+   * @example this.instance.setTitle('My Modal')
+   */
+  protected get instance(): TComponent;
+}
+/**
+ * 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
+ */
+declare abstract class BuilderComponent<BuilderKey extends BuilderType> extends BaseComponent<InstantiatedBuilder<BuilderKey>> {
+  readonly type: BuilderKey;
+  private colorApplied;
+  protected constructor(type: BuilderKey);
+  get component(): InstantiatedBuilder<BuilderKey>;
+  private applyBotColor;
+}
+/**
+ * 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
+ */
+declare abstract class RowComponent<RowKey extends RowType> extends BaseComponent<InstantiatedActionRow<RowKey>> {
+  readonly type: RowKey;
+  protected constructor(type: RowKey);
+  get component(): InstantiatedActionRow<RowKey>;
+}
+//#endregion
+//#region src/customId/Field.d.ts
+/**
+ * One field in a customId shape, its wire kind plus the type it decodes to.
+ *
+ * @internal
+ */
+interface CustomIdField<Decoded> {
+  /** Which wire encoding this field uses. */
+  readonly kind: 'snowflake' | 'uuid' | 'int' | 'bool' | 'oneOf' | 'string';
+  /** Lower bound, for a bounded int field. */
+  readonly min?: number;
+  /** Upper bound, for a bounded int field. */
+  readonly max?: number;
+  /** The allowed values, for a oneOf field. */
+  readonly choices?: readonly string[];
+  /** Phantom only, carries the decoded type and is never set at runtime. */
+  readonly decoded?: Decoded;
+}
+/**
+ * The set of fields a customId carries, keyed by name.
+ *
+ * @internal
+ */
+type CustomIdShape = Record<string, CustomIdField<unknown>>;
+/**
+ * The decoded result, each field name mapped to its decoded type.
+ *
+ * @internal
+ */
+type DecodedParams<Shape extends CustomIdShape> = { [Name in keyof Shape]: Shape[Name] extends CustomIdField<infer Decoded> ? Decoded : never };
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.7.0/node_modules/type-fest/source/non-empty-tuple.d.ts
+/**
+Matches any non-empty tuple.
+
+@example
+```
+import type {NonEmptyTuple} from 'type-fest';
+
+const sum = (...numbers: NonEmptyTuple<number>) => numbers.reduce((total, value) => total + value, 0);
+
+sum(1, 2, 3);
+// Ok
+
+// @ts-expect-error
+sum();
+// Error: Expected at least 1 arguments, but got 0.
+```
+
+@see {@link RequireAtLeastOne} for objects
+
+@category Array
+*/
+type NonEmptyTuple<T = unknown> = readonly [T, ...T[]];
+//#endregion
+//#region src/customId/CustomId.d.ts
+/** Strip the layout hash off the routeKey to recover the stable prefix the controller routes by. @internal */
+declare function prefixOf(wire: string): string;
+/**
+ * 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);
+ * ```
+ */
+declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}> {
+  /** The stable route prefix, e.g. 'approve'. */
+  readonly prefix: Prefix;
+  /** Like a zod shape */
+  readonly shape: Shape;
+  /** The prefix plus a short hash of the shape, the part of the wire before the colon. */
+  readonly routeKey: string;
+  constructor(prefix: Prefix, shape?: Shape);
+  private add;
+  /**
+   * 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 extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<Snowflake>>>;
+  /**
+   * Add a UUID field, decoded as a lowercase uuid string.
+   *
+   * @example
+   * ```ts
+   * new CustomId('ticket').uuid('ticketId');
+   * ```
+   */
+  uuid<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
+  /**
+   * Add an integer field with no bounds, for a value up to 2^53.
+   *
+   * @example
+   * ```ts
+   * new CustomId('shop').int('amount');
+   * ```
+   */
+  int<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  /**
+   * Add an integer field bounded by min and max, so it packs into fewer characters on the wire.
+   *
+   * @example
+   * ```ts
+   * new CustomId('paginate').int('page', 1, 50);
+   * ```
+   */
+  int<Name extends string>(name: Name, min: number, max: number): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  /**
+   * Add a boolean flag.
+   *
+   * @example
+   * ```ts
+   * new CustomId('settings').bool('silent');
+   * ```
+   */
+  bool<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<boolean>>>;
+  /**
+   * 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 extends string, const Choices extends NonEmptyTuple<string>>(name: Name, choices: Choices): CustomId<Prefix, Shape & Record<Name, CustomIdField<Choices[number]>>>;
+  /**
+   * 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 extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<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: DecodedParams<Shape>): string;
+  /**
+   * 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: string): DecodedParams<Shape>;
+  /** True if this wire was minted from this customId's prefix, ignoring the shape hash. */
+  owns(wire: string): boolean;
+}
+/**
+ * Any customId, for places where the exact prefix and shape do not matter.
+ *
+ * @internal
+ */
+type AnyCustomId = CustomId<string, CustomIdShape>;
+/**
+ * The outcome of decoding a wire against several customIds, the matched prefix paired with its values.
+ *
+ * @internal
+ */
+type DecodedRoute<Defs extends readonly AnyCustomId[]> = { [Index in keyof Defs]: Defs[Index] extends AnyCustomId ? {
+  readonly prefix: Defs[Index]['prefix'];
+  readonly params: DecodedParams<Defs[Index]['shape']>;
+} : never }[number];
+/**
+ * Find the customId whose prefix owns this wire, decode against it, and report which one matched.
+ *
+ * @internal
+ */
+declare function decodeFor<Defs extends readonly AnyCustomId[]>(defs: Defs, wire: string): DecodedRoute<Defs>;
+//#endregion
+export { CustomIdField as a, RowComponent as c, prefixOf as i, BuilderType as l, CustomId as n, DecodedParams as o, decodeFor as r, BuilderComponent as s, AnyCustomId as t, RowType as u };
+//# sourceMappingURL=CustomId-BJF6mbJs.d.mts.map