@theholocron/holocron-plugin-discord 5.0.0-alpha.191 → 5.0.0-alpha.193

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -56,6 +56,12 @@ declare class DiscordNotifications implements Notifications {
56
56
  private inviteUrl;
57
57
  /** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
58
58
  preflight(layout: NotificationsLayout): Promise<void>;
59
+ /** True for a 403 that is about permissions, not about the bot being unable to see the server at all. */
60
+ private static missingPermissions;
61
+ /** An invite link, or nothing when building it needs a request that fails: the advice must not depend on one. */
62
+ private inviteOrNothing;
63
+ /** Turning community on or off needs Administrator, which is more than the bot should keep. */
64
+ private communityHint;
59
65
  /** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
60
66
  private manageServerHint;
61
67
  ensureServer(settings: NotificationsServerLayout): Promise<{
package/dist/index.mjs CHANGED
@@ -82,6 +82,10 @@ const LOCALES = /* @__PURE__ */ new Set([
82
82
  "zh-TW",
83
83
  "ko"
84
84
  ]);
85
+ /** "applied a, b; " for the start of a message about a step that stopped part-way, or nothing. */
86
+ function appliedPrefix(applied) {
87
+ return applied.length > 0 ? `applied ${applied.join(", ")}; but ` : "";
88
+ }
85
89
  /** A layout name to Discord's number, undefined when the layout leaves it out; an unknown name is an error, not an omission. */
86
90
  function s_(name, map) {
87
91
  if (name === void 0) return void 0;
@@ -282,11 +286,11 @@ var DiscordNotifications = class DiscordNotifications {
282
286
  };
283
287
  }
284
288
  /** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
285
- async inviteUrl() {
289
+ async inviteUrl(names = BOT_NEEDS) {
286
290
  const url = new URL("https://discord.com/oauth2/authorize");
287
291
  url.searchParams.set("client_id", await this.botId());
288
292
  url.searchParams.set("scope", "bot");
289
- url.searchParams.set("permissions", permissions(BOT_NEEDS));
293
+ url.searchParams.set("permissions", permissions(names));
290
294
  url.searchParams.set("guild_id", this.guild());
291
295
  return url.toString();
292
296
  }
@@ -299,10 +303,31 @@ var DiscordNotifications = class DiscordNotifications {
299
303
  throw await this.manageServerHint(err);
300
304
  }
301
305
  }
306
+ /** True for a 403 that is about permissions, not about the bot being unable to see the server at all. */
307
+ static missingPermissions(err) {
308
+ return err instanceof ProviderApiError && err.status === 403 && !/Missing Access|\b50001\b/.test(String(err.details));
309
+ }
310
+ /** An invite link, or nothing when building it needs a request that fails: the advice must not depend on one. */
311
+ async inviteOrNothing(names) {
312
+ try {
313
+ return await this.inviteUrl(names);
314
+ } catch {
315
+ return;
316
+ }
317
+ }
318
+ /** Turning community on or off needs Administrator, which is more than the bot should keep. */
319
+ async communityHint(err, applied, turningOn) {
320
+ if (!DiscordNotifications.missingPermissions(err)) return err;
321
+ const link = await this.inviteOrNothing(["Administrator"]);
322
+ const byHand = turningOn ? "turn them on once in Discord (Server Settings → Enable Community; setup then keeps everything else in line)" : "turn them off once in Discord (Server Settings → Community Settings → Disable Community)";
323
+ const viaBot = link ? `give Holonet Administrator for one run and take it away again afterwards: ${link}` : "re-invite Holonet with the Administrator permission for one run, and take it away again afterwards";
324
+ return new Error(`${appliedPrefix(applied)}turning community features ${turningOn ? "on" : "off"} needs the Administrator permission, which Holonet does not have. Either ${byHand}, or ${viaBot}`, { cause: err });
325
+ }
302
326
  /** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
303
327
  async manageServerHint(err) {
304
- if (err instanceof ProviderApiError && err.status === 403) return new Error(`the bot is not allowed to change server settings: its role lacks Manage Server. Re-invite it with the permissions setup needs (this updates its role in place): ${await this.inviteUrl()}`, { cause: err });
305
- return err;
328
+ if (!DiscordNotifications.missingPermissions(err)) return err;
329
+ const link = await this.inviteOrNothing();
330
+ return new Error(`the bot is not allowed to change server settings: its role lacks Manage Server. Re-invite it with the permissions setup needs${link ? ` (this updates its role in place): ${link}` : " (this updates its role in place)"}`, { cause: err });
306
331
  }
307
332
  async ensureServer(settings) {
308
333
  const bot = this.bot();
@@ -327,32 +352,62 @@ var DiscordNotifications = class DiscordNotifications {
327
352
  set("contentFilter", "explicit_content_filter", s_(settings.contentFilter, FILTER), guild.explicit_content_filter);
328
353
  set("systemChannel", "system_channel_id", settings.systemChannel && idOf(settings.systemChannel), guild.system_channel_id);
329
354
  set("rulesChannel", "rules_channel_id", settings.rulesChannel && idOf(settings.rulesChannel), guild.rules_channel_id);
330
- set("updatesChannel", "public_updates_channel_id", settings.updatesChannel && idOf(settings.updatesChannel), guild.public_updates_channel_id);
355
+ const updatesId = settings.updatesChannel ? idOf(settings.updatesChannel) : void 0;
356
+ const updatesChanged = updatesId !== void 0 && updatesId !== guild.public_updates_channel_id;
331
357
  set("description", "description", settings.description, guild.description ?? "");
332
358
  set("locale", "preferred_locale", settings.locale, guild.preferred_locale);
333
- const features = guild.features ?? [];
334
- const community = features.includes("COMMUNITY");
335
- if (settings.community !== void 0 && settings.community !== community) {
336
- patch.features = settings.community ? [...features, "COMMUNITY"] : features.filter((f) => f !== "COMMUNITY");
337
- updated.push("community");
338
- }
339
- if (updated.length === 0) return { updated };
340
- let after;
341
- try {
342
- after = await bot.guilds.modify(this.guild(), patch);
343
- } catch (err) {
344
- throw await this.manageServerHint(err);
359
+ const community = (guild.features ?? []).includes("COMMUNITY");
360
+ const toggleCommunity = settings.community !== void 0 && settings.community !== community;
361
+ const updatesWithCommunity = updatesId !== void 0 && toggleCommunity && settings.community === true;
362
+ const communityAfter = toggleCommunity ? settings.community === true : community;
363
+ if (updatesChanged && !updatesWithCommunity) {
364
+ if (!communityAfter) throw new Error(`\`updatesChannel\` can only be set while community features are on, but they are off and the layout does not turn them on -- add \`community: true\` or remove \`updatesChannel\``);
365
+ patch.public_updates_channel_id = updatesId;
366
+ updated.push("updatesChannel");
345
367
  }
346
- const stuck = Object.keys(patch).filter((k) => k !== "features").filter((k) => {
347
- const got = after[k];
348
- return patch[k] !== (k === "description" ? got ?? "" : got);
349
- });
350
- const nowFeatures = after.features ?? [];
351
- if (patch.features && patch.features.includes("COMMUNITY") !== nowFeatures.includes("COMMUNITY")) stuck.push("features");
352
- if (stuck.length > 0) throw new Error(`sent ${stuck.join(", ")} but the server came back different -- Discord may have refused a part of it (community features need a rules channel, an updates channel, verification of at least low and the content filter on all members)`);
353
- if (patch.features?.includes("COMMUNITY")) {
354
- const lost = features.filter((f) => f !== "COMMUNITY" && !nowFeatures.includes(f));
355
- if (lost.length > 0) throw new Error(`turned community on, but the server no longer has ${lost.join(", ")} -- another admin may have changed its features at the same time; check Server Settings and re-run`);
368
+ const ordinary = async () => {
369
+ if (Object.keys(patch).length === 0) return;
370
+ let after;
371
+ try {
372
+ after = await bot.guilds.modify(this.guild(), patch);
373
+ } catch (err) {
374
+ throw await this.manageServerHint(err);
375
+ }
376
+ const stuck = Object.keys(patch).filter((k) => {
377
+ const got = after[k];
378
+ return patch[k] !== (k === "description" ? got ?? "" : got);
379
+ });
380
+ if (stuck.length > 0) throw new Error(`sent ${stuck.join(", ")} but the server came back different -- Discord may have refused a part of it`);
381
+ };
382
+ const toggle = async () => {
383
+ if (!toggleCommunity) return;
384
+ const fresh = (await bot.guilds.get(this.guild())).features ?? [];
385
+ const wanted = settings.community ? [.../* @__PURE__ */ new Set([...fresh, "COMMUNITY"])] : fresh.filter((f) => f !== "COMMUNITY");
386
+ let after;
387
+ try {
388
+ after = await bot.guilds.modify(this.guild(), {
389
+ features: wanted,
390
+ ...updatesWithCommunity ? { public_updates_channel_id: updatesId } : {}
391
+ });
392
+ } catch (err) {
393
+ throw await this.communityHint(err, updated, settings.community === true);
394
+ }
395
+ const nowFeatures = after.features ?? [];
396
+ if (wanted.includes("COMMUNITY") !== nowFeatures.includes("COMMUNITY")) throw new Error(`${appliedPrefix(updated)}sent the community feature but the server came back different -- community features need a rules channel, an updates channel, verification of at least low and the content filter on all members`);
397
+ if (settings.community) {
398
+ const lost = fresh.filter((f) => f !== "COMMUNITY" && !nowFeatures.includes(f));
399
+ if (lost.length > 0) throw new Error(`turned community on, but the server no longer has ${lost.join(", ")} -- another admin may have changed its features at the same time; check Server Settings and re-run`);
400
+ }
401
+ if (updatesWithCommunity && after.public_updates_channel_id !== updatesId) throw new Error(`${appliedPrefix(updated)}turned community on, but the server did not keep ${settings.updatesChannel} as its updates channel`);
402
+ if (updatesWithCommunity && updatesChanged) updated.push("updatesChannel");
403
+ updated.push("community");
404
+ };
405
+ if (toggleCommunity && settings.community === false) {
406
+ await toggle();
407
+ await ordinary();
408
+ } else {
409
+ await ordinary();
410
+ await toggle();
356
411
  }
