@theholocron/discord-client 1.43.1 → 1.44.0

package/README.md

@@ -52,8 +52,9 @@ into `{ id, token }`.
 ## Bot client — provisioning a server
 
 `createDiscordBotClient` authenticates as a bot (`Authorization: Bot <token>`)
-and covers what you need to set a server up. It does not post messages; use
-`createDiscordClient().webhooks.execute` for that.
+and covers what you need to set a server up. `channels.createMessage` posts as the
+bot (needs View Channel and Send Messages in that channel); to post through a
+channel webhook with no token, use `createDiscordClient().webhooks.execute`.
 
 ```ts
 import { ChannelType, createDiscordBotClient } from "@theholocron/discord-client";
@@ -98,13 +99,21 @@ the resource, look it up by name before creating it again. A webhook created
 that way cannot have its URL read back, since Discord returns the token only on
 the create response.
 
-| Resource          | Methods                                                   |
-| ----------------- | --------------------------------------------------------- |
-| `client.users`    | `me()` — `GET /users/@me`, a cheap token check            |
-| `client.guilds`   | `get`, `channels`, `createChannel`, `roles`, `createRole` |
-| `client.channels` | `modify`, `webhooks`, `createWebhook`                     |
-
-The bot needs Manage Channels, Manage Roles and Manage Webhooks in the server.
+| Resource          | Methods                                                                                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.users`    | `me()` — `GET /users/@me`, a cheap token check                                                                                                              |
+| `client.guilds`   | `get`, `modify`, `channels`, `createChannel`, `roles`, `createRole`, `modifyRole`, `welcomeScreen`, `modifyWelcomeScreen`, `onboarding`, `modifyOnboarding` |
+| `client.channels` | `modify`, `webhooks`, `createWebhook`, `createMessage`                                                                                                      |
+| `client.webhooks` | `modify` (name, avatar), `delete`                                                                                                                           |
+
+`permissions([...names])` builds the decimal-string bitfield Discord expects, and
+`permissionNames(bitfield)` reads one back; `Permission` holds the bits themselves.
+Welcome screen and onboarding only work once the server has the community
+features on, and `modifyOnboarding` is a `PUT` that replaces the whole config.
+`channels.createMessage` turns every mention off unless `allowed_mentions` says
+otherwise.
+
+The bot needs Manage Channels, Manage Roles, Manage Webhooks and (for server settings, welcome screen and onboarding) Manage Server in the server, plus View Channel and Send Messages in any channel it posts to with `channels.createMessage`.
 Discord only returns a webhook's `token`/`url` for webhooks the same
 application created, so a pre-existing webhook can be found by name but its URL
 cannot be read back.

package/dist/index.d.mts

@@ -45,9 +45,91 @@ interface DiscordUser {
   username: string;
   bot?: boolean;
 }
