@theholocron/holocron-plugin-discord 5.0.0-alpha.185 → 5.0.0-alpha.187

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsLayout, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
+import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsLayout, ResolveTokenInput, ServerInspection, 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;
@@ -46,6 +46,12 @@ declare class DiscordNotifications implements Notifications {
   whoami(): Promise<{
     target: string;
   } | null>;
+  /**
+   * Read-only: what is on the server, for the parts of `layout` we will compare. Webhooks are
+   * listed only for channels the layout gives one (one request each), so the cost scales with
+   * the layout, not with the server.
+   */
+  inspect(layout: NotificationsLayout): Promise<ServerInspection>;
   private guild;
   /**
    * The server's channel list, fetched once per instance. Every ensure* call used

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { AuthError, createResolveToken } from "@theholocron/cli";
-import { ChannelType, createDiscordBotClient, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
 import { errorMessage } from "@theholocron/misc-utils";
+import { ChannelType, createDiscordBotClient, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
 //#region src/auth.ts
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_DISCORD_WEBHOOK",
@@ -16,6 +16,10 @@ const resolveBotToken = createResolveToken({
 });
 //#endregion
 //#region src/capabilities/notifications.ts
+/** An error as one line: the message, plus Discord's own response body when there is one. */
+function reason(err) {
+	return err instanceof ProviderApiError && err.details ? `${errorMessage(err)}: ${String(err.details).slice(0, 200)}` : errorMessage(err);
+}
 var DiscordNotifications = class DiscordNotifications {
 	client;
 	opts;
@@ -54,6 +58,53 @@ var DiscordNotifications = class DiscordNotifications {
 		const me = await bot.users.me();
 		return { target: `${(await bot.guilds.get(this.opts.guildId)).name} (as ${me.username})` };
 	}
+	/**
+	* Read-only: what is on the server, for the parts of `layout` we will compare. Webhooks are
+	* listed only for channels the layout gives one (one request each), so the cost scales with
+	* the layout, not with the server.
+	*/
+	async inspect(layout) {
+		const bot = this.bot();
+		const channels = await this.channelList();
+		const categoryName = new Map(channels.filter((c) => c.type === ChannelType.Category).map((c) => [c.id, c.name]));
+		const wantsWebhook = new Set((layout.categories ?? []).flatMap((c) => (c.channels ?? []).filter((ch) => ch.webhook).map((ch) => ch.name.toLowerCase())));
+		const text = channels.filter((c) => c.type === ChannelType.Text || c.type === ChannelType.Announcement);
+		const found = [];
+		for (const c of text) {
+			let webhooks = [];
+			let webhooksError;
+			if (wantsWebhook.has(c.name.toLowerCase())) try {
+				webhooks = (await bot.channels.webhooks(c.id)).map((w) => w.name ?? "");
+			} catch (err) {
+				webhooksError = reason(err);
+			}
+			const category = c.parent_id ? categoryName.get(c.parent_id) : void 0;
+			found.push({
+				name: c.name,
+				...category ? { category } : {},
+				...c.topic ? { topic: c.topic } : {},
+				webhooks,
+				...webhooksError ? { webhooksError } : {}
+			});
+		}
+		let roles = [];
+		let rolesError;
+		if ((layout.roles ?? []).length > 0) try {
+			roles = (await bot.guilds.roles(this.guild())).map((r) => ({
+				name: r.name,
+				id: r.id,
+				mentionable: r.mentionable
+			}));
+		} catch (err) {
+			rolesError = reason(err);
+		}
+		return {
+			categories: [...categoryName.values()],
+			channels: found,
+			roles,
+			...rolesError ? { rolesError } : {}
+		};
+	}
 	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;
@@ -171,10 +222,13 @@ var DiscordNotifications = class DiscordNotifications {
 	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
-		};
+		if (existing) {
+			if (input.mentionable !== void 0 && existing.mentionable !== input.mentionable) throw new Error(`role \`${input.name}\` exists with mentionable=${existing.mentionable} but the layout wants ${input.mentionable}; updating an existing role is not supported yet — change it in Discord (Role → Allow anyone to @mention this role)`);
+			return {
+				id: existing.id,
+				created: false
+			};
+		}
 		return {
 			id: (await bot.guilds.createRole(this.guild(), {
 				name: input.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-discord",
-  "version": "5.0.0-alpha.185",
+  "version": "5.0.0-alpha.187",
   "description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
   "keywords": [
     "discord",
@@ -48,12 +48,12 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.185"
+    "@theholocron/cli": "5.0.0-alpha.187"
   },
   "peerDependencies": {
     "@theholocron/discord-client": "^1.43.1",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.185"
+    "@theholocron/cli": "5.0.0-alpha.187"
   },
   "engines": {
     "node": ">=22"