@theholocron/holocron-plugin-discord 5.0.0-alpha.18 → 5.0.0-alpha.181

package/README.md

@@ -61,3 +61,23 @@ server membership is required — generate one in Discord under
 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.
+
+## Provisioning
+
+`holocron notifications setup` and `holocron notifications channel add` create
+channels, roles and webhooks through the `notifications` capability's `ensure*`
+methods. They use the **Holonet bot**, not a webhook URL:
+
+- `HOLOCRON_DISCORD_BOT_TOKEN` (or `DISCORD_BOT_TOKEN`) — the bot token from
+  the Developer Portal. Only read when a provisioning command runs.
+- `guildId` — the server id (not a secret), set in the provider options.
+- `layout` — categories, channels (each optionally with a `webhook`) and roles.
+
+The bot needs Manage Channels, Manage Roles, Manage Webhooks and View Channels.
+Everything is idempotent (looked up by name). Discord returns a webhook's URL
+only to the application that created it, so a webhook the bot did not create
+cannot have its URL read back.
+
+`baseUrl` only redirects posting. The bot token is always sent to the real
+Discord API unless `unsafeBotBaseUrl: true` is also set (meant for tests that
+stub the API), so a changed config cannot redirect the token to another host.

package/dist/index.d.mts

@@ -1,30 +1,8 @@
-import { AuthError, Notifications, ResolveTokenInput } from "@theholocron/cli";
+import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsLayout, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
+import { DiscordBotClient, DiscordClient, DiscordClientOptions, DiscordWebhookInfo, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
 //#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;
-};
+declare const resolveBotToken: (input?: ResolveTokenInput) => string;
 //#endregion
 //#region src/capabilities/notifications.d.ts
 interface DiscordNotificationsOptions {
@@ -38,42 +16,72 @@ interface DiscordNotificationsOptions {
    * without an explicit channel, or with an empty string.
    */
   defaultChannel?: string;
+  /** Discord server (guild) id that `notifications setup` provisions. Not a secret. */
+  guildId?: string;
+  /** The server layout `notifications setup` applies. */
+  layout?: NotificationsLayout;
 }
 declare class DiscordNotifications implements Notifications {
   private readonly client;
   private readonly opts;
   /** Memoized thunk — resolves the default webhook URL on the first `send()`. */
   private readonly defaultWebhookUrl;
+  /** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
+  private readonly bot;
   readonly key: "notifications";
   readonly providerName = "discord";
   constructor(client: DiscordClient, opts: DiscordNotificationsOptions,
   /** Memoized thunk — resolves the default webhook URL on the first `send()`. */
-  defaultWebhookUrl: () => string);
+  defaultWebhookUrl: () => string,
+  /** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
+  bot?: () => DiscordBotClient);
+  get layout(): NotificationsLayout | undefined;
   send(channel: string, message: string): Promise<void>;
+  private guild;
+  private static same;
+  ensureCategory(name: string): Promise<EnsuredResource>;
+  /**
+   * Find a channel by name. A name can exist in several categories, so with a
+   * parent: prefer the one already there, then an uncategorised one (moved in);
+   * never grab a channel that lives under a different category. Announcement
+   * channels count: reusing one beats creating a same-named text channel.
+   */
+  private static findChannel;
+  ensureChannel(input: {
+    name: string;
+    category?: string;
+    topic?: string;
+  }): Promise<EnsuredResource>;
+  ensureWebhook(input: {
+    channel: string;
+    name: string;
+    category?: string;
+  }): Promise<EnsureWebhookResult>;
+  ensureRole(input: {
+    name: string;
+    mentionable?: boolean;
+  }): Promise<EnsuredResource>;
   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>;
+declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
 //#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;
+  /**
+   * Also send the BOT token to `baseUrl`. Off by default: `baseUrl` comes from a
+   * repo's config, and a changed config must not be able to redirect the bot
+   * token to another host. Tests that stub the API set it.
+   */
+  unsafeBotBaseUrl?: boolean;
 }
 interface PluginContext {
   options: DiscordPluginOptions;
@@ -83,6 +91,8 @@ interface PluginContext {
    * resolved on first `send()`, not at plugin load. `describe()` never calls it.
    */
   defaultWebhookUrl: () => string;
+  /** Memoized — resolves the bot token on the first provisioning call; `send()` and `describe()` never touch it. */
+  bot: () => DiscordBotClient;
 }
 declare function createContext(options?: DiscordPluginOptions): PluginContext;
 declare function notifications(ctx: PluginContext): Notifications;
@@ -94,4 +104,4 @@ declare function createPlugin(options?: DiscordPluginOptions): {
 };
 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 };
