dschook 1.0.0

package/lib/Webhook.d.ts

@@ -0,0 +1,242 @@
+import { Attachment } from "./attachment.js";
+import { Component } from "./components.js";
+export declare class Webhook {
+    #private;
+    /** Declarative, functional API for composing ComponentsV2. */
+    static components: {
+        section: (components: Component[]) => {
+            type: 9;
+            components: Component[];
+        };
+        text: (content: string) => {
+            type: 10;
+            content: string;
+        };
+        thumbnail: (url: string, description?: string, spoiler?: boolean) => {
+            type: 11;
+            media: {
+                url: string;
+            };
+            description?: string;
+            spoiler?: boolean;
+        };
+        media: (url: string, description?: string, spoiler?: boolean) => {
+            media: {
+                url: string;
+            };
+            description?: string;
+            spoiler?: boolean;
+        };
+        media_gallery: (...items: {
+            media: {
+                url: string;
+            };
+            description?: string;
+            spoiler?: boolean;
+        }[]) => {
+            type: 12;
+            items: {
+                media: {
+                    url: string;
+                };
+                description?: string;
+                spoiler?: boolean;
+            }[];
+        };
+        file: (url: string, spoiler?: boolean) => {
+            type: 13;
+            file: {
+                url: string;
+            };
+            spoiler?: boolean;
+        };
+        separator: (divider?: boolean, spacing?: 1 | 2) => {
+            type: 14;
+            divider?: boolean;
+            spacing?: 1 | 2;
+        };
+        container: (accent_color?: number, spoiler?: boolean, ...components: ({
+            type: 9;
+            components: Component[];
+        } | {
+            type: 10;
+            content: string;
+        } | {
+            type: 12;
+            items: {
+                media: {
+                    url: string;
+                };
+                description?: string;
+                spoiler?: boolean;
+            }[];
+        } | {
+            type: 13;
+            file: {
+                url: string;
+            };
+            spoiler?: boolean;
+        } | {
+            type: 14;
+            divider?: boolean;
+            spacing?: 1 | 2;
+        })[]) => {
+            type: 17;
+            components: ({
+                type: 9;
+                components: Component[];
+            } | {
+                type: 10;
+                content: string;
+            } | {
+                type: 12;
+                items: {
+                    media: {
+                        url: string;
+                    };
+                    description?: string;
+                    spoiler?: boolean;
+                }[];
+            } | {
+                type: 13;
+                file: {
+                    url: string;
+                };
+                spoiler?: boolean;
+            } | {
+                type: 14;
+                divider?: boolean;
+                spacing?: 1 | 2;
+            })[];
+            accent_color?: number;
+            spoiler?: boolean;
+        };
+    };
+    /** Utility functions for Discord's integer color formatting. */
+    static colors: {
+        hexCode: (code: string) => number;
+        rgb: (r: number, g: number, b: number) => number;
+        hsl: (h: number, s: number, l: number) => number;
+        hsv: (h: number, s: number, v: number) => number;
+    };
+    /** @param url Discord webhook URL */
+    constructor(url: string);
+    /**
+     * Send the next message with a different username and/or avatar.
+     * Re-returns the Webhook instance for method chaining.
+     */
+    as_user(username?: string, avatar_url?: string): this;
+    /**
+     * Send the next message in a new thread.
+     * Note: Will only work if the webhook is in a forum.
+     * @param thread_name name for the new created thread
+     * @param applied_tags Snowflakes for forum tags to be applied to the thread
+     */
+    in_thread(thread_name: string, applied_tags?: string[]): this;
+    /**
+     * Enable/disable TTS for the next message.
+     * Re-returns the Webhook instance for method chaining.
+     */
+    with_tts(tts?: boolean): this;
+    /**
+     * Send a message with one or more content types.
+     * Note that the presence of components will override any other contents.
+     */
+    send(contents: WebhookContents): void;
+    /** Send a text message. */
+    send_text(content: string): void;
+    /** Send a message with 1-10 rich embeds. */
+    send_embed(...embeds: Embed[]): void;
+    /**
+     * Send a message with one or more ComponentsV2.
+     * Use the static `Webhook.components` for a declarative functional API for constructing components.
+     */
+    send_components(...components: Component[]): void;
+    /** Send a poll message. */
+    send_poll(question: string, answers: (string | {
+        text: string;
+        emoji_id?: string;
+        emoji_name?: string;
+    })[], duration_hours?: number, allow_multiselect?: boolean): void;
+}
+export { Component };
+export type WebhookBody = WebhookContents & {
+    username?: string;
+    avatar_url?: string;
+    tts?: boolean;
+    allowed_mentions?: {};
+    payload_json?: string;
+    attachments?: Attachment[];
+    flags?: number;
+    thread_name?: string;
+    applied_tags?: string[];
+};
+export type WebhookContents = Partial<{
+    content: string;
+    embeds: Embed[];
+    files: File[];
+    poll: Poll;
+    components: Component[];
+}>;
+export type Poll = {
+    question: {
+        text: string;
+    };
+    answers: PollAnswer[];
+    duration?: number;
+    allow_multiselect?: boolean;
+};
+export type PollAnswer = {
+    poll_media: {
+        text: string;
+        emoji?: Partial<{
+            name: string;
+            id: string;
+        }>;
+    };
+};
+export type Embed = {
+    title?: string;
+    description?: string;
+    url?: string;
+    timestamp?: string;
+    color?: number;
+    footer?: EmbedFooter;
+    image?: EmbedMedia;
+    thumbnail?: EmbedMedia;
+    video?: EmbedMedia;
+    provider?: EmbedProvider;
+    author?: EmbedAuthor;
+    fields?: EmbedField[];
+};
+type EmbedFooter = {
+    text: string;
+    icon_url?: string;
+    proxy_icon_url?: string;
+};
+type EmbedMedia = {
+    url: string;
+    proxy_url?: string;
+    height?: number;
+    width?: number;
+    content_type?: number;
+    placeholder?: string;
+    placeholder_version?: number;
+    description?: string;
+    flags?: 32;
+};
+type EmbedProvider = {
+    name?: string;
+    url?: string;
+};
+type EmbedAuthor = {
+    name: string;
+    url?: string;
+    icon_url?: string;
+    proxy_icon_url?: string;
+};
+type EmbedField = {
+    name: string;
+    value: string;
+    inline?: boolean;
+};

