@theholocron/holocron-plugin-discord 5.0.0-alpha.20 → 5.0.0-alpha.201

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 CHANGED
@@ -61,3 +61,29 @@ server membership is required — generate one in Discord under
61
61
  The webhook id and token are embedded in the URL path — no `Authorization`
62
62
  header is sent. `parseWebhookUrl` is exported as a utility for callers
63
63
  that need to split the URL into its parts.
64
+
65
+ ## Provisioning
66
+
67
+ `holocron notifications setup` and `holocron notifications channel add` create
68
+ channels, roles and webhooks through the `notifications` capability's `ensure*`
69
+ methods. They use the **Holonet bot**, not a webhook URL:
70
+
71
+ - `HOLOCRON_DISCORD_BOT_TOKEN` (or `DISCORD_BOT_TOKEN`), or the keyring entry
72
+ `discord.holonet` (`holocron auth set discord.holonet <token>`) — the bot token
73
+ from the Developer Portal. Only read when a provisioning command runs, or when
74
+ `holocron doctor` checks a provider that has a `guildId`; posting never needs it.
75
+ - `HOLOCRON_DISCORD_CLIENT_SECRET` (or `DISCORD_CLIENT_SECRET`), or the keyring entry
76
+ `discord.holonet.oauth` — the application's OAuth client secret (Developer Portal →
77
+ OAuth2 → Reset Secret). Only `holocron notifications link` reads it, to learn which
78
+ GitHub account a member owns; the API can neither create nor read it.
79
+ - `guildId` — the server id (not a secret), set in the provider options.
80
+ - `layout` — categories, channels (each optionally with a `webhook`) and roles.
81
+
82
+ The bot needs Manage Channels, Manage Roles, Manage Webhooks and View Channels.
83
+ Everything is idempotent (looked up by name). Discord returns a webhook's URL
84
+ only to the application that created it, so a webhook the bot did not create
85
+ cannot have its URL read back.
86
+
87
+ `baseUrl` only redirects posting. The bot token is always sent to the real
88
+ Discord API unless `unsafeBotBaseUrl: true` is also set (meant for tests that
89
+ stub the API), so a changed config cannot redirect the token to another host.
package/dist/index.d.mts CHANGED
@@ -1,30 +1,9 @@
1
- import { AuthError, Notifications, ResolveTokenInput } from "@theholocron/cli";
1
+ import { AuthError, EnsureWebhookResult, EnsuredResource, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsWelcomeLayout, 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";
2
3
  //#region src/auth.d.ts
3
4
  declare const resolveToken: (input?: ResolveTokenInput) => string;
4
- //#endregion
5
- //#region src/rest.d.ts
6
- interface DiscordClientOptions {
7
- /** Override base URL for tests. Default: https://discord.com/api/v10 */
8
- baseUrl?: string;
9
- fetch?: typeof fetch;
10
- }
11
- interface DiscordWebhookInfo {
12
- id: string;
13
- name: string;
14
- guild_id?: string;
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
- };
5
+ declare const resolveBotToken: (input?: ResolveTokenInput) => string;
6
+ declare const resolveClientSecret: (input?: ResolveTokenInput) => string;
28
7
  //#endregion
29
8
  //#region src/capabilities/notifications.d.ts
30
9
  interface DiscordNotificationsOptions {
@@ -38,42 +17,204 @@ interface DiscordNotificationsOptions {
38
17
  * without an explicit channel, or with an empty string.
39
18
  */
40
19
  defaultChannel?: string;
20
+ /** Discord server (guild) id that `notifications setup` provisions. Not a secret. */
21
+ guildId?: string;
22
+ /** The server layout `notifications setup` applies. */
23
+ layout?: NotificationsLayout;
24
+ /** A custom API host, for tests. Webhook tokens are only sent to it when `unsafeBotBaseUrl` is also set. */
25
+ baseUrl?: string;
26
+ unsafeBotBaseUrl?: boolean;
41
27
  }
42
28
  declare class DiscordNotifications implements Notifications {
43
29
  private readonly client;
44
30
  private readonly opts;
45
31
  /** Memoized thunk — resolves the default webhook URL on the first `send()`. */
46
32
  private readonly defaultWebhookUrl;
33
+ /** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
34
+ private readonly bot;
35
+ /** Builds the OAuth client for one redirect URI; needs the application's client secret. */
36
+ private readonly oauth;
47
37
  readonly key: "notifications";
48
38
  readonly providerName = "discord";
49
39
  constructor(client: DiscordClient, opts: DiscordNotificationsOptions,
50
40
  /** Memoized thunk — resolves the default webhook URL on the first `send()`. */
51
- defaultWebhookUrl: () => string);
41
+ defaultWebhookUrl: () => string,
42
+ /** Memoized thunk — resolves the bot token on first provisioning call, never on `send()`. */
43
+ bot?: () => DiscordBotClient,
44
+ /** Builds the OAuth client for one redirect URI; needs the application's client secret. */
45
+ oauth?: (redirectUri: string) => Promise<DiscordOAuthClient>);
46
+ /**
47
+ * Sign a member in with Discord to learn which GitHub account they own. Asks only for `identify` and
48
+ * `connections`, reads the account Discord has verified, and revokes the token before returning: nothing
49
+ * about the sign-in is kept.
50
+ */
51
+ signIn(): NotificationsSignIn;
52
+ get layout(): NotificationsLayout | undefined;
52
53
  send(channel: string, message: string): Promise<void>;
54
+ /**
55
+ * `holocron doctor`: the bot token is valid and can see the configured server.
56
+ * Null when no `guildId` is set -- a post-only config has no bot to check. A
57
+ * `layout` without a `guildId` is a half-written provisioning config, so that
58
+ * fails instead of passing as post-only.
59
+ */
60
+ whoami(): Promise<{
61
+ target: string;
62
+ } | null>;
63
+ /**
64
+ * Read-only: what is on the server, for the parts of `layout` we will compare. Webhooks are
65
+ * listed only for channels the layout gives one (one request each), so the cost scales with
66
+ * the layout, not with the server.
67
+ */
68
+ inspect(layout: NotificationsLayout): Promise<ServerInspection>;
69
+ /** Where to re-invite the bot so its role holds what `setup` needs. Re-authorising updates the role in place. */
70
+ private inviteUrl;
71
+ /** Changing server settings needs Manage Server; an empty edit proves the bot has it without changing anything. */
72
+ preflight(layout: NotificationsLayout): Promise<void>;
73
+ /** The one role with this name, or an error saying why not: two would mean granting something to the wrong members. */
74
+ private static pickRole;
75
+ /** The one text or announcement channel with this name, or an error saying why not. */
76
+ private static pickChannelId;
77
+ /** True for a 403 that is about permissions, not about the bot being unable to see the server at all. */
78
+ private static missingPermissions;
79
+ /** An invite link, or nothing when building it needs a request that fails: the advice must not depend on one. */
80
+ private inviteOrNothing;
81
+ /** Turning community on or off needs Administrator, which is more than the bot should keep. */
82
+ private communityHint;
83
+ /** A 403 on a server edit becomes the explanation and the invite link; anything else is passed on as it is. */
84
+ private manageServerHint;
85
+ ensureServer(settings: NotificationsServerLayout): Promise<{
86
+ updated: string[];
87
+ }>;
88
+ /** A 403 on the welcome screen or onboarding becomes the likely reason; anything else is passed on. */
89
+ private static communityFeatureHint;
90
+ /** The numeric code Discord puts in the JSON body of an error, or undefined when the body is not that. */
91
+ private static codeOf;
92
+ /** The welcome screen; a server that never had one answers 404 (10069), which is an empty screen. */
93
+ private welcomeScreenOf;
94
+ ensureWelcome(welcome: NotificationsWelcomeLayout): Promise<{
95
+ updated: string[];
96
+ }>;
97
+ /** An onboarding prompt reduced to what the layout can state, so the server's and the layout's can be compared. */
98
+ private static onboardingKey;
99
+ ensureOnboarding(onboarding: NotificationsOnboardingLayout): Promise<{
100
+ updated: string[];
101
+ }>;
102
+ ensureEveryone(everyone: NotificationsEveryoneLayout): Promise<{
103
+ updated: string[];
104
+ }>;
105
+ ensureApplication(app: NotificationsApplicationLayout): Promise<{
106
+ updated: string[];
107
+ todo?: string[];
108
+ }>;
109
+ /** Whether the Server Members Intent is on: the unverified app's toggle, or the verified app's own bit. */
110
+ private static membersIntentOn;
111
+ validateLayout(layout: NotificationsLayout): string | undefined;
112
+ private botUser?;
113
+ private botId;
114
+ /**
115
+ * The overwrites that make a channel look like `access`. The list is exact: it replaces
116
+ * whatever was set by hand. `[]` (public) when nothing is restricted.
117
+ */
118
+ private overwritesFor;
119
+ /**
120
+ * Read an access back out of a channel's overwrites, naming roles as the layout does. Only
121
+ * overwrites of the shape {@link overwritesFor} writes can be read back; anything else
122
+ * (a role-specific deny, a member overwrite, only some of the posting bits) means the
123
+ * channel's real access is not something the layout can state, and is reported as `"custom"`
124
+ * rather than guessed at.
125
+ */
126
+ private accessOf;
127
+ /** The server's roles, fetched once and forgotten whenever setup changes a role. */
128
+ private roleLoad?;
129
+ private roleList;
130
+ private guild;
131
+ /**
132
+ * The server's channel list, fetched once per instance. Every ensure* call used
133
+ * to refetch it -- about 40 identical GETs in one setup run -- and Discord
134
+ * rate-limited the route. Our own creates and edits update the copy, so it
135
+ * stays accurate for the run; a new run builds a new instance.
136
+ *
137
+ * It is the in-flight promise that is shared, not the array: callers that start
138
+ * while the first fetch is pending all get the same snapshot, so a later
139
+ * response can never overwrite what an earlier caller added.
140
+ */
141
+ private channelLoad?;
142
+ private channelList;
143
+ /**
144
+ * Create a channel and add it to the shared list. If the create fails, Discord
145
+ * may still have applied it (a timeout looks the same as a refusal), so forget the
146
+ * list: the next ensure refetches the server's real state instead of creating a
147
+ * duplicate.
148
+ */
149
+ private createChannel;
150
+ private static same;
151
+ ensureCategory(name: string, opts?: {
152
+ access?: NotificationsAccess;
153
+ }): Promise<EnsuredResource>;
154
+ /**
155
+ * Edit a channel and keep the shared list in step; forget the list if the edit may have half-applied.
156
+ * Discord answers with the channel as it now is: if the overwrites that come back are not the ones we
157
+ * sent, something else changed it at the same time, so say so instead of reporting success.
158
+ */
159
+ private modifyChannel;
160
+ /**
161
+ * Find a channel by name. A name can exist in several categories, so with a
162
+ * parent: prefer the one already there, then an uncategorised one (moved in);
163
+ * never grab a channel that lives under a different category. Announcement
164
+ * channels count: reusing one beats creating a same-named text channel.
165
+ */
166
+ private static findChannel;
167
+ ensureChannel(input: {
168
+ name: string;
169
+ category?: string;
170
+ topic?: string;
171
+ access?: NotificationsAccess;
172
+ }): Promise<EnsuredResource>;
173
+ ensureWebhook(input: {
174
+ channel: string;
175
+ name: string;
176
+ category?: string;
177
+ avatar?: string;
178
+ }): Promise<EnsureWebhookResult>;
179
+ checkDelivery(input: {
180
+ channel: string;
181
+ name: string;
182
+ category?: string;
183
+ text: string;
184
+ }): Promise<NotificationsDelivery>;
185
+ /** The one role with this name, or an error that says what to fix: none, or more than one. */
186
+ private roleNamed;
187
+ roleMembers(roleName: string): Promise<NotificationsMember[]>;
188
+ addRoleMember(roleName: string, memberId: string): Promise<void>;
189
+ removeRoleMember(roleName: string, memberId: string): Promise<void>;
190
+ ensureRole(input: {
191
+ name: string;
192
+ mentionable?: boolean;
193
+ color?: string;
194
+ hoist?: boolean;
195
+ permissions?: string[];
196
+ }): Promise<EnsuredResource>;
53
197
  private resolve;
54
198
  }
55
199
  //#endregion
56
200
  //#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
201
  interface VerifyTokenOptions {
67
202
  baseUrl?: string;
68
203
  fetch?: typeof fetch;
69
204
  }
70
- declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
205
+ declare function verifyToken(webhookUrl: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
71
206
  //#endregion
72
207
  //#region src/index.d.ts
73
208
  interface DiscordPluginOptions extends ResolveTokenInput, DiscordNotificationsOptions {
74
209
  /** Override base URL for tests. Default: https://discord.com/api/v10 */
75
210
  baseUrl?: string;
76
211
  fetch?: typeof fetch;
212
+ /**
213
+ * Also send the BOT token to `baseUrl`. Off by default: `baseUrl` comes from a
214
+ * repo's config, and a changed config must not be able to redirect the bot
215
+ * token to another host. Tests that stub the API set it.
216
+ */
217
+ unsafeBotBaseUrl?: boolean;
77
218
  }
78
219
  interface PluginContext {
79
220
  options: DiscordPluginOptions;
@@ -83,6 +224,10 @@ interface PluginContext {
83
224
  * resolved on first `send()`, not at plugin load. `describe()` never calls it.
84
225
  */
85
226
  defaultWebhookUrl: () => string;
227
+ /** 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. */
228
+ bot: () => DiscordBotClient;
229
+ /** Builds the OAuth client for one redirect URI; resolves the application id and the client secret on first use. */
230
+ oauth: (redirectUri: string) => Promise<DiscordOAuthClient>;
86
231
  }
87
232
  declare function createContext(options?: DiscordPluginOptions): PluginContext;
88
233
  declare function notifications(ctx: PluginContext): Notifications;
@@ -94,4 +239,4 @@ declare function createPlugin(options?: DiscordPluginOptions): {
94
239
  };
95
240
  declare const AUTH_HINT: string;
96
241
  //#endregion
97
- export { AUTH_HINT, AuthError, type DiscordClient, type DiscordClientOptions, DiscordNotifications, type DiscordNotificationsOptions, DiscordPluginOptions, type DiscordWebhookInfo, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveToken, verifyToken };
242
+ export { AUTH_HINT, AuthError, type DiscordClient, type DiscordClientOptions, DiscordNotifications, type DiscordNotificationsOptions, DiscordPluginOptions, type DiscordWebhookInfo, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createDiscordClient, createPlugin, notifications, parseWebhookUrl, resolveBotToken, resolveClientSecret, resolveToken, verifyToken };