+/** Guild fields `guilds.modify` can change; the numeric enums are Discord's own. */
 interface DiscordGuild {
   id: string;
   name: string;
+  /** 0 none, 1 low, 2 medium, 3 high, 4 very high. */
+  verification_level?: number;
+  /** 0 all messages, 1 only @mentions. */
+  default_message_notifications?: number;
+  /** 0 disabled, 1 members without roles, 2 all members. */
+  explicit_content_filter?: number;
+  system_channel_id?: string | null;
+  /** Bitfield of system-channel messages to suppress. */
+  system_channel_flags?: number;
+  rules_channel_id?: string | null;
+  public_updates_channel_id?: string | null;
+  preferred_locale?: string;
+  description?: string | null;
+  /** `COMMUNITY` here means the community features (welcome screen, onboarding) are available. */
+  features?: string[];
+}
+interface ModifyGuildInput {
+  name?: string;
+  verification_level?: number;
+  default_message_notifications?: number;
+  explicit_content_filter?: number;
+  system_channel_id?: string | null;
+  system_channel_flags?: number;
+  rules_channel_id?: string | null;
+  public_updates_channel_id?: string | null;
+  preferred_locale?: string;
+  description?: string | null;
+  /** The full list of mutable guild features (for example `COMMUNITY`); Discord ignores the ones it manages itself. */
+  features?: string[];
+}
+interface DiscordWelcomeChannel {
+  channel_id: string;
+  description: string;
+  emoji_id?: string | null;
+  emoji_name?: string | null;
+}
+/** Whether the screen is on is the `WELCOME_SCREEN_ENABLED` entry in the guild's `features`; the object has no flag. */
+interface DiscordWelcomeScreen {
+  description: string | null;
+  welcome_channels: DiscordWelcomeChannel[];
+}
+interface ModifyWelcomeScreenInput {
+  enabled?: boolean;
+  description?: string | null;
+  welcome_channels?: DiscordWelcomeChannel[];
+}
+interface DiscordEmoji {
+  id: string | null;
+  name: string | null;
+  animated?: boolean;
+}
+interface DiscordOnboardingOption {
+  id?: string;
+  title: string;
+  description?: string | null;
+  channel_ids?: string[];
+  role_ids?: string[];
+  /** Discord returns the emoji as an object... */
+  emoji?: DiscordEmoji;
+  /** ...and takes it as these three fields (a custom emoji has `emoji_id`, a Unicode one only `emoji_name`). */
+  emoji_id?: string | null;
+  emoji_name?: string | null;
+  emoji_animated?: boolean;
+}
+interface DiscordOnboardingPrompt {
+  id?: string;
+  /** 0 multiple choice, 1 dropdown. */
+  type: number;
+  title: string;
+  single_select: boolean;
+  required: boolean;
+  in_onboarding: boolean;
+  options: DiscordOnboardingOption[];
+}
+interface DiscordOnboarding {
+  guild_id?: string;
+  prompts: DiscordOnboardingPrompt[];
+  default_channel_ids: string[];
+  enabled: boolean;
+  /** 0 default, 1 advanced. */
+  mode?: number;
 }
 interface DiscordPermissionOverwrite {
   /** Role or user id. */
@@ -87,9 +169,20 @@ interface DiscordRole {
   name: string;
   color: number;
   mentionable: boolean;
+  hoist?: boolean;
+  /** Bitfield of permissions, as a string. */
+  permissions?: string;
   managed?: boolean;
   position?: number;
 }
+interface ModifyRoleInput {
+  name?: string;
+  color?: number;
+  hoist?: boolean;
+  mentionable?: boolean;
+  /** Bitfield of permissions, as a string. */
+  permissions?: string;
+}
 interface CreateRoleInput {
   name: string;
   color?: number;
@@ -101,12 +194,36 @@ interface CreateRoleInput {
 interface DiscordChannelWebhook {
   id: string;
   name: string | null;
+  /** The avatar hash, or `null` for the default one. */
+  avatar?: string | null;
   channel_id: string;
   /** Present only on webhooks this application created; Discord omits it otherwise. */
   token?: string;
   /** Present only on webhooks this application created. */
   url?: string;
 }
+interface CreateMessageInput {
+  content: string;
+  /** With `enforce_nonce`, Discord drops a repeat of the same nonce, so a retry after a lost response cannot post twice. */
+  nonce?: string | number;
+  enforce_nonce?: boolean;
+  /** Defaults to no mentions, so a pasted `@everyone` cannot ping anyone. */
+  allowed_mentions?: {
+    parse?: Array<"roles" | "users" | "everyone">;
+    roles?: string[];
+    users?: string[];
+  };
+}
+interface DiscordMessage {
+  id: string;
+  channel_id: string;
+  content: string;
+}
+interface ModifyWebhookInput {
+  name?: string;
+  /** A data URI (`data:image/png;base64,...`); `null` clears it. */
+  avatar?: string | null;
+}
 //#endregion
 //#region ../../../../../src/bot/bot.d.ts
 /**
@@ -127,21 +244,106 @@ declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
   };
   guilds: {
     get: (guildId: string) => Promise<DiscordGuild>;
+    /** `PATCH /guilds/:id` — verification, notification defaults, content filter, system channels. */
+    modify: (guildId: string, body: ModifyGuildInput) => Promise<DiscordGuild>;
+    welcomeScreen: (guildId: string) => Promise<DiscordWelcomeScreen>;
+    /** Needs the community features on. */
+    modifyWelcomeScreen: (guildId: string, body: ModifyWelcomeScreenInput) => Promise<DiscordWelcomeScreen>;
+    onboarding: (guildId: string) => Promise<DiscordOnboarding>;
+    /**
+     * `PUT` replaces the whole onboarding config, so send every prompt you want to keep. Discord has no
+     * conditional write: two callers that read, edit and PUT at once, the later one wins.
+     */
+    modifyOnboarding: (guildId: string, body: Omit<DiscordOnboarding, "guild_id">) => Promise<DiscordOnboarding>;
     channels: (guildId: string) => Promise<DiscordChannel[]>;
     createChannel: (guildId: string, body: CreateChannelInput) => Promise<DiscordChannel>;
     roles: (guildId: string) => Promise<DiscordRole[]>;
     createRole: (guildId: string, body: CreateRoleInput) => Promise<DiscordRole>;
+    modifyRole: (guildId: string, roleId: string, body: ModifyRoleInput) => Promise<DiscordRole>;
   };
   channels: {
     modify: (channelId: string, body: ModifyChannelInput) => Promise<DiscordChannel>;
     webhooks: (channelId: string) => Promise<DiscordChannelWebhook[]>;
+    /** `POST /channels/:id/messages` as the bot. Mentions are off unless `allowed_mentions` asks for them. */
+    createMessage: (channelId: string, body: CreateMessageInput) => Promise<DiscordMessage>;
     createWebhook: (channelId: string, body: {
       name: string;
     }) => Promise<DiscordChannelWebhook>;
   };
+  webhooks: {
+    /** `PATCH /webhooks/:id` — name and avatar of a webhook this bot manages. */
+    modify: (webhookId: string, body: ModifyWebhookInput) => Promise<DiscordChannelWebhook>;
+    /** `DELETE /webhooks/:id` — e.g. to roll back an orphan whose URL was never stored. */
+    /** A 404 counts as done: the webhook is already gone, as when a retry follows a lost response. */
+    delete: (webhookId: string) => Promise<void>;
+  };
 };
 type DiscordBotClient = ReturnType<typeof createDiscordBotClient>;
 //#endregion
+//#region ../../../../../src/bot/permissions.d.ts
+/**
+ * Discord permission bits, by the names the Discord docs use. Permissions travel as
+ * decimal strings because they overflow a JS number's safe integer range. Bits Discord
+ * adds after this list are not named here: `permissionNames` leaves them out, and
+ * `permissions` cannot set them by name.
+ */
+declare const Permission: {
+  readonly CreateInstantInvite: bigint;
+  readonly KickMembers: bigint;
+  readonly BanMembers: bigint;
+  readonly Administrator: bigint;
+  readonly ManageChannels: bigint;
+  readonly ManageGuild: bigint;
+  readonly AddReactions: bigint;
+  readonly ViewAuditLog: bigint;
+  readonly PrioritySpeaker: bigint;
+  readonly Stream: bigint;
+  readonly ViewChannel: bigint;
+  readonly SendMessages: bigint;
+  readonly SendTtsMessages: bigint;
+  readonly ManageMessages: bigint;
+  readonly EmbedLinks: bigint;
+  readonly AttachFiles: bigint;
+  readonly ReadMessageHistory: bigint;
+  readonly MentionEveryone: bigint;
+  readonly UseExternalEmojis: bigint;
+  readonly ViewGuildInsights: bigint;
+  readonly Connect: bigint;
+  readonly Speak: bigint;
+  readonly MuteMembers: bigint;
+  readonly DeafenMembers: bigint;
+  readonly MoveMembers: bigint;
+  readonly UseVoiceActivity: bigint;
+  readonly ChangeNickname: bigint;
+  readonly ManageNicknames: bigint;
+  readonly ManageRoles: bigint;
+  readonly ManageWebhooks: bigint;
+  readonly ManageGuildExpressions: bigint;
+  readonly UseApplicationCommands: bigint;
+  readonly RequestToSpeak: bigint;
+  readonly ManageEvents: bigint;
+  readonly ManageThreads: bigint;
+  readonly CreatePublicThreads: bigint;
+  readonly CreatePrivateThreads: bigint;
+  readonly UseExternalStickers: bigint;
+  readonly SendMessagesInThreads: bigint;
+  readonly UseEmbeddedActivities: bigint;
+  readonly ModerateMembers: bigint;
+  readonly ViewCreatorMonetizationAnalytics: bigint;
+  readonly UseSoundboard: bigint;
+  readonly CreateGuildExpressions: bigint;
+  readonly CreateEvents: bigint;
+  readonly UseExternalSounds: bigint;
+  readonly SendVoiceMessages: bigint;
+  readonly SendPolls: bigint;
+  readonly UseExternalApps: bigint;
+};
+type PermissionName = keyof typeof Permission;
+/** The decimal-string bitfield Discord wants for the named permissions (`"0"` for none). */
+declare function permissions(names: readonly PermissionName[]): string;
+/** The permission names set in a bitfield, in declaration order (unknown bits are ignored). */
+declare function permissionNames(bitfield: string): PermissionName[];
+//#endregion
 //#region ../../../../../src/index.d.ts
 declare function createDiscordClient(opts?: DiscordClientOptions): {
   webhooks: {
@@ -151,4 +353,4 @@ declare function createDiscordClient(opts?: DiscordClientOptions): {
 };
 type DiscordClient = ReturnType<typeof createDiscordClient>;
 //#endregion
-export { ChannelType, CreateChannelInput, CreateRoleInput, DiscordBotClient, DiscordBotClientOptions, DiscordChannel, DiscordChannelWebhook, DiscordClient, type DiscordClientOptions, DiscordGuild, DiscordPermissionOverwrite, DiscordRole, DiscordUser, type DiscordWebhookInfo, ModifyChannelInput, createDiscordBotClient, createDiscordClient, parseWebhookUrl };
+export { ChannelType, CreateChannelInput, CreateMessageInput, CreateRoleInput, DiscordBotClient, DiscordBotClientOptions, DiscordChannel, DiscordChannelWebhook, DiscordClient, type DiscordClientOptions, DiscordEmoji, DiscordGuild, DiscordMessage, DiscordOnboarding, DiscordOnboardingOption, DiscordOnboardingPrompt, DiscordPermissionOverwrite, DiscordRole, DiscordUser, type DiscordWebhookInfo, DiscordWelcomeChannel, DiscordWelcomeScreen, ModifyChannelInput, ModifyGuildInput, ModifyRoleInput, ModifyWebhookInput, ModifyWelcomeScreenInput, Permission, PermissionName, createDiscordBotClient, createDiscordClient, parseWebhookUrl, permissionNames, permissions };

package/dist/index.mjs

@@ -55,6 +55,13 @@ function id(value) {
 	if (!/^\d{1,20}$/.test(value)) throw new Error(`invalid Discord id: ${JSON.stringify(value)}`);
 	return value;
 }
+/** Validates ids that travel in a request body, so a malformed one fails here and not at Discord. */
+function bodyIds(...values) {
+	for (const value of values) {
+		if (value === void 0 || value === null) continue;
+		for (const one of typeof value === "string" ? [value] : value) id(one);
+	}
+}
 /** How long Discord asks us to wait after a 429, in ms (header first, then the JSON body). */
 async function retryDelayMs(res) {
 	const header = Number(res.headers.get("retry-after"));
@@ -119,6 +126,36 @@ function createDiscordBotClient(opts) {
 me: () => rest.request("/users/@me") },
 		guilds: {
 			get: (guildId) => rest.request(`/guilds/${id(guildId)}`),
+			/** `PATCH /guilds/:id` — verification, notification defaults, content filter, system channels. */
+			modify: (guildId, body) => {
+				bodyIds(body.system_channel_id, body.rules_channel_id, body.public_updates_channel_id);
+				return rest.request(`/guilds/${id(guildId)}`, {
+					method: "PATCH",
+					body
+				});
+			},
+			welcomeScreen: (guildId) => rest.request(`/guilds/${id(guildId)}/welcome-screen`),
+			/** Needs the community features on. */
+			modifyWelcomeScreen: (guildId, body) => {
+				for (const c of body.welcome_channels ?? []) bodyIds(c.channel_id, c.emoji_id);
+				return rest.request(`/guilds/${id(guildId)}/welcome-screen`, {
+					method: "PATCH",
+					body
+				});
+			},
+			onboarding: (guildId) => rest.request(`/guilds/${id(guildId)}/onboarding`),
+			/**
+			* `PUT` replaces the whole onboarding config, so send every prompt you want to keep. Discord has no
+			* conditional write: two callers that read, edit and PUT at once, the later one wins.
+			*/
+			modifyOnboarding: (guildId, body) => {
+				bodyIds(body.default_channel_ids);
+				for (const prompt of body.prompts) for (const option of prompt.options) bodyIds(option.channel_ids, option.role_ids, option.emoji_id);
+				return rest.request(`/guilds/${id(guildId)}/onboarding`, {
+					method: "PUT",
+					body
+				});
+			},
 			channels: (guildId) => rest.request(`/guilds/${id(guildId)}/channels`),
 			createChannel: (guildId, body) => rest.request(`/guilds/${id(guildId)}/channels`, {
 				method: "POST",
@@ -128,6 +165,10 @@ me: () => rest.request("/users/@me") },
 			createRole: (guildId, body) => rest.request(`/guilds/${id(guildId)}/roles`, {
 				method: "POST",
 				body
+			}),
+			modifyRole: (guildId, roleId, body) => rest.request(`/guilds/${id(guildId)}/roles/${id(roleId)}`, {
+				method: "PATCH",
+				body
 			})
 		},
 		channels: {
@@ -136,10 +177,41 @@ me: () => rest.request("/users/@me") },
 				body
 			}),
 			webhooks: async (channelId) => (await rest.request(`/channels/${id(channelId)}/webhooks`)).map(withUrl),
+			/** `POST /channels/:id/messages` as the bot. Mentions are off unless `allowed_mentions` asks for them. */
+			createMessage: (channelId, body) => {
+				bodyIds(body.allowed_mentions?.roles, body.allowed_mentions?.users);
+				return rest.request(`/channels/${id(channelId)}/messages`, {
+					method: "POST",
+					body: {
+						...body,
+						allowed_mentions: body.allowed_mentions ?? { parse: [] }
+					}
+				});
+			},
 			createWebhook: async (channelId, body) => withUrl(await rest.request(`/channels/${id(channelId)}/webhooks`, {
 				method: "POST",
 				body
 			}))
+		},
+		webhooks: {
+			/** `PATCH /webhooks/:id` — name and avatar of a webhook this bot manages. */
+			modify: async (webhookId, body) => withUrl(await rest.request(`/webhooks/${id(webhookId)}`, {
+				method: "PATCH",
+				body
+			})),
+			/** `DELETE /webhooks/:id` — e.g. to roll back an orphan whose URL was never stored. */
+			/** A 404 counts as done: the webhook is already gone, as when a retry follows a lost response. */
+			delete: async (webhookId) => {
+				try {
+					await rest.request(`/webhooks/${id(webhookId)}`, {
+						method: "DELETE",
+						expectNoContent: true
+					});
+				} catch (err) {
+					if (err instanceof ProviderApiError && err.status === 404) return;
+					throw err;
+				}
+			}
 		}
 	};
 }
