@theholocron/holocron-plugin-discord 3.25.1 → 3.26.0

package/README.md

@@ -0,0 +1,61 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-discord`
+
+Discord plugin for [Holocron](../cli). Implements the `notifications`
+capability via [Discord incoming webhooks](https://discord.com/developers/docs/resources/webhook).
+
+## Install
+
+<!-- prettier-ignore -->
+```bash
+pnpm add -D @theholocron/holocron-plugin-discord
+
+```
+
+## Auth
+
+Token resolution order:
+
+1. `--token <WEBHOOK_URL>` flag on the holocron invocation
+2. `HOLOCRON_DISCORD_WEBHOOK` env var
+3. `DISCORD_WEBHOOK_URL` env var
+
+The "token" is the full incoming webhook URL
+(`https://discord.com/api/webhooks/{id}/{token}`). No bot account or
+server membership is required — generate one in Discord under
+**channel settings → Integrations → Webhooks**.
+
+## Config
+
+<!-- prettier-ignore -->
+```jsonc
+{
+  "providers": {
+    "notifications": [
+      "discord",
+      {
+        "webhooks": { "deploys": "https://discord.com/api/webhooks/…" },
+        "defaultChannel": "deploys",
+      },
+    ],
+  },
+}
+
+```
+
+- `webhooks` (optional) — map of logical channel names to webhook URLs.
+  Allows `send("deploys", msg)` instead of embedding raw URLs in call sites.
+- `defaultChannel` (optional) — alias key or raw webhook URL used when
+  `send()` is called with an empty string. Defaults to the resolved token
+  (the webhook URL from the env var / keyring).
+
+## What's implemented
+
+| Method | What it does                                                                                                                                                                                 |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send` | Posts a message to the given channel. `channel` can be a named alias (from `webhooks`), a raw webhook URL, or an empty string (falls back to `defaultChannel`). Returns on `204 No Content`. |
+
+The webhook id and token are embedded in the URL path — no `Authorization`
+header is sent. `parseWebhookUrl` is exported as a utility for callers
+that need to split the URL into its parts.

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+import { AuthError, Notifications, ResolveTokenInput } from "@theholocron/cli";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/rest.d.ts
+interface DiscordClientOptions {
+  /** Override base URL for tests. Default: https://discord.com/api/v10 */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface DiscordWebhookInfo {
+  id: string;
+  name: string;
+  guild_id?: string;
+}
+interface DiscordClient {
+  webhooks: {
+    get(id: string, token: string): Promise<DiscordWebhookInfo>;
+    execute(id: string, token: string, content: string): Promise<void>;
+  };
+}
+declare function createDiscordClient({ baseUrl, fetch: fetchImpl }?: DiscordClientOptions): DiscordClient;
+/** Parse a Discord webhook URL into its id and token parts. */
+declare function parseWebhookUrl(url: string): {
+  id: string;
+  token: string;
+};
+//#endregion
+//#region src/capabilities/notifications.d.ts
+interface DiscordNotificationsOptions {
+  /**
+   * Named aliases mapping a logical channel name to its webhook URL.
+   * Allows `send("deploys", msg)` instead of passing the full URL.
+   */
+  webhooks?: Record<string, string>;
+  /**
+   * Default webhook URL (or alias key) used when `send()` is called
+   * without an explicit channel, or with an empty string.
+   */
+  defaultChannel?: string;
+}
+declare class DiscordNotifications implements Notifications {
+  private readonly client;
+  private readonly opts;
+  readonly key: "notifications";
+  readonly providerName = "discord";
+  constructor(client: DiscordClient, opts: DiscordNotificationsOptions);
+  send(channel: string, message: string): Promise<void>;
+  private resolve;
+}
+//#endregion
+//#region src/verify-token.d.ts
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
+//#region src/index.d.ts
+interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOptions {
+  /** Override base URL for tests. Default: https://discord.com/api/v10 */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: DiscordPluginOptions;
+  client: DiscordClient;
+  defaultWebhookUrl: string;
+}
+declare function createContext(options?: DiscordPluginOptions): PluginContext;
+declare function notifications(ctx: PluginContext): Notifications;
+declare function createPlugin(options?: DiscordPluginOptions): {
+  name: string;
+  capabilities: {
+    notifications: () => Notifications;
+  };
+};
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, type DiscordClient, type DiscordClientOptions, DiscordNotifications, type DiscordNotificationsOptions, DiscordPluginOptions, type DiscordWebhookInfo, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,111 @@
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_DISCORD_WEBHOOK",
+	vendorEnvName: "DISCORD_WEBHOOK_URL",
+	keyringService: "discord",
+	errorMessage: "no Discord webhook URL found. Pass --token <WEBHOOK_URL>, set HOLOCRON_DISCORD_WEBHOOK / DISCORD_WEBHOOK_URL, or run: holocron auth set discord <https://discord.com/api/webhooks/...>"
+});
+//#endregion
+//#region src/rest.ts
+function createDiscordClient({ baseUrl, fetch: fetchImpl } = {}) {
+	const base = baseUrl ?? "https://discord.com/api/v10";
+	const f = fetchImpl ?? globalThis.fetch;
+	return { webhooks: {
+		get: async (id, token) => {
+			const res = await f(`${base}/webhooks/${id}/${token}`, { method: "GET" });
+			if (!res.ok) throw new ProviderApiError(`Discord webhook not found or invalid (${res.status})`, res.status, void 0);
+			return res.json();
+		},
+		execute: async (id, token, content) => {
+			const res = await f(`${base}/webhooks/${id}/${token}`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ content })
+			});
+			if (!res.ok) throw new ProviderApiError(`Discord webhook POST failed (${res.status})`, res.status, void 0);
+		}
+	} };
+}
+/** Parse a Discord webhook URL into its id and token parts. */
+function parseWebhookUrl(url) {
+	const match = url.match(/webhooks\/(\d+)\/([^/?#]+)/);
+	if (!match) throw new Error(`Invalid Discord webhook URL: ${url}`);
+	return {
+		id: match[1],
+		token: match[2]
+	};
+}
+//#endregion
+//#region src/capabilities/notifications.ts
+var DiscordNotifications = class {
+	client;
+	opts;
+	key = "notifications";
+	providerName = "discord";
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
+	}
+	async send(channel, message) {
+		const { id, token } = parseWebhookUrl(this.resolve(channel || (this.opts.defaultChannel ?? "")));
+		await this.client.webhooks.execute(id, token, message);
+	}
+	resolve(channel) {
+		const alias = this.opts.webhooks?.[channel];
+		if (alias) return alias;
+		if (channel.startsWith("https://")) return channel;
+		const def = this.opts.defaultChannel;
+		if (def) return this.opts.webhooks?.[def] ?? def;
+		throw new Error(`DiscordNotifications.send: unknown channel "${channel}" — pass a webhook URL, an alias key, or set defaultChannel`);
+	}
+};
+//#endregion
+//#region src/verify-token.ts
+async function verifyToken(webhookUrl, opts = {}) {
+	try {
+		const { id, token } = parseWebhookUrl(webhookUrl);
+		const info = await createDiscordClient({
+			baseUrl: opts.baseUrl,
+			fetch: opts.fetch
+		}).webhooks.get(id, token);
+		return {
+			ok: true,
+			subject: `webhook: ${info.name} (id: ${info.id})`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options = {}) {
+	const defaultWebhookUrl = resolveToken(options);
+	return {
+		options,
+		client: createDiscordClient({
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		}),
+		defaultWebhookUrl
+	};
+}
+function notifications(ctx) {
+	return new DiscordNotifications(ctx.client, {
+		...ctx.options,
+		defaultChannel: ctx.options.defaultChannel ?? ctx.defaultWebhookUrl
+	});
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-discord",
+		capabilities: { notifications: () => notifications(ctx) }
+	};
+}
+const AUTH_HINT = "create a webhook in Discord: open your server → channel settings → Integrations → Webhooks → New Webhook, copy the webhook URL, then run: holocron auth set discord <https://discord.com/api/webhooks/...>";
+//#endregion
+export { AUTH_HINT, AuthError, DiscordNotifications, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-discord",
-  "version": "3.25.1",
+  "version": "3.26.0",
   "description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-discord#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "3.25.1"
+    "@theholocron/cli": "3.26.0"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^7.19.1",
@@ -39,7 +39,7 @@
     "tsx": "4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@theholocron/cli": "3.25.1"
+    "@theholocron/cli": "3.26.0"
   },
   "publishConfig": {
     "access": "public"