@magicyan/discord 1.3.1 → 1.4.1

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as discord_js from 'discord.js';
-import { GatewayIntentBits, Partials, Attachment, AttachmentBuilder, EmbedAssetData, Guild, GuildMember, User, ClientUser, ImageURLOptions, EmbedFooterData, ColorResolvable, APIEmbed, Embed, EmbedData, EmbedBuilder, AttachmentData, AnyComponentBuilder, ActionRowBuilder, ButtonBuilder, LinkButtonComponentData, ChannelType, CommandInteractionOption, Client, ApplicationCommand, TextInputBuilder, ModalSubmitInteraction, ModalSubmitFields, Collection, TextInputComponent, TextInputStyle, TextInputComponentData, GuildEmoji, GuildTextBasedChannel, Message, Role, WebhookClientOptions, WebhookClient, WebhookClientData } from 'discord.js';
+import { GatewayIntentBits, Partials, Attachment, AttachmentBuilder, EmbedAssetData, Guild, GuildMember, User, ClientUser, ImageURLOptions, EmbedFooterData, ColorResolvable, APIEmbed, Embed, EmbedData, EmbedBuilder, AttachmentData, ButtonBuilder, LinkButtonComponentData, AnyComponentBuilder, ActionRowBuilder, FileBuilder, APIUnfurledMediaItem, MediaGalleryBuilder, MediaGalleryItemData, SeparatorBuilder, ThumbnailComponentData, ThumbnailBuilder, SectionBuilder, TextDisplayBuilder, MessageActionRowComponentBuilder, ContainerBuilder, Colors, ContainerComponentData, RGBTuple, ChannelType, CommandInteractionOption, Client, ApplicationCommand, TextInputBuilder, ModalSubmitInteraction, ModalSubmitFields, Collection, TextInputComponent, TextInputStyle, TextInputComponentData, GuildEmoji, GuildTextBasedChannel, Message, Role, WebhookClientOptions, WebhookClient, WebhookClientData, StringSelectMenuBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder } from 'discord.js';
+import * as _discordjs_builders from '/home/rinckodev/projects/npm/magicyan/node_modules/@discordjs/builders/dist/index.d.ts';
 export * from '@magicyan/core';
 
 declare const chars: {
@@ -112,7 +113,7 @@ type EmbedPlusFooterData = {
     text?: string | null;
     iconURL?: string | null;
 };
-declare function createEmbedFooter(options: EmbedPlusFooterData): EmbedFooterData | undefined;
+declare function createEmbedFooter(options: string | EmbedPlusFooterData): EmbedFooterData | undefined;
 
 type EmbedPlusBuilderReturn<B> = undefined extends B ? EmbedPlusBuilder : false extends B ? EmbedPlusBuilder : EmbedPlusBuilder[];
 type EmbedPlusColorData = string & {} | ColorResolvable | null;
@@ -121,18 +122,19 @@ type EmbedPlusAuthorData = {
     url?: string;
     iconURL?: string;
 };
+type MaybeString = string | null | undefined;
 interface EmbedPlusData {
     title?: string | null;
     color?: EmbedPlusColorData | null;
-    description?: string | null;
+    description?: MaybeString | MaybeString[];
     url?: string | null | {
         toString(): string;
     };
     thumbnail?: EmbedPlusAssetData;
     image?: EmbedPlusAssetData;
     fields?: Partial<EmbedPlusFieldData>[] | null;
-    timestamp?: string | number | Date | null;
-    footer?: EmbedPlusFooterData;
+    timestamp?: string | number | Date | null | boolean;
+    footer?: EmbedPlusFooterData | string;
     author?: EmbedPlusAuthorData;
 }
 type AnyEmbedData = APIEmbed | Embed | EmbedData;
@@ -178,11 +180,289 @@ interface CreateEmbedFilesOptions {
  */
 declare function createEmbedFiles(embed: EmbedBuilder, options?: CreateEmbedFilesOptions): AttachmentBuilder[];
 
-declare function createRow<Component extends AnyComponentBuilder>(...components: Component[]): ActionRowBuilder<Component>;
 interface CreateLinkButtonData extends Omit<LinkButtonComponentData, "style" | "type"> {
 }
 declare function createLinkButton(data: CreateLinkButtonData): ButtonBuilder;
 
+declare function createRow<Component extends AnyComponentBuilder>(...components: Component[]): ActionRowBuilder<Component>;
+
+type FileSource = string | Attachment | AttachmentBuilder;
+interface CreateFileOptions extends Omit<APIUnfurledMediaItem, "url"> {
+    spoiler?: boolean;
+}
+/**
+ * Creates a {@link FileBuilder} from an {@link AttachmentBuilder} or an attachment reference string.
+ *
+ * If the `source` is an {@link AttachmentBuilder}, it automatically prefixes the file name with `"attachment://"`.
+ * If the `source` is a string, it must already be a valid attachment reference in the format `"attachment://filename.ext"`.
+ *
+ * You can optionally provide file metadata through the `options` parameter, such as dimensions
+ * or whether the file should be marked as a spoiler.
+ *
+ * @param source - The source of the file. Must be an {@link AttachmentBuilder} or an attachment reference string.
+ * @param options - Optional metadata for the file, such as `width`, `height`, `spoiler`, and `size`.
+ *
+ * @returns A {@link FileBuilder} ready to be used inside a message component.
+ *
+ * @example
+ * // Creating a file from an AttachmentBuilder
+ * const attachmentBuilder = new AttachmentBuilder("path/to/image.png");
+ * const file = createFile(attachmentBuilder);
+ *
+ * @example
+ * // Creating a file from an attachment reference string
+ * const file = createFile("attachment://image.png");
+ *
+ * @example
+ * // Creating a file with additional options like marking it as a spoiler
+ * const file = createFile("attachment://secret.png", { spoiler: true });
+ */
+declare function createFile(source: FileSource, options?: CreateFileOptions): FileBuilder;
+
+type MediaGallerySource = MediaGalleryItemData | string | Attachment | AttachmentBuilder;
+/**
+ * Creates a {@link MediaGalleryBuilder} instance with a collection of media items, which can be images, attachments, or URLs.
+ *
+ * This function allows you to add multiple media items to a gallery, where each item can be a URL,
+ * an {@link Attachment}, or an {@link AttachmentBuilder}. It processes each item and adds it to the gallery,
+ * converting it into the appropriate format for rendering.
+ *
+ * **Parameters:**
+ * - `items`: An array of media items to be added to the gallery. Each item can be:
+ *   - A {@link MediaGalleryItemData} object, which includes media information such as URLs.
+ *   - A string URL pointing to an external resource (e.g., an image URL).
+ *   - An {@link Attachment} or {@link AttachmentBuilder}, which are Discord attachments.
+ *
+ * @param items - The media items to be added to the gallery. Each item is processed and converted into a format suitable for the gallery.
+ *
+ * @returns A {@link MediaGalleryBuilder} instance populated with the specified media items.
+ *
+ * @example
+ * // Creating a media gallery with URLs and an attachment
+ * const gallery = createMediaGallery(
+ *   "https://example.com/image1.png",
+ *   new AttachmentBuilder("image2.png", { name: "image2.png" }),
+ *   { media: { url: "https://example.com/image3.png" } }
+ * );
+ *
+ * @example
+ * // Creating a media gallery with only attachments
+ * const gallery = createMediaGallery(
+ *   new AttachmentBuilder("file1.png", { name: "file1.png" }),
+ *   new AttachmentBuilder("file2.png", { name: "file2.png" })
+ * );
+ *
+ * @example
+ * // Creating a media gallery with mixed media types (URL and attachment)
+ * const gallery = createMediaGallery(
+ *   "https://example.com/image1.png",
+ *   new AttachmentBuilder("image2.png", { name: "image2.png" })
+ * );
+ *
+ */
+declare function createMediaGallery(...items: MediaGallerySource[]): MediaGalleryBuilder;
+
+interface SeparatorData {
+    divider?: boolean;
+    large?: boolean;
+}
+/**
+ * Creates a {@link SeparatorBuilder} component with customizable options for visibility and spacing.
+ *
+ * This function generates a separator that can be configured to either be visible or disabled,
+ * and can have either small or large spacing between components. The default settings are for a
+ * visible separator with small spacing.
+ *
+ * **Parameters:**
+ * - `divider` (optional): If `false`, the separator divider will be disabled and won't be rendered. Default is `true`.
+ * - `large` (optional): If `true`, the separator will have a large spacing. Default is `false` (small spacing).
+ *
+ * @param data - An object containing the optional properties `divider` and `large` to configure the separator.
+ *
+ * @returns A {@link SeparatorBuilder} instance with the specified configuration.
+ *
+ * @example
+ * // Creating a separator with default settings (visible and small spacing)
+ * const separator = createSeparator();
+ *
+ * @example
+ * // Creating a disabled separator divider (not visible)
+ * const separator = createSeparator({ divider: false });
+ *
+ * @example
+ * // Creating a separator with large spacing
+ * const separator = createSeparator({ large: true });
+ */
+declare function createSeparator(data?: SeparatorData): SeparatorBuilder;
+
+type ThumbnailData = Partial<Omit<ThumbnailComponentData, "type">> | Attachment | AttachmentBuilder | string;
+/**
+ * Creates a {@link ThumbnailBuilder} from a URL, an attachment, or partial thumbnail data.
+ *
+ * This function helps create a thumbnail component for a container.
+ * It supports different input formats, such as a direct URL string,
+ * an {@link AttachmentBuilder}, an {@link Attachment}, or a partial {@link ThumbnailComponentData}.
+ *
+ * **Important:**
+ * - If providing a string, it must either be a valid URL or a reference to an attachment using the `attachment://filename.ext` format.
+ *
+ * @param data - The thumbnail source: a URL, an attachment builder, an attachment, or partial thumbnail data.
+ *
+ * @returns A {@link ThumbnailBuilder} instance populated with the provided data.
+ *
+ * @example
+ * // Creating a thumbnail from a URL
+ * const thumbnail = createThumbnail("https://example.com/image.png");
+ *
+ * @example
+ * // Creating a thumbnail from partial data
+ * const thumbnail = createThumbnail({
+ *   media: { url: "attachment://image.png" },
+ *   spoiler: true
+ * });
+ */
+declare function createThumbnail(data: ThumbnailData): ThumbnailBuilder;
+
+type SectionAcessoryData = {
+    button?: never;
+    thumbnail: ThumbnailData;
+} | {
+    button: ButtonBuilder;
+    thumbnail?: never;
+};
+type SectionData = SectionAcessoryData & {
+    content: string | string[];
+};
+/**
+ * Creates a {@link SectionBuilder} component with customizable content, thumbnail, and optional button.
+ *
+ * This function generates a section that can either have a button, a thumbnail, or both as accessories,
+ * along with the provided content. The content can be a single string or an array of strings.
+ * If both a button and a thumbnail are provided, only one can be set, as specified in the types.
+ *
+ * **Parameters:**
+ * - `content`: The main content of the section. This can either be a single string or an array of strings to be displayed.
+ * - `button` (optional): A {@link ButtonBuilder} instance to be added as a button accessory. If provided, no thumbnail can be set.
+ * - `thumbnail` (optional): A {@link ThumbnailData} object to set as the thumbnail accessory. If provided, no button can be set.
+ *
+ * @param data - An object containing the properties `content`, `button`, and `thumbnail` for configuring the section.
+ *
+ * @returns A {@link SectionBuilder} instance with the specified configuration.
+ *
+ * @example
+ * // Creating a section with a success button
+ * const section = createSection({
+ *   content: "Welcome to the section!",
+ *   button: new ButtonBuilder({
+ *     customId: "welcome/button",
+ *     label: "Click Me",
+ *     style: ButtonStyle.Success,
+ *   }),
+ * });
+ *
+ * @example
+ * // Creating a section with a thumbnail and content
+ * const section = createSection({
+ *   content: "This is a section with a thumbnail.",
+ *   thumbnail: "https://example.com/image.png"
+ * });
+ *
+ * @example
+ * // Creating a section with an array of content strings and a thumbnail
+ * const section = createSection({
+ *   content: ["Line 1", "Line 2", "Line 3"],
+ *   thumbnail: "https://example.com/image.png"
+ * });
+ */
+declare function createSection(data: SectionData): SectionBuilder;
+
+/**
+ * Creates a {@link TextDisplayBuilder} with the given content and optional ID.
+ *
+ * This function simplifies the creation of text display components for a container,
+ * allowing you to set the text content and optionally assign a custom ID.
+ *
+ * @param content - The text content to display.
+ * @param id - An optional numeric ID for the text component.
+ *
+ * @returns A new {@link TextDisplayBuilder} instance containing the provided content and ID.
+ *
+ * @example
+ * // Creating a simple text display component
+ * const textDisplay = createTextDisplay("Hello World!");
+ *
+ * @example
+ * // Creating a text display component with a custom ID
+ * const textDisplay = createTextDisplay("Welcome!", 123);
+ */
+declare function createTextDisplay(content: string, id?: number): TextDisplayBuilder;
+
+type ComponentData = TextDisplayBuilder | SeparatorBuilder | FileBuilder | SectionBuilder | MediaGalleryBuilder | ActionRowBuilder<MessageActionRowComponentBuilder> | MessageActionRowComponentBuilder[] | MessageActionRowComponentBuilder | AttachmentBuilder | AttachmentBuilder | string | null | undefined;
+declare function createComponents(...data: (ComponentData | ContainerBuilder)[]): (TextDisplayBuilder | SeparatorBuilder | FileBuilder | SectionBuilder | MediaGalleryBuilder | ActionRowBuilder<MessageActionRowComponentBuilder> | _discordjs_builders.ButtonBuilder | ContainerBuilder | undefined)[];
+
+type PresetColor = keyof typeof Colors;
+interface ContainerData extends Omit<ContainerComponentData, "accentColor" | "type" | "components"> {
+    accentColor?: (string & {}) | number | null | RGBTuple | PresetColor;
+    components: ComponentData[];
+}
+/**
+ * Creates a {@link ContainerBuilder} component with customizable accent color and components.
+ *
+ * This function generates a container that can include various components such as text displays, action rows,
+ * buttons, media galleries, and more. The container also allows for setting an accent color, which can be
+ * either a string (hex color), a number, a predefined color, or an RGB tuple.
+ *
+ * **Parameters:**
+ * - `accentColor` (optional): The accent color for the container. This can be:
+ *   - A hexadecimal color code (string) such as `"#ff5733"`.
+ *   - A numeric value representing the color.
+ *   - An {@link RGBTuple} (an array of three numbers representing RGB values).
+ *   - A predefined color from the {@link Colors} enum (e.g., `Colors.Red`).
+ * - `components`: An array of components that can be added to the container. These components can be:
+ *   - {@link TextDisplayBuilder}, a string, {@link ActionRowBuilder}, {@link ButtonBuilder},
+ *   - {@link SectionBuilder}, {@link MediaGalleryBuilder}, {@link FileBuilder}, or
+ *   - {@link SeparatorBuilder}. Attachments are also accepted and will be handled as media galleries.
+ *
+ * @param data - An object containing the properties `accentColor` and `components` for configuring the container.
+ *
+ * @returns A {@link ContainerBuilder} instance with the specified configuration.
+ *
+ * @example
+ * // Creating a container with an accent color and a text display component
+ * const container = createContainer({
+ *   accentColor: "#ff5733", // Hex color code
+ *   components: [
+ *     "This is a text display component"
+ *   ]
+ * });
+ *
+ * @example
+ * // Creating a container with predefined color and an action row containing a button
+ * const container = createContainer({
+ *   accentColor: Colors.Green, // Predefined color from Colors enum
+ *   components: [
+ *       createSection({
+ *          content: "-# Increment counter",
+ *          button: new ButtonBuilder({
+ *              customId: `counter/increment`,
+ *              label: "+",
+ *              style: ButtonStyle.Success
+ *          })
+ *      }),
+ *   ]
+ * });
+ *
+ * @example
+ * // Creating a container with an RGB tuple as the accent color
+ * const container = createContainer({
+ *   accentColor: [255, 87, 51], // RGB tuple
+ *   components: [
+ *     "Here's some content."
+ *   ]
+ * });
+ */
+declare function createContainer(data: ContainerData): ContainerBuilder;
+
 type GuildChannelType = Exclude<ChannelType, ChannelType.DM>;
 type FindChannelFilter<T extends GuildChannelType> = (channel: GetChannelType<T>) => boolean;
 type GetChannelType<Type extends GuildChannelType> = Extract<NonNullable<CommandInteractionOption<"cached">["channel"]>, {
@@ -311,4 +591,10 @@ declare function extractMentionId(mention: string): string | null;
 declare function createWebhookClient(url: string, options?: WebhookClientOptions): WebhookClient | null;
 declare function createWebhookClient(data: WebhookClientData, options?: WebhookClientOptions): WebhookClient | null;
 
-export { type AnyEmbedData, CustomItents, CustomPartials, EmbedLimit, type EmbedPlusAssetData, type EmbedPlusAuthorData, EmbedPlusBuilder, type EmbedPlusColorData, type EmbedPlusData, type EmbedPlusFooterData, type EmbedPlusProperty, chars, commandMention, createEmbed, createEmbedAsset, createEmbedAuthor, createEmbedFiles, createEmbedFooter, createLinkButton, createModalFields, createModalInput, createRow, createWebhookClient, extractMentionId, findChannel, findCommand, findEmoji, findMember, findMessage, findRole, getChannelUrlInfo, getMessageUrlInfo, modalFieldsToRecord, setMobileStatus };
+declare function isAttachment(value: unknown): value is Attachment | AttachmentBuilder;
+
+type AnySelectMenuBuilder = StringSelectMenuBuilder | UserSelectMenuBuilder | RoleSelectMenuBuilder | ChannelSelectMenuBuilder | MentionableSelectMenuBuilder;
+declare function isAnySelectMenuBuilder(value: unknown): value is AnySelectMenuBuilder;
+
+export { CustomItents, CustomPartials, EmbedLimit, EmbedPlusBuilder, chars, commandMention, createComponents, createContainer, createEmbed, createEmbedAsset, createEmbedAuthor, createEmbedFiles, createEmbedFooter, createFile, createLinkButton, createMediaGallery, createModalFields, createModalInput, createRow, createSection, createSeparator, createTextDisplay, createThumbnail, createWebhookClient, extractMentionId, findChannel, findCommand, findEmoji, findMember, findMessage, findRole, getChannelUrlInfo, getMessageUrlInfo, isAnySelectMenuBuilder, isAttachment, modalFieldsToRecord, setMobileStatus };
+export type { AnyEmbedData, AnySelectMenuBuilder, ComponentData, ContainerData, EmbedPlusAssetData, EmbedPlusAuthorData, EmbedPlusColorData, EmbedPlusData, EmbedPlusFooterData, EmbedPlusProperty, PresetColor, SectionAcessoryData, SectionData, SeparatorData, ThumbnailData };