@@ -153,9 +225,84 @@ const ChannelType = {
 	Forum: 15
 };
 //#endregion
+//#region ../../../../../src/bot/permissions.ts
+/**
+* Discord permission bits, by the names the Discord docs use. Permissions travel as
+* decimal strings because they overflow a JS number's safe integer range. Bits Discord
+* adds after this list are not named here: `permissionNames` leaves them out, and
+* `permissions` cannot set them by name.
+*/
+const Permission = {
+	CreateInstantInvite: 1n << 0n,
+	KickMembers: 1n << 1n,
+	BanMembers: 1n << 2n,
+	Administrator: 1n << 3n,
+	ManageChannels: 1n << 4n,
+	ManageGuild: 1n << 5n,
+	AddReactions: 1n << 6n,
+	ViewAuditLog: 1n << 7n,
+	PrioritySpeaker: 1n << 8n,
+	Stream: 1n << 9n,
+	ViewChannel: 1n << 10n,
+	SendMessages: 1n << 11n,
+	SendTtsMessages: 1n << 12n,
+	ManageMessages: 1n << 13n,
+	EmbedLinks: 1n << 14n,
+	AttachFiles: 1n << 15n,
+	ReadMessageHistory: 1n << 16n,
+	MentionEveryone: 1n << 17n,
+	UseExternalEmojis: 1n << 18n,
+	ViewGuildInsights: 1n << 19n,
+	Connect: 1n << 20n,
+	Speak: 1n << 21n,
+	MuteMembers: 1n << 22n,
+	DeafenMembers: 1n << 23n,
+	MoveMembers: 1n << 24n,
+	UseVoiceActivity: 1n << 25n,
+	ChangeNickname: 1n << 26n,
+	ManageNicknames: 1n << 27n,
+	ManageRoles: 1n << 28n,
+	ManageWebhooks: 1n << 29n,
+	ManageGuildExpressions: 1n << 30n,
+	UseApplicationCommands: 1n << 31n,
+	RequestToSpeak: 1n << 32n,
+	ManageEvents: 1n << 33n,
+	ManageThreads: 1n << 34n,
+	CreatePublicThreads: 1n << 35n,
+	CreatePrivateThreads: 1n << 36n,
+	UseExternalStickers: 1n << 37n,
+	SendMessagesInThreads: 1n << 38n,
+	UseEmbeddedActivities: 1n << 39n,
+	ModerateMembers: 1n << 40n,
+	ViewCreatorMonetizationAnalytics: 1n << 41n,
+	UseSoundboard: 1n << 42n,
+	CreateGuildExpressions: 1n << 43n,
+	CreateEvents: 1n << 44n,
+	UseExternalSounds: 1n << 45n,
+	SendVoiceMessages: 1n << 46n,
+	SendPolls: 1n << 49n,
+	UseExternalApps: 1n << 50n
+};
+/** The decimal-string bitfield Discord wants for the named permissions (`"0"` for none). */
+function permissions(names) {
+	let bits = 0n;
+	for (const name of names) {
+		const bit = Permission[name];
+		if (bit === void 0) throw new Error(`unknown Discord permission: ${JSON.stringify(name)}`);
+		bits |= bit;
+	}
+	return bits.toString();
+}
+/** The permission names set in a bitfield, in declaration order (unknown bits are ignored). */
+function permissionNames(bitfield) {
+	if (!/^\d{1,20}$/.test(bitfield)) throw new Error(`invalid permission bitfield: ${JSON.stringify(bitfield)}`);
+	const bits = BigInt(bitfield);
+	return Object.keys(Permission).filter((name) => (bits & Permission[name]) !== 0n);
+}
+//#endregion
 //#region ../../../../../src/index.ts
 function createDiscordClient(opts = {}) {
 	return { webhooks: webhooks(opts.baseUrl ?? "https://discord.com/api/v10", opts.fetch ?? globalThis.fetch) };
 }
 //#endregion
-export { ChannelType, createDiscordBotClient, createDiscordClient, parseWebhookUrl };
+export { ChannelType, Permission, createDiscordBotClient, createDiscordClient, parseWebhookUrl, permissionNames, permissions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/discord-client",
-  "version": "1.43.1",
+  "version": "1.44.0",
   "description": "A TypeScript client for the Discord webhooks API",
   "keywords": [
     "discord",
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.43.1"
+    "@theholocron/http-client": "^1.44.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.79",