357
412
  return { updated };
358
413
  }
@@ -366,6 +421,7 @@ var DiscordNotifications = class DiscordNotifications {
366
421
  const value = server?.[field];
367
422
  if (value !== void 0 && !Object.hasOwn(map, value)) return `server: \`${field}\` is ${JSON.stringify(value)}; use one of ${Object.keys(map).join(", ")}`;
368
423
  }
424
+ if (server?.community === false && server.updatesChannel !== void 0) return "server: `updatesChannel` can only be set while community features are on; remove it or set `community: true`";
369
425
  if (server?.locale !== void 0 && !LOCALES.has(server.locale)) return `server: \`locale\` ${JSON.stringify(server.locale)} is not a locale Discord accepts (for example en-US, en-GB, de, fr)`;
370
426
  if (server?.community === true && (server.verification === void 0 || server.verification === "none")) return "server: community features need `verification` of at least `low`";
371
427
  if (server?.community === true && server.contentFilter !== "all") return "server: community features need `contentFilter: \"all\"`";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-discord",
3
- "version": "5.0.0-alpha.191",
3
+ "version": "5.0.0-alpha.193",
4
4
  "description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
5
5
  "keywords": [
6
6
  "discord",
@@ -48,12 +48,12 @@
48
48
  "tsx": "4.23.15",
49
49
  "typescript": "^5.9.3",
50
50
  "vitest": "^4.1.11",
51
- "@theholocron/cli": "5.0.0-alpha.191"
51
+ "@theholocron/cli": "5.0.0-alpha.193"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "@theholocron/discord-client": "^1.44.0",
55
55
  "@theholocron/misc-utils": "^1.16.0",
56
- "@theholocron/cli": "5.0.0-alpha.191"
56
+ "@theholocron/cli": "5.0.0-alpha.193"
57
57
  },
58
58
  "engines": {
59
59
  "node": ">=22"