@lunibee/builders 0.2.2 → 0.2.4

package/README.md

@@ -1,69 +1,69 @@
-# @lunibee/builders
-
-> Fluent, validated builders for embeds, components, modals, commands and attachments.
-
-```bash
-bun add @lunibee/builders
-```
-
-```ts
-import {
-    CreateEmbed,
-    CreateActionRow,
-    CreateButton,
-    ButtonType,
-    CreateStringSelectMenu,
-    CreateSlashCommand,
-} from "@lunibee/builders";
-
-const embed = new CreateEmbed()
-    .setTitle("Welcome")
-    .setDescription("Pick a role below.")
-    .setColor(0xf5c542)
-    .addFields([{ name: "Server", value: "Lunibee" }]);
-
-const buttons = new CreateActionRow().addComponents(
-    new CreateButton().setCustomId("yes").setLabel("Yes").setStyle(ButtonType.Success),
-);
-
-const menu = new CreateActionRow().addComponents(
-    new CreateStringSelectMenu()
-        .setCustomId("role")
-        .addOptions({ label: "Developer", value: "dev" }),
-);
-
-const ping = new CreateSlashCommand()
-    .setName("ping")
-    .setDescription("Replies with pong")
-    .addStringOption((option) => option.setName("message").setDescription("Echo text"));
-
-console.log(embed.toJSON(), buttons.toJSON(), menu.toJSON(), ping.toJSON());
-```
-
-## Builders
-
-| Area | Builders |
-|---|---|
-| Embeds | `CreateEmbed` |
-| Buttons & rows | `CreateButton`, `CreateActionRow` |
-| Select menus | `CreateStringSelect` (alias `CreateStringSelectMenu`), `CreateEntitySelect`, `CreateUserSelectMenu`, `CreateRoleSelectMenu`, `CreateChannelSelectMenu`, `CreateMentionableSelectMenu` |
-| Modals | `CreateModal`, `CreateTextInput` |
-| Slash commands | `CreateSlashCommand`, `CreateSubcommand`, `CreateSubcommandGroup`, option builders |
-| Context menus | `CreateContextMenuCommand` (`setType(2 \| 3)`), `CreateUserCommand`, `CreateMessageCommand` |
-| Components V2 | `CreateContainer`, `CreateSection`, `CreateTextDisplay`, `CreateMediaGallery`, `CreateFileComponent`, `CreateSeparator`, `CreateThumbnail` |
-| Files | `CreateAttachment` |
-
-Every builder validates Discord's limits as you set values and serialises with `toJSON()`.
-
-## What's new in 0.2.1
-
-- `CreateModal.addTextInputs(...inputs)` wraps each text input in its own row.
-- `componentsV2Message(components, options?)` builds a Components V2 message with the required flag.
-- `CreateEmbed` setters (`setTitle`, `setDescription`, `setURL`, `setThumbnail`, `setImage`) clear the field with `null`.
-- `TextInputType` and `ComponentEnum` are usable as types; `CreateModal.toJSON()` is typed with a required `custom_id` and `title`.
-
-## What's new in 0.2.0
-
-`toJSON()` validates whole components (required fields, value bounds, action-row rules, button field exclusivity); `CreateButton.setSKUId()` for premium buttons.
-
-Docs: https://lunibee.js.org/core-concepts/builders/
+# @lunibee/builders
+
+> Fluent, validated builders for embeds, components, modals, commands and attachments.
+
+```bash
+bun add @lunibee/builders
+```
+
+```ts
+import {
+    CreateEmbed,
+    CreateActionRow,
+    CreateButton,
+    ButtonType,
+    CreateStringSelectMenu,
+    CreateSlashCommand,
+} from "@lunibee/builders";
+
+const embed = new CreateEmbed()
+    .setTitle("Welcome")
+    .setDescription("Pick a role below.")
+    .setColor(0xf5c542)
+    .addFields([{ name: "Server", value: "Lunibee" }]);
+
+const buttons = new CreateActionRow().addComponents(
+    new CreateButton().setCustomId("yes").setLabel("Yes").setStyle(ButtonType.Success),
+);
+
+const menu = new CreateActionRow().addComponents(
+    new CreateStringSelectMenu()
+        .setCustomId("role")
+        .addOptions({ label: "Developer", value: "dev" }),
+);
+
+const ping = new CreateSlashCommand()
+    .setName("ping")
+    .setDescription("Replies with pong")
+    .addStringOption((option) => option.setName("message").setDescription("Echo text"));
+
+console.log(embed.toJSON(), buttons.toJSON(), menu.toJSON(), ping.toJSON());
+```
+
+## Builders
+
+| Area | Builders |
+|---|---|
+| Embeds | `CreateEmbed` |
+| Buttons & rows | `CreateButton`, `CreateActionRow` |
+| Select menus | `CreateStringSelect` (alias `CreateStringSelectMenu`), `CreateEntitySelect`, `CreateUserSelectMenu`, `CreateRoleSelectMenu`, `CreateChannelSelectMenu`, `CreateMentionableSelectMenu` |
+| Modals | `CreateModal`, `CreateTextInput` |
+| Slash commands | `CreateSlashCommand`, `CreateSubcommand`, `CreateSubcommandGroup`, option builders |
+| Context menus | `CreateContextMenuCommand` (`setType(2 \| 3)`), `CreateUserCommand`, `CreateMessageCommand` |
+| Components V2 | `CreateContainer`, `CreateSection`, `CreateTextDisplay`, `CreateMediaGallery`, `CreateFileComponent`, `CreateSeparator`, `CreateThumbnail` |
+| Files | `CreateAttachment` |
+
+Every builder validates Discord's limits as you set values and serialises with `toJSON()`.
+
+## What's new in 0.2.1
+
+- `CreateModal.addTextInputs(...inputs)` wraps each text input in its own row.
+- `componentsV2Message(components, options?)` builds a Components V2 message with the required flag.
+- `CreateEmbed` setters (`setTitle`, `setDescription`, `setURL`, `setThumbnail`, `setImage`) clear the field with `null`.
+- `TextInputType` and `ComponentEnum` are usable as types; `CreateModal.toJSON()` is typed with a required `custom_id` and `title`.
+
+## What's new in 0.2.0
+
+`toJSON()` validates whole components (required fields, value bounds, action-row rules, button field exclusivity); `CreateButton.setSKUId()` for premium buttons.
+
+Docs: https://lunibee.js.org/core-concepts/builders/

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@lunibee/builders",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@lunibee/types": "^0.2.4"
   }
 }

