@theholocron/holocron-plugin-discord 5.0.0-alpha.190 → 5.0.0-alpha.192
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 +16 -1
- package/dist/index.mjs +229 -0
- package/package.json +3 -3
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsAccess, NotificationsLayout, ResolveTokenInput, ServerInspection, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsAccess, NotificationsLayout, NotificationsServerLayout, ResolveTokenInput, ServerInspection, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
2
2
|
import { DiscordBotClient, DiscordClient, DiscordClientOptions, DiscordWebhookInfo, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
|
|
3
3
|
//#region src/auth.d.ts
|
|
4
4
|
declare const resolveToken: (input?: ResolveTokenInput) => string;
|
|
@@ -52,6 +52,21 @@ declare class DiscordNotifications implements Notifications {
|
|
|
52
52
|
* the layout, not with the server.
|
|
53
53
|
*/
|
|
54
54
|
inspect(layout: NotificationsLayout): Promise<ServerInspection>;
|
|
55
|
+
/** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
|
|
56
|
+
private inviteUrl;
|
|
57
|
+
/** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
|
|
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;
|
|
65
|
+
/** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
|
|
66
|
+
private manageServerHint;
|
|
67
|
+
ensureServer(settings: NotificationsServerLayout): Promise<{
|
|
68
|
+
updated: string[];
|
|
69
|
+
}>;
|
|
55
70
|
validateLayout(layout: NotificationsLayout): string | undefined;
|
|
56
71
|
private botUser?;
|
|
57
72
|
private botId;
|
package/dist/index.mjs
CHANGED
|
@@ -16,6 +16,82 @@ const resolveBotToken = createResolveToken({
|
|
|
16
16
|
});
|
|
17
17
|
//#endregion
|
|
18
18
|
//#region src/capabilities/notifications.ts
|
|
19
|
+
/** Discord's numeric settings, by the names the layout uses. */
|
|
20
|
+
const VERIFICATION = {
|
|
21
|
+
none: 0,
|
|
22
|
+
low: 1,
|
|
23
|
+
medium: 2,
|
|
24
|
+
high: 3,
|
|
25
|
+
highest: 4
|
|
26
|
+
};
|
|
27
|
+
const NOTIFICATIONS = {
|
|
28
|
+
all: 0,
|
|
29
|
+
mentions: 1
|
|
30
|
+
};
|
|
31
|
+
const FILTER = {
|
|
32
|
+
off: 0,
|
|
33
|
+
noRoles: 1,
|
|
34
|
+
all: 2
|
|
35
|
+
};
|
|
36
|
+
const nameOf = (map, value) => Object.keys(map).find((k) => map[k] === value);
|
|
37
|
+
/** What the bot needs in the server to do everything `setup` does. The invite link asks for exactly these. */
|
|
38
|
+
const BOT_NEEDS = [
|
|
39
|
+
"ViewChannel",
|
|
40
|
+
"SendMessages",
|
|
41
|
+
"ReadMessageHistory",
|
|
42
|
+
"ManageChannels",
|
|
43
|
+
"ManageRoles",
|
|
44
|
+
"ManageWebhooks",
|
|
45
|
+
"ManageGuild",
|
|
46
|
+
"CreatePublicThreads",
|
|
47
|
+
"CreatePrivateThreads",
|
|
48
|
+
"SendMessagesInThreads"
|
|
49
|
+
];
|
|
50
|
+
/** The locales Discord accepts for a server's preferred language. */
|
|
51
|
+
const LOCALES = /* @__PURE__ */ new Set([
|
|
52
|
+
"id",
|
|
53
|
+
"da",
|
|
54
|
+
"de",
|
|
55
|
+
"en-GB",
|
|
56
|
+
"en-US",
|
|
57
|
+
"es-ES",
|
|
58
|
+
"es-419",
|
|
59
|
+
"fr",
|
|
60
|
+
"hr",
|
|
61
|
+
"it",
|
|
62
|
+
"lt",
|
|
63
|
+
"hu",
|
|
64
|
+
"nl",
|
|
65
|
+
"no",
|
|
66
|
+
"pl",
|
|
67
|
+
"pt-BR",
|
|
68
|
+
"ro",
|
|
69
|
+
"fi",
|
|
70
|
+
"sv-SE",
|
|
71
|
+
"vi",
|
|
72
|
+
"tr",
|
|
73
|
+
"cs",
|
|
74
|
+
"el",
|
|
75
|
+
"bg",
|
|
76
|
+
"ru",
|
|
77
|
+
"uk",
|
|
78
|
+
"hi",
|
|
79
|
+
"th",
|
|
80
|
+
"zh-CN",
|
|
81
|
+
"ja",
|
|
82
|
+
"zh-TW",
|
|
83
|
+
"ko"
|
|
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
|
+
}
|
|
89
|
+
/** A layout name to Discord's number, undefined when the layout leaves it out; an unknown name is an error, not an omission. */
|
|
90
|
+
function s_(name, map) {
|
|
91
|
+
if (name === void 0) return void 0;
|
|
92
|
+
if (!Object.hasOwn(map, name)) throw new Error(`unknown value ${JSON.stringify(name)}; use one of ${Object.keys(map).join(", ")}`);
|
|
93
|
+
return map[name];
|
|
94
|
+
}
|
|
19
95
|
/** `#rrggbb` to Discord's integer colour. */
|
|
20
96
|
function colorToInt(hex) {
|
|
21
97
|
if (!/^#[0-9a-fA-F]{6}$/.test(hex)) throw new Error(`invalid colour ${JSON.stringify(hex)}: use #rrggbb`);
|
|
@@ -168,6 +244,31 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
168
244
|
} catch (err) {
|
|
169
245
|
rolesError = reason(err);
|
|
170
246
|
}
|
|
247
|
+
let server;
|
|
248
|
+
let serverError;
|
|
249
|
+
if (layout.server) try {
|
|
250
|
+
const guild = await bot.guilds.get(this.guild());
|
|
251
|
+
const channelName = (id) => id ? channels.find((c) => c.id === id)?.name ?? id : void 0;
|
|
252
|
+
const verification = nameOf(VERIFICATION, guild.verification_level);
|
|
253
|
+
const defaultNotifications = nameOf(NOTIFICATIONS, guild.default_message_notifications);
|
|
254
|
+
const contentFilter = nameOf(FILTER, guild.explicit_content_filter);
|
|
255
|
+
const systemChannel = channelName(guild.system_channel_id);
|
|
256
|
+
const rulesChannel = channelName(guild.rules_channel_id);
|
|
257
|
+
const updatesChannel = channelName(guild.public_updates_channel_id);
|
|
258
|
+
server = {
|
|
259
|
+
...verification ? { verification } : {},
|
|
260
|
+
...defaultNotifications ? { defaultNotifications } : {},
|
|
261
|
+
...contentFilter ? { contentFilter } : {},
|
|
262
|
+
...systemChannel ? { systemChannel } : {},
|
|
263
|
+
...rulesChannel ? { rulesChannel } : {},
|
|
264
|
+
...updatesChannel ? { updatesChannel } : {},
|
|
265
|
+
community: (guild.features ?? []).includes("COMMUNITY"),
|
|
266
|
+
...guild.description !== void 0 && guild.description !== null ? { description: guild.description } : {},
|
|
267
|
+
...guild.preferred_locale ? { locale: guild.preferred_locale } : {}
|
|
268
|
+
};
|
|
269
|
+
} catch (err) {
|
|
270
|
+
serverError = reason(err);
|
|
271
|
+
}
|
|
171
272
|
const roleName = (id) => roles.find((r) => r.id === id)?.name ?? id;
|
|
172
273
|
found.forEach((entry, i) => {
|
|
173
274
|
entry.access = this.accessOf(text[i].permission_overwrites, roleName);
|
|
@@ -177,12 +278,139 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
177
278
|
return {
|
|
178
279
|
categories: [...categoryName.values()],
|
|
179
280
|
categoryAccess,
|
|
281
|
+
...server ? { server } : {},
|
|
282
|
+
...serverError ? { serverError } : {},
|
|
180
283
|
channels: found,
|
|
181
284
|
roles,
|
|
182
285
|
...rolesError ? { rolesError } : {}
|
|
183
286
|
};
|
|
184
287
|
}
|
|
288
|
+
/** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
|
|
289
|
+
async inviteUrl(names = BOT_NEEDS) {
|
|
290
|
+
const url = new URL("https://discord.com/oauth2/authorize");
|
|
291
|
+
url.searchParams.set("client_id", await this.botId());
|
|
292
|
+
url.searchParams.set("scope", "bot");
|
|
293
|
+
url.searchParams.set("permissions", permissions(names));
|
|
294
|
+
url.searchParams.set("guild_id", this.guild());
|
|
295
|
+
return url.toString();
|
|
296
|
+
}
|
|
297
|
+
/** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
|
|
298
|
+
async preflight(layout) {
|
|
299
|
+
if (!layout.server) return;
|
|
300
|
+
try {
|
|
301
|
+
await this.bot().guilds.modify(this.guild(), {});
|
|
302
|
+
} catch (err) {
|
|
303
|
+
throw await this.manageServerHint(err);
|
|
304
|
+
}
|
|
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
|
+
}
|
|
326
|
+
/** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
|
|
327
|
+
async manageServerHint(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 });
|
|
331
|
+
}
|
|
332
|
+
async ensureServer(settings) {
|
|
333
|
+
const bot = this.bot();
|
|
334
|
+
const guild = await bot.guilds.get(this.guild());
|
|
335
|
+
const channels = await this.channelList();
|
|
336
|
+
const idOf = (name) => {
|
|
337
|
+
const named = channels.filter((c) => (c.type === ChannelType.Text || c.type === ChannelType.Announcement) && DiscordNotifications.same(c.name, name));
|
|
338
|
+
if (named.length === 0) throw new Error(`server settings name the channel \`${name}\`, which does not exist on the server yet`);
|
|
339
|
+
if (named.length > 1) throw new Error(`server settings name the channel \`${name}\`, but ${named.length} channels have that name (ids ${named.map((c) => c.id).join(", ")}) -- rename one`);
|
|
340
|
+
return named[0].id;
|
|
341
|
+
};
|
|
342
|
+
const patch = {};
|
|
343
|
+
const updated = [];
|
|
344
|
+
const set = (label, key, want, have) => {
|
|
345
|
+
if (want !== void 0 && want !== have) {
|
|
346
|
+
patch[key] = want;
|
|
347
|
+
updated.push(label);
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
set("verification", "verification_level", s_(settings.verification, VERIFICATION), guild.verification_level);
|
|
351
|
+
set("defaultNotifications", "default_message_notifications", s_(settings.defaultNotifications, NOTIFICATIONS), guild.default_message_notifications);
|
|
352
|
+
set("contentFilter", "explicit_content_filter", s_(settings.contentFilter, FILTER), guild.explicit_content_filter);
|
|
353
|
+
set("systemChannel", "system_channel_id", settings.systemChannel && idOf(settings.systemChannel), guild.system_channel_id);
|
|
354
|
+
set("rulesChannel", "rules_channel_id", settings.rulesChannel && idOf(settings.rulesChannel), guild.rules_channel_id);
|
|
355
|
+
set("updatesChannel", "public_updates_channel_id", settings.updatesChannel && idOf(settings.updatesChannel), guild.public_updates_channel_id);
|
|
356
|
+
set("description", "description", settings.description, guild.description ?? "");
|
|
357
|
+
set("locale", "preferred_locale", settings.locale, guild.preferred_locale);
|
|
358
|
+
const community = (guild.features ?? []).includes("COMMUNITY");
|
|
359
|
+
const toggleCommunity = settings.community !== void 0 && settings.community !== community;
|
|
360
|
+
const ordinary = async () => {
|
|
361
|
+
if (Object.keys(patch).length === 0) return;
|
|
362
|
+
let after;
|
|
363
|
+
try {
|
|
364
|
+
after = await bot.guilds.modify(this.guild(), patch);
|
|
365
|
+
} catch (err) {
|
|
366
|
+
throw await this.manageServerHint(err);
|
|
367
|
+
}
|
|
368
|
+
const stuck = Object.keys(patch).filter((k) => {
|
|
369
|
+
const got = after[k];
|
|
370
|
+
return patch[k] !== (k === "description" ? got ?? "" : got);
|
|
371
|
+
});
|
|
372
|
+
if (stuck.length > 0) throw new Error(`sent ${stuck.join(", ")} but the server came back different -- Discord may have refused a part of it`);
|
|
373
|
+
};
|
|
374
|
+
const toggle = async () => {
|
|
375
|
+
if (!toggleCommunity) return;
|
|
376
|
+
const fresh = (await bot.guilds.get(this.guild())).features ?? [];
|
|
377
|
+
const wanted = settings.community ? [.../* @__PURE__ */ new Set([...fresh, "COMMUNITY"])] : fresh.filter((f) => f !== "COMMUNITY");
|
|
378
|
+
let after;
|
|
379
|
+
try {
|
|
380
|
+
after = await bot.guilds.modify(this.guild(), { features: wanted });
|
|
381
|
+
} catch (err) {
|
|
382
|
+
throw await this.communityHint(err, updated, settings.community === true);
|
|
383
|
+
}
|
|
384
|
+
const nowFeatures = after.features ?? [];
|
|
385
|
+
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`);
|
|
386
|
+
if (settings.community) {
|
|
387
|
+
const lost = fresh.filter((f) => f !== "COMMUNITY" && !nowFeatures.includes(f));
|
|
388
|
+
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`);
|
|
389
|
+
}
|
|
390
|
+
updated.push("community");
|
|
391
|
+
};
|
|
392
|
+
if (toggleCommunity && settings.community === false) {
|
|
393
|
+
await toggle();
|
|
394
|
+
await ordinary();
|
|
395
|
+
} else {
|
|
396
|
+
await ordinary();
|
|
397
|
+
await toggle();
|
|
398
|
+
}
|
|
399
|
+
return { updated };
|
|
400
|
+
}
|
|
185
401
|
validateLayout(layout) {
|
|
402
|
+
const server = layout.server;
|
|
403
|
+
for (const [field, map] of [
|
|
404
|
+
["verification", VERIFICATION],
|
|
405
|
+
["defaultNotifications", NOTIFICATIONS],
|
|
406
|
+
["contentFilter", FILTER]
|
|
407
|
+
]) {
|
|
408
|
+
const value = server?.[field];
|
|
409
|
+
if (value !== void 0 && !Object.hasOwn(map, value)) return `server: \`${field}\` is ${JSON.stringify(value)}; use one of ${Object.keys(map).join(", ")}`;
|
|
410
|
+
}
|
|
411
|
+
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)`;
|
|
412
|
+
if (server?.community === true && (server.verification === void 0 || server.verification === "none")) return "server: community features need `verification` of at least `low`";
|
|
413
|
+
if (server?.community === true && server.contentFilter !== "all") return "server: community features need `contentFilter: \"all\"`";
|
|
186
414
|
for (const role of layout.roles ?? []) try {
|
|
187
415
|
if (role.color !== void 0) colorToInt(role.color);
|
|
188
416
|
if (role.permissions !== void 0) permissions(role.permissions);
|
|
@@ -279,6 +507,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
279
507
|
}
|
|
280
508
|
guild() {
|
|
281
509
|
if (!this.opts.guildId) throw new Error("no Discord server id — set `guildId` in the discord provider options in holocron.config.ts");
|
|
510
|
+
if (!/^\d{1,20}$/.test(this.opts.guildId)) throw new Error(`\`guildId\` ${JSON.stringify(this.opts.guildId)} is not a Discord server id (digits only)`);
|
|
282
511
|
return this.opts.guildId;
|
|
283
512
|
}
|
|
284
513
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-discord",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.192",
|
|
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.
|
|
51
|
+
"@theholocron/cli": "5.0.0-alpha.192"
|
|
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.
|
|
56
|
+
"@theholocron/cli": "5.0.0-alpha.192"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
59
|
"node": ">=22"
|