@theholocron/holocron-plugin-discord 5.0.0-alpha.190 → 5.0.0-alpha.191
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 +10 -1
- package/dist/index.mjs +187 -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,15 @@ 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
|
+
/** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
|
|
60
|
+
private manageServerHint;
|
|
61
|
+
ensureServer(settings: NotificationsServerLayout): Promise<{
|
|
62
|
+
updated: string[];
|
|
63
|
+
}>;
|
|
55
64
|
validateLayout(layout: NotificationsLayout): string | undefined;
|
|
56
65
|
private botUser?;
|
|
57
66
|
private botId;
|
package/dist/index.mjs
CHANGED
|
@@ -16,6 +16,78 @@ 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
|
+
/** A layout name to Discord's number, undefined when the layout leaves it out; an unknown name is an error, not an omission. */
|
|
86
|
+
function s_(name, map) {
|
|
87
|
+
if (name === void 0) return void 0;
|
|
88
|
+
if (!Object.hasOwn(map, name)) throw new Error(`unknown value ${JSON.stringify(name)}; use one of ${Object.keys(map).join(", ")}`);
|
|
89
|
+
return map[name];
|
|
90
|
+
}
|
|
19
91
|
/** `#rrggbb` to Discord's integer colour. */
|
|
20
92
|
function colorToInt(hex) {
|
|
21
93
|
if (!/^#[0-9a-fA-F]{6}$/.test(hex)) throw new Error(`invalid colour ${JSON.stringify(hex)}: use #rrggbb`);
|
|
@@ -168,6 +240,31 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
168
240
|
} catch (err) {
|
|
169
241
|
rolesError = reason(err);
|
|
170
242
|
}
|
|
243
|
+
let server;
|
|
244
|
+
let serverError;
|
|
245
|
+
if (layout.server) try {
|
|
246
|
+
const guild = await bot.guilds.get(this.guild());
|
|
247
|
+
const channelName = (id) => id ? channels.find((c) => c.id === id)?.name ?? id : void 0;
|
|
248
|
+
const verification = nameOf(VERIFICATION, guild.verification_level);
|
|
249
|
+
const defaultNotifications = nameOf(NOTIFICATIONS, guild.default_message_notifications);
|
|
250
|
+
const contentFilter = nameOf(FILTER, guild.explicit_content_filter);
|
|
251
|
+
const systemChannel = channelName(guild.system_channel_id);
|
|
252
|
+
const rulesChannel = channelName(guild.rules_channel_id);
|
|
253
|
+
const updatesChannel = channelName(guild.public_updates_channel_id);
|
|
254
|
+
server = {
|
|
255
|
+
...verification ? { verification } : {},
|
|
256
|
+
...defaultNotifications ? { defaultNotifications } : {},
|
|
257
|
+
...contentFilter ? { contentFilter } : {},
|
|
258
|
+
...systemChannel ? { systemChannel } : {},
|
|
259
|
+
...rulesChannel ? { rulesChannel } : {},
|
|
260
|
+
...updatesChannel ? { updatesChannel } : {},
|
|
261
|
+
community: (guild.features ?? []).includes("COMMUNITY"),
|
|
262
|
+
...guild.description !== void 0 && guild.description !== null ? { description: guild.description } : {},
|
|
263
|
+
...guild.preferred_locale ? { locale: guild.preferred_locale } : {}
|
|
264
|
+
};
|
|
265
|
+
} catch (err) {
|
|
266
|
+
serverError = reason(err);
|
|
267
|
+
}
|
|
171
268
|
const roleName = (id) => roles.find((r) => r.id === id)?.name ?? id;
|
|
172
269
|
found.forEach((entry, i) => {
|
|
173
270
|
entry.access = this.accessOf(text[i].permission_overwrites, roleName);
|
|
@@ -177,12 +274,101 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
177
274
|
return {
|
|
178
275
|
categories: [...categoryName.values()],
|
|
179
276
|
categoryAccess,
|
|
277
|
+
...server ? { server } : {},
|
|
278
|
+
...serverError ? { serverError } : {},
|
|
180
279
|
channels: found,
|
|
181
280
|
roles,
|
|
182
281
|
...rolesError ? { rolesError } : {}
|
|
183
282
|
};
|
|
184
283
|
}
|
|
284
|
+
/** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
|
|
285
|
+
async inviteUrl() {
|
|
286
|
+
const url = new URL("https://discord.com/oauth2/authorize");
|
|
287
|
+
url.searchParams.set("client_id", await this.botId());
|
|
288
|
+
url.searchParams.set("scope", "bot");
|
|
289
|
+
url.searchParams.set("permissions", permissions(BOT_NEEDS));
|
|
290
|
+
url.searchParams.set("guild_id", this.guild());
|
|
291
|
+
return url.toString();
|
|
292
|
+
}
|
|
293
|
+
/** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
|
|
294
|
+
async preflight(layout) {
|
|
295
|
+
if (!layout.server) return;
|
|
296
|
+
try {
|
|
297
|
+
await this.bot().guilds.modify(this.guild(), {});
|
|
298
|
+
} catch (err) {
|
|
299
|
+
throw await this.manageServerHint(err);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
/** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
|
|
303
|
+
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;
|
|
306
|
+
}
|
|
307
|
+
async ensureServer(settings) {
|
|
308
|
+
const bot = this.bot();
|
|
309
|
+
const guild = await bot.guilds.get(this.guild());
|
|
310
|
+
const channels = await this.channelList();
|
|
311
|
+
const idOf = (name) => {
|
|
312
|
+
const named = channels.filter((c) => (c.type === ChannelType.Text || c.type === ChannelType.Announcement) && DiscordNotifications.same(c.name, name));
|
|
313
|
+
if (named.length === 0) throw new Error(`server settings name the channel \`${name}\`, which does not exist on the server yet`);
|
|
314
|
+
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`);
|
|
315
|
+
return named[0].id;
|
|
316
|
+
};
|
|
317
|
+
const patch = {};
|
|
318
|
+
const updated = [];
|
|
319
|
+
const set = (label, key, want, have) => {
|
|
320
|
+
if (want !== void 0 && want !== have) {
|
|
321
|
+
patch[key] = want;
|
|
322
|
+
updated.push(label);
|
|
323
|
+
}
|
|
324
|
+
};
|
|
325
|
+
set("verification", "verification_level", s_(settings.verification, VERIFICATION), guild.verification_level);
|
|
326
|
+
set("defaultNotifications", "default_message_notifications", s_(settings.defaultNotifications, NOTIFICATIONS), guild.default_message_notifications);
|
|
327
|
+
set("contentFilter", "explicit_content_filter", s_(settings.contentFilter, FILTER), guild.explicit_content_filter);
|
|
328
|
+
set("systemChannel", "system_channel_id", settings.systemChannel && idOf(settings.systemChannel), guild.system_channel_id);
|
|
329
|
+
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);
|
|
331
|
+
set("description", "description", settings.description, guild.description ?? "");
|
|
332
|
+
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);
|
|
345
|
+
}
|
|
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`);
|
|
356
|
+
}
|
|
357
|
+
return { updated };
|
|
358
|
+
}
|
|
185
359
|
validateLayout(layout) {
|
|
360
|
+
const server = layout.server;
|
|
361
|
+
for (const [field, map] of [
|
|
362
|
+
["verification", VERIFICATION],
|
|
363
|
+
["defaultNotifications", NOTIFICATIONS],
|
|
364
|
+
["contentFilter", FILTER]
|
|
365
|
+
]) {
|
|
366
|
+
const value = server?.[field];
|
|
367
|
+
if (value !== void 0 && !Object.hasOwn(map, value)) return `server: \`${field}\` is ${JSON.stringify(value)}; use one of ${Object.keys(map).join(", ")}`;
|
|
368
|
+
}
|
|
369
|
+
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
|
+
if (server?.community === true && (server.verification === void 0 || server.verification === "none")) return "server: community features need `verification` of at least `low`";
|
|
371
|
+
if (server?.community === true && server.contentFilter !== "all") return "server: community features need `contentFilter: \"all\"`";
|
|
186
372
|
for (const role of layout.roles ?? []) try {
|
|
187
373
|
if (role.color !== void 0) colorToInt(role.color);
|
|
188
374
|
if (role.permissions !== void 0) permissions(role.permissions);
|
|
@@ -279,6 +465,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
279
465
|
}
|
|
280
466
|
guild() {
|
|
281
467
|
if (!this.opts.guildId) throw new Error("no Discord server id — set `guildId` in the discord provider options in holocron.config.ts");
|
|
468
|
+
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
469
|
return this.opts.guildId;
|
|
283
470
|
}
|
|
284
471
|
/**
|
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.191",
|
|
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.191"
|
|
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.191"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
59
|
"node": ">=22"
|