package/src/attachment.ts

@@ -1,79 +1,104 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-
-export interface AttachmentData {
-    name: string;
-    description?: string;
-    file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
-}
-
-/** Builder for message attachments and file uploads. */
-export class CreateAttachment {
-    public name: string;
-    public description?: string;
-    public file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
-
-    public constructor(
-        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
-        data?: Partial<Omit<AttachmentData, "file">> | string,
-    ) {
-        this.file = file;
-        if (typeof data === "string") {
-            this.name = data;
-        } else {
-            this.name =
-                data?.name ??
-                (typeof file === "string" ? basename(file) : "file.bin");
-            this.description = data?.description;
-        }
-    }
-
-    /** Sets the attachment filename. */
-    public setName(name: string): this {
-        this.name = name;
-        return this;
-    }
-
-    /** Sets the attachment description / alt text. */
-    public setDescription(description: string): this {
-        this.description = description;
-        return this;
-    }
-
-    /** Sets the file contents. */
-    public setFile(
-        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
-    ): this {
-        this.file = file;
-        return this;
-    }
-
-    /** Resolves the attachment payload to a binary Uint8Array. */
-    public async toBuffer(): Promise<Uint8Array> {
-        if (typeof this.file === "string") {
-            const buffer = await readFile(this.file);
-            return new Uint8Array(buffer);
-        }
-        if (this.file instanceof Uint8Array) return this.file;
-        if (this.file instanceof ArrayBuffer) return new Uint8Array(this.file);
-        if (this.file instanceof Blob) {
-            const buf = await this.file.arrayBuffer();
-            return new Uint8Array(buf);
-        }
-        if (typeof Buffer !== "undefined" && Buffer.isBuffer(this.file)) {
-            return new Uint8Array(this.file);
-        }
-        throw new TypeError(
-            "Attachment file must be a supported binary value or file path.",
-        );
-    }
-}
-
-// ─── Deprecated names (0.2.2), removed in 2.0 ────────────────────────────────
-// Builders are now `CreateX` (`ButtonBuilder` → `CreateButton`); `…Style` became
-// `…Type` and `…Type` became `…Enum`.
-
-/** @deprecated Use {@link CreateAttachment}. Removed in 2.0. */
-export const AttachmentBuilder = CreateAttachment;
-/** @deprecated Use {@link CreateAttachment}. Removed in 2.0. */
-export type AttachmentBuilder = CreateAttachment;
+import { readFile, realpath } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+export interface AttachmentData {
+    name: string;
+    description?: string;
+    file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
+    /**
+     * Folder a string `file` must stay inside (symlinks included). Set it
+     * whenever the path is not one you wrote yourself, e.g. from a command
+     * option: without it, any readable file on the machine can be uploaded.
+     */
+    root?: string;
+}
+
+/** Builder for message attachments and file uploads. */
+export class CreateAttachment {
+    public name: string;
+    public description?: string;
+    public file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
+    /** Folder a string `file` must stay inside; see {@link AttachmentData.root}. */
+    public root?: string;
+
+    public constructor(
+        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
+        data?: Partial<Omit<AttachmentData, "file">> | string,
+    ) {
+        this.file = file;
+        if (typeof data === "string") {
+            this.name = data;
+        } else {
+            this.name =
+                data?.name ??
+                (typeof file === "string" ? basename(file) : "file.bin");
+            this.description = data?.description;
+            this.root = data?.root;
+        }
+    }
+
+    /** Sets the attachment filename. */
+    public setName(name: string): this {
+        this.name = name;
+        return this;
+    }
+
+    /** Sets the attachment description / alt text. */
+    public setDescription(description: string): this {
+        this.description = description;
+        return this;
+    }
+
+    /** Sets the file contents. */
+    public setFile(
+        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
+    ): this {
+        this.file = file;
+        return this;
+    }
+
+    /** Resolves the attachment payload to a binary Uint8Array. */
+    public async toBuffer(): Promise<Uint8Array> {
+        if (typeof this.file === "string") {
+            const path =
+                this.root === undefined
+                    ? this.file
+                    : await insideRoot(this.root, this.file);
+            const buffer = await readFile(path);
+            return new Uint8Array(buffer);
+        }
+        if (this.file instanceof Uint8Array) return this.file;
+        if (this.file instanceof ArrayBuffer) return new Uint8Array(this.file);
+        if (this.file instanceof Blob) {
+            const buf = await this.file.arrayBuffer();
+            return new Uint8Array(buf);
+        }
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(this.file)) {
+            return new Uint8Array(this.file);
+        }
+        throw new TypeError(
+            "Attachment file must be a supported binary value or file path.",
+        );
+    }
+}
+
+// ─── Deprecated names (0.2.2), removed in 0.3.0 ────────────────────────────────
+// Builders are now `CreateX` (`ButtonBuilder` → `CreateButton`); `…Style` became
+// `…Type` and `…Type` became `…Enum`.
+
+/** @deprecated Use {@link CreateAttachment}. Removed in 0.3.0. */
+export const AttachmentBuilder = CreateAttachment;
+/** @deprecated Use {@link CreateAttachment}. Removed in 0.3.0. */
+export type AttachmentBuilder = CreateAttachment;
+
+/** Resolves `file` against `root`, refusing anything outside it (after following symlinks). */
+async function insideRoot(root: string, file: string): Promise<string> {
+    const base = await realpath(root);
+    const target = await realpath(resolve(base, file)).catch(() => {
+        throw new Error("Attachment file was not found inside its root.");
+    });
+    const rel = relative(base, target);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        throw new Error("Attachment file is outside its root folder.");
+    return target;
+}