@theholocron/holocron-plugin-discord 5.0.0-alpha.180 → 5.0.0-alpha.182

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,7 +1,8 @@
-import { AuthError, Notifications, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
-import { DiscordClient, DiscordClientOptions, DiscordWebhookInfo, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
+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;
+declare const resolveBotToken: (input?: ResolveTokenInput) => string;
 //#endregion
 //#region src/capabilities/notifications.d.ts
 interface DiscordNotificationsOptions {
@@ -15,18 +16,51 @@ 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
@@ -42,6 +76,12 @@ interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOp
   /** 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;
@@ -51,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;
@@ -62,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,5 +1,5 @@
 import { AuthError, createResolveToken } from "@theholocron/cli";
-import { createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
+import { ChannelType, createDiscordBotClient, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
 import { errorMessage } from "@theholocron/misc-utils";
 //#region src/auth.ts
 const resolveToken = createResolveToken({
@@ -8,24 +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/...>"
 });
+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 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;
@@ -59,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);
@@ -80,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.180",
+  "version": "5.0.0-alpha.182",
   "description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
   "keywords": [
     "discord",
@@ -30,9 +30,9 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/discord-client": "^1.42.1",
+    "@theholocron/discord-client": "^1.43.1",
     "@theholocron/eslint-config": "^8.8.2",
-    "@theholocron/http-client": "^1.42.1",
+    "@theholocron/http-client": "^1.43.1",
     "@theholocron/misc-utils": "^1.16.0",
     "@theholocron/tsconfig": "^8.8.2",
     "@theholocron/tsdown-config": "^8.8.2",
@@ -48,12 +48,12 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.180"
+    "@theholocron/cli": "5.0.0-alpha.182"
   },
   "peerDependencies": {
-    "@theholocron/discord-client": "^1.42.1",
+    "@theholocron/discord-client": "^1.43.1",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.180"
+    "@theholocron/cli": "5.0.0-alpha.182"
   },
   "engines": {
     "node": ">=22"