@theholocron/holocron-plugin-discord 5.0.0-alpha.35 → 5.0.0-alpha.350
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/README.md +28 -0
- package/dist/index.d.mts +324 -53
- package/dist/index.mjs +1987 -42
- package/package.json +28 -24
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
<!-- alex disable host-hostess -->
|
|
2
|
+
|
|
1
3
|
<!-- editorconfig-checker-disable-file -->
|
|
2
4
|
|
|
3
5
|
# `@theholocron/holocron-plugin-discord`
|
|
@@ -61,3 +63,29 @@ server membership is required — generate one in Discord under
|
|
|
61
63
|
The webhook id and token are embedded in the URL path — no `Authorization`
|
|
62
64
|
header is sent. `parseWebhookUrl` is exported as a utility for callers
|
|
63
65
|
that need to split the URL into its parts.
|
|
66
|
+
|
|
67
|
+
## Provisioning
|
|
68
|
+
|
|
69
|
+
`holocron notifications setup` and `holocron notifications channel add` create
|
|
70
|
+
channels, roles and webhooks through the `notifications` capability's `ensure*`
|
|
71
|
+
methods. They use the **Holonet bot**, not a webhook URL:
|
|
72
|
+
|
|
73
|
+
- `HOLOCRON_DISCORD_BOT_TOKEN` (or `DISCORD_BOT_TOKEN`), or the keyring entry
|
|
74
|
+
`discord.holonet` (`holocron auth set discord.holonet <token>`) — the bot token
|
|
75
|
+
from the Developer Portal. Only read when a provisioning command runs, or when
|
|
76
|
+
`holocron doctor` checks a provider that has a `guildId`; posting never needs it.
|
|
77
|
+
- `HOLOCRON_DISCORD_CLIENT_SECRET` (or `DISCORD_CLIENT_SECRET`), or the keyring entry
|
|
78
|
+
`discord.holonet.oauth` — the application's OAuth client secret (Developer Portal →
|
|
79
|
+
OAuth2 → Reset Secret). Only `holocron notifications link` reads it, to learn which
|
|
80
|
+
GitHub account a member owns; the API can neither create nor read it.
|
|
81
|
+
- `guildId` — the server id (not a secret), set in the provider options.
|
|
82
|
+
- `layout` — categories, channels (each optionally with a `webhook`) and roles.
|
|
83
|
+
|
|
84
|
+
The bot needs Manage Channels, Manage Roles, Manage Webhooks and View Channels.
|
|
85
|
+
Everything is idempotent (looked up by name). Discord returns a webhook's URL
|
|
86
|
+
only to the application that created it, so a webhook the bot did not create
|
|
87
|
+
cannot have its URL read back.
|
|
88
|
+
|
|
89
|
+
`baseUrl` only redirects posting. The bot token is always sent to the real
|
|
90
|
+
Discord API unless `unsafeBotBaseUrl: true` is also set (meant for tests that
|
|
91
|
+
stub the API), so a changed config cannot redirect the token to another host.
|
package/dist/index.d.mts
CHANGED
|
@@ -1,32 +1,18 @@
|
|
|
1
|
-
import { AuthError, Notifications, ResolveTokenInput } from "@theholocron/cli";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
interface DiscordClient {
|
|
17
|
-
webhooks: {
|
|
18
|
-
get(id: string, token: string): Promise<DiscordWebhookInfo>;
|
|
19
|
-
execute(id: string, token: string, content: string): Promise<void>;
|
|
20
|
-
};
|
|
21
|
-
}
|
|
22
|
-
declare function createDiscordClient({ baseUrl, fetch: fetchImpl }?: DiscordClientOptions): DiscordClient;
|
|
23
|
-
/** Parse a Discord webhook URL into its id and token parts. */
|
|
24
|
-
declare function parseWebhookUrl(url: string): {
|
|
25
|
-
id: string;
|
|
26
|
-
token: string;
|
|
27
|
-
};
|
|
28
|
-
//#endregion
|
|
29
|
-
//#region src/capabilities/notifications.d.ts
|
|
1
|
+
import { AuthError, DiscussionPatch, DiscussionPost, EnsureDiscussionInput, EnsureWebhookResult, EnsuredDiscussion, EnsuredResource, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsForumTag, NotificationsLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsWelcomeLayout, PluginToken, ResolveTokenInput, ServerInspection, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
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. */
|
|
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. */
|
|
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. */
|
|
8
|
+
export declare const resolveClientSecret: import("@theholocron/cli").TokenResolver;
|
|
9
|
+
/**
|
|
10
|
+
* Every token this plugin takes, for `holocron doctor tokens`. `verifyToken` checks a webhook URL, so the bot token and
|
|
11
|
+
* the OAuth client secret are listed but not handed to it. The webhook is the last resort for a post that names no
|
|
12
|
+
* channel, alias or `defaultChannel`, so nothing needs it by default (`optional`).
|
|
13
|
+
*/
|
|
14
|
+
export declare const tokens: PluginToken[];
|
|
15
|
+
/** Options for the Discord `notifications` capability: webhook aliases, the default channel, and the server it provisions. */
|
|
30
16
|
interface DiscordNotificationsOptions {
|
|
31
17
|
/**
|
|
32
18
|
* Named aliases mapping a logical channel name to its webhook URL.
|
|
@@ -38,60 +24,345 @@ interface DiscordNotificationsOptions {
|
|
|
38
24
|
* without an explicit channel, or with an empty string.
|
|
39
25
|
*/
|
|
40
26
|
defaultChannel?: string;
|
|
27
|
+
/** Discord server (guild) id that `notifications setup` provisions. Not a secret. */
|
|
28
|
+
guildId?: string;
|
|
29
|
+
/** The server layout `notifications setup` applies. */
|
|
30
|
+
layout?: NotificationsLayout;
|
|
31
|
+
/** A custom API host, for tests. Webhook tokens are only sent to it when `unsafeBotBaseUrl` is also set. */
|
|
32
|
+
baseUrl?: string;
|
|
33
|
+
/** 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. */
|
|
34
|
+
unsafeBotBaseUrl?: boolean;
|
|
41
35
|
}
|
|
42
|
-
|
|
36
|
+
/** The Discord implementation of the `notifications` capability: sends messages through webhooks and provisions the server's channels, roles and webhooks with the bot. */
|
|
37
|
+
export declare class DiscordNotifications implements Notifications {
|
|
43
38
|
private readonly client;
|
|
44
39
|
private readonly opts;
|
|
45
40
|
/** Memoized thunk — resolves the default webhook URL on the first `send()`. */
|
|
46
41
|
private readonly defaultWebhookUrl;
|
|
42
|
+
/** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
|
|
43
|
+
private readonly bot;
|
|
44
|
+
/** Builds the OAuth client for one redirect URI; needs the application's client secret. */
|
|
45
|
+
private readonly oauth;
|
|
46
|
+
/** The capability this class provides, always `"notifications"`. */
|
|
47
47
|
readonly key: "notifications";
|
|
48
|
+
/** The provider name, `"discord"`. */
|
|
48
49
|
readonly providerName = "discord";
|
|
49
50
|
constructor(client: DiscordClient, opts: DiscordNotificationsOptions,
|
|
50
51
|
/** Memoized thunk — resolves the default webhook URL on the first `send()`. */
|
|
51
|
-
defaultWebhookUrl: () => string
|
|
52
|
+
defaultWebhookUrl: () => string,
|
|
53
|
+
/** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
|
|
54
|
+
bot?: () => DiscordBotClient,
|
|
55
|
+
/** Builds the OAuth client for one redirect URI; needs the application's client secret. */
|
|
56
|
+
oauth?: (redirectUri: string) => Promise<DiscordOAuthClient>);
|
|
57
|
+
/**
|
|
58
|
+
* Sign a member in with Discord to learn which GitHub account they own. Asks only for `identify` and
|
|
59
|
+
* `connections`, reads the account Discord has verified, and revokes the token before returning: nothing
|
|
60
|
+
* about the sign-in is kept.
|
|
61
|
+
*/
|
|
62
|
+
signIn(): NotificationsSignIn;
|
|
63
|
+
get layout(): NotificationsLayout | undefined;
|
|
52
64
|
send(channel: string, message: string): Promise<void>;
|
|
65
|
+
/**
|
|
66
|
+
* `holocron doctor`: the bot token is valid and can see the configured server.
|
|
67
|
+
* Null when no `guildId` is set -- a post-only config has no bot to check. A
|
|
68
|
+
* `layout` without a `guildId` is a half-written provisioning config, so that
|
|
69
|
+
* fails instead of passing as post-only.
|
|
70
|
+
*/
|
|
71
|
+
whoami(): Promise<{
|
|
72
|
+
target: string;
|
|
73
|
+
} | null>;
|
|
74
|
+
/**
|
|
75
|
+
* Read-only: what is on the server, for the parts of `layout` we will compare. Webhooks are
|
|
76
|
+
* listed only for channels the layout gives one (one request each), so the cost scales with
|
|
77
|
+
* the layout, not with the server.
|
|
78
|
+
*/
|
|
79
|
+
inspect(layout: NotificationsLayout): Promise<ServerInspection>;
|
|
80
|
+
/**
|
|
81
|
+
* What the bot keeps: the usual set, Pin Messages when the layout pins messages, and Manage Threads when it
|
|
82
|
+
* declares a forum (a post's tags are applied by the bot, and a moderated tag only by someone who can manage threads).
|
|
83
|
+
*/
|
|
84
|
+
private needs;
|
|
85
|
+
/** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
|
|
86
|
+
private inviteUrl;
|
|
87
|
+
/** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
|
|
88
|
+
preflight(layout: NotificationsLayout): Promise<void>;
|
|
89
|
+
/** The one role with this name, or an error saying why not: two would mean granting something to the wrong members. */
|
|
90
|
+
private static pickRole;
|
|
91
|
+
/**
|
|
92
|
+
* The one text or announcement channel with this name, or an error saying why not. A forum counts only for a
|
|
93
|
+
* setting that can point at one (`forums`): the welcome screen and onboarding can; a pinned message and the server's
|
|
94
|
+
* own channels cannot.
|
|
95
|
+
*/
|
|
96
|
+
private static pickChannelId;
|
|
97
|
+
/** True for a 403 that is about permissions, not about the bot being unable to see the server at all. */
|
|
98
|
+
private static missingPermissions;
|
|
99
|
+
/** An invite link, or nothing when building it needs a request that fails: the advice must not depend on one. */
|
|
100
|
+
private inviteOrNothing;
|
|
101
|
+
/**
|
|
102
|
+
* Changing a role's permissions is refused (403) when the role would gain one the bot does not hold itself: Discord
|
|
103
|
+
* lets a bot give only what it has. The bot's own role is managed by its integration, so it cannot be edited by
|
|
104
|
+
* hand; re-authorising the bot with the permissions setup needs updates it in place.
|
|
105
|
+
*/
|
|
106
|
+
private rolePermissionsHint;
|
|
107
|
+
/** Turning community on or off needs Administrator, which is more than the bot should keep. */
|
|
108
|
+
private communityHint;
|
|
109
|
+
/** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
|
|
110
|
+
private manageServerHint;
|
|
111
|
+
ensureServer(settings: NotificationsServerLayout): Promise<{
|
|
112
|
+
updated: string[];
|
|
113
|
+
}>;
|
|
114
|
+
/** What the bot's roles give it server-wide (the owner holds every permission), before any channel overwrite. */
|
|
115
|
+
private serverPermissions;
|
|
116
|
+
holdsPermission(permission: string): Promise<boolean>;
|
|
117
|
+
/**
|
|
118
|
+
* Whether a channel's own overwrites take a permission away from a bot whose roles grant it, in the order Discord
|
|
119
|
+
* applies them: @everyone, then the bot's roles, then the bot itself. Read fresh, since a person may have just edited them.
|
|
120
|
+
*/
|
|
121
|
+
private channelDenies;
|
|
122
|
+
/** The messages this bot posted in a channel, pinned or not, among the channel's last hundred. */
|
|
123
|
+
private ownMessages;
|
|
124
|
+
/**
|
|
125
|
+
* The layout's text with each `#name` that is one of the server's channels turned into Discord's own link to it
|
|
126
|
+
* (`<#id>`), so the message shows clickable channels. A name that matches no channel, or more than one, is left as written.
|
|
127
|
+
*/
|
|
128
|
+
private static linkChannels;
|
|
129
|
+
/**
|
|
130
|
+
* The text of a pinned message. The CLI reads a message's `file` into `content` before it calls the provider, so
|
|
131
|
+
* the text is only missing when a caller skipped that.
|
|
132
|
+
*/
|
|
133
|
+
private static pinText;
|
|
134
|
+
/** The layout's messages grouped by channel, in the order the channels first appear, with channel names linked. */
|
|
135
|
+
private static pinsByChannel;
|
|
136
|
+
/**
|
|
137
|
+
* What differs in one channel: the declared messages that are not pinned yet, and the bot's pinned messages the
|
|
138
|
+
* layout does not declare (or declares once and the bot pinned twice). The layout is the whole set of the bot's
|
|
139
|
+
* pins in a channel it names.
|
|
140
|
+
*/
|
|
141
|
+
private static pinDrift;
|
|
142
|
+
/** Whether each pinned message is in place: pinned by this bot with exactly the layout's text, and nothing else of the bot's pinned beside it. */
|
|
143
|
+
private pinnedStates;
|
|
144
|
+
private discussionStore?;
|
|
145
|
+
/** The discussion posts of this instance's forum channels, which read each forum once. */
|
|
146
|
+
private discussions;
|
|
147
|
+
/** Finds the post for a document in a forum channel, or makes it. See {@link DiscordDiscussions}. */
|
|
148
|
+
ensureDiscussion(input: EnsureDiscussionInput): Promise<EnsuredDiscussion>;
|
|
149
|
+
/** The post for a document in a forum channel, or `undefined`. */
|
|
150
|
+
readDiscussion(channel: string, key: string, url?: string): Promise<DiscussionPost | undefined>;
|
|
151
|
+
/** Changes a document's post: its title, its tag, the state last synced, the pull request line. */
|
|
152
|
+
updateDiscussion(channel: string, key: string, patch: DiscussionPatch): Promise<void>;
|
|
153
|
+
/**
|
|
154
|
+
* Posts `content` (up to 2000 characters) in a text channel as the bot, without letting it mention anyone. A `#name`
|
|
155
|
+
* that is one of the server's channels is linked.
|
|
156
|
+
*/
|
|
157
|
+
postMessage(channel: string, content: string): Promise<void>;
|
|
158
|
+
ensurePinned(pinned: NotificationsPinnedLayout[]): Promise<{
|
|
159
|
+
updated: string[];
|
|
160
|
+
}>;
|
|
161
|
+
/** A 403 on pinning becomes the missing permission and a link that grants it, which `setup` can walk a person through. */
|
|
162
|
+
private pinHint;
|
|
163
|
+
/** A 403 on the welcome screen or onboarding becomes the likely reason; anything else is passed on. */
|
|
164
|
+
private static communityFeatureHint;
|
|
165
|
+
/** The numeric code Discord puts in the JSON body of an error, or undefined when the body is not that. */
|
|
166
|
+
private static codeOf;
|
|
167
|
+
/** The welcome screen; a server that never had one answers 404 (10069), which is an empty screen. */
|
|
168
|
+
private welcomeScreenOf;
|
|
169
|
+
ensureWelcome(welcome: NotificationsWelcomeLayout): Promise<{
|
|
170
|
+
updated: string[];
|
|
171
|
+
}>;
|
|
172
|
+
/** An onboarding prompt reduced to what the layout can state, so the server's and the layout's can be compared. */
|
|
173
|
+
private static onboardingKey;
|
|
174
|
+
ensureOnboarding(onboarding: NotificationsOnboardingLayout): Promise<{
|
|
175
|
+
updated: string[];
|
|
176
|
+
}>;
|
|
177
|
+
ensureEveryone(everyone: NotificationsEveryoneLayout): Promise<{
|
|
178
|
+
updated: string[];
|
|
179
|
+
}>;
|
|
180
|
+
ensureApplication(app: NotificationsApplicationLayout): Promise<{
|
|
181
|
+
updated: string[];
|
|
182
|
+
todo?: string[];
|
|
183
|
+
}>;
|
|
184
|
+
/** Whether the Server Members Intent is on: the unverified app's toggle, or the verified app's own bit. */
|
|
185
|
+
private static membersIntentOn;
|
|
186
|
+
validateLayout(layout: NotificationsLayout): string | undefined;
|
|
187
|
+
private botUser?;
|
|
188
|
+
private botId;
|
|
189
|
+
/**
|
|
190
|
+
* The overwrites that make a channel look like `access`. The list is exact: it replaces
|
|
191
|
+
* whatever was set by hand. `[]` (public) when nothing is restricted.
|
|
192
|
+
*/
|
|
193
|
+
private overwritesFor;
|
|
194
|
+
/**
|
|
195
|
+
* Read an access back out of a channel's overwrites, naming roles as the layout does. Only
|
|
196
|
+
* overwrites of the shape {@link overwritesFor} writes can be read back; anything else
|
|
197
|
+
* (a role-specific deny, a member overwrite, only some of the posting bits) means the
|
|
198
|
+
* channel's real access is not something the layout can state, and is reported as `"custom"`
|
|
199
|
+
* rather than guessed at.
|
|
200
|
+
*/
|
|
201
|
+
private accessOf;
|
|
202
|
+
/** The server's roles, fetched once and forgotten whenever setup changes a role. */
|
|
203
|
+
private roleLoad?;
|
|
204
|
+
private roleList;
|
|
205
|
+
/** The server this run created, which takes over from `guildId` for the rest of the run. */
|
|
206
|
+
private createdGuild?;
|
|
207
|
+
private guild;
|
|
208
|
+
/**
|
|
209
|
+
* The server's channel list, fetched once per instance. Every ensure* call used
|
|
210
|
+
* to refetch it -- about 40 identical GETs in one setup run -- and Discord
|
|
211
|
+
* rate-limited the route. Our own creates and edits update the copy, so it
|
|
212
|
+
* stays accurate for the run; a new run builds a new instance.
|
|
213
|
+
*
|
|
214
|
+
* It is the in-flight promise that is shared, not the array: callers that start
|
|
215
|
+
* while the first fetch is pending all get the same snapshot, so a later
|
|
216
|
+
* response can never overwrite what an earlier caller added.
|
|
217
|
+
*/
|
|
218
|
+
private channelLoad?;
|
|
219
|
+
private channelList;
|
|
220
|
+
/**
|
|
221
|
+
* Create a channel and add it to the shared list. If the create fails, Discord
|
|
222
|
+
* may still have applied it (a timeout looks the same as a refusal), so forget the
|
|
223
|
+
* list: the next ensure refetches the server's real state instead of creating a
|
|
224
|
+
* duplicate.
|
|
225
|
+
*/
|
|
226
|
+
private createChannel;
|
|
227
|
+
private static same;
|
|
228
|
+
ensureCategory(name: string, opts?: {
|
|
229
|
+
access?: NotificationsAccess;
|
|
230
|
+
}): Promise<EnsuredResource>;
|
|
231
|
+
/**
|
|
232
|
+
* Edit a channel and keep the shared list in step; forget the list if the edit may have half-applied.
|
|
233
|
+
* Discord answers with the channel as it now is: if the overwrites that come back are not the ones we
|
|
234
|
+
* sent, something else changed it at the same time, so say so instead of reporting success.
|
|
235
|
+
*/
|
|
236
|
+
private modifyChannel;
|
|
237
|
+
/**
|
|
238
|
+
* Find a channel by name. A name can exist in several categories, so with a
|
|
239
|
+
* parent: prefer the one already there, then an uncategorised one (moved in);
|
|
240
|
+
* never grab a channel that lives under a different category. Announcement
|
|
241
|
+
* channels count: reusing one beats creating a same-named text channel.
|
|
242
|
+
*/
|
|
243
|
+
private static findChannel;
|
|
244
|
+
/** A forum tag in the layout's terms. */
|
|
245
|
+
private static tagOf;
|
|
246
|
+
/** A layout tag as Discord takes it. */
|
|
247
|
+
private static tagInput;
|
|
248
|
+
/**
|
|
249
|
+
* The forum's tags once the layout's are in: every tag it has already (kept, with the emoji and `moderated` the layout
|
|
250
|
+
* gives it) and each layout tag it lacks, added. A tag the layout does not list is never removed, since a post
|
|
251
|
+
* carries it. Returns `undefined` when nothing differs.
|
|
252
|
+
*/
|
|
253
|
+
private static mergeTags;
|
|
254
|
+
/**
|
|
255
|
+
* Finds the text or announcement channel with this name (under the category, when given), or creates it; reports
|
|
256
|
+
* whether it was created. With `kind: "forum"` it is a forum channel with the layout's tags. Discord cannot turn one
|
|
257
|
+
* kind into the other and this never deletes, so a channel of the other kind with the name stops the run with the fix.
|
|
258
|
+
*/
|
|
259
|
+
ensureChannel(input: {
|
|
260
|
+
name: string;
|
|
261
|
+
category?: string;
|
|
262
|
+
topic?: string;
|
|
263
|
+
access?: NotificationsAccess;
|
|
264
|
+
kind?: "text" | "forum";
|
|
265
|
+
tags?: NotificationsForumTag[];
|
|
266
|
+
}): Promise<EnsuredResource>;
|
|
267
|
+
/** Finds the webhook with this name on the channel, or creates it; the optional avatar is the picture it posts with. */
|
|
268
|
+
ensureWebhook(input: {
|
|
269
|
+
channel: string;
|
|
270
|
+
name: string;
|
|
271
|
+
category?: string;
|
|
272
|
+
avatar?: string;
|
|
273
|
+
}): Promise<EnsureWebhookResult>;
|
|
274
|
+
checkDelivery(input: {
|
|
275
|
+
channel: string;
|
|
276
|
+
name: string;
|
|
277
|
+
category?: string;
|
|
278
|
+
text: string;
|
|
279
|
+
keep?: boolean;
|
|
280
|
+
}): Promise<NotificationsDelivery>;
|
|
281
|
+
createServer(input: {
|
|
282
|
+
name: string;
|
|
283
|
+
force?: boolean;
|
|
284
|
+
}): Promise<{
|
|
285
|
+
id: string;
|
|
286
|
+
name: string;
|
|
287
|
+
}>;
|
|
288
|
+
/** A server this bot owns (not one it only belongs to) with exactly this name, read across every page. */
|
|
289
|
+
private botOwnedServer;
|
|
290
|
+
inviteLink(channelName: string): Promise<string>;
|
|
291
|
+
hasMember(memberId: string): Promise<boolean>;
|
|
292
|
+
transferServer(memberId: string): Promise<void>;
|
|
293
|
+
serverOwner(): Promise<{
|
|
294
|
+
id: string;
|
|
295
|
+
isBot: boolean;
|
|
296
|
+
name?: string;
|
|
297
|
+
}>;
|
|
298
|
+
/** The one role with this name, or an error that says what to fix: none, or more than one. */
|
|
299
|
+
private roleNamed;
|
|
300
|
+
roleMembers(roleName: string): Promise<NotificationsMember[]>;
|
|
301
|
+
addRoleMember(roleName: string, memberId: string): Promise<void>;
|
|
302
|
+
removeRoleMember(roleName: string, memberId: string): Promise<void>;
|
|
303
|
+
/** Finds the role with this name, or creates it with the given mentionable, color, hoist and permissions settings; reports whether it was created. */
|
|
304
|
+
ensureRole(input: {
|
|
305
|
+
name: string;
|
|
306
|
+
mentionable?: boolean;
|
|
307
|
+
color?: string;
|
|
308
|
+
hoist?: boolean;
|
|
309
|
+
permissions?: string[];
|
|
310
|
+
}): Promise<EnsuredResource>;
|
|
53
311
|
private resolve;
|
|
54
312
|
}
|
|
55
|
-
//#endregion
|
|
56
|
-
//#region src/verify-token.d.ts
|
|
57
|
-
interface VerifyTokenSuccess {
|
|
58
|
-
ok: true;
|
|
59
|
-
subject: string;
|
|
60
|
-
}
|
|
61
|
-
interface VerifyTokenFailure {
|
|
62
|
-
ok: false;
|
|
63
|
-
message: string;
|
|
64
|
-
}
|
|
65
|
-
type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
|
|
66
313
|
interface VerifyTokenOptions {
|
|
67
314
|
baseUrl?: string;
|
|
68
315
|
fetch?: typeof fetch;
|
|
69
316
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOptions {
|
|
317
|
+
/** Checks a Discord webhook URL by fetching the webhook; resolves to its name and id, or the failure message. */
|
|
318
|
+
export declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
319
|
+
/** Options for the Discord plugin: how the webhook URL is resolved plus the notifications settings. */
|
|
320
|
+
export interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOptions {
|
|
74
321
|
/** Override base URL for tests. Default: https://discord.com/api/v10 */
|
|
75
322
|
baseUrl?: string;
|
|
323
|
+
/** The `fetch` to use instead of the global one, for tests. */
|
|
76
324
|
fetch?: typeof fetch;
|
|
325
|
+
/**
|
|
326
|
+
* Also send the BOT token to `baseUrl`. Off by default: `baseUrl` comes from a
|
|
327
|
+
* repo's config, and a changed config must not be able to redirect the bot
|
|
328
|
+
* token to another host. Tests that stub the API set it.
|
|
329
|
+
*/
|
|
330
|
+
unsafeBotBaseUrl?: boolean;
|
|
77
331
|
}
|
|
78
|
-
|
|
332
|
+
/** The shared state the Discord plugin's capability and probes are built from. */
|
|
333
|
+
export interface PluginContext {
|
|
334
|
+
/** The options the plugin was created with. */
|
|
79
335
|
options: DiscordPluginOptions;
|
|
336
|
+
/** The webhook client used to send messages. */
|
|
80
337
|
client: DiscordClient;
|
|
81
338
|
/**
|
|
82
339
|
* Memoized — the resolved "token" IS Discord's default webhook URL, and it is
|
|
83
340
|
* resolved on first `send()`, not at plugin load. `describe()` never calls it.
|
|
84
341
|
*/
|
|
85
342
|
defaultWebhookUrl: () => string;
|
|
343
|
+
/** Memoized — resolves the bot token on the first provisioning call, or when `holocron doctor` checks a provider that has a `guildId`; `send()` and `describe()` never touch it. */
|
|
344
|
+
bot: () => DiscordBotClient;
|
|
345
|
+
/** Builds the OAuth client for one redirect URI; resolves the application id and the client secret on first use. */
|
|
346
|
+
oauth: (redirectUri: string) => Promise<DiscordOAuthClient>;
|
|
86
347
|
}
|
|
87
|
-
|
|
88
|
-
declare function
|
|
89
|
-
|
|
348
|
+
/** Builds the plugin context from its options; the webhook URL, bot token and client secret are each resolved on first use. */
|
|
349
|
+
export declare function createContext(options?: DiscordPluginOptions): PluginContext;
|
|
350
|
+
/** Builds the `notifications` capability for a context. */
|
|
351
|
+
export declare function notifications(ctx: PluginContext): Notifications;
|
|
352
|
+
/**
|
|
353
|
+
* Creates the Discord plugin: its `notifications` capability and its `connection` probe. The probe checks the webhook
|
|
354
|
+
* when there is one, and the bot token when there is not: the webhook is only a last resort for a post that names no
|
|
355
|
+
* channel, so a missing one is not a failed connection when the bot can be reached.
|
|
356
|
+
*/
|
|
357
|
+
export declare function createPlugin(options?: DiscordPluginOptions): {
|
|
90
358
|
name: string;
|
|
359
|
+
probes: {
|
|
360
|
+
connection: import("@theholocron/cli").Probe;
|
|
361
|
+
};
|
|
91
362
|
capabilities: {
|
|
92
363
|
notifications: () => Notifications;
|
|
93
364
|
};
|
|
94
365
|
};
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
export {
|
|
366
|
+
/** One-line hint printed by `holocron auth set discord` when no webhook URL is supplied or the supplied one is rejected. */
|
|
367
|
+
export declare const AUTH_HINT: string;
|
|
368
|
+
export { AuthError, type DiscordClient, type DiscordClientOptions, type DiscordNotificationsOptions, type DiscordWebhookInfo, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createDiscordClient, parseWebhookUrl };
|