package/lib/Webhook.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhook = void 0;
+const color_js_1 = require("./color.js");
+const components_js_1 = require("./components.js");
+class Webhook {
+    /** Declarative, functional API for composing ComponentsV2. */
+    static components = components_js_1.components;
+    /** Utility functions for Discord's integer color formatting. */
+    static colors = color_js_1.colors;
+    // Internal fields and modifiers
+    #url;
+    #tts = undefined;
+    #as_user = {};
+    #in_thread = {};
+    /** @param url Discord webhook URL */
+    constructor(url) {
+        this.#url = url;
+    }
+    /**
+     * Send the next message with a different username and/or avatar.
+     * Re-returns the Webhook instance for method chaining.
+     */
+    as_user(username, avatar_url) {
+        this.#as_user.username = username;
+        if (avatar_url)
+            this.#as_user.avatar_url = avatar_url;
+        return this;
+    }
+    /**
+     * Send the next message in a new thread.
+     * Note: Will only work if the webhook is in a forum.
+     * @param thread_name name for the new created thread
+     * @param applied_tags Snowflakes for forum tags to be applied to the thread
+     */
+    in_thread(thread_name, applied_tags) {
+        this.#in_thread.thread_name = thread_name;
+        if (applied_tags)
+            this.#in_thread.applied_tags = applied_tags;
+        return this;
+    }
+    /**
+     * Enable/disable TTS for the next message.
+     * Re-returns the Webhook instance for method chaining.
+     */
+    with_tts(tts = true) {
+        this.#tts = tts;
+        return this;
+    }
+    /**
+     * Send a message with one or more content types.
+     * Note that the presence of components will override any other contents.
+     */
+    send(contents) { this.#send_raw(contents); }
+    /** Send a text message. */
+    send_text(content) { this.#send_raw({ content }); }
+    /** Send a message with 1-10 rich embeds. */
+    send_embed(...embeds) { this.#send_raw({ embeds }); }
+    /**
+     * Send a message with one or more ComponentsV2.
+     * Use the static `Webhook.components` for a declarative functional API for constructing components.
+     */
+    send_components(...components) { this.#send_raw({ components }); }
+    /** Send a poll message. */
+    send_poll(question, answers, duration_hours, allow_multiselect) {
+        let poll_answers = answers.map((answer, i) => {
+            if (typeof answer == "string")
+                return { poll_media: { text: answer } };
+            let ans = { poll_media: { text: answer.text } };
+            if (answer.emoji_name)
+                ans.poll_media.emoji = { name: answer.emoji_name };
+            if (answer.emoji_id)
+                ans.poll_media.emoji = { id: answer.emoji_id };
+            return ans;
+        });
+        let poll = { question: { text: question }, answers: poll_answers };
+        if (typeof duration_hours == "number")
+            poll.duration = duration_hours;
+        if (typeof allow_multiselect == "boolean")
+            poll.allow_multiselect = allow_multiselect;
+        this.#send_raw({ poll });
+    }
+    // Internal send function that sets the appropriate parameters and resets temporary modifiers after making the request.
+    #send_raw(body) {
+        let url = this.#url;
+        if (body.components) {
+            url += "?with_components=true";
+            body.flags = (body.flags ?? 0) | components_js_1.IS_COMPONENTS_V2;
+        }
+        if (typeof this.#tts == "boolean")
+            body.tts = this.#tts;
+        fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                ...this.#as_user,
+                ...this.#in_thread,
+                ...body
+            })
+        }).then(async (response) => {
+            if (response.status > 399)
+                console.warn("[DiscordWebhook] Webhook execution returned error code", response.status, await response.json());
+        });
+        this.#as_user = this.#in_thread = {};
+        this.#tts = undefined;
+    }
+}
+exports.Webhook = Webhook;

