@theholocron/holocron-plugin-discord 5.0.0-alpha.277 → 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 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.277",
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.279",
44
45
  "@theholocron/discord-client": "^1.58.0-alpha.3",
46
+ "@theholocron/eslint-config": "^8.9.0-alpha.4",
47
+ "@theholocron/misc-utils": "^1.16.1-alpha.3",
48
+ "@theholocron/tsconfig": "^8.9.0-alpha.4",
45
49
  "@theholocron/http-client": "^1.58.0-alpha.3",
46
- "@theholocron/cli": "5.0.0-alpha.277",
47
- "@theholocron/eslint-config": "^8.9.0-alpha.3",
48
- "@theholocron/misc-utils": "^1.16.1-alpha.2",
49
- "@theholocron/tsconfig": "^8.9.0-alpha.3",
50
- "@theholocron/tsdown-config": "^8.9.0-alpha.3",
51
- "@theholocron/vitest-config": "^8.9.0-alpha.3"
50
+ "@theholocron/vitest-config": "^8.9.0-alpha.4",
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.277"
56
+ "@theholocron/cli": "5.0.0-alpha.279"
57
57
  },
58
58
  "engines": {
59
59
  "node": ">=22"