@theholocron/holocron-plugin-discord 5.0.0-alpha.278 → 5.0.0-alpha.279
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 +21 -0
- package/dist/index.mjs +14 -0
- package/package.json +6 -6
package/dist/index.d.mts
CHANGED
|
@@ -1,13 +1,17 @@
|
|
|
1
1
|
import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsWelcomeLayout, PluginToken, ResolveTokenInput, ServerInspection, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
2
2
|
import { DiscordBotClient, DiscordClient, DiscordClientOptions, DiscordOAuthClient, DiscordWebhookInfo, createDiscordClient, parseWebhookUrl } from "@theholocron/discord-client";
|
|
3
|
+
/** Resolves the Discord webhook URL from `--token`, `HOLOCRON_DISCORD_WEBHOOK`, `DISCORD_WEBHOOK_URL` or the keyring, and throws an `AuthError` when none is set. */
|
|
3
4
|
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
5
|
+
/** Resolves the Discord bot token used to provision channels, roles and webhooks, from `HOLOCRON_DISCORD_BOT_TOKEN`, `DISCORD_BOT_TOKEN` or the keyring. */
|
|
4
6
|
export declare const resolveBotToken: import("@theholocron/cli").TokenResolver;
|
|
7
|
+
/** Resolves the Discord application's OAuth client secret used to sign members in, from `HOLOCRON_DISCORD_CLIENT_SECRET`, `DISCORD_CLIENT_SECRET` or the keyring. */
|
|
5
8
|
export declare const resolveClientSecret: import("@theholocron/cli").TokenResolver;
|
|
6
9
|
/**
|
|
7
10
|
* Every token this plugin takes, for `holocron doctor tokens`. `verifyToken` checks a webhook URL, so the bot token and
|
|
8
11
|
* the OAuth client secret are listed but not handed to it.
|
|
9
12
|
*/
|
|
10
13
|
export declare const tokens: PluginToken[];
|
|
14
|
+
/** Options for the Discord `notifications` capability: webhook aliases, the default channel, and the server it provisions. */
|
|
11
15
|
interface DiscordNotificationsOptions {
|
|
12
16
|
/**
|
|
13
17
|
* Named aliases mapping a logical channel name to its webhook URL.
|
|
@@ -25,8 +29,10 @@ interface DiscordNotificationsOptions {
|
|
|
25
29
|
layout?: NotificationsLayout;
|
|
26
30
|
/** A custom API host, for tests. Webhook tokens are only sent to it when `unsafeBotBaseUrl` is also set. */
|
|
27
31
|
baseUrl?: string;
|
|
32
|
+
/** Also send the bot token to `baseUrl`. Off by default so a changed config cannot redirect the bot token to another host; tests that stub the API set it. */
|
|
28
33
|
unsafeBotBaseUrl?: boolean;
|
|
29
34
|
}
|
|
35
|
+
/** The Discord implementation of the `notifications` capability: sends messages through webhooks and provisions the server's channels, roles and webhooks with the bot. */
|
|
30
36
|
export declare class DiscordNotifications implements Notifications {
|
|
31
37
|
private readonly client;
|
|
32
38
|
private readonly opts;
|
|
@@ -36,7 +42,9 @@ export declare class DiscordNotifications implements Notifications {
|
|
|
36
42
|
private readonly bot;
|
|
37
43
|
/** Builds the OAuth client for one redirect URI; needs the application's client secret. */
|
|
38
44
|
private readonly oauth;
|
|
45
|
+
/** The capability this class provides, always `"notifications"`. */
|
|
39
46
|
readonly key: "notifications";
|
|
47
|
+
/** The provider name, `"discord"`. */
|
|
40
48
|
readonly providerName = "discord";
|
|
41
49
|
constructor(client: DiscordClient, opts: DiscordNotificationsOptions,
|
|
42
50
|
/** Memoized thunk — resolves the default webhook URL on the first `send()`. */
|
|
@@ -200,12 +208,14 @@ export declare class DiscordNotifications implements Notifications {
|
|
|
200
208
|
* channels count: reusing one beats creating a same-named text channel.
|
|
201
209
|
*/
|
|
202
210
|
private static findChannel;
|
|
211
|
+
/** Finds the text or announcement channel with this name (under the category, when given), or creates it; reports whether it was created. */
|
|
203
212
|
ensureChannel(input: {
|
|
204
213
|
name: string;
|
|
205
214
|
category?: string;
|
|
206
215
|
topic?: string;
|
|
207
216
|
access?: NotificationsAccess;
|
|
208
217
|
}): Promise<EnsuredResource>;
|
|
218
|
+
/** Finds the webhook with this name on the channel, or creates it; the optional avatar is the picture it posts with. */
|
|
209
219
|
ensureWebhook(input: {
|
|
210
220
|
channel: string;
|
|
211
221
|
name: string;
|
|
@@ -241,6 +251,7 @@ export declare class DiscordNotifications implements Notifications {
|
|
|
241
251
|
roleMembers(roleName: string): Promise<NotificationsMember[]>;
|
|
242
252
|
addRoleMember(roleName: string, memberId: string): Promise<void>;
|
|
243
253
|
removeRoleMember(roleName: string, memberId: string): Promise<void>;
|
|
254
|
+
/** Finds the role with this name, or creates it with the given mentionable, color, hoist and permissions settings; reports whether it was created. */
|
|
244
255
|
ensureRole(input: {
|
|
245
256
|
name: string;
|
|
246
257
|
mentionable?: boolean;
|
|
@@ -254,10 +265,13 @@ interface VerifyTokenOptions {
|
|
|
254
265
|
baseUrl?: string;
|
|
255
266
|
fetch?: typeof fetch;
|
|
256
267
|
}
|
|
268
|
+
/** Checks a Discord webhook URL by fetching the webhook; resolves to its name and id, or the failure message. */
|
|
257
269
|
export declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
270
|
+
/** Options for the Discord plugin: how the webhook URL is resolved plus the notifications settings. */
|
|
258
271
|
export interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOptions {
|
|
259
272
|
/** Override base URL for tests. Default: https://discord.com/api/v10 */
|
|
260
273
|
baseUrl?: string;
|
|
274
|
+
/** The `fetch` to use instead of the global one, for tests. */
|
|
261
275
|
fetch?: typeof fetch;
|
|
262
276
|
/**
|
|
263
277
|
* Also send the BOT token to `baseUrl`. Off by default: `baseUrl` comes from a
|
|
@@ -266,8 +280,11 @@ export interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotifica
|
|
|
266
280
|
*/
|
|
267
281
|
unsafeBotBaseUrl?: boolean;
|
|
268
282
|
}
|
|
283
|
+
/** The shared state the Discord plugin's capability and probes are built from. */
|
|
269
284
|
export interface PluginContext {
|
|
285
|
+
/** The options the plugin was created with. */
|
|
270
286
|
options: DiscordPluginOptions;
|
|
287
|
+
/** The webhook client used to send messages. */
|
|
271
288
|
client: DiscordClient;
|
|
272
289
|
/**
|
|
273
290
|
* Memoized — the resolved "token" IS Discord's default webhook URL, and it is
|
|
@@ -279,8 +296,11 @@ export interface PluginContext {
|
|
|
279
296
|
/** Builds the OAuth client for one redirect URI; resolves the application id and the client secret on first use. */
|
|
280
297
|
oauth: (redirectUri: string) => Promise<DiscordOAuthClient>;
|
|
281
298
|
}
|
|
299
|
+
/** Builds the plugin context from its options; the webhook URL, bot token and client secret are each resolved on first use. */
|
|
282
300
|
export declare function createContext(options?: DiscordPluginOptions): PluginContext;
|
|
301
|
+
/** Builds the `notifications` capability for a context. */
|
|
283
302
|
export declare function notifications(ctx: PluginContext): Notifications;
|
|
303
|
+
/** Creates the Discord plugin: its `notifications` capability and its `connection` probe. */
|
|
284
304
|
export declare function createPlugin(options?: DiscordPluginOptions): {
|
|
285
305
|
name: string;
|
|
286
306
|
probes: {
|
|
@@ -290,5 +310,6 @@ export declare function createPlugin(options?: DiscordPluginOptions): {
|
|
|
290
310
|
notifications: () => Notifications;
|
|
291
311
|
};
|
|
292
312
|
};
|
|
313
|
+
/** One-line hint printed by `holocron auth set discord` when no webhook URL is supplied or the supplied one is rejected. */
|
|
293
314
|
export declare const AUTH_HINT: string;
|
|
294
315
|
export { AuthError, type DiscordClient, type DiscordClientOptions, type DiscordNotificationsOptions, type DiscordWebhookInfo, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createDiscordClient, parseWebhookUrl };
|
package/dist/index.mjs
CHANGED
|
@@ -2,18 +2,21 @@ import { AuthError, ElevationRequiredError, ProviderApiError, connectionProbe, c
|
|
|
2
2
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
3
3
|
import { ApplicationFlag, ChannelType, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions } from "@theholocron/discord-client";
|
|
4
4
|
// src/auth.ts
|
|
5
|
+
/** Resolves the Discord webhook URL from `--token`, `HOLOCRON_DISCORD_WEBHOOK`, `DISCORD_WEBHOOK_URL` or the keyring, and throws an `AuthError` when none is set. */
|
|
5
6
|
const resolveToken = createResolveToken({
|
|
6
7
|
envName: "HOLOCRON_DISCORD_WEBHOOK",
|
|
7
8
|
vendorEnvName: "DISCORD_WEBHOOK_URL",
|
|
8
9
|
keyringService: "discord",
|
|
9
10
|
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/...>"
|
|
10
11
|
});
|
|
12
|
+
/** Resolves the Discord bot token used to provision channels, roles and webhooks, from `HOLOCRON_DISCORD_BOT_TOKEN`, `DISCORD_BOT_TOKEN` or the keyring. */
|
|
11
13
|
const resolveBotToken = createResolveToken({
|
|
12
14
|
envName: "HOLOCRON_DISCORD_BOT_TOKEN",
|
|
13
15
|
vendorEnvName: "DISCORD_BOT_TOKEN",
|
|
14
16
|
keyringService: "discord.holonet",
|
|
15
17
|
errorMessage: "no Discord bot token found. Set HOLOCRON_DISCORD_BOT_TOKEN (or DISCORD_BOT_TOKEN), or run: holocron auth set discord.holonet <token> — it is the bot token from the Discord developer portal (Bot → Reset Token), not a webhook URL."
|
|
16
18
|
});
|
|
19
|
+
/** Resolves the Discord application's OAuth client secret used to sign members in, from `HOLOCRON_DISCORD_CLIENT_SECRET`, `DISCORD_CLIENT_SECRET` or the keyring. */
|
|
17
20
|
const resolveClientSecret = createResolveToken({
|
|
18
21
|
envName: "HOLOCRON_DISCORD_CLIENT_SECRET",
|
|
19
22
|
vendorEnvName: "DISCORD_CLIENT_SECRET",
|
|
@@ -213,13 +216,16 @@ function keepThreadBits(desired, existing) {
|
|
|
213
216
|
let idCounter = 0;
|
|
214
217
|
/** A snowflake-shaped id for a new onboarding question or answer, which Discord asks the sender to make. */
|
|
215
218
|
const newId = () => String((BigInt(Date.now()) - 1420070400000n << 22n) + BigInt(idCounter++ % 4096));
|
|
219
|
+
/** The Discord implementation of the `notifications` capability: sends messages through webhooks and provisions the server's channels, roles and webhooks with the bot. */
|
|
216
220
|
var DiscordNotifications = class DiscordNotifications {
|
|
217
221
|
client;
|
|
218
222
|
opts;
|
|
219
223
|
defaultWebhookUrl;
|
|
220
224
|
bot;
|
|
221
225
|
oauth;
|
|
226
|
+
/** The capability this class provides, always `"notifications"`. */
|
|
222
227
|
key = "notifications";
|
|
228
|
+
/** The provider name, `"discord"`. */
|
|
223
229
|
providerName = "discord";
|
|
224
230
|
constructor(client, opts, defaultWebhookUrl, bot = () => {
|
|
225
231
|
throw new Error("no Discord bot client configured");
|
|
@@ -1265,6 +1271,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
1265
1271
|
if (!parentId) return named[0];
|
|
1266
1272
|
return named.find((c) => c.parent_id === parentId) ?? named.find((c) => !c.parent_id);
|
|
1267
1273
|
}
|
|
1274
|
+
/** Finds the text or announcement channel with this name (under the category, when given), or creates it; reports whether it was created. */
|
|
1268
1275
|
async ensureChannel(input) {
|
|
1269
1276
|
const parent = input.category ? (await this.ensureCategory(input.category)).id : void 0;
|
|
1270
1277
|
const existing = DiscordNotifications.findChannel(await this.channelList(), input.name, parent);
|
|
@@ -1302,6 +1309,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
1302
1309
|
created: true
|
|
1303
1310
|
};
|
|
1304
1311
|
}
|
|
1312
|
+
/** Finds the webhook with this name on the channel, or creates it; the optional avatar is the picture it posts with. */
|
|
1305
1313
|
async ensureWebhook(input) {
|
|
1306
1314
|
const bot = this.bot();
|
|
1307
1315
|
const parent = input.category ? (await this.channelList()).find((c) => c.type === ChannelType.Category && DiscordNotifications.same(c.name, input.category))?.id : void 0;
|
|
@@ -1480,6 +1488,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
1480
1488
|
async removeRoleMember(roleName, memberId) {
|
|
1481
1489
|
await this.bot().guilds.removeMemberRole(this.guild(), memberId, (await this.roleNamed(roleName)).id);
|
|
1482
1490
|
}
|
|
1491
|
+
/** Finds the role with this name, or creates it with the given mentionable, color, hoist and permissions settings; reports whether it was created. */
|
|
1483
1492
|
async ensureRole(input) {
|
|
1484
1493
|
const bot = this.bot();
|
|
1485
1494
|
const color = input.color !== void 0 ? colorToInt(input.color) : void 0;
|
|
@@ -1564,6 +1573,7 @@ var DiscordNotifications = class DiscordNotifications {
|
|
|
1564
1573
|
}
|
|
1565
1574
|
};
|
|
1566
1575
|
// src/verify-token.ts
|
|
1576
|
+
/** Checks a Discord webhook URL by fetching the webhook; resolves to its name and id, or the failure message. */
|
|
1567
1577
|
async function verifyToken(webhookUrl, opts = {}) {
|
|
1568
1578
|
try {
|
|
1569
1579
|
const { id, token } = parseWebhookUrl(webhookUrl);
|
|
@@ -1583,6 +1593,7 @@ async function verifyToken(webhookUrl, opts = {}) {
|
|
|
1583
1593
|
}
|
|
1584
1594
|
}
|
|
1585
1595
|
// src/index.ts
|
|
1596
|
+
/** Builds the plugin context from its options; the webhook URL, bot token and client secret are each resolved on first use. */
|
|
1586
1597
|
function createContext(options = {}) {
|
|
1587
1598
|
let url;
|
|
1588
1599
|
let bot;
|
|
@@ -1623,9 +1634,11 @@ function createContext(options = {}) {
|
|
|
1623
1634
|
}
|
|
1624
1635
|
};
|
|
1625
1636
|
}
|
|
1637
|
+
/** Builds the `notifications` capability for a context. */
|
|
1626
1638
|
function notifications(ctx) {
|
|
1627
1639
|
return new DiscordNotifications(ctx.client, ctx.options, ctx.defaultWebhookUrl, ctx.bot, ctx.oauth);
|
|
1628
1640
|
}
|
|
1641
|
+
/** Creates the Discord plugin: its `notifications` capability and its `connection` probe. */
|
|
1629
1642
|
function createPlugin(options = {}) {
|
|
1630
1643
|
const ctx = createContext(options);
|
|
1631
1644
|
return {
|
|
@@ -1643,5 +1656,6 @@ function createPlugin(options = {}) {
|
|
|
1643
1656
|
capabilities: { notifications: () => notifications(ctx) }
|
|
1644
1657
|
};
|
|
1645
1658
|
}
|
|
1659
|
+
/** One-line hint printed by `holocron auth set discord` when no webhook URL is supplied or the supplied one is rejected. */
|
|
1646
1660
|
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/...>";
|
|
1647
1661
|
export { AUTH_HINT, AuthError, DiscordNotifications, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveBotToken, resolveClientSecret, resolveToken, tokens, verifyToken };
|
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.279",
|
|
4
4
|
"description": "Holocron plugin for Discord. Implements the notifications capability via Discord incoming webhooks.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"discord",
|
|
@@ -41,19 +41,19 @@
|
|
|
41
41
|
"tsx": "4.23.15",
|
|
42
42
|
"typescript": "^5.9.3",
|
|
43
43
|
"vitest": "^5.0.5",
|
|
44
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
44
|
+
"@theholocron/cli": "5.0.0-alpha.279",
|
|
45
45
|
"@theholocron/discord-client": "^1.58.0-alpha.3",
|
|
46
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.4",
|
|
46
47
|
"@theholocron/misc-utils": "^1.16.1-alpha.3",
|
|
47
|
-
"@theholocron/http-client": "^1.58.0-alpha.3",
|
|
48
|
-
"@theholocron/tsdown-config": "^8.9.0-alpha.4",
|
|
49
48
|
"@theholocron/tsconfig": "^8.9.0-alpha.4",
|
|
49
|
+
"@theholocron/http-client": "^1.58.0-alpha.3",
|
|
50
50
|
"@theholocron/vitest-config": "^8.9.0-alpha.4",
|
|
51
|
-
"@theholocron/
|
|
51
|
+
"@theholocron/tsdown-config": "^8.9.0-alpha.4"
|
|
52
52
|
},
|
|
53
53
|
"peerDependencies": {
|
|
54
54
|
"@theholocron/discord-client": "^1.50.0",
|
|
55
55
|
"@theholocron/misc-utils": "^1.16.0",
|
|
56
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
56
|
+
"@theholocron/cli": "5.0.0-alpha.279"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
59
|
"node": ">=22"
|