@notifkit/provider-discord 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devkitshq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @notifkit/provider-discord
+
+Discord webhook transport for [notifkit](https://github.com/devkitshq/notifkit).
+Sends messages through an incoming Discord webhook and reports deleted/invalid
+webhooks back so notifkit can deactivate the contact.
+
+```bash
+npm install @notifkit/provider-discord
+```
+
+```ts
+import { NotifkitServer } from "notifkit";
+import { DiscordTransport } from "@notifkit/provider-discord";
+
+const server = new NotifkitServer({
+  services: ["all"],
+  providers: [new DiscordTransport()],
+});
+```
+
+## Getting a webhook URL
+
+In the target Discord channel: **Edit Channel → Integrations → Webhooks →
+New Webhook**, then copy its URL. Unlike email or push, the webhook URL _is_
+the destination — register it as the contact target directly:
+
+```ts
+await notifkit.addContact("usr_123", {
+  channel: "discord",
+  target: "https://discord.com/api/webhooks/123456789012345678/abcdef...",
+});
+```
+
+Then register a template on the `discord` channel and send:
+
+```ts
+await notifkit.syncTemplates({
+  templates: [
+    {
+      id: "order-shipped",
+      channel: "discord",
+      content: { text: "Order #{{orderId}} shipped!" },
+    },
+  ],
+});
+
+await notifkit.notify({
+  user: "usr_123",
+  template: "order-shipped",
+  channels: ["discord"],
+  data: { orderId: "9481" },
+});
+```
+
+A template's content may set `username` and `avatarUrl` to override the
+webhook's default identity per message, and `embeds` (an array of [Discord
+embed objects](https://discord.com/developers/docs/resources/webhook#execute-webhook))
+for richer formatting. Requires `notifkit` as a peer dependency.
+Documentation: [notifkit.dev/docs](https://notifkit.dev/docs/). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { DeliveryResult, Transport } from "notifkit";
+import type { NotificationDispatchedPayload, Logger } from "notifkit";
+export interface DiscordTransportOptions {
+    /**
+     * Default sender name shown on messages, overridable per template via
+     * `content.username`. Left unset, Discord uses the webhook's own name.
+     */
+    username?: string;
+    /** Default avatar URL, overridable per template via `content.avatarUrl`. */
+    avatarUrl?: string;
+    logger?: Logger;
+    /**
+     * Discord enforces roughly 5 requests / 2 seconds per webhook. Tighten
+     * this if several templates share one webhook and could burst together.
+     */
+    limits?: {
+        limit: number;
+        windowSeconds: number;
+    };
+}
+export declare class DiscordTransport implements Transport {
+    readonly channel: "discord";
+    readonly limits?: {
+        limit: number;
+        windowSeconds: number;
+    };
+    private readonly username?;
+    private readonly avatarUrl?;
+    private readonly logger?;
+    constructor({ username, avatarUrl, logger, limits, }?: DiscordTransportOptions);
+    send(task: NotificationDispatchedPayload): Promise<DeliveryResult>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEtE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,qBAAa,gBAAiB,YAAW,SAAS;IAChD,QAAQ,CAAC,OAAO,EAAG,SAAS,CAAU;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAE3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,EACV,QAAQ,EACR,SAAS,EACT,MAAM,EACN,MAAuC,GACxC,GAAE,uBAA4B;IAOzB,IAAI,CAAC,IAAI,EAAE,6BAA6B,GAAG,OAAO,CAAC,cAAc,CAAC;CA2EzE"}

package/dist/index.js

@@ -0,0 +1,75 @@
+export class DiscordTransport {
+    channel = "discord";
+    limits;
+    username;
+    avatarUrl;
+    logger;
+    constructor({ username, avatarUrl, logger, limits = { limit: 5, windowSeconds: 2 }, } = {}) {
+        this.username = username;
+        this.avatarUrl = avatarUrl;
+        this.logger = logger;
+        this.limits = limits;
+    }
+    async send(task) {
+        // `destination` is optional on the contract, so a malformed task can reach
+        // a transport without one. Failing here costs one clear error; passing
+        // `undefined` as the webhook URL costs an opaque fetch failure instead.
+        const webhookUrl = task.destination;
+        if (!webhookUrl) {
+            return { success: false, error: "No destination (Discord webhook URL) on task" };
+        }
+        const content = task.renderedContent.content;
+        const body = content.text || content.body;
+        const subject = content.subject;
+        // Discord messages have no subject line of their own, so a template that
+        // renders one is bolded onto the first line rather than dropped.
+        const text = subject ? `**${subject}**\n${body}` : body;
+        // A template may carry its own sender, so one webhook can post as
+        // different bots for different alert types.
+        const username = typeof content.username === "string" && content.username ? content.username : this.username;
+        const avatarUrl = typeof content.avatarUrl === "string" && content.avatarUrl
+            ? content.avatarUrl
+            : this.avatarUrl;
+        const embeds = Array.isArray(content.embeds) ? content.embeds : undefined;
+        try {
+            // `wait=true` makes Discord return the created message (with its id)
+            // in the response body instead of an empty 204 — without it there is
+            // no providerMessageId to record in the delivery log.
+            const url = new URL(webhookUrl);
+            url.searchParams.set("wait", "true");
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    content: text,
+                    ...(username ? { username } : {}),
+                    ...(avatarUrl ? { avatar_url: avatarUrl } : {}),
+                    ...(embeds ? { embeds } : {}),
+                }),
+            });
+            if (!res.ok) {
+                const errorBody = await res.text();
+                // A deleted or regenerated webhook answers 404/401 for every future
+                // request — the target itself is dead, not a transient failure, so
+                // the caller should deactivate the contact rather than retry it.
+                const invalidToken = res.status === 404 || res.status === 401;
+                this.logger?.warn({ taskId: task.taskId, status: res.status, errorBody }, "Discord send failed");
+                return {
+                    success: false,
+                    invalidToken,
+                    error: `Discord webhook error ${res.status}: ${errorBody}`,
+                };
+            }
+            const data = (await res.json().catch(() => null));
+            const providerMessageId = data?.id ?? "";
+            this.logger?.debug({ taskId: task.taskId, providerMessageId }, "Discord message sent");
+            return { success: true, providerMessageId };
+        }
+        catch (err) {
+            const error = err;
+            this.logger?.error({ taskId: task.taskId, error: error.message }, "Discord unexpected error");
+            return { success: false, error: error.message };
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DeliveryResult, Transport } from \"notifkit\";\nimport type { NotificationDispatchedPayload, Logger } from \"notifkit\";\n\nexport interface DiscordTransportOptions {\n  /**\n   * Default sender name shown on messages, overridable per template via\n   * `content.username`. Left unset, Discord uses the webhook's own name.\n   */\n  username?: string;\n  /** Default avatar URL, overridable per template via `content.avatarUrl`. */\n  avatarUrl?: string;\n  logger?: Logger;\n  /**\n   * Discord enforces roughly 5 requests / 2 seconds per webhook. Tighten\n   * this if several templates share one webhook and could burst together.\n   */\n  limits?: { limit: number; windowSeconds: number };\n}\n\nexport class DiscordTransport implements Transport {\n  readonly channel = \"discord\" as const;\n  readonly limits?: { limit: number; windowSeconds: number };\n\n  private readonly username?: string;\n  private readonly avatarUrl?: string;\n  private readonly logger?: Logger;\n\n  constructor({\n    username,\n    avatarUrl,\n    logger,\n    limits = { limit: 5, windowSeconds: 2 },\n  }: DiscordTransportOptions = {}) {\n    this.username = username;\n    this.avatarUrl = avatarUrl;\n    this.logger = logger;\n    this.limits = limits;\n  }\n\n  async send(task: NotificationDispatchedPayload): Promise<DeliveryResult> {\n    // `destination` is optional on the contract, so a malformed task can reach\n    // a transport without one. Failing here costs one clear error; passing\n    // `undefined` as the webhook URL costs an opaque fetch failure instead.\n    const webhookUrl = task.destination;\n    if (!webhookUrl) {\n      return { success: false, error: \"No destination (Discord webhook URL) on task\" };\n    }\n\n    const content = task.renderedContent.content as any;\n    const body = content.text || content.body;\n    const subject = content.subject;\n    // Discord messages have no subject line of their own, so a template that\n    // renders one is bolded onto the first line rather than dropped.\n    const text = subject ? `**${subject}**\\n${body}` : body;\n\n    // A template may carry its own sender, so one webhook can post as\n    // different bots for different alert types.\n    const username =\n      typeof content.username === \"string\" && content.username ? content.username : this.username;\n    const avatarUrl =\n      typeof content.avatarUrl === \"string\" && content.avatarUrl\n        ? content.avatarUrl\n        : this.avatarUrl;\n    const embeds = Array.isArray(content.embeds) ? content.embeds : undefined;\n\n    try {\n      // `wait=true` makes Discord return the created message (with its id)\n      // in the response body instead of an empty 204 — without it there is\n      // no providerMessageId to record in the delivery log.\n      const url = new URL(webhookUrl);\n      url.searchParams.set(\"wait\", \"true\");\n\n      const res = await fetch(url, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify({\n          content: text,\n          ...(username ? { username } : {}),\n          ...(avatarUrl ? { avatar_url: avatarUrl } : {}),\n          ...(embeds ? { embeds } : {}),\n        }),\n      });\n\n      if (!res.ok) {\n        const errorBody = await res.text();\n        // A deleted or regenerated webhook answers 404/401 for every future\n        // request — the target itself is dead, not a transient failure, so\n        // the caller should deactivate the contact rather than retry it.\n        const invalidToken = res.status === 404 || res.status === 401;\n\n        this.logger?.warn(\n          { taskId: task.taskId, status: res.status, errorBody },\n          \"Discord send failed\",\n        );\n\n        return {\n          success: false,\n          invalidToken,\n          error: `Discord webhook error ${res.status}: ${errorBody}`,\n        };\n      }\n\n      const data = (await res.json().catch(() => null)) as { id?: string } | null;\n      const providerMessageId = data?.id ?? \"\";\n\n      this.logger?.debug({ taskId: task.taskId, providerMessageId }, \"Discord message sent\");\n      return { success: true, providerMessageId };\n    } catch (err) {\n      const error = err as Error;\n      this.logger?.error({ taskId: task.taskId, error: error.message }, \"Discord unexpected error\");\n\n      return { success: false, error: error.message };\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@notifkit/provider-discord",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "notifkit": "^0.1.0"
+  },
+  "devDependencies": {
+    "notifkit": "file:../../",
+    "typescript": "^5.8.3"
+  },
+  "description": "Discord webhook transport for notifkit — sends messages through an incoming Discord webhook.",
+  "license": "MIT",
+  "author": "devkitshq",
+  "homepage": "https://notifkit.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devkitshq/notifkit.git",
+    "directory": "packages/provider-discord"
+  },
+  "bugs": {
+    "url": "https://github.com/devkitshq/notifkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+import type { DeliveryResult, Transport } from "notifkit";
+import type { NotificationDispatchedPayload, Logger } from "notifkit";
+
+export interface DiscordTransportOptions {
+  /**
+   * Default sender name shown on messages, overridable per template via
+   * `content.username`. Left unset, Discord uses the webhook's own name.
+   */
+  username?: string;
+  /** Default avatar URL, overridable per template via `content.avatarUrl`. */
+  avatarUrl?: string;
+  logger?: Logger;
+  /**
+   * Discord enforces roughly 5 requests / 2 seconds per webhook. Tighten
+   * this if several templates share one webhook and could burst together.
+   */
+  limits?: { limit: number; windowSeconds: number };
+}
+
+export class DiscordTransport implements Transport {
+  readonly channel = "discord" as const;
+  readonly limits?: { limit: number; windowSeconds: number };
+
+  private readonly username?: string;
+  private readonly avatarUrl?: string;
+  private readonly logger?: Logger;
+
+  constructor({
+    username,
+    avatarUrl,
+    logger,
+    limits = { limit: 5, windowSeconds: 2 },
+  }: DiscordTransportOptions = {}) {
+    this.username = username;
+    this.avatarUrl = avatarUrl;
+    this.logger = logger;
+    this.limits = limits;
+  }
+
+  async send(task: NotificationDispatchedPayload): Promise<DeliveryResult> {
+    // `destination` is optional on the contract, so a malformed task can reach
+    // a transport without one. Failing here costs one clear error; passing
+    // `undefined` as the webhook URL costs an opaque fetch failure instead.
+    const webhookUrl = task.destination;
+    if (!webhookUrl) {
+      return { success: false, error: "No destination (Discord webhook URL) on task" };
+    }
+
+    const content = task.renderedContent.content as any;
+    const body = content.text || content.body;
+    const subject = content.subject;
+    // Discord messages have no subject line of their own, so a template that
+    // renders one is bolded onto the first line rather than dropped.
+    const text = subject ? `**${subject}**\n${body}` : body;
+
+    // A template may carry its own sender, so one webhook can post as
+    // different bots for different alert types.
+    const username =
+      typeof content.username === "string" && content.username ? content.username : this.username;
+    const avatarUrl =
+      typeof content.avatarUrl === "string" && content.avatarUrl
+        ? content.avatarUrl
+        : this.avatarUrl;
+    const embeds = Array.isArray(content.embeds) ? content.embeds : undefined;
+
+    try {
+      // `wait=true` makes Discord return the created message (with its id)
+      // in the response body instead of an empty 204 — without it there is
+      // no providerMessageId to record in the delivery log.
+      const url = new URL(webhookUrl);
+      url.searchParams.set("wait", "true");
+
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          content: text,
+          ...(username ? { username } : {}),
+          ...(avatarUrl ? { avatar_url: avatarUrl } : {}),
+          ...(embeds ? { embeds } : {}),
+        }),
+      });
+
+      if (!res.ok) {
+        const errorBody = await res.text();
+        // A deleted or regenerated webhook answers 404/401 for every future
+        // request — the target itself is dead, not a transient failure, so
+        // the caller should deactivate the contact rather than retry it.
+        const invalidToken = res.status === 404 || res.status === 401;
+
+        this.logger?.warn(
+          { taskId: task.taskId, status: res.status, errorBody },
+          "Discord send failed",
+        );
+
+        return {
+          success: false,
+          invalidToken,
+          error: `Discord webhook error ${res.status}: ${errorBody}`,
+        };
+      }
+
+      const data = (await res.json().catch(() => null)) as { id?: string } | null;
+      const providerMessageId = data?.id ?? "";
+
+      this.logger?.debug({ taskId: task.taskId, providerMessageId }, "Discord message sent");
+      return { success: true, providerMessageId };
+    } catch (err) {
+      const error = err as Error;
+      this.logger?.error({ taskId: task.taskId, error: error.message }, "Discord unexpected error");
+
+      return { success: false, error: error.message };
+    }
+  }
+}