package/lib/attachment.d.ts

@@ -0,0 +1,2 @@
+export type Attachment = {};
+export type File = {};

package/lib/attachment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/color.d.ts

@@ -0,0 +1,6 @@
+export declare const colors: {
+    hexCode: (code: string) => number;
+    rgb: (r: number, g: number, b: number) => number;
+    hsl: (h: number, s: number, l: number) => number;
+    hsv: (h: number, s: number, v: number) => number;
+};

package/lib/color.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colors = void 0;
+exports.colors = {
+    hexCode: (code) => parseInt(code.startsWith('#') ? code.slice(1) : code, 16),
+    rgb: (r, g, b) => (r << 16) | (g << 8) | b,
+    hsl: (h, s, l) => {
+        const k = (n) => (n + h / 30) % 12;
+        const a = s * Math.min(l, 1 - l);
+        const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+        const r = Math.round(255 * f(0));
+        const g = Math.round(255 * f(8));
+        const b = Math.round(255 * f(4));
+        return (r << 16) | (g << 8) | b;
+    },
+    hsv: (h, s, v) => {
+        const c = v * s;
+        const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+        const m = v - c;
+        let r = 0, g = 0, b = 0;
+        if (h < 60) {
+            r = c;
+            g = x;
+            b = 0;
+        }
+        else if (h < 120) {
+            r = x;
+            g = c;
+            b = 0;
+        }
+        else if (h < 180) {
+            r = 0;
+            g = c;
+            b = x;
+        }
+        else if (h < 240) {
+            r = 0;
+            g = x;
+            b = c;
+        }
+        else if (h < 300) {
+            r = x;
+            g = 0;
+            b = c;
+        }
+        else {
+            r = c;
+            g = 0;
+            b = x;
+        }
+        r = Math.round((r + m) * 255);
+        g = Math.round((g + m) * 255);
+        b = Math.round((b + m) * 255);
+        return (r << 16) | (g << 8) | b;
+    },
+};

package/lib/components.d.ts

@@ -0,0 +1,56 @@
+export declare const IS_COMPONENTS_V2: number;
+export type Component = Section | TextDisplay | Thumbnail | MediaGallery | File | Separator | Container;
+type Section = {
+    type: 9;
+    components: Component[];
+};
+type TextDisplay = {
+    type: 10;
+    content: string;
+};
+type Thumbnail = {
+    type: 11;
+    media: UnfurledMediaItem;
+    description?: string;
+    spoiler?: boolean;
+};
+type MediaGallery = {
+    type: 12;
+    items: MediaGalleryItem[];
+};
+type File = {
+    type: 13;
+    file: UnfurledMediaItem;
+    spoiler?: boolean;
+};
+type Separator = {
+    type: 14;
+    divider?: boolean;
+    spacing?: 1 | 2;
+};
+type Container = {
+    type: 17;
+    components: ContainerChild[];
+    accent_color?: number;
+    spoiler?: boolean;
+};
+type UnfurledMediaItem = {
+    url: string;
+};
+type MediaGalleryItem = {
+    media: UnfurledMediaItem;
+    description?: string;
+    spoiler?: boolean;
+};
+type ContainerChild = Section | TextDisplay | MediaGallery | Separator | File;
+export declare const components: {
+    section: (components: Component[]) => Section;
+    text: (content: string) => TextDisplay;
+    thumbnail: (url: string, description?: string, spoiler?: boolean) => Thumbnail;
+    media: (url: string, description?: string, spoiler?: boolean) => MediaGalleryItem;
+    media_gallery: (...items: MediaGalleryItem[]) => MediaGallery;
+    file: (url: string, spoiler?: boolean) => File;
+    separator: (divider?: boolean, spacing?: 1 | 2) => Separator;
+    container: (accent_color?: number, spoiler?: boolean, ...components: ContainerChild[]) => Container;
+};
+export {};

package/lib/components.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.components = exports.IS_COMPONENTS_V2 = void 0;
+exports.IS_COMPONENTS_V2 = 1 << 15;
+exports.components = {
+    section: (components) => ({ type: 9, components }),
+    text: (content) => ({ type: 10, content }),
+    thumbnail: (url, description, spoiler) => {
+        let thumbnail = { type: 11, media: { url } };
+        if (description)
+            thumbnail.description = description;
+        if (typeof spoiler == "boolean")
+            thumbnail.spoiler = spoiler;
+        return thumbnail;
+    },
+    media: (url, description, spoiler) => {
+        let item = { media: { url } };
+        if (description)
+            item.description = description;
+        if (typeof spoiler == "boolean")
+            item.spoiler = spoiler;
+        return item;
+    },
+    media_gallery: (...items) => ({ type: 12, items }),
+    file: (url, spoiler) => {
+        let file = { type: 13, file: { url } };
+        if (typeof spoiler == "boolean")
+            file.spoiler = spoiler;
+        return file;
+    },
+    separator: (divider, spacing) => {
+        let separator = { type: 14 };
+        if (divider)
+            separator.divider = divider;
+        if (spacing)
+            separator.spacing = spacing;
+        return separator;
+    },
+    container: (accent_color, spoiler, ...components) => {
+        let container = { type: 17, components };
+        if (typeof accent_color == "number")
+            container.accent_color = accent_color;
+        if (typeof spoiler == "boolean")
+            container.spoiler = spoiler;
+        return container;
+    }
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "dschook",
+  "version": "1.0.0",
+  "description": "Convenience library for Discord's Webhook API",
+  "main": "lib/Webhook.js",
+  "files": [
+    "readme.md",
+    "lib"
+  ],
+  "keywords": [
+    "Discord",
+    "Webhook"
+  ],
+  "author": "Alfio (p2js)",
+  "license": "ISC",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "^11.9.0",
+      "onFail": "download"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/readme.md

@@ -0,0 +1,80 @@
+# dschook
+
+Simple convenience library for type-safe interaction with discord's Webhook API.
+
+Includes a functional API for componentsV2 objects.
+
+## Usage
+
+Install:
+
+```sh
+pnpm install dschook # or npm, bun, ...
+```
+
+Use:
+
+```js
+import { Webhook } from "discord-webhook";
+const hook = new Webhook("https://discord.com/api/webhooks/...");
+```
+
+## Currently supported
+
+Sending regular text messages:
+
+```js
+hook.send_text("Hello!");
+```
+
+Sending ComponentsV2 (via the static `Webhook.components` and `Webhook.colors` APIs):
+
+```js
+const { container, text } = Webhook.components;
+const { rgb } = Webhook.colors;
+
+hook.send_components(
+    text("Hello"),
+    container(rgb(100, 0, 0), false, [
+        text("I'm stuck inside a red-lined container!")
+    ])
+);
+```
+
+Sending polls:
+
+```js
+hook.send_poll(
+    "What's your favourite color?",
+    ["Red", "Orange", "Yellow", { text: "green", emoji_name: "💚" }],
+    // Optional arguments: poll duration in hours and whether to allow selecting multiple options
+    5, true
+);
+```
+
+Sending 1-10 embed objects:
+
+```js
+hook.send_embed({
+    color: Webhook.colors.rgb(100, 0, 0)
+    author: { name: "github user" },
+    fields: [
+        { name: "foo", value: "bar" }
+    ]
+});
+```
+*(Note: While sending embeds is supported, using message components is the recommended modern approach.)*
+
+Sending multiple content types in one message:
+```js
+hook.send({
+    text: "foo",
+    embeds: [/* ... */]
+});
+```
+
+## Currently unsupported
+
+PRs welcome!
+- Uploading attachments and/or files
+- Editing and deleting uploaded webhooks