+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, resolveBotToken, resolveToken, verifyToken };

package/dist/index.mjs

@@ -1,4 +1,6 @@
-import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { AuthError, createResolveToken } from "@theholocron/cli";
+import { ChannelType, createDiscordBotClient, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
+import { errorMessage } from "@theholocron/misc-utils";
 //#region src/auth.ts
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_DISCORD_WEBHOOK",
@@ -6,53 +8,126 @@ const resolveToken = createResolveToken({
 	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]
-	};
-}
+const resolveBotToken = createResolveToken({
+	envName: "HOLOCRON_DISCORD_BOT_TOKEN",
+	vendorEnvName: "DISCORD_BOT_TOKEN",
+	keyringService: "discord-bot",
+	errorMessage: "no Discord bot token found. Set HOLOCRON_DISCORD_BOT_TOKEN (or DISCORD_BOT_TOKEN) — it is the bot token from the Discord developer portal (Bot → Reset Token), not a webhook URL."
+});
 //#endregion
 //#region src/capabilities/notifications.ts
-var DiscordNotifications = class {
+var DiscordNotifications = class DiscordNotifications {
 	client;
 	opts;
 	defaultWebhookUrl;
+	bot;
 	key = "notifications";
 	providerName = "discord";
-	constructor(client, opts, defaultWebhookUrl) {
+	constructor(client, opts, defaultWebhookUrl, bot = () => {
+		throw new Error("no Discord bot client configured");
+	}) {
 		this.client = client;
 		this.opts = opts;
 		this.defaultWebhookUrl = defaultWebhookUrl;
+		this.bot = bot;
+	}
+	get layout() {
+		return this.opts.layout;
 	}
 	async send(channel, message) {
-		const { id, token } = parseWebhookUrl(this.resolve(channel || this.opts.defaultChannel || ""));
+		const webhookUrl = this.resolve(channel || this.opts.defaultChannel || "");
+		const { id, token } = parseWebhookUrl(webhookUrl);
 		await this.client.webhooks.execute(id, token, message);
 	}
+	guild() {
+		if (!this.opts.guildId) throw new Error("no Discord server id — set `guildId` in the discord provider options in holocron.config.ts");
+		return this.opts.guildId;
+	}
+	static same(a, b) {
+		return a.toLowerCase() === b.toLowerCase();
+	}
+	async ensureCategory(name) {
+		const bot = this.bot();
+		const existing = (await bot.guilds.channels(this.guild())).find((c) => c.type === ChannelType.Category && DiscordNotifications.same(c.name, name));
+		if (existing) return {
+			id: existing.id,
+			created: false
+		};
+		return {
+			id: (await bot.guilds.createChannel(this.guild(), {
+				name,
+				type: ChannelType.Category
+			})).id,
+			created: true
+		};
+	}
+	/**
+	* Find a channel by name. A name can exist in several categories, so with a
+	* parent: prefer the one already there, then an uncategorised one (moved in);
+	* never grab a channel that lives under a different category. Announcement
+	* channels count: reusing one beats creating a same-named text channel.
+	*/
+	static findChannel(channels, name, parentId) {
+		const named = channels.filter((c) => (c.type === ChannelType.Text || c.type === ChannelType.Announcement) && DiscordNotifications.same(c.name, name));
+		if (!parentId) return named[0];
+		return named.find((c) => c.parent_id === parentId) ?? named.find((c) => !c.parent_id);
+	}
+	async ensureChannel(input) {
+		const bot = this.bot();
+		const parent = input.category ? (await this.ensureCategory(input.category)).id : void 0;
+		const existing = DiscordNotifications.findChannel(await bot.guilds.channels(this.guild()), input.name, parent);
+		if (existing) {
+			const patch = {
+				...parent && existing.parent_id !== parent ? { parent_id: parent } : {},
+				...input.topic !== void 0 && (existing.topic ?? "") !== input.topic ? { topic: input.topic } : {}
+			};
+			if (Object.keys(patch).length > 0) await bot.channels.modify(existing.id, patch);
+			return {
+				id: existing.id,
+				created: false
+			};
+		}
+		return {
+			id: (await bot.guilds.createChannel(this.guild(), {
+				name: input.name,
+				type: ChannelType.Text,
+				...input.topic ? { topic: input.topic } : {},
+				...parent ? { parent_id: parent } : {}
+			})).id,
+			created: true
+		};
+	}
+	async ensureWebhook(input) {
+		const bot = this.bot();
+		const parent = input.category ? (await bot.guilds.channels(this.guild())).find((c) => c.type === ChannelType.Category && DiscordNotifications.same(c.name, input.category))?.id : void 0;
+		const channel = DiscordNotifications.findChannel(await bot.guilds.channels(this.guild()), input.channel, parent);
+		if (!channel) throw new Error(`no channel named \`${input.channel}\` — create it first`);
+		const existing = (await bot.channels.webhooks(channel.id)).find((w) => DiscordNotifications.same(w.name ?? "", input.name));
+		if (existing) return {
+			created: false,
+			...existing.url ? { url: existing.url } : {}
+		};
+		const made = await bot.channels.createWebhook(channel.id, { name: input.name });
+		return {
+			created: true,
+			...made.url ? { url: made.url } : {}
+		};
+	}
+	async ensureRole(input) {
+		const bot = this.bot();
+		const existing = (await bot.guilds.roles(this.guild())).find((r) => DiscordNotifications.same(r.name, input.name));
+		if (existing) return {
+			id: existing.id,
+			created: false
+		};
+		return {
+			id: (await bot.guilds.createRole(this.guild(), {
+				name: input.name,
+				...input.mentionable !== void 0 ? { mentionable: input.mentionable } : {}
+			})).id,
+			created: true
+		};
+	}
 	resolve(channel) {
 		const alias = this.opts.webhooks?.[channel];
 		if (alias) return alias;
@@ -78,7 +153,7 @@ async function verifyToken(webhookUrl, opts = {}) {
 	} catch (err) {
 		return {
 			ok: false,
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -86,17 +161,27 @@ async function verifyToken(webhookUrl, opts = {}) {
 //#region src/index.ts
 function createContext(options = {}) {
 	let url;
+	let bot;
 	return {
 		options,
 		client: createDiscordClient({
 			baseUrl: options.baseUrl,
 			fetch: options.fetch
 		}),
-		defaultWebhookUrl: () => url ??= resolveToken(options)
+		defaultWebhookUrl: () => url ??= resolveToken(options),
+		bot: () => bot ??= createDiscordBotClient({
+			botToken: resolveBotToken({
+				env: options.env,
+				keyring: options.keyring,
+				org: options.org
+			}),
+			...options.unsafeBotBaseUrl && options.baseUrl ? { baseUrl: options.baseUrl } : {},
+			...options.fetch ? { fetch: options.fetch } : {}
+		})
 	};
 }
 function notifications(ctx) {
-	return new DiscordNotifications(ctx.client, ctx.options, ctx.defaultWebhookUrl);
+	return new DiscordNotifications(ctx.client, ctx.options, ctx.defaultWebhookUrl, ctx.bot);
 }
 function createPlugin(options = {}) {
 	const ctx = createContext(options);
@@ -107,4 +192,4 @@ function createPlugin(options = {}) {
 }
 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 };
+export { AUTH_HINT, AuthError, DiscordNotifications, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveBotToken, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-discord",
-  "version": "5.0.0-alpha.18",
+  "version": "5.0.0-alpha.181",
   "description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
   "keywords": [
     "discord",
@@ -8,12 +8,12 @@
     "notifications",
     "plugin"
   ],
-  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-discord#readme",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/plugins/holocron-plugin-discord#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/theholocron/holocron.git",
-    "directory": "packages/holocron-plugin-discord"
+    "directory": "plugins/holocron-plugin-discord"
   },
   "license": "MIT",
   "author": "Newton Koumantzelis",
@@ -30,11 +30,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/http-client": "^1.18.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
+    "@theholocron/discord-client": "^1.43.1",
+    "@theholocron/eslint-config": "^8.8.2",
+    "@theholocron/http-client": "^1.43.1",
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/tsconfig": "^8.8.2",
+    "@theholocron/tsdown-config": "^8.8.2",
+    "@theholocron/vitest-config": "^8.8.2",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",
@@ -43,13 +45,15 @@
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.11.0",
     "tsdown": "^0.22.14",
-    "tsx": "4.23.12",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.18"
+    "@theholocron/cli": "5.0.0-alpha.181"
   },
   "peerDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.18"
+    "@theholocron/discord-client": "^1.43.1",
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/cli": "5.0.0-alpha.181"
   },
   "engines": {
     "